代码可视化
最新阅读地址：
- 当前公开站点（本仓库 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 应用”组织：
- 源码如何被结构化：AST、符号、类型、IR、CFG、DFG
- 程序事实如何被分析与融合：静态分析、动态分析、变更分析
- 代码事实如何建模为图谱：节点、边、属性、查询
- 三个核心工程场景：代码库理解、变更影响分析、架构理解与遗留系统改造
- AI 时代应用：Agent 上下文、图谱查询、Review 证据、辅助重构
- 实践闭环：采集、建图、分析、可视化、Agent 查询、验证报告
本书主线
全书围绕下面这条链路展开：
后续 AI 配图备注：可生成一张“人类开发者 + AI Agent 共同围绕代码图谱工作的主视觉图”，适合作为首页头图。画面重点是源码、运行时、测试、PR、Agent 汇聚到一张软件理解地图，风格应偏技术书籍封面，不要做营销海报。
读完这本书，你应该能够：
- 理解 AST、符号表、CFG、DFG、Call Graph、Trace、Coverage 等概念如何服务代码理解。
- 判断不同工程问题需要采集哪些代码数据。
- 设计一个小型代码图谱和可视化查询系统。
- 理解 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: xiexiao064@gmail.com
- WeChat: ShawnLFF
- 公众号：肖恩聊技术
