OCWE / FlowForge — 面向多智能体的操作系统级执行时

设计哲学：并非所有功能都需要 LLM。通过工作流 + 多节点编排 + Hook 被动调用 LLM 调试错误 + SPJ 事件报错，最大化硬编码执行比例，最小化 Token 消耗。

双支柱架构：任务规划与验证（YAML 编译器 + SPJ + DAG 引擎）+ KG 驱动上下文管理（GraphRAG + 永久知识图谱 + 可溯源检索）

可视化 AI 工作流引擎。基于 DAG 编排，集成 LightRAG 知识图谱、资源感知动态调度、对话式工作流生成、SPJ 自动验证修复。原生适配 openEuler / 鲲鹏 ARM64。

---

目录

1. 设计哲学与核心创新
2. 快速开始
3. 系统架构全景
4. 一、检索体系 — KG / RAG / Memory
5. 二、任务设计 — YAML 编译 / Skill / 工作流规划
6. 三、工作流执行 — Engine / DAG / 节点 / 调度
7. 四、验证与修复 — SPJ / Hook / Diagnosis
8. 五、会话模型 — 统一 Chat + Workflow
9. 操作指南
10. API 参考
11. 配置参考

---

设计哲学与核心创新

核心理念：Token 效率最大化

                  ┌──────────────────────┐
                  │   用户意图（对话）      │
                  └──────────┬───────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        简单问答         复杂任务         已有经验
        (直接用LLM)    (编译为YAML)      (匹配Skill)
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
         硬编码节点      条件LLM节点      被动修复
         (零Token)    (仅在需要时)    (仅在出错时)

关键原则：

• 能用 Tool/Code 节点就不用 LLM 节点 — Shell 命令、Python/JS 脚本零 Token 成本
• SPJ 预检 — 执行前校验 inputSchema，不满足不调 LLM
• Hook 被动修复 — 正常路径零开销，仅错误时调 LLM 诊断
• KG 压缩 — 旧消息存入永久 KG，检索时无 LLM 开销（纯向量+图谱匹配）
• 资源排队 — LLM 限流时任务排队等待，不浪费 Token 在会失败的调用上

五大技术创新

创新	解决的问题	实现方式
KG 驱动上下文压缩	长对话 Token 线性增长	旧消息→提取实体→注入_system KG→检索替代
资源感知动态调度	多任务争抢 LLM 资源	5 维探针 + 优先级队列 + 自动降级/failover
对话式工作流生成	手动设计 YAML 门槛高	LLM 分析需求→生成 YAML→编译→后台执行
SPJ 双向校验 + 被动修复	节点输出不可靠	Pre-hook 阻止无效调用 + Post-SPJ 捕获错误 + LLM 旁路修复
统一会话模型	聊天/工作流模式割裂	去掉 workflowMode，聊天永续，工作流异步执行

---

快速开始

# 一键安装 + 启动全部服务
git clone https://github.com/xhqyt/workflow.git && cd workflow
./setup.sh

# 分步操作
./setup.sh install   # 安装 Node + Python 依赖
./setup.sh start     # 启动 RAG → Backend → Frontend
./setup.sh status    # 查看各服务运行状态
./setup.sh stop      # 停止全部服务

访问 http://localhost:3000。首次使用在 Settings → Provider 配置 API Key。

环境：Node.js 22+ / Python 3.10+ / Redis 7+ / PostgreSQL 15+（RAG 向量存储，可选）

---

系统架构全景

