266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
# 通用 Agent 平台设计草案
|
||
|
||
## 1. 项目定位
|
||
|
||
`common_agent` 的目标是构建一个基于 Java、Spring Boot、Spring AI 的通用 Agent 平台，支持：
|
||
|
||
- 多 Agent / 单 Agent 运行
|
||
- 工具调用与流程编排
|
||
- 会话上下文管理
|
||
- RAG 知识库接入
|
||
- 文件上传与附件管理
|
||
- 前后端统一的管理控制台
|
||
|
||
当前阶段已经完成平台骨架、公共接口规范、知识库/知识文档管理、文档上传、文档解析、解析快照、手动切片入口、模型平台基础配置与 Agent 定义管理/调试入口。
|
||
后续重点从"文档可切片"推进到"向量可检索"、"模型可路由"和"Agent 运行时可编排"。
|
||
|
||
## 2. 总体设计思路
|
||
|
||
平台整体按"接入层 - 应用层 - 领域层 - 基础设施层"拆分：
|
||
|
||
- **接入层**
|
||
提供 REST API，后续可扩展 WebSocket / SSE，用于前端控制台和外部系统接入。
|
||
|
||
- **应用层**
|
||
负责请求编排、DTO 转换、统一返回体、会话协调和 Agent 调度入口。
|
||
|
||
- **领域层**
|
||
承载核心业务对象，如系统枚举、附件、知识库、知识文档、Agent 配置、任务执行记录等。
|
||
|
||
- **基础设施层**
|
||
负责数据库访问、文件存储、模型调用、向量检索、日志、缓存和第三方工具适配。
|
||
|
||
## 3. 核心模块规划
|
||
|
||
### 3.1 系统基础模块
|
||
|
||
用于支撑整个平台的通用能力：
|
||
|
||
- `sys_enum`：系统枚举配置（已完成 CRUD、批量新增、管理端查询）
|
||
- `sys_attachment`：附件与文件上传（已完成本地上传、元数据持久化）
|
||
- 文档解析抽象：`DocumentParser`、`DocumentParserFactory` 与 Tika 解析实现（已完成 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取）
|
||
- 统一 DTO / `RequestResult`（已完成）
|
||
- 通用状态枚举、启用禁用枚举（已完成）
|
||
- 全局异常处理 `GlobalExceptionHandler`（已完成）
|
||
- 公共审计字段自动填充 `EntityAuditMetaObjectHandler`（已完成）
|
||
- 后续可补用户、权限、审计等基础能力
|
||
|
||
### 3.2 RAG 知识库模块
|
||
|
||
当前已有元数据管理、文档上传和解析入口：
|
||
|
||
- `rag_store`：知识库主表（已完成 CRUD、编码唯一性校验）
|
||
- `rag_document`：知识库文档表（已完成 CRUD、条件查询、批量上传、启停用）
|
||
- `rag_chunk`：知识切片表结构、实体、Mapper、Service、定长/分隔符切片器与手动切片入口（已完成基础闭环）
|
||
- `rag_chunk_embedding`：切片向量表结构、实体、Mapper、Service（已完成结构，待模型网关接入后生成向量）
|
||
- RAG 解析状态枚举 `RagParseStatusEnum`（已完成）
|
||
- RAG 索引状态枚举 `RagIndexStatusEnum`（已完成）
|
||
- RAG 切片策略枚举 `RagChunkStrategyEnum`（已完成）
|
||
- 文档解析接口 `/api/rag/documents/parse`（已完成状态流转、文本抽取和解析快照保存）
|
||
- 文档切片接口 `/api/rag/documents/chunk`（已完成按解析快照生成并替换 `rag_chunk`）
|
||
|
||
后续计划继续扩展：
|
||
|
||
- 接入模型服务商配置与模型路由，统一管理 Ollama、硅基流动、百炼等模型来源
|
||
- 调用 Embedding 模型并写入 `rag_chunk_embedding`
|
||
- 检索召回与重排序
|
||
- 索引任务、失败重试和任务日志
|
||
|
||
当前设计原则：
|
||
|
||
- 文件物理信息放在 `sys_attachment`
|
||
- 业务归属关系通过 `storeId`、`attachmentId` 关联
|
||
- RAG 领域代码独立放在 `com.bruce.rag`
|
||
|
||
### 3.3 Agent 运行模块
|
||
|
||
当前已落地最小可用能力：
|
||
|
||
- `agent_definition`：Agent 定义管理（CRUD、编码唯一校验、知识库绑定校验）
|
||
- Agent 管理接口：`/api/agents/list`、`/api/agents/query`、`/api/agents/detail`、`/api/agents/save`、`/api/agents/delete`
|
||
- Agent 调试接口：`POST /api/agents/{agentId}/chat`，支持普通对话与 RAG 对话两种模式
|
||
- Agent 调试链路：用户问题向量化 -> `rag_chunk_embedding` 相似度召回 -> 组装上下文 -> Chat 模型回答 -> 返回引用切片
|
||
- 统一模型调用日志：通过 `ChatModelGateway` 与 `model_call_log` 记录请求 ID、模型、耗时与 token 信息
|
||
|
||
后续平台重点能力：
|
||
|
||
- Prompt 模板管理
|
||
- 会话上下文持久化与记忆
|
||
- 工具注册与调用协议
|
||
- 执行任务状态与日志
|
||
- 多步骤编排
|
||
|
||
建议后续补齐的核心对象：
|
||
|
||
- `agent_session`
|
||
- `agent_message`
|
||
- `agent_task`
|
||
- `agent_tool`
|
||
|
||
### 3.4 管理控制台模块
|
||
|
||
当前已建立基于 Vue 3、Vite、TypeScript、Element Plus 的前端控制台。
|
||
|
||
已具备的页面与布局：
|
||
|
||
- 左侧管理菜单与品牌区（232px 侧边栏）
|
||
- RAG 工作台（文档解析与切片概览）
|
||
- 系统枚举管理页（完整 CRUD + 批量新增）
|
||
- 附件管理入口（占位）
|
||
- 知识库管理页（完整 CRUD + 概览卡片 + 双栏详情 + 批量上传入口）
|
||
- 知识文档页（条件查询 + 批量上传 + 解析重试 + 批量切片 + 编辑/启停用/删除）
|
||
- 切片任务页（解析成功/失败文档概览与切片入口）
|
||
- Agent 管理页（Agent 定义管理与知识库绑定）
|
||
- Agent 调试页（普通对话 / RAG 对话切换、引用切片回显）
|
||
|
||
前端技术要点：
|
||
|
||
- Composition API + `<script setup lang="ts">`
|
||
- Axios 封装，统一 `/api` 前缀，`RequestResult<T>` 信封解包
|
||
- Long 类型安全解析（`json-bigint` 防止 JS 精度丢失）
|
||
- 全局错误拦截与 Element Plus 弹窗提示
|
||
- Vitest + @vue/test-utils 单元测试
|
||
|
||
当前样式约定：
|
||
|
||
- 管理控制台定位为后台工具界面，优先保证信息密度、可扫描性和稳定布局。
|
||
- 主内容区域只保留页面自身标题，避免外层布局和页面面板重复展示标题。
|
||
- 页面统一使用 `page-panel` 作为内容容器，侧边栏、页面面板、工具栏和表格使用统一边框、背景和主色变量。
|
||
- 全局样式集中在 `frontend/src/styles/global.css`，页面专属样式在对应 `.vue` 文件的 scoped style 中。
|
||
|
||
后续控制台至少继续覆盖：
|
||
|
||
- 附件管理页面前端联调
|
||
- RAG 检索配置、向量索引任务和最近任务页面联调
|
||
- 模型服务商、模型配置、路由规则和调用日志管理
|
||
- Agent 会话历史与运行日志页
|
||
- 执行日志查看
|
||
|
||
## 4. 当前接口设计原则
|
||
|
||
项目统一遵循这些规则：
|
||
|
||
1. `controller` 不直接暴露实体类
|
||
所有请求和响应走 DTO。
|
||
|
||
2. `service` 以 DTO 为边界
|
||
持久化实体只在内部流转，不直接穿透到外层接口。
|
||
|
||
3. 查询条件使用请求 DTO
|
||
统一使用 `QueryRequest` / `SaveRequest` / `Response` 形式。
|
||
|
||
4. 统一返回体
|
||
使用 `RequestResult<T>` 作为标准响应包装。
|
||
|
||
5. 基础枚举统一化
|
||
通用状态、启用禁用、RAG 解析/索引状态等统一管理。
|
||
|
||
6. OpenAPI 注解覆盖
|
||
所有 Controller、DTO 使用 `@Tag`、`@Operation`、`@Schema` 注解。
|
||
|
||
## 4.1 代码注释约定
|
||
|
||
为方便后续多人协作和 Agent 接力阅读，新增以下约定：
|
||
|
||
1. 新增或修改核心业务代码时，需要补充中文注释
|
||
注释优先覆盖类职责、关键方法、关键分支和重要参数含义，避免只写重复代码字面的无效注释。
|
||
|
||
2. 每次提交代码时，同步检查对应改动是否已经补齐中文注释
|
||
尤其是新引入的工厂、策略、服务编排、状态流转和复杂转换逻辑，默认需要有中文说明。
|
||
|
||
3. 注释以“帮助后来者快速理解设计意图”为目标
|
||
不追求注释数量，重点说明为什么这样做、边界是什么、哪些地方后续还会扩展。
|
||
|
||
## 4.2 结构化枚举约定
|
||
|
||
为保证前后端协议、代码定义和数据库配置一致，新增以下长期规则：
|
||
|
||
1. 长期固定的结构化文本字段，统一采用枚举值传输
|
||
不再以字符串名称作为接口协议值，前后端统一传整型枚举值。
|
||
|
||
2. 这类枚举必须先定义为 Java 枚举类
|
||
Java 枚举类作为单一事实来源，再派生前端常量和 `sys_enum` 配置。
|
||
|
||
3. 每次新增或修改结构化枚举时，必须同步纳入 `sys_enum` 初始化测试
|
||
通过统一测试入口按 `catalog + type` 先删后全量重建，避免数据库枚举配置漂移。
|
||
|
||
4. `catalog + type` 在枚举组层面必须唯一
|
||
一旦重复，会破坏枚举组重建语义，因此视为非法设计。
|
||
|
||
## 5. 数据与存储设计
|
||
|
||
### 5.1 关系型数据库
|
||
|
||
当前主数据库使用 PostgreSQL。
|
||
|
||
已确定的方向：
|
||
|
||
- 业务表采用 PostgreSQL 规范 SQL
|
||
- 主键使用 MyBatis-Plus `ASSIGN_ID`
|
||
- 通用字段沉淀到 `BaseEntity`（含审计字段 + 乐观锁 `version`）
|
||
- 审计字段通过 `EntityAuditMetaObjectHandler` 自动填充
|
||
|
||
### 5.2 向量能力
|
||
|
||
知识库检索阶段优先使用 PostgreSQL + `pgvector`：
|
||
|
||
- 统一技术栈
|
||
- 降低部署复杂度
|
||
- 便于关系数据与向量数据联动
|
||
|
||
适合项目当前阶段的中小规模知识库场景。
|
||
|
||
### 5.3 文件存储
|
||
|
||
当前使用本地文件存储（`AttachmentProperties.basePath` 默认 `data/attachments`），后续可抽象成：
|
||
|
||
- 本地文件系统
|
||
- MinIO / S3
|
||
- 其他对象存储
|
||
|
||
## 6. 当前阶段开发优先级
|
||
|
||
1. ~~统一接口层规范~~ DTO、返回体、基础校验、通用异常处理（已完成）
|
||
2. ~~收紧基础模块~~ `sys_enum`、`sys_attachment`（已完成）
|
||
3. ~~补全 RAG 基础元数据管理~~ `rag_store`、`rag_document`（已完成）
|
||
4. ~~补全 RAG 文档上传与解析入口~~ 批量上传、Tika 文本抽取、解析状态流转（已完成）
|
||
5. ~~接入切片生成与切片持久化~~（已完成定长/分隔符切片与手动切片入口）
|
||
6. 建设模型服务商配置与模型路由层
|
||
7. 接入 Embedding / Chat 模型并完成向量写入
|
||
8. 完善 Agent 运行时骨架（会话、工具、任务）
|
||
9. ~~补前端控制台基础骨架~~（已完成，部分高级页面待联调）
|
||
|
||
剩余重点：
|
||
|
||
- 完成模型服务商配置、模型配置、路由规则和调用日志基础能力
|
||
- 接入 Embedding，生成并保存 `rag_chunk_embedding`
|
||
- 补齐索引任务、重试、重建索引和最近任务接口
|
||
- 扩展 Agent 会话、工具调用与任务编排能力
|
||
|
||
## 7. 下一步建议
|
||
|
||
结合当前代码状态，接下来建议重点做：
|
||
|
||
- 完成 RAG 全量向量化链路，确保知识库可稳定召回
|
||
- 为 Agent 调试链路补齐会话持久化与多轮上下文管理
|
||
- 建立 Agent 工具注册与调用协议，沉淀最小工具集
|
||
- 把 `indexStatus` 从手工字段推进为真实状态流转
|
||
- 补齐重建索引、失败重试、最近任务接口和前端展示
|
||
|
||
## 8. 文档用途说明
|
||
|
||
本文件是项目级的 Agent 平台设计入口文档，当前用于：
|
||
|
||
- 对齐项目方向
|
||
- 固定基础架构思路
|
||
- 作为后续详细设计和模块拆分的上层说明
|
||
|
||
后续可继续拆成：
|
||
|
||
- `agent-runtime.md`
|
||
- `rag-design.md`
|
||
- `MODEL_PROVIDER_REQUIREMENTS.md`
|
||
- `MODEL_PROVIDER_DESIGN.md`
|
||
- `api-style.md`
|
||
- `frontend-console.md`
|