Conductor Workflow IDE (@yiyi_zhang/reactflow-ui v1.1.0)

基于 React 19、ReactFlow 与 Zustand 构建的下一代企业级 Netflix Conductor 工作流可视化设计器与 AI 原生编排 IDE。

提供两个可独立按需集成的核心组件入口：

• WorkflowIDE（主入口 @yiyi_zhang/reactflow-ui）— 双模全融合，支持面向业务与运维的业务卡片流 (StepFlow)，以及面向架构研发的专业开发者 DAG 拓扑同屏热切换
• AiWorkflowIDE（子路径 @yiyi_zhang/reactflow-ui/ai）— 对话优先、AI 驱动，支持多轮 Agentic 编排、子工作流库复用与混合交互

---

⚡ v1.1.0 业务与技术全融合核心新特性 (New in v1.1.0)

👔 支柱一：业务卡片流设计器 (Business StepFlow) 与双模同屏无损热切换

• 双模毫秒级热切换：工具栏一键切换 👔 业务模式 ⇄ 💻 开发者模式。业务模式下将复杂的微服务连线拓扑解构为清晰直观的业务卡片流，支持任意位置插入步骤、上下重排与内联表单配置。
• StepModel 双向无损编译引擎：提供递归编译器与反编译器，保证卡片流与原生 Conductor DAG 之间 100% 状态保真转换，非标任务通过 isProFallback 严格兜底。

☁️ 支柱二：内置云平台动作库与动态参数胶囊

• 首发生态对接类阿里云云主机 (ECS) 全生命周期动作：创建云主机、启停机、磁盘快照备份、平滑升降规格、释放实例等。
• 动态参数胶囊与智能上游引用：表单输入项胶囊化呈现，一键联想并安全绑定上游步骤产出的参数引用。

🔀 支柱三：业务容器化高级控制流卡片

• 分支路由卡片 (DecisionBranchCard)：分支 Tabs 导航、条件参数配置、分支内多步骤嵌套编排。
• 并行任务泳道卡片 (ForkJoinCard)：多泳道并发设计器，动态增删泳道。
• 循环迭代容器卡片 (LoopDoWhileCard)：循环体内嵌任务序列、继续条件表达式与防死循环熔断保护。

🪄 支柱四：生产实例一键脱敏提炼为模板工具链 (Template Extractor)

• 生产资产一键沉淀：将生产环境或演练场调试好的工作流一键提炼为公共模板，智能隐私脱敏引擎自动擦除内网 IP、密钥、密码与机密 ID。
• 8 大开箱即用场景模板中心：覆盖云主机自动化、扩容容灾、定时省电关机等高频场景，支持全流程浏览器沙箱试跑验证。

📖 支柱五：运行故事线时间轴与生活化诊断自愈建议

• 流水账故事线展开 (RunStoryTimeline)：运行态以自然语言叙述工作流执行过程，直观呈现每一步耗时与数据快照。
• 生活化故障诊断自愈：告别晦涩堆栈报错，提供通俗易懂的根因诊断与可直接操作的自愈行动建议。

---

🌟 v1.0.0 四大确定性工程底座 (Foundation)

🧬 支柱一：确定性工作流语言服务 (W-LSP) 与数据血缘图谱

