Caveman Cavecrew 深度解析：三个压缩型子代理预设，如何在长会话中为 Claude Code 省下主上下文

Cavecrew 是 Caveman 项目内置的一套"委托决策技能"（skill），定义了三个发出"穴居人风格"（caveman-compressed）输出的子代理预设：cavecrew-investigator（定位代码）、cavecrew-builder（1-2 个文件的手术式编辑）与 cavecrew-reviewer（diff 审查）。本篇基于仓库中的 skills/cavecrew/SKILL.md 展开，覆盖完整的任务选型决策矩阵、三个代理的输出契约（output contract）、三种链式调用模式、常见误用，以及结合 src/hooks/cavecrew-model-overrides.js 源码讲解的按代理模型覆盖机制。读完你可以掌握：何时该把任务委托给压缩子代理而不是内联处理、如何按契约解析其返回结果，以及如何用环境变量为每个代理单独指定模型。

一、Cavecrew 是什么：同一工作，更小的返回值

Cavecrew 的定位在 SKILL.md 中一句话概括：

Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (Explore, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.

即：它和 Anthropic 默认的子代理（Explore、编辑类代理、Code Reviewer）干的是同一类工作，唯一区别是返回给主线程的工具结果被压缩过。三个预设的职责划分如下（来自 skills/cavecrew/README.md）：

子代理	职责	适用场景
cavecrew-investigator	定位代码（只读）	"X 定义在哪 / 谁调用了 Y / 列出 Z 的所有用法"
cavecrew-builder	手术式编辑，1-2 个文件	范围明确、≤2 个文件；3 个以上文件直接拒绝
cavecrew-reviewer	diff/文件审查	单行一条 finding，带严重度 emoji

需要强调的是，Cavecrew 是一个决策指南（decision guide）而非斜杠命令——当对话中出现委托相关措辞时它自动激活，触发短语包括 "delegate to subagent"、"use cavecrew"、"spawn investigator"、"save context"、"compressed agent output" 等。

二、任务选型：cavecrew vs 原生代理 vs 主线程

SKILL.md 给出的完整选型表是整套机制的核心，完整保留如下：

任务	应使用
"X 定义在哪 / 谁调用 Y / 列出 Z 的用法"	cavecrew-investigator
同上，但你还想要建议/架构评论	Explore（原生）
手术式编辑，≤2 个文件，范围明确	cavecrew-builder
新功能 / 3+ 文件 / 横切式重构	主线程或 feature-dev:code-architect
审查 diff、分支或文件中的 bug	cavecrew-reviewer
深度代码审查，带论证 + 替代方案	Code Reviewer（原生）
你已知答案的一句话回答	主线程，不用子代理

经验法则（rule of thumb）原文为："if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla." —— 如果你希望子代理的产出只占 1/3 的 token，选 cavecrew；如果你想要完整散文式输出，选原生代理。

为什么这有价值：token 经济学

SKILL.md 用一段话解释了"真正的收益"：

Subagent tool results get injected into main context verbatim. A vanilla Explore that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from cavecrew-investigator returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.

关键点在于：子代理的工具结果会被原样注入主上下文。每次委托都是一笔"上下文预算支出"，而压缩输出把单笔支出从约 2k 降到约 700 token（该数值为文档给出的示例量级，实际取决于任务）。一次会话内 20 次委托下来，这就决定了上下文是耗尽还是能完成任务。README.md 对此措辞更审慎：紧凑返回契约可以减少结果回到主上下文时重复的散文，但实际效果取决于任务、代理和委托次数，"This skill publishes no universal reduction rate"（本技能不发布任何通用缩减率）。

三个代理的 frontmatter：工具集与默认模型

从 agents/cavecrew-investigator.md、agents/cavecrew-builder.md、agents/cavecrew-reviewer.md 的 YAML frontmatter 可以看到每个预设的能力边界：

代理	tools	默认模型
cavecrew-investigator	Read, Grep, Glob, Bash	haiku
cavecrew-builder	Read, Edit, Write, Grep, Glob	无 model: 行，使用 API 会话默认
cavecrew-reviewer	Read, Grep, Bash	haiku

从源码结构看，这个工具集设计是刻意的：investigator 有 Bash（用于 git log -S/git grep 等只读加速手段）但没有 Edit/Write；builder 有 Edit/Write 但没有 Bash——代理正文中明确写着 "No Bash available — cannot shell out, cannot push, cannot delete"，从工具层面杜绝了误操作的可能；reviewer 的 Bash 仅限 git diff/git log -p/git show，"No mutating commands"。

三、输出契约：主线程可以机械解析的返回格式

Cavecrew 最重要的工程特性是输出契约（output contract）——主线程可以像解析结构化数据一样处理返回结果，而不必消化自由文本。以下完整继承 SKILL.md 中的契约定义，并补充各代理正文中的细化规则。

cavecrew-investigator：文件路径优先，行号随行

<Header>:
- path:line — `symbol` — short note
totals: <counts>.

无命中时固定返回 No match.。规则要点（来自 agents/cavecrew-investigator.md）：

• 文件路径优先、行号随行、符号用反引号包裹，因此输出可以直接用 path:\d+ 正则 grep；
• 3 行以上时用一个单词的分组标题：Defs: / Refs: / Callers: / Tests: / Imports: / Sites:；单条命中则单行无标题；
• 最后一行给总计，如 2 defs, 5 refs.（0 或 1 条时省略）；
• 拒绝修复合：被要求修复时返回 Read-only. Spawn cavecrew-builder.；被要求设计时返回 Read-only. Spawn cavecrew-builder or use main thread.

代理文件内附带的示例输出：

Defs:
- hooks/caveman-config.js:81 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW
- hooks/caveman-config.js:160 — `readFlag` — paired reader
Callers:
- hooks/caveman-mode-tracker.js:33,87
- hooks/caveman-activate.js:40
Tests:
- tests/test_symlink_flag.js — 12 cases
2 defs, 3 callers, 1 test file.

cavecrew-builder：diff 是工件，receipt 是证明

<path:line-range> — <change ≤10 words>.
verified: <re-read OK | mismatch @ path:line>.

或者以"终止首词"开头的拒绝行：too-big. / needs-confirm. / ambiguous. / regressed.。builder 的工作流是固定的四步：Read 目标文件（never edit blind）→ Edit 最小可用 diff → 重新 Read 验证 → 返回 receipt。其正文强调 "Diff is the artifact. Receipt is the proof. No exploration story."（diff 是工件，receipt 是证明，不要附带探索过程叙述）。

四个拒绝分支（terminal lines）各有精确格式：

场景	返回
涉及 3+ 文件	too-big. split: <n one-line tasks>.
需要破坏性操作	needs-confirm. op: <command>.
规格不明确	ambiguous. ask: <one question>.
编辑后测试失败且无法在范围内修复	regressed. revert path:line. cause: <fragment>.

cavecrew-reviewer：单行 finding + 严重度 emoji

path:line: <emoji> <severity>: <problem>. <fix>.
totals: N🔴 N🟡 N🔵 N❓

无发现时返回 No issues.，findings 按文件顺序、文件内行号升序排列。严重度体系完整如下（来自 agents/cavecrew-reviewer.md）：

Emoji	级别	用于
🔴	bug	错误输出、崩溃、安全漏洞、数据丢失
🟡	risk	边界情况、竞态、泄漏、性能悬崖、缺少防护
🔵	nit	风格、命名、微性能——仅当用户要求彻底审查时输出
❓	question	需要作者意图才能判断

边界约束：只审查眼前的 diff（"No 'while we're here'"）、不提大重构方案、需要更多上下文时追加 (see L<n> in <file>) 而非猜测、格式类 nit 除非改变语义否则跳过。

四、链式调用模式

SKILL.md 定义了三种组合方式，这是把三个预设当成"流水线"使用的关键。

1. Locate → fix → verify（最常见）

1. cavecrew-investigator 返回位置清单；
2. 主线程从中挑 1-2 个位置，把 path 交给 cavecrew-builder；
3. cavecrew-reviewer 审查产生的 diff。

2. Parallel scout（调查面很宽时）

在同一条消息中发起 2-3 个 cavecrew-investigator 调用，各带不同角度（defs vs callers vs tests），结果在主线程汇合。

3. Single-shot edit（位置已知时）

跳过 investigator，直接把精确的 path:line 交给 cavecrew-builder。

四条"不要做"

文档同样明确了误用边界，完整继承如下：

• 不要在不知道文件时用 cavecrew-builder——先派 investigator，否则主线程要替它传递上下文，token 白烧；
• 不要用 investigator → builder 链条做 5 文件重构——builder 会返回 too-big.，浪费一个 turn；
• 不要向 cavecrew-reviewer 要"总体评价"——它只返回 findings，没有架构观点，那种需求用原生 Code Reviewer；
• 不要期待散文——cavecrew 输出是结构化的， terse 到有时近乎密码。如果人类要直接阅读，先转述。

五、Auto-clarity：压缩与安全的平衡

三个代理共享一条继承规则（inherited）：遇到安全警告、不可逆操作的确认、以及片段歧义可能被误读的场合，自动从 caveman 切换为正常英文，输出完毕后恢复压缩风格。在各代理正文中这一条被具体化：investigator 的 "Security warnings, destructive ops → write normal English. Resume after."；builder 的 "Security or destructive paths → write normal English warning, then resume caveman"；reviewer 的 "Security findings → state risk in plain English first sentence, then caveman fix line."。这保证了压缩输出在最容易出错的安全语义上不会因省略而产生歧义。

六、按代理指定模型：环境变量覆盖机制

skills/cavecrew/README.md 文档了一组环境变量，允许在不复制整个代理文件的情况下单独固定每个代理的模型：

环境变量	对应代理
CAVECREW_REVIEWER_MODEL	cavecrew-reviewer
CAVECREW_BUILDER_MODEL	cavecrew-builder
CAVECREW_INVESTIGATOR_MODEL	cavecrew-investigator

用法是在启动 Claude Code 前设置，例如让 reviewer 跑在 sonnet 上而其余保持默认：

export CAVECREW_REVIEWER_MODEL=sonnet

取值就是 Claude Code 代理 frontmatter 中可用的模型名字符串（如 haiku、sonnet、opus）。

源码层面：覆盖是如何落盘的

这一机制的实现是 src/hooks/cavecrew-model-overrides.js，在 caveman-activate.js 的 SessionStart 阶段被调用（见 src/hooks/caveman-activate.js 中的 applyOverrides(resolvePluginRoot(__dirname))，且包在 try/catch 中——"Best-effort: any error is swallowed so SessionStart is never blocked"）。核心行为可以从源码直接确认：

1. AGENT_ENV_MAP 将三个环境变量映射到 agents/cavecrew-*.md 三个文件；
2. patchFrontmatterModel 只改 model: 这一行：已有则原位替换，没有则插入到 tools: 行之后（或闭合 --- 之前）；prompt 正文完全不动，继续接收上游更新。含换行或控制字符的取值被直接忽略；
3. resolvePluginRoot 依次尝试 CLAUDE_PLUGIN_ROOT、hook 目录上两级、上一级，取第一个包含 agents/ 目录的候选——兼容插件安装布局与仓库 checkout 布局两种情况；
4. insideGitWorkTree 沿父目录向上探测 .git：如果插件根位于某个 git 工作树内，说明这是源码 checkout 而非已安装插件，直接 no-op。这是为了防止用户打开一个 clone 出来的仓库时，每次 SessionStart 都改写受版本控制的 agents/*.md、弄脏工作区——覆盖只发生在真正已安装的插件目录（位于 $CLAUDE_CONFIG_DIR 下、上方无 .git）；
5. 文件缺失、布局不符、写盘失败等一切错误都是静默 no-op，绝不阻塞会话启动。

对应的单测 tests/test_cavecrew_model_overrides.js 覆盖了替换已有 model: haiku、保留其余 frontmatter 行（name、tools、description 块）、正文不丢失等断言。

使用限制（与 README 一致）：覆盖只修补已安装代理 frontmatter 的 model: 行；空变量无效果；补丁会持久化，直到插件更新或重装为止；只有插件安装才有本地代理文件可被修补。

七、小结

Cavecrew 的本质是一套上下文预算管理机制：用三个工具集、模型和输出格式都经过裁剪的子代理预设，把"委托一次"这件事对主上下文的开销降到最小。它的工程价值不在单个环节，而在契约的机械可解析性（path:\d+ 可直接 grep、终止首词可分支）、链式模式的确定性（Locate → fix → verify），以及拒绝分支的显式化（too-big.、needs-confirm. 等），让主线程无需语义理解就能决定下一步动作。如果你的会话频繁出现委托调用并逼近上下文上限，这套"任务选型表 + 输出契约 + 环境变量模型覆盖"的组合就是 Caveman 项目给出的完整解法。