10 万行以上的代码仓里，无论是人还是 AI，都会遇到同一个问题：
不知道从哪里开始看代码，更不知道该改哪里。
针对这个现象我写了 RepoMap。
它是一个 CLI 工具，用于为大型代码仓生成一份稳定、可复现的仓库结构地图，主要解决下面这些真实工程痛点：
一、为什么需要 RepoMap？
在实际使用 Codex / Claude / 各类 Agent 改代码时，我反复遇到这些问题：
- AI 很难快速理解整个仓库的结构
- 修改点高度依赖“猜关键词”，命中率低
- 纯向量 RAG 在大仓库中容易召回泛化、入口定位不准
- 每次任务都要重新扫仓库，成本高、不可复现
二、RepoMap 会做什么
RepoMap 会扫描仓库，生成一份结构化产物：
- 模块级索引（module_index.json）
- 入口文件识别（路由 / controller / CLI / job 等）
- AI 友好的 summary.md（适合作为 AI 的第一输入）
- 支持 增量更新，避免全量重跑
- 输出顺序稳定，避免 diff 噪音
三、快速上手
npm i -g @repo-map/repomap
repomap build --out .repomap
repomap query "refresh token" --out .repomap
生成的 .repomap/summary.md，可以直接作为 AI 的第一阅读文件。
四、适合谁用？
- 使用 Codex / Claude Code / AI Agent 的工程师
- 维护中大型 monorepo 的团队
- 在做 prd2code / agent workflow 的平台开发者
五、测试：在 VS Code 仓库上跑 RepoMap
为了验证 RepoMap 在真实大型仓库中的可用性，我选了一个大家都很熟悉的项目：
microsoft/vscode
一个典型的 超大型 monorepo，结构复杂、入口众多、语言混合。
1️⃣ 测试环境
- Repo：
microsoft/vscode - Commit：
e08522417da0fb5500b053f45a67ee4825f63de4 - 文件数：约 8,700+
- 机器：macOS 14.3（arm64）
- Node：v22.17.1
- RepoMap：v0.1.0
2️⃣ 运行命令
在 VS Code 仓库根目录执行：
repomap build --out .repomap
3️⃣ 生成的核心产物
RepoMap 会生成一个 .repomap/ 目录，核心文件包括：
.repomap/
├── module_index.json # 模块级结构索引
├── entry_map.json # 各模块入口文件（CLI / services / workers 等）
├── summary.md # AI / 人类友好的仓库摘要
├── file_index.json # 稳定文件索引 + hash
└── meta.json # 版本、commit、生成信息
其中 summary.md 是我给 AI / Agent 先读的文件。
4️⃣ 性能表现（首次全量扫描）
使用 /usr/bin/time 测试：
/usr/bin/time -p repomap build --out .repomap
结果：
real 1.16
user 0.92
sys 0.62
👉 对一个 接近 9k+ 文件，代码百万行的仓库来说，速度可以说非常的fast！！！
5️⃣ 稳定性验证（非常关键）
RepoMap 的一个核心目标是：
同一份代码，在同一 commit 下，必须产出完全一致的结构结果。
我在相同仓库下，进行了两次构建，并对关键文件做 diff：
diff -u output/module_index.json output-tmp/module_index.json
diff -u output/entry_map.json output-tmp/entry_map.json
diff -u output/summary.md output-tmp/summary.md
结果：
👉 diff 无任何输出
这意味着：
- 输出顺序稳定
- 结构信息可复现
- 非常适合缓存、CI、Agent 多轮决策
6️⃣ 在真实 AI 场景里的用法
在 VS Code 这样的大仓库里，如果直接对 AI 说：
“帮我看看 VS Code 的 extension 激活流程”
AI 往往会：
- 猜关键词
- 误入非核心模块
- 漏掉真正入口
而我实际的做法是：
- 先让 AI 阅读
.repomap/summary.md - 用
repomap query "extension activation" - 结合
rg或 RAG 进行后续迭代开发。
👉 AI 的首次定位命中率明显更高。
六、项目地址
GitHub：
👉 github.com/Nicenonecb/…
欢迎提 issue / PR，也欢迎在评论区交流使用AI遇到的各种奇葩问题！
