common_agent/README.md

# Common Agent

Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。
项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。

当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、解析快照、手动切片入口、模型服务商配置基础能力、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, Apache Tika 3.2.3 |
| 构建 | 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/                     # 业务页面（系统、RAG、Agent）
│   │   ├── router/                    # Vue Router 配置
│   │   ├── stores/                    # Pinia 状态管理
│   │   ├── styles/                    # 全局样式
│   │   └── types/                     # TypeScript 类型声明
│   └── package.json
├── src/
│   ├── main/java/com/bruce/
│   │   ├── CommonAgentApplication.java
│   │   ├── common/                    # 公共模块
│   │   │   ├── config/                # AttachmentProperties, EntityAuditMetaObjectHandler
│   │   │   ├── controller/            # SysAttachmentController, SysEnumController
│   │   │   ├── document/parse/        # 文档解析抽象与 Tika 实现
│   │   │   ├── 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, RagChunk, RagChunkEmbedding
│   │   │   ├── enums/                 # RagParseStatusEnum, RagIndexStatusEnum, RagChunkStrategyEnum
│   │   │   ├── mapper/                # RagDocumentMapper, RagStoreMapper
│   │   │   └── service/               # 接口与实现
│   │   ├── modelprovider/             # 模型服务商、模型配置、路由、网关与调用日志
│   │   └── agent/                     # Agent 定义管理与调试链路
│   ├── main/resources/
│   │   ├── application.yaml           # 环境选择
│   │   ├── application-dev.yaml       # 开发环境配置
│   │   └── application-template.yaml  # 配置模板
│   └── test/java/                     # 单元测试（结构稳定性测试 + 前端 API 测试）
├── docs/
│   ├── ARCHITECTURE.md                # 架构说明
│   ├── ROADMAP.md                     # 开发路线图
│   ├── MODEL_PROVIDER_REQUIREMENTS.md # 模型服务商配置与路由需求
│   ├── MODEL_PROVIDER_DESIGN.md       # 模型服务商配置与路由设计
│   └── MODEL_PROVIDER_SCHEMA.sql      # 模型平台与Agent核心表结构
├── AGENT.md                           # 平台设计草案
├── agent-page-apis.md                 # Agent页面后端接口清单
├── 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。

当前已有页面：

| 页面 | 状态 |
|------|------|
| RAG 工作台 | 文档解析与切片概览 |
| 系统枚举 | 完整 CRUD + 批量新增 |
| 附件管理 | 占位 |
| 知识库 | 完整 CRUD + 双栏详情 |
| 知识文档 | 条件查询 + 批量上传 + 解析重试 + 批量切片 + 编辑/启停用/删除 |
| 切片任务 | 解析成功/失败文档概览 + 切片入口 |
| Agent管理 | Agent 定义 CRUD + 知识库绑定 |
| Agent调试 | 普通对话 / RAG 对话切换 + 引用切片回显 |

当前 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 状态码

## RAG 当前能力边界

当前 RAG 已经从元数据管理推进到"上传 + 解析 + 手动切片 + Agent 调试召回"阶段：

- 知识库：支持列表、条件查询、详情、总览、单库文档概览、新增、编辑、删除。
- 知识文档：支持列表、条件查询、详情、新增/编辑、删除、批量上传。
- 文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新 `parseStatus` 并保存解析快照。
- 文档切片：支持按解析快照进行手动异步切片，已落地定长切片和分隔符切片，写入 `rag_chunk`。
- 向量表：`rag_chunk_embedding` 实体、Mapper、Service 已有结构，向量写入与召回 SQL 已用于 Agent 调试链路，RAG 检索问答接口仍待补齐。
- 模型配置：模型服务商、模型配置、路由规则、调用日志基础能力已落地，Embedding/Chat 网关可用于 RAG 与 Agent 调试调用。
- 前端：知识库页、知识文档页、RAG 工作台和切片任务页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。

## Agent 当前能力边界

- Agent 定义：支持 `agent_definition` 的列表、查询、详情、新增/更新、删除。
- Agent 对话：支持 `POST /api/agents/{agentId}/chat`，`ragEnabled=true` 时走 RAG 召回，`false` 时走普通对话。
- RAG 对话流程：用户问题向量化 -> 按知识库召回 TopK 切片 -> 组装系统提示词与上下文 -> Chat 模型回答。
- 调试回显：返回答案、请求 ID 和引用切片，便于前端页面展示与排障。
- 当前限制：尚未持久化 `agent_session/agent_message`，工具调用和任务编排仍在规划中。

## 规划模块

- `agent-core`：Agent 执行模型、工具注册、记忆和编排能力。
- `rag-core`：文档导入、解析、切片、Embedding、检索和引用元数据。
- `model-provider`：模型服务商配置、模型路由、调用日志，以及基于 OpenAI-compatible / Spring AI 的聊天模型、Embedding、重排序适配层。
- `platform-api`：面向前端和外部系统的 REST API。
- `platform-admin`：平台管理前端。
- `common-infra`：持久化、审计日志、安全、租户隔离和可观测性。

## 文档

- [架构说明](docs/ARCHITECTURE.md)
- [开发路线图](docs/ROADMAP.md)
- [模型服务商配置与路由需求](docs/MODEL_PROVIDER_REQUIREMENTS.md)
- [模型服务商配置与路由设计](docs/MODEL_PROVIDER_DESIGN.md)
- [平台设计草案](AGENT.md)
- [Agent 页面接口清单](agent-page-apis.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/)