caveman-learn 是 Caveman 工具链中的编辑技能，与只读的 caveman learn 命令配对使用。caveman learn 负责测量 agent 的 token 流向；caveman-learn 则是经过用户同意的另一半，把测量发现转化为实际编辑，且每一次编辑都需要用户确认。它承诺：绝不宣称任何未经验证的节省，也绝不让 agent 变笨。
【先读计划】 运行 caveman learn report --json，解析 caveman.learn.v1 JSON，展示 Cave Score 及其四个组成部分，以及排序后的 token 消耗点。对每个消耗点说明其类别与依据。行为类消耗点属于观察，应把数字作为事实陈述、把建议柔和表达，不要把行为发现变成命令。如果计划带有 spend 区块，要先讲：扫描窗口花了多少钱，以及缓存复用后的有效输入费率（effective_input_multiplier）。展示费用时必须遵守：花费是窗口的成本，绝不是某项修复会返回的金额；要说明覆盖的窗口；绝不能换算成月、年或运行率；如果 unpriced 非空，要说明总额只是下限并列出被排除的模型；要补充订阅说明——在 Max/Plus/Advanced 计划上边际成本为零，该数字是 token 的 API 等价价值而非实际花费；绝不能说这些是已验证的。
【按类别执行同意循环】 只针对用户选择处理的消耗点运行同意循环。提出修复前可运行 caveman learn simulate <sink_id>，仅作为扫描历史中的规模展示，不向未来外推。
可压缩项（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 的编辑。
重复上下文（RECURRING_CONTEXT，修复类型 cavemem_offload）：把跨会话重复建立的沉重段落移入 cavemem，以紧凑方式召回而非每轮重贴。候选项只带定位符，绝不含区块正文。运行 caveman learn apply <sink_id>，读取 ~/.caveman/candidates/ 下的候选 JSON，只取定位符、数字和建议的指针文本。自行在本地重读真实区块：打开定位符的 rel_path，定位 jsonl_line，以相同方式重新切分该轮（按空行顺序切分），取 block_index，并校验原始区块的 sha256 是否等于定位符的 content_sha256；不匹配说明扫描后文件已变，放弃该项。用 caveman mem remember -- "" 存储并记录返回 id（-- 终止选项解析）。诚实测量门槛：before 是区块每轮 token 数（每轮都加载），after 是指针每轮 token 数加上召回成本（运行 caveman mem recall "" 读取命中项的 tokens_added）。若 after 不低于 before，运行 caveman mem forget 并保持源文件不变后停止。之后从 CLAUDE.md 或 AGENTS.md 中移除该区块，并在原处写入候选建议的指针文本，指针注明召回路径：caveman mem recall "" 取紧凑形式，caveman mem recover 取字节级原始内容。收尾前确认 caveman mem recall "" 有命中且指针已就位；若召回无结果或指针未写，必须回滚。
技能蒸馏（SKILL_DISTILLATION，procedure_repeat 消耗点，修复类型 skill_distillation）：把用户跨会话重复的工具步骤写成 skill，可能避免 agent 反复推导，但 skill 每会话都加载进前缀，只在命中该模式的会话上回本，因此不能用净 token 为负门槛，要把成本与收益分开看。先展示候选：步骤、在多少会话中重复出现、这些片段消耗的 token，并明说回本尚未证实。若用户要做，写完 skill 后立即启动 holdout：caveman learn experiment start --sink <sink_id> --fix-kind skill_distillation，说明用法——先开启一段时间，再运行 caveman learn experiment arm <label> off 关闭并工作一段相当时间，每条臂至少 5 个会话才有结论。用 caveman learn experiment report <label> 读结果：insufficient_data 表示继续，绝不能当作小胜；regressed 表示删除该 skill 并直接说明。若工具标记开启臂每轮工具错误更多，要先讲这点——更便宜但更多失败的会话不是节省。
记忆健康（MEMORY_HEALTH，memory_health::* 消耗点）：审计 CLAUDE.md、CLAUDE.local.md、.claude/rules、AGENTS.md、GEMINI.md 及 Claude Code 自动记忆（MEMORY.md 及其主题文件）。每项都是一次编辑、一次同意，未经同意绝不删除记忆内容。duplicate_rules（可压缩）：同一条规则每轮从两个文件加载，运行 caveman learn apply <sink_id> --dry-run，建议保留最具体文件中的副本并移除其他，每文件一个 diff，适用净 token 为负门槛。memory_orphans：索引从不链接的记忆文件，以及索引指向缺失文件；死链建议修复或删除索引行（可压缩，门槛适用），孤立文件展示开头几行后询问——从 MEMORY.md 链接它还是弃用；链接会增加索引 token，要说明，该编辑不在门槛内。memory_truncation：MEMORY.md 超出会话开始时加载的量，末尾条目永不可见；优先精简索引（每条一行、合并陈旧条目、把细节移入链接的主题文件）而非删除，写入前展示新索引及其行数与限制的对比。broken_imports：@import 指向不存在内容，逐个询问是修路径（展示找到的候选文件）还是移除导入。stale_references：反引号的仓库路径已不存在，属行为类，展示该行及文件可能移动的位置，仅在同意后更新或删除。buried_rules：启发式，要说明；可提议把列出的强调规则移到更靠前的位置，绝不改写其措辞。
LOAD_BEARING：绝不触碰，它出现在报告中只是为了让分数保持诚实。
【报告节省】 caveman learn savings 账本按“如何测量”分组，分组不是装饰而是主张的强度：deterministic_remeasure（被编辑文件被重新计数，本地最强阶梯）、interrupted_time_series（前会话 vs 后会话，无对照臂）、unattributed（已记录修复但尚不能归因，不是节省，要说明）。holdout（controlled_holdout）从不出现在账本中，只来自 caveman learn experiment report，要作为独立结果放在账本旁边，绝不累加进去。目前没有命令产生 counterfactual_replay 行，绝不宣称。三条约束：绝不跨阶梯求和，绝不给出混合的单一节省标题；呈现为胜利的行必须读出混杂因素；读 attribution.provenance——intact 表示文件仍带有建议的编辑，changed_since 表示有人改过、部分增量不是我们的，target_missing 表示增量无法归因，not_fingerprinted 表示修复早于指纹机制、编辑存在性未验证，实验带 not_applicable；绝不把 changed_since 或 target_missing 行当作 caveman 成果呈现。回归项按设计不带金额，要如实呈现其结论并提供回滚路径，不淡化也不省略。
【约束】每次编辑单独同意，不允许隐藏各条 diff 的“全部应用”。编辑应用且重新测量门槛通过后运行 caveman learn applied <sink_id>，未来 learn 运行据此报告纵向结论：improved、unchanged、regressed 或 insufficient_data；regressed 要诚实呈现并提供该编辑的确切回滚路径。每次编辑可逆：报告确切改了什么；offload 用 caveman mem forget 加恢复被裁剪的源文件来撤销。仅限推断，绝不把本地数字当作已验证；只有在报告本身带有货币时（spend 及有定价的节省行）才允许用货币，并保持该区块自身的框架——限定窗口、绝不外推、绝不声称已验证。分析器 caveman learn 是只读的，本技能是唯一的写入者，且只在用户同意后写入。