实现AgentBus自动分发SuperAgent链路

docs/project/integrations/superagent-agentbus-project-integration-guide.md

@@ -27,7 +27,7 @@ SuperAgent 和 AgentBus 不应被设计成同一个模块。
 AgentBus
 → 接收 Email / LINE 等外部渠道消息
 → 保存 SourceMessage Inbox
-→ 受控 Replay 为 MessageEvent / Evidence
+→ 受控异步分发 / Replay
 → 调用 AI 能力端口
 → SuperAgent Provider Adapter
 → 保存 AI Capability Invocation
@@ -46,7 +46,7 @@ AgentBus
 核心原则：
 
 - 前端不直接调用 SuperAgent 或 AgentBus，不接触任何 Provider Secret。
-- AgentBus 实时链路只落来源事实，不直接生成 Case、Task、Operation 或客户回复。
+- AgentBus 实时入口必须先落来源事实；如需推送 SuperAgent，只能通过入库后的受控异步 dispatch / outbox 链路完成，不直接生成 Case、Task、Operation 或客户回复。
 - SuperAgent 返回内容只能作为建议、证据或审计结果，不能直接改变业务最终状态。
 - 业务写操作必须经过平台规则校验、权限控制、幂等控制和人工确认。
 
@@ -94,6 +94,8 @@ TH Hotel 当前 M001 相关代码中的可参考文件：
 | SourceMessage 原文读取审计表 | `server/src/main/resources/db/migration/V2__create_source_message_original_access_audit.sql` |
 
 SourceMessage Replay 到 MessageEvent / Evidence 尚未实现，需等 MessageEvent、Evidence 字段模型确认后再进入后续 checkpoint。
+AgentBus SourceMessage 入库后自动分发 SuperAgent 后端 V1 已实现，默认关闭，详见
+`docs/project/requirements/M007-agentbus-superagent-auto-dispatch-v1.md`。
 
 ## 4. SuperAgent 对接
 
@@ -123,7 +125,7 @@ SUPERAGENT_EXTERNAL_SUBJECT_ID=your-project-superagent-probe
 | `SUPERAGENT_PROBE_ENABLED` | 否 | 是否开放本项目自己的探针接口。生产默认关闭。 |
 | `SUPERAGENT_PROBE_ACCESS_KEY` | 是 | 调用探针接口的本地访问密钥，不是 Provider API Key。 |
 | `SUPERAGENT_CONNECT_TIMEOUT` | 否 | 建立连接超时。 |
-| `SUPERAGENT_READ_TIMEOUT` | 否 | SSE 读取超时。 |
+| `SUPERAGENT_READ_TIMEOUT` | 否 | 旧版 RestClient SSE 读取超时兼容变量；当前 JDK SSE 客户端不设置整段 SSE 固定读取超时，断流恢复由 run/events 机制处理。 |
 | `SUPERAGENT_MAX_MESSAGE_CHARS` | 否 | 单次发送给 Provider 的消息长度上限。 |
 | `SUPERAGENT_EXTERNAL_SUBJECT_ID` | 否 | 创建 Agent Session 时使用的外部主体标识。 |
 
@@ -139,15 +141,16 @@ POST /api/open/agent-sessions
 → 解析最终 answer、run、profile、model、token usage
 ```
 
-状态变更请求需要 CSRF double-submit：
+2026-07-12 Open API 文档中，Java SSE 调用使用 `Authorization: Bearer <DEERFLOW_OPEN_API_KEY>` 或
+`X-DeerFlow-Open-API-Key` 鉴权，并通过 `X-Request-ID`、`idempotency_key` 和 metadata 做调用关联。
+当前 TH Hotel 后端 `SuperAgentOpenApiClientImpl` 不发送 CSRF double-submit。
 
 ```text
-X-CSRF-Token: <random-csrf-token>
-Cookie: csrf_token=<same-random-csrf-token>
 Authorization: Bearer <DEERFLOW_OPEN_API_KEY>
