Files

andy 53b530d0b3 实现AgentBus自动分发SuperAgent链路

2026-07-12 23:53:50 +08:00

23 KiB

Raw Blame History

M004 Debug EML SuperAgent Upload 调试邮件上传链路 V1

文档信息

项目	内容
文档版本	0.1
日期	2026-07-09
状态	第一版后端已实现
适用范围	Debug 页面上传 `.eml` 邮件、转存阿里云 OSS、写入 SourceMessage Inbox、调用 SuperAgent Open API 并展示结果
主要读者	产品、后端、前端、测试、运维、后续协作 agent

1. 文档定位

本文记录 Debug EML 上传链路的第一版后端设计。该能力用于在不依赖 AgentBus 实时生产链路的情况下，由调试页面上传 .eml 邮件文件，后端解析邮件、转存附件和内联图片到本系统阿里云 OSS，再组装成 SuperAgent 可处理的邮件输入并调用 SuperAgent Open API。

该能力是平台调试能力，不属于 workflows.reservation 主业务流。第一版必须写入 SourceMessage Inbox 作为来源事实，但不创建订单、不创建任务、不写 AI 任务结果通知接口，也不执行 OPERA。

2. 已确认决策

Debug 页面上传的邮件文件格式为 .eml。
第一版通过 SuperAgent Open API 调用 SuperAgent，不走 SuperAgent 调用本系统的任务结果通知接口。
第一版只展示 SuperAgent 生成结果，不落业务订单和任务。
上传邮件仍要写入 SourceMessage Inbox。
Debug 上传来源必须和 AgentBus 来源区分，建议 provider=DEBUG_EML_UPLOAD。
AgentBus 实时收到邮件后自动推 SuperAgent 已由 M007 后端 V1 实现；M004 仍只代表人工 Debug 上传链路，不代表生产实时自动处理链路。
使用真实阿里云 OSS，不使用本地 mock OSS。
原始 .eml 文件本身也上传到阿里云 OSS，便于后续调试追溯。
内联图片和普通附件都上传到阿里云 OSS。
HTML 正文中的 cid: 图片引用需要替换成本系统 OSS 图片地址。
Debug 上传接口第一版使用内部调试访问 key 保护，不等待完整用户权限体系。
用户 / 权限体系和管理后台仍是后续能力，本功能不依赖 M003 完成。

2.1 第一版实现记录

当前后端已完成：

POST /api/system/debug/eml-superagent-runs。
.eml MIME 解析：邮件头、纯文本正文、HTML 正文、内联图片和附件。
阿里云 OSS 上传端口和适配器：原始 .eml、内联图片和附件。
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。
Debug run 在解析、OSS 上传、构造 SourceMessage、写入 SourceMessage、调用 SuperAgent 前写入运行中阶段状态，便于测试环境定位卡点。
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 按当前后端目录规范落位。
单元测试和集成测试覆盖 EML 解析、cid 替换、SourceMessage 写入参数、OSS mock、SuperAgent mock 和接口鉴权。

3. 核心目标

第一版要解决以下问题：

前端 Debug 页面可以上传一封 .eml 邮件。
后端可以解析邮件头、纯文本正文、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 并解析最终返回。
前端可以看到 SourceMessage ID、上传媒体、处理后的 HTML、发送给 SuperAgent 的 payload、SuperAgent 原始回答和解析后的 JSON。

4. 非目标范围

第一版不做以下能力：

不创建 Reservation 订单。
不创建 Reservation 任务。
不写 workflow_reservation_* 表。
不调用 POST /api/integrations/superagent/task-results。
不做真实 OPERA / OHIP 接入。
不做邮件多封批量上传。
不做 ZIP、MSG、PDF、图片 OCR 或 Excel 解析。
不做 SourceMessage Replay 到 MessageEvent / Evidence。
不做 AgentBus 实时邮件自动调用 SuperAgent；该能力由 M007 单独设计触发、幂等、限流、断流恢复和失败补偿。
不做普通任务切换订单。
不做 SuperAgent 查询接口 3、4。
不接入完整用户 / 权限体系。
不在前端保存或暴露 SuperAgent Open API Key、阿里云 OSS Secret 或调试上传 key。

5. 总体流程