• 0ms 确定性 JSONPath 补全：在节点配置面板输入 ${ 时，W-LSP 引擎实时遍历当前节点的所有合法上游祖先节点，融合五类数据源（运行态真实 Output、人工 Mock Output、TaskSchema 注册表、节点配置自省、类型默认字段）弹出零延迟自动补全，并附带 ⚡ 实时值预览。
• Portal 视口自适应锚定：补全浮层挂载至 document.body 并自动感知视口边界翻转，彻底解决侧边抽屉滚动截断问题。
• 🔗 数据流血缘图谱 (Data Lineage Graph)：一键开启画布级蓝色虚线动画边，直观展示跨节点 ${taskRef.output.xxx} 的参数引用依赖与字段流向。
• 跨节点安全重构 (Refactor Rename)：修改任意节点的 taskReferenceName 时，自动扫描并重写全图所有下游节点的 ${oldRef.output...} 表达式，杜绝断链。

⚡ 支柱二：浏览器本地沙箱试跑 (0ms Dry-Run) 与时间旅行调试器

• 无需后端的确定性沙箱引擎 (localSandboxEngine)：支持 SIMPLE、HTTP、INLINE（安全沙箱求值）、SWITCH（真实计算 caseValueParam / expression 路由）、FORK_JOIN（并发波次耗时推演）、DO_WHILE（多轮循环迭代生成 __1、__2、__3）、SET_VARIABLE、TERMINATE 等全量控制流。
• 🧪 人工模拟数据配置台 (SandboxConfigModal)：
  • Tab 1 — 全局入参 (workflow.input)：自动提取工作流声明入参与全图 ${workflow.input.xxx} 隐式引用，一键生成可编辑 JSON 模板。
  • Tab 2 — 节点 Mock、故障注入与分支路由：按节点自定义 Mock Output JSON、模拟耗时 (durationMs)、为 SWITCH 强制指定命中分支，或注入 FAILED / TIMED_OUT 异常以验证高可用容错链路。
• 📊 并发甘特瀑布流与时间旅行回放 (ExecutionWaterfallPanel)：
  • 底部可展开并发执行甘特图，直观呈现并行分支耗时瓶颈。
  • 拖动时间旅行滑块 (Time-Travel Scrubber) 或点击 ▶ 0.5x / 1x / 2x 回放，画布节点与连线按毫秒级时间戳实时还原任意历史时刻的执行状态。
• 🔄 循环迭代切片器 (LoopIterationPill) & 结构化 JSON 树 (StructuredJsonViewer)：
  • DO_WHILE 节点内嵌 [1] [2] [3] 迭代切换胶囊，点击即可切换对应轮次的子任务快照。
  • 运行态详情面板支持字段搜索高亮、折叠展开与一键复制 JSONPath (${taskRef.output.xxx})。

🤖 支柱三：画布原生 AI Co-Pilot (Cmd+K) 与 Shadow Graph 视觉 Diff

• 画布内联微调指令栏 (InlineCanvasCopilot)：选中任意节点或直接在画布按下 Cmd+K / Ctrl+K，原位唤起毛玻璃 AI 指令浮层，支持局部新增下游节点、包裹重试循环、插入条件分支与自动补全参数。
• 👻 Shadow Graph 架构级 Diff 预览：AI 生成或修改工作流提案时，画布直接渲染虚拟变更预览图（+新增 翠绿高亮、~修改 琥珀高亮、-移除 绯红虚线），支持顶部胶囊栏一键采纳或按节点部分采纳 (Partial Accept)。
• 零外部运行时依赖的轻量级流程图渲染：内置基于 Dagre 的原生 SVG 流程图渲染引擎，无需体积庞大的外部 Mermaid 运行时即可在对话流中极速渲染架构图。

🎛️ 支柱四：双向实时代码同步、语义级缩放 (Semantic LOD) 与统一工作台

• 双向实时分屏 JSON 编辑器 (JsonPreviewPanel)：底部 Dock 栏点击 { } JSON 即可展开左画布 + 右代码的双栏分屏视图，修改 JSON 经过 300ms 防抖与结构校验后实时驱动画布重绘，画布拖拽/增删节点亦实时同步至代码。
• 三级语义缩放 (Semantic Zoom LOD)：
  • 宏观鸟瞰 (zoom < 0.55)：自动收起次要技术文本，渲染高对比度色块胶囊，百节点大图依然丝滑。
  • 标准编排 (0.55 <= zoom <= 1.15)：展示节点标题、类型徽章、引用名与运行耗时。
  • 微距透视 (zoom > 1.15)：节点卡片内直接透视展示核心入参摘要（如 GET/POST URL、SWITCH 路由表达式等），免去频繁开关抽屉。
• 统一毛玻璃胶囊工具栏 (ActionBar)：将视图层级分段滑块（📋 业务 / 🔧 标准 / 💻 全开发）、🔗 数据血缘、⌘K AI微调、↺/↻ 历史栈、🩺 诊断、⚙️ 配置、⚡ 沙箱试运行 | 🧪 统一收纳于右上角流式 Dock。

---

📦 安装

npm install @yiyi_zhang/reactflow-ui reactflow react react-dom

环境要求：react >= 18.0.0（完全兼容 React 18 与 React 19），reactflow >= 11.11.0。

---

🚀 快速开始

1. WorkflowIDE（面向专业编排与研发人员）

import { useRef } from 'react';
import { WorkflowIDE, WorkflowIDERef } from '@yiyi_zhang/reactflow-ui';
import '@yiyi_zhang/reactflow-ui/style.css';

export default function App() {
  const ideRef = useRef<WorkflowIDERef>(null);

  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <WorkflowIDE
        ref={ideRef}
        theme="dark"
        themeColor="blue"
        onSave={(workflow) => console.log('保存工作流:', workflow)}
        onWorkflowChange={(workflow) => console.log('变更回调:', workflow)}
      />
    </div>
  );
}

2. AiWorkflowIDE（面向业务与架构人员，AI 原生双栏编排）

从独立子路径 @yiyi_zhang/reactflow-ui/ai 导入：

import { AiWorkflowIDE } from '@yiyi_zhang/reactflow-ui/ai';
import '@yiyi_zhang/reactflow-ui/style.css';