+X-Request-ID: <stable-request-id>
 ```
 
-CSRF Token 由客户端实例临时生成，不需要写入配置，也不能当作 Secret 长期保存。
+如果 SuperAgent 服务端后续重新要求 CSRF double-submit，应先更新本文和 Open API client，再开启 M007 worker。
 
 ### 4.3 Session 请求示例
 
@@ -207,6 +210,23 @@ content 非空
 
 如果没有收到 `end`，或无法找到最终 AI 回答，应视为协议失败，不要伪造成成功结果。
 
+### 4.5.1 2026-07-12 SSE 断流恢复要求
+
+2026-07-12 导入的 `docs/import/20260712/OPEN_AGENT_API_JAVA_SSE_CLIENT.md` 已补充 Java 后端调用
+SuperAgent Open API 的稳定性要求。后续 TH Hotel 的共享 SuperAgent Open API client 必须满足：
+
+- 初始 `messages/stream?include_trace=true` 请求携带稳定 `X-Request-ID`。
+- 同一业务 SourceMessage 的 `idempotency_key` 在所有尝试中保持不变。
+- 初始 POST 成功后保存响应头 `Content-Location`，解析并保存 SuperAgent `run_id`。
+- SSE 必须按帧解析 `event:`、`data:`、`id:` 和 heartbeat comment，并保存 `lastEventId`。
+- 成功条件必须同时满足最终 AI 内容、`run.completed status=success`、顶层 `event: end`，且没有顶层 `error` 或 `run.failed`。
+- EOF、Premature EOF、incomplete chunked response 不能当成功。
+- 如果已有 `run_id`，断流后不得重新 POST 初始消息，应先查询 `GET /runs/{run_id}`，再通过 `GET /runs/{run_id}/events` 携带 `Last-Event-ID` 恢复。
+- 恢复失败应记录为可诊断失败，不返回部分回答。
+
+中文说明：该要求同时适用于 Debug EML 和 M007 AgentBus 自动分发链路。实现时应优先改造共享
+SuperAgent Open API client，避免调试链路和生产链路行为分叉。
+
 ### 4.6 平台能力端口
 
 其他项目建议定义一个稳定端口，例如：
@@ -268,6 +288,8 @@ AGENTBUS_SAMPLE_DIR=var/agentbus-samples
 AGENTBUS_MAX_FRAME_BYTES=1048576
 AGENTBUS_MAX_SAMPLES=100
 AGENTBUS_CAPTURE_ENABLED=true
+AGENTBUS_SUPERAGENT_DISPATCH_ENABLED=false
+AGENTBUS_SUPERAGENT_DISPATCH_WORKER_ENABLED=false
 AGENTBUS_REPLY_MODE=NONE
 AUTH_DEV_BOOTSTRAP_DEFAULT_HOTEL_ID=HOTEL-DEV
 SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY=
@@ -289,6 +311,13 @@ SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
 | `AGENTBUS_MAX_FRAME_BYTES` | 否 | 单个入站 frame 最大字节数。 |
 | `AGENTBUS_MAX_SAMPLES` | 否 | 最多保留的本地样本数。 |
 | `AGENTBUS_CAPTURE_ENABLED` | 否 | 是否写入 SourceMessage Inbox。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_ENABLED` | 否 | AgentBus 新邮件入库后是否创建 SuperAgent 自动分发记录，默认关闭。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_WORKER_ENABLED` | 否 | 是否启动 SuperAgent 自动分发 worker，默认关闭。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_MAX_ATTEMPTS` | 否 | 单条 dispatch 最大尝试次数，默认 `3`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_BATCH_SIZE` | 否 | worker 每轮领取数量，默认 `10`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_LOCK_TTL` | 否 | worker 抢占锁有效期，默认 `5m`。 |
+| `SUPERAGENT_AGENTBUS_EXTERNAL_SUBJECT_ID` | 否 | AgentBus 自动分发创建 SuperAgent session 的 external subject id。 |
+| `SUPERAGENT_OPEN_API_SSE_RECOVERY_MAX_ATTEMPTS` | 否 | SSE 断流恢复最大次数，默认 `5`。 |
 | `AUTH_DEV_BOOTSTRAP_DEFAULT_HOTEL_ID` | 否 | dev 初始化平台酒店；M005 后 AgentBus 捕获运行时从 `platform_hotel` 唯一 `ACTIVE` 酒店解析系统酒店，不再依赖 `AGENTBUS_DEFAULT_HOTEL_ID`。 |
 | `AGENTBUS_REPLY_MODE` | 否 | 调试回复模式。真实客户渠道应保持 `NONE`。 |
 | `SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY` | 是 | dev 原文读取接口的临时受控访问 key，后续可替换为正式权限体系。 |
@@ -327,6 +356,7 @@ GET /api/system/agentbus-probe
 → 忽略 session.ready / task.progress / task.result 等控制事件
 → 将业务 payload 映射为 CaptureSourceMessageCommand
 → 写入 SourceMessage Inbox
