huangting/th-hotel-simple

Fork 0

Files

andy 038fdc3c8d 对齐Debug EML V4入站模型

2026-07-20 19:53:44 +07:00

26 KiB

Raw Blame History

TH Hotel SuperAgent 与 AgentBus 项目接入记录

1. 文档定位

本文保存 TH Hotel 项目中已经验证过的 SuperAgent 与 AgentBus 接入经验、项目路径、表名和验证记录。

本文是当前项目专属记录，不应整份复制到其他项目。可复用的通用接入规则应沉淀到 docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md。

本文不是 SuperAgent 或 AgentBus 官方协议文档，也不记录任何真实 Token、API Key、 Session ID、Run ID、邮箱正文、附件 URL 或客户个人信息。其他项目接入时，应把本文作为工程边界、配置清单和验证顺序参考；具体字段仍以提供方最新协议和真实测试响应为准。

2. 两条链路的职责边界

SuperAgent 和 AgentBus 不应被设计成同一个模块。

AgentBus
→ 接收 Email / LINE 等外部渠道消息
→ 保存 SourceMessage Inbox
→ 受控异步分发 / Replay
→ 调用 AI 能力端口
→ SuperAgent Provider Adapter
→ 保存 AI Capability Invocation
→ 业务 Schema 校验
→ 人工确认
→ Case / Task / Operation / Receipt

能力	定位	负责什么	不负责什么
AgentBus	外部消息通道适配器	WebSocket 连接、接收入站 frame、保存原始来源事实	不做 AI 抽取、不创建业务 Task、不回复客户、不调用业务写接口
SuperAgent	外部 AI / Agent 能力提供方	创建 Agent Session、发送消息、解析 SSE、返回建议或回答	不决定业务动作、不绕过人工确认、不直接写业务系统
SourceMessage Inbox	平台缓冲层	不可变保存来源消息和捕获状态	不表达 AI 结论或业务归属
AiCapabilityPort	平台能力端口	隔离业务层和具体 Provider SDK / HTTP 协议	不暴露 Provider DTO 给领域层

核心原则：

前端不直接调用 SuperAgent 或 AgentBus，不接触任何 Provider Secret。
AgentBus 实时入口必须先落来源事实；如需推送 SuperAgent，只能通过入库后的受控异步 dispatch / outbox 链路完成，不直接生成 Case、Task、Operation 或客户回复。
SuperAgent 返回内容只能作为建议、证据或审计结果，不能直接改变业务最终状态。
业务写操作必须经过平台规则校验、权限控制、幂等控制和人工确认。

3. 推荐模块拆分

其他 Java / Spring Boot 项目接入时，建议按以下模块复制思路，而不是复制 TH Hotel 的预订部业务代码。

platform
├── message
│   ├── SourceMessageInbox
│   ├── MessageEvent
│   └── Evidence
├── ai
│   ├── AgentCapabilityPort
│   ├── AgentCapabilityRequest
│   ├── AgentCapabilityResult
│   └── AiCapabilityInvocation
└── system
    ├── SuperAgentProbeController
    ├── AgentBusProbeStatusController
    └── SourceMessageReplayController

integrations
├── ai
│   └── superagent
└── messaging
    └── agentbus

TH Hotel 当前 M001 相关代码中的可参考文件：

目的	参考文件
SourceMessage 查询与原文 API	`server/src/main/java/cn/nianxx/thhotel/platform/message/control/SourceMessageController.java`
SourceMessage 捕获服务	`server/src/main/java/cn/nianxx/thhotel/platform/message/service/impl/SourceMessageCaptureServiceImpl.java`
SourceMessage 原文读取服务	`server/src/main/java/cn/nianxx/thhotel/platform/message/service/impl/SourceMessageOriginalServiceImpl.java`
SourceMessage 持久化边界	`server/src/main/java/cn/nianxx/thhotel/platform/message/repository/MybatisSourceMessageInboxRepository.java`
AgentBus WebSocket 客户端	`server/src/main/java/cn/nianxx/thhotel/integrations/messaging/agentbus/adapter/AgentBusWebSocketClient.java`
AgentBus frame 处理	`server/src/main/java/cn/nianxx/thhotel/integrations/messaging/agentbus/adapter/AgentBusFrameProcessor.java`
AgentBus 到 SourceMessage 适配	`server/src/main/java/cn/nianxx/thhotel/integrations/messaging/agentbus/adapter/AgentBusSourceMessageAdapter.java`
AgentBus 状态 API	`server/src/main/java/cn/nianxx/thhotel/platform/system/control/AgentBusProbeStatusController.java`
SourceMessage 表结构	`server/src/main/resources/db/migration/V1__create_source_message_inbox.sql`
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 对接

