common_agent/AGENT.md

通用 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：系统枚举配置（已完成 CRUD、批量新增、管理端查询）
• sys_attachment：附件与文件上传（已完成本地上传、元数据持久化）
• 统一 DTO / RequestResult（已完成）
• 通用状态枚举、启用禁用枚举（已完成）
• 全局异常处理 GlobalExceptionHandler（已完成）
• 公共审计字段自动填充 EntityAuditMetaObjectHandler（已完成）
• 后续可补用户、权限、审计等基础能力

3.2 RAG 知识库模块

当前已有完整的元数据管理层：

• rag_store：知识库主表（已完成 CRUD、编码唯一性校验）
• rag_document：知识库文档表（已完成实体、Mapper、Service、条件查询）
• RAG 解析状态枚举 RagParseStatusEnum（已完成）
• RAG 索引状态枚举 RagIndexStatusEnum（已完成）

后续计划继续扩展：

• 文档切片
• 向量化
• 检索召回
• 索引任务

当前设计原则：

• 文件物理信息放在 sys_attachment
• 业务归属关系通过 storeId、attachmentId 关联
• RAG 领域代码独立放在 com.bruce.rag

3.3 Agent 运行模块

后续平台重点能力，建议逐步补齐：

• Agent 定义
• Prompt 模板
• 工具注册与调用
• 会话上下文与记忆
• 执行日志与任务状态
• 多步骤编排

建议未来增加的核心对象：

• agent_definition
• agent_session
• agent_message
• agent_task
• agent_tool

3.4 管理控制台模块

当前已建立基于 Vue 3、Vite、TypeScript、Element Plus 的前端控制台。

已具备的页面与布局：

• 左侧管理菜单与品牌区（232px 侧边栏）
• 工作台（占位）
• 系统枚举管理页（完整 CRUD + 批量新增）
• 附件管理入口（占位）
• 知识库管理页（完整 CRUD + 双栏详情）
• 知识文档入口（占位）

前端技术要点：

• 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 中。

后续控制台至少继续覆盖：

• 附件管理页面前端联调
• 知识文档管理页面前端联调
• 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 注解。

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. 接入 Spring AI
5. 建立 Agent 运行时骨架
6. 补前端控制台基础骨架（已完成，部分页面待联调）

剩余重点：

• 完善 RAG 文档上传、解析、索引的业务闭环
• 补齐前端附件管理、知识文档页面的表单与接口联调
• 接入 Spring AI 并实现模型调用链路

7. 下一步建议

结合当前代码状态，接下来建议重点做：

• 实现知识库文档上传并自动创建 rag_document 记录
• 建立文档解析任务入口与状态流转
• 为后续切片与向量化预留任务入口
• 补齐前端附件管理、知识文档页面的联调
• 接入 Spring AI，实现最小模型调用链路

8. 文档用途说明

本文件是项目级的 Agent 平台设计入口文档，当前用于：

• 对齐项目方向
• 固定基础架构思路
• 作为后续详细设计和模块拆分的上层说明

后续可继续拆成：

• agent-runtime.md
• rag-design.md
• api-style.md
• frontend-console.md