common_agent/docs/ROADMAP.md

Common Agent 开发路线图

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

已完成

基础工程

• Spring Boot 4.0.6 后端工程初始化。
• PostgreSQL 数据源与多环境配置文件（dev / template）。
• MyBatis-Plus 3.5.16、Lombok、Springdoc OpenAPI 2.8.13 已接入。
• Maven Wrapper。

公共能力

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

RAG 基础能力

• rag_store、rag_document 表结构与实体定义。
• RAG 知识库完整 CRUD（含编码唯一性校验）。
• 知识文档条件查询服务。
• RAG 解析状态枚举 RagParseStatusEnum（UPLOADED / PARSING / PARSED / FAILED）。
• RAG 索引状态枚举 RagIndexStatusEnum（PENDING / INDEXING / INDEXED / FAILED）。
• RAG 来源常量 RagSystemConstants。

前端控制台

• Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router 工程。
• AdminLayout.vue 管理后台布局（侧边栏菜单 + 主内容区）。
• 系统枚举管理页：完整 CRUD + 批量新增对话框 + 关键词搜索 + 响应式布局。
• 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框。
• API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
• 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。

质量保障

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

短期优先级

建议优先完成下面几项，把 RAG 元数据管理层升级为可用的业务闭环：

1. 知识库文档上传接口：上传文件后自动创建 rag_document 记录。
2. 文档解析任务入口与状态流转。
3. 向量化任务入口与状态流转。
4. 知识库文档新增、详情、启停用、重试等管理接口。
5. 前端附件管理页面联调。
6. 前端知识文档页面联调。

RAG 最小闭环

在基础规范层补齐后，当前 RAG 元数据层已完成，下一步建设业务闭环：

1. 附件上传后自动创建 rag_document 记录。
2. 建立文档解析任务入口（占位解析器）。
3. 解析状态、索引状态按流程流转。
4. 接入占位向量化接口。
5. 提供知识库文档管理完整接口（新增、详情、启停用、重试、删除）。

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。
• 大整数 ID 通过 @JsonSerialize(ToStringSerializer.class) 输出为字符串。

里程碑

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

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

里程碑 2：RAG 可演示

• 实现知识库文档上传、建档、状态流转。
• 预留解析和索引任务接口。
• 前端知识库页面完整联调。

里程碑 3：Agent 最小运行时

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

里程碑 4：平台管理化

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