Caveman 探索与委派机制详解：Explorer、Cavecrew 子代理与 Delegate 工具的上下文隔离设计

在 Caveman（一个通过压缩 token 开销来优化 Claude Code 等编码代理工作流的开源项目）中，本文聚焦 探索与委派文档 讲解的核心问题：宽范围仓库检索会在开始编辑前耗尽主代理的上下文。Caveman 提供了只读 explorer 代理、三个紧凑委派的 Cavecrew 子代理，以及可选的 caveman-delegate MCP 工具，让搜索过程与结果留在独立上下文中，只把证据交还给解决者。读完本文，你将掌握这三套机制的安装命令、权限契约、输出格式约定与模型覆盖配置，并能根据任务特征决定何时委派、何时直查。

1. 问题背景：为什么搜索会吃掉主上下文

代理在处理"X 定义在哪里"这类问题时，通常要在主线程里连续发起多次文件读取和搜索。从 Cavecrew 决策指南 的说明可以看到，子代理的工具结果会被逐字注入主上下文——一次返回 2k token 散文的探索调用，每次都要在主上下文里支付 2k token 的预算。文档的解法是机制隔离：让搜索记录留在子代理自己的会话里，主代理只接收经过压缩的证据。

需要强调文档中的一个关键界定：隔离是机制，不是结果保证。explorer 和委派调用本身也会消耗模型用量，只有在总任务用量和解决质量上做了对比之后，才能声称净收益为正。

2. FastContext 风格 Explorer：只读定位代理

2.1 安装命令

CLI 提供了一个名为 fastcontext 的 Claude Code 代理文件，受 FastContext 研究启发，但不实现该论文的训练模型、也不继承论文报告的结果。安装分两个作用域：

# 为当前项目安装
cave explore install

# 为当前用户安装（写入 ~/.claude/skills，跨仓库生效）
cave explore install --user

从 CLI 源码看，explore 是一个未列入打印 help 的兼容别名，其实现直接转发到 skills 安装命令：

// packages/cli/src/index.ts
async function explore(rest: string[]) {
  if (rest[0] !== "install") return exploreUsage();
  const agent = flagFrom(rest, "--agent", "claude");
  guardExploreAgent(agent);
  return skills(["install", "caveman-explore", ...rest.slice(1), "--no-pixel"]);
}

即 cave explore install 等价于：

caveman tools skills install caveman-explore --no-pixel

--no-pixel 表示安装纯文本版 SKILL.md，不做 pixel 图像化转换。当前安装器仅支持 Claude Code：源码中的 guardExploreAgent 会对非 claude 目标直接报错退出，提示 codex 需要先在"转录隔离（transcript isolation）"上有专门验证后才接入——这与文档"保留 Codex 集成直到转录隔离有独立证明"的表述一致（见 CLI 入口）。

2.2 权限边界与引用契约

Explorer 只被授予 Read、Glob、Grep 三个工具，不能编辑文件、不能执行命令（见 explorer 代理定义 的 frontmatter：tools: Read, Glob, Grep，model: haiku）。它的输出契约是每行一个经过验证的引用：

path/to/file.ext:START-END  reason location matters

规则细节：

• 行号区间必须来自 explorer 实际读取过的文件内容，禁止臆造或估算，也不得引用超出文件末尾的区间；
• 精确的小区间优于模糊的大区间；
• 回复必须是且仅是证据块——每行一个引用，无前言、无解释、无 markdown 标题；
• 当确实找不到相关内容时，契约要求返回单行 no relevant locations found，而不是编造引用。文档明确指出这种诚实回答优于猜测。

2.3 工作方式：并行撒网，尽快收网

explorer 代理定义 正文规定了工作节奏：第一轮就并行发起多个工具调用，同时覆盖互补假设——用 Glob 匹配候选路径模式、用 Grep 匹配符号和字符串、用 Read 直读最有希望的文件；之后最多再追一两轮证据即可收手。它优化的是"解决者的 token 预算"，所以越快结束越好。

2.4 何时使用、何时跳过

文档给出的使用判据：

