debug和superagent提交的数据保持一致

2026-07-13 17:03:27 +08:00
parent c55090bc2e
commit 9a2812fe74
11 changed files with 191 additions and 86 deletions
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -283,9 +283,10 @@ run_label: 可选调试标签
 - 接口会解析 `.eml`，上传原始邮件、内联图片和附件到本系统阿里云 OSS，替换 HTML 内 `cid:` 图片，再写入 SourceMessage Inbox。
 - SourceMessage 来源 provider 固定为 `DEBUG_EML_UPLOAD`，用于和 AgentBus 入库邮件区分。
 - AgentBus 实时收到邮件后自动推 SuperAgent 由 M007 单独建设；这个接口是人工 Debug 上传链路，不代表实时生产链路。
- `external_message_id` 是后端生成的 Debug 独立 ID，格式类似 `debug-eml-run-{debugRunId}-{sha256前缀}`；原始邮件 `Message-ID` 保存在 `agentbus_like_payload.source.original_message_id`。
+- `external_message_id` 是后端生成的 Debug 独立 ID，格式类似 `debug-eml-run-{debugRunId}-{sha256前缀}`；原始邮件 `Message-ID` 不再放入 `agentbus_like_payload`，需要排查时看原始 EML OSS 文件和后端 Debug run / SuperAgent metadata。
 - 邮件会话解析支持 `References`、`In-Reply-To` 和 `Thread-Index`，但 Debug EML 的 `external_message_id` 不使用原始 `Message-ID` 做幂等。
- `agentbus_like_payload.schema_version` 固定为 `debug-eml-upload-v1`，前端可用于调试展示和版本判断。
+- `agentbus_like_payload` 是后端发送给 SuperAgent 的 AgentBus Outlook-like 主输入，前端只做只读展示；该对象会包含普通 `reply_policy.mode=manual`、`reply_policy.final_only=true`，但不再包含 `schema_version`、`source.provider=DEBUG_EML_UPLOAD`、`debug_context` 或旧的 Debug 专属 `reply_policy.mode=debug_only`。
+- Debug 来源版本仍由后端 SourceMessage payload 表 `schemaVersion=debug-eml-upload-v1` 记录，前端页面不要再依赖 `agentbus_like_payload.schema_version`。
 - 第一版只返回 SuperAgent 结果，不创建订单、不创建任务、不调用任务结果通知接口。
 - `X-TH-Hotel-Debug-Upload-Key` 只能由调试人员在受控环境手动提供，不能放入 `VITE_*`、源码、构建产物、URL query、localStorage、错误上报或普通日志。
 - 返回的 `html_body_sanitized` 复用邮件会话详情的安全策略，前端展示 HTML 时优先使用；`html_body_with_oss_urls` 只作为调试原始处理结果，不建议直接渲染。
