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/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 建议包含：