跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 workflow

Workflow

使用Vercel"Workflow SDK"创建可持久,可重复的工作流程. 在构建工作流程时使用,这些工作流程需要幸存重启,暂停外部事件,对失败进行重试,或随着时间的推移协调多步操作. 提到"活活流","可持久功能","可续","活活流 sdk","活活","活活","推","订阅",或"步入"的管弦乐.

4746 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

使用 Vercel 的工作流程 SDK 创建持久、可更新的工作流程

何时用

行为

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:*Critical*: Always use correct `workflow` documentation、Official resources、Quick reference、Prefer step functions to avoid sandbox errors、Workflow sandbox limitations、WorkflowAgent: AI agents in Workflow 5。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。 正文约 779 行,超过规范建议的 500 行,激活时仍会整份载入。

官方 description(原文)

Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.

*Critical*: Always use correct `workflow` documentationOfficial resourcesQuick referencePrefer step functions to avoid sandbox errorsWorkflow sandbox limitationsWorkflowAgent: AI agents in Workflow 5Starting workflows & child workflowsHooks: pause & resume with external eventsSingle eventMultiple events (iterable hooks)Resuming from API routesError handling

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
workflow
description
Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「workflow」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-046435715d3b72c8-%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%A8%8B.html
请存为 .cursor/skills/workflow/SKILL.md 或 .claude/skills/workflow/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/vercel/workflow' --list

