用 RepoPrompt 降低 Agent 找文件的开销

问题:Agent 把 token 烧在"找路"上

观察一个编程 Agent 的执行轨迹,任务开头往往是这样的:

ls src/ → grep -r "PaymentService" → read payment.ts(800 行)
→ 不对,再 grep → read checkout.ts → read types.ts → ……

真正改代码之前,Agent 可能已经花了几十次工具调用、几万 token 在重新发现仓库结构上。更糟的是:

• 这套探索每个新会话都要重来一遍——上下文不跨会话保留;
• 探索中整读的大文件会一直躺在窗口里吃预算;
• 仓库越大,"找路"占任务总开销的比例越高。

RepoPrompt 是什么

Repo Prompt 是一个 macOS 上的上下文构建工具:让人来主导"选择哪些代码进入上下文",把探索的开销从"每次会话的 token"变成"一次性的准备工作"。核心能力:

1. 文件选择 + 一键打包上下文

用文件树勾选相关文件,RepoPrompt 实时显示已选内容的 token 总量,一键生成结构化的 prompt(文件树 + 文件内容 + 你的指令),粘给任何模型。你比 Agent 更清楚该看哪几个文件时,这比让它自己翻快得多。

2. Codemap:签名级别的仓库地图

Codemap 提取代码的API 骨架——类、函数签名、类型定义、引用关系——而不含实现体:

完整文件:  payment.ts        ~6,000 token
Codemap:   payment.ts 的骨架   ~300 token

把几十个文件的 Codemap 加进上下文,模型就能"看见"整个模块的形状、知道该精读哪里,成本却只有整读的 5% 左右。这与 tokenize 篇的原则一致:给模型信息密度最高的表示。

3. MCP 模式:给 Claude Code / Codex 当"导航员"

RepoPrompt 可以作为 MCP 服务器接入 Claude Code、Codex 等 Agent:

# 接入后 Agent 获得这些能力(工具名以实际版本为准)
manage_selection   # 读写当前文件选择集
get_file_tree      # 带 codemap 的文件树
search             # 结构化代码搜索
context_builder    # 由 RepoPrompt 侧的模型智能挑选相关文件

于是工作流变成:你(或 context_builder)先把相关文件圈好 → Agent 开局就拿到精确的文件清单和骨架地图 → 直接精读目标位置动手,跳过整个"盲目 grep"阶段。

别忘了工具爆炸

RepoPrompt MCP 自身也有十来个工具。按工具爆炸篇的原则,只在需要它的项目里启用,并保持会话边界处增删。

没有 RepoPrompt 时,同样的思想也成立

RepoPrompt 的本质是三条可移植的原则,Linux/Windows 或纯 CLI 环境可以用别的工具达成:

1. 预构建地图,替代现场探索
   • 在 CLAUDE.md / AGENTS.md 里维护目录结构说明和"改 X 去看 Y"的路标;
   • 用 tree -L 2、ctags、或让 Agent 一次性生成 ARCHITECTURE.md 后长期复用;
2. 骨架优先,按需精读
   • 引导 Agent 先 grep -n 定位、再读局部行区间,而不是整文件通读;
3. 人为圈定范围
   • 提任务时直接给出文件清单:"改 src/pay/checkout.ts 和它的测试",一句话省掉 Agent 十轮探索。

类似定位的工具还有 Aider 的 repo map(用 tree-sitter + PageRank 自动生成仓库骨架)等,选择哪个不重要,重要的是:Agent 的探索是最贵的 I/O,能预先固化的就不要现场重算。

收益核算

以一个 5 万行的中型仓库、每天 10 个 Agent 任务估算:

	盲目探索	预构建上下文
每任务探索开销	20~40 次工具调用,2~5 万 token	接近 0(开局即有清单/地图)
窗口占用	大文件整读常驻	骨架 + 目标片段
缓存影响	探索输出撑大每轮增量	前缀小而稳,命中率高
结果	更早 compact、更慢、更贵	更快进入正题、质量更稳