workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CRITICAL: Always Use Correct

workflow

Documentation

重要提示: 始终使用正确的

workflow

文档

Your knowledge of

workflow

is outdated.

The

workflow

documentation outlined below matches the installed version of the Workflow DevKit. Follow these instructions before starting on any

workflow

-related tasks:

Search the bundled documentation in

node_modules/workflow/docs/

Find docs:

glob "node_modules/workflow/docs/**/*.mdx"

Search content:

grep "your query" node_modules/workflow/docs/

Documentation structure in

node_modules/workflow/docs/

```
getting-started/
```
- Framework setup (next.mdx, express.mdx, hono.mdx, etc.)
```
foundations/
```
- Core concepts (workflows-and-steps.mdx, hooks.mdx, streaming.mdx, etc.)
```
api-reference/workflow/
```
- API docs (sleep.mdx, create-hook.mdx, fatal-error.mdx, etc.)
```
api-reference/workflow-api/
```
- Client API (start.mdx, get-run.mdx, resume-hook.mdx, etc.)
```
ai/
```
- AI SDK integration docs
```
errors/
```
- Error code documentation

Related packages also include bundled docs:

@workflow/ai

node_modules/@workflow/ai/docs/

- DurableAgent and AI integration

@workflow/core

node_modules/@workflow/core/docs/

- Core runtime (foundations, how-it-works)

@workflow/next

node_modules/@workflow/next/docs/

- Next.js integration

When in doubt, update to the latest version of the Workflow DevKit.

你所掌握的

workflow

知识已过时。

以下列出的

workflow

文档与已安装的Workflow DevKit版本匹配。在开始任何与

workflow

相关的任务前，请遵循以下说明：

在

node_modules/workflow/docs/

中搜索捆绑的文档：

查找文档：

glob "node_modules/workflow/docs/**/*.mdx"

搜索内容：

grep "your query" 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/
```
- 错误码文档

Official Resources

官方资源

Website: https://useworkflow.dev
GitHub: https://github.com/vercel/workflow

官网：https://useworkflow.dev
GitHub：https://github.com/vercel/workflow

Quick Reference

快速参考

Directives:

typescript

"use workflow";  // First line - makes async function durable
"use step";      // First line - makes function a cached, retryable unit

Essential imports:

typescript

// Workflow primitives
import { sleep, fetch, createHook, createWebhook, getWritable } from "workflow";
import { FatalError, RetryableError } from "workflow";
import { getWorkflowMetadata, getStepMetadata } from "workflow";

// API operations
import { start, getRun, resumeHook, resumeWebhook } from "workflow/api";

// Framework integrations
import { withWorkflow } from "workflow/next";
import { workflow } from "workflow/vite";
import { workflow } from "workflow/astro";
// Or use modules: ["workflow/nitro"] for Nitro/Nuxt

指令：

typescript

"use workflow";  // 第一行 - 使异步函数具备持久化能力
"use step";      // 第一行 - 使函数成为可缓存、可重试的单元

必要导入：

typescript

// Workflow原语
import { sleep, fetch, createHook, createWebhook, getWritable } from "workflow";
import { FatalError, RetryableError } from "workflow";
import { getWorkflowMetadata, getStepMetadata } from "workflow";

// API操作
import { start, getRun, resumeHook, resumeWebhook } from "workflow/api";

// 框架集成
import { withWorkflow } from "workflow/next";
import { workflow } from "workflow/vite";
import { workflow } from "workflow/astro";
// 或使用模块：["workflow/nitro"] 用于Nitro/Nuxt

Prefer Step Functions to Avoid Sandbox Errors

优先使用Step函数以避免沙箱错误

"use workflow"

functions run in a sandboxed VM.

"use step"

functions have full Node.js access. Put your logic in steps and use the workflow function purely for orchestration.

typescript

// Steps have full Node.js and npm access
async function fetchUserData(userId: string) {
  "use step";
  const response = await fetch(`https://api.example.com/users/${userId}`);
  return response.json();
}

async function processWithAI(data: any) {
  "use step";
  // AI SDK works in steps without workarounds
  return await generateText({
    model: openai("gpt-4"),
    prompt: `Process: ${JSON.stringify(data)}`,
  });
}

// Workflow orchestrates steps - no sandbox issues
export async function dataProcessingWorkflow(userId: string) {
  "use workflow";
  const data = await fetchUserData(userId);
  const processed = await processWithAI(data);
  return { success: true, processed };
}

Benefits: Steps have automatic retry, results are persisted for replay, and no sandbox restrictions.

"use workflow"

函数在沙箱化VM中运行。

"use step"

函数拥有完整的Node.js访问权限。将你的逻辑放在step中，仅用workflow函数进行编排。

typescript

// Step拥有完整的Node.js和npm访问权限
async function fetchUserData(userId: string) {
  "use step";
  const response = await fetch(`https://api.example.com/users/${userId}`);
  return response.json();
}

async function processWithAI(data: any) {
  "use step";
  // AI SDK在step中无需变通即可工作
  return await generateText({
    model: openai("gpt-4"),
    prompt: `Process: ${JSON.stringify(data)}`,
  });
}

// Workflow编排step - 无沙箱问题
export async function dataProcessingWorkflow(userId: string) {
  "use workflow";
  const data = await fetchUserData(userId);
  const processed = await processWithAI(data);
  return { success: true, processed };
}

优势： Step具备自动重试功能，结果会被持久化以便重放，且无沙箱限制。

Workflow Sandbox Limitations

Workflow沙箱限制

When you need logic directly in a workflow function (not in a step), these restrictions apply:

