@baipeng139/72flow-nodejs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 我奋斗去了
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# 72flow-nodejs
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
+
+72flow 工作流编排引擎的 **Node.js / TypeScript** 实现，支持在浏览器和 Node.js 双环境中运行，与 Java 后端引擎保持行为一致。
+
+---
+
+## 特性
+
+- ✅ **多节点类型**：START、END、SCRIPT、DECISION、CONDITION、PARALLEL、LOOP、API、LLM
+- ✅ **浏览器 & Node.js 双运行时**：无需修改代码，同一套引擎在两端行为一致
+- ✅ **并行分支**：`PARALLEL` 节点自动并发触发分支，汇聚后继续执行
+- ✅ **条件分支**：`DECISION` / `CONDITION` 节点支持 JavaScript 表达式路由
+- ✅ **循环执行**：`LOOP` 节点支持数组/次数迭代，内联同步执行循环体
+- ✅ **LLM 集成**：内置 OpenAI / Qwen / Claude / Ollama 兼容接口
+- ✅ **事件系统**：引擎发射 `node.starting`、`node.completed`、`node.failed` 等事件
+- ✅ **X6 格式解析**：内置 `@antv/x6` 画布 JSON 格式解析器，直接对接前端图形编辑器
+- ✅ **ESM + CJS 双格式产物**：兼容各种打包场景
+
+---
+
+## 安装
+
+```bash
+npm install 72flow-nodejs
+```
+
+> 需要 Node.js **18+**（使用原生 `fetch` 和 `EventTarget`）
+
+---
+
+## 快速开始
+
+### 基础线性流程
+
+```typescript
+import { FlowEngine, FlowDefinition, NodeType } from '72flow-nodejs';
+
+const definition: FlowDefinition = {
+  id: 'hello-world',
+  name: 'Hello World',
+  version: '1.0',
+  nodes: [
+    { id: 'start',  type: NodeType.START },
+    { id: 'script', type: NodeType.SCRIPT, config: { script: 'greeting = "Hello, " + name' } },
+    { id: 'end',    type: NodeType.END },
+  ],
+  edges: [
+    { id: 'e1', from: 'start',  to: 'script' },
+    { id: 'e2', from: 'script', to: 'end' },
+  ],
+};
+
+const engine = new FlowEngine();
+const result = await engine.execute(definition, { name: 'World' });
+
+console.log(result.status);           // 'COMPLETED'
+console.log(result.variables.greeting); // 'Hello, World'
+```
+
+### 条件分支（DECISION）
+
+```typescript
+const definition: FlowDefinition = {
+  id: 'branch-demo',
+  name: '条件分支示例',
+  version: '1.0',
+  nodes: [
+    { id: 'start',    type: NodeType.START },
+    { id: 'decision', type: NodeType.DECISION, config: { decision: { scriptCode: 'score >= 60 ? "pass" : "fail"' } } },
+    { id: 'pass',     type: NodeType.SCRIPT, config: { script: 'result = "通过"' } },
+    { id: 'fail',     type: NodeType.SCRIPT, config: { script: 'result = "未通过"' } },
+    { id: 'end',      type: NodeType.END },
+  ],
+  edges: [
+    { id: 'e1', from: 'start',    to: 'decision' },
+    { id: 'e2', from: 'decision', to: 'pass', condition: 'pass' },
+    { id: 'e3', from: 'decision', to: 'fail', condition: 'fail' },
+    { id: 'e4', from: 'pass',     to: 'end' },
+    { id: 'e5', from: 'fail',     to: 'end' },
+  ],
+};
+
+const result = await new FlowEngine().execute(definition, { score: 80 });
+console.log(result.variables.result); // '通过'
+```
+
+### 并行分支（PARALLEL）
+
+```typescript
+const definition: FlowDefinition = {
+  id: 'parallel-demo',
+  name: '并行流程示例',
+  version: '1.0',
+  nodes: [
+    { id: 'start',   type: NodeType.START },
+    { id: 'par',     type: NodeType.PARALLEL },
+    { id: 'taskA',   type: NodeType.SCRIPT, config: { script: 'a = 1' } },
+    { id: 'taskB',   type: NodeType.SCRIPT, config: { script: 'b = 2' } },
+    { id: 'join',    type: NodeType.SCRIPT, config: { script: 'sum = a + b' } },
+    { id: 'end',     type: NodeType.END },
+  ],
+  edges: [
+    { id: 'e1', from: 'start',  to: 'par' },
+    { id: 'e2', from: 'par',    to: 'taskA' },
+    { id: 'e3', from: 'par',    to: 'taskB' },
+    { id: 'e4', from: 'taskA',  to: 'join' },
+    { id: 'e5', from: 'taskB',  to: 'join' },
+    { id: 'e6', from: 'join',   to: 'end' },
+  ],
+  convergeMap: { par: 'join' }, // 声明汇聚关系
+};
+
+const result = await new FlowEngine().execute(definition, {});
+console.log(result.variables.sum); // 3
+```
+
+### 监听引擎事件
+
+```typescript
+const engine = new FlowEngine();
+
+engine.on('node.starting',   ({ nodeId }) => console.log(`▶ 开始: ${nodeId}`));
+engine.on('node.completed',  ({ nodeId, output }) => console.log(`✓ 完成: ${nodeId}`, output));
+engine.on('node.failed',     ({ nodeId, error }) => console.error(`✗ 失败: ${nodeId}`, error));
+
+await engine.execute(definition, variables);
+```
+
+### 解析 X6 画布 JSON
+
+```typescript
+import { parseX6 } from '72flow-nodejs';
+
+// x6Json 是 @antv/x6 画布导出的 JSON 对象
+const flowDefinition = parseX6(x6Json);
+const result = await new FlowEngine().execute(flowDefinition, {});
+```
+
+---
+
+## 节点类型说明
+
+| 节点类型    | 说明                                             | 关键配置字段                                     |
+|-------------|--------------------------------------------------|-------------------------------------------------|
+| `START`     | 流程起始节点                                     | —                                               |
+| `END`       | 流程结束节点，输出所有变量                        | —                                               |
+| `SCRIPT`    | 执行 JavaScript 脚本，可读写流程变量              | `config.script`（字符串）                        |
+| `DECISION`  | 运行脚本计算返回值，与出边 `condition` 字段匹配   | `config.decision.scriptCode`                    |
+| `CONDITION` | 对每条出边独立求值布尔表达式                       | `config.condition.scriptCode`                   |
+| `PARALLEL`  | 并发触发所有出边分支，需配合 `convergeMap` 使用   | `convergeMap` (流程定义级)                       |
+| `LOOP`      | 数组/次数迭代，内联执行循环体                     | `config.loop.loopType` / `itemsExpr` / `itemVar`|
+| `API`       | 调用 HTTP 接口，结果写入 `apiResponse` 变量       | `config.api.url` / `method` / `headers` / `body`|
+| `LLM`       | 调用 OpenAI 兼容大语言模型接口                    | `config.llm.provider` / `modelName` / `userPrompt` |
+
+---
+
+## 流程变量
+
+- 引擎所有节点**共享同一个变量空间**（`FlowContext.variables`）
+- `SCRIPT` 节点通过 `with(vars)` 语法直接读写变量，**新增的变量也会生效**
+- `API` 节点完成后，响应体自动写入 `variables.apiResponse`
+- `LLM` 节点完成后，模型回复写入 `variables.llmResponse`
+- `LOOP` 节点每轮迭代将当前元素写入 `item`（可自定义 `itemVar`），索引写入 `index`（可自定义 `indexVar`）
+
+---
+
+## 错误处理
+
+节点可在 `config.error.mode` 中指定错误处理策略：
+
+| 值              | 行为                                |
+|----------------|-------------------------------------|
+| `"throw"`      | 抛出异常，终止流程（默认）            |
+| `"fail"`       | 标记流程失败，终止流程               |
+| `"<nodeId>"`   | 跳转到指定节点 ID 继续执行（兜底逻辑）|
+
+---
+
+## API 参考
+
+### `FlowEngine`
+
+```typescript
+class FlowEngine {
+  // 执行流程定义，返回执行结果
+  execute(definition: FlowDefinition, variables?: Record<string, any>): Promise<FlowResult>;
+
+  // 事件监听（继承自 SimpleEmitter）
+  on(event: string, handler: Function): this;
+  once(event: string, handler: Function): this;
+  off(event: string, handler: Function): this;
+}
+```
+
+### `FlowResult`
+
+```typescript
+interface FlowResult {
+  executionId: string;            // 本次执行唯一 ID
+  status: NodeStatus;             // COMPLETED | FAILED | CANCELLED
+  output?: any;                   // END 节点的输出
+  error?: string;                 // 错误信息（失败时）
+  duration: number;               // 执行耗时（ms）
+  startTime: number;              // 开始时间戳（ms）
+  endTime?: number;               // 结束时间戳（ms）
+  variables: Record<string, any>; // 最终变量快照
+  traces: TraceRecord[];          // 各节点执行轨迹
+}
+```
+
+### `parseX6(x6Json)`
+
+将 `@antv/x6` 导出的画布 JSON 转为 `FlowDefinition`，自动规范化节点类型、loop 配置字段等。
+
+---
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试（watch 模式）
+npm run dev
+
+# 单次运行所有测试
+npm test
+
+# 构建 ESM + CJS 产物
+npm run build
+```
+
+### 项目结构
+
+```
+src/
+├── index.ts              # 公开导出入口
+├── types/
+│   └── models.ts         # 核心类型定义（FlowDefinition、NodeDef、FlowResult 等）
+├── core/
+│   ├── flow-engine.ts    # 流程引擎调度核心
+│   ├── flow-context.ts   # 执行上下文（变量、状态、轨迹）
+│   └── flow-engine.test.ts # 集成测试
+├── executors/
+│   └── factory.ts        # 各类型节点执行器（Start/End/Script/Decision/Parallel/Loop/API/LLM）
+├── parser/
+│   └── x6-parser.ts      # X6 画布 JSON 解析器
+└── support/
+    └── logger.ts         # 轻量日志工具
+```
+
+---
+
+## 与 Java 引擎的差异
+
+| 能力              | Node.js 引擎  | Java 引擎      |
+|-------------------|--------------|----------------|
+| SCRIPT 语言        | **JavaScript only** | JavaScript + Groovy |
+| API 跨域（浏览器）  | 需 Vite `/api-proxy` 代理 | 无限制 |
+| 运行环境           | Node.js 18+ / 现代浏览器 | JVM 11+ |
+
+> **注意**：在浏览器中调用 `API` 节点时，需确保 Vite dev server 已配置 `/api-proxy` 代理路由，以规避 CORS 限制。
+
+---
+
+## License
+
+[MIT](./LICENSE)