第 4 章 Chapter Outline：构建可靠 Agent 的工程原则

本文件是章节写作蓝图。六条可靠性原则是本书的工程组织方式，不是 NIST、OpenAI、Google SRE 或 Lilian Weng 的统一产品标准。涉及动态产品 Guardrails 或权限能力时，正文写作当天必须重新核验 REF-008。

章节契约

读者完成后的能力： 能为一个会读取或修改外部状态的 Agent 任务定义可观察目标、前置检查、受控执行、验证证据、停止条件、恢复路径和人工升级条件；能解释为什么“模型给出合理答案”不足以构成工程上的完成。

前置知识： 已理解第 1 章的 Harness 闭环、第 2 章的模型—Agent—Harness—运行环境边界，以及第 3 章的项目状态与可追溯工件。

章节边界： 本章给出跨产品的可靠性基线，不实现具体状态机、工具协议、Sandbox、批准模式、评价基准、成本控制或 A/B 测试；这些分别交给第 10、11、12、14、17、39、40、41 与 42 章。

小节蓝图

1. “看似完成”为什么不是工程完成

• 读者问题： Agent 说“配置已更新”时，为什么仍不能直接接受结果？
• 叙述任务： 用“自动将服务配置从预览改为正式写入”的教学场景区分语言输出、工具返回、目标状态、验证证据与业务接受。说明可靠性不是一个模型分数，而是结果是否在已知边界内可观察、可复核、可恢复。
• 证据边界： 该定义是本书工程模型；不声称任何来源给出了同一条定义，也不提供真实生产成功率。
• 计划工件： “声明成功 / 已有直接证据 / 仍未知”三列表。
• 验证： 读者能指出一个工具返回成功但写入了错误目标、验证遗漏或副作用不可逆的反例。
• 过渡： 要把完成做成可检查结论，先要把目标、状态和证据连成闭环。

2. 原则一：以可观察目标和完成定义开始

• 读者问题： 怎样把“修复配置”“处理订单”这样的意图改写成可验收任务？
• 叙述任务： 定义最小任务契约：目标对象、允许动作、成功条件、禁止副作用、验证命令、停止条件和责任人。将本书的 Definition of Done 作为章节内示例，而不是通用行业标准。
• 证据边界： NIST AI RMF 只支持风险管理与可信开发使用的背景；任务契约字段和 DoD 是本书扩展。
• 计划工件： 任务契约模板与“目标—证据—未覆盖范围”表。
• 验证： 同一任务在缺少成功条件或验证命令时，读者能够判断它不可领取。
• 过渡： 目标定义后，执行过程还必须暴露当前状态和失败原因。

3. 原则二：以独立验证闭环结束

• 读者问题： 为什么模型的完成说明、工具的成功返回和真正满足目标不能混为同一结论？
• 叙述任务： 将候选、执行请求、回读观察、验证判定和业务接受拆成可追踪的信号；说明验证器可以是回读、测试、格式检查、业务规则或人工审查，但必须说明覆盖范围。
• 证据边界： 验证闭环是本书工程模型；不宣称任一来源或产品提供相同验证器，也不将已检查条件外推为整体安全保证。
• 计划工件： “信号—直接说明—仍未知—下一步”表。
• 验证： 读者能识别“工具调用成功但目标错误”与“回读匹配但验收不完整”的不同缺口。
• 过渡： 验证结论需要可恢复的状态和失败记录，才不会在下一步丢失其范围。

4. 原则三：让状态、失败和恢复路径可见

• 读者问题： 失败后怎样避免重试掩盖错误、重复写入或丢失上下文？
• 叙述任务： 建立“预检 → 执行 → 验证 → 成功记录 / 失败记录 → 恢复或升级”的可观察状态路径；明确失败不是空字符串或静默重试，而是带有阶段、证据和下一步的结果。
• 证据边界： 这是本书对第 2、3 章责任和仓库状态的综合；不实现完整状态机或恢复算法。
• 计划图示： chapter-04-reliability-loop.mmd，展示目标、预检、受控执行、验证、记录、恢复/人工升级；禁止画出“模型输出 → 完成”的直连箭头。
• 验证： 图中每个终点均有明确状态、保存的证据和下一动作；读者能解释验证失败与工具失败的不同恢复路径。
• 过渡： 即使状态可见，副作用一旦过大仍可能无法恢复，因此需要限制动作能力。

5. 原则四：以最小权限和可逆性控制副作用

• 读者问题： 为什么“已经写好禁止危险操作的 Prompt”不足以保护系统？
• 叙述任务： 按只读 / 可逆写入 / 不可逆或高影响写入组织动作风险；为每类给出允许条件、预检、备份或 dry-run、验证、回滚和人工确认。明确权限由运行环境、工具协议和审批实施，而不由 Markdown 文字强制。
• 证据边界： REF-008 直接支持按工具的读写性、可逆性、账户权限与财务影响评估风险；具体风险表、dry-run 与备份流程是本书教学设计。
• 计划工件： 动作风险矩阵，标明“允许自动执行 / 需额外验证 / 必须人工升级”。
• 验证： 对配置写入、删除和发送外部消息三类任务，读者能选择不同权限与停止门槛。
• 过渡： 最小权限降低爆炸半径，但不确定或高风险结果仍需要明确交给人。

