1. 供应交付 Agent MCP Tool 化方案设计#

今天首先完成了供应交付智能助手平台原生化重构方案的整理与优化。该方案以旧供应交付 Agent 为业务样板，目标不是简单迁移旧 Agent，也不是黑盒纳管旧 Agent，而是通过旧 Agent 中沉淀的真实业务场景、Skill、API 调用链路和业务状态机，反向打磨新平台的 Plan-and-Execute 与 MCP Tool 调用基座。

本次方案明确了当前阶段的两条核心主线：

1. Plan-and-Execute 范式适配
   让平台能够基于用户自然语言意图生成结构化 Plan，并将每个 Step 映射到一个或少量 MCP Tool。

2. MCP Tool 统一执行链路
   将旧 Agent 中原有 Skill/API 调用方式统一改造为 MCP Tool 调用方式，后续平台执行真实业务代码统一通过 MCP Tool 完成。

方案中也明确当前阶段不建设记忆系统，不做 Conversation Memory、Working Memory、Long-term Memory 等实现，仅保留 conversationId、runId、executionContext 等轻量上下文字段作为后续扩展点。

本次方案的核心调整是：Skill 不再作为真实业务代码执行入口，而是退化为能力描述层和历史资产映射来源。真实执行主链路从原来的：

1
Plan Step → SkillMatcher → SkillInvoker → Tool

调整为：

1
Plan Step → ToolSelector / PlanValidator → McpToolStepExecutor → McpToolInvoker → MCP Tool

这种设计有利于统一工具发现、参数 Schema、调用审计、风险治理和后续高风险操作确认。

2. Phase 0：旧 Skill/API 能力盘点与 Tool 映射设计#

今天完成了 Phase 0 阶段验收，主要目标是对旧供应交付 Agent 的 Skill/API 能力进行系统盘点，并形成旧 Skill 到 MCP Tool 的映射设计。

Phase 0 完成内容包括：

• 梳理旧 Agent 的 29 个 SKILL.md；
• 梳理每个 Skill 实际调用的 API、Service 或 Function；
• 按复杂度将旧 Skill 归类为 ONE_TOOL、FEW_TOOLS、FLOW_RESERVED、UI_RESERVED、SKIP；
• 形成 legacy_skill_code → mcp_tool_name 映射表；
• 明确第一批查询类 Tool；
• 明确第二批校验类 Tool；
• 明确第三批执行类 Tool 及其风险等级；
• 输出 MCP Tool 命名规范和分阶段接入顺序。

本阶段统计结果显示：

• ONE_TOOL：7 个，适合单 Skill 映射为单 MCP Tool；
• FEW_TOOLS：4 个，适合由 2-3 个 MCP Tool 通过 Plan 编排；
• FLOW_RESERVED：5 个，后续进入 FlowEngine；
• UI_RESERVED：8 个，后续结合表单或页面交互扩展；
• SKIP：3 个，属于通用或元能力 Skill，暂不纳入供应交付业务 Tool 化范围。

同时，本阶段也完成了风险等级分布标注，其中查询类能力风险较低，执行类能力如订单发放、PO 审批、ShipSet 更新、ATP 初始化等被标记为高风险，后续需要接入 Human-in-the-loop、审计和幂等控制。

3. Phase 1：Plan-and-Execute + 单 MCP Tool 最小闭环#

今天完成 Phase 1 阶段验收，目标是验证新平台可以通过 Plan-and-Execute 生成 MCP_TOOL_CALL Step，并调用 MCP Tool 完成供应交付查询类任务。

Phase 1 接入的第一批 3 个 MCP Tool 包括：

• order_delivery_query：订单交付查询；
• unshipped_order_query：未发货订单查询；
• supply_capacity_query：供应能力查询。

本阶段主要完成以下开发任务：

• 新增供应交付 Agent Profile；
• 绑定 MCP Skill Server；
• 注册第一批 3 个 MCP Tool；
• 建立 agent_tool_bind；
• 建设 ToolCatalogProvider；
• 改造 PlanGenerator，使其能够读取 Tool Catalog 并生成 MCP_TOOL_CALL；
• 新增 PlanValidator，校验 Tool 存在性和参数完整性；
• 新增 McpToolStepExecutor；
• 新增 McpToolInvoker；
• 新增 ToolResultNormalizer；
• 将 Tool 调用记录写入 agent_tool_call_record。

同时新增了 agent_tool_capability 和 agent_skill_tool_mapping 两张表。其中，agent_tool_capability 用于保存 Tool 能力增强元数据，例如 intent examples、required slots、planning hints 等；agent_skill_tool_mapping 用于保存旧 Skill 到新 MCP Tool 的映射关系。

Phase 1 验收中，7 条验收标准全部通过，包括：

