图像视觉工具链gmleong/dsh-img

dsh-img

给纯文本模型装上眼睛，并升级成完整的本地视觉工具链 · Give text-only models eyes — 一个 DeepSeek Harness 插件，将任何纯文本编码 agent 桥接到视觉 API，外加一套本地、免 key 的像素工具（裁剪 / 像素差异 / 颜色 / OCR）。

- 🇨🇳 零成本开箱：默认接智谱 GLM-4V-Flash（免费），备选通义 Qwen-VL（免费额度）
- 🏠 免 key 本地模式：preset: ollama 直连本地 Ollama 视觉模型（如 minicpm-v:8b），零 API key、零外部依赖、不花钱
- 🔁 多后端自动回退：配置一个 backends 列表，按顺序 failover，一个挂了自动切下一个
- 🧰 本地像素工具（无需 key）：vision_crop / vision_pixel_diff / vision_colors / vision_ocr（本地 tesseract）/ vision_trace（SVG 矢量化）/ vision_extract_foreground（抠图）完全不调视觉 API
- 💾 识别结果缓存：按图片内容 + 问题 hash 持久化到 ~/.dsh/dsh-img-cache/，重复调用不重复花钱
- ⚙️ 设置页可视化配置：web 端「设置 → 插件」可直接改 preset / 填 key，无需 export 环境变量
- 🖥️ headless 支持：dsh --profile headless 下工具同样可用
- 📦 npm 一键安装：纯 JavaScript、零构建步骤
- 🔌 任意端点：custom 预设支持任何 OpenAI 兼容视觉端点（中转站 / 自建 vLLM / GPT-4o…）

安装（Install）

前置条件：Node.js ≥ 20；已装 dsh 本体（npm i -g @deepseek-ai/dsh，跑 dsh web 能开 http://127.0.0.1:3080 即可）。

① 装插件

cd ~/.dsh/profiles/web && pnpm add dsh-img --registry https://registry.npmjs.org

并把 dsh-img 加进该 profile 的 package.json → dsh.profile.bundles 数组（若 dsh plugin 命令在你的版本可用，则 dsh plugin --profile web add dsh-img 会自动登记）。

② 配 API key（只看图问答才需要；本地工具无需 key）

export ZHIPU_API_KEY=your-key-here   # 免费申请：https://open.bigmodel.cn/

③ 重启服务（key 必须注入到 dsh 进程）

pkill -f "dsh web"
ZHIPU_API_KEY=your-key-here dsh web

④ 新建会话，直接贴图进对话框，或对 agent 说：

用 analyze_image 看一下 ./screenshot.png 里写了什么

切换后端 / 多后端回退（Backends）

编辑 profile 的 cordis.patch.yml（$DSH_HOME/profiles/web/cordis.patch.yml），按 id 覆盖整行。

单个后端（向后兼容）：

- id: image-bridge
name: dsh-img
config:
preset: qwen        # zhipu | qwen | ollama | custom

免 key 本地模式（Ollama 已装视觉模型，如 minicpm-v:8b）：

- id: image-bridge
name: dsh-img
config:
preset: ollama      # 默认 http://127.0.0.1:11434/v1 + minicpm-v:8b，无需 key

多后端回退链（新 backends 字段，从左到右 failover）：

- id: image-bridge
name: dsh-img
config:
backends:
- preset: zhipu                       # 首选（失败→下一个）
- preset: qwen
- preset: custom
baseURL: https://your-gateway/v1
model: gpt-4o
apiKeyEnv: MY_GATEWAY_KEY

key 分别用 ZHIPU_API_KEY / DASHSCOPE_API_KEY / MY_GATEWAY_KEY 注入，或直接在 web 设置页填写。

设置页 & headless

- web 设置页：打开「设置 → 插件」→ dsh-img 卡片，可视化改 preset、填 apiKey（密文存储）。改完即时生效，无需 export 环境变量。
- headless：dsh --profile headless 下先用 dsh plugin --profile headless add dsh-img 装一次，之后 8 个工具均可用（本地工具无需 key，识图类用 preset: ollama 或环境变量 key）。

工具（Tools）

需要 key（走视觉后端）

| 工具 | 说明 |
|---|---|
| analyze_image(path, question) | 图片问答 / OCR / 布局理解，返回文字答案 |
| vision_ground(path, target) | 定位目标元素，返回原图像素坐标框 x1,y1,x2,y2 |

无需 key（纯本地）

