实现 Debug EML 上传到 SuperAgent 链路

2026-07-09 14:22:24 +08:00
parent 9fa608f602
commit fcb30d460a
50 changed files with 3527 additions and 1 deletions
--- a/docs/project/requirements/M004-debug-eml-superagent-upload-v1.md
+++ b/docs/project/requirements/M004-debug-eml-superagent-upload-v1.md
@@ -0,0 +1,477 @@
+# 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`。
+- 使用真实阿里云 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`。
+- SourceMessage 写入成功后先把 debug run 标记为 `SOURCE_CAPTURED`；即使后续 SuperAgent 调用失败，也保留 SourceMessage 和 OSS 原文追溯信息。
+- 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。
+- 后端可以组装 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。
+- 不做普通任务切换订单。
+- 不做 SuperAgent 查询接口 3、4。
+- 不接入完整用户 / 权限体系。
+- 不在前端保存或暴露 SuperAgent Open API Key、阿里云 OSS Secret 或调试上传 key。
+
+## 5. 总体流程
+
+```text
+Debug 页面上传 .eml
+→ 后端校验 X-TH-Hotel-Debug-Upload-Key
+→ 解析 MIME 邮件结构
+→ 上传原始 .eml 到阿里云 OSS
+→ 上传内联图片到阿里云 OSS
+→ 上传普通附件到阿里云 OSS
+→ 替换 HTML 正文中的 cid: 图片引用
+→ 组装 AgentBus-like payload
+→ 调用 SourceMessageCaptureService 写入 SourceMessage Inbox
+→ debug run 标记为 SOURCE_CAPTURED
+→ 调用 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
+
+```text
+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 正文 |
+| `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` | 优先邮件 `Message-ID` 的规范化值；缺失时使用 `debug-eml-{sha256前缀}` |
+| `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 媒体枚举、接口文档和前端展示说明。
+
+## 8. AgentBus-like Payload 结构建议
+
+第一版 payload 目标是让 SuperAgent 获得接近 AgentBus 邮件输入的结构，而不是完整复刻 AgentBus 协议。
+
+```json
+{
+  "source": {
+    "channel": "EMAIL",
+    "provider": "DEBUG_EML_UPLOAD",
+    "external_message_id": "debug-eml-4f2c9a8b7d6e",
+    "external_conversation_id": "debug-eml-thread-4f2c9a8b7d6e",
+    "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 形态为：
+
+```text
+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：
+
+```text
+integrations.storage
+└── aliyunoss
+    ├── adapter
+    ├── common.request
+    ├── common.result
+    └── service / service.impl
+```
+
+对象路径建议：
+
+```text
+debug/eml/{yyyyMMdd}/{debugRunId}/raw/{originalFileName}.eml
+debug/eml/{yyyyMMdd}/{debugRunId}/inline/{index}-{safeFileName}
+debug/eml/{yyyyMMdd}/{debugRunId}/attachments/{index}-{safeFileName}
+```
+
+配置建议：
+
+```text
+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 表：
+
+```text
+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`、`SOURCE_CAPTURED`、`SUPERAGENT_SUCCEEDED`、`SUPERAGENT_FAILED`、`FAILED` |
+| `safe_error_summary` | 安全错误摘要，不包含正文、Secret 或附件签名 URL |
+| `created_at` / `updated_at` | 创建和更新时间，按 UTC 写入 |
+
+说明：
+
+- Debug run 表用于调试追溯，不替代 SourceMessage Inbox。
+- 大字段是否长期保存需结合库容量评估；第一版可以保存 payload 和 SuperAgent answer，禁止保存 Secret。
+- 如果后续需要调试历史列表，可基于该表新增只读查询接口。
+
+## 12. 后端模块建议
+
+```text
+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. 配置建议
+
+```text
+DEBUG_EML_UPLOAD_ENABLED=true
+DEBUG_EML_UPLOAD_ACCESS_KEY=
+DEBUG_EML_UPLOAD_MAX_FILE_BYTES=10485760
+
+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
+```
+
+分环境建议：
+
+- 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. 建议目标模式提示词
+
+```text
+进入目标模式，目标：实现 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 迁移到权限码控制。