Agentsop Repo Map

Repo-Map — 让 LLM 在大仓库里找到正确文件

一句话：tree-sitter 抽取符号 → 在跨文件引用图上跑 PageRank → 按 token 预算把最重要的 class/function 签名作为只读地图塞进上下文。它不是 RAG、不维护向量索引、可被人审。Aider 用同样的机制在 SWE-Bench Lite 上把"正确文件命中率"打到 70.3% [aider.chat/2024/05/22/swe-bench-lite.html]。

这是一个工具技能（tool skill），不绑定 Aider；任何 coder-agent harness 只要能给 LLM 喂上下文，都可以接入或自建 repo-map。

1. 何时激活本技能

下列任一条件成立时，将"构建/刷新/使用 repo-map"作为该会话的标准动作：

• 任务涉及 多文件编辑 或 跨文件影响分析（rename、抽函数、改 API 签名、加 hook 点）。
• 仓库 ≥ ~20 个源文件，或 LLM 无法靠记忆/猜测找到正确目标。
• 你不想（或不能）维护 embedding 索引：环境无 GPU、不允许出仓数据、PR 评审需可追溯证据。
• 你想给 LLM 可审计的导航地图（vs. 黑盒向量检索）。/map 一样的 dump 必须能给人看。
• 多文件编辑后 LLM 反复改错文件、编造路径、SEARCH/REPLACE 找不到目标——典型的"没地图就乱走"信号。
• 你在写自定义 coder agent，需要一个"廉价、确定性、即时刷新"的代码 context 原语。

不应激活的反面信号：单文件改动且文件已知；任务是从零起项目；二进制资产仓库；非源代码（CSV/data lake）—— 详见 §6。

2. 核心心智模型

2.1 三个原语 + 两个不变量

+----------------------+   +-----------------------+   +-----------------------+
| 1. tree-sitter       |   | 2. cross-file graph   |   | 3. token budget       |
|    symbol extraction |-->|    + PageRank-style   |-->|    (dynamic, shrink   |
|                      |   |    importance rank    |   |    when files added)  |
| - parse, no execute  |   | - nodes = files       |   | - default ~1k tokens  |
| - class / fn / sig   |   | - edges = symbol refs |   | - cap configurable    |
| - works offline,     |   | - PageRank picks      |   | - 0 = disabled        |
|   no LLM call        |   |   "most referenced"   |   |                       |
+----------------------+   +-----------------------+   +-----------------------+
                                       |
                                       v
                       +-----------------------------------+
                       | Output: skeleton text in prompt   |
                       | (NOT a tool-call, NOT a vector)   |
                       |                                   |
                       |   path/to/file.py:                |
                       |     class Auth:                   |
                       |       def login(user, pwd) -> T   |
                       |       def logout() -> None        |
                       |     def hash_password(pwd) -> str |
                       +-----------------------------------+

不变量 A — Skeleton over snippets：地图只放 签名/类名/函数名，不放函数体。LLM 真要看实现，就让它点名要文件——这是 read-only navigation aid，不是 retriever。

"If it needs to see more code, the LLM can use the map to figure out which files it needs to look at." [aider.chat/docs/repomap.html]

不变量 B — Dynamic budget：当对话还没加载任何文件时，地图展开到上限（给 LLM 最多导航信息）；一旦真的把文件加进可读写上下文，地图自动收缩（省下的 token 让给真代码）。

"Aider adjusts the size of the repo map dynamically based on the state of the chat." [aider.chat/docs/repomap.html]

2.2 为什么不用 embeddings/RAG（设计决策）

核心判据：编辑代码的瓶颈是"找到要改的文件"，不是"找到语义相近的段落"。LLM 在签名级别上做"我该改哪里"的推理远比让向量替它推理强。

Aider's repo-map "successfully identified the correct file to edit in 70.3% of the benchmark tasks." 这一数字不依赖 embeddings、不依赖代码执行、不依赖网络 [aider.chat/2024/05/22/swe-bench-lite.html]。

2.3 LLM 看到的上下文分三层（优先级递减）

铁律：repo-map 是地图，不是写集合。LLM 看见某个文件在地图里 ≠ 它能编辑它。写集合永远只由人/agent 显式声明（在 Aider 里是 /add；在自建 harness 里是"可编辑文件白名单"）。这条边界是 repo-map 安全使用的前提。

