207 lines
5.4 KiB
Markdown
207 lines
5.4 KiB
Markdown
# 通用 Agent 平台设计草案
|
||
|
||
## 1. 项目定位
|
||
|
||
`common_agent` 的目标是构建一个基于 Java、Spring Boot、Spring AI 的通用 Agent 平台，支持：
|
||
|
||
- 多 Agent / 单 Agent 运行
|
||
- 工具调用与流程编排
|
||
- 会话上下文管理
|
||
- RAG 知识库接入
|
||
- 文件上传与附件管理
|
||
- 前后端统一的管理控制台
|
||
|
||
当前阶段以“先搭平台骨架，再逐步补智能能力”为主，优先保证工程结构、接口规范、知识库链路和可扩展性。
|
||
|
||
## 2. 总体设计思路
|
||
|
||
平台整体按“接入层 - 应用层 - 领域层 - 基础设施层”拆分：
|
||
|
||
- 接入层
|
||
提供 REST API、后续可扩展 WebSocket / SSE，用于前端控制台和外部系统接入。
|
||
|
||
- 应用层
|
||
负责请求编排、DTO 转换、统一返回体、会话协调和 Agent 调度入口。
|
||
|
||
- 领域层
|
||
承载核心业务对象，如系统枚举、附件、知识库、知识文档、Agent 配置、任务执行记录等。
|
||
|
||
- 基础设施层
|
||
负责数据库访问、文件存储、模型调用、向量检索、日志、缓存和第三方工具适配。
|
||
|
||
## 3. 核心模块规划
|
||
|
||
### 3.1 系统基础模块
|
||
|
||
用于支撑整个平台的通用能力：
|
||
|
||
- `sys_enum`：系统枚举配置
|
||
- `sys_attachment`：附件与文件上传
|
||
- 统一 DTO / `RequestResult`
|
||
- 通用状态枚举、启用禁用枚举
|
||
- 后续可补用户、权限、审计等基础能力
|
||
|
||
### 3.2 RAG 知识库模块
|
||
|
||
当前已经有初步表设计与 Java 骨架：
|
||
|
||
- `rag_store`：知识库主表
|
||
- `rag_document`：知识库文档表
|
||
|
||
后续计划继续扩展：
|
||
|
||
- 文档切片
|
||
- 向量化
|
||
- 检索召回
|
||
- 索引任务
|
||
|
||
当前设计原则：
|
||
|
||
- 文件物理信息放在 `sys_attachment`
|
||
- 业务归属关系通过 `source_type`、`source_id` 或文档关联字段承接
|
||
- RAG 领域代码独立放在 `com.bruce.rag`
|
||
|
||
### 3.3 Agent 运行模块
|
||
|
||
后续平台重点能力，建议逐步补齐：
|
||
|
||
- Agent 定义
|
||
- Prompt 模板
|
||
- 工具注册与调用
|
||
- 会话上下文与记忆
|
||
- 执行日志与任务状态
|
||
- 多步骤编排
|
||
|
||
建议未来增加的核心对象：
|
||
|
||
- `agent_definition`
|
||
- `agent_session`
|
||
- `agent_message`
|
||
- `agent_task`
|
||
- `agent_tool`
|
||
|
||
### 3.4 管理控制台模块
|
||
|
||
当前已经建立基于 Vue 3、Vite、Element Plus 的前端控制台基础骨架。
|
||
|
||
已具备的页面与布局：
|
||
|
||
- 左侧管理菜单与品牌区
|
||
- 工作台入口
|
||
- 系统枚举管理页
|
||
- 附件管理入口
|
||
- 知识库入口
|
||
- 知识文档入口
|
||
|
||
当前样式约定：
|
||
|
||
- 管理控制台定位为后台工具界面，优先保证信息密度、可扫描性和稳定布局。
|
||
- 主内容区域只保留页面自身标题，避免外层布局和页面面板重复展示标题。
|
||
- 页面统一使用 `page-panel` 作为内容容器，侧边栏、页面面板、工具栏和表格使用统一边框、背景和主色变量。
|
||
- 系统枚举页工具栏采用响应式布局，桌面端保持查询项和操作按钮分区，窄屏时纵向排列。
|
||
|
||
后续控制台至少继续覆盖：
|
||
|
||
- 枚举管理
|
||
- 附件管理
|
||
- 知识库管理
|
||
- 文档上传与状态查看
|
||
- Agent 调试页
|
||
- 执行日志查看
|
||
|
||
## 4. 当前接口设计原则
|
||
|
||
项目后续统一遵循这些规则：
|
||
|
||
1. `controller` 不直接暴露实体类
|
||
所有请求和响应优先走 DTO。
|
||
|
||
2. `service` 尽量以 DTO 为边界
|
||
持久化实体只在内部流转，不直接穿透到外层接口。
|
||
|
||
3. 查询条件不直接使用多个裸参数
|
||
尽量改成 `QueryRequest` / `SaveRequest` / `Response` 形式。
|
||
|
||
4. 统一返回体
|
||
使用 `RequestResult<T>` 作为标准响应包装。
|
||
|
||
5. 基础枚举统一化
|
||
通用状态、启用禁用、RAG 解析/索引状态等统一管理。
|
||
|
||
## 5. 数据与存储设计
|
||
|
||
### 5.1 关系型数据库
|
||
|
||
当前主数据库使用 PostgreSQL。
|
||
|
||
已确定的方向：
|
||
|
||
- 业务表采用 PostgreSQL 规范 SQL
|
||
- 主键使用 MyBatis-Plus `ASSIGN_ID`
|
||
- 通用字段沉淀到 `BaseEntity`
|
||
|
||
### 5.2 向量能力
|
||
|
||
知识库检索阶段优先使用 PostgreSQL + `pgvector`：
|
||
|
||
- 统一技术栈
|
||
- 降低部署复杂度
|
||
- 便于关系数据与向量数据联动
|
||
|
||
适合项目当前阶段的中小规模知识库场景。
|
||
|
||
### 5.3 文件存储
|
||
|
||
当前先走本地文件存储，后续可抽象成：
|
||
|
||
- 本地文件系统
|
||
- MinIO / S3
|
||
- 其他对象存储
|
||
|
||
## 6. 当前阶段开发优先级
|
||
|
||
建议优先顺序如下：
|
||
|
||
1. 统一接口层规范
|
||
DTO、返回体、基础校验、通用异常处理
|
||
|
||
2. 收紧基础模块
|
||
`sys_enum`、`sys_attachment`
|
||
|
||
3. 补全 RAG 基础业务闭环
|
||
`rag_store`、`rag_document`、文件归属、文档状态
|
||
|
||
4. 接入 Spring AI
|
||
|
||
5. 建立 Agent 运行时骨架
|
||
|
||
6. 补前端控制台
|
||
|
||
当前前端控制台已经完成基础骨架和系统枚举页面样式优化，后续重点应转向附件、知识库、知识文档页面的业务闭环。
|
||
|
||
## 7. 下一步建议
|
||
|
||
结合当前代码状态，接下来建议重点做：
|
||
|
||
- 完成现有三块接口 DTO 化改造
|
||
- 建立统一异常处理和错误码规范
|
||
- 完善 `rag_store` / `rag_document` 的增删改查
|
||
- 增加知识库文档上传并自动关联附件
|
||
- 为后续切片与向量化预留任务入口
|
||
- 补齐前端附件、知识库、知识文档页面的表单、列表和接口联调
|
||
|
||
## 8. 文档用途说明
|
||
|
||
本文件是项目级的 Agent 平台设计入口文档，当前用于：
|
||
|
||
- 对齐项目方向
|
||
- 固定基础架构思路
|
||
- 作为后续详细设计和模块拆分的上层说明
|
||
|
||
后续可继续拆成：
|
||
|
||
- `agent-runtime.md`
|
||
- `rag-design.md`
|
||
- `api-style.md`
|
||
- `frontend-console.md`
|