实现MCP任务结果提交稳定性映射

2026-07-12 19:10:03 +08:00
parent 937aa569ff
commit 9d095cfd53
15 changed files with 1468 additions and 17 deletions
--- a/docs/import/20260712/MCP_最终提交稳定性改造要求_给开发伙伴_2026-07-12.md
+++ b/docs/import/20260712/MCP_最终提交稳定性改造要求_给开发伙伴_2026-07-12.md
@@ -0,0 +1,159 @@
+# MCP 最终提交稳定性改造要求
+
+## 一、改造目标
+
+在不改变现有业务规则和业务系统输出规范的前提下，确保 Agent 生成的业务结果可以稳定转换为 MCP 可接收的 payload。
+
+我们不要求 Agent 自行理解或猜测 MCP transport 字段。`source_event_index`、`ai_task_results[]` 等字段的含义、类型和映射，必须由 MCP/Adapter 侧提供确定性实现。
+
+目标链路必须是：
+
+```text
+booking-desk-event Skill
+  → 业务结果
+  → Result Adapter
+  → MCP payload
+  → Schema Validator
+  → 冻结
+  → MCP 提交一次
+```
+
+## 二、必须保持不变的内容
+
+MCP 侧不得通过修改以下内容来解决字段接收问题：
+
+- 现有公开业务 JSON 根结构；
+- `message_events` 的业务事件类型和 subtype；
+- Parent Group / Child Group 业务语义；
+- Trace、Parent、linked/derived 事件关系；
+- S10、S99 和基础设施错误规范；
+- Skill 的业务裁决权；
+- 一次冻结、一次提交、失败不重试的生命周期。
+
+MCP 只负责接收和处理已经形成的业务结果，不负责重新解释业务含义。
+
+## 三、必须由 MCP/Adapter 侧承担的职责
+
+### 1. 提供确定性的 payload mapping
+
+必须建立固定的：
+
+```text
+BusinessResult → MCP payload
+```
+
+映射层。
+
+该层不能由 LLM 临时生成，也不能让 Agent 根据字段名称猜测。
+
+至少需要明确：
+
+| 字段 | 必须明确的内容 |
+|---|---|
+| `source_message_id` | 来源、类型、必填规则、透传方式 |
+| `source_event_index` | 真实含义、类型、索引基准、对应数组 |
+| `related_source_event_index` | 单事件关系如何映射 |
+| `related_source_event_indices` | 多事件关系如何映射、顺序和唯一性 |
+| `ai_task_results[]` | item 的完整结构和业务结果映射方式 |
+| `extraction_warnings` | 是否必填、允许的结构和空值规则 |
+
+`E1`、`E2` 只能作为 Agent/业务结果中的内部事件标识，不能默认当作 MCP 的 `source_event_index`。
+
+### 2. 负责生成 `source_event_index`
+
+Adapter 必须建立事件映射，例如：
+
+```text
+E_CHILD_1 → MCP index 0
+E_CHILD_2 → MCP index 1
+E_PARENT  → MCP index 2
+E_TRACE   → MCP index 3
+```
+
+实际索引类型和起始值必须以真实 MCP schema 为准，不允许 Agent 猜测。
+
+对于：
+
+```json
+"related_source_event_indices": ["E_CHILD_1", "E_CHILD_2"]
+```
+
+Adapter 必须将其转换成 MCP 真实要求的索引格式，并保持顺序、唯一性和关联正确。
+
+### 3. 支持跨事件 Trace
+
+当前业务要求：
+
+- 一个补充请求覆盖完整 Parent split 的全部 Child；
+- Trace 必须关联全部 Child；
+- 不得绑定到第一个 Child E1；
+- 必须保留完整跨事件关系。
+
+因此 MCP/Adapter 必须能够接收和保持：
+
+```text
+Trace
+  → related_source_event_indices[]
+  → 全部 Child New Booking
+```
+
+不能把多目标 Trace 压缩成单一 `source_event_index`。
+
+## 四、提交前必须有 Schema Validator
+
+MCP 调用前必须校验：
+
+- 必填字段；
+- 字段类型；
+- 允许值；
+- 数组顺序；
+- 索引是否存在；
+- 关系是否悬空；
+- 是否存在重复索引；
+- 是否存在未知字段；
+- `ai_task_results[]` item 是否符合完整 schema；
+- `source_message_id` 是否正确传播。
+
+校验失败时：
+
+- 不让 Agent 猜字段；
+- 不修改已经冻结的业务结果；
+- 不重新调用 Skill；
+- 不重试 MCP；
+- 按既有 transport/基础设施错误通道结束；
+- 保留原始错误和 mapping 诊断。
+
+## 五、必须提供的 MCP 交付物
+
+请提供以下内容：
+
+1. 当前实际使用的完整 MCP tool schema；
+2. `ai_task_results[]` 的完整 item schema；
+3. `source_event_index` 和关联索引的正式定义；
+4. BusinessResult → MCP payload mapping 文档；
+5. 一个成功的完整 payload 示例；
+6. 一个跨 Child Trace 的成功示例；
+7. 一个错误字段被拒绝的示例；
+8. Adapter 或 MCP wrapper 的实现位置；
+9. Schema validation 和一次提交测试结果；
+10. 失败不重试、payload 不被修改的测试证据。
+
+## 六、验收条件
+
+以下测试必须通过：
+
+1. Agent 使用 `E1` 时，Adapter 不会盲目把它当成 MCP index；
+2. 错误关系索引会在提交前被拒绝；
+3. 缺失 `source_message_id` 会按既有基础设施错误处理；
+4. MCP 失败时只提交一次，不重试；
+5. 提交 payload 与冻结结果的 mapping 可追溯；
+6. MCP 响应不会污染业务 JSON。
+
+
+## 最终要求
+
+请不要通过继续增加 Prompt 文字，让 Agent 学习 MCP 内部字段含义来解决问题。
+
+我们要求的是：
+
+> MCP/Adapter 提供稳定、确定性、可验证的业务结果到 MCP payload 的转换能力；Agent 负责业务结果，MCP 负责 transport 接收，两者之间不能依赖模型猜测。
--- a/docs/project/integrations/superagent-api-contract.md
+++ b/docs/project/integrations/superagent-api-contract.md
@@ -561,6 +561,7 @@ V3 字段说明：

 当前已支持的 V3 行为：

