## _CRITICAL_ ：始终使用正确的“工作流程”文档您对“工作流程”的了解已经过时了。下面概述的“工作流程”文档与已安装的工作流程 DevKit 版本相匹配。在开始执行任何“工作流程”相关任务之前，请遵循以下说明：在“node_modules/workflow/docs/”中搜索捆绑文档： 1. **查找文档** : `glob "node_modules/workflow/docs/**/*.mdx"` 2. **搜索内容** : `grep "您的查询" node_modules/workflow/docs/` `node_modules/workflow/docs/` 中的文档结构： * `getting-started/` \- 框架设置（next.mdx、express.mdx、hono.mdx 等） * `foundations/` \- 核心概念（workflows-and-steps.mdx、hooks.mdx、streaming.mdx 等） * `api-reference/workflow/` \- API 文档（sleep.mdx、create-hook.mdx、 fatal-error.mdx 等） * `api-reference/workflow-api/` \- 客户端 API（start.mdx、get-run.mdx、resume-hook.mdx 等） * `ai/` \- AI SDK 集成文档 * `errors/` \- 错误代码文档相关包还包括捆绑文档： * `@workflow/ai`: `node_modules/@workflow/ai/docs/` \- DurableAgent 和 AI 集成 * `@workflow/core`: `node_modules/@workflow/core/docs/` \- 核心运行时（基础、工作原理） * `@workflow/next`: `node_modules/@workflow/next/docs/` \- Next.js 集成 **如有疑问，请更新到最新版本的工作流程开发工具包。** ### 官方资源 * **网站**： * **GitHub**： ### 快速参考 **指令：** “使用工作流程”； // 第一行 - 使异步函数持久 “使用步骤”； // 第一行 - 使函数成为缓存的、可重试的单元 **必需进口：** // 工作流原语从“工作流”导入{ sleep、fetch、createHook、createWebhook、getWritable }；从“工作流”导入 { FatalError, RetryableError }; 从“工作流”导入{ getWorkflowMetadata，getStepMetadata }； // API操作从“workflow/api”导入{start、getRun、resumeHook、resumeWebhook}； // 框架集成从“workflow/next”导入{withWorkflow}；从“workflow/vite”导入{workflow}；从“workflow/astro”导入{工作流程}； // 或者使用模块：["workflow/ninto"] 用于 Nitro/Nuxt // 人工智能代理从“@workflow/ai/agent”导入{ DurableAgent }； ## 首选 Step Functions 以避免沙箱错误 “使用工作流”函数在沙盒虚拟机中运行。 “use step”函数具有 **完整的 Node.js 访问权限**。将您的逻辑分步骤进行，并使用工作流功能纯粹用于编排。 // 步骤具有完整的 Node.js 和 npm 访问权限异步函数 fetchUserData(userId: string) { “使用步骤”； const 响应 = 等待 fetch(`https://api.example.com/users/${userId}`); 返回response.json(); } 异步函数 processWithAI(data: any) { “使用步骤”； // AI SDK 分步骤工作，无需解决方法返回等待生成文本（{ 型号：openai（“gpt-4”），提示：`过程：${JSON.stringify(data)}`, }); } // 工作流程编排步骤 - 无沙箱问题导出异步函数 dataProcessingWorkflow(userId: string) { “使用工作流程”； const data = 等待 fetchUserData(userId); const 已处理 = 等待 processWithAI(数据); 返回{成功：true，已处理}； } **优点：** 步骤可以自动重试，结果可以保留以供重播，并且没有沙箱限制。 ## 工作流沙箱限制当您直接在工作流函数（而不是步骤）中需要逻辑时，以下限制适用：限制|解决方法 ---|--- 没有 `fetch()` | `import { fetch } from "workflow"` 然后 `globalThis.fetch = fetch` 没有 `setTimeout`/`setInterval` |使用“工作流程”中的“睡眠（“5s”）” 没有 Node.js 模块（fs、crypto 等）|移动到阶跃函数 **示例 - 在工作流上下文中使用 fetch：** 从“工作流程”导入{获取}；导出异步函数 myWorkflow() { “使用工作流程”； globalThis.fetch = 获取； // AI SDK 和 HTTP 库必需 // 现在generateText()和其他库可以工作了 } **注意：** 来自“@workflow/ai”的“DurableAgent”会自动处理获取分配。 ## DurableAgent — 工作流程中的 AI 代理使用“DurableAgent”构建能够维持状态并在中断中幸存的 AI 代理。它自动处理工作流沙箱（不需要手动“globalThis.fetch”）。从“@workflow/ai/agent”导入{ DurableAgent }；从“工作流程”导入{ getWritable }；从“zod”导入{z}；从“ai”导入类型{UIMessageChunk}；异步函数lookupData（{查询}：{查询：字符串}）{ “使用步骤”； // Step 函数具有完整的 Node.js 访问权限 return `“${query}”的结果`; } 导出异步函数 myAgentWorkflow(userMessage: string) { “使用工作流程”； const 代理 = 新 DurableAgent({ 型号：“anthropic/claude-sonnet-4-5”，系统：“你是一个得力助手。”, 工具：{ 查找数据：{ 描述：“搜索信息”， inputSchema: z.object({ 查询: z.string() }), 执行：查找数据， }, }, }); const 结果 = 等待代理.stream({ 消息：[{角色：“用户”，内容：userMessage }]，可写： getWritable(), 最大步数：10， }); 返回结果.消息； } **要点：** * `getWritable()` 将输出流传输到工作流运行的默认流 * 需要 Node.js/npm 访问的工具 `execute` 函数应使用 `"use step"` * 使用工作流原语的工具“执行”函数（“sleep()”、“createHook()”）不应使用“使用步骤”——它们在工作流级别运行 * `maxSteps` 限制 LLM 调用的数量（默认无限制） * 多轮：将 `result.messages` 加上新的用户消息传递给后续的 `agent.stream()` 调用 **有关“DurableAgent”的更多详细信息，请查看“node_modules/@workflow/ai/docs/”中的 AI 文档。** ## 启动工作流程和子工作流程使用“start()”从 API 路由启动工作流程。 **`start()` 不能在工作流上下文中直接调用** - 将其包装在步骤函数中。从“workflow/api”导入{start}； // 从 API 路径 - 直接工作导出异步函数 POST() { const run = 等待启动(myWorkflow, [arg1, arg2]); 返回 Response.json({ runId: run.runId }); } // 无参数工作流程 const run = 等待开始(noArgWorkflow); **从工作流程内部启动子工作流程 - 必须使用步骤：** 从“workflow/api”导入{start}； // 将 start() 包装在步骤函数中异步函数triggerChild（数据：字符串）{ “使用步骤”； const run = wait start(childWorkflow, [数据]); 返回run.runId； } 导出异步函数parentWorkflow() { “使用工作流程”； const childRunId =等待triggerChild("一些数据"); // 通过步骤即发即忘等待睡眠（“1小时”）； } `start()` 立即返回 - 它不会等待工作流程完成。使用“run.returnValue”等待完成。 ## Hooks — 通过外部事件暂停和恢复挂钩让工作流程等待外部数据。在工作流程中使用“createHook()”，并在 API 路由中使用“resumeHook()”。确定性标记仅适用于 `createHook()` \+ `resumeHook()` （服务器端）。 `createWebhook()` 始终生成随机令牌 - 不要将 `token` 选项传递给 `createWebhook()`。 ### 单一事件从“工作流程”导入{createHook}；导出异步函数approvalWorkflow() { “使用工作流程”； const hook = createHook<{ 批准: 布尔值 }>({ token: "approval-123", // 外部系统的确定性令牌 }); const 结果 = 等待钩子； // 工作流程在此暂停返回结果.批准; } ### 多个事件（可迭代钩子） Hooks 实现 `AsyncIterable` — 使用 `for wait...of` 来接收多个事件：从“工作流程”导入{createHook}；导出异步函数 chatWorkflow(channelId: string) { “使用工作流程”； const hook = createHook<{ 文本：字符串；完成？：布尔值 }>({ 令牌：`聊天-${channelId}`， }); for等待（钩子的常量事件）{ 等待 processMessage(event.text); if (event.done) 中断； } } 每个“resumeHook（token，payload）”调用都会向循环传递下一个值。 ### 从 API 路由恢复从“workflow/api”导入{resumeHook}；导出异步函数 POST(req: Request) { const { token, data } = wait req.json(); 等待resumeHook（令牌，数据）；返回新的响应（“确定”）； } ## 错误处理使用 `FatalError` 表示永久失败（不重试），使用 `RetryableError` 表示暂时失败：从“工作流”导入 { FatalError, RetryableError }; if (res.status >= 400 && res.status < 500) { throw new FatalError(`客户端错误：${res.status}`); } if (res.status === 429) { throw new RetryableError("速率受限", { retryAfter: "5m" }); } ## 序列化传入/传出工作流和步骤的所有数据都必须可序列化。 **支持的类型：**字符串、数字、布尔值、null、未定义、bigint、普通对象、数组、日期、RegExp、URL、URLSearchParams、Map、Set、标头、ArrayBuffer、类型化数组、请求、响应、ReadableStream、WritableStream。 **不支持：** 函数、类实例、符号、WeakMap/WeakSet。传递数据，而不是回调。 ## 流媒体使用 getWritable() 从工作流流式传输数据。 `getWritable()` 可以在**工作流和步骤上下文中调用，但您**不能直接在工作流函数中与流交互**（调用 `getWriter()`、`write()`、`close()`）。流必须传递给实际 I/O 的步骤函数，或者步骤可以自己调用“getWritable()”。 **获取工作流中的流，将其传递给步骤：** 从“工作流程”导入{ getWritable }；导出异步函数 myWorkflow() { “使用工作流程”；常量可写 = getWritable(); 等待 writeData(可写，“你好世界”); } 异步函数 writeData(writable: WritableStream, chunk: string) { “使用步骤”； const writer = writable.getWriter(); 尝试{ 等待 writer.write(chunk); }最后{ writer.releaseLock(); } } **直接在步骤中调用`getWritable()`（不需要传递它）：** 从“工作流程”导入{ getWritable }；异步函数streamData（块：字符串）{ “使用步骤”； const writer = getWritable().getWriter(); 尝试{ 等待 writer.write(chunk); }最后{ writer.releaseLock(); } } ## 调试 # 检查工作流端点是否可达 npx 工作流程运行状况 npx工作流运行状况 --port 3001 # 非默认端口 # 运行的可视化仪表板 npx 工作流程网络 npx 工作流程 web # CLI 检查（使用 --json 获得机器可读的输出，--help 获得完整使用） npx 工作流程检查运行 npx 工作流程检查运行 # 对于 Vercel 部署的项目，指定后端和项目 npx 工作流程检查运行 --backend vercel --project <项目名称> --team <团队slug> npx 工作流检查运行 --backend vercel --project <项目名称> --team # 在浏览器中打开 Vercel 仪表板进行特定运行 npx 工作流程检查运行 --web npx 工作流程 web --backend vercel --project <项目名称> --team # 取消正在运行的工作流程 npx 工作流程取消 npx 工作流程取消 --backend vercel --project <项目名称> --team # --env 默认为“生产”；使用 --env Preview 进行预览部署 **调试技巧：** * 在任何命令上使用 `--json` (`-j`) 以获得机器可读的输出 * 使用 `--web` 在浏览器中打开 Vercel Observability 仪表板 * 在任何命令上使用 `--help` 来获取完整的使用详细信息 * 只导入您实际使用的工作流API。未使用的导入可能会导致 500 错误。

工作流程

包含技能