你的 Agent 流程还是一团黑盒？这个开源引擎把每一步都画成了可回放的 DAG 图

你的 Agent 流程还是一团黑盒？

摘要：XFlow 是一个零外部依赖的 DAG 流程执行引擎，专为编排多 Agent LLM 工作流设计。33 种内置节点覆盖 LLM 调用、记忆系统、智能路由、代码工程等场景，支持串行/并行/条件分支/图内循环四种拓扑，3 行代码接入可视化监控，每一步输入输出和耗时实时可查。最大的不同 ：节点协议极简（execute + guard 两个方法），你可以用 ChatGPT/Claude 直接生成新节点，无限扩展。项目仅依赖 Node.js 内置模块，拷贝 core/ + nodes/ 即可嵌入任何项目。

痛点：Agent 框架越来越重了

AI Agent 框架迎来了爆发式增长。但使用下来，有几个共同的感受：

依赖地狱 ------ npm install 动辄几百个包，node_modules 黑洞比项目代码还大
概念膨胀 ------ Chain、Agent、Tool、Memory、Retriever......层层抽象，光理解概念就要半天
黑盒调试 ------ 流程跑起来后，中间每一步的输入输出全靠 console.log 猜
侵入性强 ------ 想给现有项目加个 Agent？先重构一半代码适配框架

我想要的很简单：一张图描述流程，从任意节点触发，每一步可视化，零依赖扔进项目就能跑。

于是写了 XFlow。

🏠 开源地址：gitee.com/xxt22866219...

一、XFlow 是什么

XFlow 是一个基于 DAG（有向无环图）的轻量级流程执行引擎，专为编排多 Agent LLM 工作流设计。

核心约束：零外部依赖 ，仅使用 Node.js 内置模块。这意味着不用 npm install，把 core/ + nodes/ 拷贝到任何 Node.js 项目里就能直接使用。

支持四种经典拓扑：

text 复制代码

串行:    A → B → C → D

并行:    A ─┬─→ B ─┬─→ D
             └─→ C ─┘

条件:    A → B(guard) → C     guard 返回 false 则 C 被跳过

循环:    图内回边，dispatch → execute → verify →（回边）→ dispatch

二、五个核心特点

2.1 33 种内置节点

所有节点遵循统一的 execute + guard 双协议：

| 方法 | 签名 | 职责 |
|-----------|-----------------------------------|--------------------------------|----------------------------------------|
| execute | (callback, params, ctx) => void | 主逻辑，完成后必须调用 callback(params) |
| guard | `(next, params, ctx) => void | false` | 守卫：return false 拦截，next(params) 放行 |

内置节点覆盖了 Agent 工作流的主要场景：

类别	节点	说明
LLM 调用	`deepseek`、`llm-json`	API 调用 + 结构化 JSON 输出 + 字段注入
记忆系统	`memory-full`、`memory-short`、`memory-summary`、`memory-search`、`memory-agent`、`recall-agent`	全量/滑动窗口/间隔摘要/语义检索/Agent 决策，共 6 种
智能路由	`router-agent`、`mind-router`	专家路由 + 基于 SQLite 思维库的思维模式路由
代码工程	`code-exec`、`code-verify`、`file-read`、`file-write`	代码执行、自动验证、文件读写
流程控制	`flow`（子流程）、`scheduler`（定时调度）、`env-context`	流程嵌套、定时触发、环境注入
项目管理	`project-scan`、`knowledge-memory`、`growth-memory`	项目画像扫描、Agent 知识规范、行为偏好学习

更关键的是，创建新节点极其简单 ------一个 ES 类实现 execute + guard 两个方法，再到 NodeTypes.js 注册一行即可。标准模板就十几行：

javascript 复制代码

// nodes/my-node/NodeClass.js
export default class MyNode {
    execute(callback, params, ctx) {
        // 你的核心逻辑
        callback({ ...params, result: 'done' });
    }
    guard(next, params, ctx) {
        next(params); // 默认放行，return false 则拦截
    }
}

javascript 复制代码

// core/NodeTypes.js 加一行
import MyNode from '../nodes/my-node/NodeClass.js';
export const NODE_TYPES = { 'my-node': MyNode, /* ... */ };

这意味着 你可以用 ChatGPT / Claude 直接生成新节点------告诉 AI "我需要一个调用钉钉机器人发消息的节点"，把上面的模板和协议说明丢给它，几十秒就能拿到一个可直接注册使用的节点。

2.2 四种边 ------ 比 LangChain 更灵活的数据流模型

text 复制代码

① 默认边     A → B              数据流，params 沿边传递
② env-config 配置边              source.data → target.ctx.config，不触发执行
③ 条件分支    guard 返回 false   节点被标记为 skipped
④ 多输入汇聚  guard 计数        实现 fan-in，等 N 个上游到齐后执行

四种边的组合让数据流、配置注入、条件分支、多输入汇聚都能用统一模型表达，不需要额外学一套 DSL。

2.3 可视化监控 ------ 3 行代码接入

javascript 复制代码

import { FlowMonitor } from '../monitor/FlowMonitor.js';

const monitor = new FlowMonitor(engine, {
  nodes, edges,
  name: 'my-demo',
  label: '我的 Demo',
});
monitor.start();

Hub 架构自动拉起，无需手动启动监控服务：

text 复制代码

demo 进程 FlowMonitor(Reporter) ──POST──→ server.js(Hub :3900) ──SSE──→ 浏览器 ui.html
                                              └─ monitor/logs/<name>.jsonl 持久化

浏览器打开 http://127.0.0.1:3900 可以：

