# 输出契约

## 用途

定义 `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 字段。