# 完成定义（Definition of Done）

本文档定义《Code Visualization》何时可称为**出版级终稿**。

这里的“完整”不是：

- 页数够多
- 目录写完
- 能本地预览
- 主线“差不多齐了”

而是：

> 目标读者读完后，能按同一主线完成原理理解、图谱建模、工程判断和 AI 应用设计；全书达到可对外正式发布的技术书质量：内容足够丰富、论证充分、案例贯通、权威引用扎实、图示可靠、术语统一、可复现、可构建、可稳定阅读。

“足够丰富”不是灌水，而是：概念讲透、例子够用、边界清楚、对比充分、可操作、可追溯。  
“权威引用扎实”不是文末堆链接，而是关键判断尽量有一级/高可信来源支撑，并能回指到正文论点。

公开正文与前言必须按正常技术书籍组织，不描述旧稿迁移、目录重写、写作过程备忘等内部信息。

---

## 0. 完成档位

| 档位 | 名称 | 含义 | 是否可宣布“写完了” |
| --- | --- | --- | --- |
| Draft | 主线草稿 | 目录与初稿存在，可内部讨论 | 否 |
| Beta | 内容可读稿 | 28 章结构齐全、主线闭环、可构建预览 | 否（仅内部里程碑） |
| **RC** | **出版级终稿** | 满足本文全部硬门槛 | **是** |
| Release+ | 发行增强 | PDF/纸书版式、更多语言案例、课程化等 | 否，属衍生 |

**当前目标：RC（出版级终稿）。**  
此前“v1 可读闭环”只对应 Beta，不再视为终稿完成。

---

## 1. 读者能力完成标准

读者读完后应能独立做到，且正文中有足够讲解、例子与练习支撑，而不是只在前言声称：

| 能力 | 可观察标准 |
| --- | --- |
| 原理理解 | 能说明 AST、符号表、CFG、DFG、调用图、Trace、Coverage、变更历史分别提供什么事实、如何得到、边界在哪 |
| 图谱建模 | 能基于 `mini-shop` 定义节点、边、属性，并写出不少于 5 个有工程价值的查询 |
| 工程判断 | 能对模拟 PR 独立产出影响面报告：变更实体、影响路径、相关测试、风险分级、建议动作 |
| AI 应用 | 能设计 Agent 上下文包、图谱查询接口、查询轨迹和修改后验证报告，并说明失败模式 |

如果读者只会画图、只会罗列工具、或只会空谈 AI，则不算达到完成标准。

---

## 2. 内容结构完成标准

全书必须完整、均衡地支撑主线：

```text
原理 -> 程序分析与代码图谱 -> 3 个核心工程场景 -> AI 时代应用 -> 实践闭环
```

必须同时满足：

1. **28 章全部达到“定稿”状态**（见第 3 节），不是“可读草稿”。
2. **三类样章定标完成，并被全书真实对齐**
   - 原理：`part2/source-to-ast.md`
   - 工程场景：`part4/change-impact-verification.md`
   - AI 应用：`part5/agent-context-engineering.md`
3. **贯穿案例完整且字段契约稳定**
   - `mini-shop` 贯穿：AST → 符号/调用 → 图谱 → 影响面 → Agent 上下文 → 验证报告
   - `examples/mini-shop/artifacts/` 中的 JSON/Diff/报告与正文引用一致
4. **场景边界受控**
   - 第四篇只保留 3 个核心场景
   - 性能 / 安全 / 质量 / 精准测试只作子能力，不单独铺成主线
5. **实践篇闭环可复现**
   - 说明并给出可跟做的输入、步骤、输出样例：

```text
采集 -> 建图 -> 影响面分析 -> 可视化/查询 -> Agent 接口 -> 验证报告
```

实践项目以可讲解、可复现为优先；不要求工业级平台，但要求读者能按书完成最小闭环，而不是只看概念描述。

---

## 3. 单章“定稿”标准（高于原“可读”）

任一章节只有同时满足以下条件，才算定稿：

### 3.1 结构

必须包含：

1. 本章要解决的问题
2. 读者读完应获得什么
3. 本章不讲什么（边界）
4. 概念与原理展开
5. 可跟做的例子（优先 `mini-shop` / `PR-42`）
6. 图示（Mermaid 或精确技术图）
7. 方法 / 流程 / 数据模型 / 接口（按章节类型）
8. AI 时代关联或工程接入点
9. 局限与误差
10. 小结（可检查的要点，不是空话）
11. 练习（至少 2 题，能量化检查理解）
12. 延伸阅读与参考资料（尽量权威、可核查，并能反向支撑正文关键判断；关键章建议 5 条以上）

