# @cascade-flow/workflow 中文文档

规范地址：https://npmcn.com/package/%40cascade-flow/workflow/

版本：0\.3\.6
npm 元数据更新时间：2026-08-11T22:08:08.008Z
中文译文更新时间：2026-11-09T12:30:51.770Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cascade-flow/workflow
原文对照：https://npmcn.com/package/%40cascade-flow/workflow/?lang=original
项目主页：https://github.com/cascadeflow/cascadeflow#readme
源码仓库：https://github.com/cascadeflow/cascadeflow

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：64.3 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：typescript ^5
- 首次发布：2025-11-19T11:52:01.701Z
- 最新版本发布：2026-08-11T22:08:07.820Z
- 近 30 天下载量：2715（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

工作流程为 CascadeFlow 编写 SDK 并带有类型安全步骤定义助手

## 安装

```sh
npm install @cascade-flow/workflow
```

也可以使用：`pnpm add @cascade-flow/workflow`、`yarn add @cascade-flow/workflow`、`bun add @cascade-flow/workflow`

## README

# @ cascade- flow/ workflow

为 CascadeFlow 编写 SDK 的工作流程 - 为构建工作流程提供类型安全步骤定义帮助和公用设施.

## 安装

```bash
bun add @cascade-flow/workflow
```

## API 参考

### 步骤定义

#### `defineStep(spec)`

不输入输入的工作流程默认步骤定义帮助器 .

```typescript
import { defineStep } from "@cascade-flow/workflow";

export const step = defineStep({
  name: "my-step",
  dependencies: {},
  exportOutput: true,
  fn: async ({ ctx }) => {
    return { result: "value" };
  }
});
```

#### `baseDefineStep<TInput>()`

创建已键入的工厂函数 `defineStep` 函数用于输入的工作流程.

**用法模式 :**

1.  创建特定的工作流程 `defineStep.ts`数字 :

```typescript
// workflows/my-workflow/define-step.ts
import { baseDefineStep } from "@cascade-flow/workflow";
import type { WorkflowInput } from "./input-schema";

export const defineStep = baseDefineStep<WorkflowInput>();
```

2.  用在你的台阶上:

```typescript
// workflows/my-workflow/steps/my-step/step.ts
import { defineStep } from "../../define-step";

export const step = defineStep({
  fn: async ({ ctx }) => {
    // ctx.input is now typed as WorkflowInput!
    const message = ctx.input.message; // Fully typed
    return { processed: message };
  }
});
```

### 跳过和可选依赖

#### `Skip`

故意跳过步骤错误分类 。 跳过步数 :

-   标记为“ 滑动 ” (没有失败)
-   连为依附步骤( 它们也会跳过)
-   不触发重试

```typescript
import { Skip } from "@cascade-flow/workflow";

export const step = defineStep({
  fn: async ({ ctx }) => {
    if (!ctx.input.shouldProcess) {
      throw new Skip("Processing not needed");
    }
    return { result: "processed" };
  }
});
```

**有元数据 :**

```typescript
throw new Skip("Feature flag disabled", {
  flag: "new-processor",
  environment: process.env.NODE_ENV
});
```

#### `optional(step)`

将依赖标记为可选。 可选依赖性 :

-   跳过时不会引起级联跳过
-   将会是 `undefined` 在依赖对象中,如果跳过
-   如果成功完成, 将具有正常输出值

```typescript
import { defineStep, optional } from "@cascade-flow/workflow";
import { step as validation } from "../validation/step.ts";
import { step as enrichment } from "../enrichment/step.ts";

export const step = defineStep({
  dependencies: {
    validation,                      // Required - will cascade skip
    enrichment: optional(enrichment) // Optional - won't cascade skip
  },
  fn: async ({ dependencies }) => {
    // dependencies.validation is guaranteed to exist
    // dependencies.enrichment is StepOutput | undefined
    if (dependencies.enrichment) {
      // Use enrichment data
    } else {
      // Fallback when enrichment was skipped
    }
    return { result: "processed" };
  }
});
```

#### `isOptional(dep)`

检查是否将依赖标记为可选 。 (内部工具)

### 类型

#### `RunnerContext`

每个步骤可用的运行时间背景 :

```typescript
type RunnerContext = {
  runId: string;
  workflow: {
    slug: string; // Workflow directory name
    name: string; // Friendly name from workflow.json
  };
  input?: unknown; // Validated workflow input
  log: (...args: any[]) => void;
};
```

#### `InferStepOutput<T>`

用于从函数签名中推断步骤输出类型的工具类型 .

#### `JSONValue`, (中文(简体) ), `JSONArray`, (中文(简体) ), `JSONObject`, (中文(简体) ), `JSONPrimitive`

代表 JSON 可序列值的类型 。 所有步骤的产出必须是可按顺序排列的.

#### `StepOutput`

别名 `JSONValue` - 步骤返回值的类型限制.

