第 10 章 Chapter Outline：Workflow 与状态管理

本文件是正文写作蓝图。AWS Step Functions、LangGraph 和 Temporal 的陈述只在各自产品、框架或实现语境中使用。工作流契约（Workflow Contract）、状态记录（State Record）、状态名称、迁移表、交接包、停止规则和章节生产案例均为本书工程模型；它们不是任何产品的 schema、API、默认行为、持久化保证或权限机制。正文写作、示例实现与 Fact Check 当天必须重新核验 REF-031 至 REF-035。

章节契约

读者完成后的能力： 能区分工作流定义、一次执行、一次尝试、状态迁移、状态记录（State Record）、检查点（Checkpoint）和验证结论；能为一个已获准的任务定义合法状态、迁移输入输出、可观察证据、重入条件、停止条件与交接信息；能在中断后根据状态与证据判断重试、恢复、阻塞或人工升级，而不把上次模型输出、状态文本或工具返回内容直接当作完成事实。

前置知识： 已完成第 7 章，理解工作记忆、长期记忆和 Memory Record 不能替代当前执行状态；已完成第 9 章，理解 Plan Brief、任务卡、依赖、并行候选与停止条件只定义“做什么”，不执行或恢复任务。读者应能阅读 Markdown 表格、简单状态图、键值对象和测试断言。

章节边界： 本章定义可审查的状态与恢复模型，不实现真实工作流引擎、队列、数据库、事件溯源、锁、租约、事务、调度器或恰好一次（exactly-once）语义。第 11 章负责 Tool 请求、返回和错误协议；第 12 章负责环境、Sandbox、凭证和实际权限；第 14 章负责人工批准互动；第 17 章负责结果验证；第 18 章深入重试（Retry）与恢复（Recovery）；第 19 章讨论长任务压缩；第 26 章讨论多 Agent 隔离；第 27 章讨论 Git、Worktree 与代码审查。第 10 章不把上述章节的机制预写为已存在的运行时能力。

小节蓝图

1. 任务图之后：为什么“已计划”仍不等于“可以继续”

• 读者问题： 第 9 章已经给出了 Plan Brief、任务卡和依赖图，为什么一个任务在中断后仍可能无人知道该从哪里继续？
• 叙述任务： 以原创场景开场：书籍章节的 Research 已完成，Outline 正在进行，执行者中断；仓库只留下“继续第 10 章”的自然语言提示。说明它没有回答本次执行使用的输入、已完成迁移、当前阻塞、可复用证据、下一项合法动作和先前副作用是否发生。定义本章的最小区分：工作流契约（Workflow Contract）描述可允许的路径；执行（run）是一次具体实例；尝试（attempt）是某个动作的一次发生；状态迁移是有证据的控制流变化；验证结论属于第 17 章，不能从状态名称反推。
• 证据边界： REF-031 只能用作 AWS Step Functions 以状态机组织其工作流、执行和状态输入输出的产品示例。定义、术语关系、判断规则和章节场景均为本书模型，不声称任何系统都使用相同对象或字段。
• 计划工件： “任务计划 / 工作流定义 / 执行 / 尝试 / 观察 / 验证结论”对照表，分别回答它们记录什么、可推出什么、不能推出什么，并列出关联标识应留在何处。
• 验证： 给定“计划已批准”“进入执行态”“收到工具文本”和“验证接受”四句话，读者能指出每句话仍缺少或需要何种证据，尤其不把前 3 项写成“任务完成”。
• 过渡： 先拆清对象后，才可以定义哪个状态能进入哪个状态，以及每次迁移由谁负责和依据什么。

2. 工作流契约（Workflow Contract）：把合法状态、迁移与终态写成可审查接口