+- 如果通过 MCP `th_hotel_submit_task_results` 调用，MCP adapter 会在进入业务入站服务前按 `message_events[]` 顺序把 Agent 内部事件 ID 映射为本系统一基 `source_event_index`，并校验 `related_source_event_index`、`parent_source_event_index` 和 `related_source_event_indices[]` 是否悬空或重复。
 - 40 条 P0.1 路由进入后端枚举 / 稳定配置。
 - `route_code` 是稳定代码，不因路由总数从 42 调整为 40 而重编号；联调方不要按数字连续性判断合法性。
 - 结构化 `S10/S99` 创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见。
--- a/docs/project/integrations/superagent-mcp/README.md
+++ b/docs/project/integrations/superagent-mcp/README.md
@@ -23,6 +23,7 @@ server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/
 | --- | --- |
 | `integration-guide.md` | MCP 总体接入说明和调用顺序 |
 | `tools.md` | 5 个 MCP tools 的工具契约 |
+| `submit-payload-mapping.md` | `th_hotel_submit_task_results` 的 V3/P0.1 payload adapter、事件索引映射和提交前校验 |
 | `security-policy.md` | 鉴权、权限、正文、附件和日志边界 |
 | `deployment-guide.md` | 部署参数、环境变量和上线顺序 |
 | `test-cases.md` | SuperAgent 联调测试用例 |
--- a/docs/project/integrations/superagent-mcp/integration-guide.md
+++ b/docs/project/integrations/superagent-mcp/integration-guide.md
@@ -132,6 +132,8 @@ REST request

 写入工具里的 `source_message_id` 必须来自 AgentBus payload 的 `source.external_message_id`。SuperAgent 不需要传数据库层 provider/channel；TH Hotel 后端按系统酒店和外部消息 ID 匹配唯一 SourceMessage Inbox，真实 channel 可能是 `OUTLOOK`。

+M002 V3 后，写入工具优先接收结构化 `S10/S99` 或 `source_message + message_events[]` 业务根。`message_events[].source_event_index` 可以是 SuperAgent 内部事件 ID，例如 `E_CHILD_1`；MCP adapter 会在提交前按数组顺序映射为本系统一基数字索引，并校验跨事件关系是否悬空或重复。详细映射规则见 `submit-payload-mapping.md`。
+
 ## 9. 当前 checkpoint

 当前 checkpoint：