Debug 页面上传 .eml
→ 后端校验 X-TH-Hotel-Debug-Upload-Key
→ debug run 标记为 PARSING_EML
→ 解析 MIME 邮件结构
→ debug run 标记为 UPLOADING_ORIGINAL_EML
→ 上传原始 .eml 到阿里云 OSS
→ debug run 标记为 UPLOADING_MEDIA
→ 上传内联图片到阿里云 OSS
→ debug run 标记为 UPLOADING_MEDIA
→ 上传普通附件到阿里云 OSS
→ debug run 标记为 BUILDING_SOURCE_MESSAGE
→ 替换 HTML 正文中的 cid: 图片引用
→ 组装 AgentBus-like payload
→ debug run 标记为 CAPTURING_SOURCE_MESSAGE
→ 调用 SourceMessageCaptureService 写入 SourceMessage Inbox
→ debug run 标记为 SOURCE_CAPTURED
→ debug run 标记为 CALLING_SUPERAGENT
→ 调用 SuperAgent Open API 创建 session
→ 调用 messages/stream 发送邮件 payload
→ 解析 SSE 最终回答
→ 保存 debug run 记录
→ 返回 debug 结果给前端展示

中文说明：

SourceMessage Inbox 仍然只表达来源事实，不表达 AI 结论、订单归属或任务状态。
Debug 上传链路不能伪装成 AgentBus；必须在 provider、schema_version 或 debug run 中留下可追溯来源。
SuperAgent 返回内容第一版只作为调试展示，不进入 M002 订单任务主流程。

6. 后端接口设计

6.1 上传并调用 SuperAgent

POST /api/system/debug/eml-superagent-runs
Content-Type: multipart/form-data
Header: X-TH-Hotel-Debug-Upload-Key: <DEBUG_EML_UPLOAD_ACCESS_KEY>

请求参数：

参数	是否必填	中文说明
`file`	是	`.eml` 邮件文件
`hotel_id`	是	酒店上下文 ID，用于 SourceMessage Inbox 幂等键和后续排查
`run_label`	否	前端传入的调试标签，例如 `frontend-debug-smoke`

响应字段：

字段	中文说明
`debug_run_id`	本次 Debug 运行 ID
`source_message_id`	本系统内部 SourceMessage Inbox ID
`source_provider`	固定建议为 `DEBUG_EML_UPLOAD`
`external_message_id`	Debug 链路生成的外部消息 ID，用于 SourceMessage 幂等
`external_conversation_id`	Debug 链路生成或解析出的邮件会话 ID
`original_eml_oss_url`	原始 `.eml` 文件 OSS 地址
`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，失败时为空
`superagent_raw_answer`	SuperAgent 最终文本回答
`superagent_parsed_json`	后端尝试解析出的 JSON 对象，无法解析时为空
`warnings[]`	可展示的安全警告，例如缺失 HTML、无法替换某个 cid、SuperAgent 返回非 JSON
`status`	Debug 运行状态

6.2 状态码建议

场景	HTTP 状态	中文说明
调试 key 缺失或错误	`401`	不执行解析和外部调用
文件缺失或非 `.eml`	`400`	参数错误
邮件解析失败	`422`	文件存在但 MIME 结构无法解析
OSS 上传失败	`502`	外部存储失败
SuperAgent 调用失败	`502`	外部 AI Provider 失败
写入 SourceMessage 失败	`500`	本系统持久化失败

错误响应不得返回 Secret、完整邮件正文、完整 HTML、附件 URL 中的签名参数或原始 Provider 报文。

7. SourceMessage 写入口径

Debug 链路调用现有 SourceMessageCaptureService.capture，建议映射如下：

Capture 字段	Debug EML 来源
`hotelId`	请求参数 `hotel_id`
`provider`	`DEBUG_EML_UPLOAD`
`channel`	`EMAIL`
`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 摘要
`sourceSentAt`	邮件 `Date` 头，解析失败则为空
`senderIdentifier`	邮件 `From`
`subject`	邮件 `Subject`
`textBody`	解析出的纯文本正文
`htmlBody`	已替换 OSS URL 的 HTML 正文
`payloadJson`	AgentBus-like payload JSON
`schemaVersion`	`debug-eml-upload-v1`
`mediaItems`	上传到 OSS 后的内联图片、附件和原始 `.eml` 引用

媒体类型建议：

类型	中文说明
`INLINE_IMAGE`	HTML 正文内联图片
`ATTACHMENT`	普通邮件附件
`ORIGINAL_EMAIL`	Debug 链路上传的原始 `.eml` 文件，若当前枚举不支持，需要新增枚举或作为附件类型加 `external_media_id` 区分

若新增 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 协议。