+→ 如 M007 dispatch 配置开启且为新建 RECEIVED Inbox，创建 SuperAgent dispatch run
 ```
 
 实时链路禁止：
@@ -336,6 +366,7 @@ GET /api/system/agentbus-probe
 - 自动回复客户。
 - 直接创建 MessageEvent、Evidence、AI Recognition、Case、Task、Operation 或 Receipt。
 - 直接调用 OHIP、ERP、支付系统等业务写接口。
+- 在 WebSocket 回调事务内同步等待 SuperAgent 返回。
 
 ### 5.4 当前已确认的 Outlook Payload 关键字段
 
@@ -427,6 +458,31 @@ Replay 负责：
 
 Replay 接口默认关闭，仅在本地、UAT 或受控生产运维场景开启。
 
+### 5.7 AgentBus 入库后自动分发 SuperAgent
+
+M007 已实现的自动分发链路不是 Debug EML，也不是 SourceMessage Replay。它只负责把 AgentBus 新入库邮件异步交给 SuperAgent Open API：
+
+```text
+AgentBus 新业务 frame
+→ SourceMessage Inbox RECEIVED
+→ platform_superagent_dispatch_run PENDING
+→ worker 调用 SuperAgent Open API
+→ 保存 session_id / run_id / raw answer / parsed json / 状态
+→ 等待 SuperAgent 后续通过 task-results 或 MCP 提交业务结果
+```
+
+第一版规则：
+
+- 仅处理 `provider=AGENTBUS` 且 `capture_status=RECEIVED` 的新 SourceMessage。
+- 重复 AgentBus 投递不重复创建 dispatch run。
+- `provider=DEBUG_EML_UPLOAD` 不进入生产 dispatch。
+- `FAILED` SourceMessage 不进入 dispatch。
+- dispatch 成功不代表已经创建订单或任务。
+- 任务创建仍由 SuperAgent 后续调用本系统任务结果通知接口或 MCP 写入工具触发。
+
+当前表名为 `platform_superagent_dispatch_run`，详细字段、状态流转、错误分类和验收标准见
+`docs/project/requirements/M007-agentbus-superagent-auto-dispatch-v1.md`。
+
 ## 6. 其他项目最小落地顺序
 
 ### 阶段 1：SuperAgent 连通性
@@ -481,7 +537,26 @@ AgentBus 入站业务 frame
 - 重复外部消息不重复入库。
 - 查询接口只返回安全摘要。
 
-### 阶段 4：手动 Replay
+### 阶段 4：自动分发 SuperAgent
+
+目标：
+
+```text
+SourceMessage Inbox
+→ SuperAgent dispatch / outbox
+→ SuperAgent Open API
+→ 保存 dispatch run
+```
+
+验收：
+
+- 仅新建 `AGENTBUS` + `RECEIVED` SourceMessage 创建 dispatch。
+- 重复邮件不重复 dispatch。
+- Debug EML 不进入生产 dispatch。
+- SuperAgent SSE 成功条件和断流恢复符合 2026-07-12 新文档。
+- dispatch 成功不直接创建订单或任务。
+
+### 阶段 5：手动 Replay
 
 目标：
 
@@ -497,7 +572,7 @@ SourceMessage Inbox
 - Replay 失败有 attempt 记录。
 - 响应不返回客户正文、HTML、附件 URL 或 Token。
 
-### 阶段 5：业务接入 SuperAgent
+### 阶段 6：业务接入 SuperAgent
 
 目标：
 
@@ -534,7 +609,6 @@ MessageEvent
 
 - Authorization
 - Cookie
-- CSRF Token
 - Provider API Key
 - AgentBus Token
 - 邮件正文和 HTML
@@ -554,13 +628,15 @@ MessageEvent
 SuperAgent 建议覆盖：
 
 - 缺失 API Key 时启动或调用失败。
-- CSRF Header / Cookie 不一致时转换为受控错误。
+- Bearer API Key 缺失、错误或权限不足时转换为受控错误。
 - 创建 Session 成功。
 - SSE 正常结束并解析最终回答。
 - SSE 缺少 `end` 时失败。
 - SSE 缺少最终回答时失败。
+- SSE 缺少 `run.completed status=success` 时失败。
+- SSE 断流后携带 `Last-Event-ID` 通过 `/runs/{run_id}/events` 恢复，且不重发初始 POST。
 - HTTP 401 / 403 / 404 / 409 / 5xx 错误转换。
-- 连接超时和读取超时。
+- 连接超时，以及 SSE 断流后的 run/events 恢复。
 
 AgentBus 建议覆盖：
 
@@ -604,7 +680,7 @@ SuperAgent 返回的是 Provider 输出。即使未来返回结构化 JSON，也
 接入 SuperAgent 前确认：
 
 - [ ] 已获得 Open API Key 和允许访问的 Base URL。
-- [ ] 已确认是否需要 CSRF double-submit。
+- [ ] 已确认当前 Open API 鉴权方式；如需 CSRF double-submit，已同步更新后端 client。
 - [ ] 已确认 Session、Message、Run 的生命周期。
 - [ ] 已确认 SSE 最终答案或结构化结果所在字段。
 - [ ] 已定义 `AgentCapabilityPort` 和调用审计表。