用途
本技能用于处理工作流编排模式（Workflow Orchestration Patterns）相关任务，提供指导、最佳实践与检查清单。当任务与工作流编排模式无关，或需要该范围之外的领域或工具时，不应使用本技能。
何时使用工作流编排
理想用例（来源：docs.temporal.io）：
- 跨机器、服务或数据库的多步骤流程
- 需要全有或全无语义的分布式事务
- 长时间运行的工作流（数小时到数年），具备自动状态持久化
- 必须从最后一个成功步骤恢复的故障恢复
- 业务流程：预订、订单、活动、审批
- 实体生命周期管理：库存跟踪、账户管理、购物车工作流
- 基础设施自动化：CI/CD 流水线、资源调配、部署
- 需要超时与升级的人工介入系统
不应使用的情况：
- 简单 CRUD 操作（使用直接 API 调用）
- 纯数据处理流水线（使用 Airflow、批处理）
- 无状态请求/响应（使用标准 API）
- 实时流处理（使用 Kafka、事件处理器）
关键设计决策：工作流与活动
基本规则（来源：temporal.io/blog/workflow-engine-principles）：
- 工作流 = 编排逻辑与决策
- 活动 = 外部交互（API、数据库、网络调用）
工作流（编排）特征：
- 包含业务逻辑与协调
- 必须是确定性的（相同输入 → 相同输出）
- 不能执行直接外部调用
- 状态在故障间自动保留
- 尽管基础设施故障，仍可运行数年
工作流任务示例：决定执行哪些步骤、处理补偿逻辑、管理超时与重试、协调子工作流。
活动（外部交互）特征：
- 处理所有外部系统交互
- 可以是非确定性的（API 调用、数据库写入）
- 包含内置超时与重试逻辑
- 必须幂等（调用 N 次 = 调用一次）
- 短生命周期（通常数秒到数分钟）
活动任务示例：调用支付网关 API、写入数据库、发送邮件或通知、查询外部服务。
设计决策框架：是否接触外部系统？→ 活动；是否为编排/决策逻辑？→ 工作流。
核心工作流模式
- Saga 模式与补偿
目的：实现具备回滚能力的分布式事务。
模式（来源：temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas）：
对每个步骤：
- 在执行前注册补偿
- 执行该步骤（通过活动）
- 失败时，按逆序（LIFO）运行所有补偿
示例：支付工作流
- 预留库存（补偿：释放库存）
- 扣款（补偿：退款）
- 履行订单（补偿：取消履行）
关键要求：补偿必须幂等；在执行步骤前注册补偿；按逆序运行补偿；优雅处理部分失败。
- 实体工作流（Actor 模型）
目的：表示单个实体实例的长生命周期工作流。
模式（来源：docs.temporal.io/evaluate/use-cases-design-patterns）：
- 一个工作流执行 = 一个实体（购物车、账户、库存项）
- 工作流在实体生命周期内持续存在
- 接收信号以变更状态
- 支持查询当前状态
示例用例：购物车（添加商品、结账、过期）、银行账户（存款、取款、余额查询）、产品库存（库存更新、预留）。
优势：封装实体行为；保证每个实体的一致性；自然的事件溯源。
- 扇出/扇入（并行执行）
目的：并行执行多个任务并聚合结果。
模式：生成子工作流或并行活动；等待全部完成；聚合结果；处理部分失败。
扩展规则（来源：temporal.io/blog/workflow-engine-principles）：不要扩展单个工作流；对于 100 万任务：生成 1000 个子工作流 × 每个 1000 任务；保持每个工作流有界。
- 异步回调模式
目的：等待外部事件或人工审批。
模式：工作流发送请求并等待信号；外部系统异步处理；发送信号以恢复工作流；工作流继续处理响应。
用例：人工审批工作流、Webhook 回调、长时间运行的外部流程。
状态管理与确定性
自动状态保留
Temporal 工作方式（来源：docs.temporal.io/workflows）：完整程序状态自动保留；事件历史记录每个命令与事件；从崩溃中无缝恢复；应用程序恢复故障前状态。
确定性约束
工作流作为状态机执行：重放行为必须一致；相同输入 → 每次相同输出。
工作流中禁止（来源：docs.temporal.io/workflows）：
- ❌ 线程、锁、同步原语
- ❌ 随机数生成（random()）
- ❌ 全局状态或静态变量
- ❌ 系统时间（datetime.now()）
- ❌ 直接文件 I/O 或网络调用
- ❌ 非确定性库
工作流中允许：
- ✅ workflow.now()（确定性时间）
- ✅ workflow.random()（确定性随机）
- ✅ 纯函数与计算
- ✅ 调用活动（非确定性操作）
版本管理策略
挑战：在旧执行仍在运行时更改工作流代码。
解决方案：
- 版本管理 API：将过程绑定到实际 SDK 语言与已安装版本。Python 使用 workflow.patched / workflow.deprecate_patch；其他 SDK 有不同 API。部署前重放现有历史；遵循官方 Python 版本管理指南。
- 新工作流类型：创建新工作流，将新执行路由到它
- 向后兼容：确保旧事件正确重放
弹性与错误处理
重试策略
默认行为：Temporal 永远重试活动。
配置重试：初始重试间隔；退避系数（指数退避）；最大间隔（重试延迟上限）；最大尝试次数（最终失败）。
不可重试错误：无效输入（验证失败）；业务规则违规；永久性失败（资源未找到）。
幂等性要求
为何关键（来源：docs.temporal.io/activities）：活动可能执行多次；网络故障触发重试；重复执行必须安全。
实现策略：幂等键（去重）；带唯一约束的先检查后操作；使用 upsert 而非 insert；跟踪已处理请求 ID。
活动心跳
目的：检测停滞的长时间运行活动。
模式：活动发送周期性心跳；包含进度信息；若未收到心跳则超时；支持基于进度的重试。
最佳实践
工作流设计：保持工作流专注——每个工作流单一职责；小型工作流——使用子工作流实现可扩展性；清晰边界——工作流编排，活动执行；本地测试——使用时间跳跃测试环境。
活动设计：幂等操作——可安全重试；短生命周期——数秒到数分钟，而非数小时；超时配置——始终设置超时；长任务心跳——报告进度；错误处理——区分可重试与不可重试。
常见陷阱
工作流违规：使用 datetime.now() 而非 workflow.now()；在工作流代码中使用线程或异步操作；直接从工作流调用外部 API；工作流中的非确定性逻辑。
活动错误：非幂等操作（无法处理重试）；缺少超时（活动永远运行）；无错误分类（重试验证错误）；忽略负载限制（每个参数 2MB）。
运维考虑
监控：工作流执行时长；活动失败率；重试尝试与退避；待处理工作流数量。
可扩展性：使用 worker 水平扩展；任务队列分区；子工作流分解；适当时活动批处理。
附加资源
官方文档：
- Temporal 核心概念：docs.temporal.io/workflows
- 工作流模式：docs.temporal.io/evaluate/use-cases-design-patterns
- 最佳实践：docs.temporal.io/develop/best-practices
- Saga 模式：temporal.io/blog/saga-pattern-made-easy
关键原则：工作流 = 编排，活动 = 外部调用；确定性对工作流不可协商；幂等性对活动至关重要；状态保留是自动的；为故障与恢复而设计。
限制
仅当任务明确匹配上述范围时使用本技能。不要将输出视为环境特定验证、测试或专家审查的替代品。如果缺少所需输入、权限、安全边界或成功标准，请停止并请求澄清。