huangting/fire-safety-ymd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

superagent请求问题修复

Browse Source
This commit is contained in:
andy
2026-09-06 01:40:15 +08:00
parent ee9d2d7cf1
commit 7243319bbb
19 changed files with 388 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/architecture/public-chat-entry-v1.md
View File

@@ -51,6 +51,20 @@ Nginx 不再直接调用 DashScope。它只负责 TLS、精确公开路径、基
这样保留了当前应急辅助场景的失败语义：断流或 Provider 协议不完整时，客户端不会把半截模型文本误当成已完成方案。代价是首版没有逐字动画；如后续必须实时输出，需要独立安全决策、取消/失败 UX 和新 Spec。
### 4.1 SuperAgent Trace 模式
上游消息流的 `include_trace` 由 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 控制，默认值为
`false`。两种模式都要求最终 AI 消息和顶层 `event: end`，但严格成功条件不同：
- 无 Trace：最终 AI 消息的 `finish_reason=stop` + 非空顶层 `message.final` + 顶层 `end`。
- Trace：最终内容 + `run.completed(status=success)` + 顶层 `end`。
无 Trace 只是不向调用方返回公开工具/步骤轨迹，不等于禁止 SuperAgent 执行中调用 MCP；Agent
是否实际调用消防工具仍必须通过完整对话和 `/mcp` 日志验证。当前受控诊断中，应用策略关闭
Trace 时 `include_trace=true` 返回 HTTP 403、Provider code `open_agent_trace_disabled`，
同一 Key 改为 `include_trace=false` 返回 HTTP 200。因此测试环境默认保持无 Trace；只有在外部
应用策略显式启用 `trace_policy.enabled=true` 后才可切换为 Trace 模式。
测试页面使用浏览器 `fetch` 发起 POST，以便同时设置 `xtoken` 并读取 SSE；它不会把 Token
写进 HTML、Cookie、localStorage、sessionStorage、URL 或服务端配置。用户每次打开页面都要手动
输入测试 `xtoken`，页面只在本次页面生命周期内使用该值。页面可展示用户输入的问题和最终回答，
@@ -79,4 +93,5 @@ Nginx 不再直接调用 DashScope。它只负责 TLS、精确公开路径、基
- [`chat-api-v1.md`](chat-api-v1.md)
- [`../workflows/user-chat.md`](../workflows/user-chat.md)
- [`../project/operations/nginx-public-entry.md`](../project/operations/nginx-public-entry.md)
- [`../project/integrations/superagent-openapi.md`](../project/integrations/superagent-openapi.md)
- [`../specs/fire-safety-ymd-chat-page-v1.md`](../specs/fire-safety-ymd-chat-page-v1.md)

2
docs/project/README.md
View File

@@ -13,7 +13,7 @@
| [`ai-nses-project-overlay.md`](ai-nses-project-overlay.md) | fire-safety-ymd 对通用标准的项目覆盖规则 | 低 |
| [`backend-development-guidelines.md`](backend-development-guidelines.md) | Go 后端工程规范 | 低 |
| [`security-access-control-boundary.md`](security-access-control-boundary.md) | AI、MCP、数据库、身份和敏感数据边界 | 中 |
| [`integrations/superagent-openapi.md`](integrations/superagent-openapi.md) | SuperAgent Open API、Session、SSE 恢复与探针说明 | 中 |
| [`integrations/superagent-openapi.md`](integrations/superagent-openapi.md) | SuperAgent Open API、Session、无 Trace/Trace SSE、恢复与探针说明 | 中 |
| [`integrations/superagent-mcp-spatial.md`](integrations/superagent-mcp-spatial.md) | SuperAgent 空间只读 MCP、配置、工具和联调门禁 | 高 |
| [`operations/postgis-srid-4326.md`](operations/postgis-srid-4326.md) | 已确认 WGS84 数据的 SRID 元数据迁移、验证与权限边界 | 高 |
| [`operations/nginx-public-entry.md`](operations/nginx-public-entry.md) | `agent.nianxx.com` 到 Go 页面、对话/MCP 的 HTTPS 反向代理示例 | 高 |

42
docs/project/integrations/superagent-openapi.md
View File

