代码可视化工具怎么选：Structurizr、CodeSee、Sourcetrail、Madge 和 repowise

代码可视化工具要看你想画哪种图。要给团队讲清楚系统设计、图本身要放进代码库评审，用 Structurizr 写 C4 模型。要在评审和新人上手时看文件之间的关系，用 CodeSee 这类交互式代码地图。只是查 JS/TS 的循环 import，用 Madge 或 dependency-cruiser。想让图、文档、提交历史和风险来自同一次扫描，用 repowise。

先想清楚：你要的图回答什么问题

“把代码画出来”通常包含好几种需求：

• 新同事入职，想知道系统分几块、请求从哪里进来。
• 评审一个 PR，想知道改的这几个文件会影响谁。
• 准备重构，想知道哪些模块缠在一起、从哪下手。
• 写设计文档，需要一张能放进汇报材料的架构图。

这几件事需要的图不一样。第一件要分层和入口，第二件要依赖方向，第三件要循环依赖和改动历史，第四件要表达设计意图，图和代码现状可以不完全一致。没有哪个工具在这四件事上都做得最好。

我评价代码可视化工具时看这几点：

1. 会不会过时：能不能从代码重新生成。手画的图三个月后基本就不准了。
2. 能不能缩放：仓库、模块、文件、符号，至少要有几个层级。
3. 方向和循环：依赖箭头的方向要清楚，最好能直接标出循环依赖。
4. 在不在工作流里：要单独打开一个网站才能看，用的人就会少。现在越来越多的人在 IDE 里通过 AI 助手查代码，所以能不能通过 MCP 调用也算一项。
5. 能不能指导下一步：一张图加上负责人、改动频率、风险，才能帮你做决定。

Structurizr：把架构写成代码

Structurizr 是 C4 模型的参考实现。你用 DSL 描述系统、容器、组件和它们之间的关系，它从同一个模型生成系统上下文图、容器图、组件图、部署图等多个视图，也能导出 PlantUML、Mermaid。

它适合的场景很明确：系统设计相对稳定，团队希望架构图像代码一样提交和评审。它表达的是“我们打算怎么设计”，所以不会自动发现代码里的实际依赖。模型和代码对不上的时候，要靠人去发现和修改。

CodeSee：交互式代码地图

CodeSee 的核心是自动生成的代码地图（Codebase Maps），用箭头画出文件之间的依赖，可以展开、折叠目录，也有针对 PR 的评审地图，帮你看出一次改动波及了哪些地方。它在 2024 年 5 月被 GitKraken 收购，目前官网仍在提供 Maps。

适合评审和新人熟悉代码。它的工作流围绕 CodeSee 自己的应用，导出和集成到其他工具的灵活性不如命令行工具。

Sourcetrail：已经停止维护

Sourcetrail 曾经是本地代码浏览的标杆：从一个符号出发，一层层展开调用者和被调用者，边看图边看源码。它在 2021 年停止开发，GitHub 仓库于 2021 年 12 月归档，社区有一些分支在继续维护。

我不推荐新项目再用它。把它列进来，是因为它的交互方式到现在仍然值得参考：从一个点出发，逐步向外展开，不会一上来就给你一张上万个节点的图。评价新工具的时候，这个标准仍然适用。

Madge 和 dependency-cruiser：命令行里的依赖图

Madge 生成 JS/TS 模块依赖图，--circular 查循环依赖，装了 Graphviz 可以导出 SVG 或 DOT。dependency-cruiser 更偏规则和报告，可以输出 DOT、JSON、CSV，适合放进 CI 检查架构约束。

它们快、可脚本化，前端团队很好用。局限是只看 JS/TS 的 import，不看后端，不看历史，也不生成文档。

repowise：一次扫描，图和文档放在一起

repowise 从代码生成依赖图和分层视图，同时为文件、模块、符号自动生成文档，再叠加 git 历史：热点文件、修 bug 的提交集中在哪、主要作者是谁。所以你在图上点开一个节点，能同时看到它连着谁、它是干什么的、最近改得多不多、谁在维护。

例子：deepseek-harness

deepseek-ai/deepseek-harness 是一个以 TypeScript 为主的 monorepo，12,578 个文件，约 90 万行代码，11 个顶层模块。

