实践篇 11. 与真实 API 集成：从规范到部署

状态：推荐。 SDD 阶段划分 Specify/Plan/Tasks/Implement/Validate 以及 25 分制就绪度（readiness）模型是推荐框架。它在教学流程中不要求真正的 Kubernetes、GitOps 或外部执行器。

前沿。 在关键路径上完全自动化、无需人工审批（human-review）的自动修复仍是前沿：即使拥有丰富 SDD 经验的团队也会让人类留在闭环中。Qwen Code 内置命令中此处只有 /plan；其余步骤是用户自定义命令，或通过项目脚本直接调用 qwen -p。

对于教学流程而言，本地流水线 examples/real-api/ 已经足够：规范化 webhook、通过就绪度关卡、并阻断被禁止的动作。GitOps、Kubernetes API 和完整的自动修复属于完整生产跟踪。

> [runnable] —— "webhook → 规范化 → 就绪度关卡 → 试运行"流水线的可运行版本位于 [examples/real-api/](examples/real-api/README.md)。脚本仅使用标准库，无外部依赖；它们不能替代生产基础设施，但可以本地运行关卡，并看到哪些条件会阻断动作。

high_memory_usage 场景对应的是第一册第 12 章中构建的同一个 SQLite 的读取峰值，以及相同的幂等迁移技巧。只是现在从运维的角度来看待它。在第 7 章、第 8 章和第 9 章第一册中演练的 Specify → Plan → Tasks → Implement 循环在此处并未被取消或取代。它被生产关卡包裹，并以类似第 16 章的团队评审证据包作为收尾。

阅读前

• 第一册基础：第 7–9 章定义了规范-计划-验证循环，第 16 章是团队评审。
• 本地教学案例：high_memory_usage，整个第一轮通行的经典案例。
• 在 capstone/ 中的产物：就绪度结论、两个阻断条件、以及允许动作的试运行（dry-run）结果。
• 第一轮通行的主要术语：readiness 和 dry-run。25 分制评分标准、audit_trace、GitOps、executor 为参考性内容。
• 可延后处理的内容：GitOps、Kubernetes API、完整 executor 以及无人工审批的自动修复。

目标

在教学最小化范围内，本章验证针对 high_memory_usage 的短链路 webhook -> 规范化 -> readiness -> dry-run。完整生产跟踪会将其扩展到 GitOps 部署、变更回滚（rollback）以及受限自动修复前的就绪度评估。每个动作都应与 specify/plan/tasks/implement/validate 工件关联，而不是淹没在手动命令中。

第一轮通行的实际产出不是生产编排器，而是一份证据：允许的动作能够通过 readiness，而禁止的动作在修改系统前被阻断。

此处的 readiness（就绪度）是对流水线按 25 分制、阈值为 23/25 的形式化评估。本章中的自动修复指带预批准动作（pre-approved actions）、回滚条件以及人工审批（human-review）的受限剧本。这并不是赋予代理任意修改生产的权利。

在该流水线中，Qwen Code 内置命令仅有 /plan。其余步骤（/sdd:specify、/sdd:tasks、/sdd:validate）应当在 .qwen/commands/sdd/ 中组织为用户自定义命令，或替换为通过 qwen -p 和项目脚本发起的常规提示。

最小化教学场景

教学案例

appointments-api 的生产事件 high_memory_usage 源自 MVP 阶段以及 book/part-12-mvp.md 中的 SQLite 迁移。流水线：Grafana+PagerDuty webhook → normalize_webhook.py → 基于 25 分制模型的就绪度关卡 → 对预批准动作列表进行试运行。目标是走完从原始负载到受控 restart_pod 的完整路径，并确认阻断条件（审计、有状态）能在该阻断的位置捕获失败。

准备

• book2/examples/real-api/fixtures/webhook_grafana.json、webhook_pagerduty.json —— 具有相同 incident_key 的原始负载。
• book2/examples/real-api/fixtures/incident_event.expected.json —— 规范化事件的标准参考。
• book2/examples/real-api/fixtures/readiness_pass.json（24/25）、readiness_block_audit.json（22/25 + 审计低于 1.0）、readiness_block_stateful.json（24/25，但有状态工作负载无备份）。
• book2/examples/real-api/specs/high_memory_usage/specify.md —— 预批准的 restart_pod 和 scale_up_replicas_one。
• book2/examples/real-api/scripts/normalize_webhook.py、check_readiness.py、dry_run.py。