┌──────────────────────────────────────────────────────────────────┐
│                     Frontend (React + Vite + Tailwind)            │
│                                                                  │
│  ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐ │
│  │Dashboard │ │  Chat +  │ │Settings │ │ Memory │ │  Canvas  │ │
│  │实时监控   │ │ Workflow │ │5 Tabs   │ │KB CRUD │ │ DAG编辑  │ │
│  └──────────┘ └──────────┘ └─────────┘ └────────┘ └──────────┘ │
│       ↕              ↕             ↕          ↕          ↕       │
│      WS          HTTP/SSE       HTTP       HTTP       HTTP      │
└──────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┴────────────────────────────────────┐
│                  Backend (Node.js / TypeScript / Fastify)         │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    API Layer (21 routes)                     │ │
│  │  agents · workflows · executions · providers · models       │ │
│  │  rag · knowledge-base · monitor · settings · schedules       │ │
│  │  skills · clawhub · benchmark · heartbeat · llm              │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                              │                                   │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                      Core Engine                             │ │
│  │                                                             │ │
│  │  ┌─ Workflow Execution ───────────────────────────────────┐ │ │
│  │  │ Engine → DAG Executor → Node Executor                  │ │ │
│  │  │   ├─ TaskEnvelope (节点→任务封装)                        │ │ │
│  │  │   ├─ WorkerPool (资源感知执行池)                          │ │ │
│  │  │   ├─ CheckpointManager (断点续传)                        │ │ │
│  │  │   └─ TaskInstantiator / StateMachine / ReadyQueue       │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │                                                             │ │
│  │  ┌─ Resource Scheduling ──────────────────────────────────┐ │ │
│  │  │ ResourceCollector (5维探针)                              │ │ │
│  │  │   → SchedulingDecision (执行/排队/暂停/降级/拒绝)         │ │ │
│  │  │ ResourceGuard (速率限制) · ResourceLedger (slot跟踪)     │ │ │
│  │  │ ResourceAwareScheduler (公平性+评分)                     │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │                                                             │ │
│  │  ┌─ Validation ──────────────────────────────────────────┐ │ │
│  │  │ SPJ Validator: Pre-execution Hook + Post-execution SPJ  │ │ │
│  │  │ NodeRepairHook: LLM 旁路诊断 → fix/escalate/giveup     │ │ │
│  │  │ NodeDiagnosis · NodeValidator · NodeGuidance           │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │                                                             │ │
│  │  ┌─ Retrieval ───────────────────────────────────────────┐ │ │
│  │  │ Permanent KG (_system) · KG Extractor · KG Optimizer   │ │ │
│  │  │ Context Budget · Context Manager · Content Slicer      │ │ │
│  │  │ Planning Memory · Chat Session Store                   │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │                                                             │ │
│  │  ┌─ Compiler ────────────────────────────────────────────┐ │ │
│  │  │ YAML Compiler → WorkflowDefinition                     │ │ │
│  │  │ Skill Compiler → 展开 skill 节点为基本节点              │ │ │
│  │  │ Skill Store · Skill Atomizer                           │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                              │                                   │
│                    ┌─────────┴─────────┐                        │
│                    │  PostgreSQL  │  Redis  │                    │
│                    └──────────────┴─────────┘                    │
└──────────────────────────────────────────────────────────────────┘
                              │ HTTP Proxy
┌─────────────────────────────┴────────────────────────────────────┐
│              RAG Service (Python / FastAPI / LightRAG)            │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  LightRAG Engine (GraphRAG)                                  │ │
│  │  ├─ Entity Extraction (LLM)                                  │ │
│  │  ├─ Relation Building                                       │ │
│  │  ├─ PGVector Storage                                        │ │
│  │  └─ Graph Search (mix mode, no LLM)                          │ │
│  │                                                             │ │
│  │  KB Registry (JSON file persistence)                         │ │
│  │  Custom KG Injection (ainsert_custom_kg)                     │ │
│  │  File Upload → Parse → Chunk → Embed → Store                 │ │
│  └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

---

一、检索体系 — KG / RAG / Memory

1.1 设计目标

将对话中的信息结构化为知识图谱，实现跨 Session 记忆共享，避免重复 Token 消耗。

1.2 永久知识图谱 _system

┌─────────────────────────────────────────────────────────┐
│                  Permanent KG (_system)                  │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │ Entities │  │Relations │  │ Chunks (conversation) │  │
│  │          │  │          │  │                      │  │
│  │ 用户偏好  │  │ 偏好→项目 │  │ "用户喜欢简洁代码风格"   │  │
│  │ 项目技术栈│  │ 技术栈→认证│  │ "项目用 TS+React"     │  │
│  │ 认证系统  │  │          │  │ "从JWT迁移到OAuth2"   │  │
│  └──────────┘  └──────────┘  └──────────────────────┘  │
│                                                         │
│  特性: 自动创建 · 不可删除(403) · 跨Session共享          │
└─────────────────────────────────────────────────────────┘

1.3 上下文压缩流程

每次发送消息前（在 agents.ts 中）:

