From d7dcf4c8e8706b026178cb2d58c77d47775dae66 Mon Sep 17 00:00:00 2001
From: bruce <sunzhiye01@outlook.com>
Date: Tue, 19 May 2026 07:45:29 +0800
Subject: [PATCH] =?UTF-8?q?ft:=E5=BC=95=E5=85=A5=E6=8F=90=E7=A4=BA?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6AGENT.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENT.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 AGENT.md

diff --git a/AGENT.md b/AGENT.md
new file mode 100644
index 0000000..2273b28
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1,185 @@
+# 通用 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 管理控制台模块
+
+后续需要一个前端控制台，至少覆盖：
+
+- 枚举管理
+- 附件管理
+- 知识库管理
+- 文档上传与状态查看
+- 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`