@@ -146,5 +148,6 @@ checkpoint-superagent-mcp-embedded-endpoint
 - 5 个 MCP tools 均可通过 `tools/list` 发现。
 - 只读 tool 直接复用现有查询 Service。
 - 写入 tool 受 `MCP_ENABLE_SUBMIT_TASK_RESULTS` 开关控制。
+- 写入 tool 已提供 V3/P0.1 submit payload adapter 和提交前 schema validator。
 - MCP endpoint 使用 Bearer Token 鉴权。
 - 文档不包含生产 Secret、真实客户数据、附件 URL 或原始邮件正文。
--- a/docs/project/integrations/superagent-mcp/security-policy.md
+++ b/docs/project/integrations/superagent-mcp/security-policy.md
@@ -129,6 +129,7 @@ MCP endpoint 日志允许记录：
 写入工具：

 - 默认不自动重试已发送的写请求。
+- MCP submit payload adapter 校验失败时，不调用业务写入 Service，也不触发自动重试。
 - 如果调用方需要重试，必须依赖后端幂等机制和任务结果中的幂等信息。
 - 对于响应丢失但请求可能已到达后端的场景，应优先查询已有任务或人工排查，避免重复写入。

--- a/docs/project/integrations/superagent-mcp/submit-payload-mapping.md
+++ b/docs/project/integrations/superagent-mcp/submit-payload-mapping.md
@@ -0,0 +1,308 @@
+# TH Hotel MCP Submit Payload Mapping
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档版本 | 0.1 |
+| 日期 | 2026-07-12 |
+| 状态 | 已落地第一版 |
+| 适用范围 | `th_hotel_submit_task_results` 的 V3/P0.1 payload adapter、schema validator 和一次提交规则 |
+
+## 2. 核心原则
+
+`th_hotel_submit_task_results` 接收的是 SuperAgent 已经冻结的业务结果。MCP 层只负责把业务结果转换为本系统可接收的提交 payload，不重新解释业务含义，不调用 Skill，不根据字段名猜测任务类型。
+
+目标链路：
+
+```text
+SuperAgent 业务结果
+  -> MCP Submit Payload Adapter
+  -> MCP Submit Schema Validator
+  -> ReservationAiTaskIntakeService
+  -> MCP tool result
+```
+
+实现位置：
+
+```text
+server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/service/SuperAgentMcpSubmitPayloadAdapter.java
+server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/service/impl/SuperAgentMcpSubmitPayloadAdapterImpl.java
+```
+
+## 3. 支持的输入形态
+
+| 形态 | 判断方式 | 处理方式 |
+| --- | --- | --- |
+| V3 业务根 | 同时包含 `source_message` 和 `message_events` | 先校验根结构、source message、event 必填字段和关系索引，再按 `message_events[]` 顺序映射 `source_event_index` |
+| V3 S10/S99 入口通知 | 同时包含 `source_message` 和 `route_code` | 校验 S10/S99 根字段和 source message 后透传给业务入站服务 |
+| V2 兼容任务结果 | 包含 `ai_task_results` | 保留旧 `source_message_id + ai_task_results[]` 兼容路径 |
+
+未知根字段会在 MCP 层被拒绝，错误码为 `MCP_SUBMIT_PAYLOAD_INVALID`。
+
+`source_message_id` 缺失属于既有基础设施输入错误，MCP adapter 不改写该错误通道；业务入站服务会返回 `MISSING_SOURCE_MESSAGE_ID`。
+
+## 4. source_message_id 定义
+
+| 字段 | 规则 |
+| --- | --- |
+| `source_message.source_message_id` | V3 必填；必须来自 AgentBus 原始 payload 的外部消息 ID，对应 `platform_source_message_inbox.external_message_id` |
+| `source_message_id` | V2 兼容必填；同样对应 `platform_source_message_inbox.external_message_id` |
+| `hotel_id` | SuperAgent 正式提交不需要传；本系统按平台唯一 ACTIVE 酒店解析 |
+
+`source_message_id` 不是本系统数据库主键，也不是 `platform_source_message_inbox.id`。
+
+## 5. source_event_index 映射
+
+SuperAgent 业务结果中的 `E1`、`E_CHILD_1`、`E_PARENT` 等值只是 Agent 内部事件 ID，不能直接当成本系统的 `source_event_index`。
+
+MCP adapter 按 `message_events[]` 数组顺序生成一基数字索引：
+
+| 业务事件 ID | 数组位置 | 本系统 `source_event_index` |
+| --- | --- | --- |
+| `E_CHILD_1` | 第 1 个 event | `1` |
+| `E_CHILD_2` | 第 2 个 event | `2` |
+| `E_PARENT` | 第 3 个 event | `3` |
+| `E_TRACE` | 第 4 个 event | `4` |
+
+映射规则：
+
+- `message_events[].source_event_index` 输出为数字。
+- `related_source_event_index` 输出为字符串数字，例如 `"1"`。
+- `parent_source_event_index` 输出为数字。
+- `related_source_event_indices[]` 输出为字符串数字数组，保持原顺序。
+- 悬空引用、重复引用、缺失事件 ID 都在 MCP 层拒绝。
+
+## 6. ai_task_results[] 兼容 item schema
+
+V2 兼容路径仍保留，`ai_task_results[]` item 以 REST 总契约为准，第一版 MCP schema 只暴露 object，但业务入站会校验核心字段。
+
+建议 item 结构：
+
+```json
+{
+  "source_event_index": 1,
+  "catalog_code": "S01",
+  "skill_id": "S01_new_booking_skill",
+  "result_type": "normal_task",
+  "task_type": "New Booking",
+  "task_subtype": "new_fit_reservation",
+  "current_or_history": "current",
+  "case_keys": {
+    "group_code": null,
+    "confirmation_number": null,
+    "reservation_number": null,
+    "block_code": null
+  },
+  "relevant_message_excerpt": "Please create a new booking.",
+  "attachments": [],
+  "file_references": [],
+  "context_used": {},
+  "extracted_fields": {},
+  "manual_review": null,
+  "additional_operations": [],
+  "idempotency_key": null
+}
+```
+
+新数据优先使用 V3 业务根或 V3 S10/S99，不建议继续新增 V2 `ai_task_results[]`。
+
+## 7. extraction_warnings 规则
+
+| 形态 | 规则 |
+| --- | --- |
+| V3 业务根 | `extraction_warnings` 必须存在且为数组，无警告传 `[]` |
+| V2 兼容 | `extraction_warnings` 可存在且为数组；缺省由业务层按空数组处理 |
+
+MCP 层不解释 warning 语义，不因为 warning 自动创建任务。
+
+## 8. 成功示例：Parent Split
+
+提交给 MCP tool 的业务结果可以使用 Agent 内部事件 ID：
+
+```json
+{
+  "source_message": {
+    "source_message_id": "mail-20260712-parent-split-001",
+    "subject": "Parent split booking request",
+    "from": "agent@example.test",
+    "cc": [],
+    "received_at": "2026-07-12T04:00:00Z",
+    "source_channel": "Email"
+  },
+  "message_events": [
+    {
+      "event_type": "New Booking",
+      "event_role": "travel_agent_request",
+      "source_event_index": "E_CHILD_1",
+      "current_or_history": "current",
+      "case_keys": {
+        "group_code": "CHILD-A",
+        "confirmation_number": null,
+        "reservation_number": null,
+        "block_code": null
+      },
+      "relevant_message_excerpt": "Create child group A.",
+      "attachments": [],
+      "file_references": [],
+      "context_used": {},
+      "extracted_fields": {
+        "booking_object_type": "Group Block"
+      },
+      "manual_review": null
+    },
+    {
+      "event_type": "New Booking",
+      "event_role": "travel_agent_request",
+      "source_event_index": "E_CHILD_2",
+      "current_or_history": "current",
+      "case_keys": {
+        "group_code": "CHILD-B",
+        "confirmation_number": null,
+        "reservation_number": null,
+        "block_code": null
+      },
+      "relevant_message_excerpt": "Create child group B.",
+      "attachments": [],
+      "file_references": [],
+      "context_used": {},
+      "extracted_fields": {
+        "booking_object_type": "Group Block"
+      },
+      "manual_review": null
+    },
+    {
+      "event_type": "Cancel Allotment",
+      "event_role": "travel_agent_request",
+      "source_event_index": "E_PARENT",
+      "current_or_history": "current",
+      "case_keys": {
+        "group_code": "PARENT",
+        "confirmation_number": null,
+        "reservation_number": null,
+        "block_code": "PARENT"
+      },
+      "relevant_message_excerpt": "Release parent after child split.",
+      "attachments": [],
+      "file_references": [],
+      "context_used": {},
+      "related_event_type": "New Booking",
+      "requires_downstream_hard_validation": true,
+      "related_source_event_indices": ["E_CHILD_1", "E_CHILD_2"],
+      "extracted_fields": {
+        "relationship_type": "linked_parent_release_after_child_split",
+        "parent_group_code": "PARENT",
+        "cancel_scope": "entire_allotment_control_block",
+        "parent_release_or_cancel_candidate": true,
+        "release_reason": "parent_to_child_allocation_split",
+        "allocation_split_from_parent": true,
+        "child_group_codes": ["CHILD-A", "CHILD-B"]
+      },
+      "manual_review": null
+    }
+  ],
+  "case_candidates": [],
+  "extraction_warnings": [],
+  "unhandled_current_intents": []
+}
+```
+
+MCP adapter 进入业务层前会把父事件关系映射为：
+
+```json
+{
+  "source_event_index": 3,
+  "related_source_event_indices": ["1", "2"]
+}
+```
+
+## 9. 成功示例：跨 Child Trace
+
+当 Trace 覆盖完整 Parent split 的全部 Child 时，不能只绑定第一个 Child。业务结果应保留全部 Child 引用：
+
+```json
+{
+  "event_type": "Trace",
+  "source_event_index": "E_TRACE",
+  "related_source_event_indices": ["E_CHILD_1", "E_CHILD_2"],
+  "extracted_fields": {
+    "trace_subtype": "general_request"
+  }
+}
+```
+
+MCP adapter 会把它映射为：
+
+```json
+{
+  "source_event_index": 4,
+  "related_source_event_indices": ["1", "2"]
+}
+```
+
+## 10. 拒绝示例
+
+未知字段：
+
+```json
+{
+  "source_message": {},
+  "message_events": [],
+  "case_candidates": [],
+  "extraction_warnings": [],
+  "unhandled_current_intents": [],
+  "unexpected_root": true
+}
+```
+
+返回：
+
+```json
+{
+  "isError": true,
+  "structuredContent": {
+    "success": false,
+    "error": {
+      "code": "MCP_SUBMIT_PAYLOAD_INVALID",
+      "details": {
+        "field": "unexpected_root"
+      }
+    }
+  }
+}
+```
+
+悬空关系：
+
+```json
+{
+  "related_source_event_indices": ["E_CHILD_1", "E_UNKNOWN_CHILD"]
+}
+```
+
+同样返回 `MCP_SUBMIT_PAYLOAD_INVALID`，`details.field=related_source_event_indices`，不会调用业务写入 Service。
+
+## 11. 一次提交和失败不重试
+
+当前 MCP endpoint 与后端业务 Service 同进程：
+
+- adapter 校验失败时，不调用 `ReservationAiTaskIntakeService`。
+- adapter 校验通过后，只调用一次 `ReservationAiTaskIntakeService.accept`。
+- MCP endpoint 不做自动重试。
+- 业务结果不会因为 MCP 响应被回写或污染。
+
+当前回归测试：
+
+```text
+./mvnw -Dtest=SuperAgentMcpControllerTest,SuperAgentMcpSubmitEnabledControllerTest test
+```
+
+覆盖内容：
+
+- `tools/list` 暴露 V3 submit schema。
+- 缺失 `source_message_id` 保持既有 `MISSING_SOURCE_MESSAGE_ID` 错误。
+- 未知根字段在业务层前被拒绝。
+- 悬空 `related_source_event_indices` 在业务层前被拒绝。
+- 重复 `related_source_event_indices` 在业务层前被拒绝。
+- `E_CHILD_1/E_CHILD_2/E_PARENT` 按数组顺序映射为 `1/2/3`。
+- 合法 Parent split 只创建一个 AI batch，并返回 `accepted_count=3`。
--- a/docs/project/integrations/superagent-mcp/test-cases.md
+++ b/docs/project/integrations/superagent-mcp/test-cases.md
@@ -93,12 +93,21 @@
 | MCP-T05-007 | hotel id 不一致 | 显式传非系统酒店 `hotel_id` | 返回 `HOTEL_ID_MISMATCH` |
 | MCP-T05-008 | source message 入库渠道为 OUTLOOK | 不传 `source_channel`，只传外部 `source_message_id` | 后端按真实 Inbox 渠道写入成功 |
 | MCP-T05-009 | source message 多渠道重复 | 同一酒店存在相同外部 `source_message_id` 的多条 Inbox | 返回 `SOURCE_MESSAGE_AMBIGUOUS` |