4.1 运行时配置

最小配置建议：

AI_PROVIDER_ENABLED=false
DEERFLOW_BASE_URL=https://superagent.nianxx.cn
DEERFLOW_OPEN_API_KEY=
SUPERAGENT_PROBE_ENABLED=false
SUPERAGENT_PROBE_ACCESS_KEY=
SUPERAGENT_CONNECT_TIMEOUT=15s
SUPERAGENT_READ_TIMEOUT=180s
SUPERAGENT_MAX_MESSAGE_CHARS=4000
SUPERAGENT_EXTERNAL_SUBJECT_ID=your-project-superagent-probe

变量说明：

变量	是否 Secret	说明
`AI_PROVIDER_ENABLED`	否	是否启用真实 SuperAgent Provider Adapter。默认关闭。
`DEERFLOW_BASE_URL`	否	SuperAgent / DeerFlow Open API 地址。
`DEERFLOW_OPEN_API_KEY`	是	Open API Key，应只存在后端环境变量或 Secret Manager。
`SUPERAGENT_PROBE_ENABLED`	否	是否开放本项目自己的探针接口。生产默认关闭。
`SUPERAGENT_PROBE_ACCESS_KEY`	是	调用探针接口的本地访问密钥，不是 Provider API Key。
`SUPERAGENT_CONNECT_TIMEOUT`	否	建立连接超时。
`SUPERAGENT_READ_TIMEOUT`	否	旧版 RestClient SSE 读取超时兼容变量；当前 JDK SSE 客户端不设置整段 SSE 固定读取超时，断流恢复由 run/events 机制处理。
`SUPERAGENT_MAX_MESSAGE_CHARS`	否	单次发送给 Provider 的消息长度上限。
`SUPERAGENT_EXTERNAL_SUBJECT_ID`	否	创建 Agent Session 时使用的外部主体标识。

4.2 当前已验证的 Open API 调用形态

当前 TH Hotel 已验证的流程：

POST /api/open/agent-sessions
→ 获取 session_id
→ POST /api/open/agent-sessions/{sessionId}/messages/stream
→ 读取 text/event-stream
→ 解析最终 answer、run、profile、model、token usage

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。CSRF token 由后端每次请求临时生成，不走环境变量，不作为长期 Secret 保存。

Authorization: Bearer <DEERFLOW_OPEN_API_KEY>
X-Request-ID: <stable-request-id>
X-CSRF-Token: <temporary-random-token>
Cookie: csrf_token=<same-temporary-random-token>

Debug EML 和 M007 AgentBus 自动分发复用同一个 Open API client，因此两条链路都会携带上述 CSRF header / cookie。

4.3 Session 请求示例

{
  "external_subject_id": "your-project-superagent-probe",
  "idempotency_key": "your-project-superagent-session-<correlation-id>",
  "metadata": {
    "source": "your-project",
    "purpose": "provider-connectivity-test"
  }
}

4.4 SSE 消息请求示例

{
  "message": "请介绍一下你是谁。",
  "idempotency_key": "your-project-superagent-message-<correlation-id>",
  "metadata": {
    "source": "your-project",
    "purpose": "provider-flow-test"
  }
}

4.5 SSE 解析口径

TH Hotel 当前观测并处理的事件类型：

Event	用途
`metadata`	读取 Run、Thread、Profile 等调用元数据
`messages`	流式消息增量或中间消息
`values`	阶段性或最终聚合状态
`end`	SSE 正常结束标志

解析最终答案时，不要简单拼接所有 messages。当前实现从后期 values.messages[] 中选择：

type = ai
response_metadata.finish_reason = stop
content 非空

并记录：

run_id
resolved_profile_id
resolved_profile_version_id
response_metadata.model_name
usage_metadata.input_tokens
usage_metadata.output_tokens
usage_metadata.total_tokens
已出现的 SSE event types

如果没有收到 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 平台能力端口

其他项目建议定义一个稳定端口，例如：

public interface AgentCapabilityPort {
    AgentCapabilityResult invoke(AgentCapabilityRequest request);
}

领域层只依赖这个端口，不依赖 SuperAgent HTTP DTO、SSE event、Profile ID 或厂商 SDK。

建议 AgentCapabilityResult 至少包含：

