收口MCP提交为V4契约

docs/project/integrations/superagent-mcp/tools.md

@@ -330,37 +330,33 @@ POST /api/ai-query/v1/message-conversation/messages
 
 ### 7.1 用途
 
-提交 SuperAgent 对单封外部来源消息的 AI 任务识别结果。该工具会写入 AI 过渡层、订单、任务和任务卡。
+提交 SuperAgent 对单封外部来源消息的 M002 V4 任务识别结果。该工具会写入 AI 过渡层、V4 订单任务、V4 任务卡或 V4 来源通知。
 
 ### 7.2 何时使用
 
 - SuperAgent 已完成当前邮件的最终任务拆分。
-- 已确认外部 `source_message_id` 来自 AgentBus payload；`hotel_id` 由 TH Hotel 后端解析。
-- 不需要为写入工具传数据库层 `source_provider` / `source_channel`；后端会按系统酒店和外部消息 ID 匹配真实 Inbox 记录。
+- 已确认 `source_message.source_message_id` 来自 AgentBus payload 的外部消息 ID；`hotel_id` 由 TH Hotel 后端解析。
+- 不需要为写入工具传数据库层 `hotel_id` / `source_provider` / `source_channel`；后端会按系统酒店和外部消息 ID 匹配真实 Inbox 记录。
 - 需要把 AI 任务结果交给 TH Hotel 后端进入人工确认流程。
 
 ### 7.3 不应使用
 
 - 不应在试探、草稿、未完成推理阶段调用。
 - 不应把历史邮件中的外部来源消息 ID 当作当前邮件 ID 提交。
-- 不应在缺少 `source_message_id` 时调用；`hotel_id` 不需要 SuperAgent 提供。
+- 不应在缺少 V4 `source_message.source_message_id` 时调用。
+- 不应继续提交 V2 `ai_task_results[]` 或 V3 `case_candidates` / `unhandled_current_intents` 结构。
 
 ### 7.4 输入 Schema
 
