视觉桥接插件 lium970320/dsh-vision-bridge

dsh-vision-bridge · DSH 视觉桥接

DSH 插件：本仓库已打上 dsh-plugin 标签，可在 DeepSeek Harness 官方插件发现页被检索到。

让 DeepSeek Harness（DSH） 里没有视觉能力的主模型（如 deepseek-v4-pro）能够“看图”：

1. 会话直接收图：用户在会话里发送图片不再被“模型不支持图片”拦截；
2. 消息保留图片：用户消息框显示图片缩略图，转换不在用户消息上发生；
3. 内部自动转文字：图片在模型请求组装层被自动交给视觉模型转成文字描述，主模型只收到文字；
4. 自觉看图工具：view_image 工具供模型在需要看图时自行调用（支持本地路径 / URL / data URL）。

项目结构

dsh-vision-bridge/
├── plugin/ # DSH 插件本体（npm bundle patch 入口） │ ├── dsh-view-image.js # view_image 工具：图片 → 视觉模型 → 文字描述 │ ├── apply-vision-patch.js # pi-ai 适配器补丁（幂等，可重复运行） │ └── cordis.patch.yml # bundle patch 声明（name 相对本目录解析） ├── config/ │ └── vision-bridge-config.example.json # 视觉接口配置样例（复制为 vision-bridge-config.json 使用） ├── install.ps1 # 一键安装脚本（复制/登记/声明/配置/补丁/自测） ├── package.json # npm 发布元数据（files 白名单 + bundle patch 入口） ├── README.md / CHANGELOG.md / LICENSE / VERSION.txt / .gitignore

NPM 包安装

已发布到 npm：@liu__min/dsh-vision-bridge（0.1.1，公开，dsh-plugin 标签）

两种安装方式：

- 从 npm 拉取（DSH 生态原生方式，装完需补打适配器补丁与配置）：
dsh plugin --profile web add @liu__min/dsh-vision-bridge
cd %USERPROFILE%\.dsh\profiles\web
node apply-vision-patch.js # 打 pi-ai 适配器补丁
随后写 vision-bridge-config.json（见下方「配置视觉接口」）

- 从 GitHub clone + 一键脚本（最省心，install.ps1 会自动完成复制/登记/声明/打补丁/自测）：
git clone https://github.com/lium970320/dsh-vision-bridge.git
cd dsh-vision-bridge
powershell -ExecutionPolicy Bypass -File install.ps1 -ApiBase -ApiKeyEnv -VisionModel

无论哪种方式，装完都要重启 dsh web 并配置视觉接口（这是两条总是要做的步骤，见下文）。

快速开始（30 秒）

没装过 DeepSeek Harness？先看官方快速开始：

1. 准备一个视觉接口（网址 + 密钥），例如 OpenAI 官方：网址 https://api.openai.com/v1、模型 gpt-5.1、密钥环境变量 OPENAI_API_KEY（先 setx OPENAI_API_KEY ""）；
2. 运行安装脚本，带上接口参数：

powershell -ExecutionPolicy Bypass -File install.ps1 -ApiBase https://api.openai.com/v1 -ApiKeyEnv OPENAI_API_KEY -VisionModel gpt-5.1

没有参数也可以直接运行，脚本会逐步询问网址 / 模型名 / 密钥。
3. 重启 dsh web，在任意会话里发一张图片——消息框显示图片、模型能读出内容，即安装成功。

详细配置说明见下文“配置视觉接口（必做）”。

前置条件

- DeepSeek Harness 已安装且 dsh web 启动过至少一次（~/.dsh/profiles/web/ 存在）；
- 主模型走 dsh-llm-pi-ai 适配器（settings.yaml 里 llm-pi-ai.providers. 已配置），或 你愿意手工在 settings 里声明图片输入；
- 一个视觉接口（网址 + API 密钥）——本插件不内置任何服务商，必须显式配置，例如：
- OpenAI 官方：https://api.openai.com/v1 + OPENAI_API_KEY；
- xAI Grok：https://api.x.ai/v1 + XAI_API_KEY；
- 任何 OpenAI 兼容 Responses API（本地网关、中转等）。

一键安装（推荐）

视觉接口是必做步骤：带参数直接写配置，不带参数会交互询问。

