@yiyi_zhang/reactflow-ui 0.4.0 → 1.0.0

package/README.md

@@ -1,155 +1,194 @@
-# Conductor Workflow IDE (ReactFlow UI)
-
-基于 React 19、ReactFlow 和 Vite 构建的企业级 [Netflix Conductor](https://conductor-oss.org/) 工作流可视化设计器。
-
-## ✨ 核心特性
-
-### 🎨 可视化建模
-- **从零创建**：无需预先提供 JSON，通过空状态引导面板新建空白工作流，配合中心 **[+]** 引导按钮快速开始建模
-- **完整任务类型**：支持 HTTP、SIMPLE、INLINE/LAMBDA、SWITCH、FORK_JOIN、DO_WHILE、SUB_WORKFLOW、SET_VARIABLE、TERMINATE 等全量 Conductor 任务类型
-- **极简视图**：移除冗余的 START/END 虚拟节点，工作流图更加聚焦业务逻辑
-- **智能布局**：自动 Dagre 布局（TB/LR），超大流程自动触发蛇形布局，编辑/只读模式行为一致
-
-### 🔀 复杂结构编辑
-- **SWITCH 分支管理**：在节点上直接添加、重命名、删除分支，全部通过页面内 Modal，无浏览器原生弹框
-- **DO_WHILE 循环体**：循环任务以容器方式展示，支持在循环体内任意位置插入任务（含首位）
-- **FORK_JOIN 并行分支**：支持动态分支添加和管理
-
-### ✏️ 编辑体验
-- **全屏代码编辑器**：点击任意表达式/脚本/JSON 字段右上角 **⛶** 按钮，展开全屏编辑器，支持 Ctrl+S 保存、Esc 取消，底部状态栏显示行数和字符数
-- **任务引用名实时编辑**：引用名输入框支持流畅输入，失焦/回车后提交，避免逐字符刷新
-- **撤销/重做**：完整的编辑历史，支持 Ctrl+Z / Ctrl+Shift+Z
-- **智能剪贴板**：任务复制粘贴
-
-### 👁️ 视图模式
-- **Business 模式**：仅展示核心业务节点，控制/数据节点折叠为边标签
-- **Standard 模式**：业务 + 控制流节点（默认）
-- **Developer 模式**：显示全部节点，含数据转换等辅助节点，节点上展示表达式预览
-
-### 🚀 运行态监控
-- 节点根据执行状态（Scheduled / In Progress / Completed / Failed / Timed Out / Skipped）实时变色
-- 已完成路径连线高亮，进行中路径动态动画，编辑/只读模式使用静态实线
-- 点击节点展示执行详情面板（输入/输出/耗时/重试次数）
-- **运行态操作**：暂停、继续、终止、重试、重启（支持选择定义版本）、从指定任务重跑、跳过任务
-- `allowOperations` 全局权限开关，快速控制操作按钮是否可用
-
-### 🤖 AI Copilot（智能辅助）
-- 自然语言描述生成完整工作流，支持对话式迭代修改
-- 差异卡片（Diff Card）预览变更内容，一键应用/撤销
-- **✨ AI 参数填充（v0.4.0 新增）**：节点编辑面板一键调用 AI 生成完整 `inputParameters`，基于任务类型、上游任务列表和工作流入参自动推断，diff 预览后一键应用
-
-### 🔬 执行验证闭环（v0.4.0 新增）
-- **执行验证面板**：在 edit 模式下点击"▶ 执行验证"按钮，填写工作流入参（表单/JSON 双模式），一键触发真实 Conductor 执行
-- **自动切换 run 模式**：执行触发后 IDE 自动切换到运行态，通过指数退避轮询实时更新执行状态
-- **结构化入参声明**：`WorkflowSettingsPanel` 支持可视化编辑入参名称、类型、是否必填、描述和示例值
-
-### 📊 执行结果分析（v0.4.0 新增）
-- **执行概览面板**：run 模式下点击"📊 分析"，展示总任务数/成功率/失败数/总耗时概览卡片
-- **步骤时序表**：按 `startTime` 排序显示所有任务的执行状态、耗时和重试次数，点击行可高亮对应节点
-- **智能故障诊断**：自动识别 10+ 种常见 Conductor 错误模式（JSONPath 失败、HTTP 错误码、超时、认证、脚本异常等），在诊断卡片中给出可操作的修复建议
-- **"去修复"跳转**：点击诊断卡片的"去修复"按钮，一键切换到 edit 模式并选中问题任务
-
-### 🏢 企业级能力
-- TypeScript 全量类型定义（WorkflowDef、TaskDef、WorkflowInputParam、ExecutionActions…）
-- 命令式 API（`ref`）支持程序化创建、保存、导出
-- 强类型 Ref API：`getWorkflowDef()`、`save()`、`createBlankWorkflow()`
+# Conductor Workflow IDE (`@yiyi_zhang/reactflow-ui` v1.0.0)
+
+基于 **React 19、ReactFlow 与 Zustand** 构建的下一代企业级 [Netflix Conductor](https://conductor-oss.org/) 工作流可视化设计器与 AI 原生编排 IDE。
+
+提供两个可独立按需集成的核心组件入口：
+- **`WorkflowIDE`**（主入口 `@yiyi_zhang/reactflow-ui`）— 面向专业编排与研发人员的完整可视化 IDE
+- **`AiWorkflowIDE`**（子路径 `@yiyi_zhang/reactflow-ui/ai`）— 对话优先、AI 驱动，支持多轮 Agentic 编排、子工作流库复用与混合交互
+
+---
+
+## 🌟 v1.0.0 四大核心支柱架构 (Next-Gen Architecture)
+
+### 🧬 支柱一：确定性工作流语言服务 (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。
 
 ---
 
 ## 📦 安装
 
 ```bash
-npm install reactflow-ui reactflow react react-dom
+npm install @yiyi_zhang/reactflow-ui reactflow react react-dom
 ```
 
+> **环境要求**：`react >= 18.0.0`（完全兼容 React 18 与 React 19），`reactflow >= 11.11.0`。
+
+---
+
 ## 🚀 快速开始
 
+### 1. `WorkflowIDE`（面向专业编排与研发人员）
+
 ```tsx
 import { useRef } from 'react';
-import { WorkflowIDE, WorkflowIDERef } from 'reactflow-ui';
-import 'reactflow-ui/style.css';
+import { WorkflowIDE, WorkflowIDERef } from '@yiyi_zhang/reactflow-ui';
+import '@yiyi_zhang/reactflow-ui/style.css';
 
-function App() {
+export default function App() {
   const ideRef = useRef<WorkflowIDERef>(null);
 
   return (
-    <div style={{ height: '100vh' }}>
-      <button onClick={() => ideRef.current?.createBlankWorkflow('my_flow')}>新建</button>
+    <div style={{ height: '100vh', width: '100%' }}>
       <WorkflowIDE
         ref={ideRef}
         theme="dark"
         themeColor="blue"
-        onSave={(workflow) => console.log('保存:', workflow)}
-        onRequestImport={() => { /* 打开文件选择器 */ }}
+        onSave={(workflow) => console.log('保存工作流:', workflow)}
+        onWorkflowChange={(workflow) => console.log('变更回调:', workflow)}
       />
     </div>
   );
 }
 ```
 
-不传 `workflowDef` 时画布显示引导面板，支持空白创建、AI 生成或导入 JSON。
+### 2. `AiWorkflowIDE`（面向业务与架构人员，AI 原生双栏编排）
 
-详细集成步骤和 API 参考：**[集成指南 →](./INTEGRATION.md)**
+从独立子路径 `@yiyi_zhang/reactflow-ui/ai` 导入：
 
----
+```tsx
+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>
+  );
+}
+```
 
-### 环境要求
-- Node.js >= 18.0.0
-- npm 或 yarn
+### 3. 编程式调用 W-LSP 与本地沙箱引擎 (v1.0.0 新增)
 
-### 本地开发
+```tsx
+import {
+  executeLocalSandboxDryRun,
+  buildDataFlowGraph,
+  getCompletionItems,
+} from '@yiyi_zhang/reactflow-ui';
+
+// 1. 0ms 浏览器本地确定性沙箱试跑（支持自定义入参与故障注入）
+const { instance } = executeLocalSandboxDryRun(workflowDef, {
+  workflowInput: { orderId: 'ORD-2026', vipLevel: 3 },
+  taskOverrides: {
+    charge_card: { status: 'FAILED', errorMessage: '模拟支付网关 502 超时' },
+  },
+});
+
+// 2. 构建工作流全局数据血缘图谱
+const lineageGraph = buildDataFlowGraph(workflowDef);
+```
 
-```bash
-# 克隆仓库
-git clone https://github.com/yiyisf/reactflow-ui.git
-cd reactflow-ui
+---
+
+## 🛠️ 本地开发与验证
 
+```bash
 # 安装依赖
 npm install
 
-# 启动开发服务器（含演示应用）
+# 启动本地开发调试环境（含完整演示工作台）
 npm run dev
-# 访问 http://localhost:5173
-```
 
-### 构建
+# 运行单元测试（Vitest）
+npm test
 
-```bash
+# 代码规范检查
+npm run lint
+
+# 构建 NPM 发布产物（dist/）
 npm run build
-# 产物生成在 dist/ 目录
 ```
 
-### 项目结构
+---
+
+## 📁 项目结构
 
 ```
 src/
-├── components/        # UI 核心组件（设计器、属性面板、节点…）
-│   ├── nodes/         # 各类型节点组件（TaskNode、DecisionNode、LoopNode…）
-│   ├── AICopilot/     # AI 助手面板
-│   ├── Controls/      # 工具栏、模式切换器
-│   ├── WorkflowRunPanel.tsx    # P4.2: 执行验证入参面板
-│   └── ExecutionSummaryPanel.tsx # P4.3: 执行结果分析面板
-├── store/             # Zustand 状态管理（workflowStore）
-├── parser/            # Conductor JSON ↔ ReactFlow 节点/边转换
-├── layout/            # Dagre 自动布局（含蛇形布局）
-├── types/             # TypeScript 类型定义
-├── styles/            # CSS 变量和执行状态样式
-├── utils/             # 校验器、executionAnalyzer（P4.3 诊断引擎）
-└── demo/              # 演示应用（开发调试用）
+├── 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 自动布局与超大流程蛇形布局引擎
 ```
 
 ---
 
-## 📚 文档资源
+## 📚 文档导航
 
-- [集成指南 (Integration Guide)](./INTEGRATION.md)
-- [最佳实践 (Best Practices)](./docs/best-practices.md)
-- [路线图 (Roadmap)](./ROADMAP.md)
-- [v0.4.0 发布计划](./docs/v0.4.0-release-plan.md)
+- **[🚀 v1.0.0 产品发布宣传首页 (Product Launch Showcase)](./docs/product-launch-v1.0.0.html)** — 100% 单文件零依赖 HTML，含首屏 Before/After 耗时对比、一行命令极速体验、可拖动双滑块团队 ROI 收益计算器与交互式沙箱演练
+- **[集成指南 (INTEGRATION.md)](./INTEGRATION.md)** — Props 详解、运行态接入、AI 代理配置、W-LSP 与沙箱 API
+- **[版本更新日志 (CHANGELOG.md)](./CHANGELOG.md)** — `v1.0.0` 及历次版本完整变更记录
+- **[发展路线图 (ROADMAP.md)](./ROADMAP.md)** — 演进里程碑与未来规划
+- **[最佳实践 (docs/best-practices.md)](./docs/best-practices.md)** — 常见业务拓扑建模规范
 
 ## 📄 许可证
 
 MIT
-

package/dist/AiWorkflowIDE.d.ts

@@ -0,0 +1,219 @@
+/**
+ * AiWorkflowIDE — AI-First workflow designer (component-ready)
+ *
+ * 设计目标：可被任何前端项目直接引用，仅需传入 aiConfig 即可使用。
+ *
+ * 布局：左侧 AI 对话面板（可收起） + 右侧画布 + ReviewBar
+ * 与 WorkflowIDE 共享底层 workflowStore 和组件基础设施。
+ */
+import type { WorkflowDef, WorkflowInstance } from './types/conductor';
+import type { AiConfig } from './services/ai/protocolAdapter';
+import type { AiMetrics } from './store/aiStore';
+import type { WorkflowLibraryItem } from './types/workflowLibrary';
+import type { ExecutionActions, ThemeMode, ThemeColor, LayoutDirection, ViewMode, WorkflowExecutionInput } from './types/workflow';
+import type { CustomTool } from './services/ai/toolRegistry';
+import type { CustomValidationRule } from './services/ai/ruleEngine';
+import type { TaskSchema } from './services/ai/schemaRegistry';
+import type { AiEvent } from './types/aiEvents';
+import type { IdeDraft } from './services/ai/draftPersistence';
+import './styles/tokens.css';
+import './styles/executionStyles.css';
+import './components/AiNative/AiNative.css';
+export interface AiWorkflowIDEProps {
+    /** 初始工作流定义（编辑态） */
+    workflowDef?: WorkflowDef;
+    /** 运行态执行实例数据（完整 Conductor Workflow 实例，或裸的任务实例数组） */
+    workflowExecution?: WorkflowExecutionInput;
+    /**
+     * L1/L2/L3 子工作流库元数据列表（集成方提供）。
+     *
+     * AI 会优先从库中识别可复用的子工作流，而非从零生成。
+     * 遵循分层调用规范：L3→L2/L1，L2→L1，L1同层，禁止反向跨层调用。
+     *
+     * ```tsx
+     * <AiWorkflowIDE
+     *   workflowLibrary={[
+     *     { workflowName: 'create_vm', workflowLevel: 'L1', version: '1.0',
+     *       description: '创建虚机实例', tags: ['云服务器', '计算'] },
+     *     { workflowName: 'cloud_server_apply', workflowLevel: 'L2', version: '2.1',
+     *       description: '云服务器申请完整流程', tags: ['申请'] },
+     *   ]}
+     * />
+     * ```
+     */
+    workflowLibrary?: WorkflowLibraryItem[];
+    /**
+     * AI 模型配置（集成方提供）。
+     *
+     * 最简用法：仅传 apiKey，其余使用默认值（OpenAI gpt-4o）。
+     * ```tsx
+     * <AiWorkflowIDE aiConfig={{ apiKey: 'sk-xxx' }} />
+     * ```
+     *
+     * 使用 Anthropic：
+     * ```tsx
+     * <AiWorkflowIDE aiConfig={{ provider: 'anthropic', apiKey: 'sk-ant-xxx', model: 'claude-sonnet-4-6' }} />
+     * ```
+     *
+     * 当此 prop 提供有效 apiKey 时，组件内建的 AI 配置按钮将自动隐藏，
+     * 由集成方完全掌控 AI 配置。
+     */
+    aiConfig?: Partial<AiConfig>;
+    /**
+     * 完全替换内置基础提示词（高级定制）。
+     * 工作流上下文仍会自动注入，无需手动处理。
+     *
+     * 可从 'reactflow-ui' 导入 BASE_SYSTEM_PROMPT 在此基础上修改：
+     * ```tsx
+     * import { BASE_SYSTEM_PROMPT } from 'reactflow-ui';
+     * <AiWorkflowIDE systemPrompt={BASE_SYSTEM_PROMPT + '\n\n额外规则...'} />
+     * ```
+     */
+    systemPrompt?: string;
+    /**
+     * 追加到内置提示词之后的补充内容（轻量定制）。
+     * 适合注入公司规范、业务背景等上下文，无需理解内置提示词结构。
+     */
+    systemPromptExtra?: string;
+    theme?: ThemeMode;
+    themeColor?: ThemeColor;
+    layoutDirection?: LayoutDirection;
+    /** 初始视图模式。默认 'business'（节点类型标签使用中文业务词汇）。 */
+    viewMode?: ViewMode;
+    /** 组件高度，默认 '100vh' */
+    height?: string | number;
+    /**
+     * Custom tools the AI can call alongside built-in tools (Tool Registry v1).
+     *
+     * Each tool must provide an OpenAI-compatible function definition and an
+     * async `execute` function. The return value is sent back to the model as
+     * the tool result.
+     *
+     * ```tsx
+     * <AiWorkflowIDE
+     *   customTools={[{
+     *     definition: { type: 'function', function: { name: 'query_cmdb',
+     *       description: '查询 CMDB 资源', parameters: { ... } } },
+     *     execute: async (args) => JSON.stringify(await fetchCmdb(args)),
+     *   }]}
+     * />
+     * ```
+     */
+    customTools?: CustomTool[];
+    /**
+     * Custom validation rules applied after built-in Conductor validation (Rules Engine v1).
+     *
+     * Rule `description` strings are injected into the AI system prompt so
+     * generated workflows satisfy these constraints from the start.
+     *
+     * ```tsx
+     * <AiWorkflowIDE
+     *   validationRules={[{
+     *     id: 'require-owner-email',
+     *     level: 'error',
+     *     description: '所有工作流必须设置 ownerEmail（格式：xxx@company.com）',
+     *     validate: (def) =>
+     *       def.ownerEmail ? [] : [{ type: 'GLOBAL', ref: '', message: 'ownerEmail 不能为空' }],
+     *   }]}
+     * />
+     * ```
+     */
+    validationRules?: CustomValidationRule[];
+    /**
+     * Task input/output schemas (Schema Registry v1).
+     *
+     * Registered schemas are injected into the AI system prompt so the model
+     * generates correct inputParameters references for known task types.
+     *
+     * ```tsx
+     * <AiWorkflowIDE
+     *   taskSchemas={[{
+     *     taskName: 'send_notification',
+     *     taskType: 'SIMPLE',
+     *     description: '发送通知',
+     *     inputSchema:  { userId: 'string', message: 'string' },
+     *     outputSchema: { messageId: 'string', status: 'sent|failed' },
+     *   }]}
+     * />
+     * ```
+     */
+    taskSchemas?: TaskSchema[];
+    onSave?: (def: WorkflowDef) => void;
+    onWorkflowChange?: (def: WorkflowDef) => void;
+    onRequestImport?: () => void;
+    executionActions?: ExecutionActions;
+    /**
+     * 触发执行当前工作流。若提供此回调，AI 对话中将出现"执行工作流"快捷操作。
+     *
+     * 签名与 `WorkflowIDE` 的 `onTriggerExecution` 完全一致——同一个后端适配器可同时用于两个组件。
+     */
+    onTriggerExecution?: (workflowName: string, version: number, input: Record<string, any>) => Promise<{
+        workflowId: string;
+    }>;
+    /**
+     * 轮询执行状态，由 workflowId 查询。需与 onTriggerExecution 一起提供。
+     * 返回 `null` 表示暂未获取到结果（继续轮询），返回 `WorkflowInstance` 则视为当前/终态数据。
+     *
+     * 签名与 `WorkflowIDE` 的 `onPollExecution` 完全一致。
+     */
+    onPollExecution?: (workflowId: string) => Promise<WorkflowInstance | null>;
+    /** AI 操作指标回调（accept/reject 次数等） */
+    onAiMetrics?: (metrics: AiMetrics) => void;
+    /**
+     * AI 生命周期事件回调（审计日志 v1）。
+     *
+     * 接收提案创建/接受/拒绝、计划创建/执行、修复提案/执行、工具调用、撤销等所有 AI 操作事件。
+     *
+     * ```tsx
+     * <AiWorkflowIDE
+     *   onAiEvent={(e) => console.log(e.type, e.timestamp, e.diff)}
+     * />
+     * ```
+     */
+    onAiEvent?: (event: AiEvent) => void;
+    /**
+     * AI 操作权限配置。
+     *
+     * - `canEdit`（默认 true）：false 时 AI 只能读取，不能修改工作流
+     * - `canRepair`（默认 true）：false 时运行态修复功能不可用
+     * - `restrictionMessage`：权限受限时显示的提示文字
+     *
+     * ```tsx
+     * <AiWorkflowIDE aiPermissions={{ canEdit: false, restrictionMessage: '只读演示模式' }} />
+     * ```
+     */
+    aiPermissions?: {
+        canEdit?: boolean;
+        canRepair?: boolean;
+        restrictionMessage?: string;
+    };
+    /**
+     * 开启 localStorage 草稿自动保存（workflowDef + 对话 + 待确认提案）。
+     * 默认 `false`（不写宿主页面的 localStorage）。挂载时若检测到草稿会自动恢复现场，
+     * 并展示可放弃恢复的横幅。**仅在未传入 `workflowDef` 时生效**——显式加载指定工作流
+     * 的场景视为明确意图，不应被本地草稿覆盖。
+     *
+     * ```tsx
+     * <AiWorkflowIDE draftPersist={{ key: 'my-app-ai-workflow-draft' }} />
+     * ```
+     */
+    draftPersist?: {
+        key: string;
+    } | false;
+    /**
+     * 草稿变化时的回调（与 `draftPersist` 独立，二者可同时使用）。
+     * 集成方可用它把草稿存到自己的后端，而非（或除了）localStorage。
+     */
+    onDraftChange?: (draft: IdeDraft) => void;
+}
+export interface AiWorkflowIDERef {
+    /** 获取当前工作流定义 */
+    getWorkflowDef: () => WorkflowDef | null;
+    /** 程序化设置工作流 */
+    setWorkflow: (def: WorkflowDef) => void;
+    /** 新建空白工作流 */
+    createBlankWorkflow: (name?: string) => void;
+    /** 获取 AI 使用指标 */
+    getAiMetrics: () => AiMetrics;
+}
+export declare const AiWorkflowIDE: import("react").ForwardRefExoticComponent<AiWorkflowIDEProps & import("react").RefAttributes<AiWorkflowIDERef>>;

package/dist/WorkflowIDE.d.ts

@@ -1,5 +1,4 @@
-import React from 'react';
-import { ThemeMode, ThemeColor, LayoutDirection, ValidationResults, ExecutionActions, ViewMode } from './types/workflow';
+import { ThemeMode, ThemeColor, LayoutDirection, ValidationResults, ExecutionActions, ViewMode, WorkflowExecutionInput } from './types/workflow';
 import { WorkflowDef, WorkflowInstance } from './types/conductor';
 import { AIServiceConfig } from './services/aiService';
 import './styles/tokens.css';
@@ -60,7 +59,8 @@ export interface WorkflowIDEProps {
      * 运行态数据 (WorkflowInstance)。
      * 当传入此属性时，IDE 会自动切换到 **Run Mode**，展示任务执行状态、连线路径高亮等。
      */
-    workflowExecution?: any;
+    /** 运行态执行实例数据（完整 Conductor Workflow 实例，或裸的任务实例数组） */
+    workflowExecution?: WorkflowExecutionInput;
     /**
      * 点击保存按钮时的回调函数。
      * @param def 最新的工作流定义对象
@@ -131,4 +131,4 @@ export interface WorkflowIDEProps {
  * />
  * ```
  */
-export declare const WorkflowIDE: React.ForwardRefExoticComponent<WorkflowIDEProps & React.RefAttributes<WorkflowIDERef>>;
+export declare const WorkflowIDE: import("react").ForwardRefExoticComponent<WorkflowIDEProps & import("react").RefAttributes<WorkflowIDERef>>;

package/dist/ai.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AI 入口 — AiWorkflowIDE 及其配套类型/工具的公开导出。
+ *
+ * 集成方引入方式：
+ * ```tsx
+ * import { AiWorkflowIDE } from '@yiyi_zhang/reactflow-ui/ai';
+ * import '@yiyi_zhang/reactflow-ui/style.css';
+ * ```
+ *
+ * 拆分为独立入口的原因：只使用 WorkflowIDE（主入口 `.`）的集成方不需要
+ * 承担 AI 协议适配、工具执行、Mermaid 渲染等代码体积。
+ */
+export { AiWorkflowIDE } from './AiWorkflowIDE';
+export type { AiWorkflowIDEProps, AiWorkflowIDERef } from './AiWorkflowIDE';
+export type { AiConfig, Message, ToolDef, StreamEvent, TestConnectionResult } from './services/ai/protocolAdapter';
+export { PROVIDER_DEFAULTS, testConnection } from './services/ai/protocolAdapter';
+export { BASE_SYSTEM_PROMPT, buildSystemPrompt } from './services/ai/systemPrompt';
+export type { AiTransport, AgentRequest } from './services/ai/transport';
+export type { IdeDraft } from './services/ai/draftPersistence';
+export type { CustomTool } from './services/ai/toolRegistry';
+export type { CustomValidationRule } from './services/ai/ruleEngine';
+export type { TaskSchema } from './services/ai/schemaRegistry';
+export type { WorkflowLevel, WorkflowLibraryItem, WorkflowLibraryDetail } from './types/workflowLibrary';
+export type { AiEvent, AiEventType } from './types/aiEvents';
+export type { DiffSummary, PartialAcceptSelection, PatchOp } from './services/ai/toolExecutor';
+export { applyPartialProposal, describeDiff, computeDiff } from './services/ai/toolExecutor';
+export type { AiMetrics } from './store/aiStore';
+export type { WorkflowDef, TaskDef, WorkflowInputParam, WorkflowInstance } from './types/conductor';
+export { parseWorkflowInputParams } from './types/conductor';
+export type { ExecutionActions, ThemeMode, ThemeColor, LayoutDirection, ViewMode, TaskExecutionData, WorkflowExecutionInput } from './types/workflow';
+export { getCompletionItems, buildDataFlowGraph, refactorTaskReferenceName, getUpstreamAncestors, inferTaskOutputSchema, } from './services/wlsp/workflowLsp';
+export type { WlspCompletionItem, DataFlowGraph, DataFlowEdge, InferredField, UpstreamTaskInfo, } from './services/wlsp/workflowLsp';
+export { executeLocalSandboxDryRun, buildDefaultWorkflowMockInput, generateDefaultTaskOutputPreview, } from './utils/localSandboxEngine';
+export type { SandboxDryRunOptions, TaskMockOverride, } from './utils/localSandboxEngine';

package/dist/components/AICopilot/ParameterSuggester.d.ts

@@ -1,16 +1,25 @@
 import React from 'react';
 import './ParameterSuggester.css';
+import { WlspCompletionItem, ValueType } from '../../services/wlsp/workflowLsp';
 export interface Suggestion {
     label: string;
     value: string;
     description: string;
+    category?: 'upstream' | 'workflow_input' | 'variable' | 'system' | 'ai';
+    valueType?: ValueType;
+    sourceLabel?: string;
+    sampleValue?: string;
+    isConditional?: boolean;
 }
 interface ParameterSuggesterProps {
     isOpen: boolean;
     onClose: () => void;
     onSelect: (value: string) => void;
     suggestions: Suggestion[];
+    wlspItems?: WlspCompletionItem[];
     anchorRect?: DOMRect;
+    onRequestAiHint?: () => void;
+    aiLoading?: boolean;
 }
 declare const ParameterSuggester: React.FC<ParameterSuggesterProps>;
 export default ParameterSuggester;

package/dist/components/AiNative/AgentTimeline.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AgentTimeline — visible work-in-progress log for the current agent turn (M2.2 + PI Durable 4-Phase Stepper)
+ *
+ * Replaces the single toolStatus line with:
+ * 1. A 4-Phase Synthesis Progress Bar ("① 蓝图定义 → ② 拓扑编排 → ③ 参数与数据流 → ④ 整体校验") when progressive synthesis is active
+ * 2. A growing list of completed steps ("✓ 已搜索工作流库", "✓ 阶段 2/4：已编排 5 个任务拓扑骨架")
+ * 3. The current in-flight step as a spinner row
+ */
+import React from 'react';
+import type { TimelineEntry } from '../../store/aiStore';
+import type { SynthesisPhase } from '../../services/ai/workflowSynthesizer';
+import type { WorkflowDef } from '../../types/conductor';
+interface AgentTimelineProps {
+    entries: TimelineEntry[];
+    /** Current in-flight step label, or '' when nothing is actively running */
+    activeLabel: string;
+    /** Optional current 4-phase synthesis stage */
+    synthesisPhase?: SynthesisPhase;
+    /** Optional in-progress working draft */
+    workingDraft?: WorkflowDef | null;
+}
+declare const AgentTimeline: React.FC<AgentTimelineProps>;
+export default AgentTimeline;