分层视图：知识图谱把文件归到 10 个层里，节点数分别是：Application 4,828、Config 3,748、Test 2,568、Docs & Tooling 938、Utility 187、API 161、Service 81、CLI 28、Data 25、UI 14。从这组数字能看出，配置相关的节点接近应用代码的八成，这符合它“Everything is a Plugin”的定位，大量行为是由配置和预设组合出来的。

自动生成的文档：一共 4,559 页，包括 2,802 个文件页、1,620 个符号页、78 个模块页、47 个循环依赖页，还有总览和 4 篇入门文档。入门文档里的“How It Works”从原生入口 native/system/packages/entry/src/main.c 讲起：程序启动时用 Linux 的 Landlock 给自己加沙箱，如果加不上就直接退出（代码注释写的是“fail CLOSED, never exec unconfined”），然后才进入沙箱化的 bash 执行。这种“安全默认值”的设计，单看依赖图是看不出来的。

热点：排在最前面的热点文件是 packages/extensions/tool-cordis/src/api-catalog.ts，有 139 次修复类提交；其次是 packages/core/agent-loop/src/agent.ts，78 次。图上它们只是两个普通节点，叠加历史之后才知道该先看哪里。

对照：只有图，没有文档

再看 volcengine/openviking。这个快照只做了依赖图、健康度和死代码分析，没有生成文档。即便如此，你仍然能看到它的结构：Python 1,335 个文件、C++ 386 个、TypeScript 178 个、Rust 88 个，分成 Application、API、Middleware、Data 等层；也能看到热点，比如 openviking/storage/viking_fs.py 有 35 次修复类提交。

但只靠图很难回答“这个模块是干什么的”，这个问题要靠文档。图和文档放在一起，新同事才有可能自己读懂一个仓库，我们做 repowise 就是从这个想法出发的。

repowise 的局限：它是自动生成的，所以表达的是代码现状，看不出设计意图；如果你只要一张架构图放进汇报材料，Structurizr 更合适。

大仓库的图为什么总是看不清

很多人第一次把一个大仓库画成依赖图，得到的是一团毛线，因为一万多个节点本来就没法在一张图里同时看清。好用的图都会先聚合，再按需展开。

聚合的方式有几种。按目录聚合最简单，但目录结构经常和真实的依赖结构不一致，一个叫 utils 的目录可能被所有人依赖。按分层聚合（应用、接口、数据、配置、测试）更接近人的理解方式，上面 deepseek-harness 的 10 个分层就是这样来的。按社区聚合（用社区发现算法把联系紧密的文件自动分成一组）能发现目录名没有表达出来的模块边界。

展开的方式也有讲究。Sourcetrail 从一个符号出发向外展开，CodeSee 按目录展开折叠，repowise 从分层进入模块，再到文件和符号，模块、文件、符号都有对应的文档页。选工具的时候，可以拿自己最大的那个仓库试一下：打开图之后，三次点击之内能不能找到你关心的那个文件。

静态图和活的图

表里最后一类（给 AI 助手调用的视图）是这两年才出现的。repowise 的 MCP 服务可以接入 Claude Code、Cursor、Qwen Code 等客户端；按官方文档，Claude Code 也可以换成 DeepSeek 或 Kimi 的兼容接口来跑。这样你在编辑器里问“这个仓库怎么分层”，助手调用的是同一份图和文档，不用现场去读几千个文件。

怎么选

1. 主要产出是架构文档：Structurizr。
2. 主要痛点是评审和新人上手：CodeSee 这类交互式代码地图，或者 repowise。
3. 主要问题是前端循环依赖和 import 规范：Madge、dependency-cruiser。
4. 想把依赖图、文档、历史和风险放在一起，并且让 AI 助手也能用：repowise。

试一试

在 repowise.dev 贴任何一个 GitHub 仓库地址，就能看到它的依赖图、分层和自动生成的文档。

写作说明

deepseek-harness 的数据来自 2026-09-28 的快照（提交 4878cda），OpenViking 来自 2026-06-14 的快照（提交 66622aa），都可以在对应的仓库页面上核对。分层的节点数来自 repowise 知识图谱的分层结果，文档页数来自公开的文档接口。第三方工具的现状（CodeSee 被收购、Sourcetrail 归档）以各自官网和 GitHub 仓库为准，核对日期为 2026-10-06。