当需要降低 Agent token 成本时：审查…

在收到 caveman learn 报告后，逐项审查 token 消耗排名，按类别走同意流程应用降本修复，并如实报告修复带来的可测量收益。

适用场景

解决思路

1. 先运行 caveman learn report --json，解析 caveman.learn.v1 JSON，展示 Cave Score、其四个组成部分以及排名的 token sinks；对每个 sink 说明其 class 和 basis；行为类 sink 是观察结果，数字作为事实呈现，建议要温和，不要把行为发现变成命令。
2. 如果计划带有 `spend` 块，先展示它：扫描窗口的成本以及缓存复用后的有效输入费率（`effective_input_multiplier`）。展示金额时必须遵守：spend 是窗口的成本，绝不是修复会带来的回报；说明覆盖的窗口，绝不外推到月、年或运行率；如果 `unpriced` 非空，说明总额是下限并列出被排除的模型；加上订阅说明——在 Max/Plus/Advanced 计划上边际成本为零，该数字是 token 的 API 等价价值而非实际花费；绝不称其为已验证。
3. 只对用户选择要处理的 sink，按类别运行同意循环。
4. 在提出修复前，可运行 caveman learn simulate <sink_id>，仅作为扫描历史上的规模展示：它汇总扫描历史，绝不向前预测。
5. REDUCIBLE 类（过重的 CLAUDE.md、从未被调用的 skill）：运行 caveman learn apply <sink_id> --dry-run（这会生成候选，不编辑任何东西）；提出具体 diff 并展示 before -> after tokens/turn；询问用户是或否；若同意，用自己的文件工具应用编辑；重新运行 caveman learn report --json（或重新计数被改动的文件）确认减少。这是净 token 负向门禁：如果 after 不低于 before，回滚并报告。绝不保留不降低 tokens/turn 的编辑。
6. RECURRING_CONTEXT 类（跨会话重建的重块；fix kind 为 cavemem_offload）：将其移入 cavemem，以便紧凑召回而非每轮重新粘贴。候选只携带 LOCATOR，绝不携带块正文。运行 caveman learn apply <sink_id> 并读取它写入 ~/.caveman/candidates/ 下的候选 JSON；只取 locator、数字和提议的指针文本；不要信任候选中的任何正文（本来也没有）。
7. 自己本地重读真实块：打开 locator 的 rel_path，定位到 jsonl_line，用同样方式重新切分该轮（按空行顺序切分文本），取 block_index，并验证原始块的 sha256 等于 locator 的 content_sha256。如果不匹配，说明文件自扫描后已改变——中止此项。
8. 存储它：caveman mem remember -- "<the real block>" 并捕获返回的 id。`--` 结束选项解析，使以 `---` 规则开头的块被原样存储而非被当作 flag。
9. 诚实地测量门禁。before = 该块的 tokens/turn（它每轮都加载）。after = 指针的 tokens/turn 加上召回成本。通过运行 caveman mem recall "<topic>" 并读取命中上的 tokens_added 获得召回成本。如果 after 不低于 before，运行 caveman mem forget <id>，保持源不变并停止。
10. 裁剪源并写入指针。从其 CLAUDE.md 或 AGENTS.md 章节中移除该块（对于用户手动粘贴的内容，告诉他们停止粘贴什么），并在原位置写入候选提议的指针文本。指针指明召回路径：紧凑形式用 caveman mem recall "<topic>"，字节精确原文用 caveman mem recover <handle>。
11. 绝不让 agent 变笨：完成前确认 caveman mem recall "<topic>" 返回命中且指针已就位。如果召回无返回，或你没有写入指针，则回滚（caveman mem forget <id> 并恢复源）。移除上下文却没有可用的召回路径是这个守卫要阻止的唯一失败。
12. 重新测量并报告确认的减少量和召回路径。
13. SKILL_DISTILLATION 类（procedure_repeat sink；fix kind 为 skill_distillation）：这是用户跨会话重复的工具步骤序列。写成 skill 可能阻止 agent 重新推导——但 skill 每个会话都加载进前缀，只在命中该模式的会话上回本。这与本报告惩罚的 dead_load sink 形状相同，因此评分方式不同，绝不能走捷径。
14. 绝不通过净 token 负向门禁应用此项。该门禁重新计数文件；它看不到落在不同位置的成本和收益。
15. 先展示候选：步骤、它在多少个会话中重复出现、这些跨度消耗的 token。明确说明回报未经证实。
16. 如果用户想要，写 skill，然后同时启动 holdout：caveman learn experiment start <label> --sink <sink_id> --fix-kind skill_distillation。告诉他们如何运作：开启一段时间，然后运行 `caveman learn experiment arm <label> off` 并在相当长的时间内不使用它工作。每个 arm 至少需要 5 个会话才能得出任何结论。
17. 用 `caveman learn experiment report <label>` 读取结果。`insufficient_data` 结论意味着继续——绝不要将其呈现为小胜。`regressed` 结论意味着删除该 skill；直接说明。
18. 测试框架比较每会话的中位 token 数。如果它标记 on-arm 每轮命中更多工具错误，先说明这一点：更便宜但失败更多的会话不是节省。
19. LOAD_BEARING：绝不触碰。它出现在报告中只是为了让分数保持诚实。
20. 报告节省（caveman learn savings）：账本按测量方式分组展示已应用修复的回报。呈现时，分组不是装饰——它是声明强度的体现：deterministic_remeasure（我们编辑的文件被重新计数，最强的本地层级）、controlled_holdout（在本机上开启 vs 关闭测量）、counterfactual_replay（应用变更后重跑真实历史）、interrupted_time_series（前会话 vs 后会话，无对照 arm）。
21. 三条规则，全部有约束力：绝不跨层级求和，绝不呈现单一混合的节省标题——重新计数的文件和前后中位数不是同一种证据；始终读出你作为胜利呈现的那一行上的 `confounders`，它们是常设警告而非细则，正是为好消息情形而存在；读取 `attribution.provenance`——`intact` 表示文件仍带有我们提议的编辑，`changed_since` 表示有人改过它且部分 delta 不是我们的（要说明），`target_missing` 表示 delta 根本无法归因于该修复。绝不将 `changed_since` 或 `target_missing` 行呈现为 caveman 的结果。
22. 回归按设计不携带金额数字。用其结论呈现并提供回滚路径；不要软化，也不要省略。
23. 约束规则：每次编辑都要同意，不允许隐藏个别 diff 的“全部应用”；编辑应用且其重新测量门禁通过后，运行 caveman learn applied <sink_id>，未来 learn 运行用它报告纵向结论：improved、unchanged、regressed 或 insufficient_data，诚实呈现 regressed 并提供该编辑的确切回滚路径；每次编辑都可逆：准确报告你改了什么，offload 用 caveman mem forget <id> 加恢复被裁剪的源来撤销；仅 inferred，绝不将本地数字呈现为已验证，货币仅允许在报告本身携带它的地方（`spend` 和已定价的节省行），且仅在该块自身框架完整的情况下——窗口限定、绝不预测、绝不验证；分析器（caveman learn）是只读的，你是唯一的写入者，且仅在用户同意后。

适用边界 · 注意事项

• 没有 caveman learn 报告或未运行 `caveman learn report --json` 时，不要凭猜测应用降本编辑。
• 对于 LOAD_BEARING 类 sink 绝不触碰，它出现在报告中只是为了让分数保持诚实。
• 不要将 behavioral sink 的观察结果变成命令式建议，也不要把 spend 数字外推、求和或称为已验证。