@yiyi_zhang/reactflow-ui 0.3.0 → 0.5.0-beta.0

package/README.md

@@ -2,6 +2,10 @@
 
 基于 React 19、ReactFlow 和 Vite 构建的企业级 [Netflix Conductor](https://conductor-oss.org/) 工作流可视化设计器。
 
+提供两个可独立集成的核心组件：
+- **`WorkflowIDE`**（主入口）— 面向专业编排人员的完整可视化设计器
+- **`AiWorkflowIDE`**（`/ai` 子路径）— 对话优先、AI 驱动，面向非技术业务用户
+
 ## ✨ 核心特性
 
 ### 🎨 可视化建模
@@ -34,19 +38,23 @@
 - `allowOperations` 全局权限开关，快速控制操作按钮是否可用
 
 ### 🤖 AI Copilot（智能辅助）
-- **仅在编辑模式可用**，避免干扰只读/运行态场景
 - 自然语言描述生成完整工作流，支持对话式迭代修改
 - 差异卡片（Diff Card）预览变更内容，一键应用/撤销
-- 参数智能提示：节点属性面板中基于上下文推荐 JSONPath 表达式
+- **✨ AI 参数填充（v0.4.0 新增）**：节点编辑面板一键调用 AI 生成完整 `inputParameters`，基于任务类型、上游任务列表和工作流入参自动推断，diff 预览后一键应用
+
+### 🔬 执行验证闭环（v0.4.0 新增）
+- **执行验证面板**：在 edit 模式下点击"▶ 执行验证"按钮，填写工作流入参（表单/JSON 双模式），一键触发真实 Conductor 执行
+- **自动切换 run 模式**：执行触发后 IDE 自动切换到运行态，通过指数退避轮询实时更新执行状态
+- **结构化入参声明**：`WorkflowSettingsPanel` 支持可视化编辑入参名称、类型、是否必填、描述和示例值
 
-### 🎯 视觉体验
-- 深色/浅色主题 + 品牌主色调（科技蓝/活力橙）
-- 节点边框和阴影经过调校，深色模式下更清晰可辨
-- 切换工作流时自动执行 Fit View，无需手动缩放定位
-- 校验错误徽章（❗⚠️）仅在编辑模式显示，不干扰只读查看
+### 📊 执行结果分析（v0.4.0 新增）
+- **执行概览面板**：run 模式下点击"📊 分析"，展示总任务数/成功率/失败数/总耗时概览卡片
+- **步骤时序表**：按 `startTime` 排序显示所有任务的执行状态、耗时和重试次数，点击行可高亮对应节点
+- **智能故障诊断**：自动识别 10+ 种常见 Conductor 错误模式（JSONPath 失败、HTTP 错误码、超时、认证、脚本异常等），在诊断卡片中给出可操作的修复建议
+- **"去修复"跳转**：点击诊断卡片的"去修复"按钮，一键切换到 edit 模式并选中问题任务
 
 ### 🏢 企业级能力
-- TypeScript 全量类型定义（WorkflowDef、TaskDef、ExecutionActions…）
+- TypeScript 全量类型定义（WorkflowDef、TaskDef、WorkflowInputParam、ExecutionActions…）
 - 命令式 API（`ref`）支持程序化创建、保存、导出
 - 强类型 Ref API：`getWorkflowDef()`、`save()`、`createBlankWorkflow()`
 
@@ -55,15 +63,17 @@
 ## 📦 安装
 
 ```bash
-npm install reactflow-ui reactflow react react-dom
+npm install @yiyi_zhang/reactflow-ui reactflow react react-dom
 ```
 
 ## 🚀 快速开始
 
+### 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() {
   const ideRef = useRef<WorkflowIDERef>(null);
@@ -85,6 +95,25 @@ function App() {
 
 不传 `workflowDef` 时画布显示引导面板，支持空白创建、AI 生成或导入 JSON。
 
+### AiWorkflowIDE（业务用户，AI 驱动）
+
+从独立子路径导入，避免主入口承担 AI 协议/工具执行等代码体积：
+
+```tsx
+import { AiWorkflowIDE } from '@yiyi_zhang/reactflow-ui/ai';
+import '@yiyi_zhang/reactflow-ui/style.css';
+
+function App() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <AiWorkflowIDE aiConfig={{ apiKey: 'your-key' }} onSave={(def) => console.log('保存:', def)} />
+    </div>
+  );
+}
+```
+
+> ⚠️ 生产环境请勿将真实模型密钥直接下发到前端，详见 [集成指南](./INTEGRATION.md) 中 AiWorkflowIDE 章节的安全提示。
+
 详细集成步骤和 API 参考：**[集成指南 →](./INTEGRATION.md)**
 
 ---
@@ -121,17 +150,25 @@ npm run build
 
 ```
 src/
-├── components/        # UI 核心组件（设计器、属性面板、节点…）
-│   ├── nodes/         # 各类型节点组件（TaskNode、DecisionNode、LoopNode…）
-│   ├── AICopilot/     # AI 助手面板
-│   └── Controls/      # 工具栏、模式切换器
-├── store/             # Zustand 状态管理（workflowStore）
-├── parser/            # Conductor JSON ↔ ReactFlow 节点/边转换
-├── layout/            # Dagre 自动布局（含蛇形布局）
-├── types/             # TypeScript 类型定义
-├── styles/            # CSS 变量和执行状态样式
-├── utils/             # 校验器、工作流生成工具
-└── demo/              # 演示应用（开发调试用）
+├── index.ts            # 主入口：WorkflowIDE + 共享类型
+├── ai.ts                # AI 入口（/ai 子路径）：AiWorkflowIDE + AI 配套类型
+├── WorkflowIDE.tsx      # 专业编排组件外壳
+├── AiWorkflowIDE.tsx    # AI 驱动组件外壳
+├── components/          # UI 核心组件（设计器、属性面板、节点…）
+│   ├── nodes/           # 各类型节点组件（TaskNode、DecisionNode、LoopNode…）
+│   ├── AICopilot/       # WorkflowIDE 内置 AI 助手面板
+│   ├── AiNative/        # AiWorkflowIDE 对话/画布/审查等组件
+│   ├── Controls/        # 工具栏、模式切换器
+│   ├── WorkflowRunPanel.tsx    # P4.2: 执行验证入参面板
+│   └── ExecutionSummaryPanel.tsx # P4.3: 执行结果分析面板
+├── services/ai/         # AI 协议适配、工具执行、system prompt 构建
+├── store/               # Zustand 状态管理（workflowStore、aiStore、libraryStore）
+├── parser/              # Conductor JSON ↔ ReactFlow 节点/边转换
+├── layout/              # Dagre 自动布局（含蛇形布局）
+├── types/               # TypeScript 类型定义
+├── styles/              # CSS 变量和执行状态样式
+├── utils/               # 校验器、executionAnalyzer（P4.3 诊断引擎）
+└── demo/                # 演示应用（开发调试用）
 ```
 
 ---
@@ -141,7 +178,9 @@ src/
 - [集成指南 (Integration Guide)](./INTEGRATION.md)
 - [最佳实践 (Best Practices)](./docs/best-practices.md)
 - [路线图 (Roadmap)](./ROADMAP.md)
+- [v0.4.0 发布计划](./docs/v0.4.0-release-plan.md)
 
 ## 📄 许可证
 
 MIT
+

package/dist/AiWorkflowIDE.d.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 './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,6 +1,6 @@
 import React from 'react';
-import { ThemeMode, ThemeColor, LayoutDirection, ValidationResults, ExecutionActions, ViewMode } from './types/workflow';
-import { WorkflowDef } from './types/conductor';
+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';
 import './styles/executionStyles.css';
@@ -60,7 +60,8 @@ export interface WorkflowIDEProps {
      * 运行态数据 (WorkflowInstance)。
      * 当传入此属性时，IDE 会自动切换到 **Run Mode**，展示任务执行状态、连线路径高亮等。
      */
-    workflowExecution?: any;
+    /** 运行态执行实例数据（完整 Conductor Workflow 实例，或裸的任务实例数组） */
+    workflowExecution?: WorkflowExecutionInput;
     /**
      * 点击保存按钮时的回调函数。
      * @param def 最新的工作流定义对象
@@ -97,6 +98,24 @@ export interface WorkflowIDEProps {
      * @default '100%'
      */
     height?: string | number;
+    /**
+     * P4.2: 触发工作流执行。用户在执行验证面板中点击"发起执行"时调用。
+     * 返回 workflowId 后 IDE 自动切换至 run 模式并开始轮询。
+     */
+    onTriggerExecution?: (workflowName: string, version: number, input: Record<string, any>) => Promise<{
+        workflowId: string;
+    }>;
+    /**
+     * P4.2: 轮询执行状态。IDE 在执行触发后按指数退避间隔调用。
+     * 返回 null 表示暂未获取到结果，返回 WorkflowInstance 则加载执行数据。
+     * 返回终态（COMPLETED/FAILED/TIMED_OUT/TERMINATED）后停止轮询。
+     */
+    onPollExecution?: (workflowId: string) => Promise<WorkflowInstance | null>;
+    /**
+     * P4.2: 初始轮询间隔（毫秒），内部使用指数退避，最大退避至 15000ms。
+     * @default 3000
+     */
+    executionPollInterval?: number;
 }
 /**
  * Conductor Workflow IDE 主组件。