主题: 应用部分 13. 实践考核:构建 production SDD 流水线
难度等级: 中级
预计学习时间: 6-8 小时
前置要求: 成功掌握第二卷第 1-12 章的内容
理解 SDD(Spec-Driven Development,规格驱动开发)概念及 AgentClinic-production 框架
具备使用终端并运行可执行脚本(Python/Shell)的技能
对 AI 代理工作原理、CI/CD 及 post-mortem(事后复盘)有基本了解
学习目标: 独立组装完整的工件包(capstone/)以通过 SDD production 场景
学会通过 genealogy(来源追溯)还原需求,并构建受控的缺陷规格
掌握 constitution.md(宪法)规则、预算控制与反 Goodhart 指标的配置
通过可执行脚本对案例进行验证,并形成文件仲裁记录(judgment.md)
按 30 分制评估包的准备情况,确保独立审阅者具备可复现性
概述: 本模块是第二卷的最终实践考核。其主要目标是证明您能够走通真实的 SDD(Spec-Driven Development,规格驱动开发)production 场景——从遗留(legacy)痕迹一路到最终解决方案,后者必须基于严格事实,而非 AI 代理的盲目自信。您无需学习新理论,而需基于 high_memory_usage 或 autoscale_200pct 事件,组装一条统一的可验证路径(capstone/ 包)。判定通过的标准是:第三方审阅者打开您的包后,在没有额外口头解释的情况下,就能理解验证逻辑、需求来源以及 production 中拦截或放行的原因。
关键概念: SDD 流水线(spec-driven development,规格驱动开发):一种开发与运维方法论,代理的每一项自动化操作均基于可验证的规格与不可变规则,而非启发式方法。
来源追溯(genealogy):任何需求来源皆可追溯的原则。genealogy.md 工件将需求与来源(post-mortem 事后复盘、QWEN.md、口头实践)进行关联,并评估其可信度等级。
就绪网关(readiness gate):在准入 production 前对解决方案进行的最终检查。包含就绪度评分、阻塞条件清单及证据(evidence_ref)。
受控缺陷规格(poisoned spec):刻意植入单一缺陷(如优先级冲突或隐式越界)的规格,用于验证与修复机制(fixed-spec)。
宪法(constitution):系统规则的合集,明确划分为 immutable_principles(不可变法则)与 mutable_rules(具有 TTL 生存期、作用范围与回滚条件的可变规则)。
反 Goodhart 控制:防止指标失真的保护机制——当过度优化目标 KPI 时会带来负面后果。通过引入 guard 指标(如 token_health)加以约束。
练习题: 名称: 包的初始化与路由
问题: 创建 capstone/ 目录和 README.md 文件。针对 high_memory_usage 事件,拟定 5 条关键占位行:Incident-case、主要风险、关键检查、主要阻塞项、下一步修复。
解决方案: 1) 创建文件夹 mkdir -p capstone。2) 创建文件 capstone/README.md。3) 填入占位:Incident-case: high_memory_usage;主要风险:无完整 audit_trace 的自动修复;关键检查:python3 scripts/check_readiness.py;主要阻塞项:无 backup_verified 的有状态负载;下一步修复:为备份补充 evidence_ref。这将为后续工作锚定方向。
难度: 初级
名称: 来源追溯与缺陷还原
问题: 基于一份抽象的 post-mortem(事后复盘报告),创建 genealogy.md(一条需求、两个来源)以及 poisoned-spec.md / fixed-spec.md 一对文件,其中包含一处循环缺陷及其修复。
解决方案: 1) 在 genealogy.md 中记录需求'内存达到 90% 时清理缓存',来源:'Grafana 告警'和'SRE 口头实践',可信度:High。2) 在 poisoned-spec.md 中创建规则:'若内存 >90%,清理缓存;若缓存为空,则向系统申请内存'。3) 在 fixed-spec.md 中记录:'循环修复:缓存为空时触发 GC,而非申请内存'。
难度: 中级
名称: 运行验证并固化结果
问题: 运行 runnable 示例中的 readiness_block_stateful.json 验证脚本。将结果以命令、预期事实、实际结果、阻塞项的格式搬运到 validation.md。
解决方案: 1) 运行 python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json。2) 命令将返回退出码 1(错误/阻塞)。3) 在 validation.md 中记录:命令:check_readiness...;预期:阻塞有状态负载;结果:退出码 1;阻塞项:缺少备份确认。由此证明就绪网关工作正常。
难度: 高级
案例研究: 名称: high_memory_usage 事件:从告警到安全部署
场景: AgentClinic-production 系统收到来自 Grafana 的关键告警,提示内存消耗超出阈值。legacy 痕迹部分丢失:部分恢复规则仅来源于旧版 QWEN.md 文档与口头知识传递。自动修复(清理与重启)看起来很有吸引力。
挑战: 自动化干预可能突破爆炸半径(blast radius)限制或层级预算。团队需证明所提规格安全、不含隐式缺陷,并可在无数据丢失风险的前提下准入 production。
解决方案: 工程师们组装了 capstone/ 包。在 genealogy.md 中还原了需求来源。创建了故意带缺陷的规格并加以修复,将规则固化到 constitution.md。通过 check_readiness.py 进行试运行(dry-run),由于无状态负载缺少 backup_verified 标记,操作被拦截。结论以 DEFERRED 状态写入 judgment.md。
结果: 证据包获得 26/30 分。危险的部署被就绪网关成功拦截。解决方案被推迟,直至为备份补充 evidence_ref,由此避免了 production 中的停机。
经验教训: 缺少证据(evidence_ref)的就绪度评分毫无意义,不能作为准入依据。
测试阶段发现的一个阻塞项,胜过形式上的 APPROVE 而未实际运行验证。
不应在最终送审的痕迹中包含 out/ 日志,审阅者只需 validation.md 的摘要。
相关概念: Readiness Gate(就绪网关)
Genealogy(来源追溯)
Poisoned Spec(缺陷规格)
Validation(验证)
名称: autoscale_200pct 扩容争议的解决
场景: 高负载峰值期间,AI 代理(实现者)基于 QWEN.md 模板,建议将资源扩容 200%。安全代理(Safety)以超预算风险与潜在 Goodhart 效应为由行使否决权——即系统将因指标而扩容,而非为真实价值。
挑战: 出现角色冲突。需要通过对决(duel)进行文件仲裁,并依据系统宪法与指标(而非代理的权威)做出决定。
解决方案: 启动法庭机制:run_duel.py 用于固化双方论点,check_invariants.py 用于校验预算。在 goodhart-note.md 中记录'响应速度'这一 KPI 失真,并新增 guard 指标'单次请求成本'。judgment.md 中作出 DENY 裁决,自动在 precedents.md 中生成先例(包含 case_id 与 applies_to 字段)。
结果: 冲突以形式化方式得到解决。生成的先例可在未来自动驳回类似请求,无需消耗 token 进行对决。budget-note.md 清晰展示了低成本层级的限制。
经验教训: 安全否决权无法通过简单多数票绕过。
任何反复出现的争议都应固化为记录的先例(precedent)。
反 Goodhart 控制(KPI 与 guard 指标的联动)对自动扩容至关重要。
相关概念: Арбитраж и роли(仲裁与角色)
Judgment(裁决)
Anti-Goodhart(反 Goodhart)
Precedents(先例)
学习建议: 从结果倒推:先在 README.md 中填写 5 行占位以设定边界,再创建其余工件。
不要混用事件。严格选择一个案例(如 high_memory_usage),不要混入其他场景的元素。
采用'黄金路径':打开 examples/templates/capstone-dossier.md 作为范例,了解您的包应有多简洁。勿过度堆砌文档。
模拟他人审查:capstone/ 组装完成后搁置一小时,随后仅依据您的文件(不查看与 AI 的对话历史)尝试回答 5 个验证性问题。
若在某工件上卡壳,请返回相应章节(1-12),找到'它如何纳入 capstone/'小节。
附加资源: Examples/templates/capstone-dossier.md:示范性范例(黄金路径),展示考核中细节与简洁之间的理想平衡。
第 00 部分:production-lab:AgentClinic-production 的基础实验框架。若感觉上下文缺失,务必阅读。
第 11 部分:real-api-deployment:运行 high_memory_usage 主案例可执行脚本的说明。
第 08 部分:multiagent-tribunal:autoscale_200pct 案例的文件仲裁、对决与先例管理的理论与实践。
摘要: 实践考核'构建 production SDD 流水线'旨在检验您在 AI 代理流程中落实证据文化的能力。您已学会构建一份紧凑、可复现的工件包(capstone/),将事件、缺陷、宪法与验证串联为统一的可验证路径。核心结论:production 就绪的证明,不在于完美的指标或堆叠的文档,而在于透明的来源追溯、有效的拦截机制,以及对'为何这是安全的?'这一问题的清晰回答。