实现AgentBus自动分发SuperAgent链路

2026-07-12 23:53:50 +08:00
parent c3dad8eae9
commit 53b530d0b3
42 changed files with 2512 additions and 135 deletions
--- a/docs/project/go-live-notes.md
+++ b/docs/project/go-live-notes.md
@@ -11,7 +11,7 @@
 - `GET /api/source-messages/{id}`：查询单条 SourceMessage 安全摘要。
 - `GET /api/source-messages/{id}/original`：受控读取邮件原文、HTML 和媒体 URL，并记录访问审计。
 - `GET /api/system/agentbus-probe`：查看 AgentBus WebSocket 连接状态和安全计数器。
- AgentBus WebSocket 入站链路：默认关闭，开启后只把业务 frame 写入 SourceMessage Inbox。
+- AgentBus WebSocket 入站链路：默认关闭，开启后把业务 frame 写入 SourceMessage Inbox；如开启 M007，则在入库后异步创建 SuperAgent dispatch run。
 - SuperAgent 任务结果接收接口：当前代码接收一个外部 `source_message_id` 下的 AI 任务结果，反查 SourceMessage Inbox 后写入 AI 过渡层、订单、任务和任务卡；支持 V3 结构化 `S10/S99` 和业务根基础解析，同时兼容旧 `S000/S999,source_message_id` 文本入口结果并创建只读特殊任务。
 - Reservation 任务详情接口：返回任务字段、队列可处理状态和 OPERA 模拟操作摘要。
 - Reservation 任务草稿保存和最终确认接口：按任务卡矩阵做第一版后端校验，确认后生成 `confirmed_payload_json`。
@@ -27,6 +27,7 @@
 - 真实 AI 识别服务实现、Case 完整模型、Operation、Receipt。
 - 自动 ACK、`task.result` 或客户回复。
 - 业务前端页面展示邮件原文。
+- AgentBus SourceMessage 入库后自动分发 SuperAgent 虽然后端 V1 已实现，但默认关闭；未经测试机验收前不要在生产启用。
 - OHIP / OPERA 或其他业务系统真实写操作。
 - 普通任务切换订单接口。
 - M002 V3 字段矩阵从当前扁平结构整体迁移到 0711 P0 新结构。
@@ -44,6 +45,7 @@
 - 所有 Secret 都通过环境变量、部署平台 Secret 或密钥管理系统注入，不写入仓库、镜像、前端环境变量或普通配置文件。
 - 生产默认不保存 AgentBus raw frame 样本。
 - AgentBus 实时链路开启前，已经确认 WebSocket URL、Token、Bot Address、外部消息幂等键和断线重连语义。
+- M007 自动分发开启前，必须先确认 SourceMessage 入库稳定、SuperAgent Open API Key 可用、SSE 断流恢复通过测试、dispatch worker 开关和回滚方式明确。
 - 源邮件只读通知卡上线前，必须确认 `platform_hotel` 中存在且只存在一家 `ACTIVE` 酒店，并且已有 SourceMessage Inbox 数据的 `hotel_id` 与该酒店一致。旧 `S000/S999` 和新结构化 `S10/S99` 都沿用该酒店解析约束。
 - 系统管理后台上线前，必须确认至少存在一个 `ACTIVE` 超级管理员账号，且该账号拥有 `SYSTEM_ADMIN_CONSOLE_ACCESS` 和各系统管理权限。
 - 单酒店阶段上线前，必须确认 `platform_hotel` 中只有一家 `ACTIVE` 酒店；新增酒店可以存在但应保持 `DISABLED`。