• 使用：冷启动定位（cold-start localization）、跨文件的宽范围关系梳理、或"否则会在解决者上下文里堆入大量文件读取"的搜索；
• 跳过：任务已经指名了精确文件或符号，或此前的证据已经提供了可用位置。

explorer 代理定义 的 description 字段把同一判据浓缩成了代理自身的系统提示，保证代理在会话内也会自我约束："如果精确文件或符号已经指名，跳过我。"

3. Cavecrew：三个紧凑委派的 Claude Code 子代理

cavecrew 是一组决策指南，覆盖三个 Claude Code 子代理。Cavecrew 技能文件 的定位是：它们做的工作与 Anthropic 默认子代理（Explore、编辑型代理、reviewer）相同，区别在于返回的工具结果经过 caveman 压缩，每次委派让主上下文缩水。

3.1 三个子代理的分工

子代理	权限与输出	适用场景
Investigator	只读位置清单	定义、调用方、测试
Builder	手术式编辑	一到两个已知文件
Reviewer	紧凑发现项	Diff 或文件评审

三个代理的完整定义分别位于 cavecrew-investigator、cavecrew-builder 和 cavecrew-reviewer。

cavecrew-investigator：只读代码定位器。输出为 path:line — 符号 — 不超过 6 词注释 的位置表，3 行以上用单词表头分组（Defs: / Refs: / Callers: / Tests: / Imports: / Sites:），单命中只出一行无表头，零命中输出 No match.，末尾给出统计行（如 2 defs, 5 refs.）。被要求修复时拒绝并回 Read-only. Spawn cavecrew-builder.。注意它的 frontmatter 里除了 Read/Grep/Glob 还包含 Bash——但限定用途是 git log -S/git grep/find 这类只读检索加速，不做变更操作。其 description 声称输出相比原生 Explore 让主线程少消耗约 60% token（见 investigator 定义 与 explorer 对比说明）。

cavecrew-builder：手术式 1-2 文件编辑，适用于错别字修复、单函数重写、机械重命名、注释清理等范围明确的小改动。工具集为 Read, Edit, Write, Grep, Glob，没有 Bash——不能执行 shell 命令、不能 push、不能删除。硬规则：3 个及以上文件范围直接拒绝（too-big. split: <n one-line tasks>.）；主代理应自己负责更大的重构与跨组件决策。它的输出是"diff 回执"（receipt）：

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

另有三种终止态首词：too-big. / needs-confirm. / ambiguous. / regressed.，主线程可据此直接决策。

cavecrew-reviewer：diff/分支/文件评审器，每个发现项一行、带严重度标签、无客套话、无范围蔓延，格式为 path:line: <emoji> <severity>: <problem>. <fix>.，严重度分四级：🔴 bug（错误输出、崩溃、安全漏洞、数据丢失）、🟡 risk（边界情况、竞态、泄漏、性能断崖、缺失守卫）、🔵 nit（风格命名，仅在用户要求 thorough 时输出）、❓ question（需作者意图才能判断）。零发现输出 No issues.。

3.2 委派决策与串联模式

Cavecrew 技能文件 给出一张任务到代理的路由表，核心口诀是："如果你希望子代理输出以 1/3 的 token 交付，选 cavecrew；如果你希望散文，选原生代理。" 三条串联模式：

• 定位 → 修复 → 验证（最常见）：investigator 返回位置清单 → 主线程挑 1-2 个位置交给 builder → reviewer 审计 diff；
• 并行侦察（调查面很宽时）：一条消息里并发 2-3 个 investigator（defs / callers / tests 不同角度），主线程聚合；
• 单点编辑（位置已知时）：跳过 investigator，直接把精确 path:line 交给 builder。

对应的反模式：不知道文件位置时不要用 builder（否则主线程要费 token 传上下文）；不要为 5 文件重构串 investigator→builder（builder 会返回 too-big.，浪费一轮）。

3.3 模型覆盖：CAVECREW_*_MODEL 环境变量

每个子代理可以单独指定模型：

CAVECREW_REVIEWER_MODEL
CAVECREW_BUILDER_MODEL
CAVECREW_INVESTIGATOR_MODEL

覆盖的实现位于 cavecrew-model-overrides，由 caveman-activate.js 在 SessionStart 早期调用。源码揭示了文档"只补丁已安装代理 frontmatter 的 model 行"这一行为的完整规则：

