dsh-free-vision

一句话定位

为 DeepSeek Harness 中只能看文字的模型补上"看图"能力：默认走千问、豆包、硅基流动三家提供商的免费视觉接口，把截图、报错、UI、文档转成模型能理解的文字证据，全程不需要用户手动配置 MCP 服务。

核心能力

• 注册 image_understand 工具，让纯文本模型接收本地路径、HTTP(S) URL、data URI 或粘贴的图片引用，按 PNG/JPEG/WebP/GIF 调用视觉 API 并返回文字证据
• 一键识别（默认开启）：在消息分发时把粘贴的图片替换成缓存好的文字描述，模型同一回合直接回答，无需先调工具再追问
• 注册 show_image 工具：让模型把找到的、生成的、截到的图片以内联卡片形式渲染进对话流，图片不进模型上下文
• 提供设置面板（Settings → Free Vision），表单由插件 schema 自动渲染，支持多 provider 一键切换、API Key 单独填、自定义 API 地址，保存到 ~/.dsh/free-vision.json 后下一次调用立即生效
• 提供 6 个模型提供商的切换：千问、豆包、硅基流动（OCR 专长）默认免费，智谱、腾讯混元、自建 OpenAI 兼容端点按量或自配

技术实现

• 语言: JavaScript (ESM，"type": "module")
• 关键依赖: @modelcontextprotocol/sdk（1.25.3，作为 MCP 客户端连 luma-mcp）、luma-mcp（1.7.1，本包内置的视觉引擎）、@deepseek-ai/schemastery（配置 schema 校验）
• 架构模式: 宿主通过 cordis.patch.yml 注入插件 → 插件用 apply(ctx, config) 在进程内 spawn luma-mcp 子进程 → 通过 stdio MCP 与之通信 → 用 ctx.tools.register 把通用视觉工具注册到宿主 → 配置保存走宿主 webServer 的 GET/POST /dsh-free-vision/config，配置变更会重连引擎
• 入口文件: dsh/index.js（host 端 ESM 入口，含 schema/路由/工具注册），client/client.js（浏览器端 UMD bundle，注入 settings.section）

适用场景

当用户用纯文本 DeepSeek 跑 DSH，但需要让模型"看懂"截图、报错、UI、文档时——例如调试时丢一张控制台报错图、写前端时丢一张设计稿、要 OCR 识别一段长截图——装上这个插件就能在不切换模型的情况下完成看图问答。免费额度对个人日常使用已经够用。

前置依赖与兼容性

安装方式

dsh plugin --profile web add dsh-free-vision

配置项

常见问题

Q: 装完就能用吗？

A: 还差一步：填一个 API Key。最简单的路径是阿里云百炼开通即送 50 万 token 限免额度，模型选 qwen3-vl-flash，把得到的 Key 配成环境变量 DASHSCOPE_API_KEY（或在 Settings → Free Vision 里直接粘贴）。保存后下一次调用立即生效，无需重启。

Q: 粘贴到对话里的图片，纯文本模型能看到吗？

A: 能，而且通常不需要再调工具。默认开启"一步识别"（describeAtDispatch）：分发时插件先把粘贴图片的描述文字塞给模型，模型在同一回合直接回答。image_understand 仍然保留，用于精确追问（如 OCR 逐字转写）。

Q: 支持哪些视觉模型？都免费吗？

A: 千问 Qwen3-VL-Flash（默认，限免 50 万 token）、豆包视觉（火山方舟新用户 20 万~50 万 token）、硅基流动 DeepSeek-OCR（OCR 免费）三家是免费档；智谱 GLM-4.6V、腾讯混元 HY-Vision、自建 OpenAI 兼容端点为按量或自配。

Q: 我能用国内代理或自建网关代替官方 API 地址吗？

A: 可以。在设置面板切到对应提供商卡片，下方"Base URL / API 地址"留空走官方默认；填上 https://my-proxy.example.com/v1 这种格式即可，引擎会自动拼接路径并避免重复。

Q: 为什么子进程要"直连"，不能挂代理？

A: 阿里云百炼、火山方舟、硅基流动都是国内端点，子进程启动时会主动剥离 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY 等代理环境变量；挂代理反而会拿到 502 错误。

Q: 工具名 image_understand 跟别人的插件冲突怎么办？

A: 在高级设置里把 toolName 改成别的即可；show_image 也能通过 showImageToolName 改名，改完保存立刻生效。

Q: 怎么完全卸载？

A: 配置文件在 ~/.dsh/free-vision.json（自定义路径可由 DSH_FREE_VISION_CONFIG_PATH 环境变量覆盖），删掉即清空所有 Key/地址覆盖；插件本体通过 dsh plugin --profile web remove dsh-free-vision 卸载。

Q: 引擎进程挂了怎么办？

A: 插件内置指数退避自动重连（dsh/index.js:648-664），最多 30 秒后会重连并重新注册工具；同时插件的 luma-mcp 版本被锁在 1.7.1，postinstall 钩子会在升级时自动重打幂等补丁。

上手难度

入门 — 装好插件、配一个免费 API Key，模型就能自己调工具看图；进阶能力（一键识别缓存、show_image 内联卡片、API 地址代理）都有合理默认，按需在高级设置里打开。

已知问题与限制

