应用卷：Qwen Code CLI 的生产级 SDD
本目录为教材的第二卷——应用卷。第一卷 book/ 教授 AgentClinic 上的基础 SDD 循环：章程、功能规格、计划、可验证事实、实现、审查与重新规划。第二卷将同一循环迁移至生产级场景：遗留痕迹、验证器、多智能体检阅、规格 CI、指标、模型预算与受限自动修复。
版本：v1.0 — 2026-05-20 验证。变更历史请参阅 CHANGELOG.md。
本材料不适用于首次接触 SDD。阅读前需理解 requirements.md、plan.md、validation.md、QWEN.md、功能边界、否定性要求与事实验证。若这些术语尚未成为工作用语，请先完成第一卷。
第二卷的核心规则：第一轮遍历应仅留下一个微小的可验证痕迹，而非一次性了解所有生产术语。每章首先完成教学最低要求：一个工件、一条命令或一个 capstone/ 的阻塞项。主要考核案例为 high_memory_usage；将本地案例迁移至主要案例的规则详见第 0 部分。
快速开始
- 打开第 0 部分，选取主要案例
high_memory_usage。 - 创建空的
capstone/。 - 在第 1–3 章中填写
genealogy.md、poisoned/fixed 配对和constitution.md。 - 在第 4–11 章中仅执行「最小教学场景」和 [
examples/](examples/) 中的可运行命令；若章节使用其他案例（autoscale_200pct、node_not_ready、appointment_latency/appointment_latency_spike、cdn_error_budget_burn），记录一行迁移说明——该案例的哪个原则保护主要案例high_memory_usage。 - 在第 12 章中按反模式检查包。
- 在第 13 章中汇总最终
capstone/README.md，并验证其无需聊天记录即可理解。
示例的最小检查，包括预期阻塞项：
bash book2/examples/smoke_all.sh如何阅读各章
第 1–12 章应以统一节奏阅读。每章开头先找到简短的「阅读前」块：它说明本章从第一卷获取什么、启动哪个本地案例、迁移至 capstone/ 的内容，以及属于完整轨道的部分。
随后保持五个问题：
- 第一卷的依托。 AgentClinic 的哪个概念被扩展。
- 最小教学场景。 手动做什么或在本地运行什么。
- 控制事实。 证明本章已完成的内容。
- **如何进入
capstone/。** 本章结束后保留的哪行或哪个文件。 - 完整轨道。 仅在真实生产仓库中实施时才需要的内容。
若章节显得密集，请勿线性阅读。先执行最小场景，再返回「关键思想」，最后查看校准项、[project script] 和 [conceptual interface]。若术语无助于填写当前 capstone/ 文件，可跳过至第二轮遍历。
第二卷的编辑规则：第一轮遍历时，每章新增的工作词汇中，强制术语不超过一个。若遇到另外五个名称，但当前 capstone/ 文件不需要它们，将其视为参考内容，在最小场景完成后再处理。
章节的实践测试：最小场景后，读者应能在 capstone/ 的某个文件中写入一行。若为此需要同时理解两个新机制，其中一个属于第二轮遍历或完整轨道。
状态标记与命令
章节中使用与第一卷相同的置信度级别：
- 标准 — 工具固定行为或公认实践。
- 建议 — 多数情况有效但允许调整的实践。
- 前沿 — 已采用但形式取决于团队、模型和基础设施的方法。
命令块分为三类：
- [runnable] — 在 [
book2/examples/](examples/) 中本地运行，无外部依赖。 - [project script] — 需在自身项目中实现的脚本接口。
- [conceptual interface] — 未来编排器、策略门控、MCP 层或 CI 集成的形式。
教学通过仅需 [runnable] 块和手工工件。其余属于完整轨道。
贯通路线
| 章节 | 第一轮遍历做什么 | 推迟什么 |
|---|---|---|
| 0 | 理解 AgentClinic-production，选择 high_memory_usage，创建空的 capstone/ | 适配自身生产域 |
| 1–3 | 恢复一项需求，展示一个缺陷，整理 constitution.md | 自动证明归一化器和规则公投 |
| 4–5 | 获取反例和压力突变器的 smoke 结果 | 常驻对决和 CI 中的突变工厂 |
| 6–7 | 接受/拒绝影子候选，启动 Spec CI | 完整记分册、范围门控和 PR 报告 |
| 8–9 | 汇总 judgment.md，演练廉价层级拒绝 | 独立预算服务和仲裁编排器 |
| 10–11 | 检查 high_memory_usage 的守卫指标、就绪度和 dry-run | GitOps 部署和无需手动确认的自动修复 |
| 12 | 以 blocker / owner / next_check 记录三项风险 | 将每个反模式转为 CI 策略 |
| 13 | 汇总最终证据包 | 全套流程的生产就绪实施 |
第一轮遍历的必需工件
仅关注这些文件。其余术语可在主要包已可读作单一案例后再补充。
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— 第 12 章遍历后的三项blocker / owner / next_check风险。capstone/README.md— 单一案例的最终包汇总。
第 6 章在 capstone/README.md 中添加简短的 Shadow notes 块（若在教学仓库中使用 QWEN.md，则添加至其中）。这不属于主要列表的独立文件。
其余名称（scorebook、metric_network、decision_hash、precedents.md）属于完整轨道，除非直接帮助填写上述某个文件。
每章应给出上述文件之一的最低最终片段。若章节结束后仅有一般理解，但没有 capstone/ 的行、命令或阻塞项，则该章尚未在教学级别关闭。
贯通映射「哪章写哪个 capstone/ 文件」：
capstone/ 文件 | 开启该文件的章节 | 补充该文件的章节 |
|---|---|---|
genealogy.md | 1 | 13（最终汇总） |
poisoned-spec.md / fixed-spec.md | 2 | 13 |
constitution.md | 3 | 12（可变规则反模式）、13 |
validation.md — 快乐/否定路径 + 反例 | 4 | 5（突变体）、7（Spec CI）、13 |
validation.md — 突变免疫 | 5 | 13 |
capstone/README.md 中的 Shadow notes 块 | 6 | 13 |
validation.md — Spec CI 行 | 7 | 13 |
judgment.md | 8 | 12（仲裁反模式）、13 |
budget-note.md | 9 | 13 |
goodhart-note.md | 10 | 13 |
readiness.md | 11 | 13 |
antipattern-audit.md | 12 | 13 |
capstone/README.md — 汇总 | 13 | — |
自主考核前，请打开 [examples/templates/capstone-dossier.md](examples/templates/capstone-dossier.md)。这是 high_memory_usage 最小完整包的填写范例：展示良好第一轮遍历可以多么简短。
章节地图
| 章节 | 第一卷的依托 | 最小输出 |
|---|---|---|
| 0. AgentClinic-production 实验室 | 项目最终结构和实践考核 | 选定的案例、空的 capstone/、smoke 命令 |
| 1. 从遗留中恢复规格 | 支持现有项目 | genealogy.md 中的一条记录 |
| 2. 规格缺陷诊断 | 否定性要求和事实 | poisoned/fixed 配对 |
| 3. 项目章程 | mission.md、tech-stack.md、roadmap.md、QWEN.md | 两条不可变规则和一条可变规则 |
| 4. LLM 对决 | 独立验证会话 | 一个反例或 next_guard |
| 5. 规格突变测试 | 否定路径和反例 | stress-mutator 结果 |
| 6. 影子规格筛选 | 项目记忆和少样本 | 一个接受和一个拒绝的候选 |
| 7. 规格 CI | requirements.md → plan.md → validation.md 的关联 | 含 PASS/BLOCK 的 Spec CI 行 | | 8. 文件仲裁 | 独立审查 | 含 evidence_ref 的 judgment.md | | 9. 层级预算 | 按任务风险选择模型 | 预算风险和 token_health | | 10. 古德哈特指标防护 | 以事实替代说服性散文 | KPI 和守卫指标 | | 11. 生产 API | 功能边界、回滚、手动检查 | 就绪度和 dry-run | | 12. 生产 SDD 反模式 | SDD 反模式 | 三项诊断风险 | | 13. 实践考核 | 完整 SDD 循环 | 最终 capstone/ 包 |
AgentClinic 的完整域地图位于附录 A。Qwen Code 的命令兼容性详见附录 B。检查清单汇总于附录 C。
为何各章案例不同
主要考核案例为 high_memory_usage。但第 1–10 章采用不同事件，因为并非每个事件都能同等展示所研究机制：某些领域更易展示优先级冲突，某些需要 high_memory_usage 没有的突变历史。全书单一案例将使每个模板沦为形式。
迁移规则简单：章节结束后记录一行——该案例的哪个原则保护您的 high_memory_usage。
| 章节 | 本章案例 | 迁移至 high_memory_usage 的内容 |
|---|---|---|
| 1 | node_not_ready | 从事后分析恢复需求的技术及来源 |
| 2 | appointment_latency | 一个可控的优先级冲突和反向推演 |
| 3 | node_not_ready | 不可变原则及含 ttl 和 rollback_condition 的一条可变规则 |
| 4 | autoscale_200pct | 违反 Then 的最小反例和 next_guard |
| 5 | payment_latency_spike | 突变器 smoke 结果和验证器免疫向量 |
| 6 | shadow.p0.voice_handoff | 一个接受和一个拒绝的影子候选 |
| 7 | incident payload | 覆盖度 PASS 和模式 BLOCK 的 Spec CI 行 |
| 8 | autoscale_200pct | 含 verdict、evidence_ref 和 Safety 角色的 judgment.md | | 9 | autoscale_200pct | 预算风险、token_health 和廉价层级拒绝场景 | | 10 | cdn_error_budget_burn | 修复 KPI 的配对反古德哈特指标 | | 11 | high_memory_usage | 主要案例的就绪度 23/25 和 dry-run | | 12 | 第 8–11 章任意包 | 三行 blocker / owner / next_check | | 13 | high_memory_usage | 所有工件汇总至统一 capstone/ |
若本章案例无法以一行迁移——则本章已读但未关闭。
各章节
- AgentClinic-production 实验室
- 从遗留中恢复规格
- 规格缺陷诊断
- 项目章程：首次规则公投
- LLM 对决：验证器与实现者在形式声明中的对抗
- 规格突变测试
- 影子规格筛选
- 规格 CI：规格作为可执行工件
- 争议变更的文件仲裁：角色、裁决与先例
- 模型路由与令牌预算
- 古德哈特指标防护：守卫指标与应急模式
- 真实 API 集成：从规格到部署
- 生产 SDD 反模式：应用循环诊断地图
- 实践考核：构建生产 SDD 流水线
配套文档
- 应用卷术语表 — 第二卷术语定义。
- 应用卷变更日志 — 文本修订历史。
- 教师备注 — 工作坊格式和常见错误。
- 与第一卷的桥梁 — 先决条件和 AgentClinic 域地图。
- Qwen Code 兼容性 — 内置命令、自定义命令和项目脚本。
- 应用 SDD 检查清单 — 规格 CI、仲裁、指标和生产就绪的检查。
何为成功
应用卷结束时应得到的是可复现的流水线，而非一套精美规则：
- 争议需求具有来源和不确定度级别；
- 危险自动化受章程、护栏和回滚条件限制；
validation.md验证快乐路径、否定路径、反例、漂移和古德哈特陷阱；- CI 或其可运行等效物阻塞未覆盖需求和弱有效载荷契约；
- 智能体决策留下可供他人或他模型审查的证据；
- 最终
capstone/展示从遗留痕迹到生产就绪方案的单一路径，含明确阻塞项和修复计划。