应用部分 0. AgentClinic-production 实验室

状态：教学路线的标准内容。 这一部分不引入新技术。它解释如何将第二卷作为第一卷之后的单一实验分支来阅读。

第一卷构建了一个小型 AgentClinic：路由、SQLite、功能规格、检查和审查。在第二卷中，同一个项目被用作教学生产模型。我们不要求真正的 Kubernetes、Grafana、PagerDuty 或 GitOps。这些词语在场景中代表角色：信号从何而来、什么操作可能是危险的、何处需要回滚、什么工件能证明解决方案。

如果将各章读作一组独立的高级技巧，这一卷很快就会变得沉重。换一种方式阅读：一个项目、一个主要生产流程、一个不断增长的证据包。默认使用 high_memory_usage 来通过考核；其他事件仅作为小型实验窗口，用于展示单独的机制。

第一次通过的实践规则：capstone/README.md 应该针对一个事件案例作答。另一章的本地示例可以使用不同的事件，但只有可验证的原则才能转入考核包。例如，从 autoscale_200pct 转入的不是第二个案例，而是保护规则（guard）「不得超出配额扩大影响半径」。从 cdn_error_budget_burn 转入的不是新服务，而是反古德哈特定律不变量「不得以静默 P0 为代价改善 MTTR」。

阅读前

第 0 部分是方法性的，没有教学案例。这里没有步骤和验证事实；任务是设定本卷的地图并协调执行栈。从下一章开始，标准的「阅读前」区块将回归，并作为章节与考核之间的契约。

目标

在第 1 章之前需要理解四件事：

• 什么教学生产案例贯穿考核包；
• 哪些文件被视为每章的成果；
• 哪些命令真正可运行，哪些只是未来生产层的接口；
• 教学最小值在哪里结束，完整实施轨道从哪里开始。

贯穿案例

基本场景称为 AgentClinic-production。这是同一个 AgentClinic，但现在它周围有一个运维流程。主要考核案例是 appointments-api 中的 high_memory_usage：便于将其推进到 webhook 规范化、readiness 网关、试运行和最终证据包。额外案例展示单独的机制，但不必混合在同一个 capstone/ 中。

• 服务 appointments-api；
• 告警 high_memory_usage、autoscale_200pct、appointment_latency / appointment_latency_spike、node_not_ready、cdn_error_budget_burn；
• 必须经受 /clear、模型切换和他人审查的规格；
• 禁止无证据的危险操作：扩大影响半径、丢失审计、静默关闭 P0、自动绕过回滚。

教学分支不必包含真正的生产代码。capstone/ 中的工件、examples/templates/ 中的模板和 examples/ 中的可运行示例就足够了。如果某章使用非 high_memory_usage 的案例，只在 capstone/ 中记录可验证的产出：什么缺陷、反例、预算风险或不变量需要转入主案例。

简短转移地图：

执行栈

第一卷中 AgentClinic 是一个 TypeScript、Hono、服务器端 JSX、SQLite 和 Vitest 的应用程序。这个栈不会消失：在教学模型 AgentClinic-production 中，它仍然是产品本身的栈。

第二卷出现了第二层代码 —— book2/examples/ 中的小型可运行脚本。它们用 Python 标准库编写，目的仅在于让一个人能在自己的机器上几秒钟内运行章节的最小示例，无需搭建基础设施。这不是产品栈的变更，也不是暗示生产 AgentClinic 用 Python 重写。这些是教学模拟器：stress-mutator、对决、Spec CI、令牌预算、readiness 计算器。在真实项目中，这些检查通常作为 pre-commit、GitHub Actions、MCP 工具或自有栈上的服务实现 —— 这里用 Python 只是因为它是无需构建即可运行的最便宜语言。

规则很简单：book2/examples/ 中的所有内容都可以作为 python3 ... 无依赖运行。章节中标记为 [project script] 或 [conceptual interface] 的所有内容，是未来脚本或您项目中集成的形式，不绑定于 Python。

最小路线

如果时间有限，按以下方式通过第二卷：

1. 阅读本部分和所选可运行示例的 README。
2. 在第 1–3 章填写三个手工工件：genealogy.md、poisoned/fixed 对和 constitution.md。

1. 在第 4–11 章只运行 examples/ 中的 [runnable] 命令；将其他案例的结果作为原则转入 capstone/，而非作为新领域。
2. 在第 12 章用诊断检查清单验证包。
3. 在第 13 章围绕一个事件组装小型 capstone/。

最小路线不需要编写外部编排器、MCP 服务器、Kubernetes 集成或真正的 CI 网关。这些元素属于完整轨道。

