🖼️ dsh-tool-vision

给 DeepSeek Harness 装上"眼睛"的 OpenAI 兼容视觉理解插件。 智能体终于不用再靠猜了——虽然它猜得也不差。

@aalongaa/dsh-tool-vision 为 DeepSeek Harness 注册一个 vision 工具：把本地图片或远程图片丢给任意 OpenAI 兼容的视觉模型，拿回一句人话描述。

它帮你做三件事

1. 看 —— 单图 / 多图一次分析，本地文件或 URL 都行。
2. 省 —— 图片自动缩放压缩（默认 1024px、JPEG 85%），token 省下来，钱包谢谢你。
3. 记 —— 结果缓存，同一张图问第二遍不花钱。AI 也怕重复劳动。

安装

# 装进 dsh 的 web profile（装之前记得先停掉正在跑的 dsh）
npx @deepseek-ai/dsh plugin --profile web add @aalongaa/dsh-tool-vision

# 启动
npx @deepseek-ai/dsh web

装完打开 Web 设置 → 插件 → 视觉理解，就能看到配置卡片和智能检测到的配置文件路径。

不想用了？先停掉 dsh，然后卸载：

npx @deepseek-ai/dsh plugin --profile web remove @aalongaa/dsh-tool-vision

配置

配置从哪里来？

插件会从三个地方读取配置，优先级从低到高（高优先级的会覆盖低优先级的同名项）：

| 优先级 | 来源 | 说明 | | --- | --- | --- | | 1（最低） | cordis.yml | 插件的 schema 默认值。一般不用管，放着就行 | | 2 | .dsh-tool-vision.json | 项目级配置文件，放在项目根目录（可用环境变量 DSH_TOOL_VISION_CONFIG 指定路径） | | 3（最高） | ~/.dsh/settings.yaml | dsh 的全局设置文件，Web 设置页里改的就是它 |

推荐做法：日常在 Web 设置页里改（第 3 层），想跟着项目走就写 .dsh-tool-vision.json（第 2 层）。两种都不配时，插件用默认值也能跑，只是会指向 OpenAI 官方接口。

完整配置项

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | apiKey | string | 无 | 视觉接口的 API 密钥（如 sk-xxx） | | baseUrl | string | https://api.openai.com/v1 | OpenAI 兼容的接口地址。用本地推理服务（如 LM Studio / Ollama / vLLM）就填 http://127.0.0.1:1234/v1 | | model | string | gpt-4o-mini | 视觉模型名称，如 minicpm-v-4_6 | | maxTokens | number | 1024 | 每次请求的最大输出 token 数 | | preprocess.enabled | boolean | true | 是否自动缩放压缩图片 | | preprocess.maxWidth / preprocess.maxHeight | number | 1024 | 缩放上限（像素） | | preprocess.quality | number | 85 | JPEG 压缩质量（1–100） | | preprocess.format | string | jpeg | 压缩格式：jpeg / png / webp / avif | | cache.enabled | boolean | true | 是否缓存分析结果 | | cache.dir | string | .cache/dsh-tool-vision | 缓存目录 | | cache.ttl | number | 无（不过期） | 缓存有效期（毫秒） | | artifactsDir | string | .dsh-tool-vision/artifacts | 视觉工具产物目录（标注图 / 裁剪图 / 热力图） | | liftProviders | string[] | ["deepseek-official"] | 哪些 provider 被"声明支持图片"（解除发图限制）。只放行列出的 provider，不污染第三方；["*"] 恢复全局放行 | | rewriteImages | boolean | true | 图片块在进模型前被改写成"调用 vision_describe"的文本标记——图片字节永不发给文本模型。用原生多模态模型做会话模型时建议关掉 | | providers | object[] | [] | vision_describe 的降级链：按顺序尝试，前面的挂了自动换下一个。每项 { baseUrl, apiKey?, model?, maxTokens? }，apiKey 缺省继承顶层 |

配置示例

在 ~/.dsh/settings.yaml 或 .dsh-tool-vision.json 里写：

tool-vision:
  apiKey: sk-xxx
  baseUrl: http://127.0.0.1:1234/v1
  model: minicpm-v-4_6
  maxTokens: 8192
  # 主端点挂了自动切到这个（本地 → 云端兜底）
  providers:
    - baseUrl: https://api.siliconflow.cn/v1
      apiKey: sk-cloud
      model: Qwen/Qwen2.5-VL-72B-Instruct

.dsh-tool-vision.json 支持 JSONC（带注释）。保存后每个字段上方自动带一行中英双语注释，不用猜"这行是干嘛的"：

