把 Temporal/Inngest/Trigger.dev…

当你需要把现有编排系统（Temporal、Inngest、Trigger.dev、AWS Step Functions）迁移到 Workflow SDK 时，按此流程识别源系统、选择恢复路由并生成合规迁移代码。

适用场景

解决思路

1. 识别源系统：Temporal、Inngest、Trigger.dev 或 AWS Step Functions。
2. 识别目标运行时：托管托管时聚焦 start()、getRun()、hooks/webhooks 和 route handlers；自托管时额外阅读 references/runtime-targets.md，并明确说明 workflow/step 代码可保持不变，但部署仍需实现 World 和启动引导。
3. 提取源构造：入口点、等待/定时器、外部回调/审批、重试/失败处理、子工作流/扇出、进度流、外部副作用。
4. 把编排逻辑放在 "use workflow" 函数中。
5. 把副作用、SDK 调用、数据库调用、HTTP 调用和流 I/O 放在 "use step" 函数中。
6. 只在 workflow 上下文中使用 sleep()。
7. 对于 Signals、step.waitForEvent() 和 .waitForTaskToken，只选择一个恢复面：resume/internal 使用 createHook() + resumeHook()（应用从服务端代码用确定性业务 token 恢复时）；resume/url/default 使用 createWebhook()（外部系统需要生成的回调 URL 且默认 202 Accepted 响应可接受时）；resume/url/manual 仅在提示明确要求自定义响应体、状态或头时使用 createWebhook({ respondWith: 'manual' })；如果回调 URL 提示未指定响应语义，默认使用 resume/url/default 并在 ## Open Questions 中明确该假设。
8. 绝不要将 createWebhook() 与 resumeHook() 配对，也绝不要给 createWebhook() 传 token:。
9. 把子运行的 start() 和 getRun() 包在 "use step" 函数中。
10. 使用 getStepMetadata().stepId 作为外部写入的幂等键。
11. 在 workflow 上下文中用 getWritable() 获取流，但只在 "use step" 函数中与之交互（写入、关闭）。
12. 多步补偿优先使用回滚栈。
13. 按以下顺序选择应用边界语法：1) 如果提示明确要求框架无关的应用边界代码，即使点名了 Hono 等框架也使用普通 Request / Response；2) 否则如果点名了目标框架，按该框架塑造应用边界示例；3) 否则保持示例框架无关，使用 Request / Response，除非明确点名 Next.js，否则不要默认使用 Next.js 专属路由签名。
14. 快速记忆：回调 URL + 默认确认 -> createWebhook()；回调 URL + 自定义确认 -> createWebhook({ respondWith: 'manual' })；确定性服务端恢复 -> createHook() + resumeHook()。
15. 当源在 Signals、step.waitForEvent() 或 .waitForTaskToken 处暂停时，加载 references/resume-routing.md。
16. 快速默认：仅回调 URL -> resume/url/default；回调 URL + 显式自定义响应 -> resume/url/manual；确定性服务端恢复 -> resume/internal；自托管 -> 追加 runtime/self-hosted；点名框架 -> 追加 boundary/named-framework；显式框架无关请求 -> 追加 boundary/framework-agnostic。
17. 在起草 ## Migrated Code 之前，先在 ## Migration Plan 中写下选定的 route keys。
18. 按源加载参考：Temporal -> references/temporal.md；Inngest -> references/inngest.md；Trigger.dev -> references/trigger-dev.md；AWS Step Functions -> references/aws-step-functions.md。
19. 共享参考：references/shared-patterns.md（hooks、子工作流、幂等、流、回滚的可复用代码模板）；references/runtime-targets.md（托管 vs 自定义 World 指南）；references/resume-routing.md（route-key 选择、义务和确切的 ## Migration Plan 形状）；references/retries.md（规范重试机制，包括 stepFn.maxRetries、RetryableError({ retryAfter }) 和 FatalError）。
20. 按以下结构返回迁移结果：## Migration Plan、## Source -> Target Mapping、## Migrated Code、## App Boundary / Resume Endpoints、## Verification Checklist、## Open Questions。
21. 验证清单——若以下任一为真则草稿失败：## Migration Plan 缺少 Route keys；缺少 Why these route keys；列出的 route keys 与提示不匹配；列出的必需代码义务与所选 route keys 不匹配；迁移代码中残留源框架原语；副作用仍在 workflow 上下文中；sleep() 出现在 step 内；流交互（getWriter()、write()、close()）出现在 workflow 函数内；子工作流直接从 workflow 上下文调用 start() / getRun()；外部写入缺少幂等键；源使用 signals、waitForEvent 或 task tokens 处缺少 hooks/webhooks；回调 URL 流程使用 createHook() + resumeHook() 而非 createWebhook()；resume/url/default 或 resume/url/manual 迁移在 webhook.url 应为唯一恢复面时发明用户编写的回调路由或 resumeWebhook() 包装；createWebhook() 被赋予自定义 token 或与 resumeHook() 配对。
22. 验证说明：在 workflow 上下文中读取 webhook 请求数据是允许的，只有 request.respondWith() 是 step 专属。
23. 额外失败条件：resume/internal 输出在应用边界代码中缺少 resumeHook()；缺少确定性业务 token；发出 createWebhook() 或 webhook.url；resume/url/default 输出未将 webhook.url 传给外部系统；发出 resumeHook()、respondWith: 'manual' 或 RequestWithResponse 而提示无自定义响应要求；在 webhook.url 为预期恢复面时发明用户编写的回调路由或 resumeWebhook() 包装；resume/url/manual 输出未将 webhook.url 传给外部系统；缺少 RequestWithResponse 或 await request.respondWith(...)；在 "use step" 函数外调用 request.respondWith(...)；在 webhook.url 为预期恢复面时发明用户编写的回调路由或 resumeWebhook() 包装；createWebhook() 与 resumeHook() 配对；自托管输出缺少 World extends Queue, Streamer, Storage、startWorkflowWorld() 或明确说明 workflow 和 step 代码可保持不变但应用仍需自定义 World；点名框架输出在无框架无关覆盖的情况下将框架语法与普通 Request / Response 应用边界代码混用。
24. 具体通过代码加载：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。
25. 仅在提示需要具体代码时加载已完成的示例：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。
26. 拒绝这些反例：resume/url/default 或 resume/url/manual + 用户编写的回调路由而 webhook.url 为预期恢复面；createWebhook() 与 resumeHook() 配对；点名框架的应用边界输出与普通 Request / Response 混用且无框架无关覆盖。

适用边界 · 注意事项

• 源系统不是 Temporal、Inngest、Trigger.dev 或 AWS Step Functions 之一时。
• 目标不是 Workflow SDK 时。
• 无法确定恢复语义且提示未指定响应语义时，不应擅自选择 resume/url/manual 或发明自定义回调路由。