SuperAgent Open API 项目接入指南

项	内容
项目	`fire-safety-ymd`
协议基线	TH Hotel 仓库保存的 2026-07-12 Open Agent API 资料
当前状态	Go Adapter、默认关闭的原生用户对话 API 与可选兼容入口已完成模拟联调；上线前必须与当前 SuperAgent 环境重新联调

1. 项目调用边界

用户侧应用
  -> fire-safety-ymd POST /api/chat
     或 /api/v1/apps/{app_id}/completion
  -> 内存会话与并发 Run 控制
  -> SuperAgent Client Port
  -> SuperAgent Open API Adapter（本 checkpoint）
  -> 已发布的消防 SuperAgent Profile

前端不得持有 Open API Key 或直接调用 SuperAgent。Adapter 只负责 Provider 协议，消防业务 Service 不直接解析 SSE 或依赖 Provider DTO。

2. Profile 与 Session

Open API 请求不直接提交 profile_id。平台通过 df_open_* 外部应用 Key 对应的策略选择已发布 Profile，因此消防项目必须创建独立外部应用并绑定消防 Profile，不能复用 TH Hotel 的 Profile 或 Key。

external_subject_id 表示外部主体，不是 Profile ID。首版对话 API 使用服务端固定的非真实测试主体，并在单进程内存中保存：

本地用户 + 本地会话
  -> SuperAgent external_subject_id
  -> SuperAgent session_id

同一多轮对话复用同一 Session；同一 Session 有 active Run 时返回 409，不能并发重发。该映射尚未持久化，重启和多实例切换后旧对话不可恢复；真实用户阶段必须改用经验证且假名化的主体，并补共享/持久会话存储。

3. Open API 流程

创建 Session：POST /api/open/agent-sessions。
流式发送消息：POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true。
初始流断开时查询 GET {Content-Location}。
使用 GET {Content-Location}/events 和 Last-Event-ID 恢复。
只有最终内容、成功 run.completed 和顶层 end 同时存在时返回成功。

如果未来需要主动取消，平台资料中的接口为：

POST /api/open/agent-sessions/{session_id}/runs/{run_id}/cancel

取消能力不属于本 checkpoint。

4. 外部应用要求

平台管理员需要为本项目确认：

独立消防 Profile 已发布且 API exposure 已开启。
外部应用 Key 已绑定目标 Profile。
至少具备 agent_sessions:create、agent_sessions:message 和 agent_sessions:read scope。
后续需要取消 Run 时增加 agent_sessions:cancel。
需要公开 Trace 时，应用策略的 trace_policy.enabled=true。
工具输入、输出和步骤信息默认只暴露 summary，不开放模型原始思考过程。

5. 本地配置

复制 .env.example 中的占位配置到本地 Secret 管理方式，不提交真实值。

主要变量：

FIRE_SAFETY_SUPERAGENT_ENABLED=true
FIRE_SAFETY_SUPERAGENT_BASE_URL=https://<superagent-domain>
FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<secret>

FIRE_SAFETY_CHAT_ENABLED=true
FIRE_SAFETY_CHAT_AUTH_TOKEN=<another-secret-at-least-32-printable-ascii-characters>
FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=http://localhost:5173

fire-safety-ymd 不读取通用 DEERFLOW_OPEN_API_KEY，避免开发机上其他项目的凭证被意外复用。

6. CLI 连通性探针

配置测试环境后执行：

go run ./cmd/superagent-probe

探针只发送代码内固定的无敏感信息消息，输出最终回答和必要的安全元数据。它不启动业务聊天、不查询消防数据库、不写业务状态。

探针不会自动读取 TH Hotel 的 DEERFLOW_* 或其他项目变量。至少需要显式设置本项目的启用开关、Base URL 和 Open API Key；未配置时命令会在任何网络请求前退出。

禁止把真实火情、联系人、电话、精确受限位置、生产凭证或客户数据放进探针消息和 metadata。

7. 用户对话 API

原生接口为 POST /api/chat，请求体只接受 message 和可选的本地 conversation_id，响应是 SSE。首次请求由服务端创建 SuperAgent Session 并返回随机对话 ID，后续轮次使用该 ID 复用上下文。客户端不能提交 Provider Session、主体、角色、区域或 metadata。

配置 FIRE_SAFETY_CHAT_COMPAT_APP_ID 后，同一 Chat Service 还提供 DashScope 风格受限兼容路径。它把 input.prompt / input.session_id 映射到上述本地会话语义，以 event: result 和最终 finish_reason=stop 返回严格完成的正文。该入口不是 DashScope 全量代理，也不会把 URL App ID 或客户端 session ID直接传给 Provider。

详细事件、失败语义和 curl 示例见：

FIRE_SAFETY_CHAT_AUTH_TOKEN 是独立的首版联调凭证：原生接口将其作为 Bearer，兼容入口将其作为 xtoken。它不是最终用户登录；浏览器会暴露静态 Token，因此公网真实用户入口仍必须接入身份提供方、动态授权、限流和审计。

8. 与 MCP 的关系

Open API 与 MCP 是两条独立连接：

fire-safety-ymd -> SuperAgent：使用 Open API Key。
SuperAgent -> fire-safety-ymd /mcp：使用独立 MCP 凭证。

本文件记录第一条 Open API 接入。仓库现已另外实现默认关闭的只读空间 MCP 基线；两条系统连接仍使用不同凭证，不能把 Open API Key 当作 MCP Token。用户侧原生/兼容对话使用第三个独立联调凭证，三个值都不得复用。MCP 的部署与工具契约见 superagent-mcp-spatial.md；兼容入站契约见 ../../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md。

9. 当前限制

用户聊天 HTTP API 和单进程并发 Run 控制已实现，但默认关闭，只有静态测试 Bearer，没有最终用户认证或动态授权。
本地会话未持久化；重启、多实例切换和上游失败后不能恢复旧 conversation_id，也尚无主动取消。
MCP/PostGIS 已完成本地实库冒烟，但尚未完成 SuperAgent 到公网 MCP 的联调。
真实 Profile、Key、scope、Trace 策略和网络连通性必须在目标环境验证。
Provider 协议可能在 2026-07-12 资料后变化；出现差异时更新 Spec 和契约，不在 Adapter 中静默猜测。

6.4 KiB Raw Blame History Unescape Escape