#### `OptionalDependency<T>`

代表可选依赖性包装的类型.

## 步骤配置

这个 `defineStep` 光谱接受 :

```typescript
{
  name?: string;                // Display name (defaults to directory name)
  dependencies?: Record<...>;   // Other steps this step depends on
  exportOutput?: boolean;       // Include in final workflow output
  maxRetries?: number;          // Retry count on failure (default: 0)
  retryDelayMs?: number;        // Delay between retries (default: 0)
  timeoutMs?: number;           // Max execution time (default: 300000ms / 5 min)
  fn: (args) => Promise<Output> | Output;  // Step implementation
}
```

## 组内安排步骤

可通过嵌入式目录结构组织步骤,以更好地组织:

```
workflows/my-workflow/steps/
├── step-1/step.ts                           # Flat step
└── data-processing/                         # Group directory
    ├── extract/
    │   └── fetch-data/step.ts              # Nested step
    └── transform/
        └── normalize/step.ts                # Nested step
```

**关键点 :**

-   团体纯粹是组织性的(没有特殊行为)
-   平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平起平
-   步骤ID使用路径 : `"step-1"` (平面)或 `"data-processing/extract/fetch-data"` (已注销)
-   依赖使用相对进口:

```typescript
// In steps/notifications/send/step.ts
import { step as fetchData } from "../../data-processing/extract/fetch-data/step.ts";

export const step = defineStep({
  dependencies: { fetchData },
  fn: async ({ dependencies }) => {
    // Use data from nested group
    return { sent: true, data: dependencies.fetchData };
  }
});
```

## 实例

### 简单步骤

```typescript
import { defineStep } from "@cascade-flow/workflow";

export const step = defineStep({
  exportOutput: true,
  fn: async () => {
    return { timestamp: Date.now() };
  }
});
```

### 与依附关系同步

```typescript
import { defineStep } from "@cascade-flow/workflow";
import { step as stepA } from "../step-a/step.ts";
import { step as stepB } from "../step-b/step.ts";

export const step = defineStep({
  dependencies: { stepA, stepB },
  fn: async ({ dependencies }) => {
    // Both dependencies are available and fully typed
    const combined = {
      a: dependencies.stepA.value,
      b: dependencies.stepB.result
    };
    return combined;
  }
});
```

### 步入重试逻辑

```typescript
import { defineStep } from "@cascade-flow/workflow";

export const step = defineStep({
  maxRetries: 3,
  retryDelayMs: 1000,
  fn: async () => {
    const response = await fetch("https://api.example.com/data");
    if (!response.ok) throw new Error("API request failed");
    return await response.json();
  }
});
```

### 有条件跳过

```typescript
import { defineStep, Skip } from "@cascade-flow/workflow";

export const step = defineStep({
  fn: async ({ ctx }) => {
    if (!ctx.input.featureEnabled) {
      throw new Skip("Feature disabled");
    }

    // Process when enabled
    return { status: "processed" };
  }
});
```

### 检查站

检查点在一步内节省了中间进展,在重复中持续取得成果:

```typescript
import { defineStep } from "@cascade-flow/workflow";

export const step = defineStep({
  fn: async ({ ctx }) => {
    for (let i = 0; i < items.length; i++) {
      const result = await ctx.checkpoint?.("process-item", async () => {
        return processItem(items[i]);
      });
    }
    return { processed: items.length };
  }
});
```

用于平行检查站 `awaitCheckpoints()` 在错误传播前确保全部完整:

```typescript
import { defineStep, awaitCheckpoints } from "@cascade-flow/workflow";

export const step = defineStep({
  fn: async ({ ctx }) => {
    const [a, b] = await awaitCheckpoints([
      ctx.checkpoint?.("task-a", async () => fetchData()),
      ctx.checkpoint?.("task-b", async () => validate()),
    ]);
    return { a, b };
  }
});
```

## 另见

-   [主要文件](https://npmcn.com/package/CLAUDE.md)
-   [运行软件包](https://npmcn.com/package/%40cascade-flow/runner/CLAUDE.md) - 执行引擎
-   [实例](https://npmcn.com/package/%40cascade-flow/examples/workflows/) - 实例工作流程

## 常见问题

### @cascade-flow/workflow 是什么？

工作流程为 CascadeFlow 编写 SDK 并带有类型安全步骤定义助手

### 如何安装 @cascade-flow/workflow？

在项目目录运行 npm install @cascade-flow/workflow，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cascade-flow/workflow 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cascade-flow/workflow 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cascade-flow/workflow 可以商用吗？

@cascade-flow/workflow 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cascade-flow/workflow 的下载量有多少？

根据 npm 官方下载统计，@cascade-flow/workflow 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,715 次，日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cascade-flow/workflow 还在维护吗？

最新版本 0\.3\.6 发布于 2026/08/12（2 个月前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2025/11/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。