dsh-glm-vision

Readme

# dsh-glm-vision

**GLM 视觉模型** 插件：把智谱 `glm-4.6v` 系列视觉模型以独立供应商路由的形式接进 DeepSeek Harness，并提供一个 `glm_vision` 工具，让 **DeepSeek 等文本主模型「动脑」、GLM「当眼睛」**。

1. **注册供应商路由 `glm-vision`**（openai-completions 直连 `https://open.bigmodel.cn/api/paas/v4`）
   - 内置模型目录：`glm-4.6v` / `glm-4.6v-flash`（永久免费）/ `glm-4.6v-flashx` / `glm-4.5v` / `glm-5v-turbo`
   - 每个模型都声明 `input: [text, image]`，可直接处理图片输入
   - 路由注册后：模型选择器可选、任何插件可用 `ctx.llm.stream({ provider: 'glm-vision', model: 'glm-4.6v', messages: [...含 image 块...] })` 调用
2. **注册模型可见工具 `glm_vision`**
   - 参数：`image`（本地图片路径）、`question`（可选）、`model`（可选）、`maxTokens`（可选）
   - 流程：读文件 → 存入附件服务 → 图片块进 GLM → 返回文字描述
   - 主模型无需支持图片输入即可用它看图

## 安装

- 已安装 DeepSeek Harness 本体（`@deepseek-ai/dsh`），命令行里有 `dsh` 命令
- 一个智谱开放平台（open.bigmodel.cn）的 API Key

### 安装插件

```powershell
# 从 GitHub 直接安装
dsh plugin --profile web add github:fightingFirefox/dsh-glm-vision
# 或者
dsh plugin --profile web add dsh-glm-vision
```

装完后插件自动加入 profile 的 bundles 层

### 配置 API Key

1. 到 https://open.bigmodel.cn 注册并创建 API Key
2. 在 DSH Web 的 **设置 → Models** 页面填写，或直接编辑 `$env:USERPROFILE\.dsh\.credentials.yaml`：

```yaml
ZAI_API_KEY: 你的智谱key（id.secret 两段式）
```

### 重启生效

```powershell
dsh web
```

## 配置

插件带有浏览器半边：**设置 → Plugins → Plugin config** 里会出现「GLM 视觉（智谱 bigmodel.cn）」卡片，可直接改这些字段（保存即生效，`registerTool`改动需重启）：

- `defaultModel` — glm_vision 缺省模型（下拉选择 5 个 GLM 视觉模型）
- `baseURL` — 接口地址（默认 `https://open.bigmodel.cn/api/paas/v4`）
- `apiKeyEnv` — 凭据引用名（默认 `ZAI_API_KEY`）
- `maxTokens` / `timeoutMs` — 输出上限（含思考预算）/ HTTP 超时
- `thinking` — 思考模式，一一对应智谱官方量（默认 `max` 最大深度）：
  - `max`：`thinking:{type:"enabled"}` + glm-5.x 系列附 `reasoning_effort:"max"`（官方默认推荐、深度推理，视觉最准）
  - `auto`：`thinking:{type:"enabled"}`（官方默认，模型自行判断）
  - `off`：`thinking:{type:"disabled"}`（直接作答，快但视觉准确率低，不建议视觉任务用）
- `registerTool` — 是否注册 `glm_vision` 工具
- `takeover` — 是否接管 DeepSeek 官方路由
- `systemPrompt` — 工具使用的系统提示词

也可以直接在 `settings.yaml` 里写：

```yaml
glm-vision:
  apiKeyEnv: ZAI_API_KEY          # 凭据引用
  baseURL: https://open.bigmodel.cn/api/paas/v4
  defaultModel: glm-4.6v          # glm_vision 缺省模型；免费额度建议 glm-4.6v-flash
  maxTokens: 8192
  registerTool: true
```

## 路由定位

`glm-vision` 路由定位为**视觉工具后端**：主要被 `glm_vision` 工具调用、或在模型选择器里选它做一次性的「带图问答」。**不支持带工具的多轮对话**，请用 DeepSeek 等主模型进行工具对话、需要看图时再调 `glm_vision`。

## GLM-vision 文本路由（glm_vision_router）

除视觉工具后端「glm-vision」外，插件还注册了一条「GLM 纯文本 + 视觉补充」路由 glm_vision_router（模型选择器里显示为「GLM-vision」）：

- 目录：启动时先用内置表立即显示，随后后台从智谱 GET /models 拉取刷新（模型页面也可点「获取可用模型」手动刷新）
- 每个模型都声明 input: [text, image] —— 含图会话里切到它不会被准入关卡拦下
- 图片块进入模型前被重写为 glm_vision 工具提示，所以纯文本 GLM 模型（glm-4.7 / glm-5.3 等）也能看图
- 支持工具调用多轮对话：模型可自主调 glm_vision 看图，工具结果会以 OpenAI 兼容格式回传

## 用法

- **工具方式（推荐）**：在会话里直接让模型用 `glm_vision` 分析图片（例如「用 glm_vision 看看 path/to/图片.png 里是什么」）。
- **路由方式**：在模型选择器里选「GLM 视觉（智谱）」下的模型，带图对话直接走 GLM。

## 独占视觉与共存

本插件**独占视觉**：请只保留 glm_vision 作为视觉能力来源。若检测到**其他视觉插件**（vision-router、modlens、dsh-vision 等），本插件**默认进入休眠**（不接管 deepseek-official、不注册 glm_vision 工具）并在日志告警：

> 「本插件暂未适配共存，可能出现调用问题甚至导致崩溃，请谨慎开启。」

若要强制启用（风险自负）：在设置卡的「功能开关」里把「共存检测（独占视觉）」关闭，重启生效；或卸载其他视觉插件。

## 接管 DeepSeek 官方路由

1. `cordis.patch.yml` 已禁用官方 `llm-deepseek` 行（接管所需；想恢复官方行，删掉对应条目即可）
2. 本插件启动后约 2 秒接管 `deepseek-official` 路由：
   - 模型目录/名称与官方一致（模型选择器仍显示 DeepSeek / DeepSeek-V4-Pro）
   - 路由声明 `input: [text, image]` —— DSH 的图片准入关卡（prompt/selectModel）放行
   - 文本流委托给重建的原生 DeepSeek 适配器（llm-deepseek 设置节 + credentials 的 `DEEPSEEK_API_KEY`）
   - 请求中的图片块（含 tool-result 嵌套）在委托前被重写为文本标记，提示模型调用 `glm_vision`（image 参数填附件 id）
3. `glm_vision` 工具 `image` 参数现在也接受附件 id（`sha256:...`）：从会话历史反查完整引用后直接送 GLM，无需先物化成文件
4. 设置卡片新增「接管 DeepSeek 官方路由」开关（默认开，改动重启生效）

典型会话流：选 DeepSeek-V4-Pro → 上传图片 → 准入通过 → 模型看到「已收到图片（附件 id：sha256:…）…请调用 glm_vision」→ 调用 `glm_vision(image='sha256:…')` → GLM-4.6V 返回文字描述 → 模型基于描述作答。

## 与其他路由的关系

本插件是独立路由 `glm-vision`，**不修改也不依赖** 已有的其他 LLM 供应商路由配置；可与其他文本模型路由共存、各司其职。