{
  "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"
  },
  "body": {
    "content_type": "MIXED",
    "text": "plain text body",
    "html": "<html>...</html>"
  },
  "inline_images": [],
  "attachments": [],
  "reply_policy": {
    "mode": "debug_only",
    "final_only": true
  },
  "debug_context": {
    "debug_run_id": "1900000000000000001",
    "run_label": "frontend-debug-smoke",
    "original_eml_oss_url": "https://oss.example/debug/eml/..."
  }
}

中文说明：

inline_images[] 和 attachments[] 中的 URL 必须是本系统 OSS URL。
reply_policy.mode=debug_only 表示本链路只用于调试，不允许 SuperAgent 或本系统发送客户回复。
如果后续 AgentBus 正式 payload 有字段变化，本 Debug 链路可以通过 schema version 单独升级。

9. SuperAgent Open API 调用口径

项目现有文档已验证的 SuperAgent Open API 形态为：

POST /api/open/agent-sessions
POST /api/open/agent-sessions/{sessionId}/messages/stream

第一版建议：

后端使用 DEERFLOW_BASE_URL 和 DEERFLOW_OPEN_API_KEY 调用 SuperAgent。
状态变更请求使用 CSRF double-submit：X-CSRF-Token 和 Cookie: csrf_token=<same-token>。
创建 session 时使用 SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID 作为 external_subject_id。
idempotency_key 使用 debug_run_id 派生，保证同一次 Debug 运行不会重复创建不可追溯请求。
发送消息时把 AgentBus-like payload 序列化为 JSON 文本，并附加中文指令，要求 SuperAgent 输出结构化 JSON。
SSE 解析仍按项目现有经验，从后期 values.messages[] 中寻找 type=ai 且 finish_reason=stop 的最终回答。

当前未确认项：

SuperAgent 是否需要指定具体 agent、profile 或 prompt。
SuperAgent 邮件处理 Open API 是否有比“发送 JSON 文本消息”更稳定的专用入参。

第一版实现时应把 profile / prompt 相关内容做成配置或低耦合适配，不写死在业务流程里。

10. 阿里云 OSS 设计

后端新增对象存储端口，业务层不直接依赖阿里云 SDK：

integrations.storage
└── aliyunoss
    ├── adapter
    ├── common.request
    ├── common.result
    └── service / service.impl

对象路径建议：

debug/eml/{yyyyMMdd}/{debugRunId}/raw/{originalFileName}.eml
debug/eml/{yyyyMMdd}/{debugRunId}/inline/{index}-{safeFileName}
debug/eml/{yyyyMMdd}/{debugRunId}/attachments/{index}-{safeFileName}

配置建议：

ALIYUN_OSS_ENDPOINT
ALIYUN_OSS_BUCKET
ALIYUN_OSS_ACCESS_KEY_ID
ALIYUN_OSS_ACCESS_KEY_SECRET
ALIYUN_OSS_PUBLIC_BASE_URL
ALIYUN_OSS_DEBUG_EML_PREFIX

安全要求：

阿里云 OSS AccessKey 不得进入前端代码、文档真实值或普通日志。
上传文件名必须清洗，避免路径穿越和日志污染。
Content-Type 以解析结果为准，但不能信任邮件原始文件名。
第一版可以使用长期可访问的 OSS URL；如果后续改为私有 bucket，需要补签名 URL 或后端代理读取方案。

11. 数据模型建议

新增 debug run 表：

platform_debug_eml_superagent_run

字段建议：

字段	中文说明
`id`	Debug 运行 ID
`hotel_id`	酒店上下文 ID
`run_label`	前端调试标签
`source_message_id`	内部 SourceMessage Inbox ID
`external_message_id`	Debug 链路外部消息 ID
`external_conversation_id`	Debug 链路外部会话 ID
`original_file_name`	原始上传文件名安全摘要
`original_eml_oss_url`	原始 `.eml` OSS URL
`original_eml_sha256`	原始 `.eml` SHA-256
`payload_json`	AgentBus-like payload JSON
`superagent_session_id`	SuperAgent session ID
`superagent_run_id`	SuperAgent run ID
`superagent_raw_answer`	SuperAgent 最终文本回答
`superagent_parsed_json`	后端解析出的 JSON
`run_status`	`CREATED`、`PARSING_EML`、`UPLOADING_ORIGINAL_EML`、`UPLOADING_MEDIA`、`BUILDING_SOURCE_MESSAGE`、`CAPTURING_SOURCE_MESSAGE`、`SOURCE_CAPTURED`、`CALLING_SUPERAGENT`、`SUPERAGENT_SUCCEEDED`、`SUPERAGENT_FAILED`、`FAILED`
`safe_error_summary`	运行中保存安全阶段摘要，失败时保存安全错误摘要；成功后清空为 `NULL`，不包含正文、Secret 或附件签名 URL
`created_at` / `updated_at`	创建和更新时间，按 UTC 写入

