21 · 实战：LLM 是怎么总结一个代码仓库的

21 · 实战：LLM 是怎么总结一个代码仓库的

正文二十篇已经收官。这一篇是实战番外：不再引入新部件，而是把前面焊上的零件——工具、并发、子 Agent、缓存、压缩——组装起来，解决一个具体而普遍的问题：

让 Agent 读懂一个它从没见过的代码仓库。

这是每个 Coding Agent 开工前的第一件事，也是 /init 生成一份项目说明文件、新人入职文档自动化、代码库问答这些功能背后共同的那条流水线。

一、背景：仓库根本塞不进上下文

先算一笔账。一个中等规模的 TypeScript 项目：

node_modules 之外的源文件      ~1500 个
平均每个文件                    ~180 行
合计                            ~27 万行代码
按代码约 12 token/行估算        ≈ 320 万 token

而当前主流模型的上下文窗口在 20 万 token 量级(部分支持到百万)。差 15 倍以上。 换成一个几万文件的大型单体仓库，差距是两到三个数量级。

更关键的是——就算塞得下，也不该塞：

• 成本：几百万 token 的输入，而且因为 LLM 无状态，每一轮都要整个重发。
• 注意力稀释：把关键信息埋进几百万 token 的样板代码里，模型的检索准确率会显著下降。信噪比比绝对信息量更重要。
• 缓存全废：一个巨大的前缀，任何一处改动都会让缓存整体失效。

所以，问题必须重新表述：

二、三条根本不同的路子

在进入流程之前，先把三种策略摆清楚，因为真实系统是把它们混着用的。

关于向量检索这条路，值得多说一句：它在文档上很有效，但在代码上表现常常不如朴素的 grep。原因是代码的检索需求多半是精确的符号名(“ToolRegistry 在哪定义的”)，而不是模糊的语义相似(“讲工具注册的那段”)。而且嵌入索引需要构建、存储、随代码变更维护——这些成本在一个每天几十次提交的仓库里并不低。能用符号搜索解决的，别上向量库。

三、完整流程：六个阶段

5000 个文件 / 320 万 token
   │
   ├─ 阶段 0  边界裁剪       确定性,0 token      → 800 个文件
   ├─ 阶段 1  骨架采集       确定性,0 token      → 3k token 的“项目名片”
   ├─ 阶段 2  符号级 map     tree-sitter,0 token → 40k token 的“全仓 .d.ts”
   ├─ 阶段 3  重要性排序     图算法 + git 信号    → Top-30 全文 / 其余仅签名
   ├─ 阶段 4  分治总结(map)  N 次并行 LLM 调用    → N 份结构化模块摘要
   ├─ 阶段 5  归并(reduce)   1~2 次 LLM 调用      → 全局架构视图
   └─ 阶段 6  验证与落盘     工具核对 + 记 commit → 可增量更新的产物

注意前三个阶段一个 token 都不花。这不是巧合，而是这条流水线的组织原则：越便宜的手段越早用，把模型留到最后。

阶段 0：边界裁剪(不花一个 token)

第一条，也是最容易被做错的一条：用 git，别用文件系统遍历。

git ls-files

这一行天然尊重 .gitignore，一步排除 node_modules、dist、.venv、target 这些占了 95% 体积却几乎零信息量的东西。用 find 或 readdir 递归，你得自己重新实现一遍 gitignore 的匹配规则，而且一定会漏。

在此之上再叠一层显式排除：

经过这一步，5000 个文件通常会降到 800 左右——一次 6 倍压缩，成本是零。

阶段 1：骨架采集(仍然 0 token)

这一步依旧不调用模型，只用确定性工具抽取信息密度最高的东西。四类：

① 元数据文件——一眼看清技术栈

package.json / go.mod / Cargo.toml / pyproject.toml / pom.xml 里直接写着：语言、框架、依赖清单、脚本入口、二进制入口。

其中 scripts 字段格外有价值——它告诉你怎么构建、怎么跑测试、怎么启动。这三件事是阶段 6 验证环节要用的，也是 Agent 后续真正干活时最常需要的知识。

② 目录树(必须限深限宽)

直接输出的完整目录树，本身就可能几万 token。要限制：深度限 3~4 层，同层同类条目超过阈值就折叠。

