2026 年 10 月 3 日，DeepSeek Harness (DSH) 依然秉持“一切皆插件”的设计理念。纯文本模型缺乏处理图像的能力，这是构建视觉智能体时的常见痛点。dsh-vision-bridge 插件旨在为纯文本模型补充视觉能力，它既可以复用 DSH 现有的 Provider，也支持配置任意 OpenAI 兼容的多模态 API。该插件由 alaxrpg 维护。
核心功能¶
插件提供以下核心能力：
vision_bridge_read_image工具：模型可主动调用该工具识别图片，返回结构化文本证据，包含 OCR 文本、布局信息和语义描述。- 粘贴图片自动接管：在支持 TEXTAREA、INPUT 或 contenteditable（DSH 0.1.2-alpha+）的输入框中粘贴图片时，插件会自动上传图片，并插入紧凑的引用标记（例如
「▧ 图片 #KdAy1D」），供模型后续调用视觉工具。 - 无厂商硬编码：Provider 与模型列表实时读取 DSH registry，不进行厂商硬编码。
- 可视化配置：在设置页的“插件 → 视觉桥接”子菜单中，可以选择 DSH Provider，或新增自定义 OpenAI 兼容 Provider，保存后热生效。
- 连通性测试：提供一键测试功能，向视觉 API 发送测试图，返回延迟与响应样本。
- 复用现有通道：选择 DSH Provider 时，复用其 adapter、凭据和 attachment 通道，不注册额外的 wrapper provider。
安装与启用¶
使用官方 CLI 安装插件（会自动写入 bundles）：
dsh plugin --profile web add github:alaxrpg/dsh-vision-bridge
安装完成后，插件会加载到当前 DSH 进程中。
配置¶
推荐使用 GUI 设置页进行配置。安装并重启 DSH 后，进入“设置 → 插件 → 视觉桥接”。
Provider 模式¶
- DSH Provider 模式：从 DSH 当前已添加的 Provider 与模型中选择。图片经 DSH attachment store 保存后交给选中 Provider 的 adapter。插件不读取该 Provider 的 Base URL 或密钥，凭据由其 adapter 管理。
- 自定义 Provider 模式：配置 OpenAI 兼容直连。自定义 Provider 只属于本插件，不会注册到 DSH 全局 Provider。
API Key 配置¶
若使用自定义 Provider，API Key 有以下优先级：
1. vision-bridge.apiKey（配置页输入或 settings.yaml 直填）。
2. vision-bridge.apiKeyEnv：通过 DSH 凭据服务解析，优先级高于环境变量文件。
重要说明：配置接口 GET /vision-bridge/config 永远只返回 keySource 和 keyResolved 的布尔状态，不会回显密钥。
桌面端说明¶
桌面端宿主启动时，会将 settings.yaml 一次性导入内部存储并改名 settings.yaml.imported。桌面端不向本插件注入 settings 服务。
为此，插件做了以下兜底处理：
* 读取时将 settings.yaml.imported 加入候选文件。
* 设置页的“保存”按钮在 settings 服务不可用时，会退化为直写 settings.yaml，写后立即热生效。
手动配置（YAML）¶
也可以直接编辑 ~/.dsh/settings.yaml：
vision-bridge:
enabled: true
providerMode: dsh
provider: your-dsh-provider-id
model: your-vision-model-id
timeout: 90
外部编辑配置文件同样会被监听并热生效。
使用方法¶
配置完成后，插件提供两种使用方式：
1. 模型主动调用工具¶
模型可以主动调用 vision_bridge_read_image 工具。示例命令：
使用 vision_bridge_read_image 工具识别图片：/path/to/image.png
2. 粘贴图片自动处理¶
用户直接粘贴图片时，插件会自动上传图片并插入引用标记。模型在上下文中看到该标记后，会自动调用视觉工具进行处理。
输出格式¶
工具调用后会返回结构化 JSON 证据：
{
"summary": "图片整体描述",
"ocr": {
"full_text": "完整 OCR 文本",
"lines": [{"text": "行文本", "language": "zh"}]
},
"layout": {
"regions": [{"type": "heading", "reading_order": 1, "text": "..."}]
},
"semantics": {
"scene": "场景描述",
"entities": [{"name": "实体名", "type": "类型"}]
},
"uncertainty": ["不确定项"]
}
技术细节与兼容性¶
- 兼容性：DSH 0.1.1+，Node.js 18+，支持 macOS / Linux。
- 依赖项：
@deepseek-ai/dsh-credentials(>=0.1.1-rc.1)，@deepseek-ai/schemastery(>=3.18.1)。 - 路由：
GET /vision-bridge/config：读取配置状态。POST /vision-bridge/config：保存配置。GET /vision-bridge/test：连通性测试。POST /vision-bridge/paste：粘贴上传处理。GET /vision-bridge/verdict：判断是否接管粘贴。
- 客户端：classic script 经
__ModuleLoader__加载，粘贴拦截在无插件上下文时也照常工作。
