从“先思考后行动”的对话链，到“并行预加载 + 缓存 + 降级”的 MCP 工具管线改造

1. 背景与目标

• 在多智能体产品落地中，用户最真实的痛点是两类：
• - 对话质量：系统能否“先想清楚再动手”，避免无效检索、跑偏执行；
• - 工具体验：工具是否“真正按需加载、快速稳定”，不拖响应、不污染体验。
• 我对 JoyAgent‑JDGenie 做了系统性增强，目标是开箱即用、可商用：
• - 在对话上，规范“先思考后行动”的提示结构；
• - 在工具上，引入 MCP 工具并行预加载 + 缓存 + 快速失败 + 会话级降级 + 运行时热开关；
• - 在交付上，做了 HTML/PPTX/Markdown/CSV/Token 链接的导出与 UI 体验优化；
• - 在可运维性上，加强了超时、心跳、日志与健康检查。

2. 总览：本次增强带来了什么

• - 对话链条更稳：
• - 先思考（Reasoning）→ 再行动（工具 JSON 调用）→ 后观察（结果评估），严格执行；
• - 搜索类任务按分维度检索，避免“弱 query”与工具空转；
• - SSE 流式输出 + 首段/间隔聚合，首屏快速同时稳定。
• - 工具体验更顺手：
• - MCP 并行预加载（List Tools），5 分钟内存缓存；
• - 调用超时快速失败，避免长链路卡死；
• - 会话级降级（Penalty Box）：坏节点 5 分钟内自动跳过；
• - 运行时热开关：`disableTools` 直出、`mcpEnabledServers` 精准启用；
• - 启发式装配：只有需要时才挂载工具，减少无意义装配。
• - 交付与 UI：
• - 主题背景可切换、历史对话记录与标签、5 种导出；
• - PPTX 模板化排版与配色优化，开会可直接上屏。
• - 聊天历史记录，可以点击历史记录继续对话

3. 架构与数据流

3.1 组件分层

• 前端（React + Vite + AntD，端口 3000）：多模式 UI、会话与导出/分享；
• 后端（Spring Boot，端口 8080）：`POST /AutoAgent` 建立 SSE；启发式工具装配；与 MCP 客户端交互；
• 工具服务（FastAPI，端口 1601）：`/report`、`/code_interpreter`、`/deepsearch` 全流式
• MCP 客户端（FastAPI，端口 8188）：对任意 MCP Server 统一代理 `/v1/tool/list`、`/v1/tool/call`。

3.2 数据流（简述）

前端发起 `/AutoAgent` → 后端按启发式决定是否挂载本地工具/拉取 MCP 工具 → 工具服务/MCP 并发返回增量 → 后端通过 SSE 推送前端 → 文件写盘与 SQLite 记录 → 历史对话可回溯并导出。

4. 对话质量的系统性提升

4.1 先思考后行动（Reason → Act → Observe）

• 在 Planner/Executor/ReAct 不同模式下，我都约束了“先思考后行动”，并限定思考字数（如 200 字内）；
• 思考内容必须解释“为什么要调用某工具、期待结果是什么”；
• 工具调用输出统一使用 JSON（例如 `{"function_name":"deep_search","query":"xxx"}`），禁止幻觉式工具名；
• 观察（Observe）阶段对结果进行评估，不理想则继续思考换策略。

4.2 搜索类任务的入参质量控制

• 引导按多维度（如“财务数据/行业趋势/竞争格局/估值/市场/情绪”）生成多个查询；
• 以结构化 JSON 发出多次“有差异”的搜索调用，避免重复与低质量 Query；
• 将分块结果整合为可复用的摘要/Markdown 文件，文件名与描述自动生成。

4.3 SSE 流式策略：首段与间隔

• 后端心跳：默认 10 秒；
• 工具服务聚合：支持按 token / time 聚合发送，首屏足够快同时保证稳定；
• 可通过 `message_interval` 配置首段大小与间隔频率（见下文配置）。

5. MCP 工具调用体验的系统提升

本节是重头戏，详细说明“并行预加载 + 缓存 + 快速失败 + 降级 + 热开关”的完整链路。

 5.1 并行预加载（List Tools）

触发时机：后端 `GenieController#buildToolCollection` 决定需要装配工具后，对配置的 MCP Server 并行调用 MCP 客户端 `/v1/tool/list`；

结果结构：获取工具 `name/description/inputSchema`，与来源 `server` 一起写入 `ToolCollection`；

作用：让模型在“工具列表”上有真实可用的候选，避免“虚构工具”。

5.2 缓存（5 分钟内存缓存）

位置：`McpTool#listTool` 内部维护一个 5 分钟 TTL 的内存缓存（ConcurrentHashMap）；

意义：避免每次会话都重复拉取工具列表，减少高延迟与调用成本；

与并行的配合：首次命中后，后续多个会话/请求将会直接命中缓存。

5.3 超时快速失败（Fail‑fast）

后端对 MCP 客户端请求设置了调用超时（默认 10s，可配）；

 一旦超时或网络失败，立即返回并记录，不阻塞整个对话链路；

 搜索类/报告类等其他工具链路不受影响，保障用户体验。

5.4 会话级降级（Penalty Box）

机制：对“同一个会话 + 某个 MCP Server”的调用，如果失败/超时，记录一次时间戳；

在 5 分钟窗口内，同一会话再次试图调用该 Server 时，将被直接跳过；

价值：避免“坏节点”拖累会话的后续体验，静默降级用户无感知。

