提交一次代码

2026-07-12 09:57:54 +08:00
parent 9bd6bc1cd0
commit 6e47158d9e
46 changed files with 3524 additions and 48 deletions
--- a/docs/import/20260710/归档/skills/booking-desk-event/references/00-output-contract.md
+++ b/docs/import/20260710/归档/skills/booking-desk-event/references/00-output-contract.md
@@ -0,0 +1,343 @@
+# 输出契约
+
+## 用途
+
+定义 `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 参数对象。
+
+## Source Message Identity
+
+- 所有合规的业务输出、`S10` 和 `S99` 都必须包含 `source_message`。
+- `source_message.source_message_id` 必须是上游提供的非空值，用于通知系统关联和展示原邮件；不得猜测、生成或从其他编号替代。
+- subject、from、cc、received_at 等其他元数据不可得时使用 `null` 或空数组。
+- 上游没有提供 `source_message_id` 时属于本业务契约之外的输入或基础设施错误，不能产生一个声称合规的 `S10` 或 `S99`。
+
+## Main Agent Notification Outcome
+
+`S10` 和 `S99` 共用以下源邮件查看通知结构：
+
+```json
+{
+  "source_message": {
+    "source_message_id": "<required>",
+    "subject": null,
+    "from": null,
+    "cc": [],
+    "received_at": null,
+    "source_channel": "Email"
+  },
+  "route_code": "S10 | S99",
+  "handler_type": "main_agent_outcome",
+  "result_type": "source_message_review_notification",
+  "current_or_history": "current",
+  "agent_assessment": {
+    "status": "no_booking_action_detected | material_package_unavailable",
+    "reason_code": "",
+    "automation_action": "none"
+  },
+  "notification": {
+    "required": true,
+    "notification_type": "source_message_review",
+    "show_source_message": true,
+    "requires_user_decision": true,
+    "visible_message": ""
+  },
+  "manual_review": null
+}
+```
+
+- `S10` 固定使用 `status=no_booking_action_detected`、`reason_code=no_booking_action_detected`、`manual_review=null`。为保持信息系统兼容，字段和值不变；其业务含义是输入可理解但未匹配当前 Agent 支持的业务事件，不表示用户无需查看、回复或处理源邮件。
+- `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` 只用于输入不足、无法完成支持范围分类。已经匹配支持业务事件但参数或目标不安全时，使用业务事件 `Need Manual Review`。
+
+`S99.manual_review` 必须使用：
+
+```json
+{
+  "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": {}
+}
+```
+
+## 业务事件顶层结构
+
+```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 和已被事件完整承接的内容不得重复输出。
+- 清楚但不支持的业务意图使用本字段；已匹配支持事件但参数或目标不安全时使用 `Need Manual Review`；内容不可读或抽取失败时使用 `extraction_warnings` 或相应人工复核。
+- `extraction_warnings` 只承载解析、OCR、抽取和证据质量问题，不得用来承载未覆盖业务意图。
+- `source_message_id` 只保留在根 `source_message`，不得在 item 内重复。
+
+详细覆盖顺序遵循 `03-current-content-completeness.md`。
+
+## 支持业务事件类型
+
+- `New Booking`
+- `Update Booking / Amendment`
+- `Cancel Booking`
+- `Cancel Allotment`
+- `Voucher Received`
+- `Payment Evidence`
+- `Rooming List`
+- `Allotment Maintenance`
+- `AMEND GROUP CODE`
+- `Invoice Generation`
+- `Invoice Received`
+- `Payment Notice`
+- `Trace`
+- `Manual RateCode`
+- `TA RECORDER`
+- `Note`
+
+普通预订补充信息统一输出 `Trace`。`Note` 暂时仅为旧契约兼容保留，不作为当前普通补充信息的路由结果，除非后续任务卡映射另有明确规则。
+
+## 业务人工复核结果
+
+- `Need Manual Review`
+
+## 单个事件
+
+```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
+}
+```
+
+## 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`。
+
+## 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": {}
+  }
+}
+```
+
+## 派生事件
+
+派生或关联事件使用：
+
+```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 Booking",
+  "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": null
+  },
+  "relevant_message_excerpt": "<parent line + split evidence>",
+  "attachments": [],
+  "file_references": [],
+  "context_used": {
+    "source": "current parent-to-child allocation evidence"
+  },
+  "extracted_fields": {
+    "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，不写外部系统。
+
+## 禁止输出
+
+不得输出真实 TaskCard ID、最终 Case 状态、Payment 确认、Block Status 自动转换、Receipt、Invoice 文件、Opera/PMS 写入结果。
+
+不得生成或返回结果 JSON 文件、结果文件引用、结果下载链接或 artifact。该限制只针对最终处理结果，不禁止下载、读取和解析输入附件，也不禁止在事件中保留输入附件证据。