### 3.2 深度

| 章节类型 | 最低深度要求 |
| --- | --- |
| 原理章 | 有最小代码例子 + 结构图 + 能回答“为什么需要这一层” |
| 分析/图谱章 | 有输入输出、模型字段、查询或报告样例 |
| 工程场景章 | 有问题场景、步骤、产物模板、PR/流程接入 |
| AI 应用章 | 有上下文/证据/失败模式，不只是口号 |
| 实践章 | 有数据结构、接口或伪代码、验收标准、样例产物路径 |

### 3.3 篇幅与信息密度（指导线，不是灌水）

- 原理 / 场景 / AI 关键章：通常应显著厚于提纲级短文，足够支撑自学
- 实践章：必须有可执行契约（schema、命令、JSON、验收）
- 禁止“只有小标题没有展开”的空心章
- 禁止为凑字数重复相邻章内容

### 3.4 公开文风

- 像正式技术书，不像工作备忘录
- 不出现旧稿迁移、重写过程、内部规划术语作为正文主叙事
- 术语前后一致

---


## 4. 内容丰富度标准（出版级硬门槛）

出版级终稿要求内容**尽可能丰富**，但丰富必须服务于理解与可执行，禁止同义反复灌水。

### 4.1 丰富度的正确定义

每章应尽量覆盖以下信息层中与本章相关的部分：

| 信息层 | 要求 |
| --- | --- |
| Why | 为何存在、解决什么工程/AI 问题 |
| What | 核心概念、对象、边界、反例 |
| How | 方法、流程、算法骨架、数据模型、接口 |
| Show | 可跟做例子、图示、输入输出样例 |
| Tradeoff | 取舍、误差、失败模式、适用条件 |
| Apply | 工程接入与 AI/Agent/Review 用法 |
| Prove | 验证方式、验收标准、练习 |

缺层过多的章节，即使“结构齐全”，也不算定稿。

### 4.2 篇幅与展开指导线

以下为指导线，用于防止“提纲充数”；不是为凑字而设上限/下限硬卡：

| 章节类型 | 期望完成度 | 内容丰富度要求 |
| --- | --- | --- |
| 原理章 | 高 | 概念拆解 + 最小代码 + 至少 1 张结构图 + 常见误解 + AI 关联 + 练习 |
| 分析/图谱章 | 高 | 输入/输出/误差 + 模型字段 + 查询/报告样例 + 工具/文献依据 |
| 工程场景章 | 高 | 完整场景叙事 + 步骤 + 产物模板 + 流程接入 + 反例 |
| AI 应用章 | 高 | 风险、上下文/证据、失败模式、接口或清单、审计点 |
| 实践章 | 高 | schema/伪代码/步骤/验收/样例路径齐全，读者可跟做 |
| 导论/收束章 | 中高 | 框架清楚、地图完整，不空泛重复后文 |

若一章读完后，读者仍只能复述标题，不能动手或不能判断边界，则丰富度不合格。

### 4.3 丰富度检查问题

定稿前每章至少能回答：

1. 有没有足够例子，而不是只有定义？
2. 有没有正反对比或失败模式？
3. 有没有可落地的步骤、模板、字段或接口？
4. 有没有与 `mini-shop` / `PR-42` 的具体连接？
5. 有没有讲清局限，避免过度承诺？
6. 关键判断是否有权威来源或可复核依据？

### 4.4 明确禁止

- 用空话段落填充篇幅
- 复制相邻章节大段内容充数
- 堆工具名单替代原理与方法
- 只有口号式 AI 展望，没有机制与证据
- 例子与主案例脱节，导致全书碎片化

## 5. 全书成书资产（出版级硬门槛）

除 28 章正文外，还必须具备：

