dsh-vision-adapter

English: README.en.md · 中文: 本页

给 DeepSeek Harness（DSH） 加视觉能力的插件：装完就能拖图识别——图片交给视觉模型识别、文字交给 DeepSeek 推理，聊天入口完全不变。

这是 DSH（DeepSeek Harness）专属插件，不是通用 OpenAI 客户端工具。要求 DSH Web 界面（dsh web）。

效果

装好后，DSH 的 设置 → 视觉 里会出现一个可视化设置页：

1. 下拉选一个视觉厂商（服务地址、模型自动填好）；
2. 在 API Key 框粘贴你的 Key（默认小眼睛隐藏，点眼睛可查看）；
3. 点「保存并应用」。

保存后，聊天输入框右下角的模型下拉里会出现 DeepSeek V4 Pro 视觉（X） 和 DeepSeek V4 Flash 视觉（X） 两个模型（X = 你选的厂商），选中即可拖图识别。

安装（一键）

dsh plugin --profile web add dsh-vision-adapter

然后重启 DSH 生效。

内置厂商预设（8 家）

选厂商即可，接口地址和模型名都已预设好，只需粘贴你的 API Key：

视觉厂商	视觉模型（预设）	服务地址（预设）	保存到凭据
Kimi（月之暗面）	kimi-k3	https://api.moonshot.cn/v1	VISION_API_KEY
智谱 GLM	glm-4v-flash	https://open.bigmodel.cn/api/paas/v4	ZHIPU_API_KEY
通义千问	qwen-vl-plus	https://dashscope.aliyuncs.com/compatible-mode/v1	DASHSCOPE_API_KEY
OpenAI	gpt-4o-mini	https://api.openai.com/v1	OPENAI_API_KEY
Google Gemini	gemini-2.0-flash	https://generativelanguage.googleapis.com/v1beta/openai	GEMINI_API_KEY
豆包（火山方舟）	doubao-1.5-vision-pro	https://ark.cn-beijing.volces.com/api/v3	ARK_API_KEY
MiniMax（海螺）	MiniMax-VL-01	https://api.minimax.chat/v1	MINIMAX_API_KEY
阶跃星辰	step-1v	https://api.stepfun.com/v1	STEPFUN_API_KEY

API Key 怎么填：直接粘贴该厂商的明文 Key 即可。保存时插件会把 Key 安全写入 DSH 凭据（~/.dsh/.credentials.yaml，只存引用名，不落盘到设置文件），并显示「已配置 / 缺失」状态。已配置后留空保存即可沿用。

配置（可视化）

1. 重启后打开 设置 → 视觉；
2. 「视觉厂商」下拉选一个，服务地址与模型自动填好；
3. 「API Key」粘贴你的 Key（默认隐藏，点小眼睛查看）；
4. 「输出语言」选中文或 English；
5. 点「保存并应用」。

高级区可改 DeepSeek 文本后端（模型名 / 服务地址 / Key 引用），默认 deepseek-v4-pro + DEEPSEEK_API_KEY。

模型说明

每个视觉厂商下有两个模型，对应两种 DeepSeek 文本推理后端：

• DeepSeek V4 Pro 视觉（X） → 文字走 DeepSeek V4 Pro
• DeepSeek V4 Flash 视觉（X） → 文字走 DeepSeek V4 Flash

在设置里切换厂商，模型名会同步更新（选智谱就显示智谱，选 MiniMax 就显示 MiniMax）。

原理

图片 ──► 视觉模型(Kimi/智谱/千问/OpenAI/Gemini/豆包/MiniMax/阶跃星辰) ──► 文字描述
文字 + 描述 ──► DeepSeek ──► 回复

插件在 DSH 内部起一个进程内 HTTP 桥，并把选中的视觉模型注册为 llm-pi-ai 提供方（增量合并，不覆盖其它插件/用户已有的视觉桥）。图片由视觉模型描述成文字，再把「文字 + 描述」交给 DeepSeek 推理。

保留的细节

• 图片描述缓存：同一张图只调用一次视觉模型；
• 限流退避重试：视觉接口 429 / 并发限制自动退避重试；
• 兼容修复：developer→system 角色归一化、max_completion_tokens→max_tokens 等；
• 明文 Key 安全存储：设置页粘贴的 Key 自动转入 DSH 凭据文件，不留在设置里。

常见问题

Q：装完没看到「设置 → 视觉」或模型？ 重启 DSH（dsh plugin add 只改配置，插件在启动时挂载）。

Q：识别时 401？ API Key 没配置或配错（看设置页「已配置 / 缺失」状态）；或该 Key 已过期，去对应厂商控制台换新。

Q：识别时 429？ 该视觉厂商免费额度限流。插件已内置退避重试 + 图片缓存；仍频繁出现请给该厂商充值提额，或换额度更高的厂商。

Q：想加别的视觉厂商？ 改插件里 src/config.js 的 PROVIDERS 即可（加一项预设：接口地址、模型、凭据引用名）。

License

MIT