# dsh-zcode-persona

为 DeepSeek Harness 装配 **ZCode 身份请求头**的 GLM Coding Plan 通道，让智谱网关把 DSH 客户端识别为 ZCode，吃到官方限时活动：同等模型调用量仅按 **67%** 扣减额度，等效 **1.5 倍**用量。**不做任何提示词/persona 改动**（服务端判定只看请求特征，与 system prompt 无关）。

[English](README.md) | [简体中文](README.zh-CN.md)

## 机制与依据

智谱官方文档（[docs.bigmodel.cn → GLM Coding Plan → ZCode](https://docs.bigmodel.cn/cn/coding-plan/tool/zcode)）声明：GLM Coding Plan 用户在 ZCode 中登录使用即可享受全天 1.5 倍使用额度（67% 扣减）。**该判定在服务端按 HTTP 请求特征识别客户端是否为 ZCode**。身份头字段级依据：

- [TriDefender/zcode-api](https://github.com/TriDefender/zcode-api)：`src/proxy/identity.ts` 逐字段镜像 ZCode bundle 的 `pio`（2026-08-07 刷新），README 自述 *"it's all about the 1.5x usage on frontier models"*；
- [LINUX DO t/2531858](https://linux.do/t/topic/2531858)：实测把 ZCode 请求头用于其他客户端，福利生效。

本插件在 `ready` 后经 `ctx.settings` seam 幂等写入 `llm-pi-ai` namespace 的一条 provider（默认键 `zai-coding-cn`，指向国内智谱 `https://open.bigmodel.cn/api/coding/paas/v4`），请求携带完整 ZCode 身份头：`HTTP-Referer`、`X-ZCode-App-Version`（默认 3.11.2）、`X-Title: Z Code@cli`、`X-ZCode-Agent: glm`、`X-Platform`、`X-Release-Channel: production`、`X-Client-Language`、`X-Client-Timezone`、`X-Os-Category`、`X-Os-Version`、`X-Device-Mid`（主机指纹派生稳定 UUID）。写入为**路径级 mutate**，只增 provider 键，不碰用户已有 provider（`doubao` / `opencode-go` 等）；写入经 llm-pi-ai 自身 schema 与 serviceable 校验，失败即拒且不影响既有路由。pi-ai 内置 `zai-coding-cn` catalog（`thinkingFormat: zai` 协议兼容继承），catalog 未收录的 `glm-5.3` / `glm-5.3-flash` 以完整规格声明。

**已知边界**：DSH 强制应用归因 `User-Agent`（dsh-llm `attributionHeaders`），`llm-pi-ai` 会从 profile headers 中剔除 `user-agent` 并替换为 harness UA（`adapter.ts` 合并逻辑）。因此 `User-Agent: ZCode/…` 无法经配置送达；其余 ZCode 专属头全部透传。能否过网关指纹需实测；若不足，需本地反代补 UA（本项目不内置）。

## 配置（改后需重载插件）

| 键 | 默认值 | 含义 |
|---|---|---|
| `codingPlan.enabled` | `true` | 装配总开关。 |
| `codingPlan.providerKey` | `zai-coding-cn` | `llm-pi-ai providers` 字典键（route id）。 |
| `codingPlan.apiKeyEnv` | `GLM_CODING_API_KEY` | Coding Plan API key 的环境变量引用。 |
| `codingPlan.displayName` | `GLM Coding Plan (ZCode)` | 设置界面显示名。 |
| `codingPlan.appVersion` | `3.11.2` | `X-ZCode-App-Version`；ZCode 升级后按真实客户端版本更新。 |
| `codingPlan.sourceTitle` | `cli` | `X-Title: Z Code@{sourceTitle}`。 |
| `codingPlan.deviceMid` | `''` | `X-Device-Mid`；留空按主机指纹派生稳定 UUID。 |
| `codingPlan.baseURL` | `https://open.bigmodel.cn/api/coding/paas/v4` | 国内智谱 Coding Plan OpenAI 兼容端点。 |
| `codingPlan.models` | 见源码 `DEFAULT_MODELS` | 该 route 服务的模型清单（替换 catalog）。 |

## 使用与验证

> ⚠️ 当前若已触达套餐 **5 小时周期限额**，需等该周期重置后才能发出可观测的计费请求（官方：积分在请求消耗 5 小时后刷新）。

1. 装配后，在 **设置 → 模型** 中选择 `GLM Coding Plan (ZCode)` provider 下的 `glm-5.3` / `glm-5.2` 等模型；
2. 配置环境变量 `GLM_CODING_API_KEY=<你的 Coding Plan API key>`（智谱开放平台 Coding Plan 页面生成；需先订阅 [GLM Coding Plan](https://z.ai/subscribe) 或 [bigmodel 套餐](https://www.bigmodel.cn/coding-plan)）；
3. 在限额刷新后发起若干真实请求，到 [用量统计](https://www.bigmodel.cn/coding-plan/personal/usage) 核对积分扣减是否为标准的 **67%**（等效 1.5 倍）。若按 100% 扣减，说明网关指纹不止身份头（例如校验 User-Agent），需本地反代补全 UA。

> ⚠️ 智谱会对套餐使用做风控（多人共用、异常客户端可能触发验证/限流甚至封号，见 LINUX DO 讨论）。自用、低并发、真实 Coding Plan 订阅是底线。

## 合规边界

仅用于自有订阅的行为定制、研究与测试。冒充 ZCode 或其他品牌对外提供服务、或绕过上游服务限制的风险自负；请遵守智谱服务条款。

## 构建

```bash
DSH_CHECKOUT=<checkout> bash scripts/build.sh
```