OpenAI 官方（推荐方式：密钥走环境变量） powershell -ExecutionPolicy Bypass -File install.ps1 -ApiBase https://api.openai.com/v1 -ApiKeyEnv OPENAI_API_KEY -VisionModel gpt-5.1

xAI Grokpowershell
powershell -ExecutionPolicy Bypass -File install.ps1 -ApiBase https://api.x.ai/v1 -ApiKeyEnv XAI_API_KEY -VisionModel grok-4-fast

交互式：脚本逐步询问网址 / 模型名 / 密钥 powershell -ExecutionPolicy Bypass -File install.ps1

安装脚本依次完成：复制插件文件 → 在 profile 的 cordis.patch.yml 登记插件行 → 在 settings.yaml 给主模型声明图片输入 → 写视觉接口配置（参数或交互）→ 打 pi-ai 适配器补丁 → 自测。

参数：

| 参数 | 默认 | 说明 |
| -ApiBase | 无（必填） | 视觉接口地址，如 https://api.openai.com/v1 |
| -ApiKeyEnv | 无 | 密钥环境变量名（优先）；与 -ApiKey 二选一 |
| -ApiKey | 无 | 直接写密钥（仅存本机配置文件，不会被提交） |
| -VisionModel | 无（必填） | 视觉模型名，如 gpt-5.1 / grok-4-fast |
| -Provider | opencode-go | settings 里 llm-pi-ai.providers 下的主模型路由名 |
| -Model | deepseek-v4-pro | 主模型 id（给它声明 input: [text, image]） |
| -SkipSettings | 关 | 跳过 settings 的模型声明（自己手工改） |
| -NonInteractive | 关 | 无人值守：跳过交互询问（之后手工写配置文件） |

安装后 重启 dsh web，然后在任意会话里发一张图片验证。

手动安装（想自己控制每一步时）

1. 复制 plugin/dsh-view-image.js、plugin/apply-vision-patch.js 到 ~/.dsh/profiles/web/；
2. 在 ~/.dsh/profiles/web/cordis.patch.yml 追加：

yaml
- insert:
- id: dsh-view-image
name: './dsh-view-image.js'

3. 在 ~/.dsh/settings.yaml 给主模型声明图片输入：

yaml
llm-pi-ai:
providers:
opencode-go:
apiKeyEnv: OPENCODE_GO_API_KEY
modelOverrides:
deepseek-v4-pro:
input:
- text
- image

4. 写视觉接口配置 ~/.dsh/profiles/web/vision-bridge-config.json（样例见 config/vision-bridge-config.example.json）：

json
{
"apiBase": "https://api.openai.com/v1",
"model": "gpt-5.1",
"apiKeyEnv": "OPENAI_API_KEY",
"apiKey": ""
}

apiKeyEnv（环境变量名，优先）与 apiKey（直读 key）二选一；两者都留空时表示匿名端点。未配置时工具会明确报错，不会静默失败。

5. 运行 node apply-vision-patch.js（对 pi-ai 适配器打补丁）；
6. 运行 node dsh-view-image.js 自测；
7. 重启 dsh web。

视觉接口配置优先级

cordis.patch.yml 的插件 config ＞ vision-bridge-config.json ＞ 环境变量（密钥）。没有内置默认服务商。

维护 / 升级

- 每次 dsh 升级或重装后，适配器补丁会丢失：进入 ~/.dsh/profiles/web/ 重新运行 node apply-vision-patch.js 即可（脚本幂等，多版本自动识别）；
- 插件每次启动都会检查补丁是否在位，缺失时在日志告警（[dsh-view-image] pi-ai vision patch is MISSING）；
- settings 的模型声明热生效；插件文件与补丁改动需重启 dsh web。

回滚

- 停用插件：删除 cordis.patch.yml 里的 dsh-view-image 块；
- 恢复适配器：删除补丁后重新安装 dsh 即还原（或手工把 case "image" 分支改回原始图片输出）；
- 恢复 settings：删除 modelOverrides 下对应模型的 input 声明。

安全说明

- 视觉接口密钥只存本机 vision-bridge-config.json（该文件已被 .gitignore 排除）或环境变量；
- 插件无日志、无缓存、无运行数据写盘。