gugu123a/dsh-tool-see-image

👁️ dsh-tool-see-image

给你的文本模型装上眼睛。
see_image 把图片发给一个可配置的视觉模型（默认智谱 GLM-4V-Flash，免费）， 再把它的文字描述转发回你的 DeepSeek Harness 会话。

🎖️ 已入选社区 awesome-deepseek-harness-plugins 列表。

---

✨ 为什么

DSH 默认的纯文本模型（如 deepseek-v4-flash）无法看图。本插件通过一个小而免费的视觉模型给它装上眼睛—— 不需要本地 GPU、不需要图片编辑、不需要改动你的模型。

🚀 特性

• see_image 工具 —— 传一个图片路径 + 一个问题，得到一段文字描述。
• 视觉模型可切换 —— 任意 OpenAI 兼容的 /chat/completions 端点（默认智谱 GLM-4V-Flash，或 SiliconFlow / Qwen2.5-VL 等）。
• 沙箱感知 —— 通过 ctx.fs 读取，遵循 DSH 的沙箱 / 观察策略。
• 附赠粘贴转文字 —— 一个补丁脚本，让你在聊天框直接粘贴图片并自动转成文字。

📚 目录

• 工作原理
• 安装（DSH web profile）
• 配置项
• 卸载 / 回滚
• 实现要点
• 回归测试
• 实测记录
• 粘贴图片自动转文字
• License

---

🔍 工作原理

你: "看看这张图"  ──►  文本模型 (无视觉)
                          │ 调用 see_image(path, question)
                          ▼
                     本插件 (Host 平面)
                          │ 1. ctx.fs 解析并读取图片（遵守沙箱/观察策略）
                          │ 2. 图片转 base64 data URL
                          │ 3. POST {baseURL}/chat/completions（OpenAI 兼容）
                          ▼
                     视觉模型 (GLM-4V-Flash)
                          │ 文字描述
                          ▼
                     文本模型 ──► 汇报给你

---

📦 安装（DSH web profile）

1. 拷贝插件：把本仓库放进你的 profile 目录，例如 $DSH_HOME/profiles/web/plugins/dsh-tool-see-image/ （在 DSH 中，$DSH_HOME 通常是 ~/.dsh）

2. 声明依赖：在 $DSH_HOME/profiles/web/package.json 的 dependencies 中加入：

   "dsh-tool-see-image": "file:plugins/dsh-tool-see-image"
   

   然后 pnpm install（会在 profiles/node_modules 下生成指向源码的 junction 链接）。

3. 组合进配置：在 $DSH_HOME/profiles/web/cordis.patch.yml 中加入：

   - insert:
       - id: tool-see-image
         name: 'dsh-tool-see-image'
         config:
           baseURL: https://open.bigmodel.cn/api/paas/v4
           apiKeyEnv: ZHIPU_API_KEY
           model: glm-4v-flash
   

4. 设置 API Key：去 bigmodel.cn 控制台 → API Keys 创建一个 Key（形如 id.secret），然后设置环境变量（Windows 示例）：

   setx ZHIPU_API_KEY "你的key"
   

   重开终端，然后重启 dsh web（web profile 的补丁热重载官方尚未启用， 改 patch 后仅靠 watcher 不会生效——已实测）。

5. 验证：新会话里工具列表应出现 see_image。让它"看"一张图试试：

   请用 see_image 看一下 path/to/your/image.png
   

---

⚙️ 配置项（cordis.patch.yml 的 tool-see-image 行）

键	默认值	说明
baseURL	https://open.bigmodel.cn/api/paas/v4	OpenAI 兼容端点，插件自动拼 /chat/completions
apiKeyEnv	ZHIPU_API_KEY	读取 API Key 的环境变量名
model	glm-4v-flash	视觉模型 id（智谱免费）
maxTokens	1024	输出上限。注意：glm-4v-flash 上限为 1024（实测超限会返回 400 max_tokens参数非法）；换更大模型可调大
timeoutMs	60000	请求超时
maxBytes	15728640 (15MB)	单张图片大小上限
prompt	（中文详细描述指令）	缺省问题；question 参数优先

