migrating-to-workflow-sdk

迁移到 Workflow SDK

在将现有编排系统迁移到 Workflow SDK 时使用此技能。

信息收集

1. 确定源系统：
   • Temporal
   • Inngest
   • Trigger.dev
   • AWS Step Functions
2. 确定目标运行时：
   • 托管托管 -> 示例聚焦于 start()、getRun()、钩子/ Webhook 和路由处理程序。
   • 可自托管 -> 还需阅读 references/runtime-targets.md，并明确说明工作流/步骤代码可以保持不变，但部署仍需要 World 实现和启动引导程序。
3. 提取源系统的构造：
   • 入口点
   • 等待 / 计时器
   • 外部回调 / 审批
   • 重试 / 故障处理
   • 子工作流 / 扇出
   • 进度流式传输
   • 外部副作用

默认迁移规则

• 将编排放在 "use workflow" 函数中。
• 将副作用、SDK 调用、数据库调用、HTTP 调用和流 I/O 放在 "use step" 函数中。
• 仅在工作流上下文中使用 sleep()。
• 对于 Signals、step.waitForEvent() 和 .waitForTaskToken，恰好选择一种恢复方式：
  • resume/internal -> 当应用使用确定性的业务令牌从服务器端代码恢复时，使用 createHook() + resumeHook()。
  • resume/url/default -> 当外部系统需要生成的回调 URL，且默认的 202 Accepted 响应可接受时，使用 createWebhook()。
  • resume/url/manual -> 仅当提示明确要求自定义响应正文、状态码或标头时，使用 createWebhook({ respondWith: 'manual' })。
  • 如果有关回调 URL 的提示未指定响应语义，默认使用 resume/url/default，并在 ## Open Questions 中明确说明此假设。
• 绝不将 createWebhook() 与 resumeHook() 配对使用，也绝不向 createWebhook() 传递 token:。
• 对于子运行，将 start() 和 getRun() 包装在 "use step" 函数中。
• 将 getStepMetadata().stepId 用作外部写入的幂等键。
• 在工作流上下文中使用 getWritable() 获取流，但仅在 "use step" 函数中与其交互（写入、关闭）。
• 对于多步骤补偿，优先使用回滚栈。
• 按以下顺序选择应用边界语法：
  1. 如果提示明确要求与框架无关的应用边界代码，即使提到了 Hono 之类的框架，也使用普通的 Request / Response。
  2. 否则，如果指定了目标框架，则让应用边界示例符合该框架的形式。
  3. 否则，使用 Request / Response，并保持示例与框架无关。除非明确指定 Next.js，否则不要默认使用仅适用于 Next.js 的路由签名。

快速记忆要点：

• 回调 URL + 默认确认响应 -> createWebhook()
• 回调 URL + 自定义确认响应 -> createWebhook({ respondWith: 'manual' })
• 确定性的服务器端恢复 -> createHook() + resumeHook()

快速路径路由器

如果源系统会因 Signals、step.waitForEvent() 或 .waitForTaskToken 而暂停，请加载 references/resume-routing.md。

快速默认选项：

• 仅回调 URL -> resume/url/default
• 回调 URL + 明确的自定义响应 -> resume/url/manual
• 确定性的服务器端恢复 -> resume/internal
• 可自托管 -> 添加 runtime/self-hosted
• 指定框架 -> 添加 boundary/named-framework
• 明确要求与框架无关 -> 添加 boundary/framework-agnostic

起草 ## Migrated Code 前，先在 ## Migration Plan 中写出所选路由键。

源系统参考资料

• Temporal -> references/temporal.md
• Inngest -> references/inngest.md
• Trigger.dev -> references/trigger-dev.md
• AWS Step Functions -> references/aws-step-functions.md

共享参考资料

• references/shared-patterns.md：钩子、子工作流、幂等性、流式处理和回滚的可复用代码模板。
• references/runtime-targets.md：托管式与自定义 World 的使用指南。
• references/resume-routing.md：路由键选择、所需代码义务以及精确的 ## Migration Plan 格式。
• references/retries.md：规范的重试机制，包括 stepFn.maxRetries、RetryableError({ retryAfter }) 和 FatalError。