providerCode
responseSchemaVersion
providerSessionId
providerRequestId
providerProfileId
providerProfileVersionId
providerModelId
outputText 或 outputReference
usageMetadata

4.7 调用审计

建议每次外部能力调用都写入不可变审计表。TH Hotel 当前表为 platform_ai_capability_invocation，参考：

server/src/main/resources/db/migration/V2__create_ai_capability_invocation.sql
docs/database/ai-capability-invocation-data-dictionary.md

审计表应记录成功与失败，不应记录：

Provider API Key
Cookie
Authorization
Chain of Thought
Provider 内部 Plan / Memory
未脱敏的个人信息

5. AgentBus 对接

5.1 运行时配置

最小配置建议：

AGENTBUS_PROBE_ENABLED=false
AGENTBUS_WS_URL=wss://mesh.nianxx.cn/ws
AGENTBUS_WS_TOKEN=
AGENTBUS_BOT_ADDRESS=bot:external:listener
AGENTBUS_WS_RECONNECT_DELAY=5s
AGENTBUS_CONNECT_TIMEOUT=15s
AGENTBUS_SAMPLE_ENABLED=false
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

变量说明：

变量	是否 Secret	说明
`AGENTBUS_PROBE_ENABLED`	否	是否启用 AgentBus WebSocket 监听。默认关闭。
`AGENTBUS_WS_URL`	否	AgentBus WebSocket 地址。
`AGENTBUS_WS_TOKEN`	是	WebSocket 鉴权 Token。
`AGENTBUS_BOT_ADDRESS`	否	当前 Bot / Listener 地址。
`AGENTBUS_WS_RECONNECT_DELAY`	否	断线后的重连间隔。
`AGENTBUS_CONNECT_TIMEOUT`	否	WebSocket 连接超时。
`AGENTBUS_SAMPLE_ENABLED`	否	是否保存本地原始 frame 样本。生产应默认关闭。
`AGENTBUS_SAMPLE_DIR`	否	本地样本目录，可能含 PII，不得提交。
`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_*_ORIGINAL_READ_ACCESS_KEY`	否	已废弃。SourceMessage 原文 / 会话正文读取已迁移到前端 Bearer 登录 + `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ` + 酒店访问权，不再配置原文读取 key。

5.2 WebSocket 连接

当前实现使用 JDK HttpClient 的 WebSocket：

Authorization: Bearer <AGENTBUS_WS_TOKEN>
GET <AGENTBUS_WS_URL>?ready=1

连接成功后应能收到 session.ready。

状态查询接口示例：

GET /api/system/agentbus-probe

响应只应返回连接状态、计数器和最近错误代码，不返回 Token 或原始消息。

5.3 入站 frame 处理边界

推荐处理顺序：

收到 raw WebSocket frame
→ 限制单帧大小
→ 可选本地采样
→ JSON 解析
→ 忽略 session.ready / task.progress / task.result 等控制事件
→ 将业务 payload 映射为 CaptureSourceMessageCommand
→ 写入 SourceMessage Inbox
→ 如 M007 dispatch 配置开启且为新建 RECEIVED Inbox，创建 SuperAgent dispatch run

实时链路禁止：

自动发送 ACK。
自动发送 task.result。
自动回复客户。
直接创建 MessageEvent、Evidence、AI Recognition、Case、Task、Operation 或 Receipt。
直接调用 OHIP、ERP、支付系统等业务写接口。
在 WebSocket 回调事务内同步等待 SuperAgent 返回。

5.4 当前已确认的 Outlook Payload 关键字段

AgentBus 后续确认的 Outlook 邮件 payload 包括：

text
body.content_type
body.html
body.text
inline_images[]
attachments[]
received_at
source.channel
source.channel_account
source.external_message_id
source.external_conversation_id
source.sender
source.subject
source.sent_at
source.web_link
reply_policy.mode
reply_policy.final_only

当前 SourceMessage 捕获只依赖少量稳定字段：

AgentBus 字段	平台字段
`source.channel`	`channel`，例如 `EMAIL`
`source.external_message_id`	`externalMessageId`，作为幂等键组成部分
`source.external_conversation_id`	`externalConversationId`
`payload.received_at` 或 `source.received_at`	`receivedAt`，作为邮件来源接收时间
`source.sent_at`	`sourceSentAt`，作为邮件来源发送时间
`source.sender`	`senderSummary`，当前作为发件人展示值不打码
frame `id`	`agentbusFrameId`
frame `session_id`	`agentbusSessionId`
`payload` 规范 JSON	`payloadJson` 与 `payloadSha256`