• 子进程会主动剥离 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY/http_proxy/https_proxy/all_proxy/no_proxy 八个代理环境变量（dsh/index.js:121-124），对挂代理才能联通的网络环境不可用。
• 仅支持 PNG/JPEG/WebP/GIF 四种图片格式（dsh/index.js:1046-1053），其他格式会抛 Unsupported image format。
• 视觉引擎内置 SSRF 防护，会阻止拉取 127.0.0.1 等回环地址（dsh/index.js:710-711, 1199），宿主内部 URL 必须先走粘贴图片引用再传，不允许直接拼。
• show_image 工具明确不支持远程 HTTP(S) 图片 URL（dsh/index.js:1517-1518），只接受本地路径、粘贴引用或 data URI。
• 图片读取受白名单限制：默认仅工作目录与用户主目录可读，其他路径需在 allowedDirs 用 ; 或 , 分隔添加（dsh/index.js:204-209）。
• 插件依赖 [email protected]，postinstall 钩子会在升级时对该依赖做幂等补丁；如果上游 luma-mcp 改了对应源码字符串，补丁会失败（scripts/patch-luma.mjs:46-53）。

🌐 English | 中文

DSH 免费视觉插件 — 让纯文本模型获得看图能力（截图、报错、UI 分析、OCR、文档），优先使用各平台免费视觉模型，零 MCP 配置。

Free vision plugin for DeepSeek Harness (dsh) — image understanding for text-only models using free-tier vision models, with zero MCP configuration.

为什么免费 / Why free

默认使用免费额度充足的提供商，无账单惊吓：

一张 1MB 截图 ≈ 2600 token，qwen 限免额度可分析约 19 万张图。 One 1MB screenshot ≈ 2,600 tokens ≈ $0.0006 on qwen; free quota covers ~190,000 images.

特性 / Features

• 零 MCP 配置 — 不用改 cordis.patch.yml、运行时不用 npx：视觉引擎（luma-mcp）作为本包依赖内置，进程内启动
• 单个通用工具 — image_understand（可用 config.toolName 改名）注册到 ctx.tools，每次请求模型都能看到
• 免费优先、多提供商 — 千问 / 豆包 / 硅基流动免费档开箱即用；智谱 / 混元 / custom 可切换
• 每个 Provider 可覆盖 API Base URL — 内置 Provider 可指向代理、API Gateway、本地服务或任意 OpenAI 兼容端点，无需改成 custom
• 直连 — 子进程剥离代理环境变量，国内 API 直连（带代理会导致 502）
• 任务模式 — auto | general | ocr | ui | debug | describe；大图自动多裁剪保真
• 中英双语 — 工具描述与文档中英文都可用

安装 / Install

dsh plugin --profile web add dsh-free-vision

重启 dsh web 后，工具 image_understand 即可用。 Restart dsh web; the tool appears as image_understand.

设置界面 / Settings UI

重启 dsh web 后，打开 设置 → Free Vision 即可看到配置表单（API Key、提供商、 工具名等），由插件 schema 自动渲染。保存到 ~/.dsh/free-vision.json，下一次 调用立即生效，无需重启。

After restart, open Settings → Free Vision — a form for every config option, saved to ~/.dsh/free-vision.json, effective on the next tool call.

配置 / Configuration

- id: free-vision
  name: 'dsh-free-vision'
  config:
    apiKey: 'sk-xxxx'        # 可选：缺省回退到提供商环境变量
    baseURLs: {}             # 可选：按 Provider 覆盖 API Base URL，例如 { qwen: 'https://my-proxy.example.com/v1' }
    modelProvider: qwen      # qwen | volcengine | siliconflow | zhipu | hunyuan | custom
    modelName: qwen3-vl-flash # 可选模型覆盖
    toolName: image_understand # 工具公开名（冲突时可改名）
    maxTokens: 8192
    temperature: 0.7
    multiCrop: true
    toolCallTimeoutMs: 200000
    lumaEnv: {}              # 传递给视觉引擎的额外环境变量

也可以只设置对应的环境变量（如 DASHSCOPE_API_KEY）。 Or just set the matching environment variable (e.g. DASHSCOPE_API_KEY).

覆盖 API 地址 / Base URL override

当 baseURLs 缺失或值为空时，继续使用该 Provider 的官方默认地址。

引擎会自动拼接 /chat/completions 并避免重复路径，因此以下写法都可用：

• https://my-proxy.example.com/v1
• https://my-proxy.example.com/v1/chat/completions

也可以使用环境变量：QWEN_BASE_URL、VOLCENGINE_BASE_URL、 SILICONFLOW_BASE_URL、ZHIPU_BASE_URL、HUNYUAN_BASE_URL （以及 custom 的 CUSTOM_BASE_URL）。

免费 Key 申请 / Free API keys

用法 / Usage

模型调用 image_understand 时传入：

• image_source（必填）：本地路径、HTTP(S) URL 或 data URI（PNG/JPG/WebP/GIF，≤10MB）
• prompt（必填）：对图片的问题 — 中英文均可
• task_type（可选）：auto | general | ocr | ui | debug | describe

工作原理 / How it works

dsh web → cordis 加载 free-vision → 进程内启动视觉引擎（版本锁定）
→ MCP 连接 → 注册 image_understand 到 ctx.tools
→ 模型调用工具 → 引擎预处理（压缩 / 多裁剪）→ 免费视觉 API（直连）
→ 返回文字证据

开发 / Development

npm install
node test-plugin.mjs   # 端到端冒烟测试（需要 API Key 环境变量）

许可证 / License

MIT — 封装 luma-mcp（MIT）与 MCP SDK（MIT）。免费额度数据来自各平台官方页面，可能变动，使用前请核实。