caveman cavecrew-investigator：只读代码定位子代理与压缩输出契约设计-二趣网

caveman cavecrew-investigator：只读代码定位子代理与压缩输出契约设计

【免费下载链接】caveman🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman

在大型仓库中做代码探查，主代理上下文往往还没开始写代码就被搜索结果耗尽。caveman 项目的cavecrew-investigator是一个为 Claude Code 定义的只读子代理（subagent）：它专门回答"X 定义在哪、谁在调用 Y、Z 有哪些用法、这个目录长什么样"这类问题，并以 caveman 压缩格式返回file:line表，拒绝提供任何修复建议。读完本文，你将理解该子代理的完整定义（frontmatter、职责边界、输出契约、工具策略、拒绝话术），以及它的输出格式如何在仓库真实源码中得到验证。

定义文件与 frontmatter

子代理定义位于 cavecrew-investigator.md，遵循 Claude Code 的 agent markdown 格式：YAML frontmatter 声明元数据，正文即系统提示词。frontmatter 全文如下：

--- name: cavecrew-investigator description: > Read-only code locator. Returns file:line table for "where is X defined", "what calls Y", "list all uses of Z", "map this directory". Output is caveman-compressed so the main thread eats ~60% fewer tokens than vanilla Explore. Refuses to suggest fixes. tools: [Read, Grep, Glob, Bash] model: haiku ---

各字段的作用：

字段	取值	含义
`name`	`cavecrew-investigator`	子代理标识符，主线程通过它发起委派
`description`	只读代码定位器	声明适用任务面与"不提出修复"的行为契约；其中"~60% fewer tokens"是定义文件自身的预期表述
`tools`	`Read, Grep, Glob, Bash`	工具白名单——注意有`Read`但没有`Edit`/`Write`，从权限层面强制"只读"
`model`	`haiku`	定位任务不需要最强模型，用小模型进一步降低成本（可通过环境变量覆盖，见后文）

正文第一行是全局风格指令：

Caveman-ultra. Drop articles/filler/hedging. Code/symbols/paths exact, backticked. Lead with answer.

即：丢弃冠词、填充词和模糊限定语；代码、符号、路径必须精确并加反引号；先给答案。这与 caveman 项目"少说人话废话、省 token"的整体设计一致。

职责边界：Locate. Report. Stop.

原文档对 Job 的定义只有两句：

Locate. Report. Stop. Never edit, never propose fix.

配合 Refusals 一节，当用户越界提问时，子代理按固定话术拒绝：

Asked to fix → Read-only. Spawn cavecrew-builder. Asked to design → Read-only. Spawn cavecrew-builder or use main thread.

这里有两个设计意图：

权限与提示词双重约束。工具白名单里没有Edit/Write，即使模型想改代码也做不到；提示词层面则要求它"永不提议修复"，避免输出里混入主线程不需要的改造方案。
拒绝即路由。Read-only. Spawn cavecrew-builder.不是冷冰冰的拒绝，而是告诉主线程下一步该找谁——cavecrew-builder（cavecrew-builder.md）正是 cavecrew 三件套中负责"1-2 个文件的外科编辑"的成员。定位、编辑、审查三个子代理各司其职，互不越权。

输出契约：可 grep 的 file:line 表

## Output一节定义了严格的返回格式，这是整个设计中最关键的部分：

<path:line> — `<symbol>` — <≤6 word note> <path:line> — `<symbol>` — <≤6 word note>

配套规则逐条解释：

三行以上才加分组头：Defs:/Refs:/Callers:/Tests:/Imports:/Sites:，且只用一个单词；
单条命中：一行输出，不加头；
零命中：固定返回No match.（不允许编造引用）；
末行统计：如2 defs, 5 refs.，命中数为 0 或 1 时省略统计行。

这套格式不是"写得短"而已，它是给主线程消费的机器可读契约。cavecrew 技能文档在 Output contracts 中明确写道：

Always file-path-first, line-number-attached, backticked symbols. Safe to grep withpath:\d+.

也就是说，主线程（或人）拿到 investigator 的输出后，可以直接用path:\d+正则抽取所有位置引用、用词法头（Defs:等）切分组别——因为格式被钉死了，下游无需自然语言理解。对比之下，Anthropic 原生的Explore返回散文式描述，无法程序化解析。

工具策略：四种工具各有分工

## Tools一节给出各工具的分工：

`Grep` for symbols/strings. `Glob` for paths. `Read` only specific ranges. `Bash` for `git log -S`/`git grep`/`find` when faster.

要点拆解：

Grep负责符号/字符串定位：绝大多数 "where is X defined" 靠正则搜索即可，不必整文件读取；
Glob负责路径模式匹配："map this directory" 类任务用它而非逐个Read；
Read只读特定行区间：避免把整个文件灌进子代理上下文——子代理虽然不占主线程预算，但它自己的上下文同样消耗 token 成本；
Bash是加速器而非替代：只允许git log -S（定位引入符号的提交）、git grep（跨文件/含已删除文件的搜索）、find（文件系统层面查找）这类比 Grep 工具更快的场景。

与同家族成员对比可以看得更清楚：cavecrew-builder的工具列表是Read, Edit, Write, Grep, Glob，刻意不含 Bash（cavecrew-builder.md 写明 "NoBashavailable — cannot shell out, cannot push, cannot delete"）；而cavecrew-reviewer（cavecrew-reviewer.md）虽然带Bash，但限定"only forgit diff/git log -p/git show，No mutating commands"。investigator 的Bash权限介于两者之间：能执行但只用于只读的搜索加速命令。