说明：

Debug run 表用于调试追溯，不替代 SourceMessage Inbox。
大字段是否长期保存需结合库容量评估；第一版可以保存 payload 和 SuperAgent answer，禁止保存 Secret。
如果后续需要调试历史列表，可基于该表新增只读查询接口。

12. 后端模块建议

platform.debug
├── control
├── service
│   └── impl
├── domain
├── mapper
├── repository
└── common
    ├── dto
    ├── request
    ├── result
    └── enums

platform.message
└── service / service.impl
    // EML 解析和 SourceMessage 捕获命令组装

integrations.storage.aliyunoss
└── adapter / service / service.impl
    // 阿里云 OSS 上传适配

integrations.ai.superagent
└── service / service.impl / adapter
    // SuperAgent Open API 和 SSE 解析

中文说明：

platform.debug 负责编排 Debug 运行，不直接解析厂商协议。
platform.message 可承接 EML 到 SourceMessage 捕获命令的转换，因为 EML 是消息来源处理能力。
integrations.storage.aliyunoss 隔离阿里云 OSS SDK。
integrations.ai.superagent 隔离 SuperAgent Open API、CSRF、SSE 和 Provider DTO。
workflows.reservation 不参与第一版 Debug 上传链路。

13. 依赖建议

后端实现可能需要新增依赖：

依赖	用途	说明
Jakarta Mail / Angus Mail	解析 `.eml` MIME 邮件	需要确认 Spring Boot 3.5 兼容版本
阿里云 OSS Java SDK	上传原始邮件、附件和内联图片	只在 integration adapter 使用

新增依赖前必须验证：

Java 17 兼容。
Spring Boot 3.5 兼容。
测试环境无需真实 OSS 时可以通过端口 mock 或禁用真实上传。
不引入和现有 MyBatis / Spring Boot starter 冲突的依赖。

14. 安全与审计

Debug 上传接口必须校验 X-TH-Hotel-Debug-Upload-Key。
DEBUG_EML_UPLOAD_ACCESS_KEY 必须按环境变量或部署 Secret 注入。
上传文件大小需要配置上限，避免误传超大邮件。
日志不得输出完整邮件正文、完整 HTML、附件 URL 签名参数、SuperAgent API Key、阿里云 OSS Secret。
SourceMessage 原文读取仍按既有受控读取和审计规则处理。
Debug run 错误摘要必须是安全摘要。
前端不得把 debug 上传 key、OSS Secret、SuperAgent Open API Key 放入构建产物。

15. 配置建议

DEBUG_EML_UPLOAD_ENABLED=true
DEBUG_EML_UPLOAD_ACCESS_KEY=
DEBUG_EML_UPLOAD_MAX_FILE_BYTES=10485760
DEBUG_EML_UPLOAD_SSE_HEARTBEAT_INTERVAL=15s
DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT=1800s

ALIYUN_OSS_ENDPOINT=
ALIYUN_OSS_BUCKET=
ALIYUN_OSS_ACCESS_KEY_ID=
ALIYUN_OSS_ACCESS_KEY_SECRET=
ALIYUN_OSS_PUBLIC_BASE_URL=
ALIYUN_OSS_DEBUG_EML_PREFIX=debug/eml/

DEERFLOW_BASE_URL=
DEERFLOW_OPEN_API_KEY=
SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID=th-hotel-debug-eml-upload
SUPERAGENT_DEBUG_EML_CONNECT_TIMEOUT=15s
SUPERAGENT_DEBUG_EML_READ_TIMEOUT=180s

中文说明：

DEBUG_EML_UPLOAD_SSE_HEARTBEAT_INTERVAL 控制 Debug EML SSE 在等待 SuperAgent Open API 返回期间的心跳事件间隔，用于避免中间链路按空闲连接断开。
DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT 目前映射到 Spring MVC async request timeout。Spring MVC 对 StreamingResponseBody 使用全局异步超时，因此该变量虽然为 Debug EML 设置，但会影响同一 Spring MVC 应用内其他异步请求；如后续增加其他 SSE / async 接口，需要统一评估该全局值。
前端实时页面优先调用 POST /api/system/debug/eml-superagent-runs/stream。如果 SSE 在最终 superagent_result 前断开但已收到 debug_run_id，前端可通过 GET /api/system/debug/eml-superagent-runs/{debug_run_id} 轮询运行状态和安全结果；该 GET 接口不是历史列表接口，仍必须携带 X-TH-Hotel-Debug-Upload-Key。