Limitation	Workaround
No `fetch()`	`import { fetch } from "workflow"` then `globalThis.fetch = fetch`
No `setTimeout` / `setInterval`	Use `sleep("5s")` from `"workflow"`
No Node.js modules (fs, crypto, etc.)	Move to a step function

Example - Using fetch in workflow context:

typescript

import { fetch } from "workflow";

export async function myWorkflow() {
  "use workflow";
  globalThis.fetch = fetch;  // Required for AI SDK and HTTP libraries
  // Now generateText() and other libraries work
}

Note:

DurableAgent

from

@workflow/ai

handles the fetch assignment automatically.

当你需要在workflow函数中直接编写逻辑（而非step中）时，以下限制适用：

限制	解决方法
无 `fetch()`	从 `"workflow"` 导入 `fetch` ，然后执行 `globalThis.fetch = fetch`
无 `setTimeout` / `setInterval`	使用 `"workflow"` 中的 `sleep("5s")`
无Node.js模块（fs、crypto等）	移至step函数中

示例 - 在workflow上下文中使用fetch：

typescript

import { fetch } from "workflow";

export async function myWorkflow() {
  "use workflow";
  globalThis.fetch = fetch;  // AI SDK和HTTP库需要此设置
  // 现在generateText()和其他库可以正常工作
}

注意：

@workflow/ai

中的

DurableAgent

会自动处理fetch的赋值。

Error Handling

错误处理

Use

FatalError

for permanent failures (no retry),

RetryableError

for transient failures:

typescript

import { FatalError, RetryableError } from "workflow";

if (res.status >= 400 && res.status < 500) {
  throw new FatalError(`Client error: ${res.status}`);
}
if (res.status === 429) {
  throw new RetryableError("Rate limited", { retryAfter: "5m" });
}

对于永久性失败（不重试）使用

FatalError

，对于暂时性失败使用

RetryableError

：

typescript

import { FatalError, RetryableError } from "workflow";

if (res.status >= 400 && res.status < 500) {
  throw new FatalError(`客户端错误：${res.status}`);
}
if (res.status === 429) {
  throw new RetryableError("请求受限", { retryAfter: "5m" });
}

Serialization

序列化

All data passed to/from workflows and steps must be serializable.

Supported types: string, number, boolean, null, undefined, bigint, plain objects, arrays, Date, RegExp, URL, URLSearchParams, Map, Set, Headers, ArrayBuffer, typed arrays, Request, Response, ReadableStream, WritableStream.

Not supported: Functions, class instances, Symbols, WeakMap/WeakSet. Pass data, not callbacks.

所有在workflow与step之间传递的数据必须可序列化。

支持的类型： 字符串、数字、布尔值、null、undefined、bigint、普通对象、数组、Date、RegExp、URL、URLSearchParams、Map、Set、Headers、ArrayBuffer、类型化数组、Request、Response、ReadableStream、WritableStream。

不支持的类型： 函数、类实例、Symbol、WeakMap/WeakSet。传递数据，而非回调函数。

Streaming

流式处理

Use

getWritable()

in step functions to stream data:

typescript

async function streamData() {
  "use step";  // Required - streaming only works in steps
  const writer = getWritable();
  await writer.write(data);
  writer.releaseLock();  // Always release the lock
}

// Close when done
await getWritable().close();

在step函数中使用

getWritable()

进行流式数据传输：

typescript

async function streamData() {
  "use step";  // 必须设置 - 流式处理仅在step中生效
  const writer = getWritable();
  await writer.write(data);
  writer.releaseLock();  // 务必释放锁
}

// 完成后关闭
await getWritable().close();

Debugging

调试

bash

undefined

bash

undefined

Check workflow endpoints are reachable

检查工作流端点是否可达

npx workflow health npx workflow health --port 3001 # Non-default port

npx workflow health npx workflow health --port 3001 # 非默认端口

Visual dashboard for runs

运行实例的可视化仪表板

npx workflow web npx workflow web --app-url http://localhost:3001

CLI inspection (for agents)

CLI检查（适用于代理）

npx workflow inspect runs npx workflow inspect run <run_id>


**Tip:** Only import workflow APIs you actually use. Unused imports can cause 500 errors.

npx workflow inspect runs npx workflow inspect run <run_id>


**提示：** 仅导入实际使用的workflow API。未使用的导入可能导致500错误。",

workflow

Original

Translation

CRITICAL: Always Use Correct
`workflow`
Documentation

重要提示: 始终使用正确的
`workflow`
文档

Official Resources

官方资源

Quick Reference

快速参考

Prefer Step Functions to Avoid Sandbox Errors

优先使用Step函数以避免沙箱错误

Workflow Sandbox Limitations

Workflow沙箱限制

Error Handling

错误处理

Serialization

序列化

Streaming

流式处理

Debugging

调试

Check workflow endpoints are reachable

检查工作流端点是否可达

Visual dashboard for runs

运行实例的可视化仪表板

CLI inspection (for agents)

CLI检查（适用于代理）

workflow

Original

Translation

CRITICAL: Always Use Correct workflow Documentation

重要提示: 始终使用正确的workflow文档

Official Resources

官方资源

Quick Reference

快速参考

Prefer Step Functions to Avoid Sandbox Errors

优先使用Step函数以避免沙箱错误

Workflow Sandbox Limitations

Workflow沙箱限制

Error Handling

错误处理

Serialization

序列化

Streaming

流式处理

Debugging

调试

Check workflow endpoints are reachable

检查工作流端点是否可达

Visual dashboard for runs

运行实例的可视化仪表板

CLI inspection (for agents)

CLI检查（适用于代理）

CRITICAL: Always Use Correct
`workflow`
Documentation

重要提示: 始终使用正确的
`workflow`
文档