{
  // apiKey —— 在这里填写 API 密钥（例如 sk-xxx） / put your API key here (e.g. sk-xxx)
  // baseUrl —— 在这里填写接口地址（OpenAI 兼容） / OpenAI-compatible endpoint base URL
  "baseUrl": "http://127.0.0.1:1234/v1",
  // model —— 在这里填写视觉模型名称 / vision model name
  "model": "minicpm-v-4_6"
}

常见坑

• 请求一直失败？ 检查 baseUrl 是不是默认的 https://api.openai.com/v1——如果你的网络访问不了 OpenAI，就把地址换成本地/可达的 OpenAI 兼容服务。插件启动时会打印一行诊断日志（[tool-vision] config: ...），一眼就能看到最终生效的配置。
• apiKey 是占位符？ 插件会警告配置里的 key 疑似是 test / placeholder / example 之类的测试值，说明真实密钥没配上去。
• 配置改完没生效？ 第 3 层（settings.yaml）是实时读取的，改完立即生效；第 2 层（JSON 文件）在插件启动时加载，改完需要重启 dsh。

使用

装好插件后，即使底层模型本身不支持图片输入，聊天框也可以直接粘贴/上传图片——插件自动放行图片附件，并遵守一条铁律：图片字节永不发给 DeepSeek。发图的那一轮，图片会被改写成一段"这里有一张图，请调用 vision_describe 查看"的标记，视觉工具链会自动挂载，DeepSeek 只负责基于工具读回来的文字继续干活，不会因为"模型不支持图片"而翻车。

插件默认只暴露一个零参工具 vision_activate，发图或首次调用后挂载完整的视觉工具链（保持工具面最小）：

| 工具 | 作用 | | --- | --- | | vision_describe | 看图问答 / 多图对比，返回文字描述（带缓存 + 多端点降级） | | vision_ground | 定位目标 → 返回原图像素坐标框 + 标注 PNG | | vision_crop | 按坐标裁剪出图，返回 PNG 路径 | | vision_diff | 两图逐像素对比：差异率 + 最差区域 + 热力图 PNG |

它们组成一个可验证的闭环：

vision_ground   source=ref.png target="发送按钮"     → {x1,y1,x2,y2} + 标注图
vision_crop     source=ref.png x1=.. y1=.. x2=.. y2=..  → 裁剪 PNG
vision_describe source=crop.png prompt="里面是什么？"    → 描述
vision_diff     original=ref.png candidate=impl.png      → 差异率 + 热力图

三个值得知道的细节：

1. 上传的图片可以直接用附件 id 喂工具：聊天框里发的图，各工具的 source 参数可以直接传 sha256:... 形式的附件 id，插件会从会话里把图读出来——不用先把它落到磁盘再找路径。
2. 主端点挂了自动降级：配置了 providers 后，vision_describe 会按顺序尝试，前面的失败自动换下一个，全部失败时返回每一家的原因。
3. 产物自动落盘：标注图、裁剪图、热力图默认保存在 .dsh-tool-vision/artifacts/，返回绝对路径，可继续喂给下一个工具。

提示：想完全离线，本地部署一个视觉模型

如果不想把图片交给云端 API，可以在自己电脑上跑一个 OpenAI 兼容的视觉模型，把 baseUrl 指到本地即可，零成本、不泄露图片、断网也能用。

部署方式二选一：

| 工具 | 特点 | 地址 | | --- | --- | --- | | LM Studio | 图形界面，下载模型一键启动，最省心 | https://lmstudio.ai | | llama.cpp | 命令行 / 服务端，轻量高效，适合折腾 | https://github.com/ggml-org/llama.cpp |

推荐模型：MiniCPM-V 4.6 Thinking（OpenBMB，Apache 2.0）

面壁智能联合清华 NLP 实验室开源的端侧多模态模型——专门以手机配置为标准训练，能同时理解图像和视频，给 DeepSeek 充当"眼睛"再合适不过：

• 仅 1.3B 参数，约 6GB 内存即可流畅运行，普通笔记本无压力
• 基于 SigLIP2-400M 视觉编码器 + Qwen3.5-0.8B 语言模型，支持 4x/16x 混合视觉 token 压缩
• 长思维链推理变体，复杂多模态推理、OCR、数学题表现更稳
• 官方适配 llama.cpp / Ollama / vLLM / SGLang 等推理框架

模型下载： Hugging Face · 项目主页

本地服务起好后，把 baseUrl 指向本地 OpenAI 兼容地址即可：LM Studio 用 http://127.0.0.1:1234/v1，llama.cpp 用 http://127.0.0.1:8080/v1，model 填模型名，其他照常。

开发

npm install
npm test          # 跑测试，全绿就对了
npm run build     # tsup 打包
npm publish       # 发版（记得先改 version）

License

MIT —— 随便用。但如果你的智能体靠它写出了论文，记得在致谢里提一嘴。 （开玩笑的，不提也行，它不会记仇。）