AI智能体开发平台

# 智能体开发应用平台架构设计文档

> 版本：v1.0

---

## 1. 平台定位

### 1.1 平台是什么

**Fusion AIDE** 是面向企业场景的统一 AI 智能体平台底座，承担统一接入、运行、观测、评测的核心角色。平台覆盖从 AI 能力接入、智能体构建、知识工程、工作流编排，到应用发布与质量评测的完整闭环能力体系。

### 1.2 平台边界

- **不是**单点 Agent/RAG 工具，也不是具体业务应用
- **而是**支撑上层应用的基础平台，为企业 AI 建设提供统一的能力底座与交付规范

### 1.3 解决的核心问题

| 痛点 | 当前挑战 | 平台解法 |
|------|---------|----------|
| AI 能力碎片化 | 多供应商 LLM 接口各不兼容，配置分散 | 统一供应商抽象层，屏蔽供应商差异 |
| Agent 开发门槛高 | 工具绑定、知识接入、提示词工程需要大量编码 | 可视化智能体定义 + 多维度绑定（工具/知识/钩子/MCP/技能），低代码配置 |
| 知识管理与 AI 脱节 | 文档处理流程繁琐，向量检索独立于业务 | 内置 ETL 流水线 +  向量存储 + 双模式检索引擎，知识库直接绑定智能体/应用 |
| 应用发布无标准 | 无统一 API 接入规范，缺少版本管理 | App Token 机制 + 版本快照 + 嵌入式接入，标准化应用发布 |
| 质量难以度量 | AI 回答质量无法系统性评估 | 内置评测中心，支持数据集版本管理 + 多维度评测器 + 实验对比 |

### 1.4 目标用户

- **AI 开发工程师**：构建和调试智能体，配置工具链，设计工作流
- **业务运营人员**：通过应用中心发布 AI 应用，管理对话历史，收集用户反馈
- **数据/知识工程师**：管理知识库，维护文档质量，配置检索策略
- **平台管理员**：管理模型供应商、系统配置、用户权限、安全策略

### 1.5 平台生态定位

