TH Hotel SuperAgent MCP 入站诊断链路

1. 文档信息

项目	内容
文档版本	0.1
日期	2026-07-22
状态	已落地第一版
适用范围	`POST /mcp` 的 SuperAgent MCP 请求排障、参数还原和安全审计

2. 背景

SuperAgent 通过 MCP th_hotel_submit_task_results 提交业务结果时，当前后端只接受 M002 V4 params.arguments，并把通过 V4 transport 校验的 payload 交给本系统 ReservationAiTaskIntakeService。当业务入站失败时，如果只看到最终错误，例如 SOURCE_MESSAGE_NOT_FOUND 或 MCP_SUBMIT_PAYLOAD_INVALID，很难判断问题来自：

SuperAgent 实际传入的 MCP 参数。
MCP submit adapter 的转换逻辑。
本系统业务入站校验或数据状态。

本 checkpoint 增加 MCP 入站诊断链路，只为联调排障和受控审计提供证据，不改变原有业务处理逻辑。

3. 设计原则

诊断记录不是业务事实，不参与订单、任务、卡片、来源通知或 OPERA 流转。
/mcp 原有鉴权、body size、tools/call、adapter、业务 Service 调用顺序不变。
诊断写入失败时不得影响 MCP 原响应；只能记录安全 warn 日志。
普通日志只输出诊断 ID、tool、外部 source message id、安全错误码和安全错误摘要。
不在普通前端业务接口暴露 MCP 原始请求体、邮件正文、附件 URL、AI raw payload 或 Secret。
查询类 MCP tool 的响应可能包含受控正文，第一版不保存完整响应，只保存响应安全摘要。

4. 第一版诊断表

新增表：

platform_superagent_mcp_call_diagnostic

字段口径：

字段	中文说明
`id`	MCP 调用诊断 ID
`jsonrpc_id`	JSON-RPC request id 的安全文本表示
`method_name`	JSON-RPC method，例如 `tools/call`
`tool_name`	MCP tool 名称，例如 `th_hotel_submit_task_results`
`mcp_client_id`	调用方机器身份，第一版固定 `superagent-mcp`
`request_body_bytes`	原始请求体 UTF-8 字节数
`request_body_sha256`	原始请求体 SHA-256，用于不暴露正文时定位同一次请求
`raw_body_json`	原始 MCP JSON-RPC 请求体，受控诊断字段
`arguments_json`	`params.arguments` 原始 JSON，受控诊断字段
`adapted_payload_json`	submit adapter 转换后送入业务入站层的 JSON；非 submit 或转换失败为空
`mapping_diagnostics_json`	submit adapter 诊断；V4-only 模式下通常为空对象，旧 V3 事件索引映射已废弃
`response_summary_json`	MCP 响应安全摘要，不保存完整查询结果或正文
`call_status`	`RECEIVED`、`SUCCEEDED`、`FAILED`
`safe_error_code`	安全错误码，例如 `SOURCE_MESSAGE_NOT_FOUND`
`safe_error_summary`	安全错误摘要，不包含邮件正文、HTML、附件 URL 或 Secret
`source_message_external_id`	从 submit 入参中尽力提取的外部来源消息 ID
`hotel_id`	后端解析出的系统酒店 ID；解析失败时为空
`created_at` / `updated_at`	UTC 创建 / 更新时间

5. 诊断写入时机

阶段	行为
鉴权失败	不写诊断表，避免为未授权请求保存原始数据
body 超限	不写诊断表，直接返回原有 body too large 错误
JSON 解析失败	鉴权通过后写入失败诊断，保存 body hash 和 raw body
tools/list / query tool	写入原始请求和参数，只保存响应安全摘要
submit adapter 成功	补写 `adapted_payload_json` 和 `mapping_diagnostics_json`；V4-only 模式下 `adapted_payload_json` 通常与 `arguments_json` 相同
submit adapter 失败	保留 `arguments_json`，记录 adapter 安全错误码
业务入站失败	保留 `arguments_json` 和可用的 `adapted_payload_json`，记录业务安全错误码
调用成功	标记 `SUCCEEDED`，保存响应安全摘要

因此，鉴权通过且 body 未超限的旧 V2 / V3 submit payload 会写入本表，call_status=FAILED， safe_error_code=MCP_SUBMIT_V4_REQUIRED，adapted_payload_json 为空；这表示请求已被 MCP adapter 拒绝，没有进入业务入站 Service。

6. 排障 SQL

按外部 SourceMessage ID 查询 SuperAgent 传入的原始 MCP 参数：

SELECT
    id,
    created_at,
    call_status,
    method_name,
    tool_name,
    source_message_external_id,
    safe_error_code,
    safe_error_summary,
    arguments_json,
    adapted_payload_json,
    mapping_diagnostics_json
FROM platform_superagent_mcp_call_diagnostic
WHERE source_message_external_id = '<external_message_id>'
ORDER BY created_at DESC, id DESC;

按诊断 ID 查看一次请求的原始 envelope：

SELECT
    id,
    request_body_sha256,
    raw_body_json,
    response_summary_json
FROM platform_superagent_mcp_call_diagnostic
WHERE id = <diagnostic_id>;

7. 与现有链路关系

REST POST /api/integrations/superagent/task-results 仍使用现有 batch / transition 追踪。
MCP th_hotel_submit_task_results 会同时拥有 MCP 入站诊断和业务 batch / transition 追踪；如果返回 MCP_SUBMIT_V4_REQUIRED，说明 SuperAgent 仍提交旧 V2/V3 schema，不会进入业务写入 Service。
Debug EML、AgentBus dispatch run 不改原逻辑；如果 SuperAgent 最终通过 MCP 回写，才进入本诊断表。
第一版不新增前端页面和查询接口；DB 权限和运维访问由部署环境控制。

8. 安全说明

raw_body_json、arguments_json 和 adapted_payload_json 可能包含 SuperAgent 产出的邮件摘录、客户姓名、业务线索或附件 ID，因此：

不写入普通应用日志。
不通过前端业务接口返回。
不提交为测试夹具中的真实客户数据。
生产使用时需要控制数据库访问权限，并在上线前确认保留周期。

5.8 KiB Raw Blame History Unescape Escape