步骤

1. cd book2/examples/real-api。预期：进入示例目录，无额外依赖。
2. python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json。*预期：返回码 0，规范化后的 incident_event 与标准参考一致。*
3. python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json。*预期：返回码 0，PASS incident=HM-2026-05-17-01 score=24/25。*
4. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json。*预期：返回码 1，原因是 audit_trace_coverage=0.7 < 1.0，加上总分下降（22/25）。*
5. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json。*预期：返回码 1，原因是 stateful workload 无已确认备份，即便总分为 24/25。*

不佳： 在就绪度关卡通过前运行 dry_run.py —— 动作在形式上被规范允许，但 audit_trace_coverage 或 backup_verified 可能缺失。 良好： 先过就绪度关卡，仅在关卡返回 0 时才进行试运行 —— 该顺序确保在检查动作列表前已明确影响半径。

1. python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod。*预期：返回码 0，PASS: action=restart_pod 已允许（spec 中 2 个动作）。*
2. python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace。*预期：返回码 1，BLOCK: action="delete_namespace" 在预批准列表中未找到。*

1. 在教学最小化范围内，到此为止：可运行链路展示了规范化、通过的允许路径以及对 audit/stateful/delete-namespace 的阻断。

如果你已安装 Qwen Code 并需要为评审提供解释，可执行一个单独的可选步骤：

qwen -p "阅读 @fixtures/readiness_block_audit.json 和 @specs/high_memory_usage/specify.md。要使 readiness 达到 23/25 且 audit_trace_coverage=1.0，需要补充什么？不要修改文件。" --approval-mode plan

此请求不包含在可运行最小化范围内。其输出可附在评审材料中，但 readiness 通过与否必须基于 check_readiness.py 和 dry_run.py。

验证事实

步骤 3、6 —— PASS。步骤 4、5、7 —— BLOCK，并在 stderr 中给出具体原因。如果步骤 5 在 stateful=true, backup_verified=false 时通过，则就绪度关卡存在缺陷：无法绕过对有状态工作负载的硬性阻断。

上述内容如何进入 capstone/

将 readiness 结论、两个阻断条件以及针对允许动作的 dry_run.py 结果整理到 capstone/readiness.md。在 capstone/validation.md 中列出实际运行的命令。除非已实现，否则 GitOps、Kubernetes API 和完整 executor 不属于教学最小化范围。

阅读这段内容的方式是：一个正向用例展示允许路径；两个 blockers 用例记录具体失败原因；dry_run 覆盖允许与禁止动作的边界情况。如果任何一行缺失，readiness 证据包就不完整。

readiness:
  pass_fixture: "readiness_pass.json -> 24/25"
  blockers:
    - "audit_trace_coverage=0.7 blocks auto mode"
    - "stateful=true without backup_verified blocks action"
  dry_run: "restart_pod PASS; delete_namespace BLOCK"

可评审的产物

脚本仅写入 stdout/stderr，不创建 out/。请以可读工件形式记录运行结果：简短的 capstone/readiness.md 或项目中的 CI 报告（若有）。最小化内容与上方 YAML 块相同的四行（pass_fixture、两个 blockers、dry_run）；完整的 25 分制报告仅在完整跟踪中需要。

不要为提交本身而创建提交标记。教学材料中重要的是可复现、可独立于聊天记录阅读的产物。

关键思想

追踪的起点是 audit_trace（Qwen Code 的实时日志），其中传入的 webhook 和规范差异（diff）被记录为同一条因果链。对于 HM-2026-05-17-01 事件，第一条记录将 incident_event.json、用户自定义命令 /sdd:specify 与创建的 specs/high_memory_usage/specify.md 关联起来。如果其中任何一项缺失，流水线就已丧失可证明性。日志的最小片段为：webhook_received -> incident_event_normalized -> /sdd:specify -> spec_diff_created；后续的每个差异都引用同一个 incident_id。/sdd:specify 是项目级扩展；应将其组织为 .qwen/commands/sdd/specify.md 中的用户自定义命令，或替换为直接的 qwen -p。