必需的输出格式

按以下结构返回迁移结果：

## Migration Plan
## Source -> Target Mapping
## Migrated Code
## App Boundary / Resume Endpoints
## Verification Checklist
## Open Questions

验证清单

如果符合以下任一条件，草稿即不合格：

• ## Migration Plan 未包含 Route keys
• ## Migration Plan 未包含 Why these route keys
• ## Migration Plan 列出的路由键与提示不符
• ## Migration Plan 列出的所需代码义务与所选路由键不符
• 迁移后的代码中仍有源框架原语
• 副作用仍留在工作流上下文中
• 步骤中出现 sleep()
• 工作流函数中出现流交互（getWriter()、write()、close()）
• 子工作流直接在工作流上下文中调用 start() / getRun()
• 外部写入未提供幂等键
• 源代码使用了 signals、waitForEvent 或 task tokens，但缺少钩子/网络钩子
• 回调 URL 流程使用 createHook() + resumeHook()，而不是 createWebhook()
• resume/url/default 或 resume/url/manual 迁移在 webhook.url 应是唯一恢复入口时，虚构了由用户编写的回调路由或 resumeWebhook() 包装器
• createWebhook() 使用了自定义 token，或与 resumeHook() 配对

验证说明：

• 允许在工作流上下文中读取网络钩子请求数据。只有 request.respondWith() 只能在步骤中使用。

其他不合格条件：

• resume/internal 输出未在应用边界代码中包含 resumeHook()
• resume/internal 输出未包含确定性的业务令牌
• resume/internal 输出使用了 createWebhook() 或 webhook.url
• resume/url/default 输出未将 webhook.url 传给外部系统
• resume/url/default 输出使用了 resumeHook()、respondWith: 'manual' 或 RequestWithResponse，但提示中未要求自定义响应
• resume/url/default 输出在 webhook.url 是预期恢复入口时，虚构了由用户编写的回调路由或 resumeWebhook() 包装器
• resume/url/manual 输出未将 webhook.url 传给外部系统
• resume/url/manual 输出未包含 RequestWithResponse 或 await request.respondWith(...)
• resume/url/manual 输出在 "use step" 函数之外调用 request.respondWith(...)
• resume/url/manual 输出在 webhook.url 是预期恢复入口时，虚构了由用户编写的回调路由或 resumeWebhook() 包装器
• createWebhook() 与 resumeHook() 配对使用
• 可自托管输出缺少 World extends Queue, Streamer, Storage、startWorkflowWorld()，或未明确说明工作流代码和步骤代码可以保持不变，但应用仍需要自定义 World
• 使用具名框架的输出混用了框架语法与纯 Request / Response 应用边界代码，却没有提供与框架无关的覆盖方案

如需查看具体且符合要求的代码，请加载：

• references/shared-patterns.md -> ## Generated callback URL (default response)
• references/shared-patterns.md -> ## Generated callback URL (manual response)
• references/runtime-targets.md -> ## Self-hosted output block
• references/aws-step-functions.md -> ## Combined recipe: callback URL on self-hosted Hono

示例提示

Migrate this Inngest workflow to the Workflow SDK.
It uses step.waitForEvent() with a timeout and step.realtime.publish().

预期响应格式：

## Migration Plan
## Source -> Target Mapping
## Migrated Code
## App Boundary / Resume Endpoints
## Verification Checklist
## Open Questions

示例参考

仅当提示词需要具体代码时，才加载已完成的示例：

• references/shared-patterns.md -> ## Named-framework internal resume example (Hono)
• references/shared-patterns.md -> ## Generated callback URL (default response)
• references/shared-patterns.md -> ## Generated callback URL (manual response)
• references/runtime-targets.md -> ## Self-hosted output block
• references/aws-step-functions.md -> ## Combined recipe: callback URL on self-hosted Hono

拒绝以下反例：

• 当 webhook.url 是预期的恢复入口时，使用 resume/url/default 或 resume/url/manual 搭配用户编写的回调路由
• 将 createWebhook() 与 resumeHook() 配对使用
• 将命名框架的应用边界输出与纯 Request / Response 混用，且未提供与框架无关的覆盖方式