前言

最新阅读地址：

• 当前公开站点（本仓库 RC 内容，GitHub Pages）：shawnxie94.github.io/code-visualization-book

• 旧版站点（历史版本，GitBook）：code-visualization.shawnxie.top

• 本地预览（本仓库最新）：npm run serve → http://localhost:4000/

• 部署说明：docs/github-pages-deploy.md

这本书讲什么

代码可视化不是简单画图，而是一套软件理解方法。它把源码结构、程序行为、变更历史和组织信息转化为可观察、可查询、可验证的结构化事实，并服务人类开发者、Reviewer 和 AI Agent。

软件系统里有大量“不可见但关键”的事实：

• 调用链与依赖关系

• 控制流与数据流

• 测试覆盖与运行时 Trace

• 变更历史与 Owner

• 架构边界与约束

当这些事实只散落在源码、日志、文档、PR、测试平台和人的经验里时，开发者只能靠阅读、搜索和询问来拼接上下文。代码可视化要做的，是把这些事实采集出来、组织起来，并以图、路径、矩阵、报告或查询接口的方式服务工程决策。

在 AI 时代，这件事更重要。AI 可以更快地生成和修改代码，但也带来新的问题：

• 它是否找对了修改位置？

• 它是否理解了调用链和模块边界？

• 它是否遗漏了相关测试？

• 它是否破坏了架构约束？

• 它是否引入了安全、性能或数据一致性风险？

• 人类 Reviewer 如何验证它的修改？

这些问题不能只靠自然语言解释解决。它们需要结构化证据：调用关系、影响面、测试覆盖、运行时路径、架构规则和历史变更。因此，代码可视化应升级为软件理解基础设施：它既帮助人理解复杂系统，也为 AI Agent 提供上下文、边界、证据和验证能力。

本书结构

全书按“原理先行，再推进到工程场景和 AI 应用”组织：

1. 源码如何被结构化：AST、符号、类型、IR、CFG、DFG

2. 程序事实如何被分析与融合：静态分析、动态分析、变更分析

3. 代码事实如何建模为图谱：节点、边、属性、查询

4. 三个核心工程场景：代码库理解、变更影响分析、架构理解与遗留系统改造

5. AI 时代应用：Agent 上下文、图谱查询、Review 证据、辅助重构

6. 实践闭环：采集、建图、分析、可视化、Agent 查询、验证报告

本书主线

全书围绕下面这条链路展开：

全书主线：从工程问题到 Agent 验证

后续 AI 配图备注：可生成一张“人类开发者 + AI Agent 共同围绕代码图谱工作的主视觉图”，适合作为首页头图。画面重点是源码、运行时、测试、PR、Agent 汇聚到一张软件理解地图，风格应偏技术书籍封面，不要做营销海报。

读完这本书，你应该能够：

1. 理解 AST、符号表、CFG、DFG、Call Graph、Trace、Coverage 等概念如何服务代码理解。

2. 判断不同工程问题需要采集哪些代码数据。

3. 设计一个小型代码图谱和可视化查询系统。

4. 理解 AI Agent 修改代码时需要什么上下文、约束和验证证据。

本书适合谁

• 想系统理解代码可视化、程序分析和代码图谱的开发者。

• 经常接手大型代码库、遗留系统或跨团队项目的工程师。

• 关注研发效能、质量治理、架构治理和影响面分析的技术负责人。

• 想把 AI 编程工具引入真实工程流程，但担心上下文、测试和 Review 风险的团队。

• 对“人和 AI 如何共同理解代码库”感兴趣的读者。

• 正在建设 AI Coding / AI Agent 工具，需要结构化上下文与验证证据层的工程师。

阅读方式

全书主线为：原理 → 图谱 → 三个核心场景 → AI 应用 → 实践闭环。附录提供术语表、贯穿案例、版本勘误与资料卡索引。

如果你更关注原理，建议按目录顺序阅读前 3 篇；如果你更关注工程落地，可以重点阅读“代码库理解与上下文构建”“变更影响分析与验证”“架构理解与遗留系统改造”；如果你关注 AI 编程工具，则可以在理解代码图谱基础后阅读第 5 篇。

实践部分会构建一个最小代码理解系统，目标不是做一个完整商业平台，而是把“源码解析 -> 图谱构建 -> 影响面分析 -> 可视化展示 -> Agent 查询接口 -> 验证报告”这条链路跑通。

全书统一使用模拟案例 mini-shop（见 examples/mini-shop/ 与 docs/sample-case/README.md）贯穿原理、图谱、影响面和 Agent 上下文，不引入真实业务仓库。建议先按案例中的“全书跟做主线”走完 PR-42，再进入分章精读。

术语、案例与版本

• 术语表：docs/glossary.md

• 贯穿案例：docs/sample-case/README.md · examples/mini-shop/

• 版本与勘误：docs/changelog.md

• 资料卡索引：docs/research-cards/README.md

• 完成标准（编辑用）：docs/definition-of-done.md

发现错误请在勘误入口记录章节与复现句；修正后写入 changelog。

延伸阅读与参考资料

• ANTLR：语法分析器生成工具，可用于理解 Lexer、Parser 和语法规则。

• Tree-sitter：面向代码编辑器和代码分析场景的增量解析器。

• OpenTelemetry Traces：理解 Trace、Span 和运行时链路观测的官方资料。

• CodeQL Data Flow Analysis：理解数据流和污点分析的官方资料。

• GitHub Copilot: Explore a codebase：AI 辅助代码库探索的官方教程。

• SWE-bench：仓库级软件工程任务评测基准。

交流联系

• Email: [email protected]

• WeChat: ShawnLFF

• 公众号：肖恩聊技术

公众号二维码