134 lines
5.8 KiB
Markdown
134 lines
5.8 KiB
Markdown
# 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，因此：
|
||
|
||
- 不写入普通应用日志。
|
||
- 不通过前端业务接口返回。
|
||
- 不提交为测试夹具中的真实客户数据。
|
||
- 生产使用时需要控制数据库访问权限，并在上线前确认保留周期。
|