完善 Debug EML 上传调试链路
This commit is contained in:
andy
@@ -12,7 +12,7 @@
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
本文记录 Debug EML 上传链路的第一版后端设计。该能力用于在没有 AgentBus 实时入口的情况下，
|
||||
本文记录 Debug EML 上传链路的第一版后端设计。该能力用于在不依赖 AgentBus 实时自动处理的情况下，
|
||||
由调试页面上传 `.eml` 邮件文件，后端解析邮件、转存附件和内联图片到本系统阿里云 OSS，
|
||||
再组装成 SuperAgent 可处理的邮件输入并调用 SuperAgent Open API。
|
||||
|
||||
@@ -26,6 +26,7 @@ Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任
|
||||
- 第一版只展示 SuperAgent 生成结果，不落业务订单和任务。
|
||||
- 上传邮件仍要写入 SourceMessage Inbox。
|
||||
- Debug 上传来源必须和 AgentBus 来源区分，建议 `provider=DEBUG_EML_UPLOAD`。
|
||||
- AgentBus 实时收到邮件后自动推 SuperAgent 当前未实现；现有 AgentBus 实时链路只负责写入 SourceMessage Inbox。
|
||||
- 使用真实阿里云 OSS，不使用本地 mock OSS。
|
||||
- 原始 `.eml` 文件本身也上传到阿里云 OSS，便于后续调试追溯。
|
||||
- 内联图片和普通附件都上传到阿里云 OSS。
|
||||
@@ -43,7 +44,12 @@ Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任
|
||||
- HTML `cid:` 图片替换为 OSS URL。
|
||||
- AgentBus-like 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`。
|
||||
- EML 会话解析支持 `References` / `In-Reply-To` / `Thread-Index`；缺失时再回退到当前消息 ID 或 debug 会话 ID。
|
||||
- SourceMessage 写入成功后先把 debug run 标记为 `SOURCE_CAPTURED`；即使后续 SuperAgent 调用失败，也保留 SourceMessage 和 OSS 原文追溯信息。
|
||||
- HTML 正文复用邮件会话详情的 sanitize 策略，返回 `html_body_sanitized`、`html_sanitize_required` 和 `html_render_mode`。
|
||||
- `cid:` 图片替换支持大小写不敏感的 scheme，并兼容常见的尖括号和 URL 编码尖括号形式。
|
||||
- SuperAgent Open API client：创建 session、发送 `messages/stream`、解析 SSE 最终回答。
|
||||
- `platform_debug_eml_superagent_run` 持久化。
|
||||
- Controller / Service / ServiceImpl / Repository / Mapper / Entity / DTO / Result 按当前后端目录规范落位。
|
||||
@@ -57,6 +63,7 @@ Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任
|
||||
- 后端可以解析邮件头、纯文本正文、HTML 正文、内联图片和附件。
|
||||
- 后端可以把原始 `.eml`、内联图片和附件上传到阿里云 OSS。
|
||||
- 后端可以把 HTML 正文中的 `cid:` 引用替换成 OSS URL。
|
||||
- 后端可以返回清洗后的 HTML 字段，前端优先展示 `html_body_sanitized`。
|
||||
- 后端可以组装 AgentBus-like 邮件 payload，保持和当前 SourceMessage Inbox / SuperAgent 输入口径接近。
|
||||
- 后端可以写入 SourceMessage Inbox，并明确标记来源为 Debug EML Upload。
|
||||
- 后端可以调用 SuperAgent Open API 并解析最终返回。
|
||||
@@ -74,6 +81,7 @@ Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任
|
||||
- 不做邮件多封批量上传。
|
||||
- 不做 ZIP、MSG、PDF、图片 OCR 或 Excel 解析。
|
||||
- 不做 SourceMessage Replay 到 MessageEvent / Evidence。
|
||||
- 不做 AgentBus 实时邮件自动调用 SuperAgent；该能力后续需要单独设计触发、幂等、限流和失败补偿。
|
||||
- 不做普通任务切换订单。
|
||||
- 不做 SuperAgent 查询接口 3、4。
|
||||
- 不接入完整用户 / 权限体系。
|
||||
@@ -136,6 +144,9 @@ Header: X-TH-Hotel-Debug-Upload-Key: <DEBUG_EML_UPLOAD_ACCESS_KEY>
|
||||
| `original_eml_sha256` | 原始 `.eml` 文件 SHA-256 |
|
||||
| `uploaded_media[]` | 已上传 OSS 的内联图片和附件 |
|
||||
| `html_body_with_oss_urls` | 替换 `cid:` 后的 HTML 正文 |
|
||||
| `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` |
|
||||
| `superagent_session_id` | SuperAgent Open API session ID，失败时为空 |
|
||||
| `superagent_run_id` | SuperAgent 返回的 run ID，失败时为空 |
|
||||
@@ -166,7 +177,7 @@ Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如
|
||||
| `hotelId` | 请求参数 `hotel_id` |
|
||||
| `provider` | `DEBUG_EML_UPLOAD` |
|
||||
| `channel` | `EMAIL` |
|
||||
| `externalMessageId` | 优先邮件 `Message-ID` 的规范化值；缺失时使用 `debug-eml-{sha256前缀}` |
|
||||
| `externalMessageId` | Debug 链路生成值，格式为 `debug-eml-run-{debugRunId}-{sha256前缀}`；同一封 `.eml` 重复上传也会生成独立 SourceMessage |
|
||||
| `externalConversationId` | 优先邮件 `In-Reply-To` / `References` / `Thread-Index` 可解析会话值；缺失时使用 `debug-eml-thread-{externalMessageId}` |
|
||||
| `providerFrameId` | `debug_run_id` |
|
||||
| `providerSessionId` | 可使用 `debug-eml-upload` 或后续当前用户 session 摘要 |
|
||||
@@ -189,6 +200,12 @@ Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如
|
||||
|
||||
若新增 `ORIGINAL_EMAIL` 媒体类型，需要同步更新 SourceMessage 媒体枚举、接口文档和前端展示说明。
|
||||
|
||||
补充说明：
|
||||
|
||||
- 原始邮件 `Message-ID` 保存到 `payloadJson.source.original_message_id`，不参与 Debug EML SourceMessage 幂等键。
|
||||
- 原始解析出的会话 ID 保存到 `payloadJson.source.original_conversation_id`，便于排查 Debug 会话和真实邮件头之间的关系。
|
||||
- `Thread-Index` 仅作为 `References` / `In-Reply-To` 缺失时的会话 fallback，不覆盖明确的邮件回复链。
|
||||
|
||||
## 8. AgentBus-like Payload 结构建议
|
||||
|
||||
第一版 payload 目标是让 SuperAgent 获得接近 AgentBus 邮件输入的结构，而不是完整复刻 AgentBus 协议。
|
||||
@@ -198,8 +215,10 @@ Debug 链路调用现有 `SourceMessageCaptureService.capture`，建议映射如
|
||||
"source": {
|
||||
"channel": "EMAIL",
|
||||
"provider": "DEBUG_EML_UPLOAD",
|
||||
"external_message_id": "debug-eml-4f2c9a8b7d6e",
|
||||
"external_conversation_id": "debug-eml-thread-4f2c9a8b7d6e",
|
||||
"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"
|
||||
|
||||
Reference in New Issue
Block a user