src/
├── core/            (12 个文件)
│   ├── loop.ts
│   ├── registry.ts
│   └── ...
├── tools/           (28 个文件)
├── ui/
│   ├── components/  (140 个文件,已折叠)
│   └── hooks/       (22 个文件)
└── index.ts

折叠时保留计数很重要——“这里有 140 个组件”本身就是一条结构信息，它告诉模型这是个 UI 密集型项目。

③ git 信号——被严重低估的重要性来源

git log --since=6.months --name-only --format= | sort | uniq -c | sort -rn | head -50

这一行给你最近半年改动最频繁的 50 个文件。

同源的另外两个信号也顺手可得：git log --format='%s' -50 的提交标题透露“最近在做什么”；git shortlog -sn 的作者分布透露“谁维护哪块”。

④ 文档与入口

README、docs/、CONTRIBUTING.md、Dockerfile 的 CMD、CI 配置里的构建与测试命令。

阶段 1 的产出通常只有 2~5k token，但它往往已经回答了“这是个什么项目”这个问题的一多半——而且一个 token 的模型调用都没花。

阶段 2：符号级骨架——压缩比最高的一步

现在要处理那 800 个源文件。读全文不可能，但有一个近乎免费的巨大压缩：只保留签名，丢掉函数体。

用 tree-sitter(或 ctags、语言自带的 LSP)解析出每个文件的顶层符号：

// 原文件 src/tools/registry.ts —— 480 行,约 6000 token
// 抽取后 —— 9 行,约 120 token:

export interface Tool { name: string; schema: ZodSchema; run(...): Promise<Result> }
export class ToolRegistry {
  register(tool: Tool): void
  get(name: string): Tool | undefined
  list(): Tool[]
  private resolveConflict(a: Tool, b: Tool): Tool
}
export function defineTool(spec: ToolSpec): Tool

还能再进一步：按引用关系排序。 把 import 与调用关系建成一张图，跑一遍 PageRank——被引用得越多、且引用它的文件本身越重要的符号，排名越高。然后只保留 Top-N 个符号。

这正是 aider 的 “repo map” 采用的做法(tree-sitter 抽符号 + PageRank 排序)。它的价值在于：当你只有固定的 token 预算时，装进去的是最值得装的那些符号，而不是碰巧排在字母表前面的那些。

阶段 3：重要性排序与预算分配

现在手上有：项目名片(3k) + 全仓签名骨架(40k)。还差最后一层决策——哪些文件值得读正文。

把前面的信号合成一个分数：

然后按预算分层分配：

总预算 150k token
├── 项目名片          3k    全文
├── Top-30 文件      60k    读全文
├── 次要 200 个      50k    仅签名骨架
└── 长尾 570 个      10k    仅路径 + 一行职责
                    ────
                    123k    留 27k 给模型输出与后续对话

阶段 4：分治总结(map)

终于开始调模型了。四个要点。

① 切块要沿语义边界，不要沿 token 边界。

按模块 / 目录切，不要按“每 50k token 切一刀”。一个模块的文件放在一起，模型才能看出内聚关系；切在半个模块上，两边都总结不好，而且两边都不知道自己被切了。

② 每块都要带全局上下文头。

这是最容易漏、影响却最大的一点。孤立地丢给模型一个 src/retry/ 目录，它只能说“这是一个实现重试逻辑的模块”——正确，但毫无用处。带上“本项目是一个 Coding Agent CLI，本模块位于工具执行层与 API 客户端之间”，它才说得出：“它把 API 的 429/5xx 转换成带抖动的指数退避，是 Agent Loop 在网络抖动下不中断的关键”。

┌──────────────────────────────────┐
│ [全局头] 项目名片(阶段 1 产出)      │ ← N 次调用里逐字节相同
│ [全局头] 目录树骨架                │   放最前面,整体命中缓存
├──────────────────────────────────┤
│ [本块]   src/retry/ 的完整源码     │ ← 只有这部分在变
├──────────────────────────────────┤
│ [指令]   按固定 schema 输出摘要    │
└──────────────────────────────────┘

③ 强制结构化输出。

让每块摘要按同一个 schema 产出，归并阶段才好处理：