```
┌─────────────────────────────────────────────────────────────────┐
│                        企业 AI 应用生态                           │
│                                                                   │
│  ┌─────────────┐    ┌───────────────────────────────────────┐   │
│  │  外部 LLM    │    │           Fusion AIDE 平台             │   │
│  │  供应商       │───▶│                                       │   │
│  │ OpenAI/通义  │    │  ┌─────────┐  ┌───────┐  ┌────────┐  │   │
│  │ /文心/本地   │    │  │ 知识引擎  │  │智能体  │  │ 工作流  │  │   │
│  └─────────────┘    │  │         │  │ 引擎  │  │ 引擎   │  │   │
│                     │  └────┬────┘  └───┬───┘  └───┬────┘  │   │
│  ┌─────────────┐    │       └───────────┴──────┬───┘       │   │
│  │  企业知识源  │    │                    ┌─────▼──────┐    │   │
│  │ 数据库/文档  │───▶│                    │  应用中心   │    │   │
│  │ /Web/结构化  │    │                    └─────┬──────┘    │   │
│  └─────────────┘    └──────────────────────────┼───────────┘   │
│                                                  │               │
│            ┌─────────────────────────────────────┤               │
│            ▼                      ▼              ▼               │
│    ┌──────────────┐    ┌───────────────┐  ┌──────────┐         │
│    │  管理控制台   │    │  用户工作台    │  │ REST API │         │
│    │  (admin-v2)  │    │    (chat)     │  │ + Token  │         │
│    └──────────────┘    └───────────────┘  └──────────┘         │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. 建设目标

### 2.1 能力整合

打通知识、Agent、Workflow、App、Benchmark 等核心模块，建立统一的模型供应商接入层，支持 OpenAI 兼容接口及私有部署模型。通过标准化的供应商抽象，屏蔽不同 LLM 供应商的接口差异，并内置 Token 用量计量与费用核算能力。

### 2.2 交付标准化

形成可发布、可鉴权、可回溯、可运营的应用交付模式。支持智能体标准模式与规划模式两种运行模式，通过工具/知识/钩子/MCP/技能五维绑定实现低代码配置；应用层提供 App Token 机制、版本快照与嵌入式接入能力，保障交付可控、可追溯。

### 2.3 持续优化闭环

建立从运行数据到评测、优化、再发布的完整反馈循环。平台提供完整的 RAG 流水线（文档解析 → 结构化分块 → 向量化 → 向量存储 → 双模式检索），评测体系涵盖离线评测实验（数据集版本管理 + 多维评测器 + 实验对比）与在线会话质量分析，形成运行 → 观测 → 评测 → 优化的持续闭环。

### 2.4 组织协同

统一模块边界与验收口径，提升团队协作效率。通过清晰的模块划分（platform-model / platform-knowledge / platform-agent / platform-workflow / platform-app / platform-benchmark）明确各业务域职责，配合可视化管理控制台，使 AI 开发、知识工程、业务运营、平台管理等不同角色的协作成本最小化。

---

## 3. 核心价值

### 3.1 降低重复建设成本

平台将模型接入、知识检索、智能体运行时、应用发布等能力层统一内化，各业务团队共用同一底座无需重复建设基础设施。Spring Boot 模块化单体架构 + Docker Compose 一键启动，PostgreSQL + Redis 两个基础设施依赖，运维成本极低。

### 3.2 提升交付效率

可视化的智能体定义、一键工具绑定、模板化知识库接入、标准化应用发布流程，大幅降低单个 AI 应用的交付门槛。admin-v2 管理控制台提供全程可视化操作，从知识上传到应用发布全程无需查数据库。

### 3.3 增强系统可控性与可观测性

会话链路、LLM 用量、工具调用、节点执行全链路可观测；敏感词过滤、App Token 权限控制、审计日志、配置变更审计满足合规要求；系统配置支持环境变量覆盖，适配容器化部署场景。

### 3.4 支持规模化复用

智能体定义、知识库、工具、工作流模板均可上下文复用；模型价格、安全策略、系统配置均支持平台级统一管理。通过通用分类树、标准化 API 路径、模块化依赖设计，支持大规模多团队、多项目场景下的线上复用。

---

## 4. 分层架构

### 4.1 整体分层架构图

```
┌══════════════════════════════════════════════════════════════════════════════╗
║                              用户交互层                                       ║
║  ┌─────────────────────┐  ┌─────────────────────┐  ┌──────────────────────┐  ║
║  │   管理控制台          │  │    用户工作台          │  │     开放 API          │  ║
║  │   admin-v2           │  │    chat app           │  │  REST API + Token    │  ║
║  │  Vue3 + Element Plus │  │  Vue3 + WebSocket     │  │  Embed 接入           │  ║
║  └─────────────────────┘  └─────────────────────┘  └──────────────────────┘  ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                              应用服务层                                       ║
║  ┌──────────────────┐  ┌───────────────────┐  ┌─────────────────────────┐   ║
║  │ platform-admin   │  │  Spring Security   │  │   API 路由 / 前缀分组    │   ║
║  │ Spring Boot 启动  │  │  JWT 认证 + 权限   │  │  /api/** /embed/**      │   ║
║  └──────────────────┘  └───────────────────┘  └─────────────────────────┘   ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                            平台核心能力层                                     ║
║  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   ║
║  │ platform-    │  │ platform-    │  │ platform-    │  │ platform-    │   ║
║  │ model        │  │ knowledge    │  │ agent        │  │ workflow     │   ║
║  │ 模型管理      │  │ 知识引擎      │  │ 智能体引擎    │  │ 工作流引擎    │   ║
║  │ Provider     │  │ ETL流水线     │  │ AgentScope   │  │ Graph引擎    │   ║
║  │ Config       │  │ pgvector     │  │ Session管理   │  │ Node执行器   │   ║
║  │ Pricing      │  │ 双模式检索    │  │ Tool/Hook    │  │ 状态机       │   ║
║  │ 用量计量      │  │ 问题生成      │  │ MCP集成      │  │ 断点续跑     │   ║
║  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   ║
║  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   ║
║  │ platform-app │  │ platform-    │  │ platform-    │  │ platform-    │   ║
║  │ 应用中心      │  │ plugin       │  │ benchmark    │  │ job          │   ║
║  │ 版本管理      │  │ 插件体系      │  │ 评测中心      │  │ 任务调度      │   ║
║  │ Token访问     │  │ Tool定义     │  │ 数据集版本    │  │ Cron调度     │   ║
║  │ Chat会话      │  │ Hook配置     │  │ 实验执行      │  │ 执行日志      │   ║
║  │ 反馈收集      │  │ MCP Server  │  │ 质量分析      │  │             │   ║
║  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   ║
║  ┌──────────────────────────────────────────────────────────────────────┐   ║
║  │ platform-common | platform-system | platform-resource                 │   ║
║  │ 公共工具类       | 用户/角色/菜单   | 文件存储协议(OSS/本地)            │   ║
║  └──────────────────────────────────────────────────────────────────────┘   ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                              基础设施层                                       ║
║  ┌───────────────────────┐  ┌─────────────┐  ┌───────────────────────────┐ ║
║  │ PostgreSQL 17          │  │  Redis 7    │  │  可选扩展                  │ ║
║  │ + pgvector extension  │  │  会话缓存    │  │  Neo4j (图数据库)           │ ║
║  │ 关系型 + 向量存储       │  │  Token缓存  │  │  LightRAG SDK (图谱检索)   │ ║
║  │ JSONB 半结构化字段      │  │             │  │  AgentScope SDK           │ ║
║  └───────────────────────┘  └─────────────┘  └───────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

### 4.2 分层间交互说明

| 来源层 | 目标层 | 交互方式 |
|--------|--------|---------|
| 用户交互层 → 应用服务层 | HTTP/SSE | REST API 调用，流式响应通过 SSE（Server-Sent Events） |
| 应用服务层 → 核心能力层 | Spring Bean 调用 | 模块内直接依赖，跨模块通过接口抽象 |
| 核心能力层 → 基础设施层 | MyBatis-Plus | 关系数据通过 ORM 操作；向量查询通过 pgvector 原生 SQL |
| Agent 运行时 → LLM | HTTP | AgentScope SDK 封装 OpenAI 兼容接口 |
| Knowledge → LightRAG | HTTP | LightRAG SDK 通过 REST 调用图谱检索服务 |

---

## 5. 核心能力详解

### 5.1 模型管理（platform-model）

**模块职责**：统一管理 LLM 供应商接入、模型实例配置、计费价格与用量计量。

**用量计量设计**：
- **调用明细流水**：每次 LLM 调用的明细记录，含追踪 ID、幂等键（防重）、输入/输出 token 数、实际费用
- **每日聚合统计**：按日期+来源类型（智能体/应用）+模型的聚合统计，支持 LLM 用量分析页面按维度查询

---

### 5.2 知识引擎（platform-knowledge）

**文档处理全流程**：

```
文件上传
    │
    ▼
ETL 路由 (KnowledgeEtlRouter)
    ├── GenericFileEtlHandler  → PDF/Word/TXT/Markdown 等通用文件
    ├── OnlineDocEtlHandler    → 在线文档（语雀、Confluence 等）
    ├── WebLinkEtlHandler      → 网页链接抓取
    └── QaPairEtlHandler       → 问答对直接导入
    │
    ▼
文档解析 (ParseFallbackChain)
    ├── 主解析器 → NormalizedDocumentV2Builder（结构化解析，保留标题层级）
    ├── 降级链   → ParseFallbackStep（多级降级策略）
    └── 质量评分 → 解析得分 + 解析警告写入文档记录
    │
    ▼
分块策略 (chunking/)
    ├── 分块参数: min_chunk_size / max_chunk_size / chunk_overlap（数据集级配置）
    ├── 块类型: chunk_type（正文块/标题块/问答块）
    └── 导航偏移: start_offset / end_offset / 前后切片关联
    │
    ▼
向量化 (index/)
    ├── 调用向量化类型的模型配置
    ├── 向量维度: VECTOR(1024)，存储至向量表
    └── source_type: 区分切片来源 vs 问题来源
    │
    ▼
可检索状态
```

**双模式检索架构**：

| 检索引擎 | 实现类 | 适用场景 | 技术路径 |
|---------|--------|---------|---------|
| 平台向量检索 | `PlatformRetrievalEngine` | 通用 RAG 场景 | pgvector 余弦相似度（`<=>` 运算符）|
| 图谱增强检索 | `LightRagRetrievalEngine` | 复杂关系推理、多跳问答 | LightRAG SDK + Neo4j 图数据库 |
| 混合检索 | `MixedKnowledgeRetrievalEngine` | 精度优先场景 | 平台检索 + LightRAG 结果融合 |

路由决策：`KnowledgeRetrievalEngineRouter` 根据知识库的检索引擎类型（PLATFORM / LIGHTRAG / MIXED）选择引擎。

**问题生成**：`QuestionGenerationService` 基于文档切片调用 LLM 自动生成问答对，向量化后可作为问答检索的独立入口。

**外部连接器**：支持对接外部知识系统（如企业 Wiki、数据库元数据），通过检索配置、重排配置、查询改写配置等 JSONB 字段灵活配置。

---

### 5.3 智能体引擎（platform-agent）

**智能体定义核心配置**：

| 配置分组 | 关键配置项 | 说明 |
|---------|---------|------|
| 基础配置 | 运行模式（标准/规划）、唯一键、模型配置引用 | 运行模式与模型绑定 |
| 提示词 | 系统提示词、提示词模板引用、是否继承模板 | 系统提示词配置，可继承模板 |
| 工具策略 | 工具调用策略（自动/指定/禁用）、指定工具键 | LLM 工具调用策略 |
| 规划能力 | 是否启用规划、最大子任务数、是否需要确认计划 | 规划模式参数 |
| 记忆能力 | 是否启用记忆、是否启用记忆压缩、压缩配置 | 长期记忆与压缩 |
| 输出控制 | 是否启用结构化输出、输出 JSON Schema | 结构化输出配置 |
| 安全过滤 | 敏感词策略引用、过滤开关 | 敏感词策略绑定 |

**五维绑定关系**：

```
智能体定义
    ├── 工具绑定         → 工具定义    (HTTP 工具 / Script 工具)
    ├── 知识绑定         → 知识库      (知识库绑定，含检索配置覆盖)
    │                   → 外部连接器   (外部连接器绑定)
    ├── 钩子绑定         → Hook 配置   (前置/后置 Hook)
    ├── MCP 绑定         → MCP 服务    (MCP 协议服务)
    ├── 技能包绑定        → 技能包      (技能包绑定)
    └── 子智能体绑定      → 智能体定义  (子 Agent 引用，支持 A2A)
```

**运行时架构**（`platform-agent/runtime/`）：

```
AgentRuntimeController（HTTP 请求入口）
    │
    ▼
AgentSessionController → 会话管理
    │
    ▼
AgentScope 运行时（agentscope-spring-boot-starter）
    ├── runtime/model/       → LLM 调用适配（OpenAI 兼容）
    ├── runtime/tool/        → 工具执行（HTTP 调用 / Script 执行）
    ├── runtime/knowledge/   → 检索调用（KnowledgeRetrievalEngine）
    ├── runtime/hook/        → Hook 执行（前置过滤 / 后置处理）
    ├── runtime/mcp/         → MCP Server 调用
    ├── runtime/skill/       → 技能包执行
    └── runtime/prompt/      → 提示词组装（系统提示 + 记忆 + 上下文）
    │
    ▼
消息持久化
    ├── role: user/assistant/tool
    ├── tool_calls / tool_results: JSONB，工具调用明细
    ├── attachments: JSONB，文件附件
    └── path + depth: 树形消息结构（支持消息分支）
```

**A2A 协议**：支持跨智能体调用，记录远端智能体的服务地址、认证配置、调用配置，实现智能体网络。

---

### 5.4 工作流引擎（platform-workflow）

**节点类型体系**：

| 节点类型 | 实现类 | 功能说明 |
|---------|--------|---------|
| `start` | `StartNode` | 流程入口，定义输入变量 |
| `end` | `EndNode` | 流程出口，定义输出变量 |
| `llm` | `LlmNode` | LLM 调用节点，绑定模型配置和提示词 |
| `knowledge` | `KnowledgeNode` | 知识检索节点，绑定知识库 |
| `http` | `HttpNode` | HTTP 请求节点，调用外部接口 |
| `human` | `HumanNode` | 人工审核节点，流程断点等待人工输入 |
| `image` | `ImageNode` | 图像处理节点 |
| `keyword` | `KeywordNode` | 关键词提取节点 |
| `mail` | `MailNode` | 邮件发送节点 |
| `switcher` | `SwitcherNode` | 条件分支节点 |

**工作流执行引擎**（`SimpleWorkflowEngine` / `WorkflowEngine`）：

```
WorkflowStarter（启动入口）
    │ 从工作流模板的图定义（JSONB）加载图结构
    ▼
WorkflowGraphBuilder（图构建）
    │ 解析节点列表 + 边连接关系 → 有向图
    ▼
WorkflowEngine（DAG 执行）
    ├── NodeExecutorRegistry  → 根据节点类型分发到对应 NodeExecutor
    ├── NodeExecutionContext   → 节点间数据传递（输入/输出 JSONB）
    ├── WorkflowState         → 执行状态快照（支持断点保存）
    └── InterruptedWorkflowRegistry → 人工节点中断注册，恢复令牌续跑
    │
    ▼
工作流实例记录 + 节点执行明细
```

**智能体/工具运行时绑定**：将工作流模板中的特定节点与智能体/工具关联，实现节点级资源绑定。

---

### 5.5 应用中心（platform-app）

**应用数据模型**：
- 模型参数配置、知识配置、工作流绑定：均以 JSONB 存储，灵活支持不同类型应用
- 自定义变量参数定义：JSONB 格式，支持应用层参数透传
- 分类树支持：通用分类表，业务类型标记为 APP
- 公开/私有访问控制

**版本发布流程**：
```
应用当前配置
    │  发布操作（AppVersionController）
    ▼
版本快照
    ├── version: 语义化版本号
    ├── app_snapshot: JSONB，发布时刻完整配置快照
    └── status: draft / published
```

**Token 访问机制**：
```
App 访问 Token
    ├── token: 随机生成的访问令牌
    ├── allowed_origins: 允许来源（支持通配符）
    └── expires_at: 过期时间

会话与 Token 关联
    └── anonymous_user_key: 匿名用户标识
```

**嵌入式接入**（`EmbedAppController` / `EmbedAuthController`）：通过 `/embed/**` 路由提供第三方系统嵌入能力，支持 iFrame 或 SDK 接入。

---

### 5.6 评测中心（platform-benchmark）

**评测数据流**：

```
评测集
    └── 评测集版本快照
        └── 评测样本（content_json JSONB）

评测器定义
    └── 评测器版本快照
        ├── mode: LLM 评判 / 规则评判
        ├── dimensions: 评测维度列表（准确性/相关性/完整性等）
        ├── prompt_template: LLM 评判提示词模板
        └── model_config: 评判使用的模型配置

实验配置
    ├── target_type: 智能体 / 应用（被测对象类型）
    ├── target_ref_id: 被测对象 ID
    ├── dataset_version_id: 使用的评测集版本
    └── evaluator_version_ids: 使用的评测器版本列表

实验执行记录
    ├── frozen_*_snapshot: 执行时快照（防止配置变更影响结果）
    ├── status: 待执行 / 执行中 / 已完成 / 失败
    ├── progress: 执行进度（0-100）
    └── summary: JSONB，汇总评分

样本执行结果
    └── 指标评分明细
            ├── metric_key: 指标键
            ├── judge_type: LLM 评判 / 规则评判
            ├── score: 评分（0-1）
            └── reason: 评判理由
```

**执行器（`BenchmarkRunExecutor`）**：
- 驱动 `BenchmarkTargetExecutionGateway`（智能体/应用执行接口）获取实际输出
- 通过 `BenchmarkJudgeGateway`（`BenchmarkJudgeModelGateway` 实现）调用 LLM 评判
- 支持多维度并行评测

**在线质量分析**：
- 对生产对话进行异步质量分析
- 风险等级（HIGH/MEDIUM/LOW）标记
- LLM 分析结论包含问题类型、根因、改进建议（JSONB）
- 人工复核状态跟踪

---

### 5.7 插件体系（platform-plugin）

**工具定义**：

| 工具类型 | 执行方式 | 关键配置 |
|------------|---------|----------|
| SCRIPT | 服务端脚本执行 | 脚本语言（Groovy/Python）、脚本代码 |
| HTTP | HTTP 接口调用 | HTTP 配置（JSONB，含 method/url/headers/body 模板） |
| FUNCTION | Java Bean 调用 | 处理器类（Spring Bean 全类名） |

所有工具通过入参 Schema（JSONB，JSON Schema 格式）定义入参，出参 Schema 定义出参，支持执行前需用户确认开关。

**MCP Server 管理**：
- MCP 协议类型配置
- 服务连接配置（URL、认证信息等）以 JSONB 存储
- 健康检查状态标识与最近检查时间

**Hook 机制**：
- 支持自定义 Hook 类型
- 执行方式同工具：支持 Java Bean 和脚本两种执行方式
- 执行优先级（多 Hook 时按优先级排序）

**运行时策略**：
- 工具调用确认策略（自动/手动）
- 危险级别（HIGH/MEDIUM/LOW）
- 高危工具审批流程
- 调用审计开关

---

### 5.8 系统管理（platform-system）

**RBAC 权限模型**：
```
用户 → 用户-角色关联 → 角色 → 菜单权限
```

**系统配置中心**：
- 三层结构：配置组（domain_key+group_key）→ 配置项（字段类型+组件类型）→ 配置值
- 支持环境变量覆盖，适配容器化部署
- 全量配置变更审计日志

**治理中心**（路由分组 `/governance-center`）：
- 术语管理（`TermManage`）：领域术语库，支持别名/同义词
- 同义词管理（`TermAliasManage`）：词汇扩展，用于查询改写
- 敏感策略（`SensitiveManage`）：关键词拦截策略，绑定智能体执行

---

## 6. 能力提供形式

### 6.1 能力对外暴露矩阵

| 能力域 | 管理控制台 | REST API 路径前缀 | App Token | Embed API |
|-------|-----------|-----------------|---------|-----------|
| 模型管理 | ✓ | `/api/model/**` `/api/model-provider/**` | ✗ | ✗ |
| 知识引擎 | ✓ | `/api/knowledge/**` `/api/dataset/**` `/api/document/**` | ✗ | ✗ |
| 知识检索 | ✓（测试页） | `/api/retrieval/**` | ✗ | ✗ |
| 智能体 | ✓ | `/api/agent/**` `/api/agent-session/**` | ✗ | ✗ |
| Agent 对话 | ✓ | `/api/agent-runtime/**` | ✗ | ✗ |
| 工作流 | ✓ | `/api/workflow/**` `/api/workflow-execution/**` | ✗ | ✗ |
| 应用管理 | ✓ | `/api/app/**` `/api/app-token/**` | ✗ | ✗ |
| App 对话 | ✓（管理侧） | `/api/app-runtime/**` | ✓ | ✓ |
| 评测中心 | ✓ | `/api/benchmark/**` | ✗ | ✗ |
| 插件管理 | ✓ | `/api/tool/**` `/api/hook/**` `/api/mcp/**` `/api/skill/**` | ✗ | ✗ |
| 用量分析 | ✓ | `/api/llm-usage/**` | ✗ | ✗ |
| 会话链路 | ✓ | `/api/trace/**` | ✗ | ✗ |

### 6.2 App Token 接入流程

```
管理员 → 创建 App → 生成 App Token
                          │
                          ▼
    第三方系统 / Chat 工作台
    请求头: Authorization: Bearer {token}
              │
              ▼
    EmbedAuthController（Token 验证 + 会话建立）
              │
              ▼
    会话与 Token 关联
              │
              ▼
    AppRuntimeController（App 对话执行）
```

### 6.3 SDK 集成

| SDK | 版本 | 集成方式 | 用途 |
|-----|-----|---------|------|
| AgentScope Spring Boot Starter | 1.0.10 | Maven 依赖（`io.agentscope:agentscope-spring-boot-starter`） | Agent 运行时、LLM 调用封装 |
| AgentScope AGUI Starter | 1.0.10 | Maven 依赖（`io.agentscope:agentscope-agui-spring-boot-starter`） | Agent GUI 组件 |
| LightRAG SDK | 0.1.0-local-SNAPSHOT | Maven 本地依赖 | 图谱增强检索 |
| Neo4j Java Driver | 5.28.5 | Maven 依赖 | LightRAG 图数据库访问 |

### 6.4 企业 AI 知识库连接方式

本平台与企业 AI 知识库采用**职责分离、接口对接**的协作模式，实现知识管理与智能应用的解耦。，并通过自定义来源类型的方式，定时同步，同步相关已授权文档。

---

## 7. 菜单模块设计

管理控制台按业务域划分为以下功能模块：

### 系统概览

提供平台整体运行状态的仪表盘视图。

- 平台资源统计：展示知识库数、Agent 数、应用数、会话数等关键指标
- LLM 用量趋势图：按时间维度展示模型调用趋势

### 应用构建

聚合应用、智能体、工作流三大构建模块，支撑 AI 应用的全流程开发。

| 子模块 | 功能说明 |
|-------|----------|
| 应用管理 | 应用列表（支持分类树过滤）、创建应用（配置模型/知识库/工作流）、版本发布（版本快照管理）、Token 管理（生成/吊销访问 Token）、对话测试 |
| 智能体管理 | Agent 列表（支持模式/类型过滤）、Agent 定义（基础信息+模型配置+提示词）、绑定配置（Tool/Knowledge/Hook/MCP/Skill/SubAgent）、对话测试 |
| 流程编排 | 工作流模板列表、流程编辑器（可视化节点拖拽）、Agent/Tool 节点绑定配置、工作流实例执行记录 |

### 知识中心

统一管理知识库与知识图谱，为智能体和应用提供检索能力。

| 子模块 | 功能说明 |
|-------|----------|
| 知识库管理 | 知识库列表（分类树+检索引擎类型）、数据集管理（分块参数+Embedding 配置）、文档上传工作台（批量上传+进度追踪）、文档切片管理、问题列表（问题生成+手工维护）、检索测试 |
| 知识图谱 | 图谱可视化（LightRAG 图谱管理） |

### 质量评测

内置评测中心，支持数据集版本管理、多维度评测器、实验对比。

| 子模块 | 功能说明 |
|-------|----------|
| 评测实验 | 实验列表（按 Agent/App 分类）、实验执行记录、实验结果对比 |
| 评测集 | 评测集列表（dataset_type+sample_mode）、样本管理（手工录入/Trace 导入）、版本管理（版本快照发布） |
| 评测规则 | 评测器列表、评测维度配置（LLM 评判/规则评判） |

### 运行观测

提供全链路可观测能力，覆盖会话链路、用量分析、质量监控。

| 子模块 | 功能说明 |
|-------|----------|
| 会话链路跟踪 | 链路列表（按 Agent/App 分类查询）、链路详情（节点执行时序+Tool 调用明细） |
| LLM 用量分析 | 日维度用量统计、按供应商/模型/Agent/App 多维分析 |
| 对话历史 | 全局对话记录查询（支持跨 Agent/App） |
| 回答质量分析 | 质量分析结果列表（风险等级过滤）、人工复核流程 |
| 定时任务管理 | 任务列表（Cron 表达式管理）、执行日志查看 |

### 平台集成

管理模型供应商、系统配置、插件扩展等平台级能力。

| 子模块 | 功能说明 |
|-------|----------|
| 模型管理 | 供应商管理（Provider+API Key 配置）、模型实例管理（参数配置+默认模型设置） |
| 模型计费管理 | 价格配置（有效期+输入/输出单价） |
| 系统配置 | 配置中心（分组+配置项可视化编辑） |
| MCP 管理 | MCP Server 列表、Server 健康状态监控 |
| 技能管理 | 技能包 CRUD（definition JSONB 配置） |
| Hook 管理 | Hook 配置（Java Bean/Script 执行方式） |
| 工具管理 | 工具列表（HTTP/Script/Function 分类）、工具定义（参数 Schema+执行配置） |

### 治理中心

提供术语管理、同义词管理、敏感词策略等数据治理能力。

| 子模块 | 功能说明 |
|-------|----------|
| 术语管理 | 领域术语 CRUD、发布记录 |
| 同义词管理 | 词汇扩展配置 |
| 敏感策略 | 策略列表（BLOCK/REPLACE 动作）、关键词/词组配置 |

---

## 8. 数据架构

### 8.1 数据存储策略

平台采用 PostgreSQL 17 作为主数据库，集关系型 + 向量存储于一体，无需引入独立向量数据库。Redis 7 承担会话缓存、Token 缓存等高频读写场景。

**核心存储组件**：

| 组件 | 用途 |
|------|------|
| PostgreSQL 17 | 主数据存储：业务数据、配置数据、日志数据 |
| pgvector 扩展 | 向量存储与检索（VECTOR 类型 + IVFFlat 索引） |
| Redis 7 | 会话缓存、Token 缓存、分布式锁 |
| Neo4j （可选） | LightRAG 图谱增强检索场景的图数据存储 |

### 8.2 数据域划分

数据表按业务域进行前缀分组，主要包含以下业务域：

- **系统管理域**（`sys_` 前缀）：用户、角色、菜单权限、系统参数
- **模型管理域**（`ai_model_` 前缀）：LLM 供应商、模型实例、计费配置、调用明细流水与每日聚合
- **知识引擎域**（`km_knowledge_` / `km_dataset` / `km_document` / `km_chunk` 等前缀）：知识库、数据集、文档、分块、向量、问答对
- **智能体域**（`ai_agent_` 前缀）：智能体定义、各维绑定关联、会话、消息、AgentScope 运行时状态
- **工作流域**（`km_workflow_` / `wf_` 前缀）：工作流模板、节点定义、执行实例、节点执行记录
- **应用中心域**（`km_app` 前缀）：应用定义、版本快照、Token 访问、App 会话与消息、用户反馈
- **评测中心域**（`benchmark_` 前缀）：评测集、评测器、实验配置、实验执行、样本结果与指标明细
- **插件体系域**（`ai_tool_` / `ai_hook_` / `ai_mcp_` 等前缀）：工具定义、Hook 配置、MCP Server、技能包、运行时策略
- **治理中心域**（`ai_sensitive_` / `ai_admin_` 等前缀）：敏感词策略、操作审计、系统配置中心

### 8.3 关键数据设计特点

**milvus 向量存储**：向量字段采用 VECTOR(1024) 类型，使用 IVFFlat 索引（余弦距离），1024 维度兼容主流向量化模型。

**会话追踪链路**：`trace_id` 贯穿智能体会话、消息、App 会话、工作流节点执行等多表，实现全链路可追溯。

**快照冻结机制**：评测实验在执行时冻结被测对象、数据集、评测器三方快照，确保结果可复现，不受配置变更影响。

**通用分类树**：平台提供统一的分类树结构，通过业务类型字段区分智能体/应用/知识库/工作流等不同业务域的分类，使用物化路径存储树形结构支持高效子树查询。

---

## 9. 技术架构

### 9.1 技术选型表

| 组件 | 版本 | 选型理由 |
|------|-----|---------|
| Java | 17 | LTS 版本，Record、Sealed Classes、虚拟线程基础支持 |
| Spring Boot | 3.4.9 | 最新 3.x LTS，原生支持 GraalVM，Spring AI 兼容 |
| MyBatis-Plus | 3.5.8 | 轻量 ORM，复杂查询 SQL 可控，支持 Spring Boot 3 |
| MySQL | 8 | 成熟关系型数据库， 性能优异，集成无额外基础设施 |
| Milvus  | 2.6 | 引入独立向量数据库（Milvus/Qdrant），降低运维成本 |
| Redis | 7 | 会话缓存、Token 缓存，Alpine 镜像轻量部署 |
| AgentScope | 1.0.10 | 阿里开源 Agent 框架，原生 Spring Boot 集成，支持多种 LLM 后端 |
| LightRAG | 0.1.0-local | 图谱增强 RAG，提升多跳推理场景检索质量 |
| Neo4j Driver | 5.28.5 | LightRAG 图存储后端，可选部署 |
| Lombok | 1.18.36 | 减少样板代码，与 Java 17 兼容 |
| Vue 3 | 3.x | Composition API，TypeScript 原生支持 |
| Element Plus | 当前稳定版 | 企业后台 UI 组件库，与 Vue 3 原生适配 |
| Vite | 5.x | 极速 HMR，ES Modules 原生支持，大幅优于 Webpack |
| pnpm | 10 | Monorepo 工作区支持，磁盘效率高于 npm/yarn |
| Vitest | 当前稳定版 | Vite 生态测试框架，与 TypeScript 无缝集成 |

**关键选型对比**：

| 决策点 | 选择 | 放弃 | 选择理由 |
|-------|------|------|---------|
| 向量存储 | pgvector | Milvus / Qdrant | 复用现有 Milvus |
| ORM 框架 | MyBatis-Plus | JPA/Hibernate | JSONB 复杂查询 SQL 可控，无 N+1 问题 |
| Agent 框架 | AgentScope | LangChain4j | Spring Boot Starter 成熟，阿里生态更好的中文 LLM 兼容性 |
| 图谱检索 | LightRAG | 自研 Graph RAG | LightRAG 已成熟，图谱构建与检索均已封装 |
| 前端状态管理 | Pinia（session.ts/auth.ts） | Vuex | Vue 3 官方推荐，TypeScript 类型支持更好 |

### 9.2 后端模块依赖关系

```
platform-admin（启动模块，聚合所有依赖）
    ├── platform-system    （用户/角色/权限/菜单）
    ├── platform-resource  （文件存储 OSS/本地）
    ├── platform-model     （LLM 供应商 + 模型实例 + 用量计量）
    ├── platform-knowledge （知识引擎 ETL + 检索 + 向量）
    ├── platform-agent     （Agent 定义 + AgentScope 运行时）
    ├── platform-workflow  （工作流模板 + 节点执行引擎）
    ├── platform-app       （应用中心 + Token 访问 + Chat）
    ├── platform-plugin    （Tool + Hook + MCP + Skill + Prompt）
    ├── platform-benchmark （评测数据集 + 实验执行 + 质量分析）
    ├── platform-job       （定时任务调度 + 执行日志）
    └── platform-common    （公共工具、通用响应、异常体系）
```

### 9.3 前端工程架构

```
frontend/（pnpm workspace）
    ├── apps/admin-v2     （管理控制台，主开发目标）
    │       ├── src/api/   （模块化 API 层，每个业务域独立 *.ts 文件）
    │       ├── src/views/ （页面组件，与路由一一对应）
    │       ├── src/router/（路由配置 + 菜单生成逻辑）
    │       ├── src/stores/（Pinia 状态：session / auth / theme / knowledgeUploadBatch）
    │       └── src/layouts/MainLayout.vue（主布局：左侧菜单 + 顶部栏 + 内容区）
    │
    ├── apps/chat         （用户工作台）
```

---

## 10. 部署架构

### 10.1 部署拓扑图

```
┌──────────────────────────────────────────────────────────────┐
│                         生产服务器                             │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │           应用进程（Spring Boot Fat JAR）              │    │
│  │                                                       │    │
│  │  端口 8080                                            │    │
│  │  ├── /api/**          → 管理接口（认证必须）            │    │
│  │  ├── /embed/**        → 嵌入接口（Token 认证）          │    │
│  │  └── /actuator/**     → 健康检查                       │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                               │
│  ┌──────────────────┐  ┌──────────────────────────────────┐ │
│  │  MySQL 8    │  │  Redis 7                          │ │
│  │  + milvus       │  │  端口 6379                        │ │
│  │  端口 3306         │  │  会话 / Token 缓存                │ │
│  │  库: ai_platform │  └──────────────────────────────────┘ │
│  └──────────────────┘                                        │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  前端静态资源（Nginx / CDN）                             │   │
│  │  admin 构建产物 dist/                                │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
           │（可选扩展）
           ▼
┌──────────────────────────────────────────────────────────────┐
│  Neo4j（图数据库，LightRAG 图谱增强检索启用时部署）               │
│  端口 7474 / 7687                                             │
└──────────────────────────────────────────────────────────────┘
```

### 10.2 容器化方案

`docker-compose.yml` 定义的最小运行依赖：

```yaml
services:
  mysql:              # mysql/8
    ports: 3306:3306     # 初始化脚本: schema.sql + init.sql
    healthcheck: pg_isready

redis:                 # redis:7-alpine
    ports: 6379:6379
    healthcheck: redis-cli ping
```

Spring Boot 应用本身通过 `mvn spring-boot:run`（开发）或打包成 Fat JAR 部署（生产），数据库 Schema 通过 `docker-entrypoint-initdb.d/` 自动初始化，增量 DDL 通过 `db/migrations/` 目录手动执行（共 22 个迁移脚本）。

---

## 11. 安全架构

### 11.1 认证与鉴权

**管理控制台**（admin → `/api/**`）：
- Spring Security + JWT Token 认证
- 前端 `router.beforeEach` 守卫检查 `hasActiveSession()`，未认证跳转 `/login`
- 路由级权限控制：`requiredPermissions`（`PermissionKey[]`）字段声明接口所需权限，`hasEveryPermission` 函数在导航时校验

**用户工作台 / 第三方嵌入**（`/embed/**`）：
- App Token 认证
- 允许来源字段限制访问来源
- Token 有效期管理
- 会话与 Token 关联，防止越权访问其他用户会话

**RBAC 权限模型**：
```
用户 → 角色（M:N 关联）
角色 → 菜单权限（通过权限字符串匹配）
```

### 11.2 数据安全

**敏感词过滤**：敏感词策略表定义拦截策略：
- `action=BLOCK`：直接拦截，返回错误
- `action=REPLACE`：替换敏感词（替代内容可配置）
- 智能体通过敏感策略引用绑定策略，过滤开关控制是否启用

**API Key 存储**：供应商 API Key 存储加密后的密文，支持通过环境变量注入，避免敏感凭证直接落库。