🖼️ dsh-tool-vision

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

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

它帮你做三件事

看 —— 单图 / 多图一次分析，本地文件或 URL 都行。
省 —— 图片自动缩放压缩（默认 1024px、JPEG 85%），token 省下来，钱包谢谢你。
记 —— 结果缓存，同一张图问第二遍不花钱。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      → 差异率 + 热力图

三个值得知道的细节：

上传的图片可以直接用附件 id 喂工具：聊天框里发的图，各工具的 source 参数可以直接传 sha256:... 形式的附件 id，插件会从会话里把图读出来——不用先把它落到磁盘再找路径。
主端点挂了自动降级：配置了 providers 后，vision_describe 会按顺序尝试，前面的失败自动换下一个，全部失败时返回每一家的原因。
产物自动落盘：标注图、裁剪图、热力图默认保存在 .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 —— 随便用。但如果你的智能体靠它写出了论文，记得在致谢里提一嘴。（开玩笑的，不提也行，它不会记仇。）

dsh-tool-vision

安装

源码

作者

说明文档