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

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

痛点：Agent 框架越来越重了

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

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

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

于是写了 XFlow。

---

一、XFlow 是什么

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

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

支持四种经典拓扑：

 复制代码串行:    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 注册一行即可。标准模板就十几行：

 复制代码// 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 则拦截
    }
}

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

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

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

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

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

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

 复制代码import { FlowMonitor } from '../monitor/FlowMonitor.js';const monitor = new FlowMonitor(engine, {
  nodes, edges,
  name: 'my-demo',
  label: '我的 Demo',
});
monitor.start();

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

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

浏览器打开 可以：

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

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

 复制代码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 支持多个触发点：

 复制代码await engine.buildGraph(nodes, edges);// 从用户输入触发
await engine.execute('用户输入', { message: '帮我写一个排序函数' });// 直接从验证节点触发（跳过前面的步骤）
await engine.execute('代码验证', { code: '...', language: 'javascript' });

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

---

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

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

 复制代码// 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' },
];

执行流程：

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

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

---

四、快速开始

 复制代码# 克隆项目
git clone 
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
# 浏览器打开 
# 监控页 （Hub 自动拉起）

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

---

五、适用场景

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

---

六、写在最后

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

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

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