Topograph

大型 Java/Spring 仓库的认知成本

接手一个庞大的 Java/Spring 项目，或者准备在其基础上做二次开发时，Agent 常常面临一个困境：只要有一次上下文清空，或者开启全新的会话，就必须重新扫描源码来理解架构。这不仅消耗大量 token，还会因为缺乏全局视野导致理解偏差。我们需要一种"一次扫描，永久免扫"的机制，让后续的 Agent 能够直接查阅一份静态的架构地图，快速回答"某模块职责是什么"、"依赖关系如何"、"代码放在哪里"。

工作原理：从探针到宿主指针

Topograph 专为 Java/Spring + Maven 项目设计，通过严谨的三阶段流程生成架构地图，并确保后续 Agent 读取的是经过提炼的事实，而非冗长的源码。

• Phase 1 · 自动化探针 (Probes)

运行 probes/run_all.py 脚本，无需 Agent 参与判断。脚本会产出 facts/derived/*.tsv（包含 6 个核心事实文件）以及可能的 _warnings.tsv。在此阶段，如果缺失 mvn 或 rg，系统会自动降级，并在警告文件中记录缺失的上下文（如传递依赖不完整）。

• Phase 2 · Agent 解读与制图

Agent 严格依据 references/interpretation-guide.md，只读取 derived 数据和精选采样源码。产出包含 01-overview.md 到 07-task-index.md 以及 ROUTER.md 的文档集。此阶段有严格的强制约束：不读原始数据 (facts/raw/)，且每一条架构约定都必须有 base-class-usage.tsv 或采样源码作为证据。

• Phase 3 · 宿主指针挂载

根据宿主环境（如 Claude Code、Cursor），向对应的配置文件（如 CLAUDE.md）追加幂等指针块，指示 Agent 优先阅读 docs/project-map/。

适用边界与工程注意点

• 仅限 Java/Spring + Maven：技能会在检测到非 pom.xml 根目录时中止，目前不支持 Gradle 或其他语言项目。
• 证据导向：Agent 不能臆造约定，所有的强约束必须能追溯到探针生成的数据。
• 环境完整性：完整的传递依赖分析依赖 mvn，缺失会导致依赖图存在盲区，需关注 _warnings.tsv 中的提示。

通过这套机制，二次开发 Agent 可以绕过漫长的源码扫描，直接基于经过校验的结构化事实进行开发。