1. estimateTokens(messages)     → 是否 > 80% 预算？
2. 否 → 直接发送
3. 是 →
   ┌─────────────────────────────────────────────────────┐
   │ a. 保留最后 8 轮原文 (recentMsgs)                    │
   │ b. 旧消息 → kg-extractor.extractKnowledge()          │
   │    └─ 调用 LLM 提取:                                 │
   │       { entities: [{name, type, description}],       │
   │         relationships: [{src, tgt, keywords}],       │
   │         chunks: [{content, source_id}] }             │
   │ c. → permanent-kg.injectKnowledge()                  │
   │    └─ POST /rag/custom-kg/_system                    │
   │       └─ LightRAG: ainsert_custom_kg()               │
   │ d. → permanent-kg.retrieveFromKG(currentQuery)       │
   │    └─ POST /rag/graph-search/_system                 │
   │       └─ mode="mix", only_need_context=True          │
   │       └─ 返回: chunks[] + entities[] + relationships[]│
   │ e. → permanent-kg.formatKGContext(retrieved, budget) │
   │    └─ 按 60/25/15 分配 chunks/entities/relations     │
   │    └─ 超 budget 自动截断                             │
   │ f. 组装: [system] + [KG记忆] + [recentMsgs]          │
   │ g. 校验: 若仍超预算 → 从 recent 尾部裁剪              │
   └─────────────────────────────────────────────────────┘

1.4 KG 动态优化

LLM 回复后 (异步，不阻塞):

evaluateUsage(replyText, kgContext)
  → 检测 LLM 回复中是否引用了 KG 的实体/关系/片段
  → 基于关键字重叠（支持 CJK bigram 分词）
  → 返回 { usedEntityNames[], usedChunkIds[], relevanceScore }

reinforce(usedEntities, replyText, query)
  → 更新实体 description，嵌入元信息:
    "[weight:0.85|used:3|query:用户偏好] 上次回复摘要: ..."
  → custom-kg 注入更新后的实体

maybePrune() (每 20 轮)
  → 标记从未使用的实体为 archived (weight→0.05)
  → 清理无用的记忆碎片

1.5 模块清单

文件	核心职责	关键方法
core/permanent-kg.ts	_system KG 生命周期	ensureSystemKG(), injectKnowledge(), retrieveFromKG(), formatKGContext(maxTokens)
core/kg-extractor.ts	LLM 提取结构化知识	extractKnowledge(messages) → {entities,relations,chunks}
core/kg-optimizer.ts	使用评估 + 强化 + 清理	evaluateUsage(), reinforce(), maybePrune()
core/context-budget.ts	Token 估算 + 预算管理	estimateTokens(), getBudget(), needsCompression()
core/context-manager.ts	多层上下文组装	sliceAndStore(), assemble()
core/content-slicer.ts	格式感知切片	sliceContent() 支持 JSON/Markdown/Code/Text
core/planning-memory.ts	KB 检索	searchKnowledgeBase(), retrieveSimilarWorkflows()

1.6 RAG 服务端点 (rag_service/server.py)

端点	方法	功能	LLM 开销
/rag/health	GET	健康检查	无
/rag/upload	POST	文件上传→解析→分片→向量化	有（实体提取）
/rag/query	POST	检索查询 (naive/vector/graph/hybrid)	取决于模式
/rag/custom-kg/{ws}	POST	注入预构建的实体+关系+片段	无
/rag/graph-search/{ws}	POST	图谱检索 (mix mode, only_need_context)	无
/rag/knowledge-bases	GET/POST	列出/创建 KB	无
/rag/knowledge-bases/{ws}	PUT/DELETE	更新/删除 KB	无
/rag/knowledge-bases/{ws}/insert	POST	文本插入(ainsert)	有（实体提取）
/rag/knowledge-bases/{ws}/query	POST	KB 检索	取决于模式

检索模式说明：

• naive: 纯向量搜索，最快
• vector: 语义向量搜索
• graph: 知识图谱遍历
• hybrid: 向量 + 图谱混合
• mix: 返回原始 chunks + entities + relations（仅 graph-search）

---

二、任务设计 — YAML 编译 / Skill / 工作流规划

2.1 从需求到执行：完整数据流

