mcpField
W
workflow

workflow

github.com/vercel-labs开发5.9k178 次安装22 周前更新
代码仓库

关于 workflow

面向 Workflow DevKit 的编码技能，指导开发者查阅已安装版本的文档并遵循运行约定，涵盖持久化工作流、沙箱限制、错误处理、序列化、流式处理和调试。

主要功能

  1. 01搜索随包提供的 Workflow 文档
  2. 02将编排逻辑与 Node.js 步骤分开
  3. 03处理重试和永久性错误
  4. 04遵循序列化与流式处理限制
  5. 05检查端点并查看运行记录

适用场景

  1. 01针对已安装版本实现工作流
  2. 02将依赖 Node.js 的逻辑移入步骤
  3. 03处理临时故障与永久性错误
  4. 04调试工作流端点和运行记录

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel-labs/open-agents --skill workflow

安装后在 Claude Code 中输入/workflow确认已加载。

详细介绍

重要：始终使用正确的 workflow 文档

你对 workflow 的了解已经过时。

以下 workflow 文档与已安装的 Workflow DevKit 版本相符。 开始处理任何与 workflow 相关的任务之前，请遵循以下说明：

搜索 node_modules/workflow/docs/ 中附带的文档：

  1. 查找文档：glob "node_modules/workflow/docs/**/*.mdx"
  2. 搜索内容：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/ - 错误代码文档

相关软件包也附带了文档：

  • @workflow/ai：node_modules/@workflow/ai/docs/ - DurableAgent 和 AI 集成
  • @workflow/core：node_modules/@workflow/core/docs/ - 核心运行时（foundations、how-it-works）
  • @workflow/next：node_modules/@workflow/next/docs/ - Next.js 集成

如有疑问，请更新到最新版本的 Workflow DevKit。

官方资源
快速参考

指令：

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

必要的导入：

// 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

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

"use workflow" 函数在沙箱化的 VM 中运行。"use step" 函数可完全访问 Node.js。将逻辑放在步骤中，并仅使用工作流函数进行编排。

// 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 };
}

**优点：**步骤会自动重试，结果会持久化以供重放，且不受沙箱限制。

工作流沙箱限制

如果需要直接在工作流函数（而非步骤）中编写逻辑，则需遵守以下限制：

限制解决方法
不支持 fetch()import { fetch } from "workflow"，然后设置 globalThis.fetch = fetch
不支持 setTimeout/setInterval使用来自 "workflow" 的 sleep("5s")
不支持 Node.js 模块（fs、crypto 等）移至步骤函数中

示例 - 在工作流上下文中使用 fetch：

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
}

注意：@workflow/ai 中的 DurableAgent 会自动处理 fetch 赋值。

错误处理

使用 FatalError 处理永久性故障（不重试），使用 RetryableError 处理暂时性故障：

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" });
}

序列化

传入或传出工作流和步骤的所有数据都必须可序列化。

**支持的类型：**string、number、boolean、null、undefined、bigint、普通对象、数组、Date、RegExp、URL、URLSearchParams、Map、Set、Headers、ArrayBuffer、类型化数组、Request、Response、ReadableStream、WritableStream。

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

流式传输

在步骤函数中使用 getWritable() 来流式传输数据：

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();

调试

# Check workflow endpoints are reachable
npx workflow health
npx workflow health --port 3001  # Non-default port

# Visual dashboard for runs
npx workflow web
npx workflow web --app-url http://localhost:3001

# CLI inspection (for agents)
npx workflow inspect runs
npx workflow inspect run <run_id>

**提示：**只导入实际使用的工作流 API。未使用的导入可能导致 500 错误。

评论

支持 Markdown