• Planner 能生成 MCP_TOOL_CALL；
• Step 中包含 serverCode、toolName、arguments；
• Tool 来自当前 Agent Tool Catalog；
• 参数缺失时可生成 ASK_CLARIFICATION；
• Tool 结果可被标准化；
• 最终回复可解释查询结果；
• agent_run、agent_plan、agent_plan_step、agent_tool_call_record 均有审计记录。

端到端测试中，订单交付查询、未发货订单查询、供应能力查询等场景均完成验证，4 次运行状态均为 COMPLETED。测试期间还修复了两个问题：PlanPromptBuilder Prompt 模板缺少 inputContext 输出指示，以及 PlanFallbackFactory.parseAndCreate() 未解析 inputContext 字段。

4. Phase 2：校验类 Tool 接入与匹配准确率增强#

今天还完成了 Phase 2 阶段验收，目标是在 Phase 1 查询类 Tool 的基础上，扩展校验类 Tool，并增强 Tool 匹配准确率和匹配过程审计能力。

Phase 2 新增 3 个 Tool：

• arrival_confirmation_check：到货确认检查；
• order_release_check：订单发放障碍检查；
• acceptance_materials_query：验收材料文件查询。

本阶段主要完成内容包括：

• 为 Phase 1 和 Phase 2 的 Tool 补充 intent examples；
• 为每个 Tool 补充 required slots 和 inputSchema；
• 为 Tool 补充 risk_level 和 complexity_type；
• 保持 Planner Prompt 注入 Tool Catalog；
• 新增 agent_tool_match_record 表、实体和 Mapper；
• 在 PlanValidator 中增加 Tool 存在性和参数完整性校验；
• 增加 Tool 误命中回归测试集；
• 完成核心语义区分测试，防止相似 Tool 混淆。

Phase 2 的端到端测试包括：

• 到货确认检查；
• 订单发放检查；
• 验收材料查询。

测试结果均为 COMPLETED，其中部分返回如权限异常或未查到记录属于符合预期的业务行为。本阶段也验证了相似 Tool 的区分能力，例如“查询发货状态”和“执行发放”不能误命中同一 Tool。

截至 Phase 2，供应交付 Agent 的业务 Tool Catalog 累计达到 6 个，包括 3 个查询类 Tool 和 3 个校验/查询类 Tool。验收结论为 Phase 2 通过，Tool 匹配准确率阶段目标达成，6/6 工具命中正确。

5. MCP Tool 标准执行链路优化#

今天在方案和阶段验收中进一步明确了 MCP Tool 标准执行链路。新的执行链路强调：Planner 不再主要面向旧 Skill 列表生成计划，而是面向当前 Agent 绑定的 Tool Catalog 生成 Tool-aware Plan。

标准链路如下：

1
用户输入
2
  → AgentRunController
3
  → ToolCatalogProvider
4
  → PlanGenerator
5
  → PlanValidator
6
  → McpToolStepExecutor
7
  → McpToolInvoker
8
  → MCP Client Gateway
9
  → MCP Skill Server
10
  → ERP Tool Wrapper
11
  → ERP Service / API
12
  → ToolResultNormalizer
13
  → ResultSynthesizer
14
  → 最终回复

该链路能够保证：

• Tool 必须来自当前 Agent 绑定的 Tool Catalog；
• 不允许 Planner 编造不存在的 toolName；
• 参数缺失时应追问或返回参数不足，不允许乱猜关键业务参数；
• Tool 调用结果统一标准化，便于最终回复生成；
• Tool 调用全过程可以落库审计。

这为后续接入执行类 Tool、HIL、复杂 Flow 和平台级治理打下基础。

6. 线上问题排查：反馈提交第一次失效、第二次成功#

除了供应交付 Agent MCP Tool 化工作外，今天还参与并整理了一个线上间歇性问题排查：用户反馈提交时出现“第一次失效，第二次成功”。

问题场景为用户调用 POST /api/portal/feedback 提交反馈。现象是用户第一次提交后数据库没有生成反馈记录，过一段时间再次提交同类反馈则成功。

本次排查过程包括：

1. 定位应用服务进程和日志文件
   通过 ps -ef | grep java 确认问题服务为 langchain-agent，进一步通过 /proc/<PID>/fd/1 定位标准输出日志为 /home/jar/langchain-agent/logs/console.log。

2. 确认问题发生时间范围
   结合用户反馈，将重点时间段定位到 2026-05-28 14:14 左右。

3. 检查 Nginx 访问日志
   检索 /api/portal/feedback 请求，确认 14:14 左右请求真实到达 Nginx，且 HTTP 状态码返回 200。

