# Common Agent 开发路线图

本文档基于 2026-05-24 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。

## 已完成

### 基础工程

- Spring Boot 4.0.6 后端工程初始化。
- PostgreSQL 数据源与多环境配置文件（dev / template）。
- MyBatis-Plus 3.5.16、Lombok、Springdoc OpenAPI 2.8.13 已接入。
- Apache Tika 3.2.3 已接入，用于文档文本抽取。
- Maven Wrapper。

### 公共能力

- `BaseEntity` 公共字段模型（主键、审计字段、乐观锁）。
- `EntityAuditMetaObjectHandler` 审计字段自动填充。
- `RequestResult<T>` 统一 API 返回体。
- `GlobalExceptionHandler` 全局异常处理。
- `AttachmentProperties` 附件本地存储配置。
- 文档解析抽象：`DocumentParser`、`DocumentParserFactory`、`DocumentParseContext`、`DocumentParseResult`。
- Tika 解析实现：TXT/Markdown/LOG、PDF、Word、Excel。
- `sys_enum` 完整能力：实体、Mapper、Service、Controller、DTO 层。
  - 支持单条增删改查、批量新增、管理端条件查询（含关键词搜索）。
  - 批量新增内含重复值校验。
- `sys_attachment` 完整能力：实体、Mapper、Service、Controller、DTO 层。
  - 支持本地文件上传、UUID 文件名、日期目录分层、元数据持久化。

### RAG 基础能力

- `rag_store`、`rag_document` 表结构与实体定义。
- `rag_chunk`、`rag_chunk_embedding` 表结构与实体定义。
- RAG 知识库完整 CRUD（含编码唯一性校验）。
- 知识文档完整 CRUD、条件查询、批量上传。
- 文档解析入口：支持批量提交文档 ID，按切片策略参数发起解析，状态流转为 PARSING / PARSED / FAILED。
- 知识库总览接口与单库文档概览接口。
- RAG 解析状态枚举 `RagParseStatusEnum`（UPLOADED / PARSING / PARSED / FAILED）。
- RAG 索引状态枚举 `RagIndexStatusEnum`（PENDING / INDEXING / INDEXED / FAILED）。
- RAG 切片策略枚举 `RagChunkStrategyEnum`（FIXED_LENGTH / PARAGRAPH / HEADING / TABLE_ROW / DELIMITER / SEMANTIC）。
- RAG 来源常量 `RagSystemConstants`。

### 前端控制台

- Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router 工程。
- `AdminLayout.vue` 管理后台布局（侧边栏菜单 + 主内容区）。
- 系统枚举管理页：完整 CRUD + 批量新增对话框 + 关键词搜索 + 响应式布局。
- 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框 + 批量上传入口。
- 知识文档管理页：条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除。
- RAG 文档批量上传组件：支持锁定知识库或选择知识库上传。
- API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
- 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。

### 质量保障

- 后端结构稳定性单元测试。
- 前端组件与 API 单元测试。

## 短期优先级

建议优先完成下面几项，把 RAG 上传解析链路升级为可检索链路：

1. 切片生成服务：把解析服务拿到的 `DocumentParseResult.text` 改造成可持久化的 `rag_chunk` 记录。
2. 按 `RagChunkStrategyEnum` 先落地 `FIXED_LENGTH` 和 `DELIMITER`，再扩展段落/标题/表格/语义切片。
3. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。
4. 接入 Spring AI Embedding 模型，生成并保存 `rag_chunk_embedding`。
5. 补齐重建索引、失败重试、最近任务接口。
6. 前端接入检索配置、最近任务和重建索引动作。

## RAG 最小闭环

当前上传与解析入口已完成，下一步建设最小检索闭环：

1. 批量上传文件，自动创建 `sys_attachment` 与 `rag_document`。
2. 调用解析入口，使用 Tika 抽取文本并更新 `parseStatus`。
3. 根据切片策略生成 `rag_chunk`。
4. 调用 Embedding 模型生成向量并写入 `rag_chunk_embedding`。
5. 提供检索接口，按 query 向量召回切片并返回引用元数据。

## Agent 核心能力

RAG 数据链路稳定后，再进入 Agent 主线：

1. Agent 定义管理。
2. 会话与消息模型。
3. 工具注册与工具调用协议。
4. Prompt 模板管理。
5. 任务执行与简单编排能力。
6. 运行日志与调用追踪。

## 平台化能力

中期建议补齐的平台能力：

- 用户与权限体系。
- 知识库管理后台完善（检索配置、索引任务查看）。
- Agent 管理后台。
- 文件管理与文档预览。
- 系统配置中心。
- 审计日志与监控告警。

## 前端协同建议

当前前端工程已在仓库中落地，后端约定已经冻结：

- 统一响应体格式：`RequestResult<T>`（`resultcode`, `message`, `data`）。
- 上传接口返回模型：`SysAttachmentResponse`。
- 枚举查询接口规范：POST `/api/sys-enum/queryForManagement`。
- RAG 文档状态字段：`parseStatus` + `indexStatus` + `enabled`。
- RAG 文档批量上传接口：POST `/api/rag/documents/batchUpload`。
- RAG 文档解析接口：POST `/api/rag/documents/parse`，当前同步解析并返回解析元数据。
- 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 输出为字符串。

## 里程碑

### 里程碑 1：后端规范化 ~~已完成~~

- 补齐 DTO、响应体、异常处理、校验。
- 接口具备稳定对接能力。

### 里程碑 2：RAG 可演示

- 已完成知识库文档上传、建档、解析状态流转。
- 下一步完成切片持久化、向量化和检索接口。
- 前端知识库与知识文档页面已接入当前接口，索引任务和检索配置待接入。

### 里程碑 3：Agent 最小运行时

- 支持一个可配置 Agent、一个会话、一次模型调用、一次工具调用。

### 里程碑 4：平台管理化

- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。