ld-1101/dsh-vision-plugin

给 DeepSeek Harness（DSH）装上"眼睛"：纯文本模型（如 deepseek-v4-flash）也能处理图片——发图后自动用视觉模型生成描述，文本模型基于描述回答；描述不足时自动生成更具体的提示词重新解析。配置全程 GUI 可视化、保存即生效。

⚠️ 社区项目，非 DeepSeek 官方。已在 DSH 0.1.0-rc.6（Desktop）实测。

📦 v1.0.0 ｜ MIT License ｜ Windows + PowerShell 安装 ｜ 支持 desktop / web / headless profile

---

✨ 特性

• 🖼️ 发图自动接管：对话模型收到图片不再被拒绝——用默认提示词调视觉模型生成描述，文本模型基于描述回答
• 🔁 迭代式视觉解析：描述不足时，对话模型自动生成更具体的提示词调用 view_image 重新解析（可省略 image 参数复用会话最近上传的图片）
• 🧩 两种连接模式：
  • 系统模型：自动检测 DSH 已启用且支持视觉的模型（Xiaomi / OpenCode Zen Go 等），复用系统 API Key，零配置
  • 自定义模型：手动填 OpenAI 兼容端点（URL + Key + 模型），内置 8 家常见服务商示例（智谱 GLM-4V / 通义千问 VL / OpenAI / 火山方舟 / 硅基流动 / OpenRouter / OpenCode Go / 小米 MiMo）
• 🎛️ GUI 可视化配置（设置 → 视觉模型）：保存即生效（live），无需重启，带 read-back 校验
• 🔒 Key 安全：role('secret') 自动脱敏，只写不读，永不回流前端；配置摘要不泄露 Key 明文
• 📋 未配置引导：视觉模型未配置时明确提示"请到 设置 → 视觉模型 配置"，不再报"模型不支持图片"
• 🧪 33 项自动化测试（23 项逻辑 + 5 项 bundle 契约 + 5 项真实 React 渲染）

🧠 工作原理（三层机制）

① 图片桥（admission 接管 · 宿主补丁）
   图片到达 → 宿主原逻辑：模型不支持 image 则拒绝
   插件已装 → visionImageBridge 服务接管 → 放行（不拒绝）

② pre-step 自动描述（agent/pre-step 事件钩子）
   图片消息 → 用默认提示词调视觉模型 → 生成描述文本
   会话日志保留原图（surface 占位替换），模型侧只看到描述
   未配置视觉模型 → 插入引导消息，不报"不支持图片"

③ view_image 工具（迭代式解析）
   描述不足 → 对话模型自动调 view_image（可省略 image 复用最近图片）
   → 传入针对性提示词（OCR / UI 布局 / 具体数值…）→ 重新解析 → 基于新描述回答

📦 安装（3 步）

前置

• Windows + PowerShell（脚本为 Windows 编写）
• DSH Desktop（0.1.0-rc.6）或 DSH CLI（web/headless profile）
• 已启用至少一个支持视觉的模型供应商（DSH 设置 → 模型，如 xiaomi 的 mimo-v2.5）

步骤

# 1) 克隆仓库，进入目录
git clone https://github.com/ld-1101/dsh-vision-plugin.git
cd dsh-vision-plugin

# 2) 安装插件（默认 desktop profile；web 用 -Profile web）
powershell -ExecutionPolicy Bypass -File install.ps1

# 3) 打宿主补丁（让文本模型接收图片；幂等，DSH 升级后重跑）
powershell -ExecutionPolicy Bypass -File patch-host.ps1

重启 DSH，打开 设置 → 视觉模型 配置。

补丁说明：修改 dsh-host-apiproxy 两处——① 图片准入：插件已装即接管图片（pre-step 转描述），未装保持宿主原行为；② settings namespace 暴露：允许 GUI 写入配置。原文件自动备份为 index.js.bak-dsh-vision，可用备份还原。两处补丁点都有严格匹配校验，宿主版本变化会明确报错而非静默打坏。

卸载

1. 退出 DSH
2. 从 profile 的 cordis.patch.yml 中移除 dsh-vision 与 dsh-vision-client 两个条目
3. 删除 ~/.dsh/profiles/<profile>/plugins/dsh-vision 与共享目录 ~/.dsh/profiles/node_modules/dsh-vision-client
4. 如需还原宿主行为：用备份 index.js.bak-dsh-vision 还原 dsh-host-apiproxy/lib/index.js 后重启

⚙️ 配置（设置 → 视觉模型）

连接模式

◉ 系统模型（复用系统 Key，无需填写）
   ○ MiMo-V2.5 · Xiaomi            ●系统凭证
   ○ mimo-v2-omni · Xiaomi         ●系统凭证
   ○ kimi-k2.7-code · OpenCode Zen Go
   ...（自动检测，只显示支持视觉的模型；
       "共 N 个视觉模型" + 可添加建议）
○ 自定义模型（OpenAI 兼容接口）
   API Base URL [____]   API Key [____]（只写不读）
   Key 环境变量 [____]   模型名称 [____]
   ▸ 查看常见服务商端点示例

提示词与参数

字段	说明
系统提示词	发给视觉 API 的 system 消息（留空不发送）
默认提示词	发图自动描述/未传 prompt 时使用的提示词
超时 / 最大 token / 温度	请求参数（高级参数折叠区）
URL 图片模式	direct 直传（省流量）/ download 下载转 base64

保存与验证

• 保存更改：保存后立即生效（live），无需重启；带 read-back 校验，失败会明确提示
• 撤销改动：清空未保存的草稿
• 测试连接：用 1x1 测试图真实请求，显示延迟与模型返回