不要根据 envelope 的 from、to、conversation_id 猜测酒店、业务 Case 或下游 Task。

5.5 SourceMessage Inbox

建议单独建表保存 AgentBus 入站事实。TH Hotel 当前表为：

platform_source_message_inbox
platform_source_message_replay_attempt

参考：

server/src/main/resources/db/migration/V16__create_source_message_inbox.sql
docs/agentbus-production-flow.md

推荐幂等键：

hotel_id + provider + channel + external_message_id

中文说明：M005 后 hotel_id 由本系统后端解析，不要求 AgentBus payload 携带酒店；单酒店阶段要求 platform_hotel 只有一家 ACTIVE 酒店。

重复投递时返回已有 Inbox，不覆盖原始 payload，不创建重复记录。

如果 payload 缺少必要字段或格式不符合预期，也应保存为 FAILED Inbox，并记录安全错误摘要。错误摘要不得包含：

邮件正文
HTML
附件 URL
完整邮箱地址
Token / Cookie / Secret

5.6 Replay 到 MessageEvent / Evidence

SourceMessage Inbox 不应等同于正式业务消息。推荐增加受控 Replay：

POST /api/system/source-message-inbox/{inboxId}/replay
Header: X-TH-Hotel-Source-Replay-Key

Replay 负责：

从 Inbox payload 提取 MessageEvent 字段。
保存正文或正文引用。
保存 Evidence 摘要或附件引用。
记录 replay attempt。
返回 MessageEvent ID 和状态。

Replay 接口默认关闭，仅在本地、UAT 或受控生产运维场景开启。

5.7 AgentBus 入库后自动分发 SuperAgent

M007 已实现的自动分发链路不是 Debug EML，也不是 SourceMessage Replay。它只负责把 AgentBus 新入库邮件异步交给 SuperAgent Open API：

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 写入工具触发。
Debug EML 虽然不进入生产 dispatch，但 V4 smoke 默认复用实时 AgentBus V4 Open API subject：th-hotel-agentbus-source-message。历史 th-hotel-debug-eml-upload profile 如仍需排查旧 V2/V3 页面问题，必须通过环境变量显式指定，不能作为 M002 V4 smoke 默认 profile。

M011 CP3 已在 worker 调用 SuperAgent Open API 前增加可配置的 Booking Excel 附件预处理：

SourceMessage payload + 附件引用
→ 识别 Excel 附件类型
→ 排除 PASSENGER_ROSTER 人员名单
→ 按月份窗口抽取 BOOKING_SURCHARGE / BOOKING_UPDATE 高亮行
→ 把 attachment_extractions[] 追加到发给 SuperAgent 的 AgentBus Outlook-like payload

中文说明：该预处理只增强 SuperAgent 输入证据，不改变 SourceMessage Inbox 的来源事实定位，也不直接创建订单、任务或客户回复。解析失败第一版建议写入安全 warning 并按配置决定是否继续调用 SuperAgent；日志和 dispatch run 不得保存完整附件 URL、签名参数、API Key、Cookie、Secret 或整份 Excel 内容。详细规则见 docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md。

开启方式：

AGENTBUS_TEST_SUPERAGENT_DISPATCH_INCLUDE_BOOKING_EXCEL_EXTRACTIONS=true
RESERVATION_BOOKING_EXCEL_EXTRACTION_ENABLED=true

中文说明：agentbus.superagent-dispatch.include-booking-excel-extractions 只控制 AgentBus worker 是否把抽取结果追加给 SuperAgent；reservation.booking-excel-extraction.enabled 是解析服务总开关。两者必须同时开启才会产生有效高亮行结果。当前测试机已开启该增强，生产环境默认关闭，生产开启需单独确认。

当前表名为 platform_superagent_dispatch_run，详细字段、状态流转、错误分类和验收标准见 docs/project/requirements/M007-agentbus-superagent-auto-dispatch-v1.md。

6. 其他项目最小落地顺序

阶段 1：SuperAgent 连通性

目标：

后端探针
→ 创建 SuperAgent Session
→ 发送一条无 PII 测试消息
→ 解析 SSE 最终回答
→ 返回非敏感元数据

验收：

HTTP 连接成功。
SSE 收到 end。
最终回答非空。
日志不出现 API Key、Cookie、Session 原始值或客户信息。

阶段 2：AgentBus 连接

目标：

AgentBus WebSocket
→ session.ready
→ 状态接口可见 connected/sessionReady

验收：

连接成功。
可断线重连。
不发送客户回复。
不保存本地 raw sample，除非临时排障。