--- a/docs/project/frontend-backend/debug-eml-page-integration-guide.md
+++ b/docs/project/frontend-backend/debug-eml-page-integration-guide.md
@@ -140,7 +140,7 @@ export async function uploadDebugEml(input: {
 | `html_body_sanitized` | string | 后端清洗后的 HTML，前端预览邮件正文时优先使用。 |
 | `html_sanitize_required` | boolean | 当前为 `true`，提醒前端不要直接信任原始 HTML。 |
 | `html_render_mode` | string | 当前可能为 `SANITIZED_HTML` 或 `TEXT_ONLY`。 |
-| `agentbus_like_payload` | object | 后端发送给 SuperAgent 的结构化 payload。 |
+| `agentbus_like_payload` | object | 后端发送给 SuperAgent 的 AgentBus Outlook-like 主 payload；只读展示。 |
 | `superagent_session_id` | string | SuperAgent session ID。 |
 | `superagent_run_id` | string | SuperAgent run ID。 |
 | `superagent_raw_answer` | string | SuperAgent 最终原始文本回答。 |
@@ -164,7 +164,8 @@ export async function uploadDebugEml(input: {

 - 邮件正文 iframe / 富文本预览优先使用 `html_body_sanitized`。
 - `html_body_with_oss_urls` 可以放在“原始处理 HTML”折叠面板中，不作为默认渲染内容。
- `agentbus_like_payload.source.original_message_id` 是原始邮件 `Message-ID`。
+- `agentbus_like_payload` 不包含 Debug 专属字段，不再包含 `schema_version`、`source.provider=DEBUG_EML_UPLOAD`、`source.original_message_id`、`debug_context` 或旧的 Debug 专属 `reply_policy.mode=debug_only`；当前会包含普通 `reply_policy.mode=manual`、`reply_policy.final_only=true`。
+- 原始邮件 `Message-ID` 不作为 Debug 外部消息 ID，也不进入 SuperAgent 主 payload；需要排查时看原始 EML OSS 文件和后端 Debug run / SuperAgent metadata。
 - `external_message_id` 是 Debug 链路生成的独立 ID，不等同于原始 `Message-ID`。
 - `superagent_parsed_json` 有值时优先展示格式化 JSON；没有值时展示 `superagent_raw_answer`。
 - 如果 SuperAgent 返回旧 `S000,source_message_id` 或 `S999,source_message_id`，后端会把它识别为特殊入口结果，不会作为 JSON 解析失败处理。前端可在结果区展示 `entry_result_code`、`entry_result_source_message_id`、`entry_result_meaning` 和 `entry_result_description`。
@@ -286,6 +287,7 @@ idle

 - Debug EML 页面是调试工具，不是 Message Notification 页面。
 - Debug EML 页面写入的 SourceMessage `provider=DEBUG_EML_UPLOAD`，用于和 AgentBus 来源区分。
+- Debug 页面发给 SuperAgent 的 `agentbus_like_payload` 会尽量贴近实时 AgentBus Outlook payload；前端不要用 `DEBUG_EML_UPLOAD` 或 `schema_version` 判断该对象内容。
 - Debug EML 页面第一版不创建订单和任务，所以上传成功后任务列表和订单列表不会因为这次上传自动新增业务数据。
 - AgentBus 实时收到邮件后自动推 SuperAgent 已由 M007 后端 V1 实现，但默认关闭且不走 Debug 页面；不能用 Debug EML 页面代表生产实时链路。

--- a/docs/project/go-live-notes.md
+++ b/docs/project/go-live-notes.md
@@ -192,7 +192,8 @@
 - Debug EML 上传接口会接收原始邮件、上传 OSS 并调用 SuperAgent，风险和成本高于普通查询接口。
 - Debug EML 上传 key、SuperAgent Open API Key、阿里云 OSS AccessKey 都不得进入前端源码、`VITE_*`、镜像、普通日志或文档真实值。
 - Debug EML 写入 SourceMessage Inbox 时 `provider=DEBUG_EML_UPLOAD`，不能伪装为 AgentBus 来源。
- Debug EML 写入 SourceMessage Inbox 时 `external_message_id` 是后端生成的 `debug-eml-run-{debugRunId}-{sha256前缀}`；原始邮件 `Message-ID` 只保存在 payload 的 `source.original_message_id`。
+- Debug EML 写入 SourceMessage Inbox 时 `external_message_id` 是后端生成的 `debug-eml-run-{debugRunId}-{sha256前缀}`；原始邮件 `Message-ID` 不进入发给 SuperAgent 的主 payload，需要排查时看原始 EML OSS 文件、Debug run 和 SuperAgent Open API metadata。
+- Debug EML 返回的 `agentbus_like_payload` 是 AgentBus Outlook-like 主输入，会包含普通 `reply_policy.mode=manual`、`reply_policy.final_only=true`；不再包含 `schema_version`、`source.provider=DEBUG_EML_UPLOAD`、`debug_context` 或旧的 Debug 专属 `reply_policy.mode=debug_only`。Debug 来源区分仍依赖 SourceMessage `provider=DEBUG_EML_UPLOAD` 和 payload 表 `schemaVersion=debug-eml-upload-v1`；拿到 AgentBus 真实 `reply_policy.mode` 枚举后需统一替换占位值。
 - Debug EML 返回 `html_body_sanitized`、`html_sanitize_required`、`html_render_mode`，前端展示 HTML 时应优先使用清洗字段。
 - Debug EML 当前会识别 SuperAgent Open API 返回的旧 `S000/S999,source_message_id`，并在 `superagent_parsed_json` 中返回结构化入口结果；这不是 JSON 解析失败。结构化 `S10/S99` 可通过任务结果通知接口入站，Debug EML 页面若要直接展示完整 V3 入口结构，前端展示仍需继续补齐。
 - Debug EML 第一版只展示 SuperAgent 结果，不创建订单、不创建任务、不调用任务结果通知接口。
--- a/docs/project/requirements/M004-debug-eml-superagent-upload-v1.md
+++ b/docs/project/requirements/M004-debug-eml-superagent-upload-v1.md
@@ -42,10 +42,10 @@ Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任
 - `.eml` MIME 解析：邮件头、纯文本正文、HTML 正文、内联图片和附件。
 - 阿里云 OSS 上传端口和适配器：原始 `.eml`、内联图片和附件。
 - HTML `cid:` 图片替换为 OSS URL。
- AgentBus-like payload 组装。
+- AgentBus Outlook-like payload 组装；发送给 SuperAgent 的主输入尽量贴近实时 AgentBus Outlook payload。
 - SourceMessage Inbox 写入，`provider=DEBUG_EML_UPLOAD`，`schema_version=debug-eml-upload-v1`。
 - Debug EML 的 `external_message_id` 由后端生成，格式为 `debug-eml-run-{debugRunId}-{sha256前缀}`，避免同一封 `.eml` 多次上传被 SourceMessage 幂等覆盖。
- 原始邮件 `Message-ID` 不再作为 Debug EML 的 `external_message_id`，而是保存到 `agentbus_like_payload.source.original_message_id`。
+- 原始邮件 `Message-ID` 不再作为 Debug EML 的 `external_message_id`，也不混入发送给 SuperAgent 的主 payload；调试追溯信息放入 SuperAgent Open API `metadata.debug_context` 和 Debug run / 原始 EML OSS 记录中。
 - EML 会话解析支持 `References` / `In-Reply-To` / `Thread-Index`；缺失时再回退到当前消息 ID 或 debug 会话 ID。
 - Debug run 在解析、OSS 上传、构造 SourceMessage、写入 SourceMessage、调用 SuperAgent 前写入运行中阶段状态，便于测试环境定位卡点。
 - SourceMessage 写入成功后先把 debug run 标记为 `SOURCE_CAPTURED`；即使后续 SuperAgent 调用失败，也保留 SourceMessage 和 OSS 原文追溯信息。
@@ -65,7 +65,7 @@ Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任
 - 后端可以把原始 `.eml`、内联图片和附件上传到阿里云 OSS。
 - 后端可以把 HTML 正文中的 `cid:` 引用替换成 OSS URL。
 - 后端可以返回清洗后的 HTML 字段，前端优先展示 `html_body_sanitized`。
- 后端可以组装 AgentBus-like 邮件 payload，保持和当前 SourceMessage Inbox / SuperAgent 输入口径接近。
+- 后端可以组装 AgentBus Outlook-like 邮件 payload，保持和实时 AgentBus 自动分发给 SuperAgent 的主输入结构接近。
 - 后端可以写入 SourceMessage Inbox，并明确标记来源为 Debug EML Upload。
 - 后端可以调用 SuperAgent Open API 并解析最终返回。
 - 前端可以看到 SourceMessage ID、上传媒体、处理后的 HTML、发送给 SuperAgent 的 payload、SuperAgent 原始回答和解析后的 JSON。
@@ -103,7 +103,7 @@ Debug 页面上传 .eml
 → 上传普通附件到阿里云 OSS
 → debug run 标记为 BUILDING_SOURCE_MESSAGE
 → 替换 HTML 正文中的 cid: 图片引用
-→ 组装 AgentBus-like payload
+→ 组装 AgentBus Outlook-like payload
 → debug run 标记为 CAPTURING_SOURCE_MESSAGE
 → 调用 SourceMessageCaptureService 写入 SourceMessage Inbox
 → debug run 标记为 SOURCE_CAPTURED
@@ -155,7 +155,7 @@ Header: X-TH-Hotel-Debug-Upload-Key: <DEBUG_EML_UPLOAD_ACCESS_KEY>
 | `html_body_sanitized` | 复用邮件会话安全策略清洗后的 HTML 正文，前端调试展示优先使用 |
 | `html_sanitize_required` | 固定提示前端 HTML 需要按安全策略展示 |
 | `html_render_mode` | HTML 推荐渲染模式，当前优先返回 `SANITIZED_HTML` |
-| `agentbus_like_payload` | 发送给 SuperAgent 的结构化邮件 payload，包含 `schema_version=debug-eml-upload-v1` |
+| `agentbus_like_payload` | 发送给 SuperAgent 的 AgentBus Outlook-like 结构化邮件 payload；Debug 来源版本仍由 SourceMessage payload 表 `schemaVersion=debug-eml-upload-v1` 记录，不放入主 payload |
 | `superagent_session_id` | SuperAgent Open API session ID，失败时为空 |
 | `superagent_run_id` | SuperAgent 返回的 run ID，失败时为空 |
 | `superagent_raw_answer` | SuperAgent 最终文本回答 |
@@ -194,7 +194,7 @@ Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如
 | `subject` | 邮件 `Subject` |
 | `textBody` | 解析出的纯文本正文 |
 | `htmlBody` | 已替换 OSS URL 的 HTML 正文 |
-| `payloadJson` | AgentBus-like payload JSON |
+| `payloadJson` | AgentBus Outlook-like payload JSON |
 | `schemaVersion` | `debug-eml-upload-v1` |
 | `mediaItems` | 上传到 OSS 后的内联图片、附件和原始 `.eml` 引用 |

@@ -210,42 +210,56 @@ Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如

 补充说明：

- 原始邮件 `Message-ID` 保存到 `payloadJson.source.original_message_id`，不参与 Debug EML SourceMessage 幂等键。
- 原始解析出的会话 ID 保存到 `payloadJson.source.original_conversation_id`，便于排查 Debug 会话和真实邮件头之间的关系。
+- 原始邮件 `Message-ID` 不参与 Debug EML SourceMessage 幂等键，也不进入发给 SuperAgent 的主 payload；需要排查时使用 Debug run、原始 EML OSS 文件和 Open API metadata。
+- 原始解析出的会话 ID 用于生成 `external_conversation_id`；缺失时使用 `debug-eml-thread-{externalMessageId}`。
 - `Thread-Index` 仅作为 `References` / `In-Reply-To` 缺失时的会话 fallback，不覆盖明确的邮件回复链。

-## 8. AgentBus-like Payload 结构建议
+## 8. AgentBus Outlook-like Payload 结构建议

-第一版 payload 目标是让 SuperAgent 获得接近 AgentBus 邮件输入的结构，而不是完整复刻 AgentBus 协议。
+第一版 payload 目标是让 SuperAgent 获得尽量接近实时 AgentBus Outlook 邮件输入的主结构。Debug 专属字段不进入该主 payload，避免 SuperAgent 在 Debug 和实时链路上看到不同业务语义。

 ```json
 {
+  "text": "plain text body",
+  "received_at": "2026-07-09T01:31:00Z",
  "source": {
    "channel": "EMAIL",
-    "provider": "DEBUG_EML_UPLOAD",
    "external_message_id": "debug-eml-run-1900000000000000001-4f2c9a8b7d6e",
    "external_conversation_id": "debug-eml-thread-debug-eml-run-1900000000000000001-4f2c9a8b7d6e",
-    "original_message_id": "message-id-from-eml@example.com",
-    "original_conversation_id": "thread-index-or-reference-from-eml",
    "sender": "sender@example.com",
    "subject": "Booking Request",
-    "sent_at": "2026-07-09T01:30:00Z"
+    "sent_at": "2026-07-09T01:30:00Z",
+    "received_at": "2026-07-09T01:31:00Z"
  },
  "body": {
-    "content_type": "MIXED",
+    "content_type": "mixed",
    "text": "plain text body",
    "html": "<html>...</html>"
  },
-  "inline_images": [],
-  "attachments": [],
+  "inline_images": [
+    {
+      "id": "cid:inline-001",
+      "media_type": "INLINE_IMAGE",
+      "file_name": "inline.png",
+      "content_type": "image/png",
+      "size_bytes": 1200,
+      "external_url": "https://oss.example/debug/eml/inline.png",
+      "content_id": "inline-001"
+    }
+  ],
+  "attachments": [
+    {
+      "id": "attachment:1",
+      "media_type": "ATTACHMENT",
+      "file_name": "booking.pdf",
+      "content_type": "application/pdf",
+      "size_bytes": 3400,
+      "external_url": "https://oss.example/debug/eml/booking.pdf"
+    }
+  ],
  "reply_policy": {
-    "mode": "debug_only",
+    "mode": "manual",
    "final_only": true
-  },
-  "debug_context": {
-    "debug_run_id": "1900000000000000001",
-    "run_label": "frontend-debug-smoke",
-    "original_eml_oss_url": "https://oss.example/debug/eml/..."
  }
 }
 ```
@@ -253,8 +267,10 @@ Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如
 中文说明：

 - `inline_images[]` 和 `attachments[]` 中的 URL 必须是本系统 OSS URL。
- `reply_policy.mode=debug_only` 表示本链路只用于调试，不允许 SuperAgent 或本系统发送客户回复。
- 如果后续 AgentBus 正式 payload 有字段变化，本 Debug 链路可以通过 schema version 单独升级。
+- 主 payload 包含 AgentBus Outlook 关键字段 `reply_policy.mode`、`reply_policy.final_only`；Debug EML 第一版使用 `mode=manual`、`final_only=true` 表示不由 Debug 链路自动回复客户，后续拿到 AgentBus 真实枚举后再统一对齐。
+- 主 payload 不包含 `schema_version`、`source.provider=DEBUG_EML_UPLOAD`、`debug_context`、`original_message_id`，也不再使用旧的 Debug 专属 `reply_policy.mode=debug_only`。
+- SourceMessage Inbox 仍以 `provider=DEBUG_EML_UPLOAD` 和 payload 表 `schemaVersion=debug-eml-upload-v1` 区分 Debug 来源，不能伪装成 AgentBus 入库。
+- Debug run ID、run_label、原始 Message-ID 和原始会话 ID 放入 SuperAgent Open API `metadata.debug_context`，只用于排查，不作为 SuperAgent 邮件业务主输入；原始 EML OSS URL 仅保存在本系统 Debug run / 受控响应中，不再透传给 SuperAgent metadata。

 ## 9. SuperAgent Open API 调用口径

@@ -271,7 +287,7 @@ POST /api/open/agent-sessions/{sessionId}/messages/stream
 - 状态变更请求使用 CSRF double-submit：`X-CSRF-Token` 和 `Cookie: csrf_token=<same-token>`；当前共享 Open API client 已自动生成临时随机 token 并同时写入 header / cookie。
 - 创建 session 时使用 `SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID` 作为 `external_subject_id`。
 - `idempotency_key` 使用 `debug_run_id` 派生，保证同一次 Debug 运行不会重复创建不可追溯请求。
- 发送消息时把 AgentBus-like payload 序列化为 JSON 文本，并附加中文指令，要求 SuperAgent 输出结构化 JSON。
+- 发送消息时把 AgentBus Outlook-like payload 序列化为 JSON 文本，并附加中文指令，要求 SuperAgent 输出结构化 JSON 或 S10/S99 特殊结果。
 - SSE 解析仍按项目现有经验，从后期 `values.messages[]` 中寻找 `type=ai` 且 `finish_reason=stop` 的最终回答。

 当前未确认项：
@@ -341,7 +357,7 @@ platform_debug_eml_superagent_run
 | `original_file_name` | 原始上传文件名安全摘要 |
 | `original_eml_oss_url` | 原始 `.eml` OSS URL |
 | `original_eml_sha256` | 原始 `.eml` SHA-256 |
-| `payload_json` | AgentBus-like payload JSON |
+| `payload_json` | AgentBus Outlook-like payload JSON |
 | `superagent_session_id` | SuperAgent session ID |
 | `superagent_run_id` | SuperAgent run ID |
 | `superagent_raw_answer` | SuperAgent 最终文本回答 |
@@ -478,7 +494,7 @@ SUPERAGENT_DEBUG_EML_READ_TIMEOUT=180s
 2. 支持上传 .eml，解析邮件头、text/html 正文、内联图片和附件。
 3. 接入阿里云 OSS，上传原始 .eml、内联图片和附件。
 4. 替换 HTML 正文中的 cid: 图片为 OSS URL。
-5. 组装 AgentBus-like payload。
+5. 组装 AgentBus Outlook-like payload。
 6. 写入 SourceMessage Inbox，provider 使用 DEBUG_EML_UPLOAD，schema_version 使用 debug-eml-upload-v1。
 7. 调用 SuperAgent Open API 创建 session 并发送 messages/stream。
 8. 解析 SuperAgent SSE 最终回答，返回 raw answer 和 parsed json。
--- a/docs/project/requirements/M007-agentbus-superagent-auto-dispatch-v1.md
+++ b/docs/project/requirements/M007-agentbus-superagent-auto-dispatch-v1.md
@@ -131,7 +131,7 @@ KEY idx_dispatch_external_message (hotel_id, external_message_id)

 ## 7. 消息组装

-AgentBus 自动分发发送给 SuperAgent 的 message 第一版应基于 SourceMessage 原始 payload 构造，保持和 Debug EML 的 AgentBus-like payload 语义一致。
+AgentBus 自动分发发送给 SuperAgent 的 message 第一版应基于 SourceMessage 原始 payload 构造。Debug EML 发送给 SuperAgent 的 `agentbus_like_payload` 也按 AgentBus Outlook-like 主结构组装，并包含 `reply_policy.mode`、`reply_policy.final_only`；Debug EML V1 暂用 `mode=manual`、`final_only=true`，不能再使用旧的 Debug 专属 `debug_only`。Debug 来源区分仍保留在 SourceMessage `provider=DEBUG_EML_UPLOAD`、payload 表 `schemaVersion=debug-eml-upload-v1` 和 Open API metadata 中，不混入主 payload。后续 AgentBus 明确真实 `reply_policy.mode` 枚举后，Debug EML 和实时链路需要一起对齐。

 发送 metadata 建议包含：