学习指南: 应用部分 0. AgentClinic-production 实验室

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

难度级别：中级

预计学习时间：4-6 小时（理论 + 第一次实践）

前置条件： 已完成 AgentClinic 第一卷（路由、SQLite、功能规范、检查与审查）

具备 TypeScript 和 Python 基础能力

理解 CI/CD 和生产运维概念，达到阅读水平

能够使用命令行和 Git

熟悉告警、指标和事件管理概念

学习目标： 解释教学生产模型与真实基础设施之间的区别，正确理解 Kubernetes、Grafana、PagerDuty 作为场景标识的角色

区分三种类型的命令块（[runnable]、[project script]、[conceptual interface]），并在形成评分包时仅应用 [runnable] 命令的运行规则

在 appointments-api 中构建贯穿式评分案例 high_memory_usage，选择主要事件并从附加案例中筛选原则迁移至 capstone/

创建 capstone/ 结构并按第 1-3 章的最小路径填写首批工件（genealogy.md、规范对、constitution.md）

执行 smoke 测试 bash book2/examples/smoke_all.sh 并在进入第 4-11 章前验证教学模拟器的可用性

概述：应用部分 0 是 AgentClinic 第二卷的方法论导论实验室。它不引入新技术，而是建立阅读地图：如何将一系列高级章节转化为围绕熟悉的 AgentClinic 项目的统一教学生产轮廓。关键洞察：第二卷使用相同的技术栈（TypeScript、Hono、SQLite），但增加了第二层——book2/examples/ 中的小型 Python 脚本作为教学生产机制模拟器。这些脚本不替代产品栈；它们提供在数秒内运行最小示例而无需搭建基础设施的能力。部分 0 引入「一个项目、一个主要轮廓、一个不断增长的证据包」规则，定义贯穿式案例 high_memory_usage、capstone/ 结构和有限时间的最小路径。成功完成本部分的衡量标准是控制事实：已选择主要事件案例，已创建空 capstone/，已验证或可延迟 [runnable] 示例并说明明确原因。

关键概念： Agentclinic-production：围绕熟悉的 AgentClinic 项目的教学生产模型。不需要真实的 Kubernetes、Grafana、PagerDuty 或 GitOps——这些术语表示场景中的角色：信号来自何处、何种操作危险、何处需要回滚、何种工件证明解决方案。该模型允许在不投入基础设施成本的情况下学习生产实践。

High memory usage：贯穿式评分的主要案例。appointments-api 服务中的事件，便于构建完整证据包：webhook 规范化、就绪性网关、试运行、最终包。其他案例（autoscale_200pct、cdn_error_budget_burn、node_not_ready 等）作为单独机制的实验室窗口，但其原则迁移至主要案例，而非作为平等案例混合。

Capstone/：单一事件的最终证据包。结构遵循第一卷的逻辑：意图与边界 → 计划与事实 → 审查与总结。每章打开特定文件。关键规则：包中只有一个事件，无需聊天历史即可理解解决方案。

三种命令块类型：[runnable]——按所写运行，book2/examples/ 中的示例；[project script]——您项目中未来脚本的契约，不必须在仓库中存在；[conceptual interface]——未来集成的形式，教学过程中不运行。评分包仅引用已运行的事实或无需聊天上下文即可阅读的手动工件。

教学模拟器（python stdlib）：第二卷的第二层代码——Python 标准库的小型脚本。不是产品栈的更换，而是运行示例的最廉价方式，无需构建：stress-mutator、对决、Spec CI、令牌预算、就绪性计算器。在真实项目中，这些检查将成为 pre-commit、GitHub Actions、MCP 工具或产品栈上的服务。

原则迁移 vs. 案例迁移：从章节本地案例迁移至 high_memory_usage 的不是案例本身，而是可验证的原则。例如：从 autoscale_200pct——guard 规则「不超出配额扩大影响半径」；从 cdn_error_budget_burn——反古德哈特定律不变量「不能以静默 P0 为代价改善 MTTR」；从 node_not_ready——需求溯源和「无恢复证据不关闭」规则。

