@aalongaa/dsh-tool-vision
面向模型的 DeepSeek Harness 视觉工具：通过任何兼容 OpenAI 的视觉 API 分析图像。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @aalongaa/dsh-tool-vision@2.1.0Tool Vision 以 @aalongaa/dsh-tool-vision 发布，当前版本为 2.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
给 DeepSeek Harness 装上"眼睛"的 OpenAI 兼容视觉理解插件。 智能体终于不用再靠猜了——虽然它猜得也不差。
@aalongaa/dsh-tool-vision 为 DeepSeek Harness 注册一个 vision 工具：把本地图片或远程图片丢给任意 OpenAI 兼容的视觉模型，拿回一句人话描述。
# 装进 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 之类的测试值，说明真实密钥没配上去。装好插件后，即使底层模型本身不支持图片输入，聊天框也可以直接粘贴/上传图片——插件自动放行图片附件，并遵守一条铁律：图片字节永不发给 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 → 差异率 + 热力图
三个值得知道的细节：
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 充当"眼睛"再合适不过：
模型下载： 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）
MIT —— 随便用。但如果你的智能体靠它写出了论文，记得在致谢里提一嘴。 （开玩笑的，不提也行，它不会记仇。）