WorkBuddy Token 用量统计
触发场景
用户询问 WorkBuddy 的 token 消耗量，例如：本次会话消耗、今天累计、指定时间段累计、总累计、各会话排行、按模型统计。
执行方式（重要）
直接运行脚本，不要读取 trace JSON 文件到上下文（省 token）。
第 1 步：定位脚本
脚本在本 skill 包内，相对路径为 scripts/token_usage.py。用 Glob 在以下位置搜索 scripts/token_usage.py，取实际匹配到的绝对路径（典型位置：~/.workbuddy/skills/workbuddy-token-usage/scripts/token_usage.py）：
- 用户级：~/.workbuddy/skills/**
- 项目级：当前项目目录下 .workbuddy/skills/**
注意：~ 表示用户主目录，不同机器用户名不同，任何命令中不得出现具体用户名或固定盘符。
第 2 步：选择 Python 解释器
用 Bash 依次探测，取第一个可用的（需 Python 3，脚本依赖 f-string）：
1. python3 --version
2. python --version
3. py -3 --version
第 3 步：运行
python "<第 1 步得到的脚本绝对路径>" <参数>
示例（路径必须来自第 1 步的实际查找结果，不得照抄）：
python "~/.workbuddy/skills/workbuddy-token-usage/scripts/token_usage.py" --today
能力清单（首次会话 / 用户询问"能做什么"时输出）
| 参数 | 功能 |
|---|---|
| （无参数） | 能力清单 + 今日摘要 |
--today |
今日累计 |
--session current |
本次会话（最近活跃） |
--session <id> |
指定会话（先 --list-sessions 查 id） |
--from 2026-08-01 --to 2026-08-10 |
指定时间段累计 |
--total |
总累计（全部历史） |
--weekly / --monthly |
本周 / 本月累计 |
--all |
按天总览 |
--list-sessions --top N |
会话用量排行 |
--by-model |
按模型汇总 |
--json |
机器可读 JSON |
--export <csv路径> |
导出 CSV 明细 |
--no-cost |
关闭参考费用 |
--baseline <ISO时间> |
自定义统计基线 |
--help |
完整能力清单 |
使用规则
- 统计基线：默认只统计脚本启动前已落盘的 trace，本次统计执行不计入结果。回复用户时不必强调，除非被问。
- 脚本输出即最终答案：默认只做一次运行，把结果直接转述给用户；未显式要求时不做二次分析、不读 trace 原文件、不额外解释。
- 输出必须中文；数字保持脚本格式（千分位）。
- 参考费用仅粗估，不代表官方积分扣费——如用户问积分换算，说明需以官方口径为准。
- 若提示"未找到 trace 数据"：检查
~/.workbuddy/traces/是否存在；不存在则告知用户本地无用量数据。 - 用户要求"当前对话/本次会话"时用
--session current；要求"今天/今日"用--today；要求某段日期用--from/--to；要求"总共/全部/历史累计"用--total。
字段说明（供排查用）
- 主数据源：
trace.modelInfo→totalInputTokens / totalOutputTokens / totalCachedTokens / callCount / models - 维度字段：
trace.sessionId（会话）、trace.startedAt（UTC 时间，脚本已转本地 GMT+8） - 缓存占比通常 90%+（同会话重复上下文命中缓存），实际扣费远低于名义 token 数。
