Files

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

2026-07-12 11:42:01 +08:00

22 KiB

Raw Blame History

输出契约

用途

定义 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 工具：

th-hotel-simple-superagent_th_hotel_submit_task_res

执行顺序固定为：

形成完整 final_result。
按本契约或对应公开错误契约完成校验。
冻结 final_result。
按 MCP Server 运行时提供的真实 schema，向上述工具提交完整、未修改的 final_result。
将工具响应只保留在 MCP 调用记录中。
向调用方原样返回同一个 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。缺失时先形成并校验：

{
  "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

{
  "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

{
  "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。

业务事件顶层结构

{
  "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。

每项固定使用：

{
  "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。

单个事件

{
  "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 应保留：

{
  "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。多条补充信息按当前证据顺序合并：

{
  "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。

人工复核

{
  "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。

派生事件

派生或关联事件使用：

{
  "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：

{
  "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 可以将其任务卡三元组只读归一为：

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 字段。

22 KiB Raw Blame History Unescape Escape