-当前 MCP tool 已支持三种输入形态，真实机器可读 schema 以 `/mcp` 的 `tools/list` 返回为准：
-
-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[]`。
+当前 MCP tool 只支持 M002 V4 包级结构，真实机器可读 schema 以 `/mcp` 的 `tools/list` 返回为准。
 
 补充规则：
 
-- V3 业务根或 S10/S99 如果携带 `hotel_id`、`source_provider`、`source_channel`，MCP adapter 会接受这些兼容字段，但转交业务入站层前会移除；业务定位仍以系统酒店和外部 `source_message_id` 为准。
-- 缺失 `source_message.source_message_id` 或整个 `source_message` 时，MCP adapter 不改写错误，业务入站层返回 `MISSING_SOURCE_MESSAGE_ID`。
-- V3 event 业务合法性问题，例如 unsupported `event_type`、不完整 `case_keys`、不完整 `manual_review`，由业务入站层保存为 `adapter_contract_error` transition；MCP adapter 只拦 transport 必需问题，包括未知字段、`source_event_index` 缺失/重复、关系悬空/重复。
-- V2 `ai_task_results[]` item 已在 MCP schema 和 adapter 中完整校验，必填字段为 `source_event_index`、`catalog_code`、`skill_id`、`result_type`、`task_type`。
+- V4 普通业务包：`route_code=null + source_message + order_contexts[] + message_events[]`。
+- V4 来源通知包：`route_code=S10/S99 + source_message + order_contexts=[] + message_events=[]`。
+- MCP adapter 只校验 V4 根结构和 V4 `source_message` / `attachments` transport 形态；event 业务契约问题由业务入站层记录 `adapter_contract_error`。
+- 旧 V2/V3 payload 返回 `MCP_SUBMIT_V4_REQUIRED`，不会调用业务写入 Service。
+- V4 根字段外的 `hotel_id`、`source_provider`、`source_channel`、`handler_type`、`result_type`、`ai_task_results`、`case_candidates` 等字段都会被拒绝。
 
 下面 JSON 是关键结构节选；不要手工复制为最终 schema，联调时应以 `tools/list` 实时返回为准。
 
@@ -369,158 +365,122 @@ MCP 层会先调用 `SuperAgentMcpSubmitPayloadAdapter` 做提交前校验和事
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "hotel_id": {
+    "route_code": {
       "type": ["string", "null"],
-      "description": "可选酒店上下文 ID；默认由 TH Hotel 后端解析"
-    },
-    "source_provider": {
-      "type": ["string", "null"],
-      "description": "兼容字段；写入工具通常不需要传，后端写入定位不使用该字段"
-    },
-    "source_channel": {
-      "type": ["string", "null"],
-      "description": "兼容字段；写入工具通常不需要传，后端写入定位不使用该字段，AgentBus 实际入库渠道可能是 OUTLOOK"
+      "description": "M002 V4 包级路由；普通业务必须为 null，来源通知为 S10 或 S99"
     },
     "source_message": {
       "type": "object",
-      "description": "V3 来源邮件元数据；source_message_id 对应 AgentBus source.external_message_id",
       "properties": {
-        "source_message_id": {
-          "type": "string"
+        "source_message_id": { "type": "string" },
+        "conversation_id": { "type": ["string", "null"] },
+        "subject": { "type": ["string", "null"] },
+        "sender": { "type": ["string", "null"] },
+        "sent_at": { "type": ["string", "null"] },
+        "body": { "type": ["string", "null"] },
+        "body_content_type": {
+          "type": "string",
+          "enum": ["text/plain", "text/html"]
         },
-        "subject": {
-          "type": ["string", "null"]
-        },
-        "from": {
-          "type": ["string", "null"]
-        },
-        "cc": {
+        "attachments": {
           "type": "array",
           "items": {
-            "type": "string"
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "name", "content_type", "url"],
+            "properties": {
+              "id": { "type": "string" },
+              "name": { "type": "string" },
+              "content_type": { "type": "string" },
+              "url": { "type": "string" },
+              "size": { "type": ["number", "null"] }
+            }
           }
-        },
-        "received_at": {
-          "type": ["string", "null"]
-        },
-        "source_channel": {
-          "type": "string",
-          "enum": ["Email"]
         }
       },
-      "required": ["source_message_id", "subject", "from", "cc", "received_at", "source_channel"]
+      "required": ["source_message_id", "subject", "sender", "sent_at", "body", "body_content_type", "attachments"]
     },
-    "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": {
+    "order_contexts": {
       "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": "V2 兼容字段：外部来源消息 ID，对应 AgentBus source.external_message_id"
-    },
-    "ai_task_results": {
-      "type": "array",
-      "description": "V2 兼容字段：AI 拆分出的任务结果，必须保留数组顺序",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["source_event_index", "catalog_code", "skill_id", "result_type", "task_type"],
+        "required": ["order_ref", "basic_information"],
         "properties": {
-          "source_event_index": {
-            "type": ["integer", "string"]
-          },
-          "catalog_code": {
-            "type": "string"
-          },
-          "skill_id": {
-            "type": "string"
-          },
-          "result_type": {
-            "type": "string",
-            "enum": ["normal_task", "manual_review", "informational_message"]
-          },
-          "task_type": {
-            "type": "string"
+          "order_ref": { "type": "string" },
+          "basic_information": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["account_code", "manual_review"],
+            "properties": {
+              "account_code": { "type": ["string", "null"] },
+              "manual_review": { "type": ["boolean", "null"] }
+            }
           }
         }
       }
     },
-    "extraction_warnings": {
+    "message_events": {
       "type": "array",
-      "description": "AI 抽取警告；V3/V2 都允许，缺省按空数组处理",
       "items": {
-        "type": "object"
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["order_ref", "event_type", "target_order", "manual_review"],
+        "properties": {
+          "order_ref": { "type": "string" },
+          "event_type": {
+            "type": "string",
+            "enum": ["NEW_BOOKING", "UPDATE_BOOKING", "CANCEL_BOOKING", "TRACE_RESERVATION_NOTES", "ROOMING_LIST", "PAYMENT"]
+          },
+          "target_order": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["booking_type", "locator_type", "locator_value"],
+            "properties": {
+              "booking_type": { "type": ["string", "null"] },
+              "locator_type": { "type": ["string", "null"] },
+              "locator_value": { "type": ["string", "null"] }
+            }
+          },
+          "manual_review": {
+            "type": ["boolean", "null"]
+          },
+          "arrival_date": { "type": ["string", "null"] },
+          "departure_date": { "type": ["string", "null"] },
+          "rate_code": { "type": ["string", "null"] },
+          "booking_scenario": { "type": ["string", "null"] },
+          "guest_name": { "type": ["string", "null"] },
+          "room_items": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["room_type_code", "room_count"],
+              "properties": {
+                "room_type_code": { "type": ["string", "null"] },
+                "room_count": { "type": ["integer", "null"] }
+              }
+            }
+          },
+          "after": { "type": "object" },
+          "trace_items": { "type": "array" },
+          "attachment_ids": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
       }
     }
   },
-  "required": [],
-  "oneOf": [
-    {
-      "required": ["source_message", "message_events", "case_candidates", "extraction_warnings", "unhandled_current_intents"]
-    },
-    {
-      "required": ["source_message", "route_code", "handler_type", "result_type", "current_or_history", "agent_assessment", "notification", "manual_review"]
-    },
-    {
-      "required": ["source_message_id", "ai_task_results"]
-    }
-  ]
+  "required": ["route_code", "source_message", "order_contexts", "message_events"]
 }
 ```
 
 说明：
 
