修复MCP任务结果提交契约校验

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

@@ -347,7 +347,7 @@ POST /api/ai-query/v1/message-conversation/messages
 
 ### 7.4 输入 Schema
 
-当前 MCP tool 已支持三种输入形态：
+当前 MCP tool 已支持三种输入形态，真实机器可读 schema 以 `/mcp` 的 `tools/list` 返回为准：
 
 1. V3 业务根：`source_message + message_events[]`。
 2. V3 S10/S99 入口通知：`source_message + route_code`。
@@ -355,6 +355,15 @@ POST /api/ai-query/v1/message-conversation/messages
 
 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[]`。
 
+补充规则：
+
+- 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`。
+
+下面 JSON 是关键结构节选；不要手工复制为最终 schema，联调时应以 `tools/list` 实时返回为准。
+
 ```json
 {
   "type": "object",
@@ -458,7 +467,27 @@ MCP 层会先调用 `SuperAgentMcpSubmitPayloadAdapter` 做提交前校验和事
       "type": "array",
       "description": "V2 兼容字段：AI 拆分出的任务结果，必须保留数组顺序",
       "items": {
-        "type": "object"
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source_event_index", "catalog_code", "skill_id", "result_type", "task_type"],
+        "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"
+          }
+        }
       }
     },
     "extraction_warnings": {
@@ -469,7 +498,18 @@ MCP 层会先调用 `SuperAgentMcpSubmitPayloadAdapter` 做提交前校验和事
       }
     }
   },
-  "required": []
+  "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"]
+    }
+  ]
 }
 ```
 
@@ -499,6 +539,7 @@ POST /api/integrations/superagent/task-results
 - `items[].order_id`：订单 ID。
 - `items[].task_id`：任务 ID。
 - `items[].task_status`：任务状态。
+- `mapping_diagnostics`：仅 MCP 写入工具在 V3 业务根映射时返回，记录 Agent 原始事件 ID 到本系统一基索引的映射；不写入业务 JSON。
 
 完整字段以 `superagent-api-contract.md` 第 8 节为准。