• 读者问题： 如何避免把工作流写成一张只有“开始—处理中—完成”的装饰性流程图？
• 叙述任务： 定义本书工作流契约的最小字段：目标和范围、版本、入口条件、合法状态、开始状态、终态、允许迁移、每次迁移的输入输出、负责方、证据、失败表示、可重试条件、停止和升级条件。用章节生产的教学状态展示 ready、in_progress、blocked、requires_approval、ready_for_validation、validated、stopped 等名字只是本书示例，状态名称不等于通用标准。强调“允许迁移”不等于“外部副作用获准”，也不等于“结果已验证”。
• 证据边界： REF-031 可说明 AWS 产品中状态、起点、终态与迁移是其状态机概念；本书 Contract 字段、状态集合、迁移表和章节状态名不归因给 AWS 或 Amazon States Language。REF-032 只在介绍产品级 Retry/Catch 时使用，不决定本书迁移顺序。
• 计划工件： 工作流契约模板和状态转移表：列出起始状态、触发、必要输入、可观察输出、允许后继、失败或阻塞表示、不能得出的外部结论。表中专门包含“未知效果”和“状态记录冲突”两条停止分支。
• 验证： 读者能检查转移表是否遗漏入口、终态、异常分支或证据字段；能拒绝 validated → in_progress 这类无理由重入，或要求新建执行/尝试而不是覆盖既有记录。
• 过渡： Contract 给出合法路径，但恢复要读取的不是抽象路径，而是某一次执行留下的状态和证据。

3. 状态记录（State Record）与检查点（Checkpoint）：记录当前执行，不把记忆或文本摘要当恢复依据

• 读者问题： 为什么“上次对话已经总结过”“长期记忆里有一条决策”不足以安全恢复当前任务？
• 叙述任务： 区分三类信息：第 7 章的工作记忆与长期记忆服务于信息可见性和跨任务经验；状态记录描述某一次工作流执行的当前可检查状态；检查点是用于恢复判断的一个保存快照。定义状态记录计划字段：工作流定义版本、执行/尝试标识、当前状态、最近迁移、关联输入、观察证据、未解决风险、未知项、下一个允许动作和更新时间。强调检查点只表示“有一份可定位记录”，不自动证明记录新鲜、完整、已提交或正确。
• 证据边界： REF-033 只支持 LangGraph 将图状态保存为按 thread 组织的 checkpoint，以及其框架的恢复、历史、人工中断和 replay 范围。State Record 字段、与 Memory Record 的边界、检查点新鲜度规则和教学案例均为本书模型；不套用 thread、checkpoint_id、存储后端或加密行为。
• 计划工件： “工作记忆 / 长期记忆 / 状态记录 / 检查点 / 验证证据”职责矩阵，以及一份纯教学状态记录样例，所有 run_id、时间、路径、用户和外部结果均使用抽象占位值。
• 验证： 读者能在下列情况下选择正确动作：只有长期记忆时请求补充状态；只有状态名称时请求关联证据；发现记录版本不一致时阻塞；已有匹配 checkpoint 但外部效果不明时进入恢复判断而非自动重试。
• 过渡： 有记录不代表可以重复执行；下一节解释为何重入会让副作用与已完成工作成为风险中心。

4. 重入与幂等性：恢复会重复什么，重复后如何不制造额外效果

• 读者问题： 为什么“从检查点恢复”仍可能重复 API 请求、文件写入、通知或账务动作？
• 叙述任务： 解释重入（re-entry）是再次处理某个状态或动作，不自动等于失败修复；幂等性（Idempotency）在本书中只是目标：对同一已识别效果请求的重复处理不产生额外不可解释效果。用两类教学情境对比：只读分析可以在证据范围内重做；写入效果必须先确认效果标识（effect identity）、上次效果是否可观测、去重或人工处理条件。明确本章不提供真实去重键、数据库事务、锁、服务端 API 或恰好一次（exactly-once）声明。
• 证据边界： REF-034 只支持 LangGraph Functional API 关于持久化任务结果、恢复时可能重执行和副作用幂等性建议的框架语境；REF-035 只支持 Temporal 实现中 Workflow/Activity 的限定设计边界。对 effect identity、未知效果、重入判定和升级规则的解释均为本书模型。
• 计划工件： “可重入性审查卡”：动作意图、效果标识、读/写分类、上次效果证据、重复风险、可恢复条件、不能恢复条件和升级对象。另列“重复调用不等于幂等”的反例表。
• 验证： 读者能将“未知是否已发送通知”“上次文件写入无回读”“只读资料重新筛选”分别判定为阻塞/需要观察、阻塞/需要验证、或可按规则重做；不把教学分类写成真实 API 行为。
• 过渡： 重入审查解决“能否再做一次”；下一节决定遇到错误时应重试、恢复、停止还是升级。

