feat(modelprovider): 完善模型调用与RAG召回支撑

README.md

@@ -3,8 +3,8 @@
 Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。
 项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。
 
-当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、解析快照、手动切片入口、前端知识库与知识文档管理页面。
-Agent 运行时、RAG 向量化、检索问答、模型服务商配置与更多平台管理能力会在后续阶段逐步实现。
+当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、解析快照、手动切片入口、模型服务商配置基础能力、Agent 定义管理与调试页面。
+会话持久化、工具调用编排、RAG 全量向量化与检索问答能力会在后续阶段逐步完善。
 
 ## 项目愿景
 
@@ -13,7 +13,7 @@ Common Agent 希望成为一个可复用的企业级 AI 应用基础平台：
 - Agent 运行时：支持对话、工具调用、记忆、任务执行和流程编排。
 - RAG 知识库：支持文档导入、解析、切片、向量化、检索和基于上下文的回答生成。
 - 模型抽象：通过 Spring AI 统一接入聊天模型、Embedding 模型和重排序模型。
-- 管理控制台：提供会话、Agent、知识库、文档、提示词和系统配置的 Web 管理界面。
+- 管理控制台：提供 Agent、知识库、文档、模型配置和系统配置的 Web 管理界面。
 - 多环境部署：支持本地开发、测试环境和生产环境的配置隔离。
 
 ## 当前技术栈
@@ -36,7 +36,7 @@ common_agent
 │   ├── src/
 │   │   ├── api/                       # Axios 封装与各模块 API
 │   │   ├── layouts/                   # AdminLayout 管理后台布局
-│   │   ├── pages/                     # 业务页面（工作台、枚举、附件、知识库、文档）
+│   │   ├── pages/                     # 业务页面（系统、RAG、Agent）
 │   │   ├── router/                    # Vue Router 配置
 │   │   ├── stores/                    # Pinia 状态管理
 │   │   ├── styles/                    # 全局样式
@@ -59,14 +59,16 @@ common_agent
 │   │   │   ├── 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/               # 接口与实现
+│   │   ├── 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       # 开发环境配置
@@ -74,8 +76,12 @@ common_agent
 │   └── test/java/                     # 单元测试（结构稳定性测试 + 前端 API 测试）
 ├── docs/
 │   ├── ARCHITECTURE.md                # 架构说明
-│   └── ROADMAP.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
 ```
@@ -152,6 +158,8 @@ npm run build
 | 知识库 | 完整 CRUD + 双栏详情 |
 | 知识文档 | 条件查询 + 批量上传 + 解析重试 + 批量切片 + 编辑/启停用/删除 |
 | 切片任务 | 解析成功/失败文档概览 + 切片入口 |
+| Agent管理 | Agent 定义 CRUD + 知识库绑定 |
+| Agent调试 | 普通对话 / RAG 对话切换 + 引用切片回显 |
 
 当前 UI 规范：
 
@@ -171,16 +179,24 @@ npm run build
 
 ## RAG 当前能力边界
 
-当前 RAG 已经从元数据管理推进到"上传 + 解析 + 手动切片"阶段：
+当前 RAG 已经从元数据管理推进到"上传 + 解析 + 手动切片 + Agent 调试召回"阶段：
 
 - 知识库：支持列表、条件查询、详情、总览、单库文档概览、新增、编辑、删除。
 - 知识文档：支持列表、条件查询、详情、新增/编辑、删除、批量上传。
 - 文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新 `parseStatus` 并保存解析快照。
 - 文档切片：支持按解析快照进行手动异步切片，已落地定长切片和分隔符切片，写入 `rag_chunk`。
-- 向量表：`rag_chunk_embedding` 实体、Mapper、Service 已有结构，向量写入、检索召回和重排序仍待接入。
-- 模型配置：已补充模型服务商配置与路由需求/设计文档，后续用于统一接入 Ollama、硅基流动、百炼等来源。
+- 向量表：`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 执行模型、工具注册、记忆和编排能力。
@@ -197,6 +213,7 @@ npm run build
 - [模型服务商配置与路由需求](docs/MODEL_PROVIDER_REQUIREMENTS.md)
 - [模型服务商配置与路由设计](docs/MODEL_PROVIDER_DESIGN.md)
 - [平台设计草案](AGENT.md)
+- [Agent 页面接口清单](agent-page-apis.md)
 
 ## 参考资料