分环境建议：

dev 可以默认关闭真实 SuperAgent 调用，但允许配置后开启。
test 需要真实 OSS 和真实 SuperAgent 时，必须由部署环境注入 Secret。
prod 默认不建议开放 Debug 上传；如必须开放，应先接入正式用户权限和审计策略。

16. 验收标准

第一版完成后应满足：

上传 .eml 后，原始 .eml、附件和内联图片均能在阿里云 OSS 找到。
HTML 正文中的 cid: 图片被替换为 OSS URL。
SourceMessage Inbox 中可以查到 provider=DEBUG_EML_UPLOAD 的来源消息。
SourceMessage 媒体引用中可以查到内联图片、附件和原始 .eml 引用。
Debug run 表记录 SourceMessage ID、原始文件 hash、OSS URL、SuperAgent session / run 和运行状态。
SuperAgent 成功时，接口返回最终 answer 和可解析 JSON。
SuperAgent 返回非 JSON 时，接口不报业务成功伪结果，而是返回原始 answer 和 warning。
OSS 或 SuperAgent 失败时，接口返回安全错误，不泄漏 Secret 和邮件原文。
现有 Reservation 任务列表、订单详情、任务详情接口不受影响。

17. 建议目标模式提示词

进入目标模式，目标：实现 M004 Debug EML 上传到 SuperAgent 调试链路。

范围：
1. 实现 POST /api/system/debug/eml-superagent-runs。
2. 支持上传 .eml，解析邮件头、text/html 正文、内联图片和附件。
3. 接入阿里云 OSS，上传原始 .eml、内联图片和附件。
4. 替换 HTML 正文中的 cid: 图片为 OSS URL。
5. 组装 AgentBus-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。
9. 新增 debug run 表、Entity、Mapper、Repository、Service、Controller。
10. 按当前后端代码规范放置 control、service、service.impl、domain、mapper、repository、common.request、common.result、common.dto、common.enums。
11. Controller、Service、ServiceImpl 方法加中文注释；新增 Entity 字段和 DTO/Result 字段注释符合规范。
12. 补充测试，覆盖 eml 解析、cid 替换、SourceMessage 写入参数、OSS adapter mock、SuperAgent client mock 和接口鉴权。
13. 更新前后端沟通文档、上线注意事项和相关配置文档。

不做：
1. 不创建订单。
2. 不创建任务。
3. 不调用 SuperAgent 任务结果通知接口。
4. 不做真实 OPERA / OHIP。
5. 不做批量上传。
6. 不做 SourceMessage Replay。
7. 不做普通任务切换订单。
8. 不做 SuperAgent 查询接口 3、4。
9. 不接入完整用户 / 权限体系。

完成后：
code review，运行测试，中文提交。

18. 仍需后续关注

SuperAgent 是否会提供邮件处理专用 Open API 入参、profile 或 prompt 配置。
ORIGINAL_EMAIL 是否作为 SourceMessage 媒体新类型，还是第一版复用 ATTACHMENT 并用 external_media_id 标记。
Debug 上传是否需要历史列表和单次详情查询接口。
私有 OSS bucket 场景下，前端展示附件和图片是否改为短时签名 URL 或后端代理。
正式用户 / 权限体系上线后，Debug 上传接口需要从调试 key 迁移到权限码控制。

23 KiB Raw Blame History Unescape Escape

M004 Debug EML SuperAgent Upload 调试邮件上传链路 V1

文档信息

1. 文档定位

2. 已确认决策

2.1 第一版实现记录

3. 核心目标

4. 非目标范围

5. 总体流程

6. 后端接口设计

6.1 上传并调用 SuperAgent

6.2 状态码建议

7. SourceMessage 写入口径

8. AgentBus-like Payload 结构建议

9. SuperAgent Open API 调用口径

10. 阿里云 OSS 设计

11. 数据模型建议

12. 后端模块建议

13. 依赖建议

14. 安全与审计

15. 配置建议

16. 验收标准

17. 建议目标模式提示词

18. 仍需后续关注

23 KiB

Raw Blame History