dsh-vision-adapter

Readme

# dsh-vision-adapter

> **English:** [README.en.md](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 = 你选的厂商），选中即可拖图识别。

## 安装（一键）

```bash
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](LICENSE)