dsh-ollama-vision-bridge

DeepSeek Harness（DSH）插件（适配 DSH ≥ 0.2.0-rc.1，0.2.1-rc.2 实测）：当聊天选中的模型不支持图片时， 自动用本地 Ollama VL 模型描述图片，并把说明在同一个模型步骤里注入给模型；图片本身 保留在对话历史里（请求携带 Ollama keep_alive，推理结束后模型在显存中只驻留一小段时间， 空闲即自动卸载——显存冷却，不占其他模型的显存）。视觉模型可随时用命令行切换：换一个 本地 VL 模型只需一条 npx dsh-ollama-vision-bridge model <模型名>。

English: A DeepSeek Harness (DSH ≥ 0.2.0-rc.1) plugin for text-only chat models + local image understanding. When you attach an image to a model that does not support images, a local Ollama vision model (default qwen3-vl:8b; switch anytime with npx dsh-ollama-vision-bridge model <name>) describes it and the description is injected into the same model step — one send, one answer, no cloud, no API key. Images stay in your message history; the VL model unloads after a short keep_alive idle (VRAM cooling). Falls back to DSH's native rejection when Ollama is down. 中文文档如下。

原理

• 安装时（patch/apply.mjs）给 @deepseek-ai/dsh-api-session-controller 打一个幂等补丁。 DSH 0.1.2 删除了旧版 dsh-host-apiproxy，把「聊天发图 → 模态检查 → 入队」挪进了 这个包（Web GUI 运行的是其 bundle lib/index.js，另有同类的独立编译产物 lib/types/commands.js，两处都打）。原逻辑是「模型不支持图片 → 抛 MODEL_DOES_NOT_SUPPORT_IMAGES 拒绝」，补丁把它改为先调本地 Ollama VL 模型：
  • 图片先按 DSH 原生流程落库成 durable 引用并保留在你的消息里，你的消息一字不改， 且只排队这一条消息（一次发送 = 一次回答，不会多出额外回复）；
  • 描述通过 agent/pre-step 瀑布钩子在模型请求生成时并入同一步骤；
  • 描述作为独立的**「上下文注入」消息**（source: { kind: "plugin:dsh-ollama-vision-bridge" }，DSH 0.2.x 会话格式 v4 要求 producer-owned source kind，旧的 kind: "plugin" 会被拒绝） 进入对话，界面显示为一条可折叠的"上下文注入"条目；
  • 描述文本自带系统说明，引导模型在回答开头告知「当前模型不支持原生图片识别， 已调用本地视觉模型识别」，然后基于描述正式回答；
  • 桥接未配置或 Ollama 不可用时回退到 DSH 原有的拒绝行为（错误码不变）。
• 配置来源（DSH ≥ 0.2.0）：插件行 vision-bridge 的配置写在 profile 的 cordis.patch.yml 里（- id: vision-bridge + config:），运行时行 lib/index.js 把它发布到进程内全局，补丁注入的 helper 直接读取；旧版主机仍回退读取 settings.yaml 的 vision-bridge: 段 / 独立 vision-bridge.yaml。
• 运行时（lib/index.js）是一个极小且不会抛错的 Cordis 行，启动时检查补丁状态并 打印当前模型；也提供 /vision-bridge 状态命令（若 commands 服务存在）。
• 包声明了 dsh.bundle.patch，dsh plugin add 后会自动挂进 profile 的 bundles 层 （补丁行 vision-bridge），无需手改 cordis.patch.yml。

准备：安装 Ollama 并下载视觉模型

本插件依赖本机 Ollama 提供视觉能力（不需要云端 API key）。详见 Ollama 官方文档：https://ollama.com，模型库：https://ollama.com/library。

1. 安装 Ollama（Windows / macOS / Linux 安装包见 https://ollama.com/download）：

   # Windows：下载 https://ollama.com/download/windows 安装包，双击安装，装完托盘常驻
   # macOS / Linux 也可用官方脚本：
   # curl -fsSL https://ollama.com/install.sh | sh
   

2. 确认服务在跑（默认端口 11434）：

   curl.exe http://127.0.0.1:11434/api/tags   # 返回 JSON 即正常；连不上就启动托盘里的 Ollama
   

3. 下载一个视觉（VL）模型（默认用 qwen3-vl:8b，约 6GB；也可换任意 Ollama VL 模型，模型名即 --model 参数）：

   ollama pull qwen3-vl:8b
   # 可选的同类视觉模型：qwen3-vl:30b、gemma3:12b、minicpm-v 等（越大越强，显存要求更高）
   # 更多模型见 https://ollama.com/library
   