| 资产 | 要求 | 建议位置 |
| --- | --- | --- |
| 前言/阅读指南 | 读者、主线、阅读路径、案例约定清楚 | `README.md` |
| 正式目录 | 与 `SUMMARY.md` 一致 | `SUMMARY.md` / `docs/book-outline.md` |
| 贯穿案例说明 | 业务故事、任务表、产物契约 | `docs/sample-case/README.md` + `examples/mini-shop/` |
| 术语表 | 核心术语统一定义与首次出现规范 | `docs/glossary.md`（或书内附录页） |
| 符号与缩略语 | AST/CFG/DFG/IR/MCP 等统一写法 | 术语表中维护 |
| 图示清单 | 每张关键图的用途、类型、状态 | `docs/image-plan.md` |
| 引用与资料卡 | 关键判断可追溯；重点章有资料卡 | `docs/research-cards/` |
| 交叉引用 | 前后章互相指向，避免孤立重讲 | 正文内链 |
| 练习体系 | 样章与关键章有练习；实践章有验收清单 | 各章 + 可选 `docs/exercises.md` |
| 版本与勘误入口 | 版本说明、如何反馈错误 | README 或 `docs/changelog.md` |

没有术语表、图示计划、引用体系和贯穿案例契约，不得宣布出版级终稿。

---

## 6. 图示完成标准

图示分三层，出版级终稿要求如下：

### 7.1 必须

1. 关键结构图、流程图、调用链、系统分层图：全书风格统一
2. 所有需要图的章节，至少有可渲染图（Mermaid 或静态图）
3. 图中名词与术语表一致
4. 图能服务论证，不是装饰

### 7.2 关键技术图升级

以下主题优先提供精确技术图（SVG/PNG），不能只停留在“后续 AI 配图备注”：

- 源码 → Token → AST
- CFG / DFG 示例
- `mini-shop` 代码图谱与影响路径
- 软件理解系统分层
- Agent 上下文包 / 验证报告信息结构

### 7.3 AI 插画

- 仅用于封面、篇首概念图、PR mockup 等
- **不能替代**需要精确阅读的技术图
- 风格统一为技术书籍风

---

## 7. 引用、事实与一致性标准

### 7.1 权威引用总原则

出版级终稿要求：**尽可能参考更多权威、可核查的来源**，并让引用真正支撑论证。

优先级从高到低：

1. **一级来源**：语言规范、官方文档、标准规范、学术论文、官方工程规范
2. **高可信工程来源**：主流工具官方文档、成熟开源项目文档、被广泛引用的经典技术书
3. **次级来源**：高质量技术综述、官方博客、可复核的工程白皮书
4. **低优先级**：个人博客、二手转述、无法核查的截图/口述（默认不作为关键判断唯一依据）

### 7.2 引用覆盖要求

| 要求 | 标准 |
| --- | --- |
| 章级引用 | 每章“延伸阅读与参考资料”通常不少于 3 条高相关来源；关键章建议 5 条以上 |
| 论点级支撑 | 定义、算法思想、标准术语、工具能力边界、公开基准/数据等关键判断，应尽量有来源 |
| 正文回指 | 重要结论不能只在文末挂链；应在论述处体现依据（链接、标准名、论文名或资料卡编号） |
| 来源多样性 | 避免全书只重复引用同一两篇博客；原理、分析、观测、AI 工程应有不同权威源 |
| 可核查性 | 链接可访问或给出稳定文献标识；过时链接需替换或注明版本 |
| 资料卡 | 重点章与高争议判断应有 `docs/research-cards/` 资料卡（来源、可信度、适用章节、局限） |

### 7.3 分主题建议权威源类型

| 主题 | 优先参考 |
| --- | --- |
| 语言/语法/AST | 语言规范、Compiler/Parser 官方文档、Tree-sitter/ANTLR/JavaParser 等官方资料 |
| 程序分析 | 经典静态分析文献/教材、CodeQL 等官方 dataflow 文档 |
| 运行时观测 | OpenTelemetry 规范与官方文档、主流 tracing 概念文档 |
| 变更与协作 | Git 官方文档、PR/CI 平台官方文档 |
| 图谱与查询 | 图数据建模文档、代码属性图/代码索引相关权威资料 |
| AI Coding / Agent | 官方工具文档、MCP 等协议文档、公开基准（如 SWE-bench）与可复核论文/报告 |
| 架构与改造 | 经典架构模式与可核查工程方法（如 Strangler Fig、ADR 等） |

### 7.4 引用质量红线

- 禁止用“据说/业界都知道”支撑关键结论而不给来源
- 禁止把营销页或未审核转载当一级证据
- 禁止堆大量无关链接充数
- 工具能力描述以官方文档为准，不凭印象夸大
- 若只能给经验判断，必须明确标注为工程经验/本书方法，不伪装成标准结论

### 7.5 其他一致性标准

