diff --git a/docs/zhipu-token-usage-collection.md b/docs/zhipu-token-usage-collection.md
new file mode 100644
index 0000000..1cb1ea5
--- /dev/null
+++ b/docs/zhipu-token-usage-collection.md
@@ -0,0 +1,239 @@
+# 智谱 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，所以当前项目采用低频、本机、自用、只读查询方式，不做公开服务和高频轮询。