落定M002 V4 Agent回调字段契约
This commit is contained in:
andy
210
docs/import/20260718/0718-V4剩余10项确认回复.md
Normal file
210
docs/import/20260718/0718-V4剩余10项确认回复.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# 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` 映射为：
|
||||
|
||||
```text
|
||||
source_message.source_message_id
|
||||
```
|
||||
|
||||
是否能直接一对一使用同一个值，需要根据真实 AgentBus / SourceMessage Inbox 契约确认。这是技术映射，不是新的业务问题。
|
||||
|
||||
## 3. 时间格式
|
||||
|
||||
同意统一为 UTC ISO-8601，例如：
|
||||
|
||||
```text
|
||||
2026-07-18T02:10:00Z
|
||||
```
|
||||
|
||||
如果系统需要保留来源邮件原时区，可以作为内部技术元数据保存；Agent 对信息系统的标准时间统一使用 UTC。
|
||||
|
||||
## 4. body 的内容格式
|
||||
|
||||
已经确认的业务规则是：
|
||||
|
||||
- 只保留一个 `body`；
|
||||
- 邮件监听层取得什么原文，Agent 就原样转发什么；
|
||||
- Agent 不清洗、摘要、翻译、重排或改写；
|
||||
- 不恢复 `text_body + html_body` 双正文。
|
||||
|
||||
为了让信息系统选择正确的安全渲染策略，建议增加一个技术字段：
|
||||
|
||||
```text
|
||||
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 冻结为：
|
||||
|
||||
```text
|
||||
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。
|
||||
Reference in New Issue
Block a user