2.4 25k token 的稀释阈

"Above about 25k tokens of context, most models start to become distracted." [aider.chat/docs/troubleshooting/edit-errors.html]

repo-map 本身就在 token 预算里。如果地图占太大，反而稀释了真正的源码上下文。所以预算需要"够找路 + 不挤压代码"。经验起点：1k–4k tokens；monorepo 上限 8k；超过就要靠子目录/ignore 文件先缩小搜索范围（§3 Phase 4）。

2.5 Skeleton-over-snippets 的工程含义

skeleton 给"哪儿"，snippets 给"怎么"。永远先 skeleton，再 snippets——倒过来会把预算烧光、还没找到对的文件。

3. SOP 工作流

Phase 1 — Bootstrap：建图（每会话一次）

1. 确认仓库类型：源码 + git 历史。否则不要用 repo-map（见 §6）。
2. 应用 ignore 列表：
     - .gitignore（必）
     - 自定义 ignore（如 Aider 的 .aiderignore；自建 agent 可直接复用）
     - 默认排除：vendor/, node_modules/, dist/, build/, *.min.js, generated/
3. 选定 tree-sitter 语言集：
     - 主流（Python/JS/TS/Go/Rust/Java/C/C++/Ruby/PHP/...) 默认开
     - 小众语言：要么接 grammars，要么留作 fallback（只列文件路径）
4. 设定 token 预算：
     - 小仓库（<200 文件）: 1k–2k
     - 中等（200–2000 文件）: 2k–4k
     - Monorepo（>2000 文件）: 4k–8k + 限定子目录
5. 首次运行：构建符号表 + 引用图 + PageRank。后续增量更新。

输出物：一段纯文本骨架（path + 类/函数签名），符合 token 预算。

Phase 2 — Use：让 LLM 用地图回答"改哪里"

反模式：人类拍脑袋决定加哪些文件 → 漏文件、加多文件。

正确模式：把"定位"问题外包给 LLM + repo-map。

[harness 提供给 LLM 的上下文]
- system prompt
- repo-map skeleton (read-only)
- task: "Add JWT-based auth replacing session cookies"

[LLM 输出]
- 候选目标文件: src/auth.py, src/middleware.py, tests/test_auth.py
- 候选只读引用: src/config.py, docs/auth.md

然后 harness 才把 LLM 命名的文件真正加入写集合。这一步是 repo-map 的唯一调用价值：把"navigation"从人脑卸载给 LLM。

Phase 3 — Refresh：何时重建地图

关键认知：地图过期的代价不是错，是幻觉——LLM 会以为某符号还存在/还在某处。每次 LLM 报告"找不到 X"时，第一反应是"地图过期了吗？"，第二反应才是"真的不存在吗？"

Phase 4 — Scope：地图也撑不住时

地图 > 8k token 仍然稀释信号？这是仓库太大、问题太宽的信号，不是地图的问题。逐步收缩：

1. Subtree-only: 把工作目录定到 packages/feature-foo/，只对这棵子树建图。
2. Ignore 扩展: 把 generated/、proto/、vendored/、test fixtures 全 ignore。
3. Domain split: 一次会话只覆盖一个领域（auth / payment / search 三选一）。
4. Map-tokens 0: 已经知道改哪些文件 → 直接关闭地图，节省所有 token 给代码。
5. 拆任务: 大需求拆成多会话，每会话一个收敛子目标。

判断阈：如果你不能在一句话内描述"这次任务影响哪一类模块"，那 repo-map 帮不了你——先用 /ask 类讨论 narrow 任务范围，再激活地图。

Phase 5 — Audit：把地图当可审计文物

repo-map 的最大优势是可以打印给人看：

• /map (Aider) 或等价的 dump_map() 钩子：用于 reviewer 复现"LLM 看到了什么"。
• 把当次 repo-map 存到 intermediate/repo-map-<sha>.txt，作为 PR 附件——比 "trust the agent" 强。
• 当 LLM 决策可疑时，diff 两次地图：是地图变了，还是 LLM 推理变了？

4. 操作模型（通用操作，去 Aider 化）

每条操作给 Trigger / Action / Output / Evidence。命令名是参考，实际接口取决于你的 harness。