🔧 view_image 工具

对话中由模型自动调用的"看图"统一入口，也支持用户直接表达意图触发：

参数	必填	说明
image	否	图片的本地绝对路径或 http(s) URL；省略时自动复用会话最近上传的图片
prompt	否	视觉理解提示词；省略时使用配置的「默认提示词」

• 本地路径 → 自动读取转 base64 data URI（png / jpg / webp / gif / bmp / avif / svg / ico）
• URL → 按配置 direct 直传，或下载后转 base64
• 返回 → [视觉模型 {model} 对 {source} 的识别结果] + 描述文本

🚀 使用

1. 聊天直接发图（核心场景）

用户发一张图
  → 自动：视觉模型用默认提示词生成详细描述
  → 文本模型基于描述回答
  → 追问细节（"图里小字写的什么？"）
  → 文本模型判断描述不足 → 自动调 view_image 生成更具体的提示词重新解析
  → 基于新描述回答

2. 说"看这个文件"

"看看 C:\shot.png 里是什么"
→ agent 调用 view_image（本地路径 → 自动 base64 → 视觉模型）

3. 发 URL

"看下 https://example.com/a.jpg"
→ view_image 直传 URL（或下载转 base64）

4. 未配置视觉模型时

发图后对话模型回复："视觉模型未配置：请在 设置 → 视觉模型 中选择系统模型或配置自定义模型"。

🗂️ 仓库结构

dsh-vision-plugin/
├── src/index.ts            # 插件主体（view_image 工具 / 图片桥 / pre-step 描述 / settings 接入 / 3 个路由）
├── dist/                   # GUI client 包（设置 → 视觉模型 面板），随 install.ps1 安装到共享 node_modules
│   ├── package.json        #   dsh-vision-client 包声明（platform: web）
│   └── lib/
│       ├── index.js        #   client 包入口
│       └── client.js       #   React 设置面板 bundle（__ModuleLoader__ 格式）
├── install.ps1             # 一键安装（-Profile 参数：desktop / web / …）
├── patch-host.ps1          # 宿主补丁（幂等，升级 DSH 后重跑）
├── cordis.patch.yml        # bundle patch 声明（随包发布）
├── package.json            # 插件声明（main: src/index.ts，dsh.client platform: web）
├── docs/
│   └── design-gui-config.md # GUI 配置设计文档（方案对比 / 数据流 / 历史）
├── test/
│   ├── e2e.mts             # 23 项逻辑测试（mock：双模式/发图接管/桥/兜底/Key 安全）
│   ├── client-bundle.mts   # 5 项 bundle 契约测试（mock __ModuleLoader__）
│   └── client-render.mts   # 5 项真实 React 18 渲染测试
├── LICENSE                 # MIT
└── README.md

🧪 测试与开发

⚠️ 前置：测试读取的是已安装到 profile 的插件副本（与 src/index.ts 内容一致，见各测试文件头注释），请先执行 install.ps1（desktop）完成安装，再运行测试。换机器运行时，把测试文件里硬编码的本机 profile 路径替换为对应路径即可。

node test\e2e.mts            # 23 项逻辑测试（双模式 / 发图接管 / 图片桥 / 兜底表 / Key 安全）
node test\client-bundle.mts  # 5 项 bundle 契约测试
node test\client-render.mts  # 5 项真实 React 渲染测试（React 18 + react-dom/server）

• 测试不依赖真实网络与 API Key，全部本地可跑
• 真实 API 集成验证：安装后到 GUI「设置 → 视觉模型」点击测试连接（1x1 测试图真实请求），或在本地按需编写 integration-real.mjs（不入库）
• 修改 GUI 面板（dist/）后，需同步更新 dist 产物再执行 install.ps1 才会生效

❓ 常见问题

问题	解决
系统模型只有 1 个	面板会列出"可添加的视觉模型"；在 DSH 设置 → 模型 中给供应商添加视觉模型（如 kimi-k2.7-code / qwen3.6-plus / mimo-v2-omni）
保存显示"未生效"	确认已执行 patch-host.ps1 并重启 DSH（namespace 暴露补丁）
发图仍提示"不支持图片"	插件未加载（检查 设置 → 插件 中 dsh-vision 状态）/ 未打补丁
DSH 升级后插件失效	重跑 install.ps1 + patch-host.ps1（补丁点不匹配会明确报错，请把新版本宿主文件发 issue）
跨机器部署	复制仓库 → 运行两个脚本 → 拷贝 ~/.dsh/settings.yaml 中的 dsh-vision: 配置节
测试报错找不到文件	先执行 install.ps1（测试读取已安装到 profile 的插件副本）
自定义模式请求失败	检查 Base URL 是否含 /chat/completions 后缀（应只填到版本路径为止）、Key 是否有效、模型名是否支持视觉

📝 版本记录

版本	日期	说明
v1.0.0	2026-08-17	首个发布版：发图自动接管 + view_image 迭代式解析 + GUI 可视化配置（系统/自定义双模式）+ 宿主补丁方案 + 33 项自动化测试

🙏 致谢

• 思路借鉴：dsh-llm-image-routing（MIT）——发图接管机制（agent/pre-step 描述 + 会话占位管理）参考了其 describe 模式设计思路；本插件代码为独立实现，并针对 DSH 0.1.0-rc.6 采用宿主补丁方案。
• 官方参考：DeepSeek Harness 的工具定义 DSL、settings 配置通道、settings.section 注册方式。
• 数据来源：系统视觉模型清单来自 @earendil-works/pi-ai 内置模型目录。

📄 License

MIT