Genealogy.md：第 1 章工件。需求的来源和确信程度。最小输出：一个需求配两个来源。

Poisoned-spec.md / fixed-spec.md：第 2 章工件。「有缺陷/已修复」规范对，展示一类错误。

Constitution.md：第 3 章工件。两条不可变规则和一条有期限的规则。

Validation.md：第 4 和 7 章工件。命令、手动事实和阻塞项。包含 happy path、negative path 和反例。

Judgment.md：第 8 章工件。有争议变更的裁决，引用证据。

Budget-note.md：第 9 章工件。模型预算耗尽风险和切换至廉价层级的阈值。

Goodhart-note.md：第 10 章工件。目标指标和配对保护指标，防止古德哈特偏差。

Readiness.md：第 11 章工件。生产准入裁决和允许操作的 dry-run。

Antipattern-audit.md：第 12 章工件。三个 blocker / owner / next_check 条目。

最小路径：有限时间的缩短路径：部分 0 + README runnable 示例 → 第 1-3 章（三个手工工件）→ 第 4-11 章（仅 [runnable] 命令，其他案例的原则作为字符串迁移）→ 第 12 章（诊断检查清单）→ 第 13 章（用评分标准的五条 PASS 行组装 capstone/）。不需要外部编排器、MCP 服务器、Kubernetes 集成。

完整路径：带真实集成的扩展路径。仅当实际创建或有 runnable 等效物确认原则时，才添加 scorebook、metric_network、decision_hash、precedents.md 和 CI 报告等文件。

练习： 标题：命令块分类

问题：向您展示第二卷不同章节的三个片段：

片段 A：python3 book2/examples/stress-mutator/run.py --spec capstone/fixed-spec.md 片段 B：[project script] deploy-gate --readiness capstone/readiness.md --dry-run 片段 C：[conceptual interface] 与 PagerDuty Oncall API 集成以自动分配工程师

确定每个片段的类型。指出哪个现在可以运行，哪个可以稍后在自己的项目中实现，哪个在教学过程中不运行。解释评分包是否可以引用每个片段。

解答：1. 片段 A——[runnable]。如果文件 capstone/fixed-spec.md 存在，现在即可运行。评分包可以将运行结果引用为可验证事实。

1. 片段 B——[project script]。这是您项目中未来脚本的契约。不必须在教程仓库中存在。评分包仅当您实现并运行了等效物，或描述了无需聊天上下文即可阅读的手动工件时，才能引用它。
2. 片段 C——[conceptual interface]。未来集成的形式，教学过程中不运行。在第一次通过时不作为事实进入评分包；如果原则重要，作为一行不变量记录在相应的 capstone/ 文件中。

难度：初级

标题：为 autoscale_200pct 构建迁移地图

问题：您正在阅读带有本地案例 autoscale_200pct 的章节。按照部分 0 的规则，您不应将此案例与主要案例 high_memory_usage 混合在同一个 capstone/ 中。阅读章节后，您看到：自动扩展在告警时使资源翻倍，但这扩大了影响半径（波及相邻服务），超出配额。应将什么原则迁移至主要案例 high_memory_usage，并记录到 capstone/ 的哪个文件中？

解答：1. 本地案例 autoscale_200pct 作为实验室窗口保留在章节中。

1. 要迁移的可验证原则：guard 规则「不超出配额扩大影响半径」。
2. 此规则属于反例或限制器，因此记录到 validation.md（第 4 和 7 章）作为 negative path，或作为 constitution.md（第 3 章）中的有期限规则，如果它定期检查。
3. capstone/ 中的表述：一个具体条目，例如：「Guard：high_memory_usage 告警时，扩展受配额 X 限制；autoscale_200pct 的反例显示，超出配额导致级联故障」。
4. 允许引用本地 runnable 示例，但 README.md 中的解决方案解释 high_memory_usage。