将 Grafana 和 PagerDuty 告警规范化为统一的 incident-event。否则不同来源会就同一事故给出不同版本。Grafana 提供指标和观察窗口，例如 memory_percent=93 持续 10m。PagerDuty 补充优先级、服务绑定和升级状态。规范化器将它们归并为 service、namespace、pod、severity、window_minutes、metric_context、source_refs 字段。之后 specify 步骤仅描述 WHY 和 WHAT：为何需要介入，以及什么结果算作成功。它不选择库、SDK 或具体的 API 端点。

实践中的含义。对比同一事件的两种 specify 写法：

不佳：

> high_memory_usage 的 Specify：通过 kubectl delete pod ... 重启 Pod

问题：specify 直接选择了实现命令，阻碍了 Plan 阶段。

良好：

> high_memory_usage 的 Specify：在动作执行后 5 分钟内将 memory_percent 保持在 80% 以下。预批准动作：restart_pod、scale_up_replicas_one。审计追踪为必需。

SDD 阶段划分保护流水线免于过早实现。每个阶段只负责自己的部分：

• Specify 明确用户故事、成功标准、功能与非功能约束；
• Plan 选择策略；
• Tasks 将其拆解为可执行步骤；
• Implement 通过受控机制应用变更。

这种结构与 GitHub Spec Kit（另见 GitHub Spec Kit 快速入门）中 Specify → Plan → Tasks → Implement 阶段的实用框架一致。在生产中这很重要，因为模型在未证明原因、介入边界和结果验证方式之前，并不会被赋予"直接处置"事件的权限。

不要把本章核心扩展成完整的生产编排器。第一轮通行中，这里仅验证 webhook -> 规范化 -> readiness -> dry-run 链路。前几章中的其他机制作为检查点出现：

• 第 4 章和第 8 章中的验证器在 dry-run 引发争议性反例时需要。
• 第 9 章中的分层预算在 frontier-reviewer 开始服务非高风险分支时需要。
• 第 10 章中的 Anti-Goodhart 在 memory 通过牺牲 5xx、延迟或人工审计而下降时需要。

如果这些机制尚未搭建，不要尝试在第 11 章内部模拟它们。将它们记录为阻塞点或对相应章节的引用，并以 readiness 结论和 dry-run 结果结束最小化运行。

对于 high_memory_usage，从最小影响的方案开始。基础 /plan 优先考虑影响半径，优先选择重启具体的 pod。然后评估是否需要扩容（scale-up）。只有在保留回滚路径的前提下，才允许扩大动作范围。

tasks 阶段将其拆解为操作：确认工作负载的无状态特性、在不产生实际变更的情况下执行试运行（dry-run）、仅删除目标 pod、观察 RSS、CPU、5xx；如果在指定窗口内无改善，则激活回滚并创建 human_review。

validation 阶段只有在真实指标、安全关卡和 GitOps 固定（这是前沿场景的一部分，见章首）均通过后才闭合自动修复回路。在 validation.md 中需验证四个条件：

• memory 在两个连续窗口内保持在阈值以下；
• 5xx 未上升；
• 延迟（latency）未恶化；
• 回滚已描述且可执行。

成功验证后，六项基础工件进入 GitOps：规范、计划、任务、差异（diff）、决策日志和 25 分制报告。如有需要，补充宪法（Constitution）更新。缺少这些，即便事件在技术上被缓解，也不能算作被妥善关闭。

完整跟踪：25 分制就绪度模型

在第一轮通行中，只需理解两个事实：readiness_pass.json 通过；audit/stateful 用例被阻断。下文完整评分标准在你将该关卡迁移到真实生产流程并需要解释为何阈值要这样设定时才需要。

该模型按 0–5 分为五个类别打分，并给出总加和。分数根据工件而非印象给出。如果某标准无法由文件、日志或模式佐证，则打分更低。下面按类别给出评分标准。

