第 10 章 Research Brief：Workflow 与状态管理

研究目标

为“Workflow 与状态管理”建立可追溯的事实边界：从状态机、错误处理、检查点、恢复与幂等性中提炼读者需要解决的工程问题，同时把本书的 Workflow Contract、状态记录、交接包和停止规则明确保留为原创工程模型。

本章承接第 9 章的 Plan Brief 与任务卡。第 9 章回答“应做什么、为何做、依赖什么、何时停止”；本章只研究一个已经获准的任务如何以可观察状态推进、在中断后如何判断可否继续，以及何时必须停止或人工升级。

本章要回答的问题

1. 任务清单为什么不能替代工作流（Workflow）：一个任务从准备到完成至少还缺少哪些状态、迁移和证据？
2. 如何区分工作流定义、一次执行、一次尝试、检查点和结果证据，避免把“正在运行”误写成“已经完成”？
3. 哪些错误可以根据明确策略重试，哪些情况必须进入恢复、阻塞或人工升级？
4. 为什么恢复不是“从上次看到的文本继续”，而是重读可追溯状态、确认前置条件和副作用边界？
5. 为什么重入（re-entry）和重试需要幂等性（Idempotency）设计，尤其在先前效果是否已经发生尚不明确时？
6. 交接给另一位人类或 Agent 时，最小的状态、证据、未知项和下一步信息是什么？

一手来源与允许用途

ID	来源事实	本章允许用途	禁止外推
REF-031	AWS Step Functions 将其工作流描述为由事件驱动步骤组成的状态机；其页面区分流程状态与任务状态，并说明执行、状态输入输出、错误处理和 redrive 是该产品概念。	以一个产品的明确术语说明：工作流需要状态、迁移、执行实例和输入输出，而非仅有步骤列表。	Amazon States Language、JSON 字段、服务集成、redrive 语义或 AWS 运行保证可作为本书通用协议。
REF-032	AWS Step Functions 的错误处理文档说明该产品在匹配重试策略后才进入匹配的 Catch 分支，并给出 Retry、Catch 与错误输出的产品行为。	用作“重试、恢复分支和失败终态必须显式建模”的产品实例。	所有系统都应先 Retry 后 Catch；具体错误名、退避参数、次数、超时或恢复顺序适用于其他系统。
REF-033	LangGraph 的 Persistence 文档说明该框架可把图状态写为按 thread 组织的 checkpoint，并把这用于恢复、人工中断、历史查看和 replay。	说明“可恢复执行”需要可定位的已保存状态；用该框架实例提醒读者区分 checkpoint、thread 与跨任务记忆。	LangGraph 的保存频率、存储实现、线程字段、时间旅行、加密或版本兼容规则是通用工作流标准。
REF-034	LangGraph Functional API 文档说明其任务与子图结果可被持久化，恢复可能导致未完成任务重执行，并建议把副作用置于任务中且设计为幂等。	说明一次恢复可能触发重入，因此外部效果需有防重复策略；只作为框架限定的工程背景。	任意 Agent 框架都以同样方式重放；某个键、upsert 或任务包装自动提供跨系统的 exactly-once 保证。
REF-035	Temporal 的架构文档将其实现描述为按工作流执行保存追加式历史，并要求其 Workflow 代码保持确定性、Activity 代码具备幂等性或非重试语义。	作为“历史、重放与副作用边界需要共同设计”的另一种实现背景。	事件溯源、确定性限制或 Activity 划分是本书 Workflow Contract 的强制实现；Temporal 的持久化或重试行为适用于任何平台。

来源陈述与本书模型的分界

来源只支持各自产品或框架的行为。本章不从任何一个来源推出“所有工作流都必须使用某个框架”“检查点天然可靠”或“幂等性自动实现”。以下模型由本书提出，后续正文必须明确使用“本书建议”或“本书模型”表述。

Workflow Contract

本书建议把 Workflow Contract 写成可审查工件，至少包含：

• workflow 的目标、边界、版本与入口条件；
• 合法状态、开始状态、终态和允许迁移；
• 每次迁移的输入、输出、负责人、可观察证据和失败表示；
• 哪些迁移只是准备或观察，哪些迁移会请求外部副作用；
• 可重试条件、重试预算、恢复前检查、停止条件和人工升级条件；
• 交接时必须带走的状态快照、未解决依赖、已知未知项和下一步候选。

这不是 JSON schema、产品 API、状态存储格式或权限系统。它的作用是让读者在设计具体实现前能审查状态和责任是否完整。

状态记录与检查点

本书将状态记录（State Record）定义为某次执行的可检查描述：至少关联 workflow 定义版本、执行标识、当前状态、最近成功的迁移、已观察证据、未决风险和下一次允许的动作。检查点（Checkpoint）是可用于恢复判断的一份状态记录或其持久化快照；它不等同于长期记忆（第 7 章），也不自动证明副作用已经提交。

