dsh-vision

August 15, 2026 · View on GitHub

给 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 粘贴 / 拖放图片，自动上传为会话附件并把 📎 图片附件: <id> 纯文本标记放进输入框——消息不携带 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示例模型
OpenAIhttps://api.openai.com/v1gpt-4o-mini
阿里云百炼 (DashScope)https://dashscope.aliyuncs.com/compatible-mode/v1qwen-vl-max
硅基流动https://api.siliconflow.cn/v1Qwen/Qwen2.5-VL-72B-Instruct
智谱 AIhttps://open.bigmodel.cn/api/paas/v4glm-4v-flash
本地 Ollamahttp://localhost:11434/v1llava
自定义任意 OpenAI 兼容端点任意

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

原理

  • 本包是标准 Cordis 插件（inject: ["tools", "webServer"]），在 apply 里用 defineTool 注册 analyze_image 工具：
    • 参数：path（图片路径或 URL）、prompt（可选提问）
    • 执行：取图 → base64 → POST <baseURL>/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 工具栏新增「📷 发图」按钮 —— 选图 → 上传为会话附件 → 自动把 📎 图片附件: <attachmentId> 标记放入输入框。发送的是纯文本（不携带 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 次，2n×1s2^\text{n} \times 1\text{s} 封顶 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_HOME>/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 热重载，改完无需重启）

在 <DSH_HOME>/.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。

☕ 请我喝咖啡

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

微信支付宝
微信收款码支付宝收款码

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