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 做四件事（幂等，可重复跑）：
- 补丁
dsh-api-session-controller 的两份产物（已打则跳过）；
settings.yaml 追加 llm-pi-ai 提供商 ollama（已有该段则跳过）；settings.yaml 的 vision-bridge 段 / 独立 vision-bridge.yaml（已有则跳过）；- 检查
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 分钟）决定。
