该系统由四个核心层组成：
声明式配置层（YAML）
双表达层（YAML ↔ 可视化 Canvas）
执行控制层（Reconcile Loop + 调度系统）
可观测层（多维监控与反馈控制）
- 系统整体目标
本系统不再是传统意义上的工作流工具，而是：
一个 AI Agent 生命周期的控制平面（Control Plane）
目标包括：
多表达状态一致性
高复杂度执行语义支持
自动自愈的执行系统
全链路可观测性
- 设计原则
2.1 声明式优先（Declarative First）
系统所有结构以 YAML 定义：
Agent 定义
Workflow 拓扑
Edge 执行策略
Runtime 配置
YAML 是唯一事实源（Single Source of Truth）
2.2 双表达系统（Dual Representation）
系统同时支持两种表达方式：
YAML（代码层）
Canvas（可视化 DAG）
两者实时双向同步。
2.3 Reconcile 执行模型
系统不直接执行流程，而是持续对比：
期望状态（YAML） vs 实际运行状态（Runtime）
2.4 可观测驱动控制
监控数据不仅用于展示，还会反向影响执行行为。
- 系统整体架构
┌──────────────────────────────┐
│ 表现层（UI层） │
│ React Canvas + YAML 编辑器 │
└──────────────┬───────────────┘
┌──────────────▼───────────────┐│
│ 编排控制层（核心） │
│ Reconcile 引擎 + 调度器 │
│ YAML ↔ Graph 转换系统 │
└──────────────┬───────────────┘
┌──────────────▼───────────────┐│
│ 执行运行层 │
│ Agent Runtime Engine │
│ Task Queue + Watcher │
└──────────────┬───────────────┘
┌──────────────▼───────────────┐│
│ 可观测层 │
│ Metrics + Trace + Topology │
│ Drift Detection + Feedback │
└──────────────────────────────┘ - 双表达系统（YAML ↔ Canvas）
4.1 核心思想
YAML 是系统唯一事实源，Canvas 是其可视化投影。
4.2 双向同步机制
YAML → Graph → Canvas
Canvas → Graph → YAML
通过 orc-sync.ts 实现实时转换。
4.3 防循环机制
为避免死循环同步，引入：
dirty state lock（canvasDirtyRef）
300ms debounce
稳定 ID 映射（name-based）
- Edge 执行模型（15种策略）
Edge 不再是连接线，而是执行控制单元。
支持策略包括：
sequential pipeline
fan-out / fan-in
map-reduce
parallel execution
retry + fallback
dead-letter routing
dynamic routing
human-in-the-loop
5.1 每条 Edge 的可配置能力
每条 edge 都可独立配置：
retry 策略（次数 / backoff / fallback）
timeout 行为
token 限制
安全校验 gate
数据转换逻辑
merge 策略
5.2 架构升级
传统模型：
Node = 计算单元
本系统模型：
Edge = 计算 + 控制单元
- Reconcile Loop（核心创新）
6.1 状态模型
期望状态（YAML）
Diff 引擎↓
实际运行状态↓
自动修复控制器↓
6.2 Drift 检测
系统持续检测：
拓扑偏移
执行失败路径
节点状态不一致
6.3 自愈机制
当检测到 drift：
自动重试节点
fallback 路由
dead-letter 恢复
子图重计算
- Agent 生命周期系统
系统支持完整工程生命周期：
需求 → 设计 → 实现 → 评审 → 测试 → 部署
7.1 .specs 结构
.specs/
CHANGE.md
REQUIREMENT.md
DESIGN.md
TASK.md
用于完整记录系统演化过程。
- 运行时架构
8.1 后端（FastAPI）
模块包括：
orchestration API
agent 管理
workflow 执行引擎
metrics 监控系统
runtime watcher
8.2 引擎层
核心组件：
scheduler（优先级调度）
reconcile loop engine
security gate registry
runtime hooks
8.3 存储层
SQLite（默认）
MySQL（生产）
Redis（可选缓存）
- 前端架构
技术栈：
React + Vite
Zustand 状态管理
React Flow 图编辑
CodeMirror YAML 编辑器
状态模型
系统包含多状态同步：
YAML state
topology state
runtime state
monitoring state
Canvas 系统
基于 React Flow：
DAG 可视化编辑
节点拖拽
edge 配置面板
实时拓扑更新
- 数据流架构
用户编辑 YAML
↓
状态管理（Zustand）
↓
防抖同步层
↓
Graph 转换引擎
↓
/apply API
↓
调度队列
↓
运行时执行引擎
↓
可观测反馈系统 - 多维可观测系统（Observability Layer）
可观测系统不是日志系统，而是控制系统的一部分。
11.1 执行维度
节点执行状态
Edge 路径记录
重试次数
失败分类
11.2 Token / 成本维度
节点 token 使用量
Edge token 聚合
成本分布
预算控制（软/硬限制）
11.3 性能维度
节点延迟分布
队列延迟
瓶颈检测
调度吞吐
11.4 拓扑维度
DAG 结构变化
fan-out 密度
路由行为分布
graph drift
11.5 Trace 系统
用户请求
↓
Agent A → Agent B → Agent C
↓
Edge 决策记录
↓
最终输出
包含：
完整执行链路
每条 edge 决策
retry / fallback 记录
11.6 可观测驱动控制循环
执行 → 监控 → drift检测 → 自动修复 → 再执行
形成闭环自愈系统。
11.7 实时拓扑监控
提供可视化能力：
节点状态实时变化
Edge 热力图
执行流动画
token 使用叠加
- 安全与治理
系统内建：
RBAC 权限控制
per-edge security gate
API key 加密
审计日志
数据脱敏规则
- 架构对比
能力 本系统 Dify Langflow n8n
YAML 声明式 ✔ ✘ ✘ ✘
Reconcile 自愈 ✔ ✘ ✘ ✘
Edge 可编程控制 ✔ ✘ ✘ ✘
Canvas 双向同步 ✔ ✘ ✘ ✘
生命周期管理 ✔ ✘ ✘ ✘
多维可观测 ✔ ✘ ✘ ✘ - 系统总结
本系统不是工作流工具，而是：
一个自愈式 AI Agent 控制平面（Self-Healing Control Plane）
四层结构：
- 声明式层
YAML 定义系统
- 可视化层
Canvas 编辑拓扑
- 执行层
调度器 + runtime + reconcile loop
- 可观测层
监控 + trace + 反馈控制
- 核心结论
本系统的核心范式转变是：
从“执行工作流” → “持续状态收敛 + 自我修复的系统”
也就是说：
传统系统执行流程
本系统维护一个“持续演化的智能执行体”