用户描述任务 (自然语言)
        │
        ▼
   LLM 分析需求 (agents.ts → compile_and_run tool)
        │
        ▼
   生成 YAML 工作流定义
        │
        ▼
   YAML Compiler (yaml-compiler.ts)
   ├─ YAML.parse → WorkflowDefinition
   ├─ validate nodes: 类型检查、必填字段
   ├─ validate edges: 引用完整性、循环检测
   └─ 返回 CompileResult { valid, definition, errors[], warnings[] }
        │
        ▼ (如需展开 skill 节点)
   Skill Compiler (skill-compiler.ts)
   ├─ 加载 Skill 定义 (skill-store.ts)
   ├─ 命名空间隔离 (__{skillId}__)
   ├─ 展开子图节点 + 重写边
   └─ 递归展开 (最大深度 5)
        │
        ▼
   POST /api/workflows → 保存
   POST /api/executions → 启动执行
        │
        ▼
   Engine.startWorkflow() → DAG Executor → Node Executor

2.2 YAML 编译器 (core/yaml-compiler.ts)

支持的节点类型（注册在 node-registry.ts）：start, end, agent, llm, tool, code, condition, loop, parallel, subworkflow, wait, skill

编译错误分两类：

类别	含义	LLM 行为
config	字段缺失/无效（如缺少 promptTemplate）	自行修正后重试
planning	设计错误（循环依赖/不可达节点/未注册类型）	向用户确认更多细节

// 编译结果
interface CompileResult {
  valid: boolean;
  definition?: WorkflowDefinition;
  errors: CompileIssue[];    // 阻塞性错误
  warnings: CompileIssue[];  // 非阻塞性警告
}

2.3 Skill 系统

Skill = 预编译的、带参数的可复用工作流。存储在 data/skills/{id}/skill.yml。

外部 MD Skill (Claude Code / OpenClaw)
  → LLM 分析
  → 生成 OCWE YAML
  → saveSkill() → 存入 data/skills/{id}/skill.yml
  → 用时: WorkflowDefinition 中引用 type:skill 节点
  → SkillCompiler.expandSkillNodes() → 展开为基本节点

模块	文件	职责
Skill Store	core/skill-store.ts	文件系统 CRUD，内存缓存，支持 category/tag 过滤
Skill Compiler	core/skill-compiler.ts	展开 type: skill → 内联子图，递归 maxDepth=5
Skill Atomizer	core/skill-atomizer.ts	解析自然语言中的 Skill 参数语法

编译流程：

WorkflowDefinition (含 skill 节点)
  → skill-compiler.expandSkillNodes()
  → 1. 加载 SkillDefinition (skill-store.getSkill)
  → 2. 命名空间 node IDs: __{skillNodeId}__
  → 3. 重写内部 edges
  → 4. 应用 inputMappings
  → 5. 重连外部 edges (parent in → entry nodes, exit nodes → parent out)
  → 6. 递归检查 (max depth 5, 防循环)
  → 返回纯基本节点的 WorkflowDefinition

2.4 对话式工作流生成（替代旧的 Planning 模式）

旧设计（已移除）：

escalate_to_workflow → planning 模式
  → assess_task_clarity (Q&A 3-5轮)
  → finalize_plan (创建+执行)
  → 进入 workflowMode (会话锁定)

问题：不能退出、上下文丢失、模式切换僵硬。

新设计：

LLM 直接分析用户需求
  → 如有需要，自然对话中收集信息
  → 自主决定何时生成 YAML
  → 调用 compile_and_run(yaml, name?)
  → 编译 → 创建 Workflow → 异步执行
  → SSE 实时推送进度
  → 聊天不中断，上下文保留

工具定义（tool-calling.ts）:

{
  "name": "compile_and_run",
  "parameters": {
    "yaml": "YAML 工作流定义 (nodes + edges)",
    "name": "可选工作流名称"
  }
}

2.5 节点注册表 (core/node-registry.ts)

定义所有可用节点类型、配置 Schema、分类（logic/ai/control/data）。

NodeRegistry.register('llm', {
  category: 'ai',
  configSchema: {
    promptTemplate: { type: 'string', required: true },
    systemPrompt: { type: 'string' },
    model: { type: 'string' },
    outputSchema: { type: 'object' },
  }
});

---

三、工作流执行 — Engine / DAG / 节点 / 调度

3.1 执行引擎 (core/engine.ts)

完整的生命周期管理：

startWorkflow(workflowId, {input})
  ├─ validateWorkflowDefinition()
  ├─ createExecution → 初始化 Context → Redis 存储
  ├─ CheckpointManager.startPeriodicCheckpoint()
  ├─ DAGExecutor.execute()
  │   ├─ buildGraph() → topologicalSort() → levels
  │   ├─ per level: SchedulingDecision → execute/queue/pause
  │   ├─ per node: SPJ pre-check → execute → SPJ post-check
  │   └─ on failure: NodeRepairHook.diagnose() → retry/escalate
  ├─ 事件广播: WebSocket + SSE
  └─ CheckpointManager.stopPeriodicCheckpoint()