{
  module: 'src/retry',
  responsibility: string,      // 一句话职责
  publicApi: string[],         // 对外暴露什么
  dependsOn: string[],         // 依赖哪些内部模块
  keyDecisions: string[],      // 值得记住的设计决策
  entryPoints: string[],       // 从哪个文件读起
  evidence: string[],          // 每条结论的文件路径依据  ← 关键
}

evidence 这个字段值得单独说：要求模型为每条结论给出文件路径依据，既能显著压制幻觉(说不出出处的结论，模型往往就不说了)，又让阶段 6 的验证有的放矢。

④ 并行，并且隔离。

N 个模块之间没有依赖，天然可以并发(第 06 篇)。更进一步，用子 Agent 跑每一块——这样某个模块需要额外读五个文件才看得懂时，那五份原文留在子上下文里，主线程只收到一份结构化摘要。

阶段 5：归并(reduce)

N 份模块摘要 → 一张全局图。

关键认识：归并要做的不是“拼接”，而是“发现跨模块的关系”。模块摘要各自都是局部真相，归并阶段的全部价值在于回答局部视角看不到的问题：

• 请求 / 数据从哪进来、流经哪些模块、从哪出去？
• 分层怎么分的？哪些是基础设施，哪些是业务？
• 哪两个模块耦合得不正常？

N 很大时自然会想到分层归并(树形 reduce)：目录级 → 子系统级 → 全局。但这里有个陷阱。

所以真实系统往往刻意不做深层归并，而是保留一个两层结构：

最终产物
├── 全局概览     1~2 页:架构、数据流、怎么跑起来、从哪读起
└── 模块索引     每模块 2~3 行,保留阶段 4 的原始摘要,不再压缩

这样既有全局视图，又不丢局部细节，而且总量仍然很小(几千 token)，小到可以常驻上下文。这是关键——一份需要检索才能用的摘要，价值远低于一份一直在窗口里的摘要。

阶段 6：验证与失效管理

摘要生成完了，还有两件事必须做，否则前面全白干。

① 验证：让结论可证伪。

基于摘要提几个能用工具核对的问题，然后真的去核对：

② 失效管理：摘要一定会过期。

仓库每天都在变。一份三个月前的摘要比没有摘要更糟——它会用一副权威的口吻，自信地误导。

所以产物里必须记下生成时的 commit：

<!-- generated-at: 8f3a2c1 · 2026-08-02 -->

之后判断失效范围就变成一次 diff：

git diff --name-only 8f3a2c1..HEAD

改动落在哪些模块，就只重跑那几个模块的 map，再重跑一次 reduce。

四、两条路线，其实都要

五、七个常见失败模式

这七条里，1、2、6 占了实际问题的绝大多数——而它们全都不是模型能力问题，全是流水线的工程问题。

六、小结

1. 仓库总结的本质是采样与预算分配，不是“读完再总结”。想清楚这一点，后面所有决策都有了依据。
2. 流水线的组织原则：越便宜的手段越早用——git 裁剪(0 token) → 确定性骨架(0 token) → tree-sitter 签名(0 token) → 只在最后那 5% 的内容上花模型调用。
3. 重要性排序是成败手。git 改动频率与引用图 PageRank 是两个最有效、也最容易拿到的信号。
4. map 阶段：沿语义边界切、带全局头(顺便吃满缓存)、结构化输出、要求 evidence、并行且用子 Agent 隔离。
5. reduce 阶段要克制——“薄概览 + 不再压缩的模块索引”这个两层结构，通常优于深层归并。
6. 产物必须带 commit 戳并支持增量更新，否则它迟早从资产变成负债。

回到序章那个比方：如果说前二十篇是在把一块芯片焊成一台机器，那这一篇就是第一次让这台机器去干一件真正复杂的活。而你会发现，整件事里最难的部分——排除生成物、按 git 热度排序、按语义边界切块、把不变的放在 prompt 前面——没有一处发生在模型内部。

模型只负责最后那几次调用里的理解。而理解的质量，几乎完全由你在此之前替它做的那些取舍决定。

本篇对应代码：本篇是综合运用篇，用到的部件(工具抽象、并发执行、子 Agent、缓存)在前面各篇都已落地，配套仓库无新增 tag——从 git checkout article-20 出发，照着上面六个阶段就能把这条流水线搭起来。