Auto-clarity：压缩模式的例外通道

Security warnings, destructive ops → write normal English. Resume after.

这是 cavecrew 三个子代理共享的规则（技能文档称之为 "Auto-clarity (inherited)"）：一旦涉及安全警告或不可逆/破坏性操作的确认，子代理必须暂时退出 caveman 压缩风格、改用正常英文，防止碎片化短语被误读，说完再切回压缩风格。对只读的 investigator 而言，典型触发场景是：在定位结果中发现明显的安全漏洞（如符号链接逃逸、凭据外泄路径），此时宁可多花几个 token 也要把风险说清楚。

用仓库真实源码验证一个示例

原文档自带一个端到端示例（文档中的行号是该示例所在仓库布局下的数值，此处按当前仓库实际行号重新验证）：

Q: "where symlink-safe flag write?"

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.

用同一问题在当前仓库跑一遍定位，输出应当形如（按仓库实际位置）：

Defs: - src/hooks/caveman-config.js:168 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW - src/hooks/caveman-config.js:289 — `readFlag` — symlink-refusing paired reader Callers: - src/hooks/caveman-activate.js:171,448 - src/hooks/caveman-mode-tracker.js:86,88 - src/hooks/caveman-stats.js:666 Tests: - tests/test_symlink_flag.js 2 defs, N callers, 1 test file.

每一条都能在源码中核到：

safeWriteFlag定义于 caveman-config.js。其"≤6 词注释"里的atomic write w/ O_NOFOLLOW精确对应实现：以O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW标志、0o600权限写临时文件，再renameSync原子替换；父目录若是符号链接，先realpath并校验目标属主/位于 home 内；rename 遇EPERM/EBUSY等瞬时锁冲突时用Atomics.wait阻塞退避、重试 3 次。
readFlag定义于 caveman-config.js，源码注释写明它与safeWriteFlag对称：拒绝符号链接、以MAX_FLAG_BYTES = 64硬上限封顶、白名单校验取值——防止本地攻击者把标志文件换成指向~/.ssh/id_rsa的符号链接实施信息外泄。
调用方在src/hooks/caveman-activate.js（会话激活时落盘模式标志）与src/hooks/caveman-mode-tracker.js（每轮追踪）中确实存在，且都先对safeWriteFlag做了typeof === 'function'的防御性检查再解构使用。
测试位于 test_symlink_flag.js，文件头注释说明它覆盖 issue #207 的修复："safeWriteFlag refuses flag writes when ~/.claude is a symlink"。

这个对照正好展示了输出契约的价值：一份 7 行的定位报告，每行path:line都可直接跳转验证，主线程不需要再花 2k token 的散文来描述同样的发现。

在 cavecrew 体系中的位置与配套机制

investigator 是 cavecrew 三件套（investigator / builder / reviewer）的"眼睛"。cavecrew 技能文档给出的选型决策表，第一行就是它的地盘：

任务	使用
"Where is X defined / what calls Y / list uses of Z"	`cavecrew-investigator`
同上但还想要建议/架构评论	`Explore`（原生）
外科手术式编辑，≤2 个文件	`cavecrew-builder`
新功能 / 3+ 文件 / 跨切面重构	主线程
审查 diff/分支/文件	`cavecrew-reviewer`
你已知的单行答案	主线程，不委派

经验法则：如果你希望子代理输出以 1/3 的 token 返回，选 cavecrew；如果希望散文，选原生代理。

技能文档还给出了三种典型编排模式，investigator 是前两种的起点：

Locate → fix → verify（最常用）：investigator 返回位置清单 → 主线程挑 1-2 处交给 builder 修改 → reviewer 审 diff；
Parallel scout（探查面很宽时）：一条消息里并行发起 2-3 个 investigator 调用，从 defs / callers / tests 不同角度分头扫，主线程聚合；
Single-shot edit：位置已知时直接跳过 investigator，把精确path:line交给 builder。

对应的反模式同样值得记住：不要用 investigator→builder 链去啃 5 个文件的重构（builder 会返回too-big.终止行，白耗一个回合）；位置未知时直接派 builder 会让主线程浪费 token 反复传上下文。

最后是两个配套机制（见 exploration-and-delegation 技术文档）：

模型覆盖：三个子代理都支持环境变量覆盖模型——CAVECREW_INVESTIGATOR_MODEL（同理CAVECREW_BUILDER_MODEL、CAVECREW_REVIEWER_MODEL）。覆盖只会补丁安装后 agent frontmatter 的model行，空变量不生效，插件更新或重装可能把补丁冲掉。也就是说定义文件里的model: haiku只是默认值，可按机器条件上调；
可选委派通道：CLI 在execute.delegate开启时可注册caveman-delegateMCP server（caveman tools config set execute.delegate true+caveman tools mcp install claude --server caveman-delegate），用于把委派工作显式化——它是 opt-in 的，因为委派消耗独立的权限与模型用量，且沙箱行为最终由宿主代理配置决定。

小结

cavecrew-investigator的设计可以浓缩成四句话：工具白名单砍掉写权限，提示词砍掉修复建议，输出契约砍掉散文，模型选择砍掉成本。它的价值不在于"搜索得更快"，而在于把子代理返回物变成主线程可直接解析、可直接验证的file:line证据表——每一行都能在 src/hooks/caveman-config.js 这类真实源码里核到行号。对于需要在长会话中反复探查代码的 Claude Code 工作流，这套"只读定位 + 压缩输出 + 拒绝越权"的组合，是控制主上下文膨胀的一个可复制的参考实现。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析