@@ -4,7 +4,7 @@
| --- | --- |
| 项目 | `fire-safety-ymd` |
| 协议基线 | TH Hotel 仓库保存的 2026-07-12 Open Agent API 资料 |
| 当前状态 | Go Adapter、默认关闭的原生用户对话 API 与可选兼容入口已完成模拟联调；上线前必须与当前 SuperAgent 环境重新联调 |
| 当前状态 | Go Adapter、默认关闭的原生用户对话 API 与可选兼容入口已完成；模拟联调、真实无 Trace CLI 探针和本地兼容 Chat 冒烟均已通过，测试服务器重建及公网完整多工具链仍待验收 |
## 1. 项目调用边界
@@ -37,10 +37,23 @@ Open API 请求不直接提交 `profile_id`。平台通过 `df_open_*` 外部应
## 3. Open API 流程
1. 创建 Session：`POST /api/open/agent-sessions`。
2. 流式发送消息：`POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true`。
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. 只有最终内容、成功 `run.completed` 和顶层 `end` 同时存在时返回成功。
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 日志验证。
如果未来需要主动取消，平台资料中的接口为：
@@ -58,9 +71,15 @@ POST /api/open/agent-sessions/{session_id}/runs/{run_id}/cancel
- 外部应用 Key 已绑定目标 Profile。
- 至少具备 `agent_sessions:create`、`agent_sessions:message` 和 `agent_sessions:read` scope。
- 后续需要取消 Run 时增加 `agent_sessions:cancel`。
- 需要公开 Trace 时，应用策略的 `trace_policy.enabled=true`。
- 默认无 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 管理方式，不提交真实值。
@@ -71,6 +90,9 @@ POST /api/open/agent-sessions/{session_id}/runs/{run_id}/cancel
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>
@@ -91,6 +113,10 @@ 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；未配置时命令会在任何网络请求前退出。
@@ -123,6 +149,10 @@ Open API 与 MCP 是两条独立连接：
- 用户聊天 HTTP API 和单进程并发 Run 控制已实现，但默认关闭，只有静态测试 Bearer，没有最终用户认证或动态授权。
- 本地会话未持久化；重启、多实例切换和上游失败后不能恢复旧 `conversation_id`，也尚无主动取消。
- MCP/PostGIS 已完成本地实库冒烟，但尚未完成 SuperAgent 到公网 MCP 的联调。
- 真实 Profile、Key、scope、Trace 策略和网络连通性必须在目标环境验证。
- 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 中静默猜测。

56
docs/project/operations/docker-test-deployment.md
View File

