Token Usage Auditor 是一个用于审计项目 Token 使用情况的技能，来源为 a-green-hand-jack/ml-research-skills。它把 Token 使用作为项目遥测来测量：智能体的注意力去了哪里、花费了多少新鲜工作与缓存上下文，以及哪些会话或 sidecar 运行应关联回项目阶段和产物。
用途
该技能用于从本地 Codex、Codex sidecar 和 Claude Code 日志中审计项目 Token 使用。当用户要求测量 Token 消耗、Token 燃烧、项目 Token 使用情况时使用。
技能目录结构
<installed-skill-dir>/ ├── SKILL.md ├── scripts/ │ └── collect_token_usage.py └── references/ └── data-model.md
核心原则
将 Token 使用视为注意力和成本遥测，而非质量本身。优先使用 Codex 和 Claude Code 的本地精确日志，而不是先向用户询问估算。包含 .agent/sidecars/*/model.json 元数据，因为临时 sidecar 运行可能不会持久化常规会话日志。默认不把原始提示和消息文本写入项目记忆；只记录会话元数据、使用总量、分类和产物链接。保留各智能体特有的 Token 字段，不要将提示缓存读取、缓存创建、新鲜输入、推理输出和普通输出合并为一个无法解释的数字。对推断的阶段/任务标签标注置信度。当没有提交、报告、运行或论文章节可关联到会话时，不要编造产物链接。
快速开始
对当前项目运行：
python3 <installed-skill-dir>/scripts/collect_token_usage.py --project-root .
对近期时间窗口运行：
python3 <installed-skill-dir>/scripts/collect_token_usage.py --project-root . --since 2026-05-01 --until 2026-05-31
写入仓库本地报告：
python3 <installed-skill-dir>/scripts/collect_token_usage.py --project-root . --format markdown --output docs/reports/token_usage/2026-05.md python3 <installed-skill-dir>/scripts/collect_token_usage.py --project-root . --format json --output memory/token_ledger/sessions.json
该脚本对 Codex 和 Claude Code 日志是只读的。仅在提供 --output 时写入。
工作流程
-
确定项目根目录。尽可能使用 git rev-parse --show-toplevel。对于研究项目控制根目录，如果用户想要跨组件核算，使用共享根目录；如果想要组件本地核算，使用 code/ 或 paper/。
-
运行收集器。当用户要求按周、月、阶段或发布窗口时，包含 --since 和 --until。讨论时使用 --format markdown，更新项目记忆时使用 --format json。仅当日志位于默认位置之外时使用 --codex-root 或 --claude-root。仅当用户想要不带 sidecar 元数据的原始智能体会话日志时使用 --no-sidecars。
-
解读报告。total_context_tokens：智能体观察到的所有上下文，包括提供方报告的缓存读取。fresh_tokens：非缓存输入加缓存创建加输出，作为增量成本/工作量的更接近代理。cached_tokens：提示缓存读取或缓存输入，作为上下文复用，不等同于新鲜工作。session_count：项目匹配的本地会话或记录的 sidecar 运行数量。codex-sidecar：仓库本地 .agent/sidecars/*/model.json 记录。仅当 sidecar 运行将 Codex CLI 使用情况复制到 model.json 时，才会出现精确 Token 字段。
-
仅在支持时添加项目标签。phase：idea、literature、design、implementation、experiment、diagnosis、writing、rebuttal、release、maintenance、tooling、project-management。task_type：design、implementation、debug、writing、review、release、sync、setup、experiment、diagnosis、literature、coordination。confidence：exact、inferred、manual、unknown。
-
连接到产物。仅当有来自 git 历史、文档、用户笔记或会话元数据的证据时，才将会话链接到提交、PR、实验运行、报告、论文章节或记忆更新。如果产物链接未知，留空并将该会话报告为未链接。
更新项目记忆
写入长期项目记忆时使用 references/data-model.md。推荐输出：docs/reports/token_usage/YYYY-MM.md 用于人类可读的月度报告；memory/token_ledger/sessions.json 用于结构化会话摘要；memory/token_ledger/README.md 仅在项目需要策略说明时使用。除非用户明确要求且已审查隐私，否则不要提交复制的原始转录日志。
报告框架
总结时，区分以下结论：注意力分配：项目关注了什么；新鲜 Token 燃烧：近似增量 Token 成本；上下文复用：使工作更便宜或更少重复的缓存/读取上下文；产出：已交付的提交、报告、实验、论文章节、决策或记忆更新；摩擦：重复的上下文设置、失败的命令、被放弃的分支、重复分析，或没有产物的高燃烧会话。避免说高 Token 燃烧意味着好工作。优先使用这样的表述：“Token 使用集中在实验诊断；产出以决策为主而非提交为主。”
适用场景与限制
适用于需要从本地 Codex、Codex sidecar 和 Claude Code 日志审计项目 Token 使用的场景，尤其是研究项目中需要将 Token 消耗与项目阶段、产物关联时。限制包括：脚本对日志只读，仅在指定 --output 时写入；默认不记录原始提示和消息文本；产物链接仅在存在证据时建立，否则留空；sidecar 的精确 Token 字段仅在特定条件下出现。其他收费、价格、平台等信息暂未提供。