superagent请求问题修复

2026-09-06 01:40:15 +08:00
parent ee9d2d7cf1
commit 7243319bbb
19 changed files with 388 additions and 74 deletions
--- a/docs/project/README.md
+++ b/docs/project/README.md
@@ -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 反向代理示例 | 高 |
--- a/docs/project/integrations/superagent-openapi.md
+++ b/docs/project/integrations/superagent-openapi.md
@@ -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 中静默猜测。
--- a/docs/project/operations/docker-test-deployment.md
+++ b/docs/project/operations/docker-test-deployment.md
@@ -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 条无效面几何缺口已记录。