4. 对比数据库反馈记录
   将 Nginx 请求时间与数据库记录对比，发现 14:14 左右多次请求虽然 HTTP 200，但数据库没有对应记录；14:27 之后请求恢复正常并成功落库。

5. 检索应用异常日志
   在 14:14 时间段发现 AI-UDS 网关调用异常，核心错误为 401 Unauthorized，同时业务日志中出现 SkillAccessLogService 网关返回失败记录。

最终形成的证据链表明：请求已经到达服务端，Nginx 返回 HTTP 200，但后端业务链路中调用 AI-UDS 网关记录访问日志时出现 401 Unauthorized，导致反馈提交业务未完整执行，最终反馈记录未落库。

本次问题定性为：

1
外部 AI-UDS 网关认证异常导致反馈提交业务失败，同时接口仍返回 HTTP 200，造成用户侧“提交成功假象”和数据库未落库问题。

7. 线上问题优化建议沉淀#

针对本次线上问题，今天也沉淀了后续优化建议：

• 对 AI-UDS 401 Unauthorized 增加专项处理，例如刷新 token 后重试一次；
• 避免非核心访问日志链路阻断反馈主业务落库；
• 修正接口返回语义，避免业务失败仍返回 HTTP 200 假成功；
• 前端不能只根据 HTTP 200 判断成功，应结合响应体业务 code；
• 外部网关调用失败日志中补充 traceId、用户 ID、skillCode、entityType、HTTP 状态码、重试次数等上下文；
• 对 AI-UDS 401、反馈落库失败、HTTP 200 但业务失败等情况增加监控告警；
• 建立修复后的验证场景，包括正常提交、AI-UDS 401、AI-UDS 不可用和 HTTP 200 假成功校验。

该排查文档可以作为后续修复、复盘和线上问题处理手册的一部分。

1. 旧 Skill 能力复杂，直接迁移容易导致平台主线发散#

• 问题：旧供应交付 Agent 中存在查询、校验、执行、UI、多轮状态机等多类 Skill，如果直接整体迁移，容易导致新平台执行链路复杂化。
• 处理：在 Phase 0 中将 29 个 Skill 按复杂度分为 ONE_TOOL、FEW_TOOLS、FLOW_RESERVED、UI_RESERVED、SKIP，并明确分阶段接入顺序。
• 结果：形成清晰的 Tool 化改造路线，优先推进低风险单工具查询和校验能力，复杂 Flow 与 UI 能力后置。

2. Planner 可能生成不存在或不属于当前 Agent 的 Tool#

• 问题：LLM 在生成 Plan 时可能编造 toolName，或者选择未绑定给当前 Agent 的工具。
• 处理：引入 ToolCatalogProvider 和 PlanValidator，Planner 只能基于当前 Agent 的 Tool Catalog 生成 MCP_TOOL_CALL，PlanValidator 再校验 Tool 存在性和参数完整性。
• 结果：Phase 1、Phase 2 验收中 Tool 来自 Agent Tool Catalog，PlanValidator 能拦截未知 Tool。

3. Tool 返回格式不统一影响最终回复生成#

• 问题：不同业务 Tool 的返回结果格式可能不一致，影响 ResultSynthesizer 对结果的理解和最终回复生成。
• 处理：新增 ToolResultNormalizer，对标准 JSON 和非 JSON 返回进行统一包装和规范化。
• 结果：Tool 调用结果可以稳定进入后续最终回复合成链路。

4. Tool 语义相似导致误命中风险#

• 问题：供应交付场景中“查询发货状态”“检查能否发放”“执行发放”等表达相近，容易导致 Tool 误匹配。
• 处理：Phase 2 中为每个 Tool 补充 intent examples、required slots、risk_level、complexity_type，并新增 ToolMatchRecord 审计能力。
• 结果：核心测试集中 6/6 工具命中正确，相似 Tool 的语义边界得到加强。

5. 线上反馈提交存在 HTTP 200 假成功#

• 问题：Nginx 日志显示反馈接口返回 200，但数据库中没有记录，用户感知为提交成功但实际未生效。
• 处理：通过 Nginx 日志、数据库记录、应用日志进行交叉比对，定位到 14:14 左右 AI-UDS 网关调用 401 Unauthorized。
• 结果：明确问题根因为外部网关认证异常影响反馈主流程，同时接口返回语义未正确表达业务失败。

6. 外部访问日志链路与主业务存在耦合风险#

• 问题：AI-UDS 访问日志网关异常可能影响反馈落库，说明非核心外部依赖存在阻断主业务的风险。
• 处理：在排查记录中提出将反馈落库与访问日志写入解耦，例如先写主业务，再异步写日志，失败进入补偿或降级。
• 结果：形成后续优化方向，减少外部日志依赖对核心反馈提交链路的影响。