flowchart TB
    subgraph Client["客户端层"]
        WebUI[Web界面<br/>Next.js SSR]
        API[API调用<br/>OpenAPI/SDK]
    end
    
    subgraph AppLayer["应用层 (projects/app)"]
        NextPages[Next.js Pages]
        APIRoutes[API Routes]
        PageComponents[页面组件]
    end
    
    subgraph ServiceLayer["服务层 (packages/service)"]
        CoreService[核心服务<br/>AI/App/Chat/Dataset/Workflow]
        CommonService[通用服务<br/>Mongo/Redis/S3/VectorDB]
        SupportService[支持服务<br/>User/Permission/Wallet]
        Worker[后台任务<br/>Worker]
    end
    
    subgraph GlobalLayer["全局层 (packages/global)"]
        CoreTypes[核心类型定义<br/>AI/App/Chat/Dataset/Workflow]
        CommonUtils[通用工具<br/>Error/File/String/Time]
        OpenAPITypes[OpenAPI类型]
    end
    
    subgraph WebLayer["Web组件层 (packages/web)"]
        Components[通用UI组件]
        Hooks[React Hooks]
        I18N[国际化]
    end
    
    subgraph External["外部服务"]
        Sandbox[沙箱服务<br/>NestJS]
        MCPServer[MCP服务器<br/>Model Context Protocol]
        Plugins[插件系统<br/>LLM/OCR/TTS/STT]
    end
    
    subgraph Storage["存储层"]
        MongoDB[(MongoDB<br/>业务数据)]
        VectorDB[(向量数据库<br/>PG/Milvus)]
        Redis[(Redis<br/>缓存/队列)]
        S3[(对象存储<br/>S3)]
    end
    
    subgraph ThirdParty["第三方服务"]
        LLM[LLM服务<br/>OpenAI/国内模型]
        Embedding[嵌入模型]
        Rerank[重排模型]
    end
    
    WebUI --> NextPages
    API --> APIRoutes
    NextPages --> PageComponents
    APIRoutes --> CoreService
    PageComponents --> Components
    
    CoreService --> CommonService
    CoreService --> SupportService
    CoreService --> GlobalLayer
    CommonService --> Storage
    CoreService --> Worker
    
    Worker --> Storage
    
    APIRoutes --> Sandbox
    CoreService --> MCPServer
    CoreService --> Plugins
    
    CoreService --> ThirdParty
    
    Components --> Hooks
    Components --> I18N
    
    style Client fill:#e1f5ff
    style AppLayer fill:#fff4e1
    style ServiceLayer fill:#e8f5e9
    style GlobalLayer fill:#f3e5f5
    style WebLayer fill:#fce4ec
    style External fill:#fff3e0
    style Storage fill:#e0f2f1
    style ThirdParty fill:#f1f8e9

客户端请求 → API Routes → 身份验证 → 参数验证 → Service层业务逻辑 → 数据库/外部服务 → 响应返回

API Routes → 创建任务 → BullMQ队列 → Worker消费 → 执行任务 → 更新状态 → MongoDB

工作流触发 → 解析节点和边 → 构建执行队列 → 按依赖顺序执行节点 → 变量传递 → 结果汇总

sequenceDiagram
    autonumber
    participant C as 客户端
    participant API as API Routes<br/>/v2/chat/completions
    participant Auth as 身份验证
    participant ChatS as Chat Service
    participant WF as Workflow Engine
    participant Node as 工作流节点<br/>(AI/Dataset/Agent)
    participant LLM as LLM服务
    participant VDB as 向量数据库
    participant Mongo as MongoDB
    
    C->>API: POST 对话请求<br/>{messages, stream}
    API->>Auth: 验证 API Key / Token
    Auth-->>API: 用户信息 {teamId, tmbId}
    
    API->>ChatS: initChat(appId, chatId)
    ChatS->>Mongo: 查询应用配置和历史
    Mongo-->>ChatS: 返回配置和变量
    ChatS-->>API: 初始化结果
    
    API->>WF: dispatchWorkflow(nodes, edges)
    
    Note over WF: 构建执行队列<br/>按依赖关系排序节点
    
    loop 执行每个节点
        WF->>Node: dispatch(nodeType, inputs)
        
        alt 数据集检索节点
            Node->>VDB: 向量检索(query, topK)
            VDB-->>Node: 返回相关文档片段
        else AI对话节点
            Node->>LLM: completions(messages, model)
            LLM-->>Node: 流式返回生成内容
        else Agent工具调用
            Node->>LLM: completions(messages, tools)
            LLM-->>Node: tool_calls
            Node->>Node: 执行工具节点
            Node->>LLM: completions(messages + tool_results)
            LLM-->>Node: 最终回答
        end
        
        Node-->>WF: 节点输出结果
        Note over WF: 更新变量池<br/>触发下游节点
    end
    
    WF-->>API: 工作流执行结果<br/>{flowResponses, usages}
    
    API->>ChatS: saveChat(chatId, userContent, aiContent)
    ChatS->>Mongo: 保存对话记录
    Mongo-->>ChatS: 保存成功
    
    API-->>C: SSE流式响应<br/>或JSON响应