难度：中级

标题：Smoke 测试与故障诊断

问题：您在第 5 章前执行 bash book2/examples/smoke_all.sh。脚本在 stress-mutator 块失败，错误为 ModuleNotFoundError: No module named 'json'。利用部分 0 的知识，确定可能的原因和操作。是否可以在不修复的情况下继续教学路径？

解答：1. json 是 Python stdlib 的一部分，在正常安装中不可能出现 ModuleNotFoundError。可能原因：脚本在隔离环境中运行（自定义 Python 构建、无 stdlib 的容器，或 PYTHONPATH 被覆盖）。

1. 检查：python3 -c "import json; print(json.__file__)"——如果失败，环境已损坏。
2. 根据部分 0，所有 book2/examples/ 使用 Python stdlib，应无需依赖即可运行。如果 json 不可用，这是环境契约违约，不是教学材料问题。
3. 操作：检查 which python3，使用系统 Python 3.8+，移除带有自定义配置的虚拟环境。
4. 是否可以在不修复的情况下继续：不行，smoke 测试是第 4-11 章前的控制事实。但可以选择最小方案：打开 examples/README.md，手动运行当前章节块，以「环境非标准，第 5 章已手动验证」的明确原因延迟其余部分。

难度：中级

标题：第 3 章后设计 capstone/ 结构