4. 模型库放别的磁盘（可选）：Windows 上在 Ollama 托盘 → Settings 里修改模型目录（或设 OLLAMA_MODELS 环境变量后重启 Ollama），再用 ollama list 确认能看到刚下载的模型。

安装（首次 / 换新机器）

先停掉正在运行的 dsh web（Windows 上 node 会锁住 node_modules，运行中装不了）；装完再启动。

方式一：npx 一键安装（推荐）——校验模型、装插件、打补丁、写配置一步到位：

npx github:nvbb/dsh-ollama-vision-bridge setup --model qwen3-vl:8b

（发布到 npm 后也可 npx dsh-ollama-vision-bridge setup --model qwen3-vl:8b。）

如果你的 DSH 是通过 npx 启动的（如 npx.cmd --yes @deepseek-ai/dsh@0.2.1-rc.2 web）， 请把同一个入口传给 CLI，否则 setup 找不到 dsh 命令：

npx.cmd --yes github:nvbb/dsh-ollama-vision-bridge setup --model qwen3-vl:8b `
  --dsh "npx.cmd --yes @deepseek-ai/dsh@0.2.1-rc.2"

方式二：npm 包安装（插件已发布到 npm 时）：

dsh plugin --profile web add dsh-ollama-vision-bridge
npx dsh-ollama-vision-bridge setup --skip-install --model qwen3-vl:8b

方式三：git / 手动安装：

dsh plugin --profile web add git+https://github.com/nvbb/dsh-ollama-vision-bridge.git
node "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-ollama-vision-bridge\patch\apply.mjs"
node "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-ollama-vision-bridge\bin\cli.js" model qwen3-vl:8b

本地开发 / 调试：dsh plugin --profile web add file:<仓库的本地路径>（如 file:C:/dev/dsh-ollama-vision-bridge，不需要 git 远程）。

然后重新启动 dsh web。

apply.mjs 做四件事（幂等，可重复跑）：

1. 补丁 dsh-api-session-controller 的两份产物（已打则跳过；旧版 helper 块自动刷新为 v3）；
2. settings.yaml 存在时追加 llm-pi-ai 提供商 ollama（0.2.x 的 profile 在 cordis.patch.yml 配置）；
3. 写 legacy vision-bridge.yaml（0.2.x 由 CLI 写 profile 行，此文件仅旧版回退用）；
4. 检查 OLLAMA_MODELS 下有没有 VL 模型 manifest，没有就给出提示。

用命令行修改视觉模型（DSH ≥ 0.2.0）

视觉模型换了？不用改任何文件，一条命令：

npx github:nvbb/dsh-ollama-vision-bridge model qwen3.8:27b-iq3s --keep-alive 10m
npx github:nvbb/dsh-ollama-vision-bridge status --check   # 查看当前配置并校验模型在位
npx github:nvbb/dsh-ollama-vision-bridge check --model qwen3.8:27b-iq3s --probe   # 真跑一张 1x1 图

命令	作用
setup --model <name>	首装：校验模型 → dsh plugin add → 打补丁 → 写 vision-bridge 配置行
model <name> / set-model <name>	只切换 VL 模型（可加 --base-url / --keep-alive / --apply）
status	显示 profile 配置中的 model / baseURL / keepAlive；--check 顺带校验
check --model <name>	查 GET /api/tags 确认模型存在；--probe 再跑真实推理验证是 VL 模型

常用选项：--base-url <url>（默认 http://127.0.0.1:11434）、--keep-alive <60s/10m/0>、 --profile <web>、--skip-install / --skip-apply / --no-check、--profile-file <path>。

命令写的是 profile 的 cordis.patch.yml（自动备份为 *.bak-*-visioncli），更新后重启 dsh web 生效。也可以用 GUI 的 settings 表单改 profile 配置（若该 profile 渲染了设置页）， 或直接编辑对应的 - id: vision-bridge 行。

在聊天里查询 / 切换（/vision-bridge）

安装并重启后，直接在对话框输入，无需改文件、无需重启：

用法	作用
/vision-bridge status	显示当前 VL 模型、Ollama 地址、keep_alive、宿主补丁状态
/vision-bridge model qwen3-vl:8b	把桥接切换到另一个本地 VL 模型（先查 GET /api/tags 校验该模型在位）
/vision-bridge base-url http://127.0.0.1:11434	改 Ollama 地址
/vision-bridge keep-alive 10m	改显存冷却时间（60s / 10m / 0=立即卸载）
/vision-bridge reset	恢复默认配置（删除 model/baseURL/keepAlive 覆盖项）

命令走 DSH 的 ctx.configEditor 写 profile 配置（保留 YAML 注释），同时立即更新进程内桥接配置， 下一次发图即用新模型。CLI 的 model 命令与它等价：CLI 适合脚本/首次安装， /vision-bridge 适合日常在聊天框里切换。

DSH 更新后

dsh plugin / pnpm 重装会覆盖被打补丁的包，重跑一次即可：

npx github:nvbb/dsh-ollama-vision-bridge setup --skip-install --model <你的 VL 模型>

或等价地：dsh plugin --profile web update dsh-ollama-vision-bridge，再跑 node "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-ollama-vision-bridge\patch\apply.mjs"。

配置

DSH 0.2.x 的配置在 profile 的 cordis.patch.yml（$DSH_HOME\profiles\<name>\cordis.patch.yml， CLI 会自动维护这一段）：

- id: vision-bridge
  config:
    model: 'qwen3.8:27b-iq3s'          # 兜底 VL 模型；用 model 命令切换
    baseURL: 'http://127.0.0.1:11434'  # Ollama 地址
    keepAlive: '10m'                   # 显存冷却：空闲 10m 后卸载；0 = 推理完立即卸载
    # enabled: true                    # 总开关；false 时文本模型发图恢复 DSH 原生拒绝
    # models:                          # 按聊天模型映射（可选，覆盖默认）
    #   "deepseek-v4-flash": "qwen3-vl:8b"
    # prompt: 自定义描述提示词（可选）
    # timeoutMs: 300000

旧版主机（0.1.x，settings.yaml 仍在）仍读取 $DSH_HOME\settings.yaml 的 vision-bridge: 段， 最后回退独立 vision-bridge.yaml。环境变量可覆盖：DSH_VISION_BRIDGE_BASE_URL / DSH_VISION_BRIDGE_MODEL / DSH_VISION_BRIDGE_KEEP_ALIVE。删除配置行（或 enabled: false） 即关闭桥接，恢复 DSH 原生拒绝行为。

前提：已按上文「准备」装好 Ollama 并下载了 VL 模型（ollama list 能看到），模型库环境变量 OLLAMA_MODELS 指向它的目录。

卸载

先停掉 dsh web（Windows 上 node 会锁住 profile 的 node_modules，运行中删不掉）。

方式一：一条命令（用 npx 启动 DSH 时也适用）：

# --dsh 传你平时启动 DSH 的同一个入口；npx 启动方式示例：
npx.cmd --yes github:nvbb/dsh-ollama-vision-bridge uninstall `
  --dsh "npx.cmd --yes @deepseek-ai/dsh@0.2.1-rc.2"

