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 |
                       +-----------------------------------+