dsh-ollama-vision-bridge

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

English: A DeepSeek Harness (DSH ≥ 0.1.2-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) 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-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 分钟）决定。