它依次做四件事：

1. dsh plugin --profile web remove dsh-ollama-vision-bridge（从 profile 移除插件）；
2. 从 profile 的 cordis.patch.yml 删除 - id: vision-bridge 配置块（自动备份）；
3. 运行 patch/apply.mjs --unpatch，把所有 controller 副本还原为 DSH 原始代码；
4. 提示重启 dsh web。

方式二：手动（等价步骤）：

# 1) 移除插件（入口用你平时启动 DSH 的那一个）
npx.cmd --yes @deepseek-ai/dsh@0.2.1-rc.2 plugin --profile web remove dsh-ollama-vision-bridge

# 2) 还原 controller 补丁（用仓库里的脚本；profile 内那份会随插件一起删除）
node <你的仓库路径>\patch\apply.mjs --unpatch

# 3) 删除 profile 配置中的 - id: vision-bridge 块
#    或用 CLI 自动处理（跳过已手动完成的步骤）：
node <你的仓库路径>\bin\cli.js uninstall --skip-plugin --skip-restore

然后重新启动 dsh web。

uninstall 的可选开关：--skip-plugin（只删配置并还原补丁）、--keep-config（保留配置行）、 --skip-restore（只移除插件/配置，不动 controller），便于分步处理。

可选清理（不删也不影响，插件与补丁移除后不再读取）：

• $DSH_HOME\vision-bridge.yaml（旧版 legacy 配置）；
• $DSH_HOME\profiles\web\cordis.patch.yml.bak-*-visioncli（CLI 修改配置时留下的备份）。

二次发布 / 自托管