本书建议把以下情况保持分开：

• 计划已批准： 第 9 章的任务可进入执行准备，但尚未发生状态迁移；
• 迁移已请求： 系统或人员提出下一动作，尚未形成观察证据；
• 迁移已观察： 收到可关联的结果或错误，但还需按验收规则判断；
• 验证接受或拒绝： 第 17 章的评估规则对目标状态作出判定；
• 未证实： 缺少关联、检查点、证据或前置条件，不能据此推断成功、失败或可安全重试。

恢复、重入与停止

本书模型中的恢复不是盲目继续：先定位状态记录，检查定义版本和前置条件，再区分“可从检查点安全重入”“需要补充观察”“需要重新计划”与“必须停止”。若先前外部效果是否发生不明、批准已过期、状态记录冲突或关键证据缺失，工作流应进入 blocked 或 requires_approval，而不是自动重复请求。

幂等性在本章只表示一个工程目标：重复处理同一已识别的效果请求，不应产生额外不可解释的效果。如何为具体 Tool、数据库、文件、浏览器或权限系统建立去重键、事务、锁或审计证据，分别留给第 11、12、25、26 和 27 章。

章节范围与非目标

本章讨论状态设计、状态迁移、检查点、恢复判断、重试边界、交接信息和停止规则。它不：

• 实现真实状态机、队列、持久化后端、分布式锁、租约、事务、exactly-once 语义或调度器；
• 定义 Tool 请求和返回协议（第 11 章）、Sandbox 与授权执行（第 12 章）、知识检索（第 13 章）或人工批准交互（第 14 章）；
• 取代第 18 章对 Retry、Recovery 与容错的深入策略，也不覆盖第 19 章长任务压缩和第 26 章多 Agent 隔离；
• 把本书的章节生产表或第 9 章 assessTaskPlan 纯内存教学函数称为可恢复运行时、真实状态机或权限实现。

计划正文结构

1. 从任务卡到执行状态： 说明任务定义与实际执行实例的差别，建立定义、执行、尝试和证据的最小词表。
2. 状态机与迁移契约： 用 Workflow Contract 指明合法状态、终态、迁移输入输出和每个迁移的证据。
3. 状态记录、检查点与交接： 区分当前运行状态、恢复快照和长期记忆；定义交接时不可省略的信息。
4. 重试、恢复与幂等性边界： 根据错误分类、效果不确定性和重入风险判断重试、恢复、阻塞或升级；不提供跨产品参数配方。
5. 停止与人工升级： 解释未知效果、状态冲突、证据缺口和超出授权范围为何不能靠重复执行解决。
6. 教学案例： 用本书的“Research → Outline → Draft → Review → Validate”生产流程设计状态表、恢复演练和交接包；案例只描述本书模型，不宣称实际工作流引擎行为。

拟议图示、示例与验证边界

• 图示： 计划的章节生产状态机，展示 ready、in_progress、blocked、requires_approval、validated 与终态之间的允许迁移；另以虚线说明“检查点供恢复判断”而不是“检查点证明结果正确”。此图仅表达本书模型，尚未创建图源。
• 最小示例： 后续可实现一个纯内存函数：输入 Workflow Contract、State Record、注入的观察和重试预算，输出“允许迁移”“需要补证”“需要批准”或“阻塞”。它不得持久化、调度、重放、调用模型、网络、文件、Tool 或权限系统。
• 计划测试： 至少覆盖合法迁移、终态拒绝再进入、缺 checkpoint、未知效果、过期批准和同一 effect key 的重入判定。测试只能证明教学函数的输入输出契约。
• 恢复演练： 后续正文的案例要把“上次状态”与“实际已发生效果”分开，并将缺少证据的恢复结果标为未证实，而非伪造成功或失败。

动态信息与写作要求

• REF-031、REF-032、REF-033 和 REF-034 是持续变化的产品或框架文档；正文、示例和事实核验当天必须重新读取，不能沿用本 Brief 的产品字段、版本、默认值或行为描述。
• REF-035 指向持续演进的官方项目架构文档；若正文使用其事件历史、确定性或重试限定，必须在写作当天重新定位原文并核对语境。
• 不引用配额、价格、性能数字、存储保证或安全属性，除非针对具体版本、配置和来源逐项核验。
• 若案例变为真实的书籍发布、文件写入、Git 操作或外部服务调用，须分别补充实际环境、批准边界和运行证据；不能把教学状态记录当作真实审计记录。

Research 完成检查

• [x] 每条可归因陈述都限定了来源、允许用途和外推禁区。
• [x] 区分了状态机产品行为、框架检查点/重放行为、Temporal 架构背景与本书工程模型。
• [x] 明确第 9 章计划模型、第 7 章长期记忆和本章执行状态的边界。
• [x] 定义了后续正文、图示、示例、测试和恢复演练的非事实边界。
• [x] 为动态资料记录了写作日重新核验要求。