# token-usage

**Repository Path**: tang_ai/token-usage

## Basic Information

- **Project Name**: token-usage
- **Description**: zcode 会话token同济
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# token-usage

ZCode Stop 钩子：每次模型回复结束（会话完成）时，自动统计并展示本次会话与最近一轮对话的 token 消耗量。

## 效果

每轮对话结束后，对话中自动出现 3 行用量摘要（每行行首为标题，后跟 token 详情）：

```
📊 会话累计（120 次调用）: 输入 10.38M ｜ 输出 92.1k ｜ 缓存读 5.01M ｜ 合计 10.47M tokens
⏱ 最近一轮（4 次调用，4 个工具）: 输入 685.8k ｜ 输出 3.7k ｜ 合计 689.4k tokens
🤖 按模型: GLM-5.3-Flash 5.45M ｜ z-ai/glm-5.3-free 5.02M
```

## 数据来源

查询 ZCode 本地数据库 `~/.zcode/cli/db/db.sqlite` 的 `model_usage` 表（WAL 模式只读，会话进行中即可查询），不联网、不采集任何数据。

## 安装

1. 把本项目放到任意位置（如 `D:\ai\skill\token-usage`）
2. 在 `~/.zcode/cli/config.json` 注册 Stop 钩子（脚本路径按实际位置修改）：

```json
{
  "hooks": {
    "enabled": true,
    "events": {
      "Stop": [
        {
          "hooks": [
            {
              "type": "process",
              "command": "C:/Users/pc/AppData/Local/Programs/Python/Python314/python.exe",
              "args": ["D:/ai/skill/token-usage/hooks/stop_hook.py"],
              "timeoutMs": 10000,
              "statusMessage": "统计 Token 用量"
            }
          ]
        }
      ]
    }
  }
}
```

3. 重启 ZCode 或新开会话即可生效（配置热加载时当轮即生效）。

要求：本机装有 Python 2.7 或 3.x（脚本双兼容），Windows 下建议在 `command` 写 python.exe 绝对路径。

## 工作原理

- `Stop` 事件触发时，ZCode 通过 stdin 把 `session_id`、`stop_hook_active` 等以 JSON 传给脚本
- 脚本聚合该 session 的 `model_usage` 记录，输出 `{"continue": true, "additionalContext": "<统计>"}` —— ZCode 会把上下文注入会话，模型随即向用户展示统计
- 续跑后的第二次 Stop 带 `stop_hook_active=true`，脚本静默退出，保证每回合只多一次续跑、不死循环
- 任何异常（数据库缺失、无记录等）均静默 exit 0，绝不影响会话

更多细节（排查、静默模式、卸载）见 [SKILL.md](SKILL.md)。