# 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. 第一版诊断表

新增表：

```text
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 参数：

```sql
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：

```sql
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，因此：

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