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

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 内部异常 |