问题：您已通过最小路径完成第 1-3 章。您有：genealogy.md 包含需求「readiness-gateway 必须检查 memory_before_allow」（来源：事件 high_memory_usage 和团队 SRE 指南），poisoned-spec.md/fixed-spec.md 对展示缺陷「告警不区分 memory leak 和 legitimate spike，以及 constitution.md` 包含两条不可变规则（「无 dry-run 不操作」和「所有 P0 需要审计」）和一条有期限规则「readiness 检查有效期 24 小时」。检查这是否符合部分 0 的最小输出。进入第 4 章还缺什么？

解答：1. 按最小输出表检查：

• 第 1 章后：genealogy.md 中一个需求配两个来源——✅（需求 + 事件 + SLE 指南）。
• 第 2 章后：展示可见错误类的规范对——✅（poisoned/fixed 展示告警分类缺陷）。
• 第 3 章后：constitution.md 含两条不可变和一条有期限——✅。

1. 进入第 4 章需要对一条规则的最小反例或下一个限制器的表述。这是第 4 章的输出，不是第 3 章——因此已准备好进入第 4 章。
2. 但建议预先选择 constitution.md 中哪条规则将在第 4 章获得反例。推荐：「readiness 检查 24 小时」规则——易于构建检查 25 小时后到达告警的反例。
3. 检查 capstone/ 结构：文件不混合事件，每个无需聊天历史即可阅读——✅。
4. 仅缺 smoke_all.sh 的运行或其有原因的主动延迟。

难度：中级

标题：区分最小路径和完整路径

问题：在第 7 章您遇到术语 scorebook、Spec CI pipeline、decision_hash。根据部分 0，如何确定评分包是否需要这些术语？您当前的最小输出是 Spec CI 的一行：覆盖什么，阻塞什么。如果 scorebook 和 decision_hash 未由您创建但已在章节中概念性描述，请制定应记录到 capstone/ 的内容。

解答：1. 部分 0 规则：如果术语不影响当前章节输出，第一次阅读时不要停留。

1. 第 7 章最小输出：Spec CI 的一行——覆盖什么，阻塞什么。这进入 validation.md。
2. scorebook 和 decision_hash 是完整路径的元素。仅当您实际创建它们或能解释确认相同原则的 runnable 等效物时才需要。
3. 操作：在 validation.md 中记录 scorebook 和 decision_hash 所保护的原则，一行，不提及术语本身。例如：「覆盖：规范通过 5/5 Spec CI 检查。阻塞项：如果 mutator 发现未处理 payload，禁止 merge。可验证事实：在 fixed-spec.md 上运行 python3 examples/spec-ci/run.py 得到 PASS」。
4. 如果后来在完整路径中实现 scorebook——再添加文件。第一次通过时这是多余的。

难度：高级

案例研究： 标题：教学模型向真实 SRE 实践的迁移：从 AgentClinic-production 到生产就绪流水线

场景：8 人团队通过最小路径完成 AgentClinic 第一和第二卷。他们的 capstone/ 包含 high_memory_usage 的完整包：genealogy.md 含两个来源、展示告警分类缺陷的规范对、含 guard 规则的 constitution.md、含 stress-mutator 和 Spec CI 结果的 validation.md、含 dry-run 裁决的 readiness.md。团队接到任务，为临床网络的医生预约真实服务实施类似流程。

挑战：翻译教学模型的三个关键问题：(1) 真实服务使用 Go 和 PostgreSQL，非 TypeScript/SQLite——产生丢弃教学栈作为无关的诱惑；(2) 基础设施需要真实 PagerDuty、DataDog 和 GitHub Actions，非 Python 模拟器；(3) 管理层要求立即「完整路径」，包括 scorebook 和 metric_network，将周期从 2 周延长至 3 个月并导致项目瘫痪。

解决方案：团队应用部分 0 原则：(1) 分离产品栈（Go/PostgreSQL）与检查层——Python 模拟器替换为 GitHub Actions 和 Go pre-commit 钩子，但工件结构（genealogy.md、constitution.md 等）保留；(2) PagerDuty/DataDog 术语作为场景角色使用，逐步实现集成：首先是 Slack webhook 模拟器，然后是真实 PagerDuty；(3) 坚持最小路径：前 2 周交付 capstone/ 中 5 个文件的可运行流水线，按「每个冲刺一个新增可验证输出」的原则迭代添加完整路径。

结果：最小流水线 10 天内运行。第一个真实事件（预约服务的内存压力）按 capstone/ 在 45 分钟内处理，而非以往的 4 小时。「不扩大影响半径」guard 规则防止了支付网关的级联关闭。完整路径（scorebook、decision_hash）在 6 个月内迭代实施，无瘫痪。教学 Python 脚本作为新 guard 规则的本地调试原型工具保留。

经验教训： 教学模型的价值不在技术栈，而在工件结构和检查与产品分离的原则

最小路径不是弱者的简化，而是扩展前快速验证的策略

场景角色（PagerDuty、Kubernetes）允许在基础设施就绪前设计流程

无运行中最小路径的完整路径——架构瘫痪的风险

教程的 Python 模拟器作为 guard 规则原型工具有长久生命力

相关概念： AgentClinic-production

最小路径

三种命令块类型

原则迁移 vs. 案例迁移

capstone/

标题：案例混合错误：当 autoscale_200pct 吞噬 high_memory_usage

场景：工程师阅读第二卷并决定「正确做」——将两个事件作为平等案例纳入 capstone/。README.md 描述 high_memory_usage，但 validation.md 和 readiness.md 文件包含 autoscale_200pct 的解决方案，budget-note.md 则用于 cdn_error_budget_burn。

挑战：另一工程师审查时，包不可读：autoscale_200pct 的 guard 规则与 high_memory_usage 的就绪性网关矛盾，judgment.md 引用无上下文的争议变更，README.md 未解释包中为何有三个事件。审查者花费 2 小时弄清上下文并拒绝该包。

解决方案：按部分 0 规则重做：选择单一主要案例 high_memory_usage；其他案例的原则提取为相应文件中的单行不变量。例如，替代 autoscale_200pct 的章节——validation.md 中的一行：「Guard 规则：扩展受配额限制（autoscale_200pct 的反例）」。

结果：重做后的包 15 分钟内通过审查。工程师掌握了部分 0 的关键技能：原则与案例的分离。在后续项目中，他将此应用于将数十个事件的 post-mortem 整合为单一 guard 规则集。

经验教训： capstone/ 中混合案例造成不可读性和矛盾

「一个事件一个包」原则不限制学习，而是聚焦学习

「他人审查」是质量标准，非形式；包应无需聊天历史即可理解

另一案例的反例如果记录为不变量而非单独故事，可增强主要案例

相关概念： high_memory_usage

原则迁移 vs. 案例迁移

capstone/

validation.md

学习建议： 在接触代码前完整阅读部分 0。这是无步骤的方法论章节；其目的是地图，非执行。不选择评分案例就「直接运行 smoke_all.sh」的尝试将导致积累无关工件。

阅读后立即物理创建 mkdir -p capstone。空目录是决策锚点：「这个文件放这里还是完整路径？」

打印或保持打开「章节后 → 最小输出」表。用作检查清单：如果章节后文件不符合描述，仅在完善后进入下一章。

视觉风格：在纸上绘制 capstone/ 文件之间的箭头。genealogy.md → poisoned-spec.md/fixed-spec.md → constitution.md → ... 这有助于看到每个文件不是孤立文档，而是证据链的一环。

听觉学习者：大声朗读控制问题并在检查前语音记录答案。如果回答超过 30 秒——可能理解不够深入。

动觉学习者：物理执行 smoke 测试，不阅读脚本。然后在编辑器中打开 smoke_all.sh 并追踪哪个块属于哪章。手动匹配「代码 → 章节 → 输出」强化结构。

处理附加案例（autoscale_200pct、cdn_error_budget_burn 等）时使用「一个原则一行」技术。打开目标迁移文件，在关闭章节标签页前记录原则。否则上下文会流失。

进行自我审查：关闭所有材料，尝试用您自己的话向 8 岁孩子或另一团队的同事解释「为何不能混合案例」。如果需要提及 Kubernetes 或 PagerDuty——您仍困在「真实基础设施」陷阱中，请逃向「场景角色」。

对于第 4-11 章：运行 runnable 示例前使用 --help 标志或研究 argparse 部分。理解模拟器参数比快速结果更重要——您应能解释脚本具体检查什么，而非仅它输出 PASS。

第 1 章前的最终测试：说出主要案例，展示空 capstone/，演示 smoke_all.sh 结果或其有原因的主动延迟。如果任何一点不可能——返回部分 0。

额外资源： Examples/templates/capstone-dossier.md：回答「第一次通过后应留下什么痕迹？」的最简形式。非无脑复制的模板，而是包结构自检的参照

Examples/readme.md：按章节块描述所有 runnable 示例。用于选择性 smoke 测试，如果完整 smoke_all.sh 耗时较长

Book2/examples/smoke all.sh：完整 smoke 测试脚本。在临时副本上运行，不在工作树中留下工件

AgentClinic 第一卷（路由、sqlite、功能规范）：第二卷的基础。确保理解第一卷的 genealogy.md 和规范对

部分 0 控制问题（文档内）：进入第 1 章前的四个自检问题。用作闪卡

第 4-13 章术语表：不要按部分 0 的表提前学习——术语在各章引入。但放在手边，遇到陌生词时快速查阅

总结：应用部分 0 是定义如何阅读 AgentClinic 第二卷作为统一生产轮廓而非孤立高级技术集合的基础方法论实验室。关键原则：(1) 教学模型 AgentClinic-production 使用场景角色替代真实基础设施；(2) book2/examples/ 中的 Python 脚本是本地运行的模拟器，非产品栈更换；(3) 单一贯穿案例 high_memory_usage，其余为实验室窗口用于原则迁移；(4) 三种命令块类型有明确的评分规则；(5) capstone/ 结构为无需聊天历史即可理解的不断增长证据包；(6) 最小路径 vs. 完整路径——扩展前的快速验证。成功完成的衡量标准是控制事实：已选择案例，已创建 capstone/，已验证 runnable 示例。后续所有内容建立于此基础之上。