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 | 完整能力清单 |

使用规则

1. 统计基线：默认只统计脚本启动前已落盘的 trace，本次统计执行不计入结果。回复用户时不必强调，除非被问。
2. 脚本输出即最终答案：默认只做一次运行，把结果直接转述给用户；未显式要求时不做二次分析、不读 trace 原文件、不额外解释。
3. 输出必须中文；数字保持脚本格式（千分位）。
4. 参考费用仅粗估，不代表官方积分扣费——如用户问积分换算，说明需以官方口径为准。
5. 若提示"未找到 trace 数据"：检查 ~/.workbuddy/traces/ 是否存在；不存在则告知用户本地无用量数据。
6. 用户要求"当前对话/本次会话"时用 --session current；要求"今天/今日"用 --today；要求某段日期用 --from/--to；要求"总共/全部/历史累计"用 --total。

字段说明（供排查用）

• 主数据源：trace.modelInfo → totalInputTokens / totalOutputTokens / totalCachedTokens / callCount / models
• 维度字段：trace.sessionId（会话）、trace.startedAt（UTC 时间，脚本已转本地 GMT+8）
• 缓存占比通常 90%+（同会话重复上下文命中缓存），实际扣费远低于名义 token 数。