@@ -112,6 +114,14 @@
 | `AGENTBUS_CONNECT_TIMEOUT` | 否 | 连接超时，默认 `15s`。 |
 | `AGENTBUS_MAX_FRAME_BYTES` | 否 | 单个入站 frame 最大字节数，默认 `1048576`。 |
 | `AGENTBUS_CAPTURE_ENABLED` | 否 | 是否把业务 frame 写入 SourceMessage Inbox。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_ENABLED` | 否 | AgentBus 新邮件入库后是否创建 SuperAgent dispatch 记录，默认关闭。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_WORKER_ENABLED` | 否 | 是否启动异步 worker 调用 SuperAgent Open API，默认关闭。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_MAX_ATTEMPTS` | 否 | 单条 dispatch 最大尝试次数，建议默认 `3`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_BATCH_SIZE` | 否 | worker 每轮领取数量，建议默认 `10`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_LOCK_TTL` | 否 | worker 抢占锁有效期，建议默认 `5m`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_INITIAL_BACKOFF` | 否 | 首次失败后的重试等待时间，建议默认 `30s`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_MAX_BACKOFF` | 否 | 最大重试等待时间，建议默认 `15m`。 |
+| `AGENTBUS_SUPERAGENT_DISPATCH_WORKER_FIXED_DELAY_MS` | 否 | worker 调度间隔毫秒，建议默认 `10000`。 |

 注意：

@@ -119,6 +129,7 @@
 - `AGENTBUS_CAPTURE_ENABLED=false` 时，业务 frame 会被忽略，不会写入 SourceMessage Inbox。
 - `AGENTBUS_DEFAULT_HOTEL_ID` 是 M005 前旧变量，当前后端不再读取；系统酒店来自 `platform_hotel` 唯一 `ACTIVE` 酒店。
 - 当前实现不发送 ACK、不发送 `task.result`、不自动回复客户。
+- M007 自动分发即使开启，也只能在 SourceMessage 入库后通过 dispatch / outbox 异步调用 SuperAgent，不能在 AgentBus WebSocket 回调内同步等待外部返回。

 ### 3.5 SuperAgent HMAC

@@ -158,13 +169,15 @@
 | `DEBUG_EML_UPLOAD_PROD_ACCESS_KEY` | 是 | prod Debug EML 上传访问口令；生产通常不应启用该接口。 |
 | `DEBUG_EML_UPLOAD_MAX_FILE_BYTES` | 否 | `.eml` 上传大小上限，默认 `10485760`。 |
 | `DEBUG_EML_UPLOAD_SSE_HEARTBEAT_INTERVAL` | 否 | Debug EML 页面到后端的 SSE 心跳间隔，默认 `15s`；测试机如仍遇到空闲断流可调小到 `10s`。 |
-| `DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT` | 否 | Spring MVC 异步请求总超时，默认 `1800s`；当前用于保障 Debug EML SSE 不先于 SuperAgent read timeout 关闭。注意 Spring MVC async timeout 是应用级全局设置，后续如增加其他 async/SSE 接口需一起评估。 |
+| `DEBUG_EML_UPLOAD_SSE_REQUEST_TIMEOUT` | 否 | Spring MVC 异步请求总超时，默认 `1800s`；用于保障 Debug EML 页面长流程不被后端 MVC 容器提前关闭。注意 Spring MVC async timeout 是应用级全局设置，后续如增加其他 async/SSE 接口需一起评估。 |
 | `DEERFLOW_DEV_BASE_URL` / `DEERFLOW_TEST_BASE_URL` / `DEERFLOW_PROD_BASE_URL` | 否 | SuperAgent / DeerFlow Open API 基础地址，未配置时可兜底 `DEERFLOW_BASE_URL`。 |
 | `DEERFLOW_DEV_OPEN_API_KEY` / `DEERFLOW_TEST_OPEN_API_KEY` / `DEERFLOW_PROD_OPEN_API_KEY` | 是 | SuperAgent Open API Key，未配置时可兜底 `DEERFLOW_OPEN_API_KEY`。 |
 | `SUPERAGENT_DEV_OPEN_API_ENABLED` / `SUPERAGENT_TEST_OPEN_API_ENABLED` / `SUPERAGENT_PROD_OPEN_API_ENABLED` | 否 | 是否启用真实 SuperAgent Open API 调用；prod 默认关闭。 |
 | `SUPERAGENT_DEBUG_EML_EXTERNAL_SUBJECT_ID` | 否 | Debug EML 创建 SuperAgent session 的 external subject id。 |
+| `SUPERAGENT_AGENTBUS_EXTERNAL_SUBJECT_ID` | 否 | AgentBus 自动分发创建 SuperAgent session 的 external subject id。 |
 | `SUPERAGENT_DEBUG_EML_CONNECT_TIMEOUT` | 否 | SuperAgent Open API 建连超时，默认 `15s`。 |
-| `SUPERAGENT_DEBUG_EML_READ_TIMEOUT` | 否 | SuperAgent SSE 读取超时，默认 `180s`。 |
+| `SUPERAGENT_DEBUG_EML_READ_TIMEOUT` | 否 | 旧版 RestClient 读取超时兼容变量；当前 JDK SSE 客户端不设置整段 SSE 固定读取超时，断流恢复由 run/events 机制处理。 |
+| `SUPERAGENT_OPEN_API_SSE_RECOVERY_MAX_ATTEMPTS` | 否 | SSE EOF 后通过 `/runs/{run_id}/events` 恢复的最大尝试次数，默认 `5`。 |
 | `ALIYUN_OSS_DEV_ENDPOINT` / `ALIYUN_OSS_TEST_ENDPOINT` / `ALIYUN_OSS_PROD_ENDPOINT` | 否 | 阿里云 OSS Endpoint，未配置时可兜底 `ALIYUN_OSS_ENDPOINT`。 |
 | `ALIYUN_OSS_DEV_BUCKET` / `ALIYUN_OSS_TEST_BUCKET` / `ALIYUN_OSS_PROD_BUCKET` | 否 | 阿里云 OSS Bucket，未配置时可兜底 `ALIYUN_OSS_BUCKET`。 |
 | `ALIYUN_OSS_DEV_ACCESS_KEY_ID` / `ALIYUN_OSS_TEST_ACCESS_KEY_ID` / `ALIYUN_OSS_PROD_ACCESS_KEY_ID` | 是 | 阿里云 OSS AccessKey ID，未配置时可兜底 `ALIYUN_OSS_ACCESS_KEY_ID`。 |
@@ -181,7 +194,8 @@
 - Debug EML 返回 `html_body_sanitized`、`html_sanitize_required`、`html_render_mode`，前端展示 HTML 时应优先使用清洗字段。
 - Debug EML 当前会识别 SuperAgent Open API 返回的旧 `S000/S999,source_message_id`，并在 `superagent_parsed_json` 中返回结构化入口结果；这不是 JSON 解析失败。结构化 `S10/S99` 可通过任务结果通知接口入站，Debug EML 页面若要直接展示完整 V3 入口结构，前端展示仍需继续补齐。
 - Debug EML 第一版只展示 SuperAgent 结果，不创建订单、不创建任务、不调用任务结果通知接口。
- AgentBus 实时收到邮件后自动推 SuperAgent 当前未实现，不能把 Debug EML 链路等同于生产实时自动处理链路。
+- AgentBus 实时收到邮件后自动推 SuperAgent 已由 M007 后端 V1 实现，不能把 Debug EML 链路等同于生产实时自动处理链路。
+- Debug EML 和 AgentBus 自动分发复用同一个 SuperAgent Open API SSE 稳定客户端；上线前必须验证 `run.completed + end + final answer` 严格成功条件和 EOF 后 `/events` 恢复。

 ## 4. 数据库上线注意事项

@@ -207,6 +221,10 @@

 - `server/src/main/resources/db/migration/V8__create_source_message_payload_duplicate.sql`

+当前 M007 AgentBus 自动分发 SuperAgent 相关 migration：
+
+- `server/src/main/resources/db/migration/V20__create_superagent_dispatch_run.sql`
+
 当前 M003 登录权限相关 migration：

 - `server/src/main/resources/db/migration/V9__create_identity_access_hotel_menu.sql`
@@ -295,8 +313,8 @@ Header: X-TH-Hotel-Access-Scene

 AgentBus 是消息入口，不是 AI Provider。生产实时链路必须保持以下边界：

- 只写 SourceMessage Inbox。
- 不自动调用 SuperAgent。
+- WebSocket 回调内只做 SourceMessage Inbox 入库和轻量 dispatch 标记。
+- 如启用 M007，只能在入库后通过受控异步 dispatch / outbox 调用 SuperAgent。
 - 不创建 MessageEvent、Evidence、Case、Task、Operation、Receipt。
 - 不调用 OHIP、ERP、支付系统等业务写接口。
 - 不自动发送 ACK、`task.result` 或客户回复。
@@ -311,11 +329,14 @@ AgentBus 是消息入口，不是 AI Provider。生产实时链路必须保持
 5. 观察 `/api/system/agentbus-probe`，确认连接状态、`sessionReady`、计数器和最近错误代码。
 6. 用合成测试邮件验证 SourceMessage Inbox 是否写入。
 7. 确认日志和监控没有泄露 raw frame、正文或附件 URL。
+8. 如需开启 M007 自动分发，先保持 worker 关闭并确认 dispatch run 能正确创建，再打开 worker 处理少量合成邮件。
+9. 验证 SuperAgent dispatch 成功不会直接创建订单或任务，业务任务仍只来自 SuperAgent 后续任务结果通知或 MCP 提交。

 如果出现异常：

 - 先关闭 `AGENTBUS_PROBE_ENABLED`，停止接收入站 frame。
 - 如果只是想暂停入库但保留连接，可关闭 `AGENTBUS_CAPTURE_ENABLED`。
+- 如果只想暂停 M007 自动分发，优先关闭 `AGENTBUS_SUPERAGENT_DISPATCH_WORKER_ENABLED`；如需停止新建 dispatch，再关闭 `AGENTBUS_SUPERAGENT_DISPATCH_ENABLED`。
 - 保留状态接口、应用日志和数据库记录用于排查，但不要导出真实邮件正文或附件 URL。

 ## 7. 上线后冒烟验证