支持：start / pause / resume / stop。Paused 状态持久化到 Redis + PostgreSQL。

3.2 DAG 执行器 (core/dag.ts)

任务级并行调度器。核心流程：

1. buildGraph(nodes, edges) → DAGGraph
   ├─ 计算每个节点的 dependencies[] 和 dependents[]
   └─ 找到 startNodes (无依赖) 和 endNodes (无后继)

2. topologicalSort(graph) → levels[][] 
   └─ Kahn 算法，检测循环依赖

3. per level:
   ├─ SchedulingDecision.decide(node, priority):
   │   ├─ check CPU/Memory/Disk/LLM
   │   ├─ queue? → 延迟重试 (5-30s)
   │   ├─ pause_flow? → 暂停 + checkpoint
   │   ├─ degrade? → 切换到备用模型
   │   └─ execute_now → 执行
   ├─ Promise.all(level) 并行执行同层节点
   └─ 结果存入 context.variables

关键组件：ConcurrencyLimiter、DependencyResolver、TaskInstantiator、ReadyQueue、ResourceAwareScheduler

3.3 节点执行器 (core/executor.ts)

按类型分发，支持模板变量 {{nodeId.output}} 和 {{nodeId.output.field}}。

节点类型	执行方式	Token 成本
start	初始化输入	0
end	收集最终输出	0
tool	executeCommand(cmd) → 沙箱校验 → spawn	0
code	写入临时文件 → python3/node → 收集 stdout	0
llm/agent	构建 prompt → callLlmWithTools()	有
condition	表达式求值 或 LLM 判断	0~有
parallel	拆分为 N 个子任务 → 并发控制 → 合并	取决于子节点
loop	条件循环 → 每次迭代独立执行	取决于子节点
subworkflow	嵌套调用 engine.startWorkflow()	取决于子工作流
wait	setTimeout	0

上游上下文组装 (buildUpstreamContext):

for each upstreamNode.output:
  if _sliced → 使用 KGGraphRAG 摘要
  elif estimateTokens > 2000 → retrieveFromKG(摘要) 
  else → text.slice(0, 4000)

3.4 资源感知调度系统

┌─────────────────────────────────────────────────────────────┐
│                  ResourceProbeManager                        │
│  CpuMemoryProbe │ LLMProviderProbe │ DiskProbe │ NetworkProbe│
│  每 5s 采集一次                                              │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                  ResourceCollector                           │
│  聚合 5 维快照 → ResourceSnapshot                            │
│  { cpu, memory, llm: {providers}, disk, network }            │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                  SchedulingDecision                          │
│  decide(node, priority) → ScheduleAction                     │
│                                                             │
│  ┌──────────────┬──────────────────────────────────────┐    │
│  │ 条件          │ 动作                                  │    │
│  ├──────────────┼──────────────────────────────────────┤    │
│  │ 磁盘 < 1GB    │ reject (拒绝新执行)                    │    │
│  │ 内存 > 85%    │ queue 30s / 优先级≥8 放行             │    │
│  │ CPU > 80%     │ 非LLM节点 queue 5-15s                │    │
│  │ LLM全部耗尽   │ pause_flow                           │    │
│  │ LLM < 20%     │ queue 10s / 优先级≥7 放行 / degrade  │    │
│  │ LLM 充足      │ execute_now / auto-assign provider   │    │
│  └──────────────┴──────────────────────────────────────┘    │
│                                                             │
│  selectFromPoolSync(usage, poolConfig)                       │
│  → 按序查找第一个 enabled + used < max 的 Provider           │
│  → 全部满 → 返回 undefined (排队)                           │
│  → 高优先级 → 自动 failover 到下一个可用 Provider            │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                    WorkerPool                                │
│  poll() → 取任务 → SchedulingDecision → acquire → execute   │
│  → SPJ validate → checkpoint → release                      │
└─────────────────────────────────────────────────────────────┘

LLM 池配置（通过 Settings 前端管理，持久化在 engine-settings.json）：

{
  "llmPool": {
    "providers": [
      { "id": "deepseek", "maxConcurrency": 5, "enabled": true },
      { "id": "anthropic", "maxConcurrency": 3, "enabled": true },
      { "id": "zhipu", "maxConcurrency": 10, "enabled": true }
    ]
  }
}

