> For the complete documentation index, see [llms.txt](https://code-visualization.shawnxie.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-visualization.shawnxie.top/readme.md).
# 前言
最新阅读地址：
* 当前公开站点（旧版 GitBook，待同步本仓库 RC 内容）：[code-visualization.shawnxie.top](https://code-visualization.shawnxie.top/)
* 本地预览（本仓库最新）：`npm run serve` →
* 部署说明：[`docs/github-pages-deploy.md`](https://github.com/Xiaoxie1994/code-visualization-book/tree/main/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 查询、验证报告
## 本书主线
全书围绕下面这条链路展开：
```mermaid
flowchart LR
Problem[工程问题] --> Source[源码结构化]
Source --> Analysis[静态/动态/变更分析]
Analysis --> Graph[代码图谱]
Graph --> Viz[可视化与查询]
Viz --> Scene[核心工程场景]
Graph --> Agent[AI Agent 上下文]
Scene --> Review[Review 与验证证据]
Agent --> Review
```
> 后续 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`](/fu-lu/sample-case.md)）贯穿原理、图谱、影响面和 Agent 上下文，不引入真实业务仓库。建议先按案例中的“全书跟做主线”走完 PR-42，再进入分章精读。
## 术语、案例与版本
* 术语表：[`docs/glossary.md`](/fu-lu/glossary.md)
* 贯穿案例：[`docs/sample-case/README.md`](/fu-lu/sample-case.md) · [`examples/mini-shop/`](https://github.com/Xiaoxie1994/code-visualization-book/tree/main/examples/mini-shop/README.md)
* 版本与勘误：[`docs/changelog.md`](/fu-lu/changelog.md)
* 资料卡索引：[`docs/research-cards/README.md`](/fu-lu/research-cards.md)
* 完成标准（编辑用）：[`docs/definition-of-done.md`](https://github.com/Xiaoxie1994/code-visualization-book/tree/main/docs/definition-of-done.md)
发现错误请在勘误入口记录章节与复现句；修正后写入 changelog。
## 延伸阅读与参考资料
* [ANTLR](https://www.antlr.org/)：语法分析器生成工具，可用于理解 Lexer、Parser 和语法规则。
* [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)：面向代码编辑器和代码分析场景的增量解析器。
* [OpenTelemetry Traces](https://opentelemetry.io/docs/concepts/signals/traces/)：理解 Trace、Span 和运行时链路观测的官方资料。
* [CodeQL Data Flow Analysis](https://codeql.github.com/docs/writing-codeql-queries/about-data-flow-analysis/)：理解数据流和污点分析的官方资料。
* [GitHub Copilot: Explore a codebase](https://docs.github.com/en/copilot/tutorials/explore-a-codebase)：AI 辅助代码库探索的官方教程。
* [SWE-bench](https://github.com/swe-bench/SWE-bench)：仓库级软件工程任务评测基准。
## 交流联系
* Email:
* WeChat: ShawnLFF
* 公众号：肖恩聊技术
