前言¶

在 DSH 的插件化扩展方式下，社区目录是独立站点，本文介绍的 @dsh-extension/dsh-vision-bridge 是一个第三方插件。它面向 text-only DSH 会话，解决一个具体问题：会话中会出现上传图片或工具产生的图片，但文本模型请求不适合携带 image blocks；如果为了“看图”直接把长会话历史发给视觉模型，成本和控制都不好把握。

这个插件让会话继续走文本模型，只在需要理解图片时调用 vision_describe。每次视觉调用只发送指定图片和一个聚焦问题，把视觉模型作为按需调用的外部能力。

这是什么¶

@dsh-extension/dsh-vision-bridge 由 sfyyy 维护，许可证为 MIT。它的一行定位是：

On-demand vision for text-only DSH sessions: images become markers, and a vision_describe tool sends only image + question to an OpenAI-compatible vision model.

简单说，它给 text-only DSH 会话提供按需视觉能力：图片在会话和 UI 中仍作为图片存在，进入文本模型输入层时被改写成 text marker；模型需要看图时调用工具，由 OpenAI-compatible 视觉端点返回文本结果。

核心能力¶

按需调用视觉模型¶

插件不把所有图片都主动发给视觉模型。它注册 vision_describe 工具，由文本模型在需要时调用。每次调用只发送图片和 question，不发送长 conversation history，从而把视觉调用控制在“只发当前要看的内容”这一层。

会话保留原图，只改写模型输入¶

插件通过 agent/pre-step hook 记录会话中出现的图片附件，并建立 attachment index，供 vision_describe 按 id 解析图片。

同时，它包装 session.deriveMessages()，让发给文本模型的消息不包含 image blocks。会话日志和 UI 仍然保留原始图片；被改写的只是模型输入。

使用 OpenAI-compatible 视觉端点¶

插件支持任何 OpenAI-compatible /v1/chat/completions endpoint 作为视觉端点。它在 DSH llm-pi-ai providers 中只维护一条 vision-bridge provider route。

禁用后恢复原生行为¶

配置 enabled: false 会关闭整条链路：不注册工具、不做图片改写、不保留 admission bypass，恢复 native behavior。

安装与启用¶

安装命令¶

从 npm registry 安装，不使用 local checkout：

dsh plugin --profile web add @dsh-extension/dsh-vision-bridge

如果一直通过 npx 调用 DSH CLI，也可以用：

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @dsh-extension/dsh-vision-bridge

--profile 指向你要启动的 profile；web 是浏览器 UI profile。如果新增 client bundle，需要重启一次 dsh web，让 UI 加载到插件。

基本配置¶

可以在 DSH Web 的 Settings -> Vision Bridge 中配置，也可以编辑 ~/.dsh/vision-bridge.json：

{
  "enabled": true,
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "sk-xxxx",
  "apiKeyEnv": "",
  "model": "gpt-5.6-terra"
}

配置项包括：

• enabled：是否启用整条链路。
• baseUrl：OpenAI-compatible /v1/chat/completions 视觉端点。
• apiKey：直接填入的 API key。
• apiKeyEnv：用于引用环境变量的字段；与 apiKey 互斥。
• model：视觉模型名称。

直接填入的 key 会同步到 DSH credential store，并被引用为 DSH_VISION_BRIDGE_API_KEY。

配置优先级¶

优先级从高到低：

Settings page (with schema defaults) -> environment variables -> config file

可用的环境覆盖项包括：

DSH_VISION_BRIDGE_BASE_URL
DSH_VISION_BRIDGE_API_KEY
DSH_VISION_BRIDGE_API_KEY_ENV
DSH_VISION_BRIDGE_MODEL
DSH_VISION_BRIDGE_ENABLED

检查运行状态¶

可以请求插件提供的 settings 接口，查看当前 live 的 value.admissionBypass 和 dependency-service status：

GET /_dsh/vision-bridge/settings

典型用法¶

调用 vision_describe¶

vision_describe 用于让视觉模型回答关于图片的问题。它接受：

• attachmentIds：当前会话中的图片 attachment ids。
• paths：图片文件路径，通过 DSH 的 sandbox-aware file service 解析，支持 png、jpeg、webp、gif。
• question：必填，必须是聚焦、具体的问题。

一次调用的图片总数为 1-4。

一个参数层面的调用可以写成模板形式：

vision_describe(
  attachmentIds: ["<current-conversation-attachment-id>"],
  paths: ["<image-path>"],
  question: "<question>"
)

多张图片¶

如果需要一次查看多张图片，可以把 1-4 张图片一起传给 vision_describe，并在 question 中说明要观察或比较的内容。

验证与本地开发¶

运行测试：

npm test

测试覆盖 marker rewriting、attachment resolution、event-log indexing、disabled shutdown 和 text-only session behavior。

如果从 local checkout 开发，可以注入本地路径：

dsh plugin inject /path/to/dsh-vision-bridge

适用场景与注意¶

适合以下情况：

• text-only DSH 会话中偶尔需要理解截图、上传图片或图表。
• 希望视觉模型只接收图片和聚焦问题，不接收长会话历史。
• 已有 OpenAI-compatible /v1/chat/completions 视觉端点。
• 希望 UI 和会话日志继续显示原始图片，只改写发给文本模型的输入。

使用前注意：

• 插件以当前 dsh 进程权限运行，安装前建议检查源码与 MIT 许可证。
• apiKey 与 apiKeyEnv 互斥；不要同时依赖两种方式产生歧义。
• enabled: false 会关闭工具注册、图片改写和 admission bypass。
• attachment ids 必须来自当前会话；paths 走 DSH 的 sandbox-aware file service。

结尾¶

@dsh-extension/dsh-vision-bridge 的价值在于给 text-only DSH 会话补上“按需看图”的能力：图片留在会话和 UI 中，文本模型通过 text marker 感知图片，真正需要时再用最小 payload 调用视觉模型。

GitHub 仓库：

https://github.com/sfyyy/dsh-vision-bridge

社区目录页 URL 未在已核实资料中提供；安装时可用上面的 npm registry 安装命令。