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

docs/ARCHITECTURE.md

@@ -135,8 +135,50 @@
 
 - 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析、解析快照和状态流转已完成。
 - `rag_chunk` 已支持基于解析快照的手动异步切片，当前已落地定长切片和分隔符切片。
-- `rag_chunk_embedding` 的结构层已就绪，尚未实现模型调用、向量化、索引任务和检索问答。
-- 模型服务商配置与路由已有需求/设计文档，后续会作为 Embedding、Chat 和 Rerank 的统一接入层。
+- `rag_chunk_embedding` 已支持按知识库向量相似度召回 TopK，用于 Agent 调试链路引用回显。
+- RAG 对外检索问答接口、索引任务化和重排序能力仍在后续建设中。
+
+### 3.3 Agent 模块
+
+包路径：`com.bruce.agent`
+
+职责：
+
+- 维护 Agent 定义主数据（CRUD + 编码唯一性 + 绑定知识库校验）。
+- 提供 Agent 调试对话接口，支持普通对话与 RAG 对话模式切换。
+- 在 RAG 对话模式下，完成“问题向量化 -> 切片召回 -> 上下文组装 -> Chat 模型回答”的最小链路。
+- 返回引用切片和请求 ID，便于前端调试与调用追踪。
+
+关键类：
+
+| 类 | 路径 |
+|----|------|
+| AgentDefinition | `agent/entity/AgentDefinition.java` |
+| AgentDefinitionController | `agent/controller/AgentDefinitionController.java` |
+| AgentDefinitionServiceImpl | `agent/service/impl/AgentDefinitionServiceImpl.java` |
+| AgentDefinitionResponse | `agent/dto/response/AgentDefinitionResponse.java` |
+| AgentChatResponse | `agent/dto/response/AgentChatResponse.java` |
+| ChatModelGateway | `modelprovider/gateway/ChatModelGateway.java` |
+| ChatModelGatewayImpl | `modelprovider/gateway/ChatModelGatewayImpl.java` |
+| ChatRequest | `modelprovider/gateway/ChatRequest.java` |
+| ChatResult | `modelprovider/gateway/ChatResult.java` |
+
+接口列表：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/agents/list` | 查询全部 Agent |
+| POST | `/api/agents/query` | Agent 条件查询 |
+| GET | `/api/agents/detail` | 获取 Agent 详情 |
+| POST | `/api/agents/save` | 新增/更新 Agent |
+| POST | `/api/agents/delete` | 删除 Agent |
+| POST | `/api/agents/{agentId}/chat` | Agent 调试对话 |
+
+当前边界：
+
+- `agent_definition` 与前端 Agent 管理页已完成联调。
+- 对话入口已支持 `ragEnabled` 开关，`true` 走 RAG 召回，`false` 走普通对话。
+- 尚未落地会话持久化（`agent_session` / `agent_message`）和工具调用编排。
 
 ## 4. 数据模型关系
 
@@ -150,8 +192,9 @@
 | `rag_document` | 知识库文档表 | 关联 `rag_store.id` 和 `sys_attachment.id` |
 | `rag_chunk` | 知识切片表 | 关联 `rag_store.id` 和 `rag_document.id` |
 | `rag_chunk_embedding` | 切片向量表 | 关联 `rag_store.id`、`rag_document.id` 和 `rag_chunk.id` |
+| `agent_definition` | Agent 定义表 | 关联 `rag_store.id` |
 
-`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是下一步检索链路的核心落点。
+`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是检索链路核心落点，`agent_definition` 负责把 Agent 与知识库绑定到同一调用链路。
 
 ## 5. 配置与运行
 
@@ -183,16 +226,15 @@
 
 ## 7. 当前不足
 
-- RAG 尚未进入"可检索链路"，当前完成上传、解析和手动切片，但未完成向量化和召回。
-- 模型服务商配置、模型路由和调用日志尚未落地代码。
-- Agent 运行时相关模型与服务尚未开始建设。
+- RAG 尚未形成独立检索问答接口，当前召回能力主要用于 Agent 调试链路。
+- Agent 运行时尚未持久化会话，工具调用与任务编排仍未落地。
 - 前端部分页面（附件管理、检索配置、最近任务）为占位或后续能力提示。
 - 缺少鉴权、租户、操作日志。
 
 ## 8. 建议演进方向
 
 1. 补 RAG 最小检索闭环：解析文本 → 生成切片 → 生成向量 → 检索召回。
-2. 建设模型服务商配置与路由层，统一接入 Ollama、硅基流动、百炼等 OpenAI-compatible 来源。
-3. 建设 Agent 域模型：Agent、Session、Message、Tool、Task。
+2. 把当前 Agent 调试链路升级为会话化运行：沉淀 Session、Message 和上下文裁剪策略。
+3. 建设 Agent 工具注册与调用协议，补齐任务状态与执行日志。
 4. 补齐索引任务、重试、重建索引和前端任务视图。
 5. 衔接模型供应商、Spring AI 适配层、工作流编排和前端管理台。