换其他视觉 API 只需改这三项，例如 SiliconFlow：

config:
  baseURL: https://api.siliconflow.cn/v1
  apiKeyEnv: SILICONFLOW_API_KEY
  model: Qwen/Qwen2.5-VL-32B-Instruct

---

🗑️ 卸载 / 回滚

1. 删掉 cordis.patch.yml 里的 - insert: ... tool-see-image ... 段；
2. 删掉 junction：Remove-Item profiles\node_modules\@deepseek-ai\dsh-tool-see-image；
3. 删掉 profiles/web/package.json dependencies 里那一行；
4. 重启 dsh web。

---

🧠 实现要点（供学习插件开发）

• 导出 { name, inject, Config, apply }，与所有 DSH 工具插件同构；
• inject: ["tools", "fs"]：工具注册表 + 沙箱化文件服务都是 Host 全局服务；
• 注册进全局层 → 所有会话可见（与 TUI 模式 host 工具行同理）；
• 读文件走 ctx.fs（自动应用沙箱/观察策略），不用裸 node:fs；
• 参数 schema 用 DSH 专用格式：required: true 显式必填，可选参数省略 required 键 （required: false 会被 defineTool 拒绝）；
• 网络请求带超时与 exec.signal 取消；错误信息面向模型可读。

---

🧪 回归测试

test/mount-test.mjs：用真实 Cordis Loader 挂载本插件行（timer + system-prompt + tools + 本插件），验证行激活且 see_image 进入工具注册表。运行：

$env:DSH_CHECKOUT="<你的 dsh 安装根目录，含 node_modules/@deepseek-ai>"
node test/mount-test.mjs

期望输出：tools.schemas() 含 see_image: true 与 === MOUNT TEST PASS ===。 脚本会自动把插件临时链接进 checkout 的 node_modules（Windows junction / 其它平台 symlink），测试结束自动清理，无本机路径硬编码。

---

📝 实测记录

• 2026-08-13：真实 Key + triz-workflow.png（DSH Web GUI 截图）→ HTTP 200，约 6.8s， 准确识别界面文字（搜索框/MCP 设置/Fetch/Filesystem/Sequential-Thinking）。
• 踩坑：glm-4v-flash 的 max_tokens 上限 1024（默认 2048 会 400，已修正默认值）。

---

📋 粘贴图片自动转文字（附带功能）

除了 see_image 工具（按路径看图），本仓库还附带一个补丁脚本， 让你能直接在聊天框粘贴图片并自动转成文字：

$env:DSH_CHECKOUT="<你的 dsh 安装根目录，含 node_modules/@deepseek-ai>"
node scripts/patch-dsh-image-relay.mjs          # 应用（幂等，自动备份）
node scripts/patch-dsh-image-relay.mjs --check  # 检查状态
node scripts/patch-dsh-image-relay.mjs --revert # 回滚
pm2 restart dsh-web                              # 重启后硬刷新浏览器

它补丁三个 DSH 包（host-apiproxy、llm-deepseek、client-ui），实现：

• 界面显示粘贴的图片（hidden 文字块被前端过滤，用户看不到描述）；
• DeepSeek 收到的是 GLM-4V-Flash 生成的 【图片：...】 描述而非原始像素；
• 相同图片命中本地缓存（~/.dsh/cache/image-relay/），失败 8 秒内优雅降级。

需要 ZHIPU_API_KEY。图片缓存本身使用可移植的 ~/.dsh/cache/image-relay/；只有 DSH 安装根目录需要显式设置。 注意：npx 升级 dsh 后需重新运行脚本——npm 缓存刷新会丢失补丁。

---

📄 License

MIT