图像理解插件yyking12/dsh-vision

dsh-vision · 开眼

给 DeepSeek Harness 的 Agent 装上眼睛：让不支持图片的模型也能“看见”图片。
仓库名：dsh-vision · 插件包名：dsh-tool-vision（保持兼容，安装名不变）

让 DeepSeek Harness 里的 Agent 看懂图片：注册一个 analyze_image 工具，把本地图片（或图片 URL）发给你自己配置的 OpenAI 兼容视觉模型（任何提供商：OpenAI、通义千问 Qwen-VL、智谱 GLM-4V、硅基流动、本地 vLLM / Ollama 等），返回模型的文字描述。

它是干什么的？

DeepSeek Harness 里默认的模型通常不接受图片输入（宿主会直接拒绝带 image 块的消息）。这个插件通过三条途径让 Agent 依然能看图：

1. analyze_image 工具：告诉 Agent「用户提到图片时调用我」，插件把图片发给你自己配置的视觉模型（OpenAI 兼容接口），把模型返回的文字描述带回对话——Agent 就这样“看见”了图片；
2. 📷 发图按钮 + 粘贴/拖放：composer 里选图 / Ctrl+V 粘贴 / 拖放图片，自动上传为会话附件并把 📎 图片附件:  纯文本标记放进输入框——消息不携带 image 块，绕开宿主对模型图片能力的检查，非多模态模型也能发送图片；
3. 三种图片来源：本地文件路径、http(s) URL、会话图片附件（attachment_id）。

- 模型提供商完全由你配置：baseURL + model + apiKey 三件套，随你指定
- 图片以 data URL 发送（image_url 内容块），走标准 chat/completions 协议
- 支持 png / jpg / jpeg / gif / webp / bmp，单张上限默认 20 MiB
- 支持本地文件路径或 http(s) 图片 URL（URL 同样受体积上限约束）
- GUI 设置页：设置 → 图像理解，可视化配置服务商 / 端点 / 模型 / Key，一键测试连接

支持的服务商

任何兼容 OpenAI chat/completions 接口的视觉模型都能接入——插件只依赖 baseURL + model + apiKey，不绑定任何厂商。设置页内置以下预设（也可选「自定义」手填任意端点）：

| 预设 | baseURL | 示例模型 |
| --- | --- | --- |
| OpenAI | https://api.openai.com/v1 | gpt-4o-mini |
| 阿里云百炼 (DashScope) | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-vl-max |
| 硅基流动 | https://api.siliconflow.cn/v1 | Qwen/Qwen2.5-VL-72B-Instruct |
| 智谱 AI | https://open.bigmodel.cn/api/paas/v4 | glm-4v-flash |
| 本地 Ollama | http://localhost:11434/v1 | llava |
| 自定义 | 任意 OpenAI 兼容端点 | 任意 |

其它常见的 OpenAI 兼容供应商（vLLM / Xinference / Moonshot / 阶跃星辰 / MiniMax 等）直接选「自定义」填端点与模型即可；只要服务商提供 /chat/completions 且支持 image_url 内容块就能用。

原理

- 本包是标准 Cordis 插件（inject: ["tools", "webServer"]），在 apply 里用 defineTool 注册 analyze_image 工具：
- 参数：path（图片路径或 URL）、prompt（可选提问）
- 执行：取图 → base64 → POST /chat/completions（image_url 块）→ 返回 { description, model, cached }
- 结果以纯文本渲染给模型，Agent 即可“看见”图片内容
- 配置优先级（每次调用实时解析，热重载）：patch config 字面量 → 凭据服务（ctx.credentials，.credentials.yaml，引用名 VISION_API_KEY / VISION_BASE_URL / VISION_MODEL / VISION_DETAIL）→ 环境变量 → 内置默认值
- 浏览器设置页（client 半身）注册在 settings.section（id: vision），通过同源 HTTP 路由 /api/vision-config（host 半身经 webServer 注册）读写配置与测试连通性

特性（v0.6.0）

- 📷 发图按钮：composer 工具栏新增「📷 发图」按钮 —— 选图 → 上传为会话附件 → 自动把 📎 图片附件:  标记放入输入框。发送的是纯文本（不携带 image 块），因此不受「模型必须支持图片」的发送检查限制；Agent 见到标记会自动调用 analyze_image 看图（无需切换模型，非多模态模型也能“看”图）
- 粘贴 / 拖放图片同样走标记管线：在输入框内 Ctrl+V 粘贴图片、或把图片拖进页面，会自动上传并转为附件标记（宿主对不支持图片的模型会拒绝原生 image 块，标记管线绕开该限制）
- GUI 设置页：设置 → 图像理解。服务商预设（OpenAI / 阿里云百炼 / 硅基流动 / 智谱 / 本地 Ollama / 自定义）、baseURL / 模型 / detail / API Key 表单、保存（写凭据文件，立即生效）、测试连接（16x16 图验证端点 + Key，兼容 qwen-vl-max 等要求宽高 > 10px 的模型）
- 三种图片来源：本地文件路径 / http(s) URL / 会话图片附件（attachment_id）
- 结果缓存：同一张图 + 同一 prompt + 同一模型只调用一次 API。缓存键 = sha256(图片字节) + prompt + model + detail + baseURL，默认最多缓存 64 条（LRU 逐出），改图、改问题、换模型/端点都会自然绕过缓存
- 自动重试：HTTP 429 / 5xx / 瞬时网络错误按指数退避重试（默认 2 次，2^n × 1s 封顶 10s），尊重 Retry-After 响应头；总时长受 timeoutMs 约束，取消信号随时可中断
- detail 控制：auto / low / high（OpenAI 语义），high 适合 OCR / 小字，low 省 token 更快
- URL 输入：path 直接传图片链接；Content-Length 与实读字节双重体积校验；MIME 优先取响应头 content-type
- 诊断友好：413 提示图片过大、401/403 提示检查 Key、404 提示检查 baseURL 是否重复加了 /v1 等