export default function AiApp() {
  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <AiWorkflowIDE
        aiConfig={{
          // 生产环境推荐使用后端代理模式，避免暴露模型 API Key
          transport: { mode: 'endpoint', endpoint: '/api/ai/workflow-agent' },
        }}
        draftPersist={{ key: 'my-workflow-ide-draft' }}
        onSave={(def) => console.log('保存:', def)}
      />
    </div>
  );
}

3. 编程式调用 W-LSP 与本地沙箱引擎 (v1.0.0 新增)

import {
  executeLocalSandboxDryRunAsync,
  buildDataFlowGraph,
  getCompletionItems,
} from '@yiyi_zhang/reactflow-ui';

// 1. 浏览器本地沙箱试跑：INLINE / JQ / SWITCH / DO_WHILE 等真实执行（脚本在隔离的 Web Worker 中运行），
//    HTTP 等调用外部系统的任务返回模拟数据，可按任务覆盖输出或注入故障
const instance = await executeLocalSandboxDryRunAsync(workflowDef, {
  workflowInput: { orderId: 'ORD-2026', vipLevel: 3 },
  taskMocks: {
    charge_card_ref: { status: 'FAILED', reasonForIncompletion: '模拟支付网关 502 超时' },
  },
});
// 每个任务的 sandboxExecution 说明它是 'executed' / 'mocked' / 'not_executed'

// 2. 构建工作流全局数据血缘图谱
const lineageGraph = buildDataFlowGraph(workflowDef);

---

🛠️ 本地开发与验证

# 安装依赖
npm install

# 启动本地开发调试环境（含完整演示工作台）
npm run dev

# 运行单元测试（Vitest）
npm test

# 代码规范检查
npm run lint

# 构建 NPM 发布产物（dist/）
npm run build

---

📁 项目结构

src/
├── index.ts                      # 主入口：WorkflowIDE + W-LSP + 沙箱引擎导出
├── ai.ts                         # AI 入口（/ai 子路径）：AiWorkflowIDE + Agent 工具链导出
├── WorkflowIDE.tsx               # 专业编排组件外壳
├── AiWorkflowIDE.tsx             # AI 原生编排组件外壳
├── components/
│   ├── WorkflowDesigner.tsx      # 核心画布（集成血缘连线、Shadow Graph、时间旅行）
│   ├── TaskDetailPanel.tsx       # 节点属性抽屉（集成 W-LSP 补全与重构提示）
│   ├── ExecutionTaskPanel.tsx    # 运行态详情抽屉（集成 StructuredJsonViewer）
│   ├── SandboxConfigModal.tsx    # 🧪 沙箱人工模拟数据与故障注入配置台
│   ├── ExecutionWaterfallPanel.tsx # 📊 并发甘特瀑布流与时间旅行回放面板
│   ├── JsonPreviewPanel.tsx      # { } 双向实时分屏 JSON 编辑器
│   ├── StructuredJsonViewer.tsx  # 树形 JSON 检索与一键复制 JSONPath 组件
│   ├── nodes/                    # 节点渲染层（含 Semantic LOD 三级语义缩放与 Loop 切片器）
│   ├── Controls/                 # 统一毛玻璃胶囊工具栏 ActionBar、ModeSlider、ControlHub
│   ├── AICopilot/                # W-LSP ParameterSuggester 补全浮层与对话面板
│   └── AiNative/                 # AiCommandCenter、InlineCanvasCopilot (Cmd+K)、MermaidBlock
├── services/
│   ├── wlsp/workflowLsp.ts       # W-LSP 工作流语言服务（祖先推导、Schema 推断、血缘、重构）
│   └── ai/                       # 多模型协议适配、Agent 循环、工具注册表、规则引擎
├── utils/
│   ├── localSandboxEngine.ts     # 浏览器本地确定性沙箱执行引擎
│   ├── validator.ts              # 静态拓扑与引用校验器
│   └── executionAnalyzer.ts      # 运行态智能故障诊断引擎
├── store/                        # Zustand 状态管理（workflowStore、aiStore、libraryStore）
├── parser/                       # Conductor DSL ↔ ReactFlow 节点/边双向解析器
└── layout/                       # Dagre 自动布局与超大流程蛇形布局引擎

---

📚 文档导航

• v1.0.0 产品发布宣传页 — 首屏 Before/After 耗时对比、一行命令极速体验、团队 ROI 收益计算器与交互式沙箱演练。最新版本见首页 index.html。
• 集成指南 (INTEGRATION.md) — Props 详解、运行态接入、AI 代理配置、W-LSP 与沙箱 API
• 版本更新日志 (CHANGELOG.md) — v1.0.0 及历次版本完整变更记录
• 发展路线图 (ROADMAP.md) — 演进里程碑与未来规划
• 最佳实践 (docs/best-practices.md) — 常见业务拓扑建模规范

📄 许可证

MIT