DSH GLM Usage
在 DeepSeek Harness 侧栏展示智谱 GLM Coding Plan 的用量 —— 无需切到控制台，也不用记 5 小时窗口什么时候刷新。
同时支持两个区域，凭据一份、按卡片切换：
| 区域 | 额度接口 | 控制台 |
|---|
| 智谱开放平台（默认） | https://open.bigmodel.cn/api/monitor/usage/quota/limit | bigmodel.cn |
| Z.AI 国际站 | https://api.z.ai/api/monitor/usage/quota/limit | z.ai |
两站的 API Key 不互通：国内 Key 调国际站会失败，反之亦然。
功能
- 侧栏常驻小卡：底部一行显示各窗口的「已用 / 总量 + 百分比 + 进度条」，并带最后更新时间；侧栏收起到 56px 轨道时自动变成只显示最紧张那个窗口百分比的图标。
- 点击打开明细面板：在中间栏打开完整面板，逐行展示 5 小时窗口、每周窗口与 MCP 工具额度，含重置时间；再点一次收起。
- MCP 工具明细：面板里额外列出
search-prime / web-reader / zread 各自的调用次数，MCP 数字异常时能立刻定位到是哪个工具。
- 零配置起步：默认直接复用 DSH 凭据库里已有的
ZAI_API_KEY（以及同名环境变量），不必再粘贴一次。
- Key 只在宿主侧：浏览器永远拿不到 Key —— 所有上游读取都由宿主进程完成，卡片只拿到归一化后的数字。
- 保存前先校验：粘贴新 Key 时先真的打一次上游，通过才落盘，打错不会把可用的凭据弄丢。
- 中英双语：跟随 DSH 的界面语言。
- 低调的轮询：默认 5 分钟一次，页面不可见时跳过；所有界面共享同一份快照与同一个定时器，面板与侧栏永远显示同一组数字。
界面
侧栏底部小卡：
GLM 用量 更新于 10:32
5 小时 1,234 / 12,000 10%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
每周 23,456 / 60,000 39%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MCP 工具 1,203 / 4,000 30%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
点开后中间栏是明细面板，带套餐徽标、Key 来源、刷新与关闭按钮。
安装
dsh plugin --profile desktop add /path/to/dsh-glm-usage
或直接放进 profile 的 package.json 依赖，并在 dsh.profile.bundles 里追加 dsh-glm-usage。装好后重启 DSH。
配置
设置 → 插件设置 → GLM 用量，或侧栏「插件」面板里本插件的详情页：
| 项 | 说明 |
|---|
| 区域 | 智谱开放平台 / Z.AI 国际站 |
| Coding Plan API Key | 留空则用 DSH 的 ZAI_API_KEY |
| 侧栏显示 | 关掉后侧栏不再出现小卡，其余功能不变 |
Key 的解析优先级：卡片保存的 Key > DSH 凭据库的 ZAI_API_KEY > 环境变量 ZAI_API_KEY。面板上的徽标会显示当前生效来源。
数据文件
<profile>/.dsh-glm-usage/settings.json
只有区域、Key（若保存过）与显示开关。可用 DSH_GLM_USAGE_DATA_DIR 覆盖目录。
用 CLI 排查
不想起 DSH 就能确认 Key 和区域是否可用（走的是插件同一条代码路径）：
ZAI_API_KEY=... node test/live-check.mjs # 两个区域都试
ZAI_API_KEY=... node test/live-check.mjs cn # 只试国内站
cn OK plan=max 5h=1.00% week=3.00% mcp=0.57% (23/4000)
tools: search-prime:16, web-reader:7, zread:0
global FAIL [auth] 令牌已过期或验证不正确
hint: the key is stale, revoked, or belongs to the other region.
失败时打印的是卡片上会显示的同一套分类（auth / no-plan / upstream / network / shape），所以「区域选错了」和「Key 过期了」一眼能分清。
关于上游接口
额度接口没有公开文档，实现按实测响应字段归一化，两个关键点：
- 业务失败也是 HTTP 200。Key 失效或账号没有套餐时，服务返回
200 OK 加 success:false，所以判断依据是响应体而不是状态码。本体区分三种失败：auth（Key 无效）、no-plan（按量计费账号，读不到套餐）、upstream（其它）。
- 窗口靠
unit 识别，不靠数组位置。5 小时窗口是 unit:3，每周窗口是 unit:6。上游随时可能调整 limits 的顺序，按位置切分会把两个窗口张冠李戴。
百分比优先用绝对值算（currentValue / usage），因为上游的 percentage 是取整后的整数，会把 0.71% 报成 1%、算成整数倍误差；只有在没有绝对数值时（旧版 TOKENS_LIMIT）才回退到 percentage。
CREDIT_LIMIT 的字段名与直觉相反：usage 是总额度，currentValue 才是已用。三种桶（TOKENS_LIMIT / CREDIT_LIMIT / TIME_LIMIT）都会被读取，未知类型跳过而不是报错。
开发
npm test # 两个套件一起跑
node test/host.test.mjs # 宿主：路由、鉴权、Key 解析、错误分类
node test/client.test.mjs # 浏览器：注册、渲染、语言切换、清理
两个套件都不需要启动 DSH：宿主测试把路由挂在裸 node:http server 上跑，浏览器测试复现 window.__ModuleLoader__ 的 handoff 契约、用 react-dom/server 静态渲染每个已注册组件。
client.test.mjs 需要 react，通过 GLM_PROFILE_NODE_MODULES 指向装了 react 的 node_modules：
# Windows
$env:GLM_PROFILE_NODE_MODULES = "$env:USERPROFILE\.dsh\profiles\node_modules"
# macOS / Linux
export GLM_PROFILE_NODE_MODULES="$HOME/.dsh/profiles/node_modules"
npm test
test/host.test.mjs 会用 ZAI_API_KEY（或 GLM_TEST_KEY）做真实上游读取；没有可用 Key 时它会直接退出并说明原因（退出码 2），而不是假装通过 —— 「归一化结果对不对」只有对着真实响应才验证得了，用 fixture 替代只会得到一份会跟上游一起腐化的假保证。设置 GLM_TEST_DIR 可把测试用的设置文件写到临时目录，避免污染真实 profile。
CI
.github/workflows/test.yml 两个 job：
- client：在 runner 上装 react 后跑渲染测试，任何 fork 的 PR 都会跑。
- host：需要仓库 secret
GLM_TEST_KEY（一枚真实的 Coding Plan Key）。未配置时这一步跳过并给出警告，而不是失败 —— 这样 fork 的 PR 不会因为读不到 secret 而变红。想让 live 测试真正跑起来，去 Settings → Secrets and variables → Actions 加一个 GLM_TEST_KEY。
lib/quota.js 是完全纯函数（归一化 + 抓取），可以单独引用来验证上游字段。
许可
MIT。与智谱、Z.AI、DeepSeek 官方均无关联，是社区插件 —— 上游接口随时可能变化，届时可能只有等作者跟进。