+| MCP-T05-010 | V3 Parent split 使用 Agent 内部事件 ID | `message_events[].source_event_index=E_CHILD_1/E_CHILD_2/E_PARENT` | MCP adapter 按数组顺序映射为 `1/2/3`，返回 `accepted_count=3` |
+| MCP-T05-011 | V3 缺失 source message id | `source_message.source_message_id` 缺失 | 返回既有 `MISSING_SOURCE_MESSAGE_ID` typed infrastructure error |
+| MCP-T05-012 | V3 多事件关系悬空 | `related_source_event_indices` 引用不存在的事件 ID | 返回 `MCP_SUBMIT_PAYLOAD_INVALID`，不写 AI batch、订单或任务 |
+| MCP-T05-013 | V3 多事件关系重复 | `related_source_event_indices=["E_CHILD_1","E_CHILD_1"]` | 返回 `MCP_SUBMIT_PAYLOAD_INVALID`，不写 AI batch、订单或任务 |
+| MCP-T05-014 | V3 根节点未知字段 | 根节点存在 `unexpected_root` | 返回 `MCP_SUBMIT_PAYLOAD_INVALID`，不调用业务写入 Service |
+| MCP-T05-015 | V3 跨 Child Trace | Trace event 关联全部 Child event | `related_source_event_indices[]` 保留全量关系并映射为真实索引，不压缩到第一个 Child |

 写入验证：

 - `ai_task_results[]` 顺序不能被 MCP endpoint 改变。
