huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
79fb1aef2d8290c3c6b6242ec4782c6cc6f5477c
th-hotel-simple/docs/import/20260718/0718-V4剩余10项确认回复.md
andy b949177feb 落定M002 V4 Agent回调字段契约
2026-07-18 17:01:12 +07:00

8.2 KiB
Raw Blame History

0718 V4 剩余 10 项确认回复

日期：2026-07-18

适用范围：Agent → Adapter / MCP → 信息系统的 V4 回调技术契约

说明：以下内容不改变已经确认的页面业务规则，主要用于冻结字段名、校验规则，以及明确需要 SuperAgent、Adapter 和信息系统共同对齐的技术边界。

1. Key 是否正式冻结

建议 V4 正式采用并冻结以下 key：

  • route_code
  • source_message
  • order_contexts
  • message_events
  • order_ref
  • target_order
  • attachment_ids

具体语义：

  • route_code：普通业务为 null，纯通知为 S10。
  • source_message：当前触发邮件的包级来源事实，只出现一次。
  • order_contexts[]：每个 order_ref 一项，承载订单级 Basic Information。
  • message_events[]：承载 New、Update、Cancel、Trace、Rooming List、Payment 六类业务 Event。
  • order_ref：只用于当前结果包内聚合同一订单，不用于 PMS 查单。
  • target_order：用于信息系统查询和绑定真实订单。
  • attachment_ids[]：仅用于 Payment 关联包级附件。

SuperAgent、Adapter、MCP Schema 和信息系统最终必须使用完全相同的字段名与嵌套位置。

2. source_message_id 与 external_message_id

业务要求是：source_message_id 必须代表本次触发邮件的稳定唯一 ID。

建议 Adapter 将 AgentBus / SourceMessage Inbox 的 external_message_id 映射为：

source_message.source_message_id

是否能直接一对一使用同一个值，需要根据真实 AgentBus / SourceMessage Inbox 契约确认。这是技术映射，不是新的业务问题。

3. 时间格式

同意统一为 UTC ISO-8601，例如：

2026-07-18T02:10:00Z

如果系统需要保留来源邮件原时区，可以作为内部技术元数据保存；Agent 对信息系统的标准时间统一使用 UTC。

4. body 的内容格式

已经确认的业务规则是：

  • 只保留一个 body；
  • 邮件监听层取得什么原文，Agent 就原样转发什么；
  • Agent 不清洗、摘要、翻译、重排或改写；
  • 不恢复 text_body + html_body 双正文。

为了让信息系统选择正确的安全渲染策略，建议增加一个技术字段：

body_content_type = text/plain | text/html

信息系统根据该字段进行纯文本转义展示或 HTML 安全渲染。无论使用哪种渲染方式，都不能改写保存的原始 body。

如果邮件监听层能够保证所有正文永远只有一种固定格式，也可以由 Adapter 固定该类型，不要求 Agent 重新判断。

5. 受控 code 目录

Account、RoomType、RateCode、Department 的目录由信息系统或其主数据服务统一维护，并作为唯一事实源。

规则如下：

  • SuperAgent 只能输出目录中已有的稳定 code；
  • 不允许输出自由文本或自行创造 code；
  • Agent 无法可靠匹配时，按对应业务字段的未解决规则处理；
  • Agent 输出非空 code、但信息系统目录不存在该值时，属于目录校验或契约问题；
  • 目录如何同步或提供给 SuperAgent，由双方技术方案决定，可以使用版本化目录快照或查询能力。

Market 和 Source 仍由信息系统根据订单级 account_code 派生，不由 Agent 输出。

6. 技术异常通知链路

同意需要独立的技术运行链路，但技术失败不属于酒店用户任务。

建议至少具备：

  • dispatch_run_id 或同类技术运行 ID；
  • PENDING / RUNNING / SUCCEEDED / FAILED / TIMED_OUT 等运行状态；
  • Agent 未回调的超时检测；
  • Agent、Skill、Adapter、MCP 和附件读取错误记录；
  • 面向开发或运维的告警、日志或错误查询入口。

技术失败不得创建 S10、人工复核卡或其他酒店用户业务任务。

dispatch_run_id 如何产生、请求与回调如何关联、错误通过回调还是独立 channel 返回，需要由 AgentBus、SuperAgent 和信息系统共同设计。

7. PAYMENT 的 attachment_ids