5.5 运行时热开关（Per‑Request Override）

 `disableTools=true`：完全跳过工具装配，进入“快速直出”模式；

`mcpEnabledServers=["http://x/sse", "http://y/sse"]`：仅在当前会话启用这些 MCP Server；

- 这一切都发生在请求级别，避免重启与全局配置污染。

5.6 启发式装配（Should Use Tools?）

当识别到是“写作/报告/表格/PPT/结构化/检索”等意图，或用户选择了特定交付样式（docs/ppt/table/html），系统才装配工具；

闲聊/问候或极短问题，默认不装配；

这能避免“过度装配”与提示词干扰，保持对话简洁与稳定。

6. 关键配置与建议

 6.1 后端（`genie-backend/src/main/resources/application.yml`）

llm:

default:

base_url: "<你的模型Base URL>"

apikey: "<你的模型API Key>"

model: "moonshotai/Kimi-K2-Instruct"

max_tokens: 16384

autobots:

autoagent:

tool_list: '{"default":"search,code,report"}'

deep_search_url: "http://127.0.0.1:1601" # 工具服务地址

mcp_client_url: "http://127.0.0.1:8188" # MCP 客户端地址

mcp_server_url: "http://mcp1/sse,http://mcp2/sse" # 可选

mcp_call_timeout_seconds: 10

message_interval: '{"search":"5,20"}' # 首段/间隔

建议：

1. 保持 `mcp_call_timeout_seconds` 在 5–12s 之间，避免误伤又不拖链路；
2. `tool_list` 可为不同场景定义不同 Profile；
3. LLM Key 建议通过环境变量注入，避免写入仓库。

6.2 工具服务（`genie-tool/.env`）

OPENAI_BASE_URL=https://api.siliconflow.cn/v1

OPENAI_API_KEY=<your key>

DEFAULT_MODEL=moonshotai/Kimi-K2-Instruct

# 搜索引擎（按需）

TAVILY_API_KEY=<your tavily key>

EXA_API_KEY=<your exa key>

SERPER_SEARCH_API_KEY=<your serper key>

FILE_SAVE_PATH=file_db_dir

SQLITE_DB_PATH=autobots.db

FILE_SERVER_URL=http://127.0.0.1:1601/v1/file_tool

建议：

• 生产环境统一通过环境变量注入 Key；
• 合理设置搜索引擎超时与并发，保证“一致可用”。

7. 端到端示例：从前端到工具/文件的完整交付

7.1 示例请求（后端 `/AutoAgent`，SSE）

{

"requestId": "req-2025-0001",

"query": "请制作一份近三年黄金与美元走势的分析报告，并输出PPT",

"agentType": 3,

"outputStyle": "ppt",

"isStream": true,

"disableTools": false,

"mcpEnabledServers": ["http://mcp.example.com/sse?key=xxxx"]

}

7.2 前端体验

• 选择 PPT 模式 → 输入需求 → 实时看到 Reason → Action → Observe 的过程；
• 工具服务生成 HTML/PPTX/Markdown/CSV 文件；
• 会话结束后，一键导出为 PPTX 或 HTML，或生成 Token 链接分享。

7.3 文件侧与数据库

• 工具服务将生成的内容写入 `FILE_SAVE_PATH`，并在 SQLite (`autobots.db`) 记录元数据；
• 后端在搜索等环节会将阶段性结果写成 Markdown/文本，方便二次复用；
• 前端可通过文件预览 URL 直接查看（如 HTML 报告）。

8. 性能与稳定性：指标、策略与取舍

• - 并行化：MCP List 并行 + 工具管线细化；
• - 缓存：MCP 工具列表 5 分钟缓存，降低冷启动成本；
• - 超时：OkHttp 连接/读/写/调用多级超时，工具服务也有聚合与心跳；
• - 降级：Penalty Box 会话级降级，坏节点 5 分钟内不再干扰本会话；
• - 提速：工具链路顺滑度 ≈ +40%，快速直出 ≈ +60% 响应提速（视场景与模型/网络而定）。---

9. 常见问题（FAQ）与排障

**Q1：为什么没有装配工具？**

- 可能触发了启发式判定为闲聊/极短问题；或请求里显式 `disableTools=true`。

**Q2：MCP 工具列表不更新？**

- 5 分钟缓存生效中；或 MCP Server 不可用/超时；检查 `/v1/tool/list` 与网络连通性。

**Q3：PPTX 导出失败？**

- 开发模式用 CDN 组件，如内网受限可切换后端生成方案或本地打包依赖。

**Q4：搜索引擎调用超时？**

- 调整工具服务中各搜索的超时/并发，或改用其他可用引擎作为主/备。

**Q5：Key 安全？**

- 强烈建议所有 Key 走环境变量注入，不写入仓库；对生产环境进行最小化权限控制。

10. 结语

这次增强的核心，是把“对话质量提升”和“工具体验升级”做成工程化能力：

• 对话端：先思考后行动 + 结构化工具调用 + 流式输出策略；
• 工具端：MCP 并行预加载 + 缓存 + 快速失败 + 会话级降级 + 热开关；
• 交付端：HTML/PPTX/Markdown/CSV/Token 链接，历史沉淀与复用。

如果你准备把多智能体产品真正落地到业务一线，相信这套改造会让你的用户“明显体感更好”，也能让你的工作效率upup。欢迎基于本文配置与示例直接实操，也欢迎提出建议一起打磨到更高水位。

11.Contact if needed

CD2410546

上面的绿🫧