任务优先级： | 级别 | 范围 | 行为 | |——|——|——| | Critical | 8-10 | 资源紧张也执行，自动 failover | | High | 7 | 优先分配，短队列等待 | | Normal | 5-6 | 正常排队 | | Low | 0-4 | 资源不足时优先让位 |

3.5 断点续传 (core/checkpoint.ts)

Checkpoint 创建 (每次节点完成 + 定期 60s):

{
  context: {
    variables: { nodeA.output: ..., nodeB.output: ... }
    _completedNodes: ["nodeA", "nodeB"],
    _resourceSnapshot: { cpu: 45%, mem: 60%, llm: "normal" }
  }
}

恢复流程:
1. getLatestCheckpoint(executionId) → 加载快照
2. workflowState.setContext() → 恢复 Redis
3. 跳过 _completedNodes
4. SchedulingDecision.canResume() → 检查资源
5. 从中断点继续执行

3.6 调度器 (core/scheduler.ts)

基于 Cron 的定时任务系统：

• SchedulerService: 管理定时任务的创建/启停/触发
• SchedulerRecovery: 重启后恢复未完成的调度任务
• SchedulerOutboxRelay: 可靠事件投递

3.7 模块清单

文件	职责
core/engine.ts	核心编排器，完整生命周期管理
core/dag.ts	DAG 拓扑排序 + 分层并行 + 资源调度 + 修复触发
core/executor.ts	按类型分发节点执行，模板变量插值
core/resource-collector.ts	5 维探针聚合
core/scheduling-decision.ts	资源决策引擎
core/worker-pool.ts	资源感知任务执行池
core/task-envelope.ts	节点→任务封装
core/task-instantiator.ts	节点→任务实例转换
core/task-state-machine.ts	任务状态机
core/checkpoint.ts	断点保存/恢复
core/dependency-resolver.ts	节点依赖解析
core/ready-queue.ts	就绪任务队列
core/concurrency-limiter.ts	并发控制
core/resource-guard.ts	Provider 速率限制
core/resource-ledger.ts	资源 slot 分配追踪
core/resource-probes.ts	5 类硬件/网络探针
core/resource-probe-manager.ts	探针管理器
core/resource-lock-manager.ts	资源锁
core/resource-aware-scheduler.ts	多维评分 + 公平性
core/scheduler.ts	Cron 调度器

---

四、验证与修复 — SPJ / Hook / Diagnosis

4.1 核心思想：正常路径零 LLM 开销

                    ┌─────────────────┐
                    │   Node Ready     │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Pre-Hook 检查   │  ← 纯逻辑，0 Token
                    │  inputSchema    │
                    │  模板变量       │
                    └────────┬────────┘
                             │ passed
                    ┌────────▼────────┐
                    │  执行节点        │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Post-SPJ 检查   │  ← 纯逻辑，0 Token
                    │  outputSchema   │
                    │  类型检查       │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │ passed        │ failed       │
              ▼               ▼              │
         ✅ 完成      ┌──────────────┐       │
                      │ NodeRepairHook│  ← LLM 旁路
                      │ diagnose()    │     仅失败时调用
                      └──────┬───────┘
                             │
              ┌──────────────┼──────────────┐
              │ fix           │ escalate     │ giveup
              ▼               ▼              ▼
         修正配置重试      通知用户       标记失败

4.2 Pre-execution Hook (spj-validator.ts → validatePreExecution)

validatePreExecution(node, context) → { passed, violations[] }