本仓库本身就是完整的 git 仓库，零 npm 依赖（apply.mjs / lib 只用 node 内置模块； 运行时依赖宿主提供的 @deepseek-ai/schemastery 与 js-yaml，无需 npm install、无 lockfile）。 clone / fork 后推到自己的 GitHub / Gitee 远程即可：

• 从 git 安装：本仓库直接照「安装-方式三」执行即可；fork 后把命令里的仓库地址换成你自己的 fork；
• 发布到 npm：先确认 package.json 的 name 未被占用，再 npm publish； 之后可用「安装-方式二」/npx dsh-ollama-vision-bridge 直接按包名安装；
• 私有远程：先配置 git 凭据（Windows 凭据管理器 / SSH）。

目录结构

dsh-ollama-vision-bridge/
├── package.json          # dsh.bundle.patch → 自动挂载为 profile bundle；bin 提供 CLI
├── cordis.patch.yml      # 插入 vision-bridge 运行时行
├── bin/cli.js            # npx 安装器/配置器：setup / model / status / check
├── lib/index.js          # 运行时行：发布配置到全局 + 状态检查（绝不抛错）
├── test/bridge-smoke.mjs # 端到端冒烟测试（真实调本地 Ollama VL 模型）
├── LICENSE               # MIT
└── patch/
    ├── source.mjs        # 补丁源码（单一事实源，含 v4 辅助代码与锚点）
    └── apply.mjs         # 安装/重装/检查脚本（支持 --check / --file）

开发 / 测试

node patch/apply.mjs --check   # 只读检查：宿主补丁与配置状态（需 DSH profile 在位）
node bin/cli.js status --check # 查看 profile 配置并校验模型在位
node bin/cli.js model <name>   # 切换 VL 模型（写 profile 的 vision-bridge 行）
node test/bridge-smoke.mjs     # 端到端冒烟：需本地 Ollama(127.0.0.1:11434) 且 VL 模型在位

排障：普通浏览器卡死 / 白屏（与插件无关）

症状：更新插件并重启 dsh web 后，普通浏览器标签页打开后卡死/白屏，而无痕窗口正常。

这是 DSH Web 的登录态 / 浏览器本地状态问题，不是本插件造成的，依据：

• 本插件没有前端代码（无 client bundle、无 service worker），不写浏览器缓存；
• 插件的所有改动都在服务端：controller 补丁、profile 配置、/vision-bridge 聊天命令；
• 前端静态资源随 DSH 包发布（本机为 dsh-web-frontend，哈希资源未变），服务端对 index.html 与接口使用 cache-control: no-store，客户端不缓存页面；
• DSH Web 用「启动 token → Cookie」登录：dsh web 启动时会打印形如 http://127.0.0.1:3080/?token=… 的 URL，用它打开会换发有效期约 30 天的签名 Cookie （dsh-client-connection 的 authorizeIndex）；没有有效 Cookie 时访问根地址会 401， 客户端可能因此表现为卡死/白屏。无痕窗口是全新 Cookie + token URL，所以正常。

处理顺序：

1. 用本次 dsh web 启动时打印的完整 token URL 打开一次（注意 host 一致： 127.0.0.1 与 localhost 的 Cookie 不通用）；
2. 仍卡：F12 → Application → Clear site data（Cookie / Storage / Cache），再用 token URL 打开；
3. 无痕可用而常规不行 → 常规浏览器是 Cookie/扩展问题：禁用扩展再试，或换一个干净的浏览器配置；
4. 若每次重启都复现、清 Cookie 也无效，请把 F12 Console/Network 的报错反馈给 DSH 上游。

插件更新本身只写服务端文件，不会破坏浏览器缓存；上述现象在任何 DSH 重启后都可能出现。

已知限制

• 依赖 dsh-api-session-controller 的 prompt 处理器两个稳定锚点（lib/index.js 的 单行拒绝式与 lib/types/commands.js 的多行拒绝块）。DSH 大版本若改动它们， apply.mjs 会报「refusal anchor not found」，届时更新本插件即可。
• 仅覆盖 Web GUI 普通会话的聊天发图路径；子代理等平行入口的图片拒绝（subagent/attachment-invalid） 不在桥接范围内（与旧版一致）。
• 直接选中 VL 模型（如 qwen3.8:27b-iq3s）发图走 DSH 原生通道，不经过桥接，其卸载时机由 Ollama 全局 OLLAMA_KEEP_ALIVE（默认 5 分钟）决定。
• 0.2.x 的配置热加载依赖宿主实现：改 profile 行后用 status 确认，必要时重启 dsh web。