+- V3 `message_events[]` 顺序是 `source_event_index` 的唯一基准，MCP endpoint 不能重排。
+- `E1/E2/E_PARENT` 等 Agent 内部事件 ID 只能由 MCP adapter 转换，不能作为本系统最终 `source_event_index`。
 - MCP endpoint 不能在日志输出完整 `extracted_fields` 中的敏感内容。
 - 失败响应应保留后端错误码和 message。
+- MCP adapter 校验失败时不进入业务写入 Service，且不自动重试。

 ## 9. MCP 鉴权和开关测试

@@ -127,6 +136,7 @@
 - 5 个工具正常成功调用。
 - 查询接口错误 envelope 不丢失。
 - 任务结果写入成功和幂等重放正常。
+- V3 submit payload adapter 的事件索引映射、悬空关系拒绝、重复关系拒绝和未知字段拒绝正常。
 - provider/channel 隔离正常。
 - 受控正文不返回附件 URL。
 - MCP auth 失败不进入业务 Service。
--- a/docs/project/integrations/superagent-mcp/tools.md
+++ b/docs/project/integrations/superagent-mcp/tools.md
@@ -347,7 +347,13 @@ POST /api/ai-query/v1/message-conversation/messages

 ### 7.4 输入 Schema

-迁移提醒：当前 MCP tool 仍对应 M002 V2 的 `ai_task_results[]` 阶段契约。M002 V3 已确认迁移到结构化 `S10/S99` 和业务根 `message_events[]`，后续 MCP tool schema 必须跟随 `docs/project/integrations/superagent-api-contract.md` 和 `docs/project/requirements/M002-order-task-workflow-v3.md` 同步更新；在实现前不要把下方 schema 当作 V3 新入口。
+当前 MCP tool 已支持三种输入形态：
+
+1. V3 业务根：`source_message + message_events[]`。
+2. V3 S10/S99 入口通知：`source_message + route_code`。
+3. V2 兼容任务结果：`source_message_id + ai_task_results[]`。
+
+MCP 层会先调用 `SuperAgentMcpSubmitPayloadAdapter` 做提交前校验和事件索引映射。`E1`、`E_CHILD_1`、`E_PARENT` 等 Agent 内部事件 ID 不会直接进入业务层；adapter 会按 `message_events[]` 顺序生成本系统一基数字 `source_event_index`，并同步映射 `related_source_event_index`、`parent_source_event_index` 和 `related_source_event_indices[]`。

 ```json
 {
@@ -366,36 +372,115 @@ POST /api/ai-query/v1/message-conversation/messages
      "type": ["string", "null"],
      "description": "兼容字段；写入工具通常不需要传，后端写入定位不使用该字段，AgentBus 实际入库渠道可能是 OUTLOOK"
    },
+    "source_message": {
+      "type": "object",
+      "description": "V3 来源邮件元数据；source_message_id 对应 AgentBus source.external_message_id",
+      "properties": {
+        "source_message_id": {
+          "type": "string"
+        },
+        "subject": {
+          "type": ["string", "null"]
+        },
+        "from": {
+          "type": ["string", "null"]
+        },
+        "cc": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "received_at": {
+          "type": ["string", "null"]
+        },
+        "source_channel": {
+          "type": "string",
+          "enum": ["Email"]
+        }
+      },
+      "required": ["source_message_id", "subject", "from", "cc", "received_at", "source_channel"]
+    },
+    "route_code": {
+      "type": ["string", "null"],
+      "description": "V3 S10/S99 入口通知路由码"
+    },
+    "handler_type": {
+      "type": ["string", "null"],
+      "description": "V3 Main Agent 输出处理器类型"
+    },
+    "result_type": {
+      "type": ["string", "null"],
+      "description": "V3 入口通知或 V2 任务结果类型"
+    },
+    "current_or_history": {
+      "type": ["string", "null"],
+      "description": "V3 current/history 标记"
+    },
+    "agent_assessment": {
+      "type": "object",
+      "description": "V3 S10/S99 入口判断摘要"
+    },
+    "notification": {
+      "type": "object",
+      "description": "V3 S10/S99 通知展示信息"
+    },
+    "manual_review": {
+      "type": ["object", "null"],
+      "description": "V3 人工复核对象；S10 可为空，S99 必须完整"
+    },
+    "message_events": {
+      "type": "array",
+      "description": "V3 业务事件数组；MCP Adapter 会按数组顺序生成一基 source_event_index",
+      "items": {
+        "type": "object"
+      }
+    },
+    "case_candidates": {
+      "type": "array",
+      "description": "V3 订单候选数组，无候选传空数组",
+      "items": {
+        "type": "object"
+      }
+    },
+    "unhandled_current_intents": {
+      "type": "array",
+      "description": "V3 未覆盖当前意图数组，无意图传空数组",
+      "items": {
+        "type": "object"
+      }
+    },
    "source_message_id": {
      "type": "string",
-      "description": "外部来源消息 ID，对应 AgentBus source.external_message_id"
+      "description": "V2 兼容字段：外部来源消息 ID，对应 AgentBus source.external_message_id"
    },
    "ai_task_results": {
      "type": "array",
-      "description": "AI 拆分出的任务结果，必须保留数组顺序",
+      "description": "V2 兼容字段：AI 拆分出的任务结果，必须保留数组顺序",
      "items": {
        "type": "object"
      }
    },
    "extraction_warnings": {
      "type": "array",
-      "description": "AI 抽取警告",
+      "description": "AI 抽取警告；V3/V2 都允许，缺省按空数组处理",
      "items": {
        "type": "object"
      }
    }
  },
-  "required": ["source_message_id", "ai_task_results"]
+  "required": []
 }
 ```

 说明：