附件引用说明

「发图 / 粘贴」上传的图片只把 attachmentId 写进消息（纯文本），完整附件元数据（mediaType / bytes / width / height）由 host 半身在上传时持久化到 /dsh-tool-vision-refs.json，analyze_image 按 id 还原完整引用后从附件存储读取。删除该文件会导致历史标记无法再读图（重新上传即可）。

安装

作为本地插件直接放入 profile

把本包目录放进 ~/.dsh/profiles/web/plugins/，在 profile 的 package.json 里加一行
"dsh-tool-vision": "link:plugins\\dsh-tool-vision"（或用 dsh plugin --profile web add ），
并在 cordis.patch.yml 里启用（见下文）。重启后生效。

CLI dsh web（本 GUI）

1. 装进 web profile（DSH_HOME 默认 ~/.dsh）
DSH_HOME=~/.dsh dsh plugin --profile web add

2. 确认 cordis.patch.yml 里有启用行（上一步通常已写入；没有就手动加）：
- insert:
- id: vision
name: dsh-tool-vision

3. 重启 dsh web（Ctrl+C 后重新运行 npx @deepseek-ai/dsh web）

配置模型提供商

首选：GUI 设置页（设置 → 图像理解）：选服务商预设 → 填 API Key → 保存 → 测试连接。
保存写入凭据文件（.credentials.yaml），热重载立即生效，无需重启。

也可以手动配置，三种方式任选其一（字面量配置优先级最高）：

1. 环境变量（最简单，重启 dsh web 前在终端里 export）

export VISION_API_KEY="sk-你的密钥"
export VISION_BASE_URL="https://api.openai.com/v1"   # 换成你的提供商端点
export VISION_MODEL="gpt-4o-mini"                    # 换成你的视觉模型
可选：
export VISION_DETAIL="high"                          # auto / low / high
npx @deepseek-ai/dsh web

2. 凭据文件（API Key 热重载，改完无需重启）

在 /.credentials.yaml（即 ~/.dsh/.credentials.yaml）里加一行：

VISION_API_KEY: sk-你的密钥

VISION_BASE_URL / VISION_MODEL / VISION_DETAIL 仍走环境变量或第 3 种方式。

3. patch 配置（cordis.patch.yml 的 insert 条目）

- insert:
- id: vision
name: dsh-tool-vision
config:
baseURL: https://api.openai.com/v1
model: gpt-4o-mini
apiKey: sk-你的密钥   # 或省略，走凭据服务/环境变量
detail: auto          # auto / low / high
maxImageBytes: 20971520
maxTokens: 1024
timeoutMs: 120000
maxRetries: 2         # 失败重试次数，0 关闭
retryBaseDelayMs: 1000
cacheSize: 64         # 结果缓存条目数，0 关闭

注意：GUI 的设置页只对少量内置 namespace 开放，第三方插件的 config 请用上面三种方式配置。

使用

重启后直接在对话里给 Agent 图片路径即可，例如：

看一下 C:\Users\me\Pictures\截图.png，里面写了什么？

Agent 会自动调用 analyze_image 并把描述带回对话。也可以要求特定分析：

分析 screenshots/bug.png，重点是报错信息。

看下 https://example.com/foo.png 里有什么。

插件生效前 / 调试用：独立命令行

VISION_API_KEY=sk-xxx VISION_MODEL=qwen-vl-max node plugins/dsh-tool-vision/scripts/vision.mjs 图片.png "图片里有什么文字？"

支持本地路径与 URL、自动重试、--json 输出完整响应；--detail high 可调细节等级。
可用它先验证提供商配置是否正确。

常见问题

- vision has no API key for "VISION_API_KEY"：三种方式都没配到 Key，按上文配置其一。
- vision API error (HTTP 4xx)：端点或 Key 不对；用 --json 看提供商返回的完整错误。401/403 查 Key，404 查 baseURL（是否重复拼了 /v1），413 换小图或调低 maxImageBytes。
- vision request to ... failed：端点不可达或超时，检查 VISION_BASE_URL 与网络（瞬时故障会自动重试）。
- unsupported image type：只支持 png/jpg/jpeg/gif/webp/bmp。

☕ 请我喝咖啡

如果这个插件帮到了你，欢迎请我喝杯咖啡 ☕ 你的支持是持续维护的最大动力：

| 微信 | 支付宝 |
| --- | --- |
|  |  |

扫码后即可转账，金额随意，心意无价 ❤️