@@ -109,6 +109,8 @@ FIRE_SAFETY_BUILD_GOPROXY=https://proxy.golang.org,direct
FIRE_SAFETY_SUPERAGENT_ENABLED=true
FIRE_SAFETY_SUPERAGENT_BASE_URL=https://<superagent-api-host>
FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<superagent-open-api-key>
# 当前外部应用策略关闭 Trace 时保持 false；只有策略显式允许 Trace 才设置 true
FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false
FIRE_SAFETY_CHAT_ENABLED=true
FIRE_SAFETY_CHAT_AUTH_TOKEN=<独立的高熵xtoken>
@@ -141,6 +143,10 @@ FIRE_SAFETY_POSTGIS_EXPECTED_SRID=4326
- FIRE_SAFETY_CHAT_PAGE_ENABLED 默认必须为 false。开启后 Go 提供 `/chat`、`/chat/` 以及同源的
`/chat/app.css`、`/chat/app.js`；`/chat` 会 308 到 `/chat/`，页面和资源的最终可用性仍由 Go
开关决定。页面只用于受控测试，不嵌入或持久化 Token。
- FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE 默认必须为 false。无 Trace 的严格成功条件是最终 AI 消息
`finish_reason=stop`、非空顶层 `event: message.final` 加顶层 `event: end`；设置为 true 时还要求
`run.completed(status=success)`，且外部应用策略必须开启 `trace_policy.enabled=true`。无 Trace
只是不返回公开工具/步骤轨迹，不等于禁止 SuperAgent 调用 MCP。
- 页面开启时 FIRE_SAFETY_CHAT_ALLOWED_ORIGINS 必须包含精确的 `https://agent.nianxx.com`，并且
Chat 兼容 App ID、Chat Token 和 SuperAgent 配置已经可用；该静态页面不是最终用户认证。
- 使用 FIRE_SAFETY_MCP_SCOPE_MODE=all 时，FIRE_SAFETY_MCP_ALLOWED_TOWNS 必须保持为空。all 是服务账号级的固定查询表范围，不是最终用户级授权。
@@ -148,6 +154,10 @@ FIRE_SAFETY_POSTGIS_EXPECTED_SRID=4326
- FIRE_SAFETY_HTTP_ADDR 在容器内应为 :8080，安全边界由 Compose 的 127.0.0.1:16587:8080 和宿主机 Nginx 提供；不要在 Compose 场景设为容器内的 127.0.0.1:8080。
- 不要用没有 --quiet 的 docker compose config 或 docker inspect 把完整环境渲染到终端、CI 日志或工单；检查 .env 权限仍为 600。
- 修改 `.env` 后必须重新创建容器（例如 `docker compose up -d --force-recreate --no-build`）才能加载新的 Chat 兼容开关；单独 `docker compose restart` 不会重新读取容器环境。旧短凭证仅用于受控测试/迁移，完成轮换后把开关改回 `false` 并再次 recreate。
- 修改 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 或其他 SuperAgent 代码/配置后，至少执行
`docker compose config --quiet`、`docker compose build --pull` 和
`docker compose up -d --force-recreate --remove-orphans`；仅 `docker compose restart` 不会
重新读取 `.env`，也不会把新代码构建进镜像。
## 4. 容器访问现有 PostgreSQL/PostGIS
@@ -381,7 +391,43 @@ curl -i https://agent.nianxx.com/chat/
版本导致故障，回到维护者指定的已验证 Git revision 或 root-only Nginx 备份，先 `nginx -t`
再 reload；不要恢复旧的全路径 DashScope 代理、关闭 Go 鉴权或把 Secret 写入 Nginx。
## 9. SuperAgent MCP 回调配置与冒烟
## 9. SuperAgent Open API 无 Trace 模式
当前测试环境优先使用无 Trace 模式，避免外部应用策略未开放公开 Trace 导致消息流返回
`HTTP 403` / `open_agent_trace_disabled`。在服务器 `.env` 中确认：
~~~text
FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false
~~~
无 Trace 模式仍严格要求上游最终 AI 消息的 `finish_reason=stop`、非空顶层
`event: message.final` 和顶层 `event: end`；最终回答只取 `message.final.text`。它只是不向调用方
返回公开工具/步骤轨迹，不等于禁止 SuperAgent 在执行中调用已配置的 MCP 工具。确认 MCP 是否
实际被调用，必须检查 `/mcp` 日志和返回结果。只有外部应用策略显式开启
`trace_policy.enabled=true` 时，才把该值改为 `true`；Trace 模式会额外要求
`run.completed(status=success)`。
修改 `.env` 后必须重新构建并重新创建服务，使配置在运行容器中生效：
~~~bash
cd /home/firee-safety-ymd
docker compose config --quiet
docker compose build --pull
docker compose up -d --force-recreate --remove-orphans
docker compose ps
docker compose logs --tail=100 api
curl --fail http://127.0.0.1:16587/health
~~~
不要在日志或工单中粘贴 Open API Key。若仍收到 403，只记录 HTTP 状态、脱敏后的 Provider code、
时间和请求关联 ID，交由 SuperAgent 平台核对外部应用策略；不要反复轮换无关的 Chat/MCP 凭证。
受控诊断已经确认：同一 Key 的 `include_trace=true` 因应用策略返回 403
`open_agent_trace_disabled`；同一 Key 的 `include_trace=false` 已由真实探针完成严格成功判定，
本地兼容 Chat SSE 也完成 `finish_reason=null -> stop`。公网完整消防对话、MCP 实际工具调用和
多轮会话仍需单独验收。
## 10. SuperAgent MCP 回调配置与冒烟
在 SuperAgent 的工具/MCP 配置中新增远程 MCP 服务：
@@ -454,7 +500,7 @@ curl --fail \
unset MCP_BEARER
~~~
## 10. 更新、重启与回滚
## 11. 更新、重启与回滚
### 发布新版本
@@ -515,7 +561,7 @@ cd /home/firee-safety-ymd
docker compose down
~~~
## 11. 完成判定与当前限制
## 12. 完成判定与当前限制
本手册完成不代表公网部署已完成。现场交付至少应记录：
@@ -525,6 +571,10 @@ docker compose down
- Chat 首轮/多轮 SSE、错误凭证、未知 app/path 的实际 HTTPS 响应。
- 页面浏览器验收证明用户手动输入 xtoken、Token 不被页面持久化、兼容 completion SSE 及同页面 `session_id` 复用；这只是静态测试页面，不是生产认证。
- 若为已交付旧客户端临时开启 Chat legacy 短凭证兼容，应记录受控迁移窗口，确认启动 warning 不含 Secret，并在凭证轮换后恢复 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false`。
- SuperAgent Open API 使用 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false` 时，验证最终 AI 消息
`finish_reason=stop`、非空顶层 `message.final` 加顶层 `end`；若切换为 true，验证外部应用
Trace 策略已开启且 `run.completed(status=success)` 仍为必要条件。无 Trace 不等同于 MCP
禁用；完整消防对话和 MCP 工具调用仍须单独记录。
- SuperAgent -> `/mcp` 的独立 Bearer、TLS/网络白名单、无版本配置 initialize 兼容响应、`notifications/initialized`、`tools/list` 和全部 7 个受控只读 `tools/call`。现场已有地点搜索一次成功证据，但其余工具未验收；版本字段/Header 不作为配置或拒绝门禁；公网请求到达但没有完成这条调用链，不算完成。
- 数据库未公开 5432，运行账号保持只读，PostGIS readiness warning 和 35 条无效面几何缺口已记录。

