| name | repo_map_guide |
| description | Guide for generating and using AI-readable code maps |
| version | 1.0 |
Repo Map 生成指南
概述
Repo Map 是一个代码地图生成系统,参考 Aider 的 RepoMap 实现,
将任意代码项目扫描后生成 AI 可读的 Markdown 文件目录结构。
输出结构
<output_dir>/
repo_map/
index.md # 项目总览 + PageRank top-20 关键模块
dependencies.md # 跨文件依赖关系
<dir>/
index.md # 该目录所有文件的定义+引用摘要
analysis.md # LLM 生成的架构分析(step3)
data/
tags.json # 所有文件的代码 tags(原始数据)
ranked.json # PageRank 排序结果
scan_meta.json # 扫描元信息
analysis_progress.json # step3 执行进度(断点续传)
index.md 格式说明
每个目录的 index.md 包含:
# src/core/
- 文件数: 12
- 总定义数: 78
## 文件列表(按重要性排序)
### engine.c ★★★★★
*src/core/engine.c*
- `engine_init` (line 28)
- `engine_run` (line 45)
- `process_event` (line 78)
*被引用于*: `main.c`, `handler.c` ... +3 more
PageRank 重要性说明
⭐ 星级由 PageRank 分数决定:
- ★★★★★ — 被最多文件引用的核心模块
- ★★★★ — 重要模块
- ★★★ — 中等重要
- ★★ — 较少被引用
- ★ — 边缘模块
analysis_progress.json 格式
{
"src/core": {
"status": "completed",
"md_file": "/abs/path/repo_map/src/core/index.md",
"output": "/abs/path/repo_map/src/core/analysis.md",
"rank": 1,
"file_count": 12
}
}
断点续传机制
step3 通过 analysis_progress.json 支持断点续传:
- Supervisor 读取 progress 文件
- 跳过
status == "completed" 的目录
- 每次迭代前设置
status = "in_progress"(立即写回)
- 完成后设置
status = "completed"(立即写回)
- 中断重启后,
in_progress 状态自动重置为 pending
使用方式
.venv/bin/python applications/repo_map/repo_map_app.py /path/to/project
.venv/bin/python applications/repo_map/repo_map_app.py /path/to/project \
--output_dir /tmp/mymap \
--exclude_dirs vendor \
--exclude_dirs third_party \
--exclude_dirs build
支持的语言
通过 tree-sitter 支持 30+ 语言,包括:
C, C++, Python, JavaScript, TypeScript, Java, Go, Rust, Ruby,
Swift, Kotlin, Dart, Elixir, Elm, Haskell, OCaml, Scala, Zig 等
注意事项
- [pitfall] 大型项目(>1000 文件)扫描较慢,属正常现象
- [pitfall] 二进制文件和 .min.js 等自动跳过
- [decision] step3 每次只读一个目录的 index.md,避免 context 超限
- [fact] analysis_progress.json 支持中断恢复,不用从头重跑