sequenceDiagram
    autonumber
    participant U as 用户
    participant API as API Routes
    participant FileS as File Service
    participant S3 as 对象存储
    participant Worker as Worker进程
    participant Parser as 文件解析器
    participant Embed as 嵌入模型
    participant VDB as 向量数据库
    participant Mongo as MongoDB
    
    U->>API: 上传文件<br/>POST /dataset/collection/create
    API->>FileS: 处理上传文件
    FileS->>S3: 存储原始文件
    S3-->>FileS: 返回fileId
    
    FileS->>Mongo: 创建Collection记录<br/>{name, fileId, status: waiting}
    Mongo-->>FileS: 返回collectionId
    FileS->>Worker: 发送文件解析任务<br/>BullMQ
    
    API-->>U: 返回collectionId<br/>状态: waiting
    
    Worker->>S3: 下载文件
    S3-->>Worker: 文件流
    Worker->>Parser: 解析文件内容<br/>(PDF/DOCX/TXT等)
    Parser-->>Worker: 提取文本和结构
    
    Note over Worker: 文本分块<br/>RecursiveCharacterTextSplitter
    
    loop 每个文本块
        Worker->>Embed: 生成向量<br/>embedding(text)
        Embed-->>Worker: vector[1536]
        Worker->>VDB: 插入向量<br/>{id, vector, metadata}
        Worker->>Mongo: 插入DatasetData<br/>{q, a, vector}
    end
    
    Worker->>Mongo: 更新Collection状态<br/>status: active
    
    Note over U: 用户发起检索
    
    U->>API: 搜索知识库<br/>POST /dataset/searchTest
    API->>Embed: 生成查询向量<br/>embedding(query)
    Embed-->>API: queryVector[1536]
    
    API->>VDB: 向量检索<br/>search(queryVector, topK)
    VDB-->>API: 返回相似文档<br/>[{id, score, metadata}]
    
    API->>Mongo: 查询完整数据<br/>DatasetData.find({_id: {$in: ids}})
    Mongo-->>API: 返回文档内容<br/>{q, a, source}
    
    API-->>U: 返回检索结果<br/>[{score, q, a}]

# MongoDB
MONGODB_URI=mongodb://localhost:27017/fastgpt

# PostgreSQL (向量数据库)
PG_URL=postgresql://user:pass@localhost:5432/postgres

# Redis
REDIS_URL=redis://localhost:6379

# S3对象存储
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_NAME=fastgpt

# OneAPI (多模型代理)
ONEAPI_URL=http://localhost:3000/v1
ONEAPI_KEY=sk-xxx

# 商业版（可选）
FASTGPT_PRO_URL=
FASTGPT_PRO_KEY=

# 沙箱服务（可选）
SANDBOX_URL=http://localhost:3001

# MCP服务器（可选）
MCP_SERVER_URL=http://localhost:3002

// 1. 通过API创建应用
const createAppResponse = await fetch('/api/core/app/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: '我的第一个应用',
    type: 'simple',
    avatar: '/icon/logo.svg'
  })
});

const { appId } = await createAppResponse.json();

