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 ---各字段的作用字段取值含义namecavecrew-investigator子代理标识符主线程通过它发起委派description只读代码定位器声明适用任务面与不提出修复的行为契约其中~60% fewer tokens是定义文件自身的预期表述toolsRead, Grep, Glob, Bash工具白名单——注意有Read但没有Edit/Write从权限层面强制只读modelhaiku定位任务不需要最强模型用小模型进一步降低成本可通过环境变量覆盖见后文正文第一行是全局风格指令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-buildercavecrew-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 类任务用它而非逐个ReadRead只读特定行区间避免把整个文件灌进子代理上下文——子代理虽然不占主线程预算但它自己的上下文同样消耗 token 成本Bash是加速器而非替代只允许git log -S定位引入符号的提交、git grep跨文件/含已删除文件的搜索、find文件系统层面查找这类比 Grep 工具更快的场景。与同家族成员对比可以看得更清楚cavecrew-builder的工具列表是Read, Edit, Write, Grep, Glob刻意不含 Bashcavecrew-builder.md 写明 NoBashavailable — cannot shell out, cannot push, cannot delete而cavecrew-reviewercavecrew-reviewer.md虽然带Bash但限定only forgit diff/git log -p/git showNo 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 Zcavecrew-investigator同上但还想要建议/架构评论Explore原生外科手术式编辑≤2 个文件cavecrew-builder新功能 / 3 文件 / 跨切面重构主线程审查 diff/分支/文件cavecrew-reviewer你已知的单行答案主线程不委派经验法则如果你希望子代理输出以 1/3 的 token 返回选 cavecrew如果希望散文选原生代理。技能文档还给出了三种典型编排模式investigator 是前两种的起点Locate → fix → verify最常用investigator 返回位置清单 → 主线程挑 1-2 处交给 builder 修改 → reviewer 审 diffParallel 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 servercaveman tools config set execute.delegate truecaveman tools mcp install claude --server caveman-delegate用于把委派工作显式化——它是 opt-in 的因为委派消耗独立的权限与模型用量且沙箱行为最终由宿主代理配置决定。小结cavecrew-investigator的设计可以浓缩成四句话工具白名单砍掉写权限提示词砍掉修复建议输出契约砍掉散文模型选择砍掉成本。它的价值不在于搜索得更快而在于把子代理返回物变成主线程可直接解析、可直接验证的file:line证据表——每一行都能在 src/hooks/caveman-config.js 这类真实源码里核到行号。对于需要在长会话中反复探查代码的 Claude Code 工作流这套只读定位 压缩输出 拒绝越权的组合是控制主上下文膨胀的一个可复制的参考实现。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考