- `ai_task_results[]` 内部字段较多，完整结构以 `superagent-api-contract.md` 第 8 节为准。
- MCP endpoint 不应重排 `ai_task_results[]`。
+- V3 业务根字段、S10/S99 字段和 V2 `ai_task_results[]` item 完整语义以 `superagent-api-contract.md` 第 8 节为准。
+- BusinessResult 到 MCP payload 的稳定映射、`source_event_index` 正式定义、跨 Child Trace 示例和拒绝示例见 `submit-payload-mapping.md`。
+- MCP endpoint 不应重排 V2 `ai_task_results[]`，也不应重排 V3 `message_events[]`。
 - `source_message_id` 必须是 AgentBus payload 的 `source.external_message_id`，不是内部 `platform_source_message_inbox.id`；写入工具不要求 SuperAgent 知道 Inbox 的真实 channel。
 - 同一系统酒店下如果外部 `source_message_id` 匹配多条 Inbox，业务 Service 返回 `SOURCE_MESSAGE_AMBIGUOUS`，MCP tool result 应原样保留该错误码和 message。
- 如后续需要强 schema 校验，可在 MCP endpoint 内复制 REST 契约中的细粒度字段约束。
+- MCP adapter 校验失败时返回 `MCP_SUBMIT_PAYLOAD_INVALID`，不会调用业务写入 Service，也不会自动重试。

 ### 7.5 输出

