@andrewyang/ai-workflow-editor 0.1.0

package//345/211/215/347/253/257/345/256/232/345/210/266/345/274/200/345/217/221/357/274/232ai-workflow-editor/345/274/200/345/217/221/350/256/241/345/210/222.md

@@ -0,0 +1,655 @@
+# 前端定制开发：基于 Vue-Nuxt-TypeScript 的 AI 工作流编辑器
+
+你希望开发一款基于 Vue 3+Nuxt 4+TypeScript 的在线绘图组件，核心是 AI 智能体与工作流可视化编辑器（支持拖拽连接节点、自定义工作流），要求组件可通过 npm 安装使用，原生集成 Ollama、OpenAI 等 LLM 并支持 LangChain 扩展，适用于 AI 工作流构建、智能体开发且可扩展为架构图/流程图工具。以下是一份**可落地、分阶段的前端定制开发规划**，覆盖从技术选型到发布维护的全流程：
+
+---
+
+## 一、前期准备阶段（1-2 周）
+
+### 1.1 需求精细化拆解
+
+|核心模块|子功能|详细要求|
+|---|---|---|
+|可视化编辑器|画布基础|缩放、平移、居中、全屏；支持网格/吸附；多画布切换|
+||节点管理|拖拽创建节点；自定义节点样式（图标、颜色、尺寸）；节点增删改查；支持分组节点|
+||连线管理|拖拽连线；自定义连线样式（实线/虚线、颜色、箭头）；连线标签；自动避障|
+||工作流操作|工作流保存/导入/导出（JSON/YAML）；撤销/重做；历史版本管理|
+|AI 集成模块|LLM 适配|原生对接 OpenAI（API）、Ollama（本地/远程）；统一调用接口；支持模型切换|
+||AI 能力|自然语言生成工作流；节点智能推荐；工作流逻辑校验；AI 解释工作流意图|
+||LangChain 扩展|集成 LangChain.js；支持 Prompt 模板、Chain、Agent 封装为可视化节点|
+|组件化封装|接入方式|支持 Vue 3 组件引入、Nuxt 4 自动导入；支持全局注册/局部引入|
+||配置化|通过 Props 配置画布、节点、AI 服务；支持自定义事件（节点点击/连线变化）|
+|扩展能力|扩展类型|支持架构图、流程图、时序图等图表类型；可自定义节点库|
+### 1.2 技术选型最终确认
+
+|技术点|选型结果|选型理由|
+|---|---|---|
+|可视化核心|Vue Flow（优先）|基于 Vue 3+TS 开发，生态更贴合 Nuxt 4；API 简洁，自定义节点/连线成本低；支持组合式 API；社区维护活跃|
+|备选：LogicFlow|适配 Vue 3，专注流程图，但 Nuxt 4 适配文档较少，自定义扩展稍复杂||
+|AI 集成核心|LangChain.js + llm-client|LangChain.js 统一封装 LLM 调用逻辑；llm-client 适配 OpenAI/Ollama 等多模型|
+|状态管理|Pinia（Nuxt 4 内置）|管理画布状态、AI 服务配置、工作流数据；支持 SSR 适配|
+|构建工具|Vite（Nuxt 4 内置）|快速构建、热更新；支持库模式打包（适配 npm 发布）|
+|类型校验|TypeScript + Zod|强类型约束；校验 AI 接口返回、工作流 JSON 结构|
+|样式方案|UnoCSS/Tailwind CSS|原子化 CSS，适配自定义节点样式；支持主题定制|
+### 1.3 环境搭建
+
+1. 初始化 Nuxt 4 项目（组件库模式）：
+
+    ```Bash
+    
+    npx nuxi init ai-workflow-editor -t module
+    cd ai-workflow-editor
+    npm install @vue-flow/core @vue-flow/controls @langchain/openai @langchain/community zod
+    ```
+
+2. 配置开发环境：
+
+    - 开启 TypeScript 严格模式（`tsconfig.json` 中 `strict: true`）；
+
+    - 配置 Nuxt 4 插件目录，预注册 Vue Flow 全局组件；
+
+    - 搭建本地 Ollama 环境（用于 AI 功能测试）。
+
+---
+
+## 二、架构设计阶段（1 周）
+
+### 2.1 整体架构
+
+```mermaid
+graph TD
+    A[核心组件层] --> B[可视化编辑器核心]
+    A --> C[AI 集成模块]
+    A --> D[扩展能力模块]
+    B --> B1[画布管理]
+    B --> B2[节点/连线管理]
+    B --> B3[工作流操作]
+    C --> C1[LLM 适配器]
+    C --> C2[AI 工作流生成]
+    C --> C3[LangChain 扩展]
+    D --> D1[自定义节点库]
+    D --> D2[图表类型扩展]
+    E[基础封装层] --> A
+    E --> E1[Props/事件封装]
+    E --> E2[Nuxt 4 适配]
+    E --> E3[样式主题]
+    F[对外接口层] --> E
+    F --> F1[npm 发布包]
+    F --> F2[使用文档]
+    F --> F3[示例工程]
+```
+### 2.2 项目目录结构（组件库模式）
+
+```Plain Text
+
+ai-workflow-editor/
+├── src/
+│   ├── components/          # 核心组件
+│   │   ├── AiWorkflowEditor.vue  # 根组件（对外暴露）
+│   │   ├── editor/          # 编辑器子组件
+│   │   │   ├── Canvas.vue   # 画布容器
+│   │   │   ├── NodePanel.vue # 节点面板
+│   │   │   └── Toolbar.vue  # 工具栏
+│   │   └── ai/              # AI 相关组件
+│   │       ├── LlmClient.vue # LLM 客户端封装
+│   │       └── AiGenerator.vue # AI 生成工作流组件
+│   ├── composables/         # 组合式函数
+│   │   ├── useEditor.ts     # 编辑器核心逻辑
+│   │   ├── useNodes.ts      # 节点管理
+│   │   ├── useAi.ts         # AI 能力封装
+│   │   └── useLangChain.ts  # LangChain 扩展
+│   ├── types/               # 类型定义
+│   │   ├── editor.ts        # 编辑器类型
+│   │   ├── ai.ts            # AI 相关类型
+│   │   └── workflow.ts      # 工作流数据类型
+│   ├── utils/               # 工具函数
+│   │   ├── workflowParser.ts # 工作流解析/导出
+│   │   └── llmAdapter.ts    # LLM 适配工具
+│   └── plugins/             # Nuxt 插件
+│       └── aiWorkflowEditor.ts # 组件注册插件
+├── package.json             # 包配置（npm 发布）
+├── tsconfig.json            # TS 配置
+└── nuxt.config.ts           # Nuxt 配置
+```
+
+### 2.3 核心接口设计（TypeScript）
+
+```TypeScript
+
+// src/types/workflow.ts
+export interface WorkflowNode {
+  id: string;
+  type: string; // 节点类型（AI 节点/普通节点/分支节点）
+  data: {
+    label: string;
+    props?: Record<string, any>; // 节点自定义属性
+    llmConfig?: LlmConfig; // AI 节点配置
+  };
+  position: { x: number; y: number };
+}
+
+export interface WorkflowEdge {
+  id: string;
+  source: string; // 源节点 ID
+  target: string; // 目标节点 ID
+  label?: string; // 连线标签
+}
+
+export interface LlmConfig {
+  provider: 'openai' | 'ollama'; // LLM 提供商
+  model: string; // 模型名称（如 gpt-3.5-turbo、llama3）
+  temperature: number; // 温度系数
+  apiKey?: string; // OpenAI API Key
+  baseUrl?: string; // Ollama/OpenAI 自定义地址
+}
+
+// AI 生成工作流入参
+export interface AiGenerateWorkflowParams {
+  prompt: string; // 自然语言描述
+  llmConfig: LlmConfig;
+  nodeTypes?: string[]; // 可选节点类型
+}
+```
+
+---
+
+## 三、核心功能开发阶段（4-6 周）
+
+### 3.1 可视化编辑器核心开发（2 周）
+
+#### 3.1.1 画布基础功能
+
+基于 Vue Flow 实现画布核心能力：
+
+```Plain Text
+
+<!-- src/components/editor/Canvas.vue -->
+<template>
+  <VueFlow
+    v-model:nodes="nodes"
+    v-model:edges="edges"
+    :zoom-on-scroll="true"
+    :pan-on-drag="true"
+    @node-click="handleNodeClick"
+    @edge-click="handleEdgeClick"
+  >
+    <!-- 内置控制组件（缩放、居中） -->
+    <VueFlowControls />
+    <!-- 自定义节点渲染 -->
+    <template #node-custom-ai="props">
+      <AiNode :data="props.data" />
+    </template>
+    <template #node-custom-normal="props">
+      <NormalNode :data="props.data" />
+    </template>
+  </VueFlow>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VueFlow, VueFlowControls, type Node, type Edge } from '@vue-flow/core';
+import AiNode from './nodes/AiNode.vue';
+import NormalNode from './nodes/NormalNode.vue';
+import '@vue-flow/core/dist/style.css';
+import '@vue-flow/controls/dist/style.css';
+
+const nodes = ref<Node[]>([]);
+const edges = ref<Edge[]>([]);
+
+// 节点/连线点击事件
+const handleNodeClick = (event: MouseEvent, node: Node) => {
+  emit('node-click', node);
+};
+const handleEdgeClick = (event: MouseEvent, edge: Edge) => {
+  emit('edge-click', edge);
+};
+
+// 对外暴露画布方法（如添加节点、导出工作流）
+defineExpose({
+  addNode: (node: Node) => nodes.value.push(node),
+  exportWorkflow: () => ({ nodes: nodes.value, edges: edges.value }),
+  importWorkflow: (data: { nodes: Node[]; edges: Edge[] }) => {
+    nodes.value = data.nodes;
+    edges.value = data.edges;
+  }
+});
+</script>
+```
+
+#### 3.1.2 自定义节点/连线
+
+- 设计 3 类基础节点：AI 执行节点（对接 LLM）、普通执行节点、分支节点；
+
+- 支持通过 Props 传入自定义节点模板，实现节点扩展；
+
+- 自定义连线样式（支持箭头、标签、状态色）。
+
+#### 3.1.3 工作流操作
+
+- 实现保存/导入/导出（JSON/YAML 格式）；
+
+- 基于 `history` 模块实现撤销/重做；
+
+- 画布状态持久化（localStorage/自定义存储）。
+
+### 3.2 AI 集成模块开发（2 周）
+
+#### 3.2.1 LLM 统一适配器
+
+封装支持 OpenAI/Ollama 的统一调用接口，屏蔽不同提供商的差异：
+
+```TypeScript
+
+// src/utils/llmAdapter.ts
+import { ChatOpenAI } from '@langchain/openai';
+import { ChatOllama } from '@langchain/community/chat_models/ollama';
+import type { LlmConfig } from '@/types/ai';
+
+export class LlmClient {
+  private client: ChatOpenAI | ChatOllama;
+
+  constructor(config: LlmConfig) {
+    if (config.provider === 'openai') {
+      this.client = new ChatOpenAI({
+        apiKey: config.apiKey,
+        modelName: config.model,
+        temperature: config.temperature,
+        baseURL: config.baseUrl,
+      });
+    } else if (config.provider === 'ollama') {
+      this.client = new ChatOllama({
+        model: config.model,
+        temperature: config.temperature,
+        baseUrl: config.baseUrl || 'http://localhost:11434',
+      });
+    } else {
+      throw new Error('Unsupported LLM provider');
+    }
+  }
+
+  // 统一调用方法
+  async invoke(prompt: string): Promise<string> {
+    const response = await this.client.invoke(prompt);
+    return response.content;
+  }
+}
+```
+
+#### 3.2.2 AI 生成工作流
+
+通过自然语言描述生成结构化工作流节点/连线：
+
+```TypeScript
+
+// src/composables/useAi.ts
+import { ref } from 'vue';
+import type { AiGenerateWorkflowParams, WorkflowNode, WorkflowEdge } from '@/types/workflow';
+import { LlmClient } from '@/utils/llmAdapter';
+import { z } from 'zod';
+
+// 定义 AI 返回结构的校验 Schema
+const WorkflowSchema = z.object({
+  nodes: z.array(z.object({
+    id: z.string(),
+    type: z.string(),
+    data: z.object({
+      label: z.string(),
+    }),
+    position: z.object({
+      x: z.number(),
+      y: z.number(),
+    }),
+  })),
+  edges: z.array(z.object({
+    id: z.string(),
+    source: z.string(),
+    target: z.string(),
+  })),
+});
+
+export const useAi = () => {
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+
+  // AI 生成工作流
+  const generateWorkflow = async (params: AiGenerateWorkflowParams): Promise<{ nodes: WorkflowNode[]; edges: WorkflowEdge[] }> => {
+    loading.value = true;
+    error.value = null;
+    try {
+      const llmClient = new LlmClient(params.llmConfig);
+      // 构造 Prompt（引导 AI 返回结构化 JSON）
+      const prompt = `
+        根据以下描述生成工作流的 JSON 结构：${params.prompt}
+        要求：
+        1. 仅返回 JSON，不要其他文字；
+        2. JSON 包含 nodes 和 edges 两个数组；
+        3. nodes 中每个节点包含 id、type（可选：ai、normal、branch）、data（包含 label）、position（x/y 为数字）；
+        4. edges 中每个连线包含 id、source（源节点 ID）、target（目标节点 ID）；
+        5. 节点 position 分布合理，避免重叠；
+      `;
+      const response = await llmClient.invoke(prompt);
+      // 解析并校验返回结果
+      const workflow = JSON.parse(response);
+      const validatedWorkflow = WorkflowSchema.parse(workflow);
+      return validatedWorkflow;
+    } catch (err) {
+      error.value = (err as Error).message;
+      throw err;
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return {
+    loading,
+    error,
+    generateWorkflow,
+  };
+};
+```
+
+#### 3.2.3 LangChain 扩展
+
+封装 LangChain 的 Chain/Agent 为可视化节点，支持拖拽组合 AI 流程：
+
+```TypeScript
+
+// src/composables/useLangChain.ts
+import { PromptTemplate } from '@langchain/core/prompts';
+import { LLMChain } from 'langchain/chains';
+import { LlmClient } from '@/utils/llmAdapter';
+import type { LlmConfig } from '@/types/ai';
+
+export const useLangChain = () => {
+  // 创建 LLM Chain 节点逻辑
+  const createLlmChain = (llmConfig: LlmConfig, promptTemplate: string, inputVariables: string[]) => {
+    const llmClient = new LlmClient(llmConfig);
+    const prompt = PromptTemplate.fromTemplate(promptTemplate);
+    const chain = new LLMChain({
+      llm: llmClient.client,
+      prompt,
+    });
+    // 执行 Chain
+    const run = async (inputs: Record<string, string>) => {
+      return await chain.run(inputs);
+    };
+    return { run };
+  };
+
+  return {
+    createLlmChain,
+  };
+};
+```
+
+### 3.3 组件化封装（1 周）
+
+#### 3.3.1 根组件封装（对外暴露）
+
+```Plain Text
+
+<!-- src/components/AiWorkflowEditor.vue -->
+<template>
+  <div class="ai-workflow-editor">
+    <!-- 工具栏 -->
+    <Toolbar
+      @save="handleSave"
+      @import="handleImport"
+      @ai-generate="handleAiGenerate"
+    />
+    <!-- 节点面板 -->
+    <NodePanel @add-node="handleAddNode" />
+    <!-- 画布 -->
+    <Canvas
+      ref="canvasRef"
+      @node-click="emit('node-click')"
+      @edge-click="emit('edge-click')"
+    />
+    <!-- AI 生成弹窗 -->
+    <AiGenerator
+      v-model:visible="aiGenerateVisible"
+      @confirm="handleAiGenerateConfirm"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import Canvas from './editor/Canvas.vue';
+import Toolbar from './editor/Toolbar.vue';
+import NodePanel from './editor/NodePanel.vue';
+import AiGenerator from './ai/AiGenerator.vue';
+import { useAi } from '@/composables/useAi';
+import type { LlmConfig } from '@/types/ai';
+
+// 定义 Props
+const props = defineProps<{
+  // 初始工作流数据
+  initialWorkflow?: { nodes: any[]; edges: any[] };
+  // LLM 默认配置
+  defaultLlmConfig?: LlmConfig;
+  // 自定义节点类型
+  customNodeTypes?: Record<string, any>;
+}>();
+
+// 定义事件
+const emit = defineEmits<{
+  (e: 'save', workflow: { nodes: any[]; edges: any[] }): void;
+  (e: 'node-click', node: any): void;
+  (e: 'edge-click', edge: any): void;
+  (e: 'ai-generate-success', workflow: { nodes: any[]; edges: any[] }): void;
+}>();
+
+const canvasRef = ref<InstanceType<typeof Canvas>>();
+const aiGenerateVisible = ref(false);
+const { generateWorkflow } = useAi();
+
+// 初始化工作流
+if (props.initialWorkflow) {
+  canvasRef.value?.importWorkflow(props.initialWorkflow);
+}
+
+// AI 生成工作流确认
+const handleAiGenerateConfirm = async (prompt: string) => {
+  if (!props.defaultLlmConfig) return;
+  const workflow = await generateWorkflow({
+    prompt,
+    llmConfig: props.defaultLlmConfig,
+  });
+  canvasRef.value?.importWorkflow(workflow);
+  emit('ai-generate-success', workflow);
+};
+
+// 保存工作流
+const handleSave = () => {
+  const workflow = canvasRef.value?.exportWorkflow();
+  if (workflow) emit('save', workflow);
+};
+
+// 暴露对外方法
+defineExpose({
+  exportWorkflow: () => canvasRef.value?.exportWorkflow(),
+  importWorkflow: (data: any) => canvasRef.value?.importWorkflow(data),
+  generateWorkflow: (prompt: string) => handleAiGenerateConfirm(prompt),
+});
+</script>
+```
+
+#### 3.3.2 Nuxt 4 适配
+
+编写 Nuxt 插件，支持自动导入和全局注册：
+
+```TypeScript
+
+// src/plugins/aiWorkflowEditor.ts
+import { defineNuxtPlugin } from '#app';
+import AiWorkflowEditor from '@/components/AiWorkflowEditor.vue';
+
+export default defineNuxtPlugin((nuxtApp) => {
+  // 全局注册组件
+  nuxtApp.vueApp.component('AiWorkflowEditor', AiWorkflowEditor);
+});
+```
+
+---
+
+## 四、组件化发布阶段（1 周）
+
+### 4.1 打包配置
+
+修改 `package.json` 和 `nuxt.config.ts`，配置库模式打包：
+
+```JSON
+
+// package.json
+{
+  "name": "ai-workflow-editor",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/module/index.js",
+  "types": "./dist/module/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt build --preset module",
+    "publish:npm": "npm publish --access public"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0",
+    "nuxt": "^4.0.0"
+  }
+}
+```
+
+### 4.2 npm 发布流程
+
+1. 构建组件库：`npm run build`；
+
+2. 登录 npm 账号：`npm login`；
+
+3. 发布包：`npm run publish:npm`；
+
+4. 发布后验证：在测试项目中安装 `npm install ai-workflow-editor`，验证引入是否正常。
+
+---
+
+## 五、测试验证阶段（1-2 周）
+
+### 5.1 测试类型
+
+|测试类型|测试内容|测试工具|
+|---|---|---|
+|单元测试|核心函数（LLM 适配器、工作流解析）、组件逻辑|Vitest|
+|集成测试|组件间交互（节点添加-连线-AI 生成）|Vitest + Vue Test Utils|
+|E2E 测试|完整流程（打开编辑器-拖拽节点-AI 生成-导出）|Playwright|
+|AI 功能测试|验证 OpenAI/Ollama 对接、LangChain 扩展|手动测试 + 接口模拟|
+|兼容性测试|Nuxt 4 适配、不同浏览器（Chrome/Firefox）|手动测试|
+### 5.2 测试用例示例
+
+```TypeScript
+
+// src/utils/__tests__/llmAdapter.test.ts
+import { describe, it, expect } from 'vitest';
+import { LlmClient } from '../llmAdapter';
+
+describe('LLM Adapter', () => {
+  it('should create OpenAI client correctly', () => {
+    const client = new LlmClient({
+      provider: 'openai',
+      model: 'gpt-3.5-turbo',
+      apiKey: 'test-key',
+      temperature: 0.7,
+    });
+    expect(client).toBeInstanceOf(LlmClient);
+  });
+
+  it('should throw error for unsupported provider', () => {
+    expect(() => {
+      // @ts-ignore 故意传入不支持的 provider
+      new LlmClient({ provider: 'test', model: 'test' });
+    }).toThrow('Unsupported LLM provider');
+  });
+});
+```
+
+---
+
+## 六、文档与示例阶段（1 周）
+
+### 6.1 文档内容
+
+- 快速开始：安装、基本使用、Nuxt 4 集成；
+
+- API 文档：Props、事件、暴露方法、类型定义；
+
+- AI 集成：OpenAI/Ollama 配置、LangChain 扩展示例；
+
+- 自定义扩展：自定义节点、自定义 LLM 提供商；
+
+- 常见问题：部署 Ollama、跨域处理、性能优化。
+
+### 6.2 示例工程
+
+提供 2 个示例工程：
+
+1. Vue 3 + Vite 示例：展示纯前端使用方式；
+
+2. Nuxt 4 示例：展示 SSR 环境下的使用方式。
+
+---
+
+## 七、迭代与维护阶段（长期）
+
+### 7.1 短期迭代（1-3 个月）
+
+- 支持更多图表类型（架构图、时序图）；
+
+- 优化 AI 生成工作流的准确性（Prompt 优化、结果校验）；
+
+- 支持实时协作（基于 Yjs 集成）；
+
+- 性能优化（大工作流的渲染/操作性能）。
+
+### 7.2 长期维护
+
+- 跟进 Vue Flow/LogicFlow、LangChain.js 的版本更新；
+
+- 适配新的 LLM 提供商（如 Claude、Gemini）；
+
+- 修复 Bug、响应社区反馈；
+
+- 完善文档和示例。
+
+---
+
+## 总结
+
+### 核心开发要点
+
+1. **技术核心**：基于 Vue Flow 构建可视化编辑器，通过 LangChain.js 统一封装 LLM 调用，确保 OpenAI/Ollama 原生适配；
+
+2. **组件化关键**：遵循 Vue 3 组件规范，适配 Nuxt 4 插件机制，通过库模式打包实现 npm 发布；
+
+3. **AI 能力核心**：通过 Prompt 引导 + Zod 校验确保 AI 生成的工作流结构合法，支持 LangChain 扩展复杂 AI 逻辑。
+
+### 开发节奏
+
+- 前期准备 + 架构设计：2-3 周；
+
+- 核心功能开发：4-6 周；
+
+- 发布 + 测试 + 文档：2-3 周；
+
+- 整体周期：8-12 周（可根据功能优先级调整）。
+
+### 风险与应对
+
+- AI 生成结果不稳定：增加结果校验、Prompt 模板优化、支持手动调整；
+
+- 性能问题（大工作流）：实现节点懒加载、画布虚拟滚动；
+
+- Nuxt 4 适配问题：优先兼容 Vue 3 核心功能，Nuxt 4 适配作为扩展。
+
+你可根据实际团队规模、开发周期调整各阶段的时间分配，优先完成核心的可视化编辑器 + AI 集成功能，再逐步扩展高级特性。
+> （注：文档部分内容可能由 AI 生成）