实现M002 V3 P0.1 Parent Group路由修订

2026-07-12 11:42:01 +08:00
parent 0358b34159
commit 92489af18e
42 changed files with 3971 additions and 79 deletions
--- a/1743/skills/booking-desk-event/references/00-output-contract.md
+++ b/1743/skills/booking-desk-event/references/00-output-contract.md
@@ -0,0 +1,460 @@
+# 输出契约
+
+## 用途
+
+定义 `booking-desk-event` 的统一 JSON 输出，以及 Main Agent 的 `S10/S99` 源邮件查看通知结果。所有业务事件都先是候选 `MessageEvent`，不是系统事实，不是真实 TaskCard。
+
+## 输出交付形式
+
+- 最终输出必须是当前调用直接返回的结构化 JSON 参数对象，不是 JSON 字符串或结果文件。
+- JSON 根对象必须直接使用本契约定义的顶层结构，不得增加 `booking_data`、`file`、`filename`、`artifact`、`download_url` 或其他文件包装层。
+- 不得创建、写入、上传、附加或返回 `booking_data.json` 或任何其他结果 JSON 文件。
+- 不得用结果文件名、文件路径、下载链接、artifact 或文件引用代替最终 JSON 参数对象。
+- 最终返回值不得使用 Markdown 代码块，也不得在 JSON 前后附加解释性文字。
+- 不得为交付形式增加 `output_mode`、`filename` 等非业务字段。
+- 输入附件引用仍可保留在事件的 `attachments` 或 `file_references` 中，但只能作为输入证据，不能替代最终 JSON 参数对象。
+
+## Constitutional Final Submission Lifecycle
+
+每个公开最终结果在直接返回前，都必须由最外层 finalizer 严格调用一次 MCP 工具：
+
+```text
+th-hotel-simple-superagent_th_hotel_submit_task_res
+```
+
+执行顺序固定为：
+
+1. 形成完整 `final_result`。
+2. 按本契约或对应公开错误契约完成校验。
+3. 冻结 `final_result`。
+4. 按 MCP Server 运行时提供的真实 schema，向上述工具提交完整、未修改的 `final_result`。
+5. 将工具响应只保留在 MCP 调用记录中。
+6. 向调用方原样返回同一个 `final_result`。
+
+适用结果包括业务根、S10、S99、`infrastructure_input_error` 和未来正式公开的最终错误对象。不得硬编码 MCP 参数名；不得省略、重命名、包装或二次序列化 payload。
+
+Main Agent/最外层 finalizer 是唯一 caller。`booking-desk-event` skill、`candidate_events`、`no_supported_event` 和 `candidate_package_contract_error` 都属于内部处理，不得直接调用提交工具或作为提交 payload。
+
+每个任务最多调用一次，Agent 不自行重试。工具失败时保留冻结的原始结果并暴露编排层 MCP 工具错误；不得修改结果、把工具错误塞进结果、递归提交或再次调用。工具响应不得成为业务 JSON 字段、包装层或最终结果的替代值。
+
+该调用只交付候选结果，不表示 TaskCard、Payment、Receipt、Invoice 或 Opera/PMS 操作已经成功。
+
+## Source Message Identity
+
+- 所有合规的业务输出、`S10` 和 `S99` 都必须包含 `source_message`。
+- `source_message.source_message_id` 必须是上游提供的非空值，用于通知系统关联和展示原邮件；不得猜测、生成或从其他编号替代。
+- subject、from、cc、received_at 等其他元数据不可得时使用 `null` 或空数组。
+- `null`、空字符串和纯空白字符串都视为缺失 `source_message_id`。
+
+## Infrastructure Input Error
+
+Gateway 必须在读取正文、附件、OCR、历史或系统上下文，以及调用业务 skill 之前校验 `source_message_id`。缺失时先形成并校验：
+
+```json
+{
+  "result_type": "infrastructure_input_error",
+  "error_code": "missing_source_message_id",
+  "retryable": true,
+  "missing_fields": [
+    "source_message.source_message_id"
+  ]
+}
+```
+
+该结果属于调用层，不属于业务输出、S10 或 S99，并明确豁免“结果必须包含 `source_message`”的业务规则。不得继续读取材料、调用 skill、生成通知、`message_events`、`unhandled_current_intents` 或 TaskCard。唯一允许的后续工具调用是按 Constitutional Final Submission Lifecycle 提交一次该 error，然后原样返回。Gateway 若在 Main Agent 前短路，必须执行同一提交钩子；Main Agent 若仍收到该输入，也必须使用相同结构作为防御性终态并完成提交。
+
+## Main Agent Notification Outcome
+
+`route_code` 是 S10/S99 结构的 discriminator。以下示例都是可直接返回的完整成品，不得在最终值中使用 `A | B` 表示二选一。
+
+### S10
+
+```json
+{
+  "source_message": {
+    "source_message_id": "<required>",
+    "subject": null,
+    "from": null,
+    "cc": [],
+    "received_at": null,
+    "source_channel": "Email"
+  },
+  "route_code": "S10",
+  "handler_type": "main_agent_outcome",
+  "result_type": "source_message_review_notification",
+  "current_or_history": "current",
+  "agent_assessment": {
+    "status": "no_booking_action_detected",
+    "reason_code": "no_booking_action_detected",
+    "automation_action": "none"
+  },
+  "notification": {
+    "required": true,
+    "notification_type": "source_message_review",
+    "show_source_message": true,
+    "requires_user_decision": true,
+    "visible_message": "未匹配到当前 Agent 支持的业务事件类型，请查看原邮件并决定是否需要回复或进行其他处理。"
+  },
+  "manual_review": null
+}
+```
+
+### S99
+
+```json
+{
+  "source_message": {
+    "source_message_id": "<required>",
+    "subject": null,
+    "from": null,
+    "cc": [],
+    "received_at": null,
+    "source_channel": "Email"
+  },
+  "route_code": "S99",
+  "handler_type": "main_agent_outcome",
+  "result_type": "source_message_review_notification",
+  "current_or_history": "current",
+  "agent_assessment": {
+    "status": "material_package_unavailable",
+    "reason_code": "material_package_unavailable",
+    "automation_action": "none"
+  },
+  "notification": {
+    "required": true,
+    "notification_type": "source_message_review",
+    "show_source_message": true,
+    "requires_user_decision": true,
+    "visible_message": "当前输入不足，无法判断是否匹配当前 Agent 支持的业务事件类型，请查看原邮件并决定后续处理。"
+  },
+  "manual_review": {
+    "reason_code": "material_package_unavailable",
+    "visible_reason": "当前输入不足，无法完成支持业务事件范围分类。",
+    "review_record_type": "main_agent_entry_review",
+    "missing_fields": [],
+    "blocking_points": [],
+    "conflicting_points": [],
+    "suggested_human_actions": ["review_source_message"],
+    "evidence_to_check": ["source_message"],
+    "known_fields": {}
+  }
+}
+```
+
+- `S10` 固定使用 `status=no_booking_action_detected`、`reason_code=no_booking_action_detected`、`manual_review=null`。它表示输入可理解但未匹配 active event，不表示用户无需查看、回复或处理源邮件。
+- `S99` 固定使用 `status=material_package_unavailable`；`agent_assessment.reason_code` 必须与 `manual_review.reason_code` 一致，`manual_review.review_record_type=main_agent_entry_review`。
+- 两者均使用 `requires_user_decision=true`，不得增加 `action_required` 替用户判断是否介入。
+- `S99` 只用于输入不足、无法完成 active-event 范围分类。业务类型或 subtype 已知但字段、目标或证据不安全时，保留该业务 `event_type` 并使用非空 `manual_review`；只有类型或 subtype 无法确定时才使用 `Need Manual Review`。
+
+## 业务事件顶层结构
+
+```json
+{
+  "source_message": {
+    "source_message_id": "<required>",
+    "subject": null,
+    "from": null,
+    "cc": [],
+    "received_at": null,
+    "source_channel": "Email"
+  },
+  "message_events": [],
+  "case_candidates": [],
+  "extraction_warnings": [],
+  "unhandled_current_intents": []
+}
+```
+
+所有业务输出都必须固定包含以上五个顶层字段。没有未覆盖当前意图时，`unhandled_current_intents` 使用空数组。该字段只属于业务输出；`S10` 和 `S99` 保持既有入口通知结构，不增加该字段。
+
+## Unhandled Current Intents
+
+`unhandled_current_intents` 用于展示同一邮件中意图清楚、具有当前业务意义，但现有事件目录或任务卡无法承接的内容。它不是 `MessageEvent`，信息系统不得据此自动创建 TaskCard。
+
+每项固定使用：
+
+```json
+{
+  "category": "unhandled_current_business_content",
+  "current_or_history": "current",
+  "reason_code": "requires_business_approval_or_unsupported_task_card",
+  "text_raw": "<当前证据原文>",
+  "visible_message": "当前邮件包含未被现有任务类型覆盖的业务意图：<忠实中文概述>。请查看原邮件并决定后续处理。",
+  "requires_user_decision": true,
+  "case_keys": {
+    "group_code": null,
+    "confirmation_number": null,
+    "reservation_number": null,
+    "block_code": null
+  },
+  "attachments": [],
+  "file_references": []
+}
+```
+
+固定规则：
+
+- 仅由当前正文、当前附件、当前 OCR、当前表格或当前继续处理指令产生；history-only 内容不得进入。
+- `text_raw` 原样保留；`visible_message` 提供忠实中文说明，不得增加批准、拒绝、执行或业务结论。无法安全翻译时使用“当前邮件包含未被现有任务类型覆盖的业务意图，请查看原文并决定后续处理。”
+- `requires_user_decision` 固定为 `true`。
+- `case_keys` 始终包含四个键。仅在当前证据或允许的历史证据唯一支持时填写；否则使用 `null`，不得猜测。
+- `attachments` 和 `file_references` 只保留当前证据引用；历史附件不得带入。
+- 一个独立意图一个 item，按当前证据顺序输出；连续多句组成同一请求时保持一个 item。
+- HTML/plain MIME alternatives、重复 OCR、quoted thread 和已被事件完整承接的内容不得重复输出。
+- 清楚但不支持的业务意图使用本字段；业务类型和 subtype 已知但参数或目标不安全时，保留业务事件并附非空 `manual_review`；只有业务类型或 subtype 无法确定时才使用 `Need Manual Review`。内容不可读或抽取失败时使用 `extraction_warnings` 或相应业务复核。
+- `extraction_warnings` 只承载解析、OCR、抽取和证据质量问题，不得用来承载未覆盖业务意图。
+- `source_message_id` 只保留在根 `source_message`，不得在 item 内重复。
+
+详细覆盖顺序遵循 `03-current-content-completeness.md`。
+
+## Active Emittable Event Types
+
+- `New Booking`
+- `Update Booking / Amendment`
+- `Cancel Booking`
+- `Cancel Allotment`
+- `Voucher Received`
+- `Payment Evidence`
+- `Rooming List`
+- `AMEND GROUP CODE`
+- `Invoice Generation`
+- `Invoice Received`
+- `Payment Notice`
+- `Trace`
+- `Manual RateCode`
+- `TA RECORDER`
+
+只有本列表中的值可以由当前 Agent 新生成，也只有本列表中的值可以进入 Main Agent 的粗候选 `possible_event_types`。
+
+## Legacy Accepted Event Types
+
+- `Allotment Maintenance`
+- `Note`
+
+以上值只允许读取历史旧数据，当前 Agent 不得新生成。普通预订补充信息统一输出 `Trace`；部分配额维护不再路由为 Update 或 Allotment Maintenance。
+
+## Business Review Outcomes
+
+- `Need Manual Review`
+
+`Need Manual Review` 不是 active event，也不能放入 Main Agent 的 `possible_event_types`。它只用于业务类型或 subtype 本身无法确定的 Fallback 复核；业务类型和 subtype 已知时保留原 `event_type`。
+
+## 单个事件
+
+```json
+{
+  "event_type": "",
+  "event_role": "travel_agent_request",
+  "current_or_history": "current",
+  "source_event_index": "E1",
+  "case_keys": {
+    "group_code": null,
+    "confirmation_number": null,
+    "reservation_number": null,
+    "block_code": null
+  },
+  "relevant_message_excerpt": "",
+  "attachments": [],
+  "file_references": [],
+  "context_used": {},
+  "extracted_fields": {},
+  "manual_review": null
+}
+```
+
+`manual_review=null` 表示普通候选。`manual_review` 为完整 `business_event_review` 对象时，该事件仍保留原 `event_type`，但 adapter 必须把它作为对应业务卡的 manual-review mode；不得自动执行或写 PMS。
+
+## Case Key
+
+- `case_keys.group_code` 必须是单值或 `null`。
+- 多个 group code 必须拆成多个事件。
+- `U-<number>` 是价格或 Rate Code marker，绝不能写入 confirmation、reservation、booking reference 或 target key。
+- Parent allocation group code 是证据，不是 child event 的 `case_keys.group_code`。
+- `Allotment / Control Block` 与 `Parent Group` 是同一业务对象；Allotment code 与 Parent Group code 是同一 code。
+- 当前 producer 生成任何 Parent Group 事件时，归一后的 `case_keys.group_code` 和 `case_keys.block_code` 必须同时存在且完全相等。只有一边有值时复制到另一边。
+- 两边原始候选同时存在但归一后不同，两个 case key 都必须置为 `null`，并在 `context_used.parent_identity_candidates[]` 保留候选字段、原值和证据来源；已知业务卡使用 `manual_review.reason_code=target_object_unclear`。
+- Child Group 和普通 Group Block 只填 `group_code`，`block_code=null`。
+
+## Date Evidence
+
+涉及入住、离店或晚数时，`extracted_fields` 应保留：
+
+```json
+{
+  "arrival_date": "2026-05-14",
+  "departure_date": "2026-05-15",
+  "nights": 1,
+  "date_evidence": {
+    "hotel_date_raw": "14-15",
+    "tour_date_raw": "2026/05/11\n2026/05/16",
+    "action_date_raw": "11/05 AMD",
+    "sheet_month_year": "BOOKING 05-2026",
+    "date_inference_basis": "hotel_date_range_with_tour_date_context"
+  }
+}
+```
+
+日期识别必须遵循 `54-stay-date-parsing.md`。`action_date_raw` 是动作日期证据，不是入住日期。
+
+## Trace Contract
+
+Trace 用于当前邮件中能绑定具体预订对象、但不属于主任务核心参数的补充业务信息。要求、安排、备注和包含具体预订事实的单纯告知都可以触发 Trace；不要判断发件人是否明确要求酒店记录、执行或转交。
+
+同一封邮件、同一目标对象只输出一个 Trace。多条补充信息按当前证据顺序合并：
+
+```json
+{
+  "event_type": "Trace",
+  "extracted_fields": {
+    "trace_subtype": "extra_bed | general_request",
+    "trace_text": "<按当前证据顺序合并的完整补充信息原文>",
+    "trace_items": [
+      {
+        "category": "extra_bed | room_preference | room_setup | meeting | function | meal | transport | payment_information | general_information",
+        "text_raw": "<单条原文>",
+        "service_date": "YYYY-MM-DD | null",
+        "service_period_raw": "<原始时段或 null>",
+        "pax": null,
+        "notify_departments": []
+      }
+    ],
+    "notify_departments": []
+  }
+}
+```
+
+- `trace_text` 必须保留完整原文，结构化字段不能替代原文。
+- `trace_items` 的顺序必须与 `trace_text` 一致。
+- `category` 必须使用固定枚举；banquet 归入 `function`，无法归入更具体类别时使用 `general_information`。
+- `service_date`、`service_period_raw`、`pax` 只有在证据明确时填写，否则为 `null`。
+- item 的 `notify_departments` 只保留明确或规则唯一支持的部门；事件级 `notify_departments` 是 item 已知部门的去重合集。
+- 部门不清时使用空数组，不得仅因此输出人工复核。
+- 全部 item 都是 extra bed 时使用 `trace_subtype=extra_bed`；其他情况使用 `general_request`。
+- Trace 包含 extra bed item 时，继续在事件级 `extracted_fields` 保留原有 `occupancy_update`、`requires_rate_update` 和 `rate_adjustment_formula`，不得移动到 item 或删除。
+- 主事件已完整承接的核心参数不得重复生成 Trace。
+- 不同目标对象必须拆成不同 Trace；`case_keys.group_code` 仍为单值。
+- `payment_information` 只表示已经确定、需要随预订保留的补充付款安排；付款凭证、到账结果、Payment Notice、Invoice、催款或付款条件审批询问不得改名为 Trace。
+
+`FYI guide will arrive at 20:00` 等具体预订告知可以触发 Trace；只有 `Thanks`、`Noted`、`Received`、裸 `FYI` 等没有具体业务信息的文字不能触发 Trace。需要酒店进行价格、退款、账期、付款政策、合同条件或其他业务审批的询问也不能伪装成 Trace。
+
+不属于 Trace 但具有当前业务意义的内容必须原样保留在 Main Agent 素材包的 `unknowns` 中。只要同邮件存在至少一个支持事件，业务 skill 就按 `03-current-content-completeness.md` 将其一对一输出到顶层 `unhandled_current_intents`；不得静默忽略或改成 Trace。
+
+## 人工复核
+
+```json
+{
+  "manual_review": {
+    "reason_code": "",
+    "visible_reason": "",
+    "review_record_type": "business_event_review",
+    "missing_fields": [],
+    "blocking_points": [],
+    "conflicting_points": [],
+    "suggested_human_actions": [],
+    "evidence_to_check": [],
+    "known_fields": {}
+  }
+}
+```
+
+固定规则：
+
+- 九个字段必须全部存在；`reason_code` 和 `visible_reason` 必须是非空字符串，`review_record_type` 固定为 `business_event_review`。
+- `missing_fields`、`blocking_points`、`conflicting_points`、`suggested_human_actions` 和 `evidence_to_check` 固定为数组；`known_fields` 固定为对象。
+- `missing_fields[]` 每项必须是指向当前 event 的 RFC 6901 JSON Pointer，例如 `/extracted_fields/room_items/0/pms_room_type_code`。不得放人类说明文字。
+- adapter 必须先按业务 `event_type` 和 subtype 判别字段得到原业务 task type/subtype，再依据 `manual_review` 是否为空派生 `normal_task` 或 `manual_review`。
+- 只有业务类型或 subtype 无法确定时，才使用 `event_type=Need Manual Review` 并派生 `manual_review + Fallback + business_event_review`。
+- `requires_downstream_hard_validation` 只用于契约明确的系统级候选校验，不得替代必需房型、Rate Code 或其他业务字段的人工确认。
+- 原 Agent event 保持不可变；用户覆盖值、`review_status`、解决人和解决时间由信息系统持有，全部缺失字段解决并重新校验后才进入 Preflight。
+
+## 派生事件
+
+派生或关联事件使用：
+
+```json
+{
+  "related_source_event_index": "",
+  "related_source_event_indices": [],
+  "related_event_type": "",
+  "relationship_type": "",
+  "requires_downstream_hard_validation": true
+}
+```
+
+`related_source_event_index` 用于单一关联事件；一个派生事件关联多个来源事件时使用 `related_source_event_indices`。
+
+典型场景：
+
+- New/Update/Amend Group Code 同事件出现 extra bed、Meeting、meal、arrival notice 或其他预订补充信息，按目标派生一个 linked `Trace`。
+- Rooming List 按每个目标 group 派生 `TA RECORDER`。
+- Parent-to-child allocation creation 必须派生独立的 parent release/cancel 候选 `message_event`，不得只放进 child `New Booking.extracted_fields`。
+
+## Parent-To-Child Parent Candidate
+
+当 current evidence 确认 parent group 拆成 child group codes，且 parent group code 清楚时，必须额外输出一个 parent release/cancel candidate：
+
+```json
+{
+  "event_type": "Cancel Allotment",
+  "event_role": "travel_agent_request",
+  "current_or_history": "current",
+  "source_event_index": "E_PARENT_RELEASE",
+  "case_keys": {
+    "group_code": "<parent_group_code>",
+    "confirmation_number": null,
+    "reservation_number": null,
+    "block_code": "<parent_group_code>"
+  },
+  "relevant_message_excerpt": "<parent line + split evidence>",
+  "attachments": [],
+  "file_references": [],
+  "context_used": {
+    "source": "current parent-to-child allocation evidence"
+  },
+  "extracted_fields": {
+    "cancel_scope": "entire_allotment_control_block",
+    "parent_release_or_cancel_candidate": true,
+    "release_reason": "parent_to_child_allocation_split",
+    "parent_group_code": "<parent_group_code>",
+    "child_group_codes": ["<child_group_code>"],
+    "allocation_split_from_parent": true,
+    "parent_original_room_summary": null
+  },
+  "related_source_event_indices": ["E1"],
+  "related_event_type": "New Booking",
+  "relationship_type": "linked_parent_release_after_child_split",
+  "requires_downstream_hard_validation": true,
+  "manual_review": null
+}
+```
+
+该事件是候选事件，不代表 PMS 已取消成功，不创建真实 TaskCard，不执行业务外部写入。mandatory submit 仅交付最终候选结果，不改变该边界。
+
+关系约束：
+
+- Allotment / Control Block 就是 Parent Group；该事件复用 `Cancel Allotment / cancel_allotment_control_block` 卡，不使用独立 parent cancel subtype。
+- 一个 split cluster 只能有一个 parent candidate。显式 `Cancel Allotment` 与派生 parent release 命中同一归一化 parent code 时合并证据，只保留一个事件；不同 parent code 分别输出。
+- `child_group_codes[]` 不得重复，并与 `related_source_event_indices[]` 数量和顺序一一对应。
+- 每个相关 index 必须指向同一 `message_events[]` 中的 `New Booking`，其 `booking_object_type=Group Block` 且 `case_keys.group_code` 等于对应 child code。
+- Parent 始终使用复数 `related_source_event_indices[]`，即使只有一个 child。
+- Parent event 的 `case_keys.group_code` 与 `case_keys.block_code` 必须相同。
+- Parent code 不得写入 child event 的 `case_keys.group_code`。
+- 当前 producer 不得输出 `event_type=Cancel Booking` 与 `relationship_type=linked_parent_release_after_child_split` 的组合。
+
+## Legacy Parent Split Compatibility
+
+历史 payload 若使用 `Cancel Booking + relationship_type=linked_parent_release_after_child_split`，reader/adapter 可以将其任务卡三元组只读归一为：
+
+```text
+normal_task|manual_review + Cancel Allotment + cancel_allotment_control_block
+```
+
+归一只影响读取和展示，不得改写原 payload、迁移历史任务或放宽当前 producer 的禁止规则。
+
+## 禁止输出
+
+不得输出真实 TaskCard ID、最终 Case 状态、Payment 确认、Block Status 自动转换、Receipt、Invoice 文件、Opera/PMS 写入结果。
+
+不得生成或返回结果 JSON 文件、结果文件引用、结果下载链接或 artifact。该限制只针对最终处理结果，不禁止下载、读取和解析输入附件，也不禁止在事件中保留输入附件证据。
+
+除 Constitutional Final Submission Lifecycle 指定的单次 MCP 结果交付外，不得执行其他外部写入。不得在最终 JSON 中增加提交状态、工具响应或 transport error 字段。