40
docs/specs/fire-safety-ymd-superagent-openapi-connectivity.md
View File

@@ -12,13 +12,14 @@
fire-safety-ymd 需要由 Go 后端调用既有 SuperAgent 平台，并在后续让 SuperAgent 通过本项目 MCP 工具查询 PostgreSQL/PostGIS 消防数据。
TH Hotel 项目已经验证了“创建 Open Agent Session、流式发送消息、解析公开 Trace、严格判断完成状态和断流恢复”的调用形态。本 checkpoint 只迁移协议经验和安全边界，使用 Go 独立实现，不复制 Java、酒店业务、AgentBus、邮件、OSS 或任务结果写入逻辑。
TH Hotel 项目已经验证了“创建 Open Agent Session、流式发送消息、解析公开 Trace、严格判断完成状态和断流恢复”的调用形态。本 checkpoint 只迁移协议经验和安全边界，使用 Go 独立实现，不复制 Java、酒店业务、AgentBus、邮件、OSS 或任务结果写入逻辑。当前 SuperAgent 外部应用策略关闭了 Trace：同一 Key 使用 `include_trace=true` 返回 HTTP 403、Provider code 为 `open_agent_trace_disabled`，使用 `include_trace=false` 返回 HTTP 200，因此本项目默认采用无 Trace 模式，同时保留显式 Trace 开关。
## 2. 目标
- 建立独立、可测试的 Go SuperAgent Open API Adapter。
- 分离 `CreateSession` 与 `StreamMessage`，为后续一个本地对话复用一个 SuperAgent Session 做准备。
- 使用严格 SSE 成功条件，拒绝部分回答和不完整协议结果。
- 通过 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 选择无 Trace 或公开 Trace；两种模式均不返回部分答案。
- 初始 SSE 断流后通过既有 Run 恢复，不重新发送原始消息。
- 提供默认关闭的 CLI 连通性探针，只发送固定无敏感信息消息。
- 所有自动化测试使用本地模拟 Provider，不需要真实 Secret 或网络。
@@ -43,6 +44,7 @@ TH Hotel 项目已经验证了“创建 Open Agent Session、流式发送消息
- 目标与非目标已确认：是。
- 协议基线已确认：以 TH Hotel 仓库保存的 2026-07-12 SuperAgent Open API 文档和当前实现为输入，真实环境上线前重新验证。
- 权限和安全边界已确认：Secret 仅由本项目环境变量注入；没有用户业务数据进入探针。
- Trace 策略已确认：默认无 Trace；如需 `include_trace=true`，外部应用必须允许 `trace_policy.enabled=true`。
- 外部依赖已确认：实现只使用 Go 标准库。
- 未确认问题已列出：Profile、外部应用、scope、真实 Base URL 和 API Key 均由平台管理员后续提供。
@@ -65,10 +67,12 @@ POST /api/open/agent-sessions
### 6.2 流式发送消息
```text
POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true
POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=false
```
请求包含 `message`、稳定 `idempotency_key` 和安全 `metadata`。Session ID 由上层明确传入，Adapter 不在每条消息前隐式创建新 Session。
`include_trace` 由 `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 控制，默认值为 `false`；只有外部应用
策略明确开启 Trace 时才设置为 `true`。请求包含 `message`、稳定 `idempotency_key` 和安全
`metadata`。Session ID 由上层明确传入，Adapter 不在每条消息前隐式创建新 Session。
### 6.3 鉴权与关联 Header
@@ -79,12 +83,18 @@ POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true
## 7. SSE 成功与恢复规则
一次调用只有同时满足以下条件才成功：
一次调用只有满足对应模式的严格条件才成功：
1. 收到最终内容；优先使用 `message.final`，兼容累计 `message.delta` 和历史 `messages`/`values` AI 消息。
2. 收到 `run.completed` 且 `status=success`。
3. 收到顶层 `event: end`。
4. 没有收到顶层 `error` 或 `run.failed`。
- 无 Trace（`include_trace=false`）：收到历史 `messages`/`values` 中最终 AI 消息，且其
`response_metadata.finish_reason=stop`，同时收到非空顶层 `event: message.final` 和顶层
`event: end`；最终回答只采用 `message.final.text`。
- Trace（`include_trace=true`）：收到最终内容（优先 `message.final`，兼容累计
`message.delta` 和历史 `messages`/`values` AI 消息）、`run.completed` 且 `status=success`，
并收到顶层 `event: end`。
- 两种模式都不能收到顶层 `error` 或 `run.failed`；断流、缺少必要条件或协议错误不得返回部分答案。
无 Trace 不向调用方返回公开工具/步骤轨迹，但只控制 Trace 暴露和完成判定，不禁止 SuperAgent
在执行中调用已配置的 MCP 工具。是否实际调用工具仍须使用完整对话和 MCP 服务日志验收。
解析器必须支持 `event:`、多行 `data:`、`id:`、心跳注释和空行分帧，并按 SSE event ID 去重。
@@ -104,6 +114,7 @@ POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true
| `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_INCLUDE_TRACE` | `false` | 是否请求公开 Trace；`true` 要求外部应用策略开启 `trace_policy.enabled` |
| `FIRE_SAFETY_SUPERAGENT_CONNECT_TIMEOUT` | `15s` | 建连超时 |
| `FIRE_SAFETY_SUPERAGENT_RECOVERY_MAX_ATTEMPTS` | `5` | SSE 恢复最大次数；最大可配置为 20 |
| `FIRE_SAFETY_SUPERAGENT_RECOVERY_INITIAL_BACKOFF` | `250ms` | 首次恢复退避 |
@@ -128,16 +139,17 @@ POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true
| --- | --- | --- | --- | --- |
| 环境配置与安全默认值 | Done | Passed | 本文第 8 节 | Implemented |
| CreateSession | Done | Passed | 本文第 6.1 节 | Implemented |
| StreamMessage 与严格成功条件 | Done | Passed | 本文第 6.2、7 节 | Implemented |
| StreamMessage 与按模式严格成功条件 | Done | Passed | 本文第 6.2、7 节 | Implemented |
| SSE 断流恢复 | Done | Passed | 本文第 7 节 | Implemented |
| CLI 探针 | Done | Compile passed；live test pending | 项目集成指南 | Implemented |
| CLI 探针 | Done | Automated passed；2026-09-06 live no-Trace passed | 项目集成指南 | Verified |
## 11. 验收标准
- Given 未启用 SuperAgent，When 执行真实调用，Then 返回受控禁用错误且不发起网络请求。
- Given 配置完整，When 创建 Session，Then请求具备鉴权、幂等、关联和 CSRF Header，且能解析 Session ID。
- Given完整 SSE，When 同时收到最终内容、成功完成和 `end`，Then 返回最终回答与安全元数据。
- Given SSE 缺少任一成功条件，When 无法恢复，Then 返回协议错误且不返回部分回答。
- Given `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=false` 且收到 `finish_reason=stop`、非空顶层 `message.final` 与 `end`，Then 返回 `message.final.text` 和安全元数据，不要求 `run.completed`。
- Given `FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE=true` 且同时收到最终内容、成功完成和 `end`，Then 返回最终回答与安全元数据。
- Given 对应模式缺少任一必要成功条件，When 无法恢复，Then 返回协议错误且不返回部分回答。
- Given 初始 SSE 提前结束且存在 Run URL，When 恢复，Then只 GET Run/events、携带 `Last-Event-ID`，消息 POST 次数仍为 1。
- Given未设置真实环境变量，When 运行全部测试，Then 不访问外网且测试通过。
@@ -145,7 +157,8 @@ POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true
- 配置默认值、合法值和错误值。
- Session 请求路径、Header、CSRF、请求体和响应解析。
- 当前 Trace SSE、历史 messages/values 兼容、事件 ID 去重和多行 data。
- 无 Trace 的历史 messages/values 最终 AI 消息、`finish_reason=stop`、非空顶层 `message.final` 和顶层 `end`。
- Trace SSE 的最终内容、`run.completed(status=success)`、历史 messages/values 兼容、事件 ID 去重和多行 data。
- 缺少 final/completed/end、顶层 error、run.failed 和非法 JSON。
- 提前 EOF 恢复、Last-Event-ID、同源 URL 和不重复 POST。
- HTTP 非 2xx、超大控制响应和 context 取消。
@@ -156,4 +169,5 @@ POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true
- `gofmt`、`go test ./...` 和 `go vet ./...` 通过。
- 没有真实 Secret、用户数据、构建产物或无关用户变更。
- 项目索引、集成指南、安全边界和 `PROJECT_STATE.md` 已同步。
- 默认无 Trace 能在不开放 `trace_policy` 时完成严格成功判定；Trace 模式仍保留 `run.completed` 成功门禁。
- 真实环境未配置时明确说明未做 live connectivity test。

13
docs/workflows/user-chat.md
View File

@@ -42,6 +42,13 @@ Network 应显示同源 POST 到精确 app ID 的 completion 路径，Request He
发送第二个问题时，应在第二次请求中看到上一轮返回的 `session_id` 被放入 `input.session_id`。不要把初始 `finish_reason=null` 或
断流内容当作最终答案。
页面客户端看到的成功契约不随上游 Trace 开关变化，始终以兼容流最后的
`output.finish_reason=stop` 为准。服务端到 SuperAgent 的严格判定由
`FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 控制：默认 `false` 时要求上游最终 AI 消息
`finish_reason=stop`、非空顶层 `message.final` 和顶层 `event: end`；设置为 `true` 时还要求
`run.completed(status=success)`。无 Trace 只是不返回工具/步骤轨迹，不代表 SuperAgent 不会
调用 MCP；要确认 MCP 是否实际执行，必须同时检查服务日志和工具结果。
## 3. 后续对话
后续请求同时发送 `message` 和前一轮保存的 `conversation_id`。成功流中的 `conversation` 事件返回 `reused=true`，说明复用了原 SuperAgent Session 上下文。
@@ -56,6 +63,12 @@ Network 应显示同源 POST 到精确 app ID 的 completion 路径，Request He
- 上游超时、协议错误、Run 失败或客户端中途断开：当前实现会使会话映射失效，以免继续复用可能仍有活动 Run 的 Provider Session。
- 网络断开且没有看到 `done`：结果未知；首版不自动重放原消息，避免重复 Run。
如果上游返回 `open_agent_trace_disabled` 或 HTTP 403，先检查是否将
`FIRE_SAFETY_SUPERAGENT_INCLUDE_TRACE` 设置为 `true`。当前应用策略关闭 Trace 时，使用
`include_trace=true` 会被拒绝；同一 Key 使用默认的 `include_trace=false` 可以返回 HTTP 200。
只有在外部应用策略明确启用 `trace_policy.enabled=true` 后，才应切换为 `true`。修改环境变量后
必须重建或重新创建运行容器，不能只依赖 `docker compose restart` 重新读取配置。
## 5. curl 联调
先把 `.env` 显式加载到当前 shell，再启动服务；Go 程序不会自动读取 `.env`：