本地视觉桥接 nvbb/dsh-ollama-vision-bridge

dsh-ollama-vision-bridge

DeepSeek Harness（DSH）插件（适配 DSH ≥ 0.1.2-rc.1）：当聊天选中的模型不支持图片时，自动用本地 Ollama VL 模型描述图片，并把说明在同一个模型步骤里注入给模型；图片本身保留在对话历史里（请求携带 Ollama keep_alive，推理结束后模型在显存中只驻留一小段时间，空闲即自动卸载——显存冷却，不占其他模型的显存）。

English：一个 DeepSeek Harness（DSH ≥ 0.1.2-rc.1）插件，用于纯文本聊天模型 + 本地图像理解。当你把图片附加到不支持图片的模型时，本地 Ollama 视觉模型（默认 qwen3-vl:8b）会描述它，描述会被注入到同一个模型步骤——一次发送，一次回答，无云端，无 API 密钥。图片保留在你的消息历史中；VL 模型会在短暂的 keep_alive 空闲后卸载（显存冷却）。当 Ollama 不可用时，回退到 DSH 原生的拒绝行为。中文文档如下。

原理

- 安装时（patch/apply.mjs）给 @deepseek-ai/dsh-api-session-controller 打一个幂等补丁。
DSH 0.1.2-rc.1 删除了旧版 dsh-host-apiproxy，把「聊天发图 → 模态检查 → 入队」挪进了这个包（Web GUI 运行的是其 bundle lib/index.js，另有同类的独立编译产物 lib/types/commands.js，两处都打）。原逻辑是「模型不支持图片 → 抛 MODEL_DOES_NOT_SUPPORT_IMAGES 拒绝」，补丁把它改为先调本地 Ollama VL 模型（默认 qwen3-vl:8b）：
- 图片先按 DSH 原生流程落库成 durable 引用并保留在你的消息里，你的消息一字不改，且只排队这一条消息（一次发送 = 一次回答，不会多出额外回复）；
- 描述通过 agent/pre-step 瀑布钩子在模型请求生成时并入同一步骤；
- 描述作为独立的「上下文注入」消息（source: { kind: "plugin", plugin: "dsh-ollama-vision-bridge" }）进入对话，界面显示为一条可折叠的"上下文注入"条目；
- 描述文本自带系统说明，引导模型在回答开头告知「当前模型不支持原生图片识别，已调用本地视觉模型识别」，然后基于描述正式回答；
- 桥接未配置或 Ollama 不可用时回退到 DSH 原有的拒绝行为（错误码不变）。
- 备注：0.1.2-rc.1 自带的 dsh-llm 已会把「文本模型请求中的图片块」投影成 [image omitted …] 占位文本，所以保留图片引用的用户消息永远不会真正发给文本适配器；桥接的价值在于让模型拿到本地 VL 模型对图片的真实描述，而不是一个空占位符。
- 运行时（lib/index.js）是一个极小且不会抛错的 Cordis 行，启动时检查补丁/配置状态并打印日志，也提供 /vision-bridge 状态命令（若 commands 服务存在）。
- 包声明了 dsh.bundle.patch，dsh plugin add 后会自动挂进 profile 的 bundles 层（补丁行 vision-bridge），无需手改 cordis.patch.yml。

安装（首次 / 换新机器）

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

方式一：从 GitHub 安装 ：

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"

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

然后重新启动 dsh web。

apply.mjs 做四件事（幂等，可重复跑）：
1. 补丁 dsh-api-session-controller 的两份产物（已打则跳过）；
2. settings.yaml 追加 llm-pi-ai 提供商 ollama（已有该段则跳过）；
3. settings.yaml 的 vision-bridge 段 / 独立 vision-bridge.yaml（已有则跳过）；
4. 检查 OLLAMA_MODELS 下有没有 VL 模型 manifest，没有就给出提示。

DSH 更新后

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

dsh plugin --profile web update dsh-ollama-vision-bridge # 或直接 dsh plugin --profile web add
node "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-ollama-vision-bridge\patch\apply.mjs"

配置

配置在 DSH 的设置文档 $DSH_HOME\settings.yaml 的 vision-bridge: 段（与 llm-pi-ai 同款，热加载，改完即生效，不用重启；旧的独立 vision-bridge.yaml 仍作为兼容回退，优先读 settings.yaml）：

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

环境变量可覆盖：DSH_VISION_BRIDGE_BASE_URL / DSH_VISION_BRIDGE_MODEL / DSH_VISION_BRIDGE_KEEP_ALIVE。删除 vision-bridge 段（或置空 model、或 enabled: false）即关闭桥接，恢复 DSH 原生拒绝行为。

前提：Ollama 在跑（ollama list 能看到模型），模型目录环境变量 OLLAMA_MODELS 指向含 qwen3-vl:8b 的目录。

二次发布 / 自托管

本仓库本身就是完整的 git 仓库，且零 npm 依赖（apply.mjs / lib 只用 node 内置模块，补丁注入的运行时辅助代码所需的 js-yaml 由 DSH 宿主环境提供——无需 npm install、无 lockfile）。clone / fork 后推到自己的 GitHub / Gitee 远程即可：

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

目录结构

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

开发 / 测试

node patch/apply.mjs --check # 只读检查：宿主补丁与配置状态（需 DSH profile 在位）
node test/bridge-smoke.mjs # 端到端冒烟：需本地 Ollama(127.0.0.1:11434) 且 VL 模型在位

已知限制

- 依赖 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-vl:8b）发图走 DSH 原生通道，不经过桥接，其卸载时机由 Ollama 全局 OLLAMA_KEEP_ALIVE（默认 5 分钟）决定。