dsh-vision

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-vision-free-eyes

给 DeepSeek Harness（DSH）里的纯文本模型补上免费「眼睛」：GUI 直接贴图自动转译 + 磁盘图片识图工具 + 使用指引 skill。底层视觉走智谱 GLM 免费模型（glm-4v-flash），无需付费。

Eyes for text-only DeepSeek Harness agents: paste an image in the Web GUI and it just works — the image is transcribed by a free Zhipu GLM vision model before DeepSeek sees the text.

> ⚠️ **需要 GLM key（免费，但必须要有）**：识图走智谱免费模型 `glm-4v-flash`，需要去 [open.bigmodel.cn](https://open.bigmodel.cn) 注册获取免费 API key（格式 `id.secret`），配置为环境变量 `GLM_API_KEY` 或 `ZHIPU_API_KEY`（Windows 可直接 `setx GLM_API_KEY "你的key"`）。**没有 key 时贴图转译会失败**（对话中显示 `[图片转译失败: 未找到 GLM_API_KEY ...]`）。key 只存在于你的环境，不会进代码或仓库。

## 特性

| 组件 | 作用 |
|---|---|
| **deepseek-vision 路由**（`packages/vision-route`） | 注册新模型组「DeepSeek + 自动识图」：声明图像输入（`inputModalities: ['text','image']`），贴图在请求流里被 GLM 自动转译成文字，再委派给真正的 DeepSeek 适配器 |
| **vision 工具**（`packages/vision-tool`） | 模型可对磁盘上的图片路径直接调用的 `vision(image, question)` 工具（直连 GLM API，无需外部 CLI） |
| **vision-free-eyes skill**（`skill/`） | 教模型「何时 / 怎么用」视觉能力的指令文件 |

- 免费默认：智谱 GLM 免费通道（`glm-4v-flash` → `glm-4.6v-flash` → `glm-4.1v-thinking-flash` 自动降级链），只需一个免费申请的 GLM key。
- 官方 DeepSeek 路由**完全不动**：纯文本对话零开销、零改动；贴图时在模型选择器里切到「DeepSeek + 自动识图」即可。
- 无重启热生效：插件行写入 profile 的 `cordis.patch.yml` 后由 `watchUserPatches` 实时重放（见安装步骤；Windows 上插件路径必须用 `file:///` URL）。
- 优雅降级：某个图片转译失败时替换为 `[图片转译失败: ...]` 文本，对话不卡死。

## 架构

```
用户贴图/截图
   │
   ▼
DSH Web GUI 预检（检查所选模型的 inputModalities）
   │  ← deepseek-vision 路由声明了 ['text','image']，放行
   ▼
deepseek-vision 适配器（vision-route）
   │  拦截请求，把每个 { type:'image', attachment } 块：
   │    readImage(ref) → base64 → GLM chat/completions → 文字描述
   │  替换成 { type:'text', text:'[图片转译] …' }
   ▼
真正的 DeepSeek 适配器（deepseek-official，纯文本）
   │
   ▼
DeepSeek 基于文字作答
```

```
磁盘上的图片文件
   │
   ▼
模型调用 vision 工具（vision-tool）
   │  直连 GLM API（glm-4v-flash 降级链 + 进程内缓存）
   ▼
文字描述 → 模型整合进回答
```

## 安装

### 前提

- DeepSeek Harness `0.1.0-rc.5` / `rc.6`（本方案在 rc.5 上实测通过）
- 智谱 GLM 免费 key（[open.bigmodel.cn](https://open.bigmodel.cn) 注册即得，格式 `id.secret`），配置方式（任选其一）：
  - 环境变量 `GLM_API_KEY` 或 `ZHIPU_API_KEY`；或
  - Windows 用户环境变量（`setx GLM_API_KEY "..."`，插件会自动读注册表 `HKCU\Environment`）

### 通过 npm 安装（推荐）

两个包发布到 npm 后（`dsh-vision-free-eyes` + `dsh-vision-proxy-route`）：

```sh
dsh plugin --profile web add dsh-vision-free-eyes dsh-vision-proxy-route
```

`dsh plugin add` 会安装包并写入 profile 的 `dsh.profile.bundles`，重启 `dsh web`（或刷新页面）后生效。
包已装入 profile 的前提下，也可以直接在 profile 的 `cordis.patch.yml` 里用包名挂载（热生效，无需重启）：

```yaml
- insert:
    - id: dsh-vision-free-eyes
      name: dsh-vision-free-eyes
    - id: dsh-vision-proxy-route
      name: dsh-vision-proxy-route
```

### 手动安装（备选：未发布 / 本地目录）

1. 把 `packages/vision-tool` 和 `packages/vision-route` 放到你的机器上（例如 `D:\tools\`）。

2. 编辑 profile patch（`$DSH_HOME/profiles/web/cordis.patch.yml`，即 `C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml`），追加：
   ```yaml
   - insert:
       - id: tool-vision
         name: file:///D:/tools/vision-tool/index.js
       - id: vision-proxy-route
         name: file:///D:/tools/vision-route/index.js
   ```
   > ⚠️ **Windows 必须用 `file:///` URL 形式**：DSH 的 Loader 用原生 `import()` 加载插件行，`D:/xxx` 盘符路径会报 `ERR_UNSUPPORTED_ESM_URL_SCHEME`。Linux/macOS 用 `/abs/path/to/index.js` 即可。完整模板见 [`cordis.patch.example.yml`](cordis.patch.example.yml)。

3. 安装 skill（可选但推荐）：把 `skill/vision-free-eyes/` 复制到 `$DSH_HOME/skills/`（即 `C:\Users\<你>\.dsh\skills\`）。

4. 生效方式（二选一）：
   - **热生效**：patch 由 `watchUserPatches` 实时重放，改完等 1~2 秒即可；刷新浏览器页面让模型选择器加载新组。
   - 或重启 `dsh web`（修改插件代码后必须重启，Loader 对同名模块复用旧导出）。

5. 验证：
   ```sh
   dsh --profile web --dump-config | grep -A2 vision
   ```
   应看到两个插件行；浏览器刷新后模型选择器出现「DeepSeek + 自动识图」。

## 使用

1. 聊天框右下角**模型选择器**选 **「DeepSeek + 自动识图」**（原 DeepSeek 组保留不动）。
2. **直接粘贴图片 / 截图**并附带问题，或给出图片文件路径。
3. DeepSeek 基于转译文字作答。

`vision` 工具（任何路由都可用）：让模型"看一下 `D:\xxx\screenshot.png`"即可，或直接告诉模型图片路径。

## 配置

### vision-route（`packages/vision-route/index.js`）

| 常量 | 默认 | 说明 |
|---|---|---|
| `API_URL` | `https://open.bigmodel.cn/api/paas/v4/chat/completions` | GLM OpenAI 兼容端点 |
| `VISION_MODELS` | `glm-4v-flash → glm-4.6v-flash → glm-4.1v-thinking-flash` | 转译降级链 |
| `TRANSCRIBE_TIMEOUT_MS` | `60000` | 单次转译超时 |
| `MAX_IMAGE_BYTES` | `15MB` | GLM 单图上限 |
| `PROMPT_BASE` | 中文结构化描述提示词 | 可改（如改成纯段落描述） |
| 缓存 | 按 `attachmentId` 进程内缓存，上限 200 条 | 同图只转译一次 |

### vision-tool（`packages/vision-tool/index.js`）

| 环境变量 / config | 默认 | 说明 |
|---|---|---|
| `GLM_API_KEY` / `ZHIPU_API_KEY` | — | GLM key（Windows 也自动读注册表） |
| config `apiKeyEnv` | `GLM_API_KEY` / `ZHIPU_API_KEY` | 自定义 key 的环境变量名（可传数组） |
| config `no_cache` | `false` | 跳过进程内结果缓存，强制重新请求 |

## 兼容性

- 实测：DSH `0.1.0-rc.5`（Windows）。
- 设计兼容：rc.6（与 dsh-vision-proxy 相同的公开缝：`ctx.llm.registerAdapter` / `resolveModel.inputModalities` / `ctx.llm.registration(provider).adapter` / `ctx.attachments.readImage`）。
- ⚠️ 这些是 DSH 的**半稳定插件缝**，后续大版本可能变动；升级 DSH 后若失效，优先检查上述 API 是否改名。

## 隐私

- 图片字节会上传到智谱服务器（open.bigmodel.cn）进行转译。
- 未配置任何 key 或转译失败时，会以 `[图片转译失败: ...]` 占位并继续对话，不会静默卡死。
- 会话历史中只存转译后的文字，不存图片字节（DSH 附件存储除外）。

## 致谢

- 智谱 GLM 免费视觉模型（glm-4v-flash 系列）。
- DeepSeek Harness 插件体系（profile patch / `watchUserPatches` / `ctx.llm`）。

## License

[MIT](LICENSE)