| 维度 | 出版级标准 |
| --- | --- |
| 术语 | 代码图谱、软件理解系统、Agent 上下文、证据层等全书统一；有术语表 |
| 深度 | 相邻同类章深度接近，无“一章很厚、一章只有提纲” |
| 丰富度 | 满足第 4 节；例子、边界、模板、练习充分 |
| 案例 | 优先 `mini-shop`；新例子必须说明与主案例关系 |
| 数据契约 | artifacts 字段名、实体 ID、PR-42 数字（如 180→170）前后一致 |
| 边界 | 不做工具测评合集；不写完整编译器；不铺开全部传统场景 |
| 重复 | 第四篇与第五篇不互相复制；实践篇不重讲原理全文 |
| 审校 | 完成至少一轮全书一致性审校并记录问题关闭 |

`docs/chapter-quality-matrix.md` 中 28 章状态均应为 **定稿** 或 **样章定稿**，不得停留在草稿 / 可读 / 需重构。

---

## 8. 可复现与实践完成标准

出版级终稿要求读者能“跟做”，不只是“看懂”：

1. `examples/mini-shop` 结构完整、可读、与正文一致
2. artifacts 至少包括：
   - `code-graph.json`
   - `pr-42.diff`
   - `impact-report-pr-42.json`
   - `agent-context-pack.json`
   - `verification-report-pr-42.md`
3. 实践篇给出：
   - 输入
   - 步骤
   - 输出 schema / 样例
   - 验收标准
4. 关键命令、路径、JSON 字段在书中出现时保持一致
5. 若提供脚本/工具，需写明运行前提；若不提供可运行工具，须明确“手工/伪代码可复现路径”

---

## 9. 发布与交付完成标准

主发布形态：HonKit 静态站 + GitHub Pages。

### 9.1 构建质量

1. `npm run build` 稳定成功
2. `SUMMARY.md` 与正文内链全部有效
3. Mermaid 可正常渲染
4. 无空章、明显坏图、明显错链
5. 本地预览与线上版本一致

### 9.2 线上发布

1. GitHub Pages（或等价公开地址）**真实可访问**
2. 有可复现部署说明：`docs/github-pages-deploy.md`
3. 有自动化构建/部署或同等可靠发布流程
4. README 中的阅读地址可用且指向当前版本

### 9.3 发行增强（非 RC 硬门槛，属 Release+）

- PDF / 纸书专业排版
- ISBN / 纸质出版流程
- 公众号连载改编
- 多语言完整工业实现
- 全量商业级插画

以上不做完，不阻碍 RC；但 **RC 本身必须是可公开、可稳定阅读的成书质量**。

---

## 10. 编辑与审校完成标准

出版级终稿必须完成：

1. **结构审校**：目录递进、篇章职责、前后依赖
2. **术语审校**：术语表与正文一致
3. **案例审校**：`mini-shop` / `PR-42` 数字、实体 ID、路径一致
4. **引用审校**：死链、明显过时或无法支撑论点的引用处理
5. **语言审校**：病句、重复段、口语化工作备忘残留、中英文混用规范
6. **教学审校**：练习可做、小结可检验、阅读路径清楚
7. **构建审校**：build / link / 关键页抽检

建议在 `docs/editorial-checklist.md` 或质量矩阵中保留审校记录；没有“问题关闭”记录，不得口头宣称终稿完成。

---

## 11. 状态模型（质量矩阵）

章节状态升级为：

| 状态 | 含义 |
| --- | --- |
| 草稿 | 有提纲或初稿，结构/例子不足 |
| 可读 | 主线清楚，可内部阅读，未达出版深度 |
| 样章定稿 | 三类样章达到出版模板标准 |
| 定稿 | 达到第 3 节单章定稿标准 |
| 需返工 | 审校发现问题，必须修改 |

**出版级终稿要求：**

- 3 个样章 = 样章定稿
- 其余 25 章 = 定稿
- 0 章停留在草稿 / 可读 / 需返工

---

## 12. 出版级终稿总验收清单

### A. 内容与教学