路线验证很简单：每章之后 capstone/ 中应出现一个可验证的新产出。不是完整的生产流程，而是一个可以展示给他人的小记录。

> 如何阅读表格。 「产出」列故意用平实语言描述，不使用第 4–13 章的术语。如果右列出现下方短词典中尚不存在的词，它会在需要的那一章引入。不要试图通过此表格学习本卷词汇。

| 3 | constitution.md 有两条不可变规则和一条有期限的规则 | | 4 | 一条规则的最小反例或下一个限制器的表述 | | 5 | stress-mutator 的 smoke 运行结果或验证器捕获哪些突变的简要报告 | | 6 | 一个接受和一个拒绝的 shadow 候选（可能进入规格的备选规则） | | 7 | Spec CI 的一行：什么已覆盖，什么被阻断 | | 8 | 一个争议变更的裁决文件，附证据链接 | | 9 | 模型预算耗尽风险和切换至廉价层级的阈值 | | 10 | 一个目标指标和一对反古德哈特的保护指标 | | 11 | 生产准入裁决和允许操作的 dry-run | | 12 | 三个 blocker / owner / next_check 条目 | | 13 | 围绕一个事件组装的 capstone/，有五条评分标准的 PASS 记录 |

如果章节中遇到额外术语但没有此产出，先完成产出。术语可以稍后补读。

作为参考，将填好的示例 [examples/templates/capstone-dossier.md](examples/templates/capstone-dossier.md) 放在手边。这不是无脑复制的模板，而是回答「第一次通过后应留下什么痕迹？」的最小形式。

第一次通过的短词典很短：

• capstone/ — 围绕一个事件的最终证据包；
• genealogy.md — 需求来源和确信度；
• validation.md — 命令、手工事实和阻断器；
• judgment.md — 争议变更的裁决；
• readiness.md — 为什么允许、阻断或转入半手动模式。

所有其他术语只在帮助填写这些文件之一时才需要。如果术语不影响当前章节产出，第一次阅读时不要停留。

真正要运行的

第二卷使用三种命令块：

• [runnable] — 按所写运行。示例位于 book2/examples/。
• [project script] — 这是您项目中未来脚本的契约。如果旁边没有标注可运行等价物，该命令不必存在于教程仓库中。

• [conceptual interface] — 未来集成的形式。教学通过时无需运行。

规则很简单：考核包只能引用您真正运行过的事实，或无需聊天记录即可阅读的手工工件。

第一次 smoke 运行

在阅读第 4–11 章之前，验证本地示例能运行是有用的：

bash book2/examples/smoke_all.sh

脚本在 book2/examples 的临时副本上运行 smoke 测试，因此不会在工作树中留下 out/ 和 __pycache__。如果时间有限，打开 examples/README.md 只选择当前正在通过的章节区块。

考核工作目录

创建未来包的目录：

mkdir -p capstone

暂时留空。在第 1–12 章中，您会逐渐理解哪些文件会进入其中。不要在一个证据包中混合多个事件：一个文件可以引用另一案例的可运行等价物，但解决方案必须解释一个主事件。

capstone/
  README.md
  genealogy.md
  poisoned-spec.md
  fixed-spec.md
  constitution.md
  validation.md
  judgment.md
  budget-note.md

goodhart-note.md
  readiness.md
  antipattern-audit.md

此结构重复第一卷：先意图和边界，再计划和事实，再审查和最终包。第二卷的唯一区别是事实不关乎单一功能，而关乎危险操作的生产准入。

第一次通过时，不要因为某文件在章节中被命名就将其从完整轨道加入 capstone/。scorebook、metric_network、decision_hash、precedents.md 和 CI 报告只在您真正创建它们或能解释什么可运行等价物确认同一原则时才需要。

为便于定位，哪章开启哪个文件：

如果途中章节出现此列表之外的第四或第五个文件 —— 这是完整轨道。将原则记录为一行然后继续前进。

验证事实

本章之后，已选定一个主事件案例，已创建空 capstone/，且已通过 bash book2/examples/smoke_all.sh 验证可运行示例或因明确原因推迟。如果您说不出主案例和将第一个进入 capstone/ 的文件，现在转入第 1 章为时尚早。

检查问题

1. 为什么 AgentClinic-production 是教学模型，而非要求搭建真正基础设施？
2. [runnable] 与 [project script] 有何区别？
3. 为什么最终 capstone/ 中不能将 high_memory_usage 和 autoscale_200pct 作为两个平等案例混合？
4. 为什么最终 capstone/ 必须无需聊天记录即可理解？