仓库架构交互图一键生成

为什么需要这张图

接手一个没文档的老仓库时，最常见的困境不是“看不懂某一行代码”，而是“不知道从哪里开始看”。你打开目录树，看到几十个文件夹；你翻 README，发现它停在两年前；你问同事，每个人只记得自己负责的那一块。结果就是：在 code review 前，你很难判断这次改动会影响哪些模块；给新人讲解系统结构时，你不得不手绘 PPT，边画边漏。

更麻烦的是，自动生成的依赖图往往不可信。工具按 import 或目录名猜关系，常把无关文件连在一起，或者漏掉真正的调用链。你拿到一张看似完整的图，却不知道该信哪条边。

它如何工作

这个技能扮演“代码库导游”的角色，核心信念是：读源码先从“形状”开始。看懂模块怎么连，比钻进某一行重要得多。它把陌生仓库变成一张能点、能展开的交互图，让人在 5 分钟内建立心智模型。

工作流程分为四个关键步骤：

• 喂入仓库：用仓库 URL 或本地路径生成初始图。这一步只求“全貌”，不追求细节。
• 分层聚焦：先关掉叶子节点，只看核心服务或包之间的依赖关系。避免一上来就被细枝末节淹没。
• 交互下钻：点开关键模块，查看其下目录，并标出你这次要改的范围。图变成你的“改动影响半径”探针。
• 对照验证：拿图去对照真实代码，修正自动分析误连的边。这一步必不可少，因为自动图常有错。

适用边界与注意点

这个技能适合快速建立方向感，但不要把它当成最终结论。自动生成的架构图基于静态分析，可能与运行期真实依赖存在偏差。常见陷阱包括：

• 盲信自动图：工具按 import 猜依赖，常把无关文件连在一起。必须人工校验每条边。
• 过度展开：一口气展开全部节点，图会比代码还乱。正确做法是只关注你这次任务相关的子图。
• 只看图不读码：图给方向，真正的逻辑还得进代码确认。注释和 commit 历史才能解释“为什么这么设计”。

导出关键子图时，记得带上图例，否则别人也读不懂。这个技能不替代源码阅读，它只是帮你更快找到该读的地方。

检查清单

• 图是否标出了你本次任务的“改动影响半径”？
• 自动识别的依赖边是否人工校验过（误连/漏连）？
• 是否区分了“运行时依赖”与“构建依赖”？
• 导出的图是否带了图例让别人也能读懂？