ZCode 编码套餐 yuyang2230/dsh-zcode-coding-plan

dsh-zcode-coding-plan

中文 · English · Release notes

买了 GLM Coding Plan，却只在别的客户端里用？ 这个 DSH 桌面端插件让那份已付费的套餐额度，在 DeepSeek Harness 会话里真正发挥作用——把编码重活派给官方 ZCode 通道，享受 1.5 倍（150%）额度，外加原生 Agent 能力（文件 / Bash / MCP）与多轮会话。

直连 API Key 与经 ZCode 官方 CLI 的对比

合规驱动官方 ZCode 客户端，不修改客户端、不伪造请求、不绕过任何限制。

注册两个工具：

| 工具 | 作用 |
| zcode_call | 派一个真实 agent 任务给套餐通道，支持 --resume 多轮续接 |
| zcode_quota | 查套餐余量；配合内置闸门做到「余量够才自动派活」 |

先看对比，再决定要不要装 ↓

为什么用它：直连 API Key vs 本插件

同一个 GLM Coding Plan 套餐 Key，两种花法，结果差很远。

| 维度 | 直连 API Key（自己调 open.bigmodel.cn/api/anthropic） | 本插件（经 ZCode 官方 CLI） |
| 计费口径 | 扣账户余额（按量付费，与套餐无关） | 扣套餐积分（你已付费的订阅额度） |
| ZCode 渠道倍率 | 不适用——非官方指定工具，无倍率概念 | 1.5 倍（150%）套餐额度消耗 |
| 前置条件 | 任意智谱 API Key 即可 | 需装 ZCode 客户端 + 有 GLM Coding Plan 订阅 |
| Agent 能力 | 纯 LLM 调用，只有模型本身的读写/执行能力 | 原生文件 / Bash / MCP / Hooks，是完整 agent |
| 多轮续接 | 自己实现会话状态，自己管重试与上下文裁剪 | 原生 --resume <sessionId>，客户端负责 |
| 上下文缓存 | 无 | 支持（实测 cacheReadTokens 命中约 13K–68K） |
| 凭证管理 | 你自己在代码里塞 Key | Key 交给官方客户端，本插件只做路由 |
| 可审计性 | 无内建记录 | ZCode 本地 db.sqlite 逐条记录 provider/model/token |
| 故障面 | 自己维护 | 依赖 ZCode 客户端版本（升级可能改 schema） |

更详细的计费与能力矩阵见 docs/comparison.md。

什么时候值得

- 你已经买了 GLM Coding Plan，但 DSH 这边没在用 → 套餐在闲置，本插件让它干活；
- 你想把多文件重构 / 跑测试 / 批量修改这类重活外包出去，不想让它们吃主会话额度；
- 你看重可审计（每次调用 provider、model、token 都有本地记录）。

什么时候不值得

- 你没有 Coding Plan 订阅 → 装了无效果，白折腾。直连 API Key 按量扣余额也完全能用。
- 你只想要一次性的短问答 → 起 ZCode 子进程要背约 66K tokens 的系统提示，比裸 API 调用重得多。
- 你不接受在机器上多装一个 Electron 客户端 → 本插件依赖它。

快速判断：装之前问自己三句

1. 我已经订阅了 GLM Coding Plan 吗？（没有 → 跳过本插件）
2. 我平时主要在 DSH 里干活，而不是 ZCode 客户端里？（是 → 插件有用）
3. 我有重活（多文件重构 / 跑测试 / 批量修改）想外包吗？（有 → 直接收益）

三个都是「是」再往下看安装。

安装（3 步）

0. 前置：装 ZCode，并准备好套餐 Key

1. 安装 ZCode 官方客户端：<https://zcode.z.ai/cn/docs/install>
2. 在智谱平台开通 GLM Coding Plan，拿到套餐 API Key。
3. 把 Key 放进 DSH 凭据文件 ~/.dsh/.credentials.yaml 的 refs: 段（插件不附带任何 Key，也没有 Key 就无法工作）：

refs:
BIGMODEL_CODING_PLAN_API_KEY: 你的套餐Key

1. 放插件并注册

把仓库放到你机器上的任意目录，例如 C:/tools/dsh-zcode-coding-plan。

A) 注册到 DSH profile —— 编辑 ~/.dsh/profiles/desktop/cordis.patch.yml，在顶层列表追加：

- id: zcode-coding-plan
name: dsh-zcode-coding-plan
config:
下面三行可以整个省略 —— 插件会自动探测 ZCode 安装位置 zcodeExe: 'D:/Program Files/ZCode/ZCode.exe' zcodeCjs: 'D:/Program Files/ZCode/resources/glm/zcode.cjs' builtinProviderConfig: 'D:/Program Files/ZCode/resources/config/provider/zcode-builtin.json' providerOverride: 'C:/Users/你的用户名/.dsh/zcode-provider-override.json' defaultMode: yolo defaultTimeoutMs: 900000 余量闸门可选：填脚本路径才有闸门；留空则直接派活（fail-open） quotaScript: ''

