DeepSeek Harness（dsh）接入智谱免费模型配置指南

# DeepSeek Harness（dsh）接入智谱免费模型配置指南
## 一、适用场景
在 DeepSeek Harness（dsh，桌面版，示例版本 0.2.1-rc.2）中使用智谱开放平台免费模型 `glm-4-Flash`。智谱接口为 OpenAI 兼容协议，可直接接入。
## 二、配置总览
| 项目 | 值 |
|---|---|
| Base URL | https://open.bigmodel.cn/api/paas/v4 |
| API 协议 | openai-completions（OpenAI 兼容） |
| 模型 | glm-4-flash（免费，128K 上下文，最大输出 4096） |
| API Key 存放 | 用户级环境变量 ZHIPU_API_KEY |
| 配置文件 | C:\Users\<用户名>\.dsh\profiles\desktop\cordis.patch.yml |
## 三、配置步骤
### 第 1 步：设置环境变量
打开 PowerShell，执行（把 KEY 换成你自己的智谱 key）：
```powershell
[Environment]::SetEnvironmentVariable('ZHIPU_API_KEY', '你的智谱APIKey', 'User')
```
设置的是用户级变量，新启动的进程才会读到。
### 第 2 步：编辑配置文件
配置文件路径：`C:\Users\<用户名>\.dsh\profiles\desktop\cordis.patch.yml`
该文件是 dsh profile 的补丁层（patch layer），应用启动时会合并生效。**不要改同目录的 cordis.yml（根配置）**。
在文件末尾的 `llm-pi-ai.config.providers`（默认是空 `{}`）下新增 zhipu 路由，并同步切换默认模型：
```yaml
- id: agent-default-model
  name: "@deepseek-ai/dsh-agent-default-model"
  config:
    provider: zhipu
    model: glm-4-flash
    # 注意：glm-4-flash 不支持 reasoningEffort，千万不要设置该字段，否则启动报错：
    # provider "zhipu" model "glm-4-flash" does not support reasoning effort "high"
- id: llm-pi-ai
  name: "@deepseek-ai/dsh-llm-pi-ai"
  config:
    providers:
      zhipu:
        displayName: 智谱GLM
        apiKeyEnv: ZHIPU_API_KEY
        api: openai-completions
        baseURL: https://open.bigmodel.cn/api/paas/v4
        models:
          - id: glm-4-flash
            name: GLM-4-Flash
            contextWindow: 131072
            maxTokens: 4096
```
保留文件中其他已有的 patch 条目不动，只改这两段。
### 第 3 步：重启应用
完全退出 DeepSeek Harness 后重新打开（环境变量和配置只在启动时加载）。

## 四、验证
- 启动后发一条消息，默认应走智谱 GLM-4-Flash。
- 若报 `does not support reasoning effort`：检查 agent-default-model 下是否残留 reasoningEffort 字段，删掉即可。
- 若提示找不到 key：确认 ZHIPU_API_KEY 环境变量已设置，且应用是设置之后启动的。

## 五、踩坑记录
1. **reasoningEffort 只属于 DeepSeek 系模型**：从 deepseek 默认配置照搬 `reasoningEffort: high` 会导致智谱模型报错，必须移除。
2. **API key 不要写进 yml**：自定义 provider 通过 `apiKeyEnv` 引用环境变量（解析顺序：凭据存储 → 环境变量），key 本体放环境变量更安全。
3. **不要改 cordis.yml**：文件注释明确要求编辑 cordis.patch.yml。
4. **配置必须重启生效**：改完文件不重启，应用不会加载新配置。