67cfbeb572
AGENT.md、README.md、ARCHITECTURE.md、ROADMAP.md 已根据最新代码更新： - 补充 DTO 层、统一返回体、全局异常处理、审计自动填充等已完成项 - 更新前端控制台架构描述与页面实现状态 - 调整 RAG 模块状态描述（元数据层已完成，业务闭环待建设） - 移除 docs 目录的 .gitignore 排除规则 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
189 lines
7.3 KiB
Markdown
189 lines
7.3 KiB
Markdown
# Common Agent
|
||
|
||
Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。
|
||
项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。
|
||
|
||
当前项目处于基础工程阶段。后端骨架（含 DTO、统一返回体、全局异常处理、审计自动填充）、PostgreSQL 配置、MyBatis-Plus、Lombok、多环境配置文件和前端控制台基础页面已经完成；
|
||
Agent 运行时、RAG 文档解析与向量化和更多管理功能会在后续阶段逐步实现。
|
||
|
||
## 项目愿景
|
||
|
||
Common Agent 希望成为一个可复用的企业级 AI 应用基础平台：
|
||
|
||
- Agent 运行时：支持对话、工具调用、记忆、任务执行和流程编排。
|
||
- RAG 知识库：支持文档导入、解析、切片、向量化、检索和基于上下文的回答生成。
|
||
- 模型抽象：通过 Spring AI 统一接入聊天模型、Embedding 模型和重排序模型。
|
||
- 管理控制台：提供会话、Agent、知识库、文档、提示词和系统配置的 Web 管理界面。
|
||
- 多环境部署：支持本地开发、测试环境和生产环境的配置隔离。
|
||
|
||
## 当前技术栈
|
||
|
||
| 类别 | 技术 |
|
||
|------|------|
|
||
| 后端 | Java 21, Spring Boot 4.0.6, MyBatis-Plus 3.5.16 |
|
||
| 数据库 | PostgreSQL |
|
||
| 工具库 | Lombok, Springdoc OpenAPI 2.8.13, Jackson |
|
||
| 构建 | Maven Wrapper |
|
||
| 前端 | Vue 3, TypeScript 5.9, Vite, Element Plus, Pinia, Vue Router 4 |
|
||
| 前端测试 | Vitest, @vue/test-utils |
|
||
| 后端测试 | Spring Boot Test |
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
common_agent
|
||
├── frontend/ # Vue 3 前端控制台
|
||
│ ├── src/
|
||
│ │ ├── api/ # Axios 封装与各模块 API
|
||
│ │ ├── layouts/ # AdminLayout 管理后台布局
|
||
│ │ ├── pages/ # 业务页面（工作台、枚举、附件、知识库、文档）
|
||
│ │ ├── router/ # Vue Router 配置
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── styles/ # 全局样式
|
||
│ │ └── types/ # TypeScript 类型声明
|
||
│ └── package.json
|
||
├── src/
|
||
│ ├── main/java/com/bruce/
|
||
│ │ ├── CommonAgentApplication.java
|
||
│ │ ├── common/ # 公共模块
|
||
│ │ │ ├── config/ # AttachmentProperties, EntityAuditMetaObjectHandler
|
||
│ │ │ ├── controller/ # SysAttachmentController, SysEnumController
|
||
│ │ │ ├── domain/
|
||
│ │ │ │ ├── entity/ # SysAttachment, SysEnum
|
||
│ │ │ │ └── model/ # BaseEntity, RequestResult
|
||
│ │ │ ├── dto/
|
||
│ │ │ │ ├── request/ # 各模块请求 DTO
|
||
│ │ │ │ └── response/ # 各模块响应 DTO
|
||
│ │ │ ├── enums/ # CommonStatusEnum, EnableStatusEnum
|
||
│ │ │ ├── handler/ # GlobalExceptionHandler
|
||
│ │ │ ├── mapper/ # SysAttachmentMapper, SysEnumMapper
|
||
│ │ │ └── service/ # 接口与实现
|
||
│ │ └── rag/ # RAG 知识库模块
|
||
│ │ ├── constant/ # RagSystemConstants
|
||
│ │ ├── controller/ # RagStoreController, RagDocumentController
|
||
│ │ ├── dto/ # 请求/响应 DTO
|
||
│ │ ├── entity/ # RagStore, RagDocument
|
||
│ │ ├── enums/ # RagParseStatusEnum, RagIndexStatusEnum
|
||
│ │ ├── mapper/ # RagDocumentMapper, RagStoreMapper
|
||
│ │ └── service/ # 接口与实现
|
||
│ ├── main/resources/
|
||
│ │ ├── application.yaml # 环境选择
|
||
│ │ ├── application-dev.yaml # 开发环境配置
|
||
│ │ └── application-template.yaml # 配置模板
|
||
│ └── test/java/ # 单元测试（结构稳定性测试 + 前端 API 测试）
|
||
├── docs/
|
||
│ ├── ARCHITECTURE.md # 架构说明
|
||
│ └── ROADMAP.md # 开发路线图
|
||
├── AGENT.md # 平台设计草案
|
||
├── pom.xml
|
||
└── README.md
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
主配置文件只负责选择当前环境：
|
||
|
||
```yaml
|
||
spring:
|
||
application:
|
||
name: common_agent
|
||
profiles:
|
||
active: dev
|
||
```
|
||
|
||
本地开发环境配置位于 `src/main/resources/application-dev.yaml`。
|
||
当前开发环境数据库指向 PostgreSQL：
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
driver-class-name: org.postgresql.Driver
|
||
url: jdbc:postgresql://110.42.106.130:5431/common_agent?currentSchema=common_agent
|
||
username: common_agent
|
||
password: common_agent
|
||
```
|
||
|
||
`src/main/resources/application-template.yaml` 是配置模板，可用于复制生成
|
||
`application-test.yaml`、`application-prod.yaml` 等其他环境配置文件。
|
||
|
||
## 运行方式
|
||
|
||
运行测试：
|
||
|
||
```bash
|
||
./mvnw test
|
||
```
|
||
|
||
启动应用：
|
||
|
||
```bash
|
||
./mvnw spring-boot:run
|
||
```
|
||
|
||
启动前端：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
前端检查：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run test:unit
|
||
npm run type-check
|
||
npm run build
|
||
```
|
||
|
||
## 前端控制台
|
||
|
||
前端控制台位于 `frontend` 目录，当前使用 Vue 3、Vite、Pinia、Vue Router 和 Element Plus。
|
||
|
||
当前已有页面：
|
||
|
||
| 页面 | 状态 |
|
||
|------|------|
|
||
| 工作台 | 占位 |
|
||
| 系统枚举 | 完整 CRUD + 批量新增 |
|
||
| 附件管理 | 占位 |
|
||
| 知识库 | 完整 CRUD + 双栏详情 |
|
||
| 知识文档 | 占位 |
|
||
|
||
当前 UI 规范：
|
||
|
||
- 左侧为固定管理导航，右侧为主内容区。
|
||
- 主内容区不再额外渲染外层页面标题，标题由各业务页面面板自行展示。
|
||
- 全局样式集中在 `frontend/src/styles/global.css`，页面专属样式优先放在对应 `.vue` 文件的 scoped style 中。
|
||
- 后台页面以清晰、克制、便于扫描为优先目标，避免营销式大面积装饰。
|
||
|
||
## 接口规范
|
||
|
||
- 统一返回体：`RequestResult<T>`（`resultcode`, `message`, `data`）
|
||
- 所有接口通过 DTO 交互，不直接暴露实体
|
||
- 查询条件封装为 `XxxQueryRequest`
|
||
- 响应 DTO 提供 `fromEntity()` 静态转换
|
||
- 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 防止前端精度丢失
|
||
- 全局异常处理返回 HTTP 400/500 状态码
|
||
|
||
## 规划模块
|
||
|
||
- `agent-core`：Agent 执行模型、工具注册、记忆和编排能力。
|
||
- `rag-core`：文档导入、切片、Embedding、检索和引用元数据。
|
||
- `model-provider`：基于 Spring AI 的聊天模型、Embedding、重排序和模型配置层。
|
||
- `platform-api`：面向前端和外部系统的 REST API。
|
||
- `platform-admin`：平台管理前端。
|
||
- `common-infra`：持久化、审计日志、安全、租户隔离和可观测性。
|
||
|
||
## 文档
|
||
|
||
- [架构说明](docs/ARCHITECTURE.md)
|
||
- [开发路线图](docs/ROADMAP.md)
|
||
- [平台设计草案](AGENT.md)
|
||
|
||
## 参考资料
|
||
|
||
- [Spring AI Reference](https://docs.spring.io/spring-ai/reference/)
|
||
- [Spring AI RAG Reference](https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html)
|
||
- [MyBatis-Plus](https://baomidou.com/) |