159 lines
9.4 KiB
Markdown
159 lines
9.4 KiB
Markdown
# SuperAgent Open API 项目接入指南
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 项目 | `fire-safety-ymd` |
|
||
| 协议基线 | TH Hotel 仓库保存的 2026-07-12 Open Agent API 资料 |
|
||
| 当前状态 | Go Adapter、默认关闭的原生用户对话 API 与可选兼容入口已完成；模拟联调、真实无 Trace CLI 探针和本地兼容 Chat 冒烟均已通过，测试服务器重建及公网完整多工具链仍待验收 |
|
||
|
||
## 1. 项目调用边界
|
||
|
||
```text
|
||
用户侧应用
|
||
-> 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 使用服务端固定的非真实测试主体，并在单进程内存中保存：
|
||
|
||
```text
|
||
本地用户 + 本地会话
|
||
-> SuperAgent external_subject_id
|
||
-> SuperAgent session_id
|
||
```
|
||
|
||
同一多轮对话复用同一 Session；同一 Session 有 active Run 时返回 `409`，不能并发重发。该映射尚未持久化，重启和多实例切换后旧对话不可恢复；真实用户阶段必须改用经验证且假名化的主体，并补共享/持久会话存储。
|
||
|
||
## 3. Open API 流程
|
||
|
||
1. 创建 Session：`POST /api/open/agent-sessions`。
|
||
2. 按 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 选择流式发送消息：
|
||
`POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=false`
|
||
（默认）或 `include_trace=true`。
|
||
3. 初始流断开时查询 `GET {Content-Location}`。
|
||
4. 使用 `GET {Content-Location}/events` 和 `Last-Event-ID` 恢复。
|
||
5. 两种模式都要求最终 AI 消息和顶层 `end`；无 Trace 模式还必须收到非空顶层
|
||
`message.final`，且最终 AI 消息必须带 `finish_reason=stop`；Trace 模式还必须收到
|
||
`run.completed` 且 `status=success`。
|
||
|
||
严格成功条件按模式区分：
|
||
|
||
- `include_trace=false`：`AI message.finish_reason=stop` + 非空顶层 `event: message.final` + 顶层 `event: end`。
|
||
- `include_trace=true`：最终内容 + `run.completed(status=success)` + 顶层 `event: end`。
|
||
- 任一模式收到顶层 `error`、`run.failed`、断流或协议不完整，都不返回部分答案。
|
||
|
||
无 Trace 只是不向调用方返回公开工具/步骤轨迹，不等于禁止 SuperAgent 在执行过程中调用
|
||
已配置的 MCP 工具；工具是否实际调用仍需通过完整对话和 MCP 日志验证。
|
||
|
||
如果未来需要主动取消，平台资料中的接口为：
|
||
|
||
```text
|
||
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 策略；如果设置 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=true`，
|
||
应用策略必须显式设置 `trace_policy.enabled=true`。
|
||
- 工具输入、输出和步骤信息默认只暴露 summary，不开放模型原始思考过程。
|
||
|
||
2026-09-06 的受控诊断使用同一个外部应用 Key：`include_trace=true` 因应用策略关闭 Trace
|
||
返回 HTTP 403，Provider code 为 `open_agent_trace_disabled`；改为 `include_trace=false`
|
||
后返回 HTTP 200。该结果说明默认无 Trace 是当前策略下的兼容运行模式；它不代表 Agent 不能
|
||
调用 MCP，公网完整消防对话和多工具调用仍待验证。
|
||
|
||
## 5. 本地配置
|
||
|
||
复制 `.env.example` 中的占位配置到本地 Secret 管理方式，不提交真实值。
|
||
|
||
主要变量：
|
||
|
||
```text
|
||
FIRE_SAFETY_SUPERAGENT_ENABLED=true
|
||
FIRE_SAFETY_SUPERAGENT_BASE_URL=https://<superagent-domain>
|
||
FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<secret>
|
||
# Default false: require AI finish_reason=stop, non-empty message.final, and end.
|
||
# Set true only if the external app policy enables trace_policy.enabled.
|
||
FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false
|
||
|
||
FIRE_SAFETY_CHAT_ENABLED=true
|
||
FIRE_SAFETY_CHAT_AUTH_TOKEN=<another-secret-at-least-32-printable-ascii-characters>
|
||
# Keep false for new environments. Only set true during a controlled migration
|
||
# when an already-issued legacy Chat credential is shorter than 32 characters.
|
||
FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
|
||
FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=http://localhost:5173
|
||
```
|
||
|
||
fire-safety-ymd 不读取通用 `DEERFLOW_OPEN_API_KEY`，避免开发机上其他项目的凭证被意外复用。
|
||
|
||
## 6. CLI 连通性探针
|
||
|
||
配置测试环境后执行：
|
||
|
||
```bash
|
||
go run ./cmd/superagent-probe
|
||
```
|
||
|
||
探针只发送代码内固定的无敏感信息消息，输出最终回答和必要的安全元数据。它不启动业务聊天、不查询消防数据库、不写业务状态。
|
||
探针遵循 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE`：默认无 Trace 时按
|
||
`finish_reason=stop`、非空顶层 `message.final` 和顶层 `end` 判定成功；启用 Trace 时还要求
|
||
`run.completed(status=success)`。
|
||
无 Trace 不会返回工具轨迹，但不等于禁止 Agent 调 MCP。
|
||
|
||
探针不会自动读取 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 示例见：
|
||
|
||
- [`../../architecture/chat-api-v1.md`](../../architecture/chat-api-v1.md)
|
||
- [`../../workflows/user-chat.md`](../../workflows/user-chat.md)
|
||
- [`../../specs/fire-safety-ymd-chat-api-v1.md`](../../specs/fire-safety-ymd-chat-api-v1.md)
|
||
|
||
`FIRE_SAFETY_CHAT_AUTH_TOKEN` 是独立的首版联调凭证：原生接口将其作为 Bearer，兼容入口将其作为 `xtoken`。默认要求至少 32 个字符；如果旧客户端已经拿到且无法立即更换的凭证较短，只能在受控测试/迁移窗口显式设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`。此时仍要求凭证非空、不超过 4096 字节，并且仅含 ASCII `0x21-0x7e`（无空格、控制字符或 Unicode）；该开关不影响 MCP Token 的至少 32 个字符门禁，三种凭证仍必须不同。轮换后恢复 `false`，新环境不得开启；服务会记录不含 Secret 的安全 warning 提醒清理。它不是最终用户登录；浏览器会暴露静态 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`](../../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md)。
|
||
|
||
## 9. 当前限制
|
||
|
||
- 用户聊天 HTTP API 和单进程并发 Run 控制已实现，但默认关闭，只有静态测试 Bearer，没有最终用户认证或动态授权。
|
||
- 本地会话未持久化；重启、多实例切换和上游失败后不能恢复旧 `conversation_id`，也尚无主动取消。
|
||
- MCP/PostGIS 已完成本地实库冒烟；SuperAgent 到公网 MCP 已完成一次
|
||
`fire_safety_search_place_candidates` 调用，但其余 6 个工具和完整多工具链仍待验收。
|
||
- 当前测试 Profile、Key、scope 和网络已通过真实无 Trace CLI 探针；本地兼容 Chat SSE 也已完成
|
||
`finish_reason=null -> stop`。生产凭证、轮换和目标服务器重建仍待验收；
|
||
`FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=true` 因当前应用策略关闭 Trace 而返回
|
||
`open_agent_trace_disabled`，只有策略显式开启后才能验证 Trace 模式。
|
||
- Provider 协议可能在 2026-07-12 资料后变化；出现差异时更新 Spec 和契约，不在 Adapter 中静默猜测。
|