// 2. 配置工作流（最简单的AI对话）
await fetch(`/api/core/app/update`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    appId,
    nodes: [
      {
        nodeId: 'workflowStartNodeId',
        flowNodeType: 'workflowStart',
        position: { x: 300, y: 300 },
        inputs: [
          {
            key: 'userChatInput',
            renderTypeList: ['reference'],
            valueType: 'string',
            label: '用户问题',
            required: true
          }
        ]
      },
      {
        nodeId: 'aiChatNodeId',
        flowNodeType: 'chatNode',
        position: { x: 800, y: 300 },
        inputs: [
          {
            key: 'model',
            value: 'gpt-3.5-turbo',
            valueType: 'string'
          },
          {
            key: 'systemPrompt',
            value: '你是一个友好的AI助手',
            valueType: 'string'
          },
          {
            key: 'userChatInput',
            value: ['workflowStartNodeId', 'userChatInput'],
            valueType: 'string'
          }
        ]
      }
    ],
    edges: [
      {
        source: 'workflowStartNodeId',
        target: 'aiChatNodeId',
        sourceHandle: 'workflowStartNodeId-source-right',
        targetHandle: 'aiChatNodeId-target-left'
      }
    ]
  })
});

// 3. 发起对话
const chatResponse = await fetch('/api/v2/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    chatId: 'unique_chat_id', // 使用nanoid()生成
    appId: appId,
    stream: true,
    messages: [
      {
        role: 'user',
        content: '你好，介绍一下自己'
      }
    ]
  })
});

// 处理SSE流式响应
const reader = chatResponse.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim());
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data.choices[0].delta.content);
    }
  }
}

// 1. 创建知识库
const createDatasetResponse = await fetch('/api/core/dataset/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: '产品文档知识库',
    type: 'dataset',
    avatar: '/icon/logo.svg',
    vectorModel: 'text-embedding-ada-002'
  })
});

const { datasetId } = await createDatasetResponse.json();

// 2. 上传文档
const formData = new FormData();
formData.append('file', file); // File对象
formData.append('datasetId', datasetId);
formData.append('mode', 'auto'); // 自动分块

await fetch('/api/core/dataset/collection/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

// 3. 配置工作流（知识库检索 + AI对话）
await fetch(`/api/core/app/update`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    appId,
    nodes: [
      {
        nodeId: 'workflowStart',
        flowNodeType: 'workflowStart',
        // ... 省略其他配置
      },
      {
        nodeId: 'datasetSearch',
        flowNodeType: 'datasetSearchNode',
        inputs: [
          {
            key: 'datasetIds',
            value: [datasetId],
            valueType: 'selectDataset'
          },
          {
            key: 'query',
            value: ['workflowStart', 'userChatInput'],
            valueType: 'string'
          },
          {
            key: 'similarity',
            value: 0.5, // 相似度阈值
            valueType: 'number'
          },
          {
            key: 'limit',
            value: 5000, // 最大Token
            valueType: 'number'
          },
          {
            key: 'searchMode',
            value: 'embedding', // 向量检索
            valueType: 'string'
          }
        ]
      },
      {
        nodeId: 'aiChat',
        flowNodeType: 'chatNode',
        inputs: [
          {
            key: 'model',
            value: 'gpt-4',
            valueType: 'string'
          },
          {
            key: 'systemPrompt',
            value: '你是一个专业的客服，请根据知识库内容回答用户问题。如果知识库中没有相关信息，请诚实告知。',
            valueType: 'string'
          },
          {
            key: 'userChatInput',
            value: ['workflowStart', 'userChatInput'],
            valueType: 'string'
          },
          {
            key: 'quoteQA', // 引用知识库
            value: ['datasetSearch', 'quoteQA'],
            valueType: 'datasetQuote'
          }
        ]
      }
    ],
    edges: [
      {
        source: 'workflowStart',
        target: 'datasetSearch'
      },
      {
        source: 'datasetSearch',
        target: 'aiChat'
      }
    ]
  })
});

// 4. 测试检索效果
const searchTestResponse = await fetch('/api/core/dataset/searchTest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    datasetId,
    text: '如何使用知识库？',
    similarity: 0.5,
    limit: 5000
  })
});

const searchResults = await searchTestResponse.json();
console.log('检索结果：', searchResults);

// 1. 创建HTTP工具
const createToolResponse = await fetch('/api/core/app/httpTools/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: '天气查询',
    description: '查询指定城市的天气信息',
    url: 'https://api.weather.com/query',
    method: 'GET',
    params: [
      {
        key: 'city',
        type: 'string',
        required: true,
        description: '城市名称，如：北京、上海'
      }
    ]
  })
});

const { toolId } = await createToolResponse.json();