6. 原则五：把人工升级设计为正常路径

• 读者问题： Human-in-the-loop 是“失败后的求助”，还是任务设计的一部分？
• 叙述任务： 说明升级条件必须可观察：连续失败超过阈值、证据冲突、目标不明确、动作不可逆或影响范围超过授权。升级记录包含候选动作、已执行步骤、证据、风险、待决问题和可选决策。
• 证据边界： REF-008 支持高风险动作和失败阈值可触发人工介入；阈值数值、审批表单与组织责任分配均留为本书案例假设。
• 计划工件： “继续 / 回滚 / 请求审批”决策表与交接包模板。
• 验证： 读者能区分“模型不确定”与“系统证据不足”，并知道何时停止自动化而不是继续重试。
• 过渡： 人工升级并不意味着每次变更都全量暴露；可靠系统还需让变化逐步扩大。

7. 原则六：先在小范围验证，再扩大影响

• 读者问题： 为什么一个通过单元测试的 Agent 改动仍应先在受限范围运行？
• 叙述任务： 借用 Canary 的工程思想解释：选择受限对象或 dry-run，定义对照与评价信号，达到阈值后继续，否则暂停、回滚或升级。把它映射为 Agent 的配置变更范围，而不声称 Agent 必须采用流量分割。
• 证据边界： REF-009 直接支持子集投放、评价过程与发布流程集成；Agent 映射、教学阈值和示例配置都是本书扩展。
• 计划工件： “范围—信号—停止条件—回滚动作”渐进变更表。
• 验证： 读者能说明为什么全量执行前需要直接验证，并识别无对照、无回滚或无阈值的风险。
• 过渡： 这些原则需要汇总为一次可审计的最小闭环。

8. 完整工程案例：受控修改一项服务配置

• 读者问题： 六条原则在一项具体、可检查的 Agent 任务中怎样协同？
• 叙述任务： 设计原创案例：Agent 被请求调整一个教学配置字段。先展示任务契约和只读预览，再生成备份、在受限目标上写入、读取回验、记录结果；若字段不匹配、目标范围不明或写入被拒绝，则停止并交给人。
• 证据边界： 案例为纯内存或临时目录教学设计，不访问真实服务、不使用真实凭证、不声称任何云平台工具行为。
• 计划示例： 最小示例只模拟计划、预检、写入、验证与升级结果；将真实文件 I/O、权限执行、并发和网络调用标为后续章节范围。
• 验证： 成功、验证失败、权限拒绝与高风险升级均返回结构化状态和证据；不允许仅以模型文字宣告成功。
• 过渡： 第 5 章将进一步讨论 Instructions 与 Prompt 如何承载稳定规则和任务输入；第 6 至 14 章会分别实现上下文、记忆、规划、状态、工具、环境与人工协作组件。

章节工件状态

1. 已完成：Research Brief 与候选参考资料；来源的风险管理、Guardrails 和 Canary 陈述均限定在直接支持范围。
2. 已完成：Chapter Outline；已规定正文、事实核验、图示和示例的输入输出与非范围。
3. 已完成：Fact Check、Mermaid 图源与 Diagram Review；SVG/PNG 已实际导出并视觉检查，图示仍只表达本书工程模型，不得将其表述为产品架构或真实权限控制。
4. 已完成：First Draft；正文已通过项目 Markdown 校验，且来源事实、本书工程模型和教学案例保持分层。
5. 已完成：Technical Review；已核对来源范围、章节依赖、正文、图源与示例的阶段语义，记录位于 .memory/reviews/2026-07-15-chapter-04-technical-review.md。
6. 已完成：Example Implementation；纯内存 evaluateConfigChange、5 项 Node 内置测试与演示入口已实际运行，记录位于 .memory/reviews/2026-07-15-chapter-04-example-integration.md。
7. 已完成：Language Editing；编辑只涉及阶段语义、具体主语、因果和图文术语，未改变来源范围、示例或图示接口，记录位于 .memory/reviews/2026-07-15-chapter-04-language-edit.md。
8. 已完成：Validation 与 Final Review；跨工件复核修正示例说明和出版目录中的“计划”阶段漂移，重新运行示例、演示、Mermaid 导出与项目校验后确认完成。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] NIST、OpenAI、Google SRE 和 Weng 的限定陈述与本书工程原则、教学案例明确分开。
• [x] 可靠性未被写成准确率、产品保证或权限控制的同义词。
• [x] 计划图示和示例均要求可观察的状态、证据、停止与升级路径。
• [x] 明确了与第 5、6、10、11、12、14、17、39、40、41 和 42 章的边界。