superagent请求问题修复

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 中静默猜测。