npx skills add 'https://github.com/vercel/workflow' --skill 'workflow'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: workflow description: Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration. metadata: author: Vercel Inc. version: '1.16' --- ## *Critical*: Always use correct `workflow` documentation Your knowledge of `workflow` is outdated. The `workflow` documentation outlined below matches the installed version of the Workflow SDK. Follow these instructions before starting on any `workflow`-related tasks: Search the bundled documentation in `node_modules/workflow/docs/`: 1. **Find docs**: `glob "node_modules/workflow/docs/**/*.mdx"` 2. **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.) - `api-reference/workflow-runtime/` - Runtime API (get-world.mdx) and `world/` World SDK (storage.mdx, streams.mdx, queue.mdx) - `api-reference/workflow-observability/` - Hydration and name parsing utilities (hydrate-resource-io.mdx, parse-workflow-name.mdx, etc.) - `ai/`: AI SDK integration docs - `errors/` - Error code documentation Related packages also include bundled docs: - `@ai-sdk/workflow`: `node_modules/ai/docs/` - WorkflowAgent and AI SDK integration - `@workflow/ai`: `node_modules/@workflow/ai/docs/` - deprecated DurableAgent APIs for existing applications - `@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 SDK.** ### Official resources - **Website**: https://workflow-sdk.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"; // Observability & data hydration import { hydrateResourceIO, observabilityRevivers, parseStepName, parseWorkflowName } from "workflow/observability"; // 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 // AI agent (Workflow 5) import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow"; ``` ## Prefer step functions to avoid sandbox errors `"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: "spacexai/grok-4.6", 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. ## Workflow sandbox limitations 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:** Plain `"provider/model"` strings use Vercel AI Gateway. Do not construct a direct provider instance unless the user explicitly needs a provider-only feature. ## WorkflowAgent: AI agents in Workflow 5 Use AI SDK's `WorkflowAgent` for durable agents on Workflow 5. It replaces the deprecated `DurableAgent` API from `@workflow/ai` and checkpoints model calls and step-backed tools. ```typescript import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow"; import { isStepCount, tool } from "ai"; import { getWritable } from "workflow"; import { z } from "zod"; async function lookupData({ query }: { query: string }) { "use step"; // Step functions have full Node.js access return `Results for "${query}"`; } export async function myAgentWorkflow(userMessage: string) { "use workflow"; const agent = new WorkflowAgent({ model: "spacexai/grok-4.6", instructions: "You are a helpful assistant.", tools: { lookupData: tool({ description: "Search for information", inputSchema: z.object({ query: z.string() }), execute: lookupData, }), }, }); const result = await agent.stream({ messages: [{ role: "user", content: userMessage }], writable: getWritable(), stopWhen: isStepCount(10), }); return result.messages; } ``` **Key points:** - A plain `"provider/model"` string routes through Vercel AI Gateway; `spacexai/grok-4.6` is the default model in Workflow examples - `getWritable()` streams durable model-call output; convert it with `createModelCallToUIChunkTransform()` in an HTTP route - Tool `execute` functions that need Node.js/npm access should use `"use step"` - Tool `execute` functions that use workflow primitives (`sleep()`, `createHook()`) should **NOT** use `"use step"` because they run at the workflow level - `stopWhen` limits the number of model calls; the default is to stop when the model stops calling tools - Multi-turn: pass `result.messages` plus new user messages to subsequent `agent.stream()` calls **For more details, check the WorkflowAgent docs in the installed AI SDK package or at https://ai-sdk.dev/v7/docs/agents/workflow-agent.** ## Starting workflows & child workflows Use `start()` to launch workflows from API routes. In Workflow 5, `start()` can also be called directly from a workflow function to spawn a child run; it is step-backed and records a deterministic boundary in the parent's event log. ```typescript import { start } from "workflow/api"; // From an API route; works directly export async function POST() { const run = await start(myWorkflow, [arg1, arg2]); return Response.json({ runId: run.runId }); } // No-args workflow const run = await start(noArgWorkflow); ``` **Starting child workflows from inside a Workflow 5 workflow:** ```typescript import { start } from "workflow/api"; export async function parentWorkflow() { "use workflow"; const childRun = await start(childWorkflow, ["some data"]); await sleep("1h"); return { childRunId: childRun.runId }; } ``` `start()` returns after creating the child run and doesn't wait for it to complete. Use `childRun.returnValue` only when the parent should wait for the child; each `Run` property access or method call inside a workflow is a step. ## Hooks: pause & resume with external events Hooks let workflows wait for external data. Use `createHook()` inside a workflow and `resumeHook()` from API routes. Deterministic tokens are for `createHook()` + `resumeHook()` (server-side) only. `createWebhook()` always generates random tokens, so do not pass a `token` option to `createWebhook()`. ### Single event ```typescript import { createHook } from "workflow"; export async function approvalWorkflow() { "use workflow"; const hook = createHook<{ approved: boolean }>({ token: "approval-123", // deterministic token for external systems }); const result = await hook; // Workflow suspends here return result.approved; } ``` ### Multiple events (iterable hooks) Hooks implement `AsyncIterable`. Use `for await...of` to receive multiple events: ```typescript import { createHook } from "workflow"; export async function chatWorkflow(channelId: string) { "use workflow"; const hook = createHook<{ text: string; done?: boolean }>({ token: `chat-${channelId}`, }); for await (const event of hook) { await processMessage(event.text); if (event.done) break; } } ``` Each `resumeHook(token, payload)` call delivers the next value to the loop. ### Resuming from API routes ```typescript import { resumeHook } from "workflow/api"; export async function POST(req: Request) { const { token, data } = await req.json(); await resumeHook(token, data); return new Response("ok"); } ``` ## Error handling Use `FatalError` for permanent failures (no retry), `RetryableError` for transient failures: ```typescript import { FatalError, RetryableError } from "workflow"; if (res.status === 429) { throw new RetryableError("Rate limited", { retryAfter: "5m" }); } if (res.status >= 400 && res.status < 500) { throw new FatalError(`Client error: ${res.status}`); } ``` ## Serialization All data passed to/from workflows and steps must be serializable. **Supported built-in 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, Symbols, WeakMap/WeakSet. Pass data, not callbacks. ### Custom class serialization Class instances **can** be serialized across workflow/step boundaries by implementing the `@workflow/serde` protocol. This is essential when a class has instance methods with `"use step"` or when you want to pass class instances between steps. **Install:** `@workflow/serde` must be a dependency of the package containing the class. **Pattern:** Add two static methods inside the class body using computed property syntax: ```typescript import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde"; export class Point { x: number; y: number; constructor(x: number, y: number) { this.x = x; this.y = y; } // Serialize: return plain data (must be devalue-compatible types only) static [WORKFLOW_SERIALIZE](instance: Point) { return { x: instance.x, y: instance.y }; } // Deserialize: reconstruct from plain data static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) { return new Point(data.x, data.y); } async computeDistance(other: Point) { "use step"; return Math.sqrt((this.x - other.x) ** 2 + (this.y - other.y) ** 2); } } ``` **Critical rules:** 1. **Define serde methods INSIDE the class body** as static methods with computed property syntax (`static [WORKFLOW_SERIALIZE](...)`). The SWC plugin detects them by scanning the class. Do NOT assign them externally (e.g., `(MyClass as any)[WORKFLOW_SERIALIZE] = ...`) -- the compiler will not detect this. 2. **Serde methods must return only devalue-compatible types** (plain objects, arrays, primitives, Date, Map, Set, Uint8Array, etc.). No functions, no class instances, no Node.js-specific objects. 3. **Add `"use step"` to Node.js-dependent instance methods.** The SWC plugin strips `"use step"` method bodies from the workflow bundle. This is how you keep Node.js imports (fs, crypto, child_process, etc.) out of the workflow sandbox. The class shell with its serde methods remains in the workflow bundle; only the step method bodies are removed. 4. **Do NOT manually register classes.** The SWC plugin automatically generates registration code (an IIFE that sets `classId` and adds the class to the global registry). Manual calls to `registerSerializationClass()` are unnecessary and error-prone. 5. **Do NOT use dynamic imports to work around sandbox restrictions.** If a class method needs Node.js APIs, the correct solution is `"use step"`, not `/* @vite-ignore */ import(...)`. **When serde works well:** Pure data classes, domain models, configuration objects, and classes where Node.js-dependent methods can be marked with `"use step"`. **When to avoid serde:** If a class is fundamentally inseparable from Node.js APIs (every method needs `fs`, `net`, etc.) and cannot meaningfully exist as a shell in the workflow sandbox, keep it entirely in step functions and pass plain data objects across boundaries instead. ### Validating serde compliance Use these tools to verify classes are correctly set up: - **`workflow transform --check-serde`** -- Shows the SWC transform output for a file and checks if serde classes are compliant (no Node.js imports remaining in the workflow bundle). - **`workflow validate`** -- Scans all workflow files and reports serde compliance issues. Use `--json` for machine-readable output. - **SWC Playground** -- The web playground at `workbench/swc-playground` shows a Serde Analysis panel when serde patterns are detected. - **Build-time warnings** -- The builder automatically warns when serde classes have Node.js built-in imports remaining in the workflow bundle. ## Streaming Use `getWritable()` to stream data from workflows. `getWritable()` can be called in **both** workflow and step contexts, but you **cannot interact with the stream** (call `getWriter()`, `write()`, `close()`) directly in a workflow function. The stream must be passed to step functions for actual I/O, or steps can call `getWritable()` themselves. **Get the stream in a workflow, pass it to a step:** ```typescript import { getWritable } from "workflow"; export async function myWorkflow() { "use workflow"; const writable = getWritable(); await writeData(writable, "hello world"); } async function writeData(writable: WritableStream, chunk: string) { "use step"; const writer = writable.getWriter(); try { await writer.write(chunk); } finally { writer.releaseLock(); } } ``` **Call `getWritable()` directly inside a step (no need to pass it):** ```typescript import { getWritable } from "workflow"; async function streamData(chunk: string) { "use step"; const writer = getWritable().getWriter(); try { await writer.write(chunk); } finally { writer.releaseLock(); } } ``` ### Namespaced streams Use `getWritable({ namespace: 'name' })` to create multiple independent streams for different types of data. This is useful for separating logs from primary output, different log levels, agent outputs, metrics, or any distinct data channels. Long-running workflows benefit from namespaced streams because you can replay only the important events (e.g., final results) while keeping verbose logs in a separate stream. **Example: Log levels and agent output separation:** ```typescript import { getWritable } from "workflow"; type LogEntry = { level: "debug" | "info" | "warn" | "error"; message: string; timestamp: number }; type AgentOutput = { type: "thought" | "action" | "result"; content: string }; async function logDebug(message: string) { "use step"; const writer = getWritable({ namespace: "logs:debug" }).getWriter(); try { await writer.write({ level: "debug", message, timestamp: Date.now() }); } finally { writer.releaseLock(); } } async function logInfo(message: string) { "use step"; const writer = getWritable({ namespace: "logs:info" }).getWriter(); try { await writer.write({ level: "info", message, timestamp: Date.now() }); } finally { writer.releaseLock(); } } async function emitAgentThought(thought: string) { "use step"; const writer = getWritable({ namespace: "agent:thoughts" }).getWriter(); try { await writer.write({ type: "thought", content: thought }); } finally { writer.releaseLock(); } } async function emitAgentResult(result: string) { "use step"; // Important results go to the default stream for replay const writer = getWritable().getWriter(); try { await writer.write({ type: "result", content: result }); } finally { writer.releaseLock(); } } export async function agentWorkflow(task: string) { "use workflow"; await logInfo(`Starting task: ${task}`); await logDebug("Initializing agent context"); await emitAgentThought("Analyzing the task requirements..."); // ... agent processing ... await emitAgentResult("Task completed successfully"); await logInfo("Workflow finished"); } ``` **Consuming namespaced streams:** ```typescript import { start, getRun } from "workflow/api"; import { agentWorkflow } from "./workflows/agent"; export async function POST(request: Request) { const run = await start(agentWorkflow, ["process data"]); // Access specific streams by namespace const results = run.getReadable({ namespace: undefined }); // Default stream (important results) const infoLogs = run.getReadable({ namespace: "logs:info" }); const debugLogs = run.getReadable({ namespace: "logs:debug" }); const thoughts = run.getReadable({ namespace: "agent:thoughts" }); // Return only important results for most clients return new Response(results, { headers: { "Content-Type": "application/json" } }); } // Resume from a specific point (useful for long sessions) export async function GET(request: Request) { const { searchParams } = new URL(request.url); const runId = searchParams.get("runId")!; const startIndex = parseInt(searchParams.get("startIndex") || "0", 10); const run = getRun(runId); // Resume only the important stream, skip verbose debug logs const stream = run.getReadable({ startIndex }); return new Response(stream); } ``` For long-running sessions (50+ minutes), namespaced streams help manage replay performance. Put verbose/debug output in separate namespaces so you can replay only the important events. ## Debugging ```bash # 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 # CLI inspection (use --json for machine-readable output, --help for full usage) npx workflow inspect runs npx workflow inspect run # For Vercel-deployed projects, specify backend and project npx workflow inspect runs --backend vercel --project --team npx workflow inspect run --backend vercel --project --team # Open Vercel dashboard in browser for a specific run npx workflow inspect run --web npx workflow web --backend vercel --project --team # Cancel a running workflow npx workflow cancel npx workflow cancel --backend vercel --project --team # --env defaults to "production"; use --env preview for preview deployments ``` ### Deep-linking to a run (share a URL, no browser) Use `--url` to **print** the dashboard deep link and exit. No browser opens, and no local server starts. This is the right tool when you need to hand a user a clickable link (PR comment, Slack message, debugging summary) rather than open a UI. (`--web` opens the dashboard; `--url` only prints the link.) ```bash # Vercel run: prints the Vercel dashboard URL for the run npx workflow inspect run --backend vercel --project --team --url npx workflow web --backend vercel --project --team --env preview --url # Local run: prints the local web UI deep link npx workflow inspect run --url # Machine-readable: --url --json prints { "url": "..." } to stdout npx workflow inspect run --backend vercel --url --json ``` URL formats produced: - **Vercel:** `https://vercel.com///workflows/runs/?environment=` (`--env` selects the environment; defaults to `production`. Resolving the team slug requires being logged in via `vercel login` with the project linked.) - **Local:** `http://localhost:?resource=run&id=` (port defaults to `3456`; the link works while the `npx workflow web` server is running). stdout contains **only** the URL (or the JSON object). All other output goes to stderr, so you can capture it directly, for example, `URL=$(npx workflow web --backend vercel --url)`. **Debugging tips:** - Use `--json` (`-j`) on any command for machine-readable output - Use `--web` to open the Vercel Observability dashboard in your browser or `--url` to print the deep link - Use `--help` on any command for full usage details - Only import workflow APIs you actually use. Unused imports can cause 500 errors. ## Testing workflows Workflow SDK provides a Vitest plugin for testing workflows in-process without a running server. **Unit testing steps:** Steps are functions; without the compiler, `"use step"` is a no-op. Test them directly: ```typescript import { describe, it, expect } from "vitest"; import { createUser } from "./user-signup"; describe("createUser step", () => { it("should create a user", async () => { const user = await createUser("[email protected]"); expect(user.email).toBe("[email protected]"); }); }); ``` **Integration testing:** Use `@workflow/vitest` for workflows using `sleep()`, hooks, webhooks, or retries: ```typescript // vitest.integration.config.ts import { defineConfig } from "vitest/config"; import { workflow } from "@workflow/vitest"; export default defineConfig({ plugins: [workflow()], test: { include: ["**/*.integration.test.ts"], testTimeout: 60_000, }, }); ``` ```typescript // approval.integration.test.ts import { describe, it, expect } from "vitest"; import { start, getRun, resumeHook } from "workflow/api"; import { waitForHook, waitForSleep } from "@workflow/vitest"; import { approvalWorkflow } from "./approval"; describe("approvalWorkflow", () => { it("should publish when approved", async () => { const run = await start(approvalWorkflow, ["doc-123"]); // Wait for the hook, then resume it await waitForHook(run, { token: "approval:doc-123" }); await resumeHook("approval:doc-123", { approved: true, reviewer: "alice" }); // Wait for sleep, then wake it up const sleepId = await waitForSleep(run); await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); const result = await run.returnValue; expect(result).toEqual({ status: "published", reviewer: "alice" }); }); }); ``` **Testing webhooks:** Use `resumeWebhook()` with a `Request` object. No HTTP server is needed: ```typescript import { start, resumeWebhook } from "workflow/api"; import { waitForHook } from "@workflow/vitest"; const run = await start(ingestWorkflow, ["ep-1"]); const hook = await waitForHook(run); // Discovers the random webhook token await resumeWebhook(hook.token, new Request("https://example.com/webhook", { method: "POST", body: JSON.stringify({ event: "order.created" }), })); ``` **Key APIs:** - `start()`: Trigger a workflow - `run.returnValue`: Await workflow completion - `waitForHook(run, { token? })` / `waitForSleep(run)`: Wait for workflow to reach a pause point - `resumeHook(token, data)` / `resumeWebhook(token, request)`: Resume paused workflows - `getRun(runId).wakeUp({ correlationIds })`: Skip `sleep()` calls **Best practices:** - Keep unit tests (no plugin) and integration tests (`workflow()` plugin) in separate configs - Use deterministic hook tokens based on test data for easier resumption - Set generous `testTimeout` values because workflows may run longer than typical unit tests - `vi.mock()` does **not** work in integration tests because step dependencies are bundled by esbuild ## Observability & World SDK Use `await getWorld()` to build observability dashboards, admin panels, and inspect workflow state. `getWorld()` is asynchronous and returns `Promise` (dynamic import / env-based setup). **Key imports:** ```typescript import { getWorld } from "workflow/runtime"; import { hydrateResourceIO, observabilityRevivers, parseStepName, parseWorkflowName } from "workflow/observability"; ``` **Key docs** (grep `node_modules/workflow/docs/` for full details): - `api-reference/workflow-runtime/world/storage.mdx`: Events, runs, steps, and hooks (events are the source of truth; others are materialized views) - `api-reference/workflow-observability/`: Hydration and name parsing ### World SDK method signatures ⚠️ Pagination is nested: `{ pagination: { cursor } }`, NOT `{ cursor }` directly. ```typescript const world = await getWorld(); // Runs const { data, cursor } = await world.runs.list({ pagination: { cursor }, resolveData: 'all' | 'none' }); const run = await world.runs.get(runId, { resolveData: 'all' | 'none' }); // Cancel via event creation (no cancel() method on runs) await world.events.create(runId, { eventType: 'run_cancelled' }); // Steps: runId is top-level, NOT inside pagination const { data, cursor } = await world.steps.list({ runId, pagination: { cursor }, resolveData: 'all' | 'none' }); const step = await world.steps.get(runId, stepId, { resolveData: 'all' | 'none' }); // Events const { data, cursor } = await world.events.list({ runId, pagination: { cursor } }); await world.events.create(runId, { eventType: 'run_cancelled' }); // Hooks const hook = await world.hooks.get(hookId); const hook = await world.hooks.getByToken(token); // Streams (methods on world.streams) await world.streams.write(runId, name, chunk); await world.streams.writeMulti?.(runId, name, chunks); const readable = await world.streams.get(runId, name, startIndex); await world.streams.close(runId, name); const streamNames = await world.streams.list(runId); const chunks = await world.streams.getChunks(runId, name, { limit, cursor }); const info = await world.streams.getInfo(runId, name); // Queue (methods live directly on world as internal SDK infrastructure) await world.queue(queueName, payload, opts); const deploymentId = await world.getDeploymentId(); ``` ### `resolveData` parameter Controls whether input/output data is **included** in the response. Accepts `'all'` (default) or `'none'`. **IMPORTANT**: Even with `'all'`, data is still devalue-serialized. You MUST call `hydrateResourceIO()` to get usable JS values. - **Use `'none'`** for status polling, progress dashboards, run listings - **Use `'all'`** (or omit) when you need to inspect actual step I/O data, then **always hydrate** ```typescript // Lightweight status check with no I/O loaded const run = await world.runs.get(runId, { resolveData: 'none' }); console.log(run.status); // 'running' | 'completed' | 'failed' | 'cancelled' // Full inspection: resolveData includes data, hydrateResourceIO deserializes it const step = await world.steps.get(runId, stepId); // defaults to 'all' const hydrated = hydrateResourceIO(step, observabilityRevivers); ``` > **Common mistake**: Checking `step.input !== undefined` after `resolveData: 'all'` and assuming > the data is ready to use. The data exists but is serialized, so always hydrate first. ### Data hydration (devalue format) Step I/O is serialized via [devalue](https://github.com/Rich-Harris/devalue) with a 4-byte format prefix (`devl`). Without hydration, `input`/`output` are Uint8Array-like objects with numeric keys: `{"0":100,"1":101,"2":118,"3":108,...}` contains values that are NOT usable without hydration. **Always hydrate before using I/O data:** ```typescript import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; const { data: steps } = await world.steps.list({ runId, resolveData: 'all' }); const hydrated = steps.map(s => hydrateResourceIO(s, observabilityRevivers)); // hydrated[0].input → [123, 2] (actual function arguments) // hydrated[0].output → 125 (actual return value) ``` `hydrateResourceIO` works on both `Step` and `WorkflowRun` objects. For encrypted workflows, use `getEncryptionKeyForRun()` + `hydrateResourceIOWithKey()`. ### Name parsing `parseWorkflowName()`, `parseStepName()`, and `parseClassName()` return `{ shortName: string, moduleSpecifier: string } | null`. Always use optional chaining: ```typescript const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // parsed?.shortName → "processOrder" // parsed?.moduleSpecifier → "./src/workflows/order" // ⚠️ Returns null if format doesn't match ``` ### Event types Events are the append-only source of truth. Runs/Steps/Hooks are materialized views. | Category | Types | |----------|-------| | Run | `run_created`, `run_started`, `run_completed`, `run_failed`, `run_cancelled` | | Step | `step_created`, `step_started`, `step_completed`, `step_failed`, `step_retrying` | | Hook | `hook_created`, `hook_received`, `hook_disposed`, `hook_conflict` | | Wait | `wait_created`, `wait_completed` | ## Error handling patterns Three error strategies for different failure modes: | Error Type | Use When | Behavior | |------------|----------|----------| | `FatalError` | Permanent failure (bad input, auth denied) | Terminates workflow immediately, no retry | | `RetryableError` | Transient failure (rate limit, timeout) | Retries with optional `retryAfter` delay | | `Promise.allSettled` | Parallel steps with mixed criticality | Continues even if some steps fail | ```typescript import { FatalError, RetryableError } from "workflow"; // Permanent failure, so the workflow terminates throw new FatalError("Invalid input: missing required field"); // Transient failure, so it will retry throw new RetryableError("API rate limited", { retryAfter: "5m" }); // Mixed criticality parallel execution const results = await Promise.allSettled([ criticalStep(data), // Must succeed optionalStep(data), // OK to fail enrichmentStep(data), // OK to fail ]); const [critical, optional, enrichment] = results; if (critical.status === "rejected") throw new FatalError(critical.reason); ```

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…