@@ -448,4 +533,5 @@ MCP 层新增错误建议：
 | `MCP_REQUEST_BODY_TOO_LARGE` | MCP 请求体超过 10MB 默认限制或环境配置限制 |
 | `MCP_METHOD_NOT_FOUND` | MCP 方法不存在 |
 | `MCP_TOOL_NOT_FOUND` | MCP 工具不存在 |
+| `MCP_SUBMIT_PAYLOAD_INVALID` | 写入工具 payload 未通过 MCP adapter 提交前校验 |
 | `MCP_INTERNAL_ERROR` | MCP endpoint 内部异常 |
--- a/docs/project/requirements/M002-order-task-workflow-v3.md
+++ b/docs/project/requirements/M002-order-task-workflow-v3.md
@@ -405,7 +405,8 @@ V3 建议拆成以下 checkpoint，避免一次性重构过大：
 | M002-V3-CP4 | 列表 / 详情展示 | 已完成第一版：任务列表、订单任务时间线和任务详情透出 V3 路由字段；任务详情支持 S10/S99 入口通知结构、unhandled intent 展示块和 adapter contract error 展示块 |
 | M002-V3-CP5 | 同卡复核解阻 | 已完成第一版：支持 review_status、review_resolution.field_overrides[]、复核场景订单归属确认、JSON Pointer 校验和 READY 流转 |
 | M002-V3-CP6 | P0 fixtures 回归 | 已完成第一版：引入 0711 P0 fixtures / validator 作为后端适配测试参考，覆盖 main_outcomes、candidate_gate、manual_review_resolution、source_identity_errors、parent_split_two_children、row_multiple_derived、allotment_scope；其中 candidate_gate 是 Main Agent 调 Skill 前契约，后端以 validator 和 fixture reference 固化，不作为任务结果回调直接建任务 |