DAG 状态着色 ------ 节点按 pending / running / success / failed / skipped 实时变色
节点详情面板 ------ 点击节点查看静态配置、注入配置、每轮输入/输出 params、耗时
执行时间线 ------ 每一步执行过程完整记录
多会话管理 ------ 左侧栏同时监控多个 demo，live 绿点 / 离线灰点
历史回放 ------ SQLite 持久化，过往执行日志随时回放，支持按轮次切换和单轮删除

2.4 三层分离 ------ 终端和 Web 共用一套逻辑

text 复制代码

flow-graph.js         DAG 结构定义（nodes/edges/常量），不含任何运行逻辑
handlers.js           共享编排（registerHandler 集合 + runTurn），终端与网页共用
─────────────────────────────────────────────────────────────
chat.js  （终端入口）  buildGraph → setupHandlers → readline 循环
web.js   （网页入口）  buildGraph → setupHandlers → node:http 服务
web.html （单文件页）  聊天气泡 + SSE 进度条 + Markdown 渲染
─────────────────────────────────────────────────────────────
monitor Hub (:3900)   深度节点监控（输入/输出/耗时）

一套 handlers 同时驱动终端和浏览器，零重复代码。新增流程只需改 flow-graph.js + handlers.js 两个文件。

2.5 可从任意节点触发执行

不同于大多数框架必须从"入口"开始，XFlow 的同一套 DAG 支持多个触发点：

javascript 复制代码

await engine.buildGraph(nodes, edges);

// 从用户输入触发
await engine.execute('用户输入', { message: '帮我写一个排序函数' });

// 直接从验证节点触发（跳过前面的步骤）
await engine.execute('代码验证', { code: '...', language: 'javascript' });

这对调试和子流程复用极其友好。

三、实战：一个编码 Agent 的 DAG

以下是一个完整的"编码 Agent"流程定义：

javascript 复制代码

// flow-graph.js
export const nodes = [
  { id: 'ask',    type: 'screen-input',  alias: '入口',       data: { label: '用户输入' } },
  { id: 'master', type: 'deepseek',      alias: 'master',     data: { label: '主人格',
    systemPrompt: '你是一个全栈工程师，擅长分析需求并协调专家完成任务。',
    userPrompt: '{{message}}',
  }},
  { id: 'router', type: 'router-agent',  alias: 'router',     data: { label: '路由',
    agents: ['coder', 'reviewer'],
  }},
  { id: 'coder',  type: 'deepseek',      alias: 'coder',      data: { label: '编码专家',
    systemPrompt: '你是一个资深程序员，写出高质量、可运行的代码。',
  }},
  { id: 'verify', type: 'code-verify',   alias: 'verify',     data: { label: '代码验证' } },
  { id: 'mem',    type: 'memory-full',   alias: 'mem-save',   data: { label: '全量记忆·保存',
    mode: 'save', key: 'chat', dbPath: './data/agent.db',
  }},
  { id: 'out',    type: 'output',        alias: '出口',       data: { label: '结果输出' } },
];

export const edges = [
  { source: 'ask',    target: 'master' },
  { source: 'master', target: 'router' },
  { source: 'router', target: 'coder' },
  { source: 'coder',  target: 'verify' },
  { source: 'verify', target: 'mem' },
  { source: 'mem',    target: 'out' },
  // ★ 验证失败 → 回边重试
  { source: 'verify', target: 'coder' },
];

执行流程：

text 复制代码

用户输入 → 主人格分析 → 专家路由 → 编码专家生成代码
                ↑                              ↓
                └──── 验证失败，回边重试 ←── 代码验证
                                                   ↓ 通过
                                              记忆保存 → 结果输出

整个流程在监控页实时可见，每个节点的状态、耗时、输入输出一目了然。

四、快速开始

bash 复制代码

# 克隆项目
git clone https://gitee.com/xxt2286621910/xflow.git
cd xflow

# 配置 API Key
cp .env.example .env
# 编辑 .env，填入 DeepSeek API Key（兼容 OpenAI 协议）

# 极简对话（30 行代码，控制台 + 监控）
node examples/minimal-chat/chat.js

# 完整 Agent（记忆 + 思维路由 + Web 聊天页）
node examples/agent-chat/web.js
# 浏览器打开 http://127.0.0.1:3901
# 监控页 http://127.0.0.1:3900（Hub 自动拉起）

环境要求：Node.js ≥ 22 （需要实验性 node:sqlite 支持）。

五、适用场景

场景	说明
现有项目加 Agent	零依赖，纯 ESM，`core/` + `nodes/` 丢进去就能用
多 Agent 协作	专家路由 + fan-in 汇聚 + 条件分支，多角色分工
开发流水线	代码生成 → 自动校验 → 失败重试，节点状态全程可视
原型验证	监控页实时看每一步输入/输出/耗时，调试不再靠猜
子流程复用	Flow-as-Node 机制，流程可嵌套为另一个流程的节点

六、写在最后

XFlow 不追求大而全的"平台化"，而是追求 轻量、可理解、可调试 。它解决的核心问题是：让你用一张 DAG 图描述 Agent 工作流，然后可视化地看到每一步发生了什么。

如果你厌倦了框架的层层抽象，或者想在自己的项目里快速加一个可控的 Agent 流程，欢迎试试。

Star ⭐ 是对开源作者最大的鼓励，感谢支持！

🏠 Gitee：gitee.com/xxt22866219...

📖 文档：docs/NODE-DEVELOPMENT.md · docs/FLOW-DEVELOPMENT.md · docs/WEB-CHAT.md