阶段 3：SourceMessage Inbox

目标：

AgentBus 入站业务 frame
→ SourceMessage Inbox

验收：

正常 payload 保存为 RECEIVED。
无效 payload 保存为 FAILED。
重复外部消息不重复入库。
查询接口只返回安全摘要。

阶段 4：自动分发 SuperAgent

目标：

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

目标：

SourceMessage Inbox
→ MessageEvent / Evidence

验收：

同一 Inbox 可以按不同 replayRunId 多次 replay。
相同 replayRunId 幂等。
Replay 失败有 attempt 记录。
响应不返回客户正文、HTML、附件 URL 或 Token。

阶段 6：业务接入 SuperAgent

目标：

MessageEvent
→ AgentCapabilityPort
→ SuperAgent Adapter
→ AiCapabilityInvocation
→ 业务 Schema 校验

验收：

Provider 返回记录为审计，不直接触发业务写操作。
结构化输出必须通过 Schema 校验。
无法映射或不可信结果进入人工处理。

7. 安全与日志清单

必须放入 Secret 管理，不得提交仓库：

DEERFLOW_OPEN_API_KEY
SUPERAGENT_PROBE_ACCESS_KEY
AGENTBUS_WS_TOKEN
SOURCE_MESSAGE_REPLAY_ACCESS_KEY
数据库密码
任何真实客户渠道 Token

普通日志和错误响应不得输出：

Authorization
Cookie
Provider API Key
AgentBus Token
邮件正文和 HTML
附件 URL
客人姓名、邮箱、电话、证件号
支付信息

本地采样要求：

AGENTBUS_SAMPLE_ENABLED 默认 false。
只在隔离测试或排障时临时开启。
样本目录必须被 .gitignore 忽略。
排障结束后删除样本。

8. 测试建议

SuperAgent 建议覆盖：

缺失 API Key 时启动或调用失败。
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 建议覆盖：

session.ready 只更新状态，不写 Inbox。
控制事件不写 Inbox。
正常 Outlook payload 写入 Inbox。
captureEnabled=false 时忽略业务 frame。
无效 payload 写入 FAILED Inbox。
超大 frame 被拒绝并记录错误代码。
重复外部消息保持幂等。
查询接口不返回原始 payload。
Replay 相同 run id 幂等。

9. 常见误区

9.1 把 AgentBus 当 AI Provider

AgentBus 是消息入口，不是抽取模型。它可以传递 Email / LINE 原始事实，但不应该直接产生业务最终判断。

9.2 把 SuperAgent 返回当业务事实

SuperAgent 返回的是 Provider 输出。即使未来返回结构化 JSON，也必须经过平台 Schema、业务规则、Case 匹配和人工确认。

9.3 让浏览器直接调用 Provider

浏览器不能持有 Provider Key、AgentBus Token 或 replay access key。前端只调用本项目后端。

9.4 实时入口直接生成 Task

实时 AgentBus 链路如果直接创建 Task，会导致重复投递、字段不完整、后续协议变化和人工回溯都难处理。先落 Inbox，再 Replay，是更稳的路线。

9.5 在文档或测试里保存真实邮件

真实邮件、附件 URL、客户姓名和联系方式都可能是敏感数据。测试夹具应使用合成数据。

10. 接入前检查清单

接入 SuperAgent 前确认：

已获得 Open API Key 和允许访问的 Base URL。
已确认当前 Open API 鉴权方式；当前后端 client 会自动发送临时 CSRF double-submit header / cookie。
已确认 Session、Message、Run 的生命周期。
已确认 SSE 最终答案或结构化结果所在字段。
已定义 AgentCapabilityPort 和调用审计表。
已确认 Provider 输出不会直接触发业务写操作。

接入 AgentBus 前确认：

已获得 WebSocket URL、Token 和 Bot Address。
已确认真实渠道 payload 字段。
已确认外部消息稳定幂等键。
已确认断线重连和重复投递语义。
已确认是否允许 ACK 或客户回复；默认按禁止处理。
已建立 SourceMessage Inbox 和 Replay attempt。
已定义原始 payload 的保存、访问、保留和删除策略。

进入生产前确认：

所有 Secret 均通过环境变量或 Secret Manager 注入。
.env.example 只有占位值。
日志脱敏已验证。
自动回复保持关闭。
自动业务写操作保持关闭，除非经过单独评审。
监控至少覆盖连接状态、失败次数、Replay 失败和 Provider 调用失败。

26 KiB Raw Blame History Unescape Escape