/agentsop-repo-map

name: agentsop-repo-map
version: 0.1.0
description: >-
  Symbol-level code context for LLM coder-agents: tree-sitter extracts symbols, PageRank ranks them over the cross-file reference graph, and the top class/function signatures are fed to the LLM as a token-budgeted read-only map (not RAG, no vector index, human-auditable). Use when an agent must locate the right files in a large/multi-file repo, when builds/refreshes/scopes a repo-map, or when "model edits the wrong file" needs fixing.
domain: symbol-level code context for LLM coder-agents
source: aider.chat repo-map docs + Paul Gauthier blog + SWE-Bench Lite evidence + cross-tool comparison
audience: coder-agents (Aider/Cline/Cursor/Continue/OpenHands/custom) editing multi-file repositories via LLMs
status: specialized but high-leverage; hits on every multi-file edit

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（设计决策）

| 维度 | Repo-map (tree-sitter + PageRank) | Embedding RAG | |---|---|---| | LLM 可读性 | 真签名，LLM 能直接推理 | 向量，LLM 看不懂；只能信检索器选出的片段 | | 索引维护 | 无；每次会话按需重建 | 需要 chunker + embedder + 向量库 + 失效策略 | | 确定性 | 同代码同输入 → 同地图 | embedding 模型/参数变化 → 检索结果漂移 | | 可审计 | 一段纯文本，能 `cat`、能 diff、能给 reviewer 看 | 黑盒：哪些 chunk 被选不直观 | | 出仓风险 | 全本地静态分析 | 通常调用外部 embedding API | | 失败模式 | tree-sitter 不支持该语言 → 优雅降级 | 语义距离 ≠ 调用关系，错召回 |

**核心判据**：编辑代码的瓶颈是"**找到要改的文件**"，不是"找到语义相近的段落"。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 看到的上下文分三层（优先级递减）

| 层 | 内容 | 写权限 | |---|---|---| | 系统/编辑格式 | harness 固化 | harness | | **Repo-map**（本技能） + read-only files + CONVENTIONS | **只读上下文** | 人/agent 配置 | | Read-write files | LLM 唯一允许编辑的 | 人/agent 显式加入 |

**铁律**：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 | |---|---| | 全仓导航、定位修改点 | 已锁定 ≤5 个文件、想看实现细节 | | Token 预算紧 | 真的需要函数体语义 | | 多语言混合 | 单语言、深度分析 |

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