阈值 23/25 是 AgentClinic-production 教学模型中"严格但不至于瘫痪"的折衷：允许在不同类别中最多两项"4"（4+4+5+5+5 = 23），或在其余为"5"时允许一项"4"（24/25）。任一类别出现"3"或更低，总分立即降至 22 或以下，并取消自动通过资格。低于 23：20–22/25 将流水线降级为半人工模式，在每个 implement 步骤后需人工确认。高于 24/25 时，任何小瑕疵都会让自动模式退回半人工，团队会开始忽视模型。请根据风险偏好校准：支付和医疗场景要求 auto ≥ 24/25；内部工具可接受 21–22/25，但仅限半人工或金丝雀（canary）模式，不能作为生产就绪的自动修复。

Spec —— WHY/WHAT/约束的完整性

Implementation —— 幂等性与受控变更

Verification —— Given/When/Then、模式、压测、监控

Process —— "webhook → CLI → diff → 回放"的可追踪性

Security —— 护栏、紧急停止、回滚、升级

评分方式与阻止合并的条件

分数总和给出 0 到 25 的评分。auto 通过的生产就绪阈值为 23/25：低于此值，即便三个类别为满分，流水线也不能获得生产就绪状态。Security 列零分在任何总分下均禁止。零分意味着缺失防护闭环，连半人工模式也会被阻断，直到出现最小化的回滚、护栏和升级机制。

阻断条件与总分无关。以下任一情况都会单独阻断合并：

• 验证失败（Verification ≤ 2）；
• 缺少回滚（Security ≤ 2）；
• 影响半径未确定（Implementation ≤ 2 且无显式字段）。

总分为 20–22 时，流水线仅在无上述阻断条件时，才可进入半人工模式：在每个 implement 步骤后暂停、显式人工确认、强制更新规范、并在返回 auto 回路前重新评估。

投产切换（cutover）前的检查清单

将该关卡迁移到真实流程时使用 —— 每项都关联到评分标准中可能隐藏失分的类别：

• [ ] Spec 包含 WHY/WHAT/约束并绑定到 incident_id；每个任务注明 implements: 指向 REQ 标识符。
• [ ] 试运行在实际变更前记录；影响半径固定在 pod 或 deployment 级别，而非文字描述。
• [ ] JSON Schema 校验 incident_event 和最终 validation_report；Given/When/Then 覆盖正常与异常路径。
• [ ] 回滚条件在执行前已写入并在预发布环境验证；紧急停止对操作员可用，无需进入集群。
• [ ] webhook → CLI → diff → commit → validate 链路可通过 incident_id 复现；在再次失败或扩大影响半径时自动触发人工确认。

high_memory_usage 评分填写示例

完整跟踪：阈值校准

阈值 readiness 的"低 / 默认 / 高"对照表、THRESHOLD 重定义练习以及阈值复审信号见 附录 D 第 D.5 节。在第一轮通行中，只要 readiness_pass.json 通过、audit/stateful 用例被阻断、delete_namespace 不出现在预批准列表中，本章最小化内容即已得到证明。

示例与应用

Qwen Code 的实际输入日志可这样开始：POST /hooks/grafana 报告 memory_percent=93、pod=api-7b4、namespace=appointments-api、window=10m。随后 POST /hooks/pagerduty 确认 severity=critical，并将事件关联到服务 appointments-api。规范化器创建 incident_id=HM-2026-05-17-01 的 incident_event，删除敏感字段，附上源引用，并运行用户自定义命令 /sdd:specify --event incident_event.json --preset high_memory_usage 或等价的 qwen -p 提示 —— 两种方式都属于章首推荐的框架，并通过围绕 Qwen Code 的项目命令实现。

specify.md 中的第一处差异（diff）固定三个块：WHAT（10 分钟内将 RSS 降至 80% 以下）、WHY（避免 OOMKill 和延迟上升）、约束（不动有状态工作负载、不改 HPA、6 分钟内无改善时需可回滚）。在 /plan 阶段，系统比较两种策略：(A) 重启目标 pod 并观察；(B) 重启并临时扩容至 4 副本。验证器跑 Given/When/Then：给定 pod 无状态且 10 分钟内 memory 高于 90%；当仅重启目标 pod；则 memory 应低于 80%，且 5xx 不应超过允许阈值。如果压测规格显示 scale-up 需要修改发布策略或以增加副本数掩盖内存泄漏，则方案 B 退居为带人工确认的备用分支，而非自动动作。

