dsh-img

给纯文本模型装上眼睛，并升级成完整的本地视觉工具链 · Give text-only models eyes — a DeepSeek Harness plugin that bridges any text-only coding agent to a vision API, plus a set of local, key-free pixel tools (crop / pixel-diff / colors / 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