用途
token-efficiency 是一套关于 AI 编程助手 token 使用的实践技能，目标是在不牺牲验证的前提下减少重复往返和无关输出。资料特别提示：上下文大小、缓存输入、输出和推理用量是不同测量维度，字节更少并不能证明账单更低或答案质量不变。
主要关注点
用量去向分析。 资料基于一位重度用户本地日志的测量（2026-10-10，约 1,100 个会话，涉及 Codex、Claude Code、Hermes 和 Grok）。建议先运行 python TOOLS/usage_report.py 获取自身数据再作调整。其中一个历史 Codex 日志样本显示，累计输入除以工具调用次数约为 124k，但这并非实测的中位请求大小或未缓存费用。稳定指令、技能索引、MCP schema 和大型输出会影响后续请求，实际成本由缓存、延迟加载和压缩决定。建议保持这些内容精简，并通过更新 STATE.md 结束阶段、在新会话中继续，而不是维持一条超长线程。
审批与子代理成本。 Codex 审批审查约占 Codex 用量的 23%，每次升级命令都会启动审查者重新读取记录；减少升级可减少审查，例如在可写根目录内工作、批量执行命令，由用户决定是否扩大 sandbox_workspace_write.writable_roots。分叉子代理约占 12%，因为分叉会重新读取父历史，建议仅用于独立工作并给出简短的书面任务说明。71 个会话是达到用量限制后的恢复，维护当前 STATE.md 可让恢复变成一次短读。
等待 CI/构建。 建议使用宿主提供的后台/通知机制处理长时间构建和 CI。反复轮询模型即使没有变化也会产生推理成本。对于 GitHub 发布，应记录确切的已推送 SHA、查找其必需的运行，并用 TOOLS/Wait-External.ps1 -GitHubRun <run-id> 等待；该脚本执行 gh run watch <run-id> --compact --exit-status，失败时执行一次 gh run view <run-id> --log-failed。发布前须确认该 SHA 上所有必需检查均成功；无运行、失败/取消的运行或不同 SHA 都不算成功。
缓存证据。 缓存规则和价格取决于提供商、模型和计费方案，不能将某一 API 的费率套用到另一 API 或订阅配额。资料举例说明 Anthropic 标准 API 缓存写入为 5 分钟 1.25 倍基础输入或 1 小时 2 倍，读取为 0.1 倍，并提醒先核实当前适用定价。应保持持久指令/工具定义稳定，把变化的任务状态放在后面；使用实际用量字段（如 Anthropic cache_read_input_tokens）或提供商遥测来确认缓存命中，不要为保持缓存预热而安排请求。
按需加载能力。 保持技能名称/描述紧凑，仅在相关时加载正文；优先使用已有的原生工具或 CLI；对可选 MCP 服务器进行范围控制，尊重用户自有服务器。schema 字节数除以 4 只是粗略大小估计，不是已加载、缓存或计费 token。不要仅为了节省 token 而在用户未提出质量与配置约束的情况下更换模型、辅助路由或提供商。资料还说明不应将主模型路由到 openrouter/free，因为该路由随机选择免费模型，模型/缓存复用不可预测；免费账户限额为每天 50 次请求、每分钟 20 次；Cloudflare 免费池为每天 10,000 neurons，并非 token 配额。遇到 429 应检查错误/重置元数据并遵守 Retry-After 进行有界退避，不要静默切换模型或付费路由。
批量与约束输出。 批量执行独立读取、复用上下文中已有证据、只请求所需字段或行；用工作区地图（WORKSPACE.md）替代重复探索；检查退出码和截断情况；输入或环境未变时不要重跑已通过的检查；优先使用定向搜索而非导出整棵树、历史或配置文件。资料说明 RTK 是有损且依赖命令/版本的，并非通用的 97% 节省；附带的窄安全钩子仅覆盖面向人的独立状态/测试，精确差异、搜索、读取、结构化输出和管道保持原样。
使用方式
资料给出的可执行内容主要是：先运行 python TOOLS/usage_report.py 测量自身用量，使用 TOOLS/Wait-External.ps1 -GitHubRun <run-id> 等待 GitHub 运行，并通过 STATE.md、WORKSPACE.md 等文件管理会话状态和工作区信息。资料未提供安装命令或版本信息。
适用场景
适用于等待 CI/构建、减少重复读取、测量 token 成本与缓存、选择 MCP/技能范围等场景。
限制
缓存规则、价格、配额和工具行为均依赖宿主与提供商，需以实际遥测为准；资料中的测量数据来自特定用户和特定时间点，不构成普遍结论；部分优化手段（如 RTK）是有损的；不得自行更改沙箱或审批设置。