-- 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。
+- V4 字段完整语义以 `superagent-api-contract.md` 第 8 节和 `M002-v4-agent-callback-field-contract.md` 为准。
+- `source_message.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。
-- MCP adapter 校验失败时返回 `MCP_SUBMIT_PAYLOAD_INVALID`，不会调用业务写入 Service，也不会自动重试。
+- 旧 V2/V3 payload 会返回 `MCP_SUBMIT_V4_REQUIRED`；V4 transport 校验失败返回 `MCP_SUBMIT_PAYLOAD_INVALID`。两者都不会调用业务写入 Service，也不会自动重试。
 
 ### 7.5 输出
 
@@ -537,9 +497,8 @@ POST /api/integrations/superagent/task-results
 - `accepted_count`：接收数量。
 - `items[].ai_transition_id`：AI 过渡层 ID。
 - `items[].order_id`：订单 ID。
-- `items[].task_id`：任务 ID。
-- `items[].task_status`：任务状态。
-- `mapping_diagnostics`：仅 MCP 写入工具在 V3 业务根映射时返回，记录 Agent 原始事件 ID 到本系统一基索引的映射；不写入业务 JSON。
+- `items[].task_id`：V4 主线不再返回旧任务 ID，通常为 `null`。
+- `items[].task_status`：V4 主线不再返回旧任务状态，通常为 `null`。
 
 完整字段以 `superagent-api-contract.md` 第 8 节为准。
 
@@ -574,5 +533,6 @@ MCP 层新增错误建议：
 | `MCP_REQUEST_BODY_TOO_LARGE` | MCP 请求体超过 10MB 默认限制或环境配置限制 |
 | `MCP_METHOD_NOT_FOUND` | MCP 方法不存在 |
 | `MCP_TOOL_NOT_FOUND` | MCP 工具不存在 |
+| `MCP_SUBMIT_V4_REQUIRED` | 写入工具收到的不是 M002 V4 根结构，例如旧 V2/V3 payload |
 | `MCP_SUBMIT_PAYLOAD_INVALID` | 写入工具 payload 未通过 MCP adapter 提交前校验 |
 | `MCP_INTERNAL_ERROR` | MCP endpoint 内部异常 |