-| M002-V3-CP7 | P0.1 Parent Group 路由修订 | 当前 checkpoint：将 Parent split 父事件从旧 Cancel Booking 迁移为 Cancel Allotment，路由总数 42 → 40，并保留旧 payload 只读兼容 |
+| M002-V3-CP7 | P0.1 Parent Group 路由修订 | 已完成：将 Parent split 父事件从旧 Cancel Booking 迁移为 Cancel Allotment，路由总数 42 → 40，并保留旧 payload 只读兼容 |
+| M002-V3-CP8 | MCP submit 稳定性 | 已完成第一版：MCP `th_hotel_submit_task_results` 支持 V3 业务根、结构化 S10/S99 和 V2 兼容，新增提交前 payload adapter / schema validator，按 `message_events[]` 顺序把 Agent 内部事件 ID 映射为本系统一基 `source_event_index`，并拒绝未知字段、悬空关系和重复关系 |

 ## 13. 明确不做

@@ -441,6 +442,7 @@ V3 P0.1 不做以下事项：
 - `field_contract_version` 历史迁移已收紧：V18 只把没有 `draft_payload_json` 且没有 `confirmed_payload_json` 的 `code-v1` 任务卡标记为 `20260711-p0`；已经存在用户草稿或确认 payload 的历史任务卡保留旧版本，等待重新保存、确认或后续专项 backfill。
 - 订单 / 任务列表、任务详情、草稿保存、最终确认、OPERA 模拟骨架和审计列表。
 - SuperAgent 查询上下文接口 1、2，以及邮件会话相关查询。
+- MCP `th_hotel_submit_task_results` 的 V3/P0.1 payload adapter 和提交前校验；`E1/E_CHILD_1/E_PARENT` 等 Agent 内部事件 ID 不直接进入业务层，由 MCP adapter 映射为 `1/2/3` 等本系统一基索引，跨 Child Trace / Parent split 多事件关系保留顺序并拒绝悬空或重复引用。

 仍需后续 checkpoint 实现：