5. 重试（Retry）、恢复（Recovery）、停止（Stop）与升级（Upgrade）：错误路径是设计的一部分

• 读者问题： 为什么“失败后重试三次”既可能不够，也可能带来更严重的重复效果？
• 叙述任务： 建立本书的错误路径模型：先记录可关联观察，再根据错误类别、已知效果、重试预算、状态完整性和授权范围，选择 retry、recovery、blocked、requires_approval 或 stopped。解释 retry 是再次尝试同一动作的候选；recovery 是在保留状态与证据后重新判断下一动作；stop 是不继续制造新效果；upgrade 是请求人类或环境决策。强调这些状态不描述任何产品的默认顺序，也不代替第 18 章的容错策略。
• 证据边界： REF-032 只能作为 AWS Step Functions 中匹配 Retry 后再进入匹配 Catch 分支的产品实例，不能外推为本书或其他系统的流程。REF-033、REF-034、REF-035 可作为各自框架或实现里的恢复、重放与幂等性背景，但不支持跨产品错误分类、重试次数、退避值、超时或成功保证。
• 计划工件： 错误与恢复判定表，包含“观察缺失”“可确认的暂时性失败”“状态记录冲突”“外部效果未知”“批准失效”“验收失败”等输入；每行给出允许动作、必须保留的证据、不可作出的结论和应移交章节。
• 验证： 读者能指出“Retry 成功”最多说明一次尝试返回了某种可观察结果，仍需验证；能为外部效果未知的写入请求选择停止或升级，而不是按固定次数重试。
• 过渡： 即使没有错误，长任务仍会因人员切换或会话丢失而暂停；恢复必须使下一位执行者知道什么是事实、什么仍未知。

6. 交接与恢复演练：让下一位执行者能复原边界，而不是复述聊天摘要

• 读者问题： 人类或 Agent 接力时，最少要交接什么，才能避免依据过期摘要重复工作或覆盖未知状态？
• 叙述任务： 定义本书的交接包（Handoff Packet）：工作流版本与执行/尝试标识、当前状态、最近迁移和证据、未解决依赖与风险、已知未知项、可用检查点、下一步候选、停止或批准条件、未验证范围。用本仓库的章节生产流程作为教学案例：Research 完成后可领取 Outline，但新执行者仍需核对状态文件、研究资料和模板。解释交接不授予权限、不完成审批、不替代 Tool 结果，也不能压缩掉原始证据。
• 证据边界： Handoff Packet 字段、仓库案例、恢复演练和状态冲突规则均为本书模型。REF-033 可用于框架级 checkpoint/恢复背景，但不证明任意 handoff 都可恢复、任意状态都可共享或产品会自动合并冲突。
• 计划工件： 交接包模板、恢复前检查表和“摘要与当前状态冲突”诊断表。字段统一使用现有项目术语，避免引入未定义的运行时 API。
• 验证： 设计两份互相冲突的交接信息：旧摘要说“Draft 已完成”，当前 State Record 说“Outline 未开始”；读者应以最近可追溯的当前状态为基线，阻止直接续写 Draft，并记录冲突而不是凭摘要择一。
• 过渡： 一份能交接的状态记录还要能被审查；最后的案例把 Contract、Record、恢复和停止条件串成一个可读的工程闭环。

7. 完整工程案例：把书籍章节生产过程设计成可恢复工作流

