# 智谱 token 用量采集方案

本文档记录当前 ESP32-S3-RLCD 小屏项目中，智谱 GLM Coding Plan 的 token 用量采集方式、数据字段、刷新策略和安全边界。

## 结论

当前方案使用 Windows 本机的一个采集进程统一采集数据：

- 电脑性能数据
- Codex 用量数据
- 智谱额度与 token 用量数据

智谱密钥只保留在 Windows 本机环境变量 `ZHIPU_API_KEY` 中，不写入 Git、不写入固件、不通过 BLE 发送给开发板。ESP32 只接收已经简化后的数字。

## 数据来源

智谱数据分两类接口采集。

### quota/limit（额度百分比接口）

用途：读取 5H / 周额度窗口的百分比和重置时间。

请求：

```http
GET https://open.bigmodel.cn/api/monitor/usage/quota/limit
Authorization: <ZHIPU_API_KEY>
Content-Type: application/json
Accept-Language: en-US,en
```

注意：

- `Authorization` 直接放 API Key，不加 `Bearer` 前缀。
- `type == "TOKENS_LIMIT"` 才是 token 限额。
- `unit == 3` 表示 5H token 窗口。
- `unit == 6` 表示周 token 窗口；部分套餐不会返回。
- `TIME_LIMIT` 不是 token 用量，当前屏幕不使用它。

当前项目显示：

- `zhipu_5h_percent`
- `zhipu_5h_reset_mins`
- `zhipu_week_percent`
- `zhipu_week_reset_mins`

### model-usage（模型用量接口）

用途：读取真实 token 消耗，用于显示今日 token 和最近 14 天每日柱状图。

请求：

```http
GET https://open.bigmodel.cn/api/monitor/usage/model-usage?startTime=<yyyy-MM-dd HH:mm:ss>&endTime=<yyyy-MM-dd HH:mm:ss>
Authorization: <ZHIPU_API_KEY>
Content-Type: application/json
Accept-Language: en-US,en
```

当前项目查询窗口：

- 起始时间：最近 14 天第一天的 `00:00:00`
- 结束时间：当前本机时间

实测返回的关键字段：

```json
{
  "success": true,
  "data": {
    "x_time": ["2026-06-23 00:00"],
    "tokensUsage": [0],
    "totalUsage": {
      "totalModelCallCount": 700,
      "totalTokensUsage": 129053626,
      "modelSummaryList": [
        {
          "modelName": "GLM-5.2",
          "totalTokens": 123456,
          "sortOrder": 1
        }
      ]
    },
    "modelDataList": [
      {
        "modelName": "GLM-5.2",
        "tokensUsage": [0],
        "totalTokens": 123456
      }
    ],
    "modelSummaryList": [
      {
        "modelName": "GLM-5.2",
        "totalTokens": 123456,
        "sortOrder": 1
      }
    ],
    "granularity": "hourly"
  }
}
```

当前项目只使用：

- `x_time`
- `tokensUsage`

处理方式：

1. 按 `x_time` 的日期部分聚合 `tokensUsage`。
2. 得到最近 14 天每天 token 总量。
3. 今日 token 转为屏幕紧凑单位。
4. 以最近 14 天最大值为 100，生成每日柱状图百分比。

## 显示单位

电脑端会把 token 转成 `m10` 整数发送：

```text
m10 = round(tokens / 100000)
```

固件端再显示为：

- `< 1000`：显示为 `x.xM`
- `>= 1000`：显示为 `xxxM`
- `>= 10000`：显示为 `x.xB`

示例：

- `1455` -> `146M`
- `10000` -> `1.0B`

## 刷新策略

当前实现：

- `quota/limit` 默认 60 秒刷新一次。
- `model-usage` 默认 600 秒刷新一次。
- BLE 仍然每秒推送一次完整 `SYS8` 数据，但智谱 token 部分使用缓存值。

建议后续：

- `quota/limit` 可以调整为 2-5 分钟。
- `model-usage` 可以保持 10-15 分钟。
- 不建议秒级请求智谱接口。

## 协议字段

当前 BLE 协议为 `SYS8`。

智谱相关字段位置：

```text
..., zhipu_status,
zhipu_5h,
zhipu_week,
zhipu_5h_reset,
zhipu_week_reset,
zhipu_today_tokens_m10,
zhipu_daily_bars,
cpu_core_text,
disk_text
```

其中：

- `zhipu_status`：`0=WAIT`，`1=OK`，`2=ERR`
- `zhipu_5h`：5H token 使用百分比
- `zhipu_week`：周 token 使用百分比，没有则为 `-1`
- `zhipu_5h_reset`：5H 重置剩余分钟数
- `zhipu_week_reset`：周重置剩余分钟数，没有则为 `-1`
- `zhipu_today_tokens_m10`：今日 token，单位为 `100000 token`
- `zhipu_daily_bars`：最近 14 天每日柱状图百分比，使用冒号分隔，例如 `0:0:24:78:100`

固件仍保留 `SYS7` 解析，方便旧采集端短时间兼容。

## 代码位置

电脑端采集：

- `tools/pc-metrics/push-metrics-ble.py`
- `ZhipuStatusReader`
- `_query_quota()`
- `_query_usage()`
- `_usage_to_daily_snapshot()`

固件端协议解析：

- `main/metrics_protocol.c`
- `parse_sys8_line()`
- `parse_zhipu_daily_bars()`

固件端 UI：

- `main/ui_screen.h`
- `main/ui_screen.c`
- `update_zhipu_panel()`

## 安全边界

必须遵守：

- 不把 `ZHIPU_API_KEY` 写入代码。
- 不把 `ZHIPU_API_KEY` 写入文档。
- 不把 `ZHIPU_API_KEY` 写入固件。
- 不把 `ZHIPU_API_KEY` 发送给 ESP32。
- 不把原始接口返回完整转发给 ESP32。
- ESP32 只接收数字化后的结果。

当前推荐启动方式：

```powershell
$env:ZHIPU_API_KEY="<your-zhipu-api-key>"
& "D:\AI Code\ESP-32\tools\pc-metrics\start-ble-metrics.ps1" -IntervalSeconds 1
Remove-Item Env:\ZHIPU_API_KEY -ErrorAction SilentlyContinue
```

注意：这种方式只让启动后的采集进程持有密钥，不会把密钥持久写入系统环境变量。电脑重启后需要重新启动采集进程。

## 性能开销

本机实测结果：

| 接口 | 中位耗时 | 返回大小 |
| --- | ---: | ---: |
| `quota/limit` | 约 257 ms | 约 443 B |
| `model-usage`，近 7 天 | 约 348 ms | 约 7.1 KB |
| `tool-usage`，近 7 天 | 约 272 ms | 约 5.9 KB |

当前项目暂不使用 `tool-usage`。

按 10 分钟查询一次 `model-usage` 计算，一天只有约 144 次请求，数据量很小，对电脑和网络影响可以忽略。

## 官方性说明

`model-usage` 属于智谱官方用量查询插件实际使用的接口，风险低于社区逆向 Cookie 方案。

但它不是普通开放 API 文档中明确列出的长期稳定业务 API，所以当前项目采用低频、本机、自用、只读查询方式，不做公开服务和高频轮询。