dsh-free-vision · DSH 免费视觉插件

English | 中文

dsh-free-vision 是 DeepSeek Harness（DSH）的免费视觉插件：让纯文本模型获得看图能力（截图、报错、OCR、UI 分析、文档），优先使用各平台免费视觉模型，自带设置界面，零 MCP 配置。

功能特性

免费优先，多提供商

开箱即用免费档模型，无需任何配置即可切换：

提供商	模型	免费额度	API Key 环境变量	申请链接
千问（默认）	Qwen3-VL-Flash	百炼限免（激活送 50万 token）	DASHSCOPE_API_KEY	阿里云百炼
火山豆包	Doubao 视觉模型	火山免费 token（20万起，可申请 50万）	VOLCENGINE_API_KEY	火山方舟
硅基流动	DeepSeek-OCR	OCR 免费调用	SILICONFLOW_API_KEY	硅基流动
智谱	GLM-4.6V	按量	ZHIPU_API_KEY	智谱开放平台
混元	HY-Vision	按量	HUNYUAN_API_KEY	腾讯云 TokenHub
自定义	任意 OpenAI 兼容	—	CUSTOM_API_KEY + CUSTOM_BASE_URL + CUSTOM_MODEL_NAME	—

一张 1MB 截图 ≈ 2600 token，千问限免额度可分析约 19 万张图。

设置界面（Settings → Free Vision）

插件注册独立的设置分区，所有配置可视化操作、保存即生效（下一次调用立即使用新配置，无需重启）：

• 提供商卡片：点击即切换，免费家带「FREE 免费」徽章；
• 每家独立 Key 槽：per-provider keys，配一次永久保留，切换提供商自动用对应 Key；
• 申请链接：卡片下方直达各家免费 Key 注册页；
• 实时状态行：显示当前生效的提供商与 Key 来源（已保存 / 环境变量）；
• 高级设置：模型名、工具名、最大 token、温度、多裁剪、超时、额外环境变量；
• 无 Key 降级：未配置 Key 时插件照常加载，顶部黄色横幅提示，工具调用给出友好指引，绝不报插件错误。

零 MCP 配置

视觉引擎（luma-mcp）作为插件自身依赖版本锁定，进程内启动——不需要在 cordis.patch.yml 配任何 MCP 服务器，也没有第二个「谁在识图」的通道。

工程化保障

• 崩溃自动重连：引擎进程异常退出后指数退避自动恢复；
• 国内 API 直连：子进程剥离代理环境变量（带代理会导致 502）；
• 双模型支持工具：image_understand 单工具覆盖 OCR / UI / debug / describe 任务；
• CI + 13 项单元测试，随版本发布。

安装

DSH 插件通过 dsh plugin 命令安装进 profile（dsh web 对应 web profile）。

方式一：从 npm 安装（推荐）

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

装完重启 dsh web，打开 设置 → Free Vision：

1. 点选提供商卡片（免费家带徽章）；
2. 在联动区粘贴该家的 API Key（或直接点申请链接去注册）；
3. 点「保存」——状态行变绿，模型即可用 image_understand 识图。

首次安装提示 ERR_PNPM_IGNORED_BUILDS：pnpm 拒绝依赖的构建脚本时，按提示把 luma-mcp（sharp 原生依赖）加入 profile 的 pnpm-workspace.yaml allowBuilds 后重新安装。

方式二：从 GitHub 仓库安装（开发调试）

git clone https://github.com/FuzzySoul/dsh-free-vision.git
cd dsh-free-vision
npm install
# 装进 web profile（本地路径）
cd ~/.dsh/profiles/web
pnpm add "file:F:/code/Code/simple/dsh-free-vision"  # Windows 跨盘符请用 tarball：pnpm add <npm 包名>@latest

验证与卸载

安装成功后重启 dsh web，设置 → Free Vision 出现配置卡片即生效；也可用 dsh --profile web --dump-config 确认插件配置层已挂载。

卸载：dsh plugin --profile web remove dsh-free-vision，然后重启 dsh web。

技术细节见 docs/ARCHITECTURE.md。

配置说明

设置界面 vs 配置文件

设置界面保存到 ~/.dsh/free-vision.json（推荐在界面操作，字段含义相同）：

{
  "keys": { "qwen": "sk-...", "volcengine": "" },
  "modelProvider": "qwen",
  "modelName": "",
  "toolName": "image_understand",
  "maxTokens": 8192,
  "temperature": 0.7,
  "multiCrop": true,
  "toolCallTimeoutMs": 200000,
  "lumaEnv": {}
}

Key 解析优先级：keys[当前提供商] > 旧版顶层 apiKey（自动迁移）> 提供商环境变量。

常见问题

设置里显示「未配置 API Key」，但我明明能用？

请先重启 dsh web 并确认状态行。早期版本存在双通道（手动 mcp-luma 配置 + 插件）导致状态不同步，0.5.0 起已统一为单一通道，设置界面实时显示实际生效的提供商与 Key 来源。

调用报 502？

dashscope 等是国内服务，必须直连。插件已自动剥离子进程的代理环境变量；如果你在系统环境变量中配置了代理，请勿对插件单独设置 HTTP_PROXY。

图片报「Unsupported image format」？

luma 按文件扩展名识别格式，无扩展名的附件请复制为 .png / .jpg 后传入，或使用 http(s) URL / data URI。

如何更换提供商？

设置界面点卡片即可切换；每家 Key 独立保存，切过去自动生效。

从源码开发

npm install
npm test              # vitest 单元测试（13 项）
node test-plugin.mjs  # 端到端冒烟测试（需要提供商 API Key 环境变量）

来源与版权

部分	来源	版权
dsh-free-vision 插件本体	作者 FuzzySoul 个人开发	MIT
视觉引擎 luma-mcp	JochenYang/luma-mcp	MIT
MCP SDK	modelcontextprotocol	MIT

友情链接

• awesome-dsh-plugin —— DSH 插件精选列表（本插件收录入口）；
• dsh-market —— DSH 内置可视化插件市场；
• liustack/modlens —— 另一款 DSH 视觉插件；
• DeepSeek Harness —— DSH 官方仓库。

Star 历史