| 工具 | 说明 |
|---|---|
| vision_crop(path, region, out?) | 裁剪 "x1,y1,x2,y2" 区域，输出 PNG |
| vision_pixel_diff(original, rebuilt, out?) | 像素级比对：diff 比率 + 最差区域排行 + 红色热力图 |
| vision_colors(path, top?) | 提取主色（hex + 占比） |
| vision_ocr(path) | 本地 tesseract 转录（chi_sim+eng），失败自动转视觉后端 |
| vision_trace(path, steps?, out?) | potrace 矢量化：位图 → SVG 路径（logo/图标/线稿） |
| vision_extract_foreground(path, tolerance?, out?) | 边界 flood fill 抠图：均匀背景变透明，输出透明 PNG |

支持 .png .jpg .jpeg .webp .gif .bmp。

配置项（Config）

| 字段 | 默认 | 说明 |
|---|---|---|
| preset | zhipu | 旧式单后端快捷方式（zhipu/qwen/custom） |
| backends | 无 | 新式：有序后端数组，从左到右 failover（优先于 preset） |
| timeoutMs | 60000 | 单次请求超时 |
| maxImageMB | 10 | 图片大小上限 |
| detail | auto | auto / low / high |
| chatBridge | true | 对话框直发图：声明图片输入 + 请求前把附件转译成文字 |
| bridgePrompt | 内置 | 附件转译时发给视觉模型的问题 |
| cache | true | 识别结果持久化缓存（~/.dsh/dsh-img-cache/） |
| ocrLang | chi_sim+eng | 本地 OCR 的 tesseract 语言包 |
| pixelDiffSampleMax | 1024 | pixel-diff 降采样最长边（控制 CPU） |
| traceSteps | 4 | vision_trace 的 posterize 颜色层数 |
| foregroundTolerance | 40 | vision_extract_foreground 的背景色容差（越大抠得越狠） |

排错（Troubleshooting）

| 报错 | 原因与解法 |
|---|---|
| all N vision backend(s) failed | 回退链里每个后端都失败；检查各 key 环境变量是否注入 dsh 进程 |
| Vision API HTTP 401 | key 错误或未开通对应模型 |
| Unsupported image type | 转了不支持的格式；先转成 png/jpg |
| Image too large | 超过 maxImageMB；调大配置或压缩图片 |
| vision_ground could not parse a box | 视觉模型没按格式返回坐标；换模型或用更明确的目标描述 |
| 所有工具调用崩 reading 'prepare' | 装的是 ≤0.2.3 旧版（双实例 bug）；pnpm add dsh-img@latest 升级 |
| 贴图后模型答非所问 | 检查图里是否有旧指令文字——模型会把图中文字当上下文读 |
| 旧会话持续报 tool_calls 错 | 该会话已被旧 bug 毒化（append-only 日志），新建会话即可 |

适用边界（Limits）

本地工具各有其适用场景，超出边界效果会差，选对工具很重要：

| 工具 | 适合 | 不适合 |
|---|---|---|
| vision_trace | logo / 图标 / 线稿 / 简洁几何图形 | 彩色插画、照片、有渐变的图（potrace 是"位图→少色阶轮廓"工具，会压平成单一色块，无法保留连续色调） |
| vision_extract_foreground | 均匀背景（纯白 / 纯色底）的人/物 | 复杂背景、纹理背景（flood fill 抠不干净） |
| vision_pixel_diff | 同尺寸 UI 截图、设计稿还原度比对 | 尺寸差异大、内容完全不同的两张图（无对齐意义） |
| vision_ocr | 印刷体文字、屏幕截图文字 | 手写体、艺术字（识别率下降，可改用 analyze_image 走视觉模型） |

想要"彩色插画转 SVG"，potrace 不是正确工具（它不做彩色矢量化）。请改用专业矢量工具（Illustrator / Inkscape 的自动描摹），或直接交给视觉模型出设计稿再人工绘制。

English

A zero-build plugin for DeepSeek Harness. One command to install, one env var to configure, and your text-only model gains image understanding through analyze_image — plus key-free local tools (vision_crop, vision_pixel_diff, vision_colors, vision_ocr, vision_trace, vision_extract_foreground) and an ordered multi-backend failover chain.

cd ~/.dsh/profiles/web && pnpm add dsh-img --registry https://registry.npmjs.org
export ZHIPU_API_KEY=...   # free at https://open.bigmodel.cn/

License

MIT