huangting/fire-safety-ymd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee9d2d7cf1a31c7a8be50fcc06f7e6a5d8ad795d
fire-safety-ymd/docs/specs/fire-safety-ymd-superagent-openapi-connectivity.md
andy 8a6c31c14d 初始化第一版
2026-09-05 15:46:37 +08:00

7.8 KiB
Raw Blame History

SuperAgent Open API 连通性基线 Spec

项 内容
状态 Implemented
日期 2026-09-04
负责人 fire-safety-ymd 后端
需求来源 用户 checkpoint fire-safety-ymd-superagent-openapi-connectivity
关联 Change Request 无

1. 背景

fire-safety-ymd 需要由 Go 后端调用既有 SuperAgent 平台，并在后续让 SuperAgent 通过本项目 MCP 工具查询 PostgreSQL/PostGIS 消防数据。

TH Hotel 项目已经验证了“创建 Open Agent Session、流式发送消息、解析公开 Trace、严格判断完成状态和断流恢复”的调用形态。本 checkpoint 只迁移协议经验和安全边界，使用 Go 独立实现，不复制 Java、酒店业务、AgentBus、邮件、OSS 或任务结果写入逻辑。

2. 目标

  • 建立独立、可测试的 Go SuperAgent Open API Adapter。
  • 分离 CreateSession 与 StreamMessage，为后续一个本地对话复用一个 SuperAgent Session 做准备。
  • 使用严格 SSE 成功条件，拒绝部分回答和不完整协议结果。
  • 初始 SSE 断流后通过既有 Run 恢复，不重新发送原始消息。
  • 提供默认关闭的 CLI 连通性探针，只发送固定无敏感信息消息。
  • 所有自动化测试使用本地模拟 Provider，不需要真实 Secret 或网络。

3. 非目标

  • 不实现浏览器或业务聊天 API。
  • 不持久化本地会话与 SuperAgent Session 的映射。
  • 不实现 /mcp endpoint 或消防工具。
  • 不连接 PostgreSQL/PostGIS。
  • 不创建或配置 SuperAgent Profile、外部应用、API Key 或 MCP Server。
  • 不把 SuperAgent 输出写入消防业务事实。

4. 用户与场景

当前用户是开发和联调人员：在安全配置测试环境后，通过 CLI 探针验证 Go 服务能创建 Session、发送无敏感信息消息并取得严格完成的最终回答。

后续的用户对话 API v1 已在独立 Spec 中实现对该 Adapter 的复用、单进程会话映射、并发冲突和客户端 SSE；真实身份、持久化与主动取消仍需另行设计。

5. Definition of Ready

  • 目标与非目标已确认：是。
  • 协议基线已确认：以 TH Hotel 仓库保存的 2026-07-12 SuperAgent Open API 文档和当前实现为输入，真实环境上线前重新验证。
  • 权限和安全边界已确认：Secret 仅由本项目环境变量注入；没有用户业务数据进入探针。
  • 外部依赖已确认：实现只使用 Go 标准库。
  • 未确认问题已列出：Profile、外部应用、scope、真实 Base URL 和 API Key 均由平台管理员后续提供。

6. 协议与客户端契约

6.1 创建 Session

POST /api/open/agent-sessions

请求包含：

  • external_subject_id：调用方提供的稳定、非敏感主体标识。
  • idempotency_key：创建 Session 的稳定幂等键。
  • metadata：不包含 Secret 的关联元数据。

客户端接受响应中的 session_id，并兼容 id 字段。

6.2 流式发送消息

POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true

请求包含 message、稳定 idempotency_key 和安全 metadata。Session ID 由上层明确传入，Adapter 不在每条消息前隐式创建新 Session。

6.3 鉴权与关联 Header

  • Authorization: Bearer <Open API Key>
  • X-Request-ID: <稳定请求关联 ID>
  • X-CSRF-Token 与 Cookie: csrf_token=... 使用同一个每请求随机值。
  • SSE 使用 Accept: text/event-stream 和 Cache-Control: no-cache。

7. SSE 成功与恢复规则

一次调用只有同时满足以下条件才成功：

  1. 收到最终内容；优先使用 message.final，兼容累计 message.delta 和历史 messages/values AI 消息。
  2. 收到 run.completed 且 status=success。
  3. 收到顶层 event: end。
  4. 没有收到顶层 error 或 run.failed。