检查项:
1. inputSchema: 必需字段是否存在、类型是否正确
2. promptTemplate: {{变量}} 是否在 context 中有值
3. tool command: 模板语法是否正确 (未闭合的 {{)

节省 Token：如果上游输出不满足当前节点的输入要求，直接报错不调 LLM。

4.3 Post-execution SPJ (spj-validator.ts → validateOutput)

validateOutput(node, output) → { passed, violations[] }

检查项:
1. outputSchema 声明的字段是否存在
2. 字段类型是否匹配 (string/number/boolean/object/array)
3. required 字段是否非空
4. LLM 返回字符串但 schema 期望 object → 尝试 JSON.parse
5. 可选: LLM 语义检查 (spjPrompt)

4.4 节点修复 (core/node-repair.ts)

仅在 SPJ 失败或节点异常时调用（旁路 LLM，不计入正常 Token 预算）：

NodeRepairHook.diagnose({node, context, error, output, spjVerdict})
  → 构建诊断 Prompt (node-diagnosis.ts)
  → 调用修复 LLM (低 temperature, 旁路)
  → parseDiagnosisResponse()
  → 返回 RepairAction:
      fix:      { action:'fix', configOverrides, explanation, confidence }
                → 应用修正 → 重试执行 (最多1次)
      escalate: { action:'escalate', reason }
                → 数据/输入问题 → 通知用户
      giveup:   { action:'giveup', explanation }
                → 无法判断 → 标记失败

置信度阈值: CONFIDENCE_THRESHOLD = 0.5

4.5 模块清单

文件	职责
core/spj-validator.ts	Pre-execution hook + Post-execution SPJ
core/node-repair.ts	LLM 旁路诊断修复
core/node-diagnosis.ts	诊断 Prompt 构建 + 响应解析
core/node-validator.ts	编译时配置校验
core/node-guidance.ts	LLM/ Gate 节点上下文引导

---

五、会话模型 — 统一 Chat + Workflow

5.1 设计原则

不区分”聊天模式”和”工作流模式”。 会话永远是一个聊天，工作流是聊天中可以调用的工具。

旧模型（已移除）:
  Chat → escalate_to_workflow → Planning → workflowMode (锁定)
  问题: 不能退出、上下文丢失

新模型:
  Chat (始终活跃)
    ├─ 日常对话 (LLM 直接回复)
    ├─ compile_and_run → 后台执行 (不阻塞聊天)
    ├─ 查看结果 (执行完成后)
    └─ 继续对话 (上下文保留)

5.2 会话状态

字段	说明
activeExecutionId	当前有工作流在异步执行 (否则 null)
draftYaml	对话中正在设计的 YAML
referencedWorkflowIds	用户引用的工作流

去掉了 workflowMode、planningPhase、workflowId、workflowExecutionId。

5.3 实时反馈

compile_and_run → SSE 推送:
  execution.started     → 🚀 "工作流「XXX」开始执行 (5 节点) [a1b2c3d4]"
  node:complete         → ✅ "节点完成: fetch-data (1.2s)"
  node:error            → ❌ "节点错误: analyze — timeout"
  node.repair_diagnosing → 🔧 "正在诊断: analyze"
  workflow:complete     → 🎉 "工作流执行完成！"
  workflow:error        → 💥 "工作流执行失败: ..."

Dashboard 通过 WebSocket 同步接收:
  workflow:started → 刷新执行列表 + 队列状态
  node:complete    → 刷新执行列表
  workflow:complete → 刷新执行列表 + 队列状态

---

操作指南

聊天

1. 左侧面板 → 新建 Session
2. 输入消息 → Enter 发送
3. 引用工作流：输入框上方「工作流」按钮
4. 上传文件：📎 按钮或拖放
5. KG 压缩：长对话自动触发

工作流创建

• 对话式：直接告诉 LLM 你的需求
• 可视化：左侧「工作流」标签 → 拖拽节点
• YAML：编写 YAML → 导入

Dashboard

• 执行队列 + LLM 池实时状态
• 活跃任务 → 「👁 预览」→ 浮动画布（节点着色）
• WebSocket 自动刷新

Settings (5 Tabs)

Tab	功能
模型选择	切换活跃 LLM
Provider	管理 API Key + Base URL
LLM 池	拖拽排序优先级 + 并发上限
调度	资源阈值 + 并发数
上下文	Token 预算 + 压缩策略

Memory

KB 管理：创建/编辑/删除、文件上传、文本插入、检索测试

---

API 参考

聊天

方法	路径	说明
POST	/api/chat/sessions	创建会话
POST	/api/chat/sessions/:id/messages	发送消息 (SSE 流式)
POST	/api/chat/upload	上传文件

工作流

方法	路径	说明
GET/POST	/api/workflows	列表/创建
GET/PUT/DELETE	/api/workflows/:id	查询/更新/删除
POST	/api/executions	启动执行 {workflowId}
GET	/api/executions/:id/state	节点级状态
POST	/api/executions/:id/pause|resume|stop	控制

设置

方法	路径	说明
GET/PUT	/api/settings	调度/上下文/LLM池配置

监控

方法	路径	说明
GET	/api/monitor/resources	LLM 资源状态
GET	/api/monitor/queue-status	执行队列 + LLM 池

知识库

方法	路径	说明
GET/POST	/api/rag/knowledge-bases	列表/创建
PUT/DELETE	/api/rag/knowledge-bases/:ws	更新/删除 (_system 403)
POST	/api/rag/knowledge-bases/:ws/insert	文本插入
POST	/api/rag/knowledge-bases/:ws/query	检索
POST	/api/rag/custom-kg/:ws	KG 注入
POST	/api/rag/graph-search/:ws	图谱检索 (无 LLM)

---

配置参考

backend/src/config/engine-settings.json（可通过 Settings API 热更新）：

{
  "scheduling": {
    "maxConcurrentNodes": 3,
    "thresholds": {
      "cpuHighPercent": 80,
      "memoryHighPercent": 85,
      "diskLowMB": 1024,
      "llmTightPercent": 20
    }
  },
  "llmPool": {
    "providers": [
      { "id": "deepseek", "maxConcurrency": 5, "enabled": true },
      { "id": "zhipu", "maxConcurrency": 10, "enabled": true }
    ]
  },
  "context": {
    "tokenBudgetRatio": 0.75,
    "compressThresholdRatio": 0.80,
    "keepRecentTurns": 8,
    "kgRetrievalBudget": 3000,
    "checkpointIntervalSec": 60
  }
}

节点类型

类型	Token 成本	用途
start / end	0	入口/出口
tool	0	Shell 命令 (curl, python3, git, etc.)
code	0	Python/JavaScript 脚本
llm / agent	有	LLM 推理
condition	0~有	条件分支
parallel	取决于子节点	并发执行集合
loop	取决于子节点	条件循环
subworkflow	取决于子工作流	嵌套调用
wait	0	延时等待
skill	编译时展开	可复用模块

---

---

技术栈

层	技术选型	作用
前端	React 19 + TypeScript	UI 组件化 + 类型安全
	@xyflow/react (React Flow)	可视化 DAG 画布
	Zustand + persist	全局状态 + localStorage 持久化
	@tanstack/react-query	服务端状态缓存
	Tailwind CSS	原子化样式
	Vite 6	构建工具
后端	Node.js 22 + TypeScript	异步运行时
	Fastify 5	HTTP 服务
	Drizzle ORM + PostgreSQL	持久化存储
	Redis (ioredis)	缓存 + 状态 + 队列
	Zod	运行时类型校验
	WebSocket + SSE	实时事件推送
RAG	Python + FastAPI	独立微服务
	LightRAG	GraphRAG 引擎
	PGVector	向量存储
	Nomic Embed	嵌入模型
部署	Docker + docker-compose	容器化
	Nginx	反向代理
	openEuler / 鲲鹏 ARM64	国产平台原生适配

平台兼容性

• 原生适配 openEuler 操作系统
• 原生支持 鲲鹏 ARM64 架构
• 支持 通义千问、智谱 GLM、DeepSeek、Kimi 等国产大模型
• RAG 服务支持本地化部署，数据不出域
• 一键部署脚本 (setup.sh + deploy.sh)

GraphRAG 学术创新

FlowForge 的 RAG 系统包含两项已投稿 SIGKDD 2027 的学术成果：

1. 多 RAG 联合检索的多维度评价体系 — 形式化定义了”多个独立 RAG 协同检索同一目标”问题，构建了配套 benchmark，作为 FlowForge 检索效果的验证指标。

2. BP-free 图 RAG 检索方法 — 在 HotpotQA、2WikiMultihopQA 等国际公认的多跳问答基准数据集上，主要指标大幅超过 LightRAG、PathRAG 等 SOTA 方法。非工程封装，而是检索算法本身的创新。

对标分析

维度	LangGraph / AutoGen / CrewAI	Claude Code / OpenClaw	FlowForge
任务表示	Python 代码 / 对话	长 Prompt + 全 LLM	YAML DAG + 11种节点
编译期校验	❌ 运行时暴露	❌	✅ 多遍编译器
LLM 最小化	❌	❌	✅ 硬编码优先
资源调度	❌	❌	✅ 5维感知 + 池化
上下文管理	无	纯 LLM 上下文	✅ KG 驱动压缩
知识溯源	无	无	✅ 可溯源到 KG 实体
Token 效率	低（全 LLM）	低（全 LLM）	高（减少 60-80%）

许可证

MIT License