Op 1 — map.build(root, budget, ignore) 构建/重建

• Trigger：会话开始；或大规模重构后；或切换工作根。
• Action：遍历 root 下所有匹配 tree-sitter 的源文件 → 抽符号 → 建跨文件引用图 → 跑 PageRank → 按 budget 截取顶部 → 渲染 skeleton。
• Output：纯文本，形如 path:\n class X:\n def foo(a: T) -> U。
• Evidence：[aider.chat/docs/repomap.html] "concise map … includes the most important classes and functions along with their types and call signatures"。

Op 2 — map.refresh(files) 增量刷新

• Trigger：某文件被 LLM 或人编辑；或 LLM 提示"找不到符号"但应存在。
• Action：只对 files 重抽符号，更新引用图边集，重跑 PageRank（局部）。
• Output：新的 skeleton。
• Evidence：Aider --map-refresh 文档；动态预算"adjusts ... based on the state of the chat" [aider.chat/docs/repomap.html]。

Op 3 — map.scope(subtree | glob) 缩范围

• Trigger：monorepo；或仓库 > 2000 文件；或地图 > 8k token。
• Action：把 PageRank 跑在 subtree 内或 glob 命中的文件上，根之外的文件最多保留路径不渲染签名。
• Output：更瘦的 skeleton。
• Evidence：Aider --subtree-only；.aiderignore。

Op 4 — map.print() / dump 可审计

• Trigger：reviewer 要求；或决策不解；或写 PR description。
• Action：直接打印当前 skeleton。
• Output：plain text，存 intermediate/repo-map-<sha>.txt。
• Evidence：Aider /map。"deterministic & inspectable"（地图是确定性产物，不是模型采样）。

Op 5 — map.locate(task_description) 让 LLM 找文件

• Trigger：任务进来但写集合未定。
• Action：把 task_description + repo-map 喂给 LLM，要求输出"目标文件 + 引用文件"两组路径。不让 LLM 直接编辑，只让它命名。
• Output：候选文件列表（建议 ≤5 个写集合 + ≤3 个只读）。
• Evidence：SWE-Bench Lite 上 repo-map 让 Aider 70.3% 命中正确文件 [aider.chat/2024/05/22/swe-bench-lite.html]。

Op 6 — map.budget_set(N) / map.disable() 调预算

• Trigger：上下文超 25k；或目标文件已锁定（地图无用）。
• Action：缩小或归零 --map-tokens 等价物。N=0 等于完全关闭。
• Output：更瘦上下文。
• Evidence：Aider --map-tokens；25k 阈值 [aider.chat/docs/troubleshooting/edit-errors.html]。

Op 7 — map.ignore_add(patterns) 加排除

• Trigger：地图被 node_modules / generated/*.pb.go 类垃圾撑大。
• Action：写入 ignore 文件（.aiderignore / 等价物）；下次构建生效。
• Output：更聚焦的地图。
• Evidence：Aider 文档；通用做法。

Op 8 — map.diff(prev, curr) 地图差分

• Trigger：怀疑地图过期；或大规模 rename 后审计；或调试 LLM 反复改错文件。
• Action：对比两次 skeleton 文本 diff。
• Output：新增/消失/重命名的符号列表。
• Evidence：repo-map 是文本 → 任何 diff 工具都能跑。这是 embedding 系统做不到的可观测性。

5. 困境决策案例 (Examples / Scenarios)

案例 1 — Repo too big：地图撑大了反而稀释信号

触发：monorepo 10k+ 文件；首次 map.build 出来的 skeleton 接近 8k token，主对话快要破 25k。LLM 开始忽视细节、编辑跑偏。

症状：

• /tokens（或等价物）显示 map 占比 > 40%。
• LLM 答非所问，给出的修改散在十几个文件里。
• 25k 阈值越线，模型注意力分散 [aider.chat/docs/troubleshooting/edit-errors.html]。

决策树（按代价递增）：

反模式：把地图开到 16k 期望"看全"——LLM 会被噪声呛死。地图不是越大越好；它的价值是"navigation precision per token"。

为什么这有效：repo-map 的 PageRank 已经在按重要性排序，预算砍掉的是长尾低相关符号，不是核心 API。再加 ignore 排除生成代码，信噪比改善是非线性的。