- [x] 28 章全部定稿
- [x] 3 个样章定稿，并被其他章对齐
- [x] 读者四类能力可被正文直接支撑
- [x] `mini-shop` 贯穿 AST / 图谱 / 影响面 / 上下文 / 验证报告
- [x] 实践闭环可跟做，artifacts 与正文一致
- [x] 第四篇仅 3 场景，主线未退化成工具或场景合集
- [x] 关键章有练习；实践章有验收标准
- [x] 内容丰富度达标：例子、步骤/模板、边界、失败模式充分，无空心章
- [x] 术语表完成，并与正文一致
- [x] 图示清单完成；关键技术图达到可出版清晰度
- [x] 权威引用充分：章级参考资料达标，关键判断尽量有一级/高可信来源
- [x] 资料卡体系覆盖重点章与高争议判断
- [x] 公开正文无旧稿迁移/重写过程叙述

### B. 一致性与审校

- [x] 术语、深度、案例、数字、实体 ID 一致
- [x] 完成结构 / 术语 / 案例 / 引用 / 语言 / 教学 / 构建审校
- [x] 质量矩阵状态全部为定稿或样章定稿
- [x] 已知问题清单：本地内容 P0 已关闭；E006 公开同步已完成（公开站点部署并抽检 200，与 §14 状态一致）

### C. 发布交付

- [x] HonKit 构建稳定成功
- [x] 目录与正文链接全部有效
- [x] Mermaid/关键图渲染正常
- [x] GitHub Pages（或等价地址）公开可访问（已启用并部署，抽检 200）
- [x] 部署说明与 README 阅读入口正确
- [x] 版本说明 / 勘误反馈入口可用

### D. 明确不纳入 RC 但可后续做

- [ ] PDF/纸书专业版式
- [ ] 全量精美插画
- [ ] 真实公司案例
- [ ] 多语言工业级实现
- [ ] 课程/训练营改编

---

> 状态说明：A/B/C 全部完成，E006 已关闭，可宣布出版级终稿（RC）。

## 13. 与旧“v1 可读闭环”的关系

| 旧说法 | 新口径 |
| --- | --- |
| v1 完整 | 仅等于 **Beta：内容可读稿** |
| v1.1 精修 | 并入 **RC 出版级终稿** 的硬门槛（图示、术语、引用、审校、加厚） |
| v2 衍生 | 对应 **Release+**（PDF、更多案例、发行形态） |

因此：

- 只完成“28 章可读 + 能 build + 有案例骨架”**不能**宣布出版级终稿
- 必须完成第 3–10 节与第 12 节清单，才可宣布 RC

---

## 14. 当前状态（对照新标准）

| 项目 | 状态 | 说明 |
| --- | --- | --- |
| 主线与目录冻结 | 已完成 | 不再大改大纲 |
| 28 章定稿结构/练习/引用 | 已完成 | 每章达标轮次 |
| 术语表/图示清单/资料卡/审校清单 | 已完成 | 成书资产齐全 |
| 关键精确技术图 | 已完成 | 13 张 SVG |
| 内容丰富度 | 已完成两轮 | 第二轮补 schema/模板/失败模式/工作示例 |
| 权威引用与资料卡 | 已完成一轮 | ≥5 外链/章 + 18 资料卡 |
| 语言审校 | 已完成一轮 | 见 language-review-notes |
| 质量矩阵状态 | 已升格 | 25 定稿 + 3 样章定稿 |
| 本地构建与链接 | 已完成 | `npm run build` + 内链检查 |
| 线上公开站点同步 RC | **已完成** | GitHub Pages 已部署并抽检（见 rc-completion-log） |
| 出版级终稿 | **可宣布** | 全部门槛已关闭；E006 已验证 |


## 15. 使用方式

后续每次扩写、审校或准备发布前，先问：

1. 这是在推进 **RC 出版级终稿**，还是只在修 Beta？
2. 该章是否已达到第 3 节“定稿”与第 4 节丰富度，而不只是“可读”？
3. 关键判断是否有足够权威引用/资料卡支撑？
4. 是否同步更新了术语表、图示清单、artifacts、质量矩阵？
5. 公开文字是否仍像一本正常技术书？
6. 若今天发布，是否经得起“给陌生人自学”和“公开链接长期可读”的检查？

相关文档：

- 定位：[`content-positioning.md`](content-positioning.md)
- 目录：[`book-outline.md`](book-outline.md)
- 章节状态：[`chapter-quality-matrix.md`](chapter-quality-matrix.md)
- 推进方案：[`content-confirmation-and-optimization-plan.md`](content-confirmation-and-optimization-plan.md)
- 贯穿案例：[`sample-case/README.md`](sample-case/README.md)
- 部署：[`github-pages-deploy.md`](github-pages-deploy.md)
- 写作框架：[`ai-writing-framework.md`](ai-writing-framework.md)