编辑前先备份（cordis.patch.yml.bak-<用途>-<时间戳>）——运行中的 DSH 可能改写它。

B) 加依赖 —— 在 DSH 应用目录的 package.json 的 dependencies 里追加：

"dsh-zcode-coding-plan": "link:C:/tools/dsh-zcode-coding-plan"

C) 建 junction —— 在 DSH 应用目录执行：

node -e "require('fs').symlinkSync('C:/tools/dsh-zcode-coding-plan', require('path').join(process.cwd(),'node_modules','dsh-zcode-coding-plan'), 'junction')"

用 link: + junction，不要用 cp 复制——复制后插件改动不会生效。

2. 生成 provider 覆盖配置 + 自检

cd C:/tools/dsh-zcode-coding-plan
node scripts/generate-override.mjs # 读 ~/.dsh/.credentials.yaml，写 ~/.dsh/zcode-provider-override.json
node scripts/setup-check.mjs # 环境自检，退出码 0 = 就绪

或者用 node scripts/install.mjs 一步打印上面所有片段（含本机探测到的真实路径）。

最后重启 DSH 桌面端。日志里应出现：

[dsh-zcode-coding-plan] tools zcode_call + zcode_quota registered; zcode=… cjs=… override=… probe=windows-paths

用法

自然语言触发

跟 agent 这么说就会走本插件：

- 「用 zcode 跑这个重构」「把编码任务派给 ZCode」
- 「省 DSH 额度」「吃 150% 配额」
- 「让 GLM Coding Plan 干这个重活」

agent 会先 zcode_quota 查余量，再决定是否 zcode_call 派活。

zcode_call 参数

| 参数 | 类型 | 必填 | 说明 |
| prompt | string | ✅ | 派给 GLM 的任务提示词，写清目标与验收标准 |
| cwd | string | | 任务工作目录；绝对路径或相对会话目录；省略 = 会话工作目录 |
| resume | string | | 上次返回的 sessionId，续接多轮会话 |
| mode | string | | build/edit/plan/yolo，默认 yolo（全自动）；仅咨询用 plan |
| timeout_ms | number | | 子进程超时，默认 900000（15 分钟），钳制到 [30000, 3600000] |
| force | boolean | | true 跳过余量闸门强行执行（默认 false，余量不足返回 quota_insufficient） |

返回

{
"sessionId": "sess_…", "traceId": "…", "response": "…",
"usage": { "inputTokens": 67512, "outputTokens": 4, "totalTokens": 67516 },
"projection": { "contextWindow": 200000, "contextUsed": 67516 },
"exitCode": 0
}

失败时返回 { error, hint?, timedOut?, timeoutMs?, exitCode?, stderrTail? }。

zcode_quota 参数

无参数。返回套餐余量与路由判定：

{
"available": true,
"sufficient": true,
"plan": "pro",
"windowPct": 4.3, "routeWindowPct": 60,
"weekPct": 16.0, "routeWeekPct": 80
}

available:false 表示没配置余量脚本（正常状态，闸门会 fail-open 直接放行）。

多轮示例

1. zcode_call({ "prompt": "在 src/ 下新增一个 Express 服务并写好 README", "cwd": "D:/work/myproj" }) → response: …, sessionId: "sess_124bfb13-fc98-42c4-8056-f0b3aa584bed"

2. zcode_call({ "prompt": "接着把测试补齐，跑到全绿", "cwd": "D:/work/myproj", "resume": "sess_124bfb13-fc98-42c4-8056-f0b3aa584bed" })

3. zcode_call({ "prompt": "评估要不要上 gRPC", "cwd": "D:/work/myproj", "resume": "sess_124bfb13-…", "mode": "plan" }) // 只讨论，不动文件

余量闸门（可选）

闸门在派活前跑一次本地余量估算脚本，5h 窗口 < 60% 且本周 < 80% 才放行，否则快速返回 quota_insufficient（不消耗任何额度、不启动子进程）。

默认不启用——发布版不预设任何人的监控脚本路径。配置 quotaScript 才生效；缺失/异常/超时一律 fail-open 放行。

脚本契约（任何满足此约定的程序都可以）：

<python> <quotaScript> --json --plan <plan>
→ stdout: {"plan":"pro","window_weighted":5,"window_cap":400,
"week_weighted":308,"weekly_cap":2000}

结果缓存 60 秒，避免一个会话里反复起 python。强制执行用 force: true。

验证调用真的走了套餐

ZCode 把每次调用记在本地 ~/.zcode/cli/db/db.sqlite（约 440MB，务必只读打开）：

python -c "
import sqlite3
con = sqlite3.connect('file:' + r'C:\Users\你的用户名\.zcode\cli\db\db.sqlite?mode=ro', uri=True)
for r in con.execute('select session_id, provider_id, model_id, status, input_tokens from model_usage order by rowid desc limit 3'):
print(r)
"

