commit b2153d6f51b3e4a2cd4601e3dc06d5085dad7a27
Author: wehub-skill-sync <skill-sync@wehub.local>
Date:   Mon Jul 13 21:36:20 2026 +0800

    chore: import zh skill workflow-orchestration-patterns

diff --git a/README.wehub.md b/README.wehub.md
new file mode 100644
index 0000000..f0ec2c4
--- /dev/null
+++ b/README.wehub.md
@@ -0,0 +1,9 @@
+# WeHub 来源说明
+
+- Skill 名称：`workflow-orchestration-patterns`
+- 中文类目：分布式长事务工作流与 Saga 编排
+- 上游仓库：`wshobson__agents`
+- 上游路径：`plugins/backend-development/skills/workflow-orchestration-patterns/SKILL.md`
+- 上游链接：https://github.com/wshobson/agents/blob/HEAD/plugins/backend-development/skills/workflow-orchestration-patterns/SKILL.md
+- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
+- 原作者、版权和许可证信息以上游仓库为准
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..252fbf2
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,101 @@
+---
+
+
+---
+name: workflow-orchestration-patterns
+description: 使用 Temporal 为分布式系统设计持久化工作流。涵盖工作流与活动分离、Saga 模式、状态管理和确定性约束。在构建长时间运行的进程、分布式事务或微服务编排时使用。
+---
+
+# 工作流编排模式
+
+掌握基于 Temporal 的工作流编排架构，涵盖基础设计决策、弹性模式以及构建可靠分布式系统的最佳实践。
+
+## 何时使用工作流编排
+
+### 理想用例（来源：docs.temporal.io）
+
+- **多步骤流程**：跨机器/服务/数据库执行
+- **分布式事务**：需要全有或全无语义
+- **长时间运行的工作流**（数小时到数年）：自动持久化状态
+- **故障恢复**：必须从上一步成功处恢复执行
+- **业务流程**：预订、订单、营销活动、审批
+- **实体生命周期管理**：库存追踪、账户管理、购物车工作流
+- **基础设施自动化**：CI/CD 流水线、资源调配、部署
+- **人工介入**系统：需要超时和升级机制
+
+### 何时不应使用
+
+- 简单的 CRUD 操作（使用直接 API 调用）
+- 纯数据处理流水线（使用 Airflow、批处理）
+- 无状态请求/响应（使用标准 API）
+- 实时流处理（使用 Kafka、事件处理器）
+
+## 详细模式与工作示例
+
+详细模式文档位于 `references/details.md`。当上述导航层级不够用时，请阅读该文件。
+
+## 最佳实践
+
+### 工作流设计
+
+1. **保持工作流聚焦**——每个工作流单一职责
+2. **小型工作流**——使用子工作流实现可扩展性
+3. **明确边界**——工作流负责编排，活动负责执行
+4. **本地测试**——使用时间跳跃测试环境
+
+### 活动设计
+
+1. **幂等操作**——可安全重试
+2. **短生命周期**——持续数秒到数分钟，而非数小时
+3. **超时配置**——始终设置超时
+4. **长时间任务发送心跳**——上报进度
+5. **错误处理**——区分可重试与不可重试错误
+
+### 常见陷阱
+
+**工作流违规**：
+
+- 使用 `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
+
+**关键原则**：
+
+1. 工作流 = 编排，活动 = 外部调用
+2. 确定性对工作流来说不可妥协
+3. 幂等性对活动来说至关重要
+4. 状态持久化是自动的
+5. 为故障和恢复而设计
diff --git a/references/details.md b/references/details.md
new file mode 100644
index 0000000..62318f4
--- /dev/null
+++ b/references/details.md
@@ -0,0 +1,229 @@
+---
+name: workflow-orchestration-patterns
+version: 1.0.0
+license: MIT
+---
+
+# 工作流编排模式 —— 详细模式与实操示例
+
+## 关键设计决策：工作流 vs 活动
+
+**基本原则**（来源：temporal.io/blog/workflow-engine-principles）：
+
+- **工作流** = 编排逻辑与决策
+- **活动** = 外部交互（API、数据库、网络调用）
+
+### 工作流（编排）
+
+**特征：**
+
+- 包含业务逻辑与协调
+- **必须具有确定性**（相同输入 → 相同输出）
+- **不能**直接进行外部调用
+- 状态在故障时自动保留
+- 即使基础设施发生故障，也可运行数年
+
+**工作流示例任务：**
+
+- 决定执行哪些步骤
+- 处理补偿逻辑
+- 管理超时与重试
+- 协调子工作流
+
+### 活动（外部交互）
+
+**特征：**
+
+- 处理所有外部系统交互
+- 可以是非确定性的（API 调用、数据库写入）
+- 内置超时与重试逻辑
+- **必须是幂等的**（调用 N 次 = 调用一次）
+- 生命周期短（通常数秒至数分钟）
+
+**活动示例任务：**
+
+- 调用支付网关 API
+- 写入数据库
+- 发送电子邮件或通知
+- 查询外部服务
+
+### 设计决策框架
+
+```
+是否涉及外部系统？→ 活动
+是否为编排/决策逻辑？→ 工作流
+```
+
+## 核心工作流模式
+
+### 1. Saga 模式与补偿
+
+**目的**：实现分布式事务，具备回滚能力
+
+**模式**（来源：temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas）：
+
+```
+每个步骤：
+  1. 在执行之前先注册补偿
+  2. 执行该步骤（通过活动）
+  3. 失败时，按相反顺序（后进先出）运行所有补偿
+```
+
+**示例：支付工作流**
+
+1. 预留库存（补偿：释放库存）
+2. 扣款（补偿：退款）
+3. 履约订单（补偿：取消履约）
+
+**关键要求：**
+
+- 补偿操作必须是幂等的
+- 在执行步骤之前先注册补偿
+- 按相反顺序运行补偿
+- 优雅处理部分失败
+
+### 2. 实体工作流（Actor 模型）
+
+**目的**：代表单个实体实例的长期运行工作流
+
+**模式**（来源：docs.temporal.io/evaluate/use-cases-design-patterns）：
+
+- 一个工作流执行 = 一个实体（购物车、账户、库存项）
+- 工作流在实体生命周期内持续存在
+- 通过信号接收状态变更
+- 支持通过查询获取当前状态
+
+**使用场景示例：**
+
+- 购物车（添加商品、结账、过期）
+- 银行账户（存款、取款、余额查询）
+- 产品库存（库存更新、预订）
+
+**优势：**
+
+- 封装实体行为
+- 保证每个实体的一致性
+- 天然的事件溯源
+
+### 3. 扇出/扇入（并行执行）
+
+**目的**：并行执行多个任务，汇总结果
+
+**模式：**
+
+- 启动子工作流或并行活动
+- 等待所有任务完成
+- 汇总结果
+- 处理部分失败
+
+**扩缩规则**（来源：temporal.io/blog/workflow-engine-principles）：
+
+- 不要扩缩单个工作流
+- 对于 100 万个任务：启动 1K 个子工作流 × 每个处理 1K 个任务
+- 使每个工作流的规模有界
+
+### 4. 异步回调模式
+
+**目的**：等待外部事件或人工审批
+
+**模式：**
+
+- 工作流发送请求并等待信号
+- 外部系统异步处理
+- 发送信号以恢复工作流
+- 工作流继续处理响应
+
+**使用场景：**
+
+- 人工审批工作流
+- Webhook 回调
+- 长时间运行的外部进程
+
+## 状态管理与确定性
+
+### 自动状态保留
+
+**Temporal 的工作原理**（来源：docs.temporal.io/workflows）：
+
+- 完整程序状态自动保留
+- 事件历史记录每个命令和事件
+- 从崩溃中无缝恢复
+- 应用程序恢复到故障前状态
+
+### 确定性约束
+
+**工作流作为状态机执行**：
+
+- 重放行为必须一致
+- 相同输入 → 每次相同输出
+
+**工作流中禁止的操作**（来源：docs.temporal.io/workflows）：
+
+- ❌ 线程、锁、同步原语
+- ❌ 随机数生成（`random()`）
+- ❌ 全局状态或静态变量
+- ❌ 系统时间（`datetime.now()`）
+- ❌ 直接文件 I/O 或网络调用
+- ❌ 非确定性库
+
+**工作流中允许的操作**：
+
+- ✅ `workflow.now()`（确定性时间）
+- ✅ `workflow.random()`（确定性随机数）
+- ✅ 纯函数与计算
+- ✅ 调用活动（非确定性操作）
+
+### 版本化策略
+
+**挑战**：在旧执行仍在运行时修改工作流代码
+
+**解决方案：**
+
+1. **版本化 API**：使用 `workflow.get_version()` 进行安全变更
+2. **新的工作流类型**：创建新工作流，将新执行路由到它
+3. **向后兼容**：确保旧事件能正确重放
+
+## 弹性与错误处理
+
+### 重试策略
+
+**默认行为**：Temporal 会无限重试活动
+
+**配置重试：**
+
+- 初始重试间隔
+- 退避系数（指数退避）
+- 最大间隔（重试延迟上限）
+- 最大尝试次数（最终失败）
+
+**不可重试的错误：**
+
+- 无效输入（校验失败）
+- 业务规则违反
+- 永久性失败（资源未找到）
+
+### 幂等性要求
+
+**为何至关重要**（来源：docs.temporal.io/activities）：
+
+- 活动可能被执行多次
+- 网络故障会触发重试
+- 重复执行必须是安全的
+
+**实现策略：**
+
+- 幂等键（去重）
+- 先检查再执行 + 唯一约束
+- 使用更新插入操作替代插入
+- 跟踪已处理的请求 ID
+
+### 活动心跳
+
+**目的**：检测停滞的长时间运行活动
+
+**模式：**
+
+- 活动定期发送心跳
+- 包含进度信息
+- 若未收到心跳则超时
+- 支持基于进度的重试