Topograph
扫一次，永久免扫。目标：让后续二开 Agent 只读 docs/project-map/ 即可回答"有没有 X 依赖 / 某模块干嘛 / 代码放哪 / 架构怎么实现"，不再扫源码。
何时激活
| 信号 | 判定 |
|---|---|
| "梳理/测绘/分析这个项目的架构" / "二开前先看懂项目" / "画依赖图模块图" | 激活 |
| 目标根目录有 pom.xml 且是 Java/Spring | 继续 |
| 根目录无 pom.xml | 中止：仅支持 Java/Spring+Maven，Gradle 暂不支持 |
| 非 Java 项目 | 不适用 |
三阶段流程
Phase 1 · 探针（脚本，无 Agent 判断）
跑 probes/run_all.py 的 run_all（需 Python 3.8+；可选 rg、mvn）：
python "<本 skill 目录>/probes/run_all.py" --project-root <目标项目根> --out-dir <目标项目根>/docs/project-map
产出 docs/project-map/facts/derived/*.tsv（6 文件 + 可选 _warnings.tsv）与 facts/raw/（gitignored）。mvn 缺失/报错时自动降级，记 _warnings.tsv。探针契约详见 references/probe-spec.md。
> 检查点 C1 · 事实复核（进 Phase 2 前必停）：读 _warnings.tsv（若有），向用户报告缺口（mvn 缺失→传递依赖未完整 / rg 缺失→类计数为空 / 某探针崩溃→对应事实缺 / 外部 BOM 未展开→托管版本不全）。明确"带着这些缺口继续解读"还是"先补环境重跑探针"。用户确认后才进 Phase 2。
Phase 2 · 解读（Agent，按指南）
读 facts/derived/*.tsv → 精选采样源码 → 写 01-overview.md … 07-task-index.md + ROUTER.md（均置于 docs/project-map/ 下）。
严格按 references/interpretation-guide.md：不读 raw/、不读全量源码、每条约定须有 derived/采样证据。文档模板见 references/doc-templates.md。
> 检查点 C2 · 地图复核（写完 7 文档+ROUTER 后必停）：地图会成为后续 Agent 的"地面真相"，错一处会传染。至少让用户复核两点：① ROUTER 的强约束——每条是否真有 base-class-usage.tsv 证据、有无臆造；② 01 速览表——技术栈/模块树一眼对得上。确认无误再进 Phase 3；有问题回 Phase 2 修订对应文档。
Phase 3 · 宿主指针
按 references/host-pointers.md 向目标仓库追加幂等指针块（opencode→AGENTS.md / Claude Code→CLAUDE.md / Cursor→.cursor/rules/project-map.mdc），并向 .gitignore 追加 docs/project-map/facts/raw/。
> 检查点 C3 · 宿主确认（改宿主文件前必停）：先检测宿主类型（查 AGENTS.md/CLAUDE.md/.cursor/rules/ 存在性，存在多个则问），向用户列出将改动清单：新建或改写哪个文件、追加幂等块区间、改 .gitignore。改的是用户仓库的自动加载文件，必须用户点头再写。 确认后只替换 <!-- topograph:start -->…:end --> 自有区间，不碰其余内容。若用户拒绝：跳过 Phase 3（地图照常落在 docs/project-map/，只是不挂宿主指针），并在 ROUTER 顶部注明"本地图未挂宿主指针，需手动让 Agent 读 docs/project-map/"。
强约束（Agent 执行时必守）
- 不读 facts/raw/：万行级，只供脚本解析。Agent 只读 facts/derived/。
- 不臆造约定：每条约定/强约束必须有 base-class-usage.tsv 或采样源码证据。
- 项目无关：绝不用项目名前缀猜 internal；internal 判定只靠 P1 模块名册。
- 速览表优先：每份地图 md 必须以速览表开头，一屏看完。
- 幂等指针：宿主指针块只替换自有区间，不破坏用户其余内容。
- 路径一致：指针块/ROUTER/文档里引用的事实路径必须与探针实际写入的
docs/project-map/facts/derived/*.tsv完全一致。
输出自检（产出前）
- [ ] 7 份地图 + ROUTER 齐全，每份开头是速览表？
- [ ] ROUTER 的强约束每条都能在 base-class-usage.tsv 找到证据？
- [ ]
_warnings.tsv里的缺口已在对应文档标注（如"传递依赖未完整"）？ - [ ] 宿主指针块已幂等追加？
.gitignore已含docs/project-map/facts/raw/？ - [ ] 文档/指针里的事实路径与实际
facts/derived/*.tsv一致（无 derived/ vs facts/derived/ 错位）？