• 变量未设置或为空 → 无操作；
• 值包含换行或控制字符（\x00-\x1f\x7f）→ 忽略；
• 已有 model: 行 → 原位替换（如 investigator 默认的 model: haiku）；
• 没有 model: 行 → 插入到 tools: 之后，或关闭分隔符 --- 之前；
• 文件缺失或不在插件布局内 → 静默无操作；所有文件系统错误静默失败，绝不阻塞会话启动。

此外该 hook 还有一层安全防御（见 源码）：若插件根目录位于 git 工作树内，说明当前运行的是源码 checkout 而非已安装插件——此时覆盖会被跳过，否则每次打开仓库，SessionStart 都会重写被跟踪的 agents/*.md 文件并弄脏工作树。这与文档提醒的"插件更新或重新安装会替换补丁"共同构成使用时必须了解的两个限制。

4. 可选的 caveman-delegate MCP 工具

CLI 在 execute.delegate 配置项开启时可以注册 caveman-delegate MCP server。它是显式 opt-in 的，因为委派工作会消耗独立的权限与模型用量。开启步骤：

caveman tools config set execute.delegate true
caveman tools mcp install claude --server caveman-delegate

从 CLI 源码看，execute.delegate 是一个布尔配置项，默认为 false；wrap 流程会检查该 server 是否已安装，若启用但不可用则向 stderr 提示 "delegate enabled but caveman-delegate server is unavailable; launching without delegate" 并降级为不带 delegate 启动（见 wrap 逻辑）。

delegate server 的实现是一个无依赖的 stdio MCP server（caveman-delegate-mcp），只暴露一个工具 caveman_delegate：在 pi harness 中运行一个有界的子任务并返回 worker 报告加上 provider 上报的用量。源码注释给出了选型理由——pi 子任务约 4.5k token 前缀，而裁剪过的 Claude Code 子进程最小约 30k token。可通过环境变量调参：

CAVE_DELEGATE_PROVIDER    pi provider id（默认 openai-codex）
CAVE_DELEGATE_MODEL       模型 id（默认读取 ~/.codex/config.toml 的 model=，兜底 gpt-5.2-codex）
CAVE_DELEGATE_PI_BIN      pi 二进制路径（默认 pi）
CAVE_DELEGATE_PI_DIR      PI_CODING_AGENT_DIR 覆盖（隔离/测试用）
CAVE_DELEGATE_TIMEOUT_MS  worker 超时（默认 300000 毫秒）

权限边界方面文档的表述与实现一致：宿主代理和 server 各自拥有确切的沙箱与审批行为；启用该功能不会授予超出宿主配置允许范围的更宽权限。

5. 证据规则：如何诚实地评估隔离收益

文档最后列出了五条必须遵守的评估规则，它们同样适用于使用 explorer 与 Cavecrew 的任何人：

1. 把 explorer 和委派调用计入总用量——子代理调用本身就是模型开销；
2. 不要从"返回的散文更短"推断整任务的节省——短输出 ≠ 净节省，必须对比总 token；
3. 存在行号漂移（line drift）可能时，编辑前先验证引用——explorer 给出的 START-END 区间基于它读取时的文件状态；
4. 基准测试中保留失败与无结果案例——no relevant locations found 这类诚实的负结果同样需要被测量；
5. 把论文结果当作外部研究，而非本包的性能数据——FastContext 的指标不能移用于 Caveman。

6. 小结

Caveman 的探索与委派体系围绕一个原则设计：让主代理只接收证据，不接收过程。只读 explorer 用"每行一个引用"的契约把定位任务隔离出去；Cavecrew 用三个带严格输出格式与拒绝规则的子代理覆盖定位、小编辑、评审三类高频委派；caveman-delegate 则提供了一个低前缀开销的独立 worker 通道，并以 opt-in 与宿主权限为边界。三者共同的前提是文档反复强调的评估纪律：隔离只是机制，净收益必须用总任务用量与解决质量来验证。相关实现可继续在 explorer 定义、三个子代理定义、Cavecrew 决策指南、模型覆盖 hook 和 delegate server 中查证。