implement 阶段先执行试运行。然后 commit 经 GitOps 通过，并在验证器状态为绿时才在 ArgoCD 中同步。执行者不会在重启后立即关闭 PagerDuty 事件。他等待两个监控窗口，对照 validation.md，检查安全关卡，并在评论中附上 spec、tasks、commit 和验证结果的链接。如果 6 分钟后 memory 未下降或 5xx 上升，则启用回滚路径、创建 human_review，并以 verification 标准的失败为依据重新计算就绪度评分。

小结

生产流水线的就绪度由 25 分制模型固化：五个类别（Spec、Implementation、Verification、Process、Security）每项最高 5 分，对应 SDD 循环的各阶段。权重相等是一条原则：任何类别都不能弥补另一类别的缺口，因此阈值 23 总计最多允许两处局部缺口。生产就绪要求总分不低于 23/25，且 validation 和安全关卡无严重违规。低于阈值会将自动修复降级为半人工模式，直到规范、策略或执行路径得到修正。完全自动化的修复仍是章首提及的前沿场景：只有在积累了回放证据和操作员试运行之后，才可启用。它将每个未来事件转化为系统可验证的改进。

错误即契约的一部分

生产 API 不仅应返回 PASS 或 BLOCK，还应返回错误类型，编排器据此选择恢复策略。将所有失败混为 failed 是危险的：webhook 字段缺失、LLM 超时、Kubernetes API 不可用、Safety 拒绝，都需要不同的处理动作。

本章的最小化分类如下：

对于 high_memory_usage，降级模式意味着：规范化事件、写入 readiness.md、向操作员展示建议的后续步骤，但不自动执行 restart_pod。这是一种诚实的降级：系统在模型或工具不可用时保留证据、且不扩大影响半径。

工件与就绪标准

完整跟踪额外要求：specs/high_memory_usage/specify.md、plan.md、tasks.md 和 validation.md；与 incident_id 关联的 GitOps 差异或 commit；webhook → CLI → diff → commit → validate 的决策日志；以及附有证据的 25 分制就绪度表格。视为就绪的条件：plan 与 tasks 具备影响半径、试运行、回滚条件、人工确认触发器；validation 验证两个指标窗口、5xx、延迟和安全关卡；用户自定义命令已组织为项目级命令，或替换为 qwen -p 提示或项目脚本；就绪度总分不低于 23/25 且回滚、verification、影响半径方面无阻断条件。

练习

1. cd book2/examples/real-api && python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json —— *预期：返回码 0，规范化后的 incident_event 与标准参考逐字段一致。*
2. 分别运行以下四项检查（各项返回各自的返回码，因此不适合用 && 串联）：

   python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json
   python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json
   python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod
   python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace

*预期：readiness_pass → 返回码 0，PASS incident=HM-… score=24/25；readiness_block_audit → 返回码 1，BLOCK … score=22/25，原因包括"score 22/25 低于阈值 23"以及"audit_trace_coverage=0.7 < 1.0 —— 必须完全覆盖"；restart_pod PASS，delete_namespace BLOCK。*

1. 按 25 分制模型评估你的案例，并填写下表。每一类别需给出分数、证据工件，以及分数低于 5 时的扣分原因。计算总分、检查阻断条件，并说明要使流水线达到 23/25 阈值需要修改什么。*预期：表格中每一行的三个字段都已填写；"证据工件"指向具体文件或运行结果，而非笼统表述；总计单元格中包含 N/25 形式的数字和阻断条件列表，或显式的"无阻断条件"。*

思考题

1. 为什么 specify 不应选择具体的修复命令？
2. 哪些条件会使自动修复不可接受？
3. 当 readiness 低于 23/25 时，哪些条件会阻断通过？
4. 关于 high_memory_usage 的 webhook 在非工作时间到达，自动修复已准备就绪可重启 pod。就绪度模型给出 22/25（因审计不完整扣 3 分）。你会立即重启、等天亮、还是呼叫值班人员？