同意正常 Payment 冻结为：

attachment_ids.length > 0

同时建议校验：

  • attachment_ids[] 至少一项；
  • ID 不重复；
  • 每个 ID 都必须存在于同包 source_message.attachments[]；
  • 每个 ID 必须属于当前订单的付款凭证；
  • 正常 Payment 至少关联一份可用付款凭证。

没有任何凭证附件时，不能创建正常的空 Payment 卡：

  • 来源附件存在，但 Agent 没有关联任何 ID：Agent / Adapter 契约错误；
  • 来源本身没有可用于 Payment 卡的付款凭证：不形成正常 Payment，按 S10 展示原邮件；
  • 附件 metadata 存在但 URL 无法读取：附件或存储技术异常。

以上情况都不使用复杂 manual_review 对象。

8. manual_review=true 的 validator

同意冻结，但必须按当前对象的具体 Schema 判断，不能把任意空值都视为合法。

规则如下：

  • manual_review 只允许 null | true；
  • 正常对象为 null，不使用 false；
  • manual_review=true 时，当前 Basic Information 或 Event 中必须存在至少一个由该 Schema 允许的未解决标记；
  • 未解决标记可以是特定可空字段、被允许的空清单或不完整 item；
  • 来源冲突时，把无法可靠决定的原业务字段置为 null；
  • 不能笼统认为任何空数组都能解释 manual_review=true；
  • 所有字段完整、合法且通过目录校验，却仍输出 manual_review=true，属于 Agent / Adapter 契约异常。

不增加以下字段：

  • manual_review_info
  • missing_fields[]
  • reason_code
  • 字段路径
  • 候选值
  • 复核说明对象

具体字段错误路径、错误码和页面提示由信息系统根据 Schema、目录和业务规则生成。

9. Update 的 after.room_items=null

同意冻结为三态语义：

结构 语义
after 中不存在 room_items 本次邮件没有要求修改房型或房量
after.room_items=null 已识别本次涉及房型或房量修改，但无法形成修改后的完整房型清单；必须同时 manual_review=true
after.room_items=[...] 修改后的完整房型清单，不是只输出变化行

不要使用空数组表达“无法形成完整房型清单”。

如果修改后整笔订单不再保留任何房间，应按整单 CANCEL_BOOKING 处理，而不是提交空的 Update 房型清单。

10. 无 Confirmation Number 阶段的 Fit 后续定位

确认接受既有规则。

当前无 PMS API，且该 Fit 尚未取得真实 Confirmation Number 时：

  • Agent 可以输出 booking_type=FIT；
  • locator_type=BOOKING_CODE；
  • locator_value=Booking Code；
  • 信息系统使用 Booking Code 查询本地订单投影。

取得真实 Confirmation Number 后：

  • 后续业务切换为 locator_type=CONFIRMATION_NUMBER；
  • 不生成假的 Confirmation Number；
  • Booking Code 不成为未来 PMS 场景的永久关联键；
  • 信息系统不使用当前 Name 查询已有 Fit。

11. 确认状态汇总

项目 当前处理
1. V4 key 建议按本文正式冻结，需四方使用同名、同层级
2. message ID 映射 需根据真实 AgentBus / SourceMessage Inbox 契约核对
3. UTC ISO-8601 可以冻结
4. body 格式 原文透传已确认；body_content_type 需监听层 / Adapter 技术对齐
5. code 目录 信息系统主数据是唯一事实源；同步方式需技术设计
6. 技术异常 channel 需要单独建设；不进入酒店用户任务体系
7. Payment 非空附件 可以冻结
8. manual_review validator 可以冻结，并按各对象条件 Schema 校验
9. Update room_items 三态 可以冻结
10. Fit Booking Code 临时定位 已确认，可直接实施

12. 开发推进建议

后端可以继续进行领域模型与页面数据模型设计，不需要等待所有技术通道完成后才开始。

但在正式写入站 validator 和完成端到端联调前，应完成以下技术对齐：

  1. 核对 source_message_id 与真实上游 message ID 的映射；
  2. 确认 body_content_type 的来源与取值；
  3. 确认 dispatch_run_id、超时和错误 channel；
  4. 确认主数据目录如何提供给 SuperAgent；
  5. 保证 SuperAgent、Adapter、MCP Schema 和信息系统使用同一份 V4 Schema。