• 读者问题： 如何为一个非代码长任务设计可观察状态，而不把写作进度表误称为生产工作流引擎？
• 叙述任务： 构造原创教学案例：为一个虚构章节建立从 Research、Outline、Draft、Review、Validate 到 Completion 的工作流契约。每一步都有入口、输入、输出、证据、阻塞与下一步；案例演练“Research 完成后交接”“Outline 状态缺少引用登记”“Draft 的示例请求需要独立批准”“验证失败后回到局部修订”四种路径。案例必须区分章节状态、实际文件变更、外部命令和发布结果，不能把 Markdown 状态字段当作真实工作流执行证明。
• 证据边界： 状态表、案例字段、迁移、恢复演练和预期输出都是本书教学设计。它不调度 Agent、不写文件、不调用模型、网络、Git、CI、Tool、环境变量、凭证或发布系统，也不宣称本仓库当前由某个工作流引擎驱动。
• 计划图示： chapter-10-workflow-state-machine.mmd 将表达本书章节生产的状态、允许迁移、检查点供恢复判断、阻塞/升级回流与验证终态；图中不得把状态箭头画成实际文件写入、权限授予、工具调用或内容正确性。
• 计划示例： 10-workflow-and-state-management.example-plan.md 将定义一个纯内存函数，例如 assessWorkflowTransition：输入工作流契约、状态记录、观察与批准快照；输出只表示允许迁移、需要补证、阻塞或需要批准。示例不得持久化、调度、重放、调用模型、网络、文件、Git、Tool 或权限系统。
• 验证： 计划测试至少覆盖：合法转移、无效终态重入、缺 checkpoint、未知写入效果、过期批准、冲突交接、验证拒绝后的局部恢复。所有断言只证明纯函数契约，不能证明真实工作流、重试、审计或发布行为。
• 过渡： 第 11 章把单次 Tool 请求和结果做成可验证接口；第 12、14、18、19、26、27 章分别为实际执行、批准、容错、长任务、隔离与版本控制补全边界。

章节工件状态

1. 已完成：Research Brief 与候选参考资料。REF-031 至 REF-035 的允许陈述、外推禁区和写作日复核要求已登记。
2. 本阶段完成：Chapter Outline。逐节定义读者问题、叙述任务、证据边界、计划工件、验证和相邻章节责任。
3. 已完成：First Draft。正文已在 2026-07-16 写作日重读 REF-031 至 REF-035，并将产品或框架的限定陈述、本书工程模型和教学案例分开；当时 Mermaid 图源、示例和真实运行时均未实施。
4. 已完成：Technical Review。重新核对 REF-031 至 REF-035 的当前页面、来源范围、术语、相邻章节边界与阶段语义；修正统一词表、引用登记和本 Outline 的状态漂移，记录位于 .memory/reviews/2026-07-16-chapter-10-technical-review.md。
5. 已完成：Example Plan 与 Example Implementation。纯内存 assessWorkflowTransition 已先以模块缺失建立红灯，再由 8 项 Node 内置测试和演示验证；它只判断注入的教学对象，未调度、持久化、重放或调用模型、网络、文件、Git、Tool、权限或外部系统。记录位于 .memory/reviews/2026-07-16-chapter-10-example-integration.md。
6. 已完成：Mermaid 图源与 Diagram Review。chapter-10-workflow-state-machine.mmd 已由 Mermaid CLI 11.16.0 导出 SVG/PNG 并实际查看；图源与正文 Mermaid 块一致，且只表达本书的状态、证据和保守出口模型。记录位于 .memory/reviews/2026-07-16-chapter-10-diagram-review.md。
7. 已完成：Fact Check。REF-031 至 REF-035 已于 2026-07-16 重新读取；允许用途、外推禁区与纯内存示例的非产品边界见 10-workflow-and-state-management.fact-check.md。
8. 已完成：Language Editing。已统一术语首现、来源段落主语和段落节奏，未改变 REF-031 至 REF-035 的限定范围、示例接口或 Mermaid 语义；记录位于 .memory/reviews/2026-07-16-chapter-10-language-edit.md。
9. 已完成：Final Review。正文、来源、示例、图示、审查记录和状态工件已交叉复核；完整校验与 diff 检查的真实结果记录于 CURRENT_STATE.md。不得把本 Outline 的案例或验证描述为已经创建、运行、重放或核验的真实运行时工件。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] 覆盖执行与尝试、状态迁移、Workflow Contract、State Record、Checkpoint、重入、幂等性、Retry、Recovery、停止、升级和交接。
• [x] 明确区分 AWS、LangGraph、Temporal 的限定陈述与本书工程模型，未把产品/框架实现改写为通用保证。
• [x] 明确第 7、9、11、12、14、17、18、19、26、27 章的责任边界，不提前实现 Tool、权限、批准、重试运行时或多 Agent 隔离。
• [x] Mermaid 图示与示例实现均如实链接到实际工件和审查记录；图示、案例和验证没有被写成真实工作流、外部效果或运行时证明。