期望 provider_id == 'dsh-glm-coding-plan'、model_id == 'GLM-5.3-Flash'。
如果是别的 provider id，说明覆盖配置没生效（多见于 providerOrder[0] 不是我们）。

本仓库的真实调用记录：

('sess_124bfb13-fc98-42c4-8056-f0b3aa584bed', 'dsh-glm-coding-plan', 'GLM-5.3-Flash', 'completed', 67512)

插件配置一览

cordis.patch.yml 的 config: 段，全部可选：

| 键 | 默认 | 说明 |
| zcodeRoot | 探测 | ZCode 安装根目录 |
| zcodeExe / zcodeCjs / builtinProviderConfig | 探测 | 显式指定可跳过探测 |
| providerOverride | ~/.dsh/zcode-provider-override.json | 覆盖配置路径（可用 DSH_ZCODE_OVERRIDE 覆盖） |
| providerId | dsh-glm-coding-plan | 注入的 provider id |
| baseUrl | https://open.bigmodel.cn/api/anthropic | 端点 |
| modelIds | ["GLM-5.3-Flash","GLM-5.3"] | 套餐内可用模型 |
| contextWindow | 200000 | 写入覆盖配置的上下文窗口 |
| defaultMode / defaultTimeoutMs / minTimeoutMs / maxTimeoutMs | yolo / 900000 / 30000 / 3600000 | 调用参数 |
| maxStdoutBytes / maxStderrBytes | 16MB / 16KB | 输出上限 |
| pythonExe / quotaScript / quotaPlan | python / （空） / pro | 余量闸门 |
| quotaRouteWindowPct / quotaRouteWeekPct / quotaCacheTtlMs | 60 / 80 / 60000 | 余量闸门阈值与缓存 |

路径解析优先级：插件 config > ZCODE_HOME 环境变量 > 平台探测。

合规声明

本插件驱动官方 ZCode 客户端，用它已有的 provider 机制把套餐 Key 排在首位，从而让 DSH 的请求走官方的 Coding Plan 渠道。

- 不修改 ZCode 客户端任何代码或二进制；
- 不修改 ZCode 桌面端 provider 注册表（…/provider_config.json）；
- 不修改 ~/.zcode/v2/credentials.json；
- 不伪造请求、不绕过服务端校验、不破解任何限制；覆盖配置仅通过每次 spawn 的环境变量注入，不落盘到 ZCode 的目录；
- 使用请遵循智谱《GLM Coding Plan 使用须知》及 ZCode 官方文档。

官方文档：<https://zcode.z.ai/cn/docs>

已知限制

1. ZCode 升级可能改 provider schema。本插件只生成实测验证过的 personal 键；ZCode 升级后 lib/schema.js 会读取其内置 provider 配置，自动检测 personal schema 是否仍兼容，并在生成日志 / node scripts/setup-check.mjs 输出告警——但不会自动适配未知键（那需要重新实测）。看到告警或 Model creation failed 时，按 docs/troubleshooting.md 第 2 节处理。
2. 每次新会话约 49K–66K tokens 系统提示（实测单轮 inputTokens 约 67.5K）。这是官方客户端的固定成本，短问答很不划算。
3. 计费按请求次数，不是按你的提示长度。单轮多步工具调用可能产生多条 model 记录。
4. macOS / Linux 路径探测为尽力而为，未在本机验证。本仓库的实测验证全部在 Windows + ZCode 3.14.5 上完成。其他平台可能需要显式配置 zcodeExe/zcodeCjs。
5. 并发保守：zcode_call 标记为非并发安全，多派活会串行排队——这是刻意为之，避免双倍计费和机器被压垮。
6. 余量闸门依赖外部脚本，本仓库不提供任何配额估算实现（无法通用估算各套餐的真实消耗）。

文档

- docs/comparison.md — 详版对比：计费、倍率、能力矩阵、适用人群
- docs/how-it-works.md — 机制原理：provider 注入、选模型规则、多轮、缓存
- docs/troubleshooting.md — 排障：找不到 ZCode / Model creation failed / 401 / 余量闸门 / 没额度

开发与贡献

- CONTRIBUTING.md — 开发约定、提交前检查、provider 配置的两个硬性要求
- CHANGELOG.md — 变更记录

npm test # 三套测试，114 断言，零计费（推荐）
npm run check # 环境自检（需要装了 ZCode）
npm run test:smoke -- "回复两个字：就绪" # 真实调用（消耗套餐额度！）

仓库包含一份 CI 配置（Ubuntu + Windows × Node 18/20/22）。测试全部使用 mock spawn，在 CI 上不会调用 ZCode、不消耗任何额度；真实调用只存在于 npm run test:smoke，刻意不进 CI。

License

MIT — 见 LICENSE。