FlowKit

v1.0.0 · Node.js >=22.13.0 · 专有授权 · 私有 GitHub Packages

用 JavaScript / TypeScript DSL 定义工作流，静态检查流程结构，生成可读 JavaScript 与 Mermaid，并通过你提供的宿主 Runtime 执行 Agent、业务动作、验证和人工审批。

公开文档 · 工作流示例 · 内部示例源码

适用场景

适合需要条件分支、并行处理、校验重试、循环修复或人工决策的多步骤任务。模型调用、业务接口、Schema 校验器及人工交互由宿主提供。FlowKit 不内置持久化审批服务或跨进程恢复；并行分支共享状态，any 汇合不会取消其他分支。

运营定位

FlowKit 是 私有、内部部署的商业产品基础设施。未来可通过 MCP 服务、托管 API 或付费工作流设计产品向客户提供能力，不向客户分发 FlowKit npm 安装包或源码。目前这些商业服务属于规划方向，尚未作为本仓库的现成服务发布。客户使用服务和取得生成工作流的权利，应由单独的服务条款约定。

内部安装（仅维护者）

以下命令仅供拥有仓库或内部部署权限的维护者使用；公开文档读者和未来付费客户无需安装 FlowKit。先为 GitHub Packages 配置 @devcodex-labs Registry，使用具备 read:packages 权限的 GitHub PAT (classic)，由环境变量 NODE_AUTH_TOKEN 提供，不把真实令牌提交到仓库。创建项目中的 .npmrc：

@devcodex-labs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

然后逐行执行（PowerShell / Bash 均可）：

npm init -y
npm pkg set type=module
npm install --save-exact @devcodex-labs/flowkit@1.0.0

内部开发示例：第一个工作流

以下是供内部开发与审查使用的最小示例，公开读者可以阅读其流程，但不获得安装包或源码访问权。示例不需要模型密钥，也不依赖源码仓库。创建以下两个文件。

sample.workflow.js

import { defineWorkflow, action, terminal } from '@devcodex-labs/flowkit/dsl';

export default defineWorkflow({
  id: 'hello-flowkit', version: '1.0.0', name: '第一个工作流',
  nodes: [
    action('greet', { name: '生成问候', action: 'greet', writes: ['message'], next: 'done' }),
    terminal('done', { name: '完成', status: 'succeeded' }),
  ],
});

host.mjs

import { run, isControlSignal } from '@devcodex-labs/flowkit';
import { fileURLToPath } from 'node:url';

const runtime = {
  isControlSignal,
  async runAction(action, name, ctx) {
    if (action !== 'greet') throw new Error(`未实现的动作：${action}`);
    ctx.state.message = `你好，${ctx.state.name}！`;
  },
};
const result = await run(fileURLToPath(new URL('./sample.workflow.js', import.meta.url)), runtime, { name: 'FlowKit' });
console.log(JSON.stringify(result, null, 2));

在这两个文件所在目录执行：

npx --no-install flowkit compile sample.workflow.js
npx --no-install flowkit check sample.workflow.js
node host.mjs

编译生成 sample.compiled.mjs 和 sample.mmd；检查成功退出0，通常无输出。运行结果：

{
  "status": "succeeded",
  "terminal": "done",
  "state": {
    "name": "FlowKit",
    "message": "你好，FlowKit！"
  }
}

writes 是静态声明，实际赋值由 runAction 完成。check 不创建产物；文件缺失时仍可能成功，因此要检查编译生成的文件。完整解释、失败复原及后续学习路径见快速开始。

公开接口

能力图谱可选适配由 @devcodex-labs/flowkit/capability-graph 导出 flowkitProvider 和 createCapabilityGraphActionAdapter，它不内置模型或执行引擎；参见能力声明与宿主消费示例。

SDK 根入口提供 run、compile、compileSource、check、evalWhen、isControlSignal。DSL 从 @devcodex-labs/flowkit/dsl 导入。CLI 提供 compile / check；运行流程使用 SDK。避免导入包内私有路径。

工作流源文件必须以 .workflow.js 或 .workflow.ts 结尾。AOT 部署保留原始源码、编译产物及所需 Skill；一致性校验不能替代对宿主代码和产物来源的信任。

内部开发与许可

从仓库开发：npm ci，再运行 npm run verify。文档站位于 website/，其开发环境为 Node >=24，依赖与 SDK 分开安装。贡献入口见贡献说明。

FlowKit 是仅供内部部署的私有专有软件，公开文档并不授予安装权；当前使用 专有授权协议，Copyright (c) 2026 devcodex-labs。仓库当前版本为 v1.0.0，实际包发行以 GitHub Packages 记录为准；更新记录说明能力与限制。