common_agent/docs/ROADMAP.md

Common Agent 开发路线图

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

已完成

基础工程

• 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_document_parse_result，供后续切片复用。
• 切片基础能力：已完成 Chunker、ChunkerFactory、定长切片和分隔符切片。
• 文档切片入口：支持按切片策略异步生成并替换 rag_chunk。
• 知识库总览接口与单库文档概览接口。
• 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 工作台与切片任务页：展示文档解析/切片概览并提供切片入口。
• RAG 文档批量上传组件：支持锁定知识库或选择知识库上传。
• Agent 管理页：支持 Agent 定义新增、编辑、删除、状态管理和知识库绑定。
• Agent 调试页：支持普通对话 / RAG 对话切换、请求 ID 与引用切片回显。
• API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
• 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。

模型平台与 Agent 最小链路

• 模型服务商、模型配置、路由规则、知识库模型绑定、调用日志核心表结构已落地（docs/MODEL_PROVIDER_SCHEMA.sql）。
• EmbeddingModelGateway 和 ChatModelGateway 已落地，统一走 OpenAI-compatible 协议调用上游模型。
• AgentDefinitionController 与 AgentDefinitionServiceImpl 已提供 Agent CRUD 与调试对话接口。
• Agent 调试链路已接入：问题向量化 -> rag_chunk_embedding 召回 -> 组装上下文 -> Chat 回答 -> 返回引用切片。

质量保障

• 后端结构稳定性单元测试。
• 前端组件与 API 单元测试。
• Agent 结构与服务单元测试（AgentComponentStructureTests、AgentDefinitionServiceImplTests）。

短期优先级

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

1. 打通文档切片后的全量向量写入，确保 rag_chunk_embedding 可持续更新。
2. 新增独立 RAG 检索问答接口，避免仅依赖 Agent 调试入口消费召回能力。
3. 索引任务入口：把文档或知识库的 indexStatus 推进为真实状态流转。
4. 补齐重建索引、失败重试、最近任务接口。
5. 落地 Agent 会话持久化（agent_session、agent_message）与多轮上下文管理。
6. 补齐 Agent 工具注册、工具调用协议和任务执行日志。

RAG 最小闭环

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

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

Agent 核心能力

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，当前同步解析、保存解析快照并返回解析元数据。
• RAG 文档切片接口：POST /api/rag/documents/chunk，当前异步生成并替换 rag_chunk。
• Agent 管理接口：/api/agents/list、/api/agents/query、/api/agents/detail、/api/agents/save、/api/agents/delete。
• Agent 调试接口：POST /api/agents/{agentId}/chat，支持 ragEnabled 开关。
• 大整数 ID 通过 @JsonSerialize(ToStringSerializer.class) 输出为字符串。

里程碑

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

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

里程碑 2：RAG 可演示

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

里程碑 3：Agent 最小运行时

• 已完成：支持一个可配置 Agent、一次模型调用与 RAG 召回调试链路。
• 待完成：会话持久化、工具调用与任务编排。

里程碑 4：平台管理化

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