// 2. 配置Agent工作流
await fetch(`/api/core/app/update`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    appId,
    nodes: [
      {
        nodeId: 'workflowStart',
        flowNodeType: 'workflowStart',
        // ... 省略
      },
      {
        nodeId: 'agent',
        flowNodeType: 'agent',
        inputs: [
          {
            key: 'model',
            value: 'gpt-4', // Agent需要支持function calling的模型
            valueType: 'string'
          },
          {
            key: 'systemPrompt',
            value: '你是一个智能助手，可以帮用户查询天气信息。',
            valueType: 'string'
          },
          {
            key: 'userChatInput',
            value: ['workflowStart', 'userChatInput'],
            valueType: 'string'
          },
          {
            key: 'maxRunTimes',
            value: 5, // 最多执行5轮工具调用
            valueType: 'number'
          }
        ]
      },
      {
        nodeId: 'weatherTool',
        flowNodeType: 'tool',
        inputs: [
          {
            key: 'toolId',
            value: toolId,
            valueType: 'string'
          }
        ]
      }
    ],
    edges: [
      {
        source: 'workflowStart',
        target: 'agent'
      },
      {
        source: 'agent',
        target: 'weatherTool',
        sourceHandle: 'agent-source-tool'
      },
      {
        source: 'weatherTool',
        target: 'agent',
        targetHandle: 'agent-target-tool'
      }
    ]
  })
});

// 3. 测试工具调用
const chatResponse = await fetch('/api/v2/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    chatId: 'unique_chat_id',
    appId: appId,
    stream: false,
    messages: [
      {
        role: 'user',
        content: '帮我查一下北京今天的天气'
      }
    ]
  })
});

const result = await chatResponse.json();
console.log('AI回复：', result.choices[0].message.content);
console.log('工具调用记录：', result.usage.toolCalls);

// 插件代码（独立服务）
import express from 'express';

const app = express();
app.use(express.json());

// 插件必须实现的接口
app.post('/analyze', async (req, res) => {
  const { text } = req.body;
  
  // 调用情感分析模型（示例）
  const sentiment = await analyzeSentiment(text);
  
  res.json({
    sentiment: sentiment.label, // positive/negative/neutral
    score: sentiment.score
  });
});

app.listen(3010, () => {
  console.log('情感分析插件启动在 3010 端口');
});

// 在FastGPT中使用插件
// 1. 创建插件应用
const createPluginResponse = await fetch('/api/core/app/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: '情感分析插件',
    type: 'plugin',
    avatar: '/icon/plugin.svg'
  })
});

const { pluginId } = await createPluginResponse.json();

// 2. 配置插件工作流
await fetch(`/api/core/app/update`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    appId: pluginId,
    nodes: [
      {
        nodeId: 'pluginInput',
        flowNodeType: 'pluginInput',
        inputs: [
          {
            key: 'text',
            valueType: 'string',
            label: '待分析文本',
            required: true
          }
        ]
      },
      {
        nodeId: 'httpRequest',
        flowNodeType: 'httpRequest468',
        inputs: [
          {
            key: 'url',
            value: 'http://localhost:3010/analyze',
            valueType: 'string'
          },
          {
            key: 'method',
            value: 'POST',
            valueType: 'string'
          },
          {
            key: 'body',
            value: JSON.stringify({
              text: '{{text}}'
            }),
            valueType: 'string'
          }
        ]
      },
      {
        nodeId: 'pluginOutput',
        flowNodeType: 'pluginOutput',
        inputs: [
          {
            key: 'sentiment',
            value: ['httpRequest', 'sentiment'],
            valueType: 'string',
            label: '情感倾向'
          },
          {
            key: 'score',
            value: ['httpRequest', 'score'],
            valueType: 'number',
            label: '置信度'
          }
        ]
      }
    ],
    edges: [
      {
        source: 'pluginInput',
        target: 'httpRequest'
      },
      {
        source: 'httpRequest',
        target: 'pluginOutput'
      }
    ]
  })
});

// 3. 在主应用中使用插件
// 在主应用的工作流中添加"运行插件"节点
{
  nodeId: 'runPlugin',
  flowNodeType: 'pluginModule',
  inputs: [
    {
      key: 'pluginId',
      value: pluginId,
      valueType: 'string'
    },
    {
      key: 'text',
      value: ['workflowStart', 'userChatInput'],
      valueType: 'string'
    }
  ]
}