解析器必须支持 event:、多行 data:、id:、心跳注释和空行分帧，并按 SSE event ID 去重。

初始流提前结束时：

  • 不重新 POST 消息。
  • 从 Content-Location 获取同源 Run URL；必要时使用已解析的 Run ID 构造 URL。
  • 查询 Run 状态，再订阅 {run_url}/events。
  • 恢复请求携带 Last-Event-ID。
  • 使用有上限的指数退避并服从调用方 context 取消。
  • 恢复耗尽或进入失败终态时返回明确错误，不返回部分答案。

8. 配置契约

环境变量 默认值 说明
FIRE_SAFETY_SUPERAGENT_ENABLED false 总开关，默认不调用真实 Provider
FIRE_SAFETY_SUPERAGENT_BASE_URL 空 SuperAgent Open API Base URL
FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY 空 Secret，启用时必填
FIRE_SAFETY_SUPERAGENT_CONNECT_TIMEOUT 15s 建连超时
FIRE_SAFETY_SUPERAGENT_RECOVERY_MAX_ATTEMPTS 5 SSE 恢复最大次数；最大可配置为 20
FIRE_SAFETY_SUPERAGENT_RECOVERY_INITIAL_BACKOFF 250ms 首次恢复退避
FIRE_SAFETY_SUPERAGENT_MAX_MESSAGE_BYTES 65536 单条消息 UTF-8 字节上限；最大可配置为 16 MiB
FIRE_SAFETY_SUPERAGENT_PROBE_SUBJECT_ID 固定探针主体 仅 CLI 探针使用
FIRE_SAFETY_SUPERAGENT_PROBE_TIMEOUT 10m 探针总超时

启用时配置缺失或不合法必须启动失败；错误不得包含 API Key。

9. 安全规则

  • 不读取 TH Hotel 的环境变量或 Secret，不共享 API Key。
  • Base URL 必须是绝对 HTTP/HTTPS URL，且不得带 userinfo、query 或 fragment。
  • Content-Location 和恢复 URL 必须与配置 Base URL 同源，防止向其他主机转发 Authorization。
  • 错误只暴露安全状态和经过限制的 Provider error code，不返回响应正文。
  • 客户端不记录消息、Header、Cookie、API Key 或 SSE 原始数据。
  • Probe 使用固定安全消息；不得用它发送真实火情、联系人或生产数据。

10. 需求追踪表

需求项 后端状态 测试状态 文档位置 当前状态
环境配置与安全默认值 Done Passed 本文第 8 节 Implemented
CreateSession Done Passed 本文第 6.1 节 Implemented
StreamMessage 与严格成功条件 Done Passed 本文第 6.2、7 节 Implemented
SSE 断流恢复 Done Passed 本文第 7 节 Implemented
CLI 探针 Done Compile passed；live test pending 项目集成指南 Implemented

11. 验收标准

  • Given 未启用 SuperAgent，When 执行真实调用，Then 返回受控禁用错误且不发起网络请求。
  • Given 配置完整，When 创建 Session，Then请求具备鉴权、幂等、关联和 CSRF Header，且能解析 Session ID。
  • Given完整 SSE，When 同时收到最终内容、成功完成和 end，Then 返回最终回答与安全元数据。
  • Given SSE 缺少任一成功条件，When 无法恢复，Then 返回协议错误且不返回部分回答。
  • Given 初始 SSE 提前结束且存在 Run URL，When 恢复，Then只 GET Run/events、携带 Last-Event-ID，消息 POST 次数仍为 1。
  • Given未设置真实环境变量，When 运行全部测试，Then 不访问外网且测试通过。

12. 测试范围

  • 配置默认值、合法值和错误值。
  • Session 请求路径、Header、CSRF、请求体和响应解析。
  • 当前 Trace SSE、历史 messages/values 兼容、事件 ID 去重和多行 data。
  • 缺少 final/completed/end、顶层 error、run.failed 和非法 JSON。
  • 提前 EOF 恢复、Last-Event-ID、同源 URL 和不重复 POST。
  • HTTP 非 2xx、超大控制响应和 context 取消。

13. Definition of Done

  • 实现满足本文契约。
  • gofmt、go test ./... 和 go vet ./... 通过。
  • 没有真实 Secret、用户数据、构建产物或无关用户变更。
  • 项目索引、集成指南、安全边界和 PROJECT_STATE.md 已同步。
  • 真实环境未配置时明确说明未做 live connectivity test。