dsh-zhipu

Readme

# dsh-zhipu

智谱 BigModel 全家桶，一个插件接进 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH），
一把 `ZAI_API_KEY` 通吃：

| 能力 | 形态 | 说明 |
|---|---|---|
| **联网搜索** | `web_search` 内置工具（提供方 `zhipu-prime`） | `web_search_prime` MCP（`search_pro` 引擎），工具名不变 |
| **网页阅读** | `web_fetch` 内置工具（提供方 `zhipu-reader`） | `webReader` MCP，**服务端渲染**（JS 页面可读），本机不对目标 URL 发请求 |
| **视觉理解** | `vision_analyze` 工具（GLM-4.6V） | 8 个任务模式，镜像官方视觉 MCP 的专项系统提示词 |
| **贴图识别** | `agent/pre-step` 钩子 | 对话贴图自动转围栏包裹的文字描述，纯文本聊天模型无感 |

GLM Coding Plan 套餐内：搜索/阅读 MCP 每次调用抵扣 1.2 积分；GLM-4.6V 抵扣系数
Input 1.2 / Cached 0.3 / Output 2.7（约 GLM-5.3 的 1/6~1/9，非高峰半价）。

## 安装（消费者）

```bash
dsh plugin --profile web add github:<you>/dsh-zhipu     # GitHub 仓库
# 或已发 npm：
dsh plugin --profile web add dsh-zhipu
```

然后把包名加进 profile 的 bundle 列表（`~/.dsh/profiles/web/package.json`）：

```json
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-zhipu"] } }
```

bundle 自带接线（本包 `cordis.patch.yml`）：选定两个 web 提供方、点亮 `web_fetch`
（60s 预算）、插入插件行（`apiKeyEnv: ZAI_API_KEY`）。重启 `dsh web` 生效。

**前置**：`~/.dsh/.env` 里有 `ZAI_API_KEY=<你的key>`（GLM Coding Plan 的 key，与
Models 页 `zai-coding-cn` 同一把即可）。

**贴图/拖放图片必做**：在 `~/.dsh/settings.yaml` 的聊天模型条目上声明图片输入模态
（api-proxy 在消息入队前按此校验，不声明会被"当前模型不支持图片"拦下，钩子无机会
介入）：

```yaml
llm-pi-ai:
  providers:
    zai-coding-cn:
      models:
        - id: glm-5.3          # 你的默认聊天模型
          input: [text, image] # ← 加这一行（其余字段保留）
```

该声明的含义是"图片可进入对话流水线"——真正送进模型前由贴图钩子转成文字描述。
**勿**把这些模型加进插件的 `passthroughModels`（它们的 API 不收裸图）。

headless/其他 profile 同理（`--profile <name>`；headless 无拖放入口，声明可省）。

## 配置（可选，经用户 patch 层覆盖）

```yaml
# ~/.dsh/profiles/<name>/cordis.patch.yml
- id: zhipu
  config:
    apiKeyEnv: ZAI_API_KEY     # 或指向别的 credential ref
    # searchEngine: search_std
    # model: glm-4.6v          # 视觉模型
    # enableTool: false        # 去掉 vision_analyze 工具
    # enablePreStep: false     # 关闭贴图钩子（不外发贴图）
    # passthroughModels: []    # 原生吃图的聊天模型 id 列表；命中才跳过描述直通裸图
    # maxResponseChars: 10485760
```

回退 DeepSeek 搜索（用户 patch 层）：

```yaml
- id: web
  config:
    searchProvider: deepseek-official   # 并删掉 fetchProvider 键
- id: tool-web
  config:
    fetch: false
```

## 数据外发披露（装前必读）

- **全部出站仅指向 `open.bigmodel.cn`**（TLS + Bearer 同一把 key）：
  搜索查询词、`web_fetch` 的目标 URL（服务端抓取，**URL 会出现在智谱侧**）、
  `vision_analyze` 的图片/视频字节（base64 上传）、贴图附件字节（自动，所有会话含
  子代理都会触发；不想外发就 `enablePreStep: false`）。
- `vision_analyze` 读本地文件的范围与内置 read 工具一致（fs 沙箱各模式放行读），
  差异在于**字节会离机**；受限会话里它是唯一的"读+外发"通道。
- key 仅存在于单次调用栈；本插件零日志输出；图片字节不落盘、不进会话日志。
- 搜索/阅读结果是不可信内容（与官方搜索同面）；贴图描述以 `<<<IMAGE_CONTENT`
  围栏包裹并标注 UNTRUSTED（图中排印的指令按引用数据对待）。

## 已知行为

- `search_pro` 引擎忽略 `count` 固定返回 10 条；接缝按 `maxResults` 截断并置
  `truncated: true`。
- MCP 响应 `content[0].text` 是双重 JSON 编码（已做两层容错解码）。
- 每次操作一次 MCP initialize + 一次 tools/call（多一个往返，换取对会话过期的健壮性）。
- OCR 模式转录可见文字，不解码二维码载荷（GLM-4.6V 能力边界）。
- 视觉必须走 Coding Plan 端点（默认 `codingBaseURL`）；按量端点对这把 key 报
  429 code 1113（错误信息里带此提示）。
- 贴图替换的持久化语义：替换版（带 attachmentId 前缀）是会话日志唯一事实；描述
  失败时保留原 image 块（诚实失败）。
- 直通判定是**显式配置**（`passthroughModels`），不读模型元数据——settings 声明
  `input: [text, image]` 之后元数据已不能反映"API 是否原生吃图"。
- 声明 `input: [text, image]` 后 `read_image` 工具对文本模型也会亮起：其返回的裸图
  进历史会因服务端拒收而报错（与不声明时 pi-ai 客户端拒绝同级的失败）；让模型用
  `vision_analyze` 处理图片文件更稳。
- 恢复含图旧会话：历史 image 块不经钩子，纯文本模型会报错（用 vision_analyze 按
  attachmentId 分析）。

## 开发与测试

```powershell
# 冒烟（真实调用，耗额度约 3 次）：web 或 headless
node "$env:USERPROFILE\.dsh\plugins\dsh-zhipu\test\smoke.mjs" web

# 改码后重装副本（pnpm 对路径未变的 file: 依赖不会自动重打包）
Remove-Item -Recurse -Force "$env:USERPROFILE\.dsh\profiles\<name>\node_modules\dsh-zhipu"
pnpm install --prefer-offline   # 在 ~/.dsh/profiles/<name> 下
# web 进程须由用户在终端重启；headless 每次运行即新进程
```

热重载警告：对运行中的 web 进程同时做「服务行改配置 + 加依赖行」的组合变更会进入
半更新死态（无告警）；yml 小改不受影响，组合大改后重启。

## License

MIT