增加调试前端页面

2026-09-06 00:25:25 +08:00
parent 3080b17d02
commit ee9d2d7cf1
22 changed files with 1442 additions and 59 deletions
--- a/docs/project/README.md
+++ b/docs/project/README.md
@@ -16,10 +16,11 @@
 | [`integrations/superagent-openapi.md`](integrations/superagent-openapi.md) | SuperAgent Open API、Session、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 反向代理示例 | 高 |
+| [`operations/nginx-public-entry.md`](operations/nginx-public-entry.md) | `agent.nianxx.com` 到 Go 页面、对话/MCP 的 HTTPS 反向代理示例 | 高 |
 | [`operations/docker-test-deployment.md`](operations/docker-test-deployment.md) | `/home/firee-safety-ymd` 测试服务器的 Docker Compose、Nginx、验证与回滚手册 | 高 |
 | [`../architecture/chat-api-v1.md`](../architecture/chat-api-v1.md) | 用户对话入口、内存 Session 映射、SSE 和三凭证边界 | 高 |
 | [`../architecture/public-chat-entry-v1.md`](../architecture/public-chat-entry-v1.md) | DashScope 风格兼容入口、Nginx、会话映射与严格结果边界 | 高 |
+| [`../specs/fire-safety-ymd-chat-page-v1.md`](../specs/fire-safety-ymd-chat-page-v1.md) | 默认关闭的 `/chat` 测试页面、同源兼容 SSE、Token 与会话边界 | 高 |
 | [`../architecture/spatial-mcp-v1.md`](../architecture/spatial-mcp-v1.md) | MCP、Service、Repository 与 8 张 PostGIS 表的架构 | 中 |
 | [`../workflows/user-chat.md`](../workflows/user-chat.md) | 首轮/多轮对话、失败处理和 curl 联调流程 | 高 |
 | [`../workflows/exercise-plan-evidence.md`](../workflows/exercise-plan-evidence.md) | 从地名候选或演练点坐标查询方案证据的流程与能力边界 | 中 |
@@ -45,6 +46,6 @@
 - `docs/architecture/`：已有用户对话、DashScope 风格公网兼容入口和空间 MCP v1；后续保存系统、数据、模块和部署架构。
 - `docs/workflows/`：已有用户对话和演练方案证据查询流程；后续保存异常补偿流程。
 - `docs/adr/`：不可逆或跨模块的重要决策。
- `docs/specs/`：可验收的功能规格；已有原生/兼容用户对话 API、SuperAgent Open API 和空间只读 MCP Spec。
+- `docs/specs/`：可验收的功能规格；已有原生/兼容用户对话 API、受控测试页面、SuperAgent Open API 和空间只读 MCP Spec。

 新增文档必须能回答“未来的新 Agent 为什么需要阅读它”，并从本索引或上级文档建立入口。
--- a/docs/project/operations/docker-test-deployment.md
+++ b/docs/project/operations/docker-test-deployment.md
@@ -6,7 +6,7 @@
 | 运行方式 | 宿主机 Nginx 终止 HTTPS，Docker Compose 运行单个 Go 服务 |
 | 应用监听边界 | 容器内监听 8080，只发布到宿主机 127.0.0.1:16587 |
 | 数据库 | 使用现有 PostgreSQL/PostGIS；本手册不创建数据库容器、不导入 SQL |
-| 状态 | 测试环境部署基线；目标机镜像构建和 Nginx 语法检查已由现场截图证明通过，但容器稳定运行、公网 TLS 和 SuperAgent MCP 握手/工具回调仍待重测 |
+| 状态 | 测试环境部署基线；目标机镜像构建和 Nginx 语法检查已由现场截图证明通过，但容器稳定运行、页面资源、公网 TLS 和 SuperAgent MCP 完整工具链仍待重测 |

 本手册不包含真实 Token、API Key、数据库密码或旧 Nginx 配置内容。命令中的尖括号是服务器上需要替换的占位符；不要把 Secret 写进命令行、Nginx 文件、镜像构建参数或 Git。

@@ -117,8 +117,10 @@ FIRE_SAFETY_CHAT_AUTH_TOKEN=<独立的高熵xtoken>
 FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_SUBJECT_ID=fire-safety-ymd-chat-test-subject
 FIRE_SAFETY_CHAT_COMPAT_APP_ID=<与Nginx路径完全一致的公开app-id>
-# 仅浏览器实际 Origin；CLI/服务端调用可以留空
-FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://<actual-frontend-origin>
+# 可选的受控测试页面默认关闭；开启时必须同时启用 Chat/兼容入口
+FIRE_SAFETY_CHAT_PAGE_ENABLED=false
+# 页面从 agent.nianxx.com 同源加载时必须包含该精确 Origin；可按需追加其他测试 Origin
+FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://agent.nianxx.com

 FIRE_SAFETY_MCP_ENABLED=true
 FIRE_SAFETY_MCP_AUTH_TOKEN=<独立的高熵MCP-bearer>
@@ -136,6 +138,11 @@ FIRE_SAFETY_POSTGIS_EXPECTED_SRID=4326
 - FIRE_SAFETY_CHAT_AUTH_TOKEN 只用于兼容对话入口的 xtoken；FIRE_SAFETY_MCP_AUTH_TOKEN 只用于 SuperAgent 调用 /mcp；FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY 只用于 Go 服务访问 SuperAgent。三者必须不同。
 - Chat Token 默认至少 32 个可打印 ASCII 字符。如果已交付的旧客户端凭证较短且无法立即更换，只能临时设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`；此时仍要求 Token 非空、不超过 4096 字节，并且每个字符都在 ASCII `0x21-0x7e` 范围内（无空格、控制字符或 Unicode）。该开关只影响 Chat 原生 Bearer 和兼容 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的要求。新环境不得开启，凭证轮换完成后必须恢复 `false`；开关启用时启动日志会记录不含 Secret 的安全 warning。
 - FIRE_SAFETY_CHAT_COMPAT_APP_ID 是公开路径标识，不是 Secret；它必须与 Nginx 的精确 location = /api/v1/apps/<app-id>/completion 完全一致。
+- FIRE_SAFETY_CHAT_PAGE_ENABLED 默认必须为 false。开启后 Go 提供 `/chat`、`/chat/` 以及同源的
+  `/chat/app.css`、`/chat/app.js`；`/chat` 会 308 到 `/chat/`，页面和资源的最终可用性仍由 Go
+  开关决定。页面只用于受控测试，不嵌入或持久化 Token。
+- 页面开启时 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 是服务账号级的固定查询表范围，不是最终用户级授权。
 - FIRE_SAFETY_POSTGIS_MIGRATION_DSN 不应配置给运行服务；迁移凭证只供一次性迁移命令使用，完成后应移除。
 - FIRE_SAFETY_HTTP_ADDR 在容器内应为 :8080，安全边界由 Compose 的 127.0.0.1:16587:8080 和宿主机 Nginx 提供；不要在 Compose 场景设为容器内的 127.0.0.1:8080。
@@ -295,7 +302,86 @@ curl -N --fail \
 unset CHAT_XTOKEN
 ~~~

-## 8. SuperAgent MCP 回调配置与冒烟
+## 8. 公网 Chat 测试页面
+
+测试页面由 Go 可选提供，不需要单独的前端容器或 Nginx 静态目录。页面及两个同源资源的
+Nginx 精确路径已经包含在仓库模板中：`/chat`、`/chat/`、`/chat/app.css` 和 `/chat/app.js`。
+Nginx 始终可以反代这些路径，但是否返回内容由 Go 的
+`FIRE_SAFETY_CHAT_PAGE_ENABLED` 控制。
+
+### 开启页面
+
+在服务器受保护的 `.env` 中确认或修改以下非 Secret 配置：
+
+~~~text
+FIRE_SAFETY_CHAT_ENABLED=true
+FIRE_SAFETY_CHAT_COMPAT_APP_ID=<与Nginx completion路径一致的公开app-id>
+FIRE_SAFETY_CHAT_PAGE_ENABLED=true
+FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://agent.nianxx.com
+~~~
+
+页面开启要求 Chat、兼容 App ID、Chat 测试凭证和 SuperAgent 配置已经有效；
+`https://agent.nianxx.com` 必须是精确 Origin，不能使用 `*`。页面是受控测试工具，不是最终
+用户认证，用户要在页面中手动输入 xtoken，不能把 Token 写入页面、Nginx 或镜像。
+
+修改 `.env` 后必须重新创建容器，单独 restart 不会重新读取环境变量：
+
+~~~bash
+cd /home/firee-safety-ymd
+docker compose config --quiet
+docker compose up -d --force-recreate --no-build
+docker compose ps
+curl --fail http://127.0.0.1:16587/health
+~~~
+
+如果 Nginx 模板刚刚更新，再执行 `sudo nginx -t`，确认通过后再 reload；只改 Go 开关时不需要
+改 Nginx 文件。
+
+### 页面验收
+
+先不带 Token 检查页面和资源路由：
+
+~~~bash
+curl -i https://agent.nianxx.com/chat
+curl -i https://agent.nianxx.com/chat/
+curl -i https://agent.nianxx.com/chat/app.css
+curl -i https://agent.nianxx.com/chat/app.js
+~~~
+
+开启时预期 `/chat` 返回 HTTP 308 并指向 `/chat/`，`/chat/` 返回 HTTP 200 HTML，CSS 和
+JavaScript 返回 HTTP 200。需要自动跟随入口重定向时使用：
+
+~~~bash
+curl -iL https://agent.nianxx.com/chat
+~~~
+
+关闭时，Go 不注册页面 Handler，`/chat`、`/chat/`、`/chat/app.css` 和 `/chat/app.js` 均
+直接返回 HTTP 404；这与 Nginx 是否保留四个精确 location 无关。
+
+浏览器打开 `https://agent.nianxx.com/chat/`，手动输入受控测试 xtoken（页面不会预填或保存），
+发送不含敏感信息的问题。Network 面板应看到同源 POST 到
+`/api/v1/apps/<same-safe-app-id>/completion`，请求体为第三方兼容格式，Header 含 `xtoken`，
+响应为 `event: result` SSE。只有 `output.finish_reason=stop` 才是成功；第二轮请求应把第一轮
+成功返回的 `output.session_id` 放入 `input.session_id`。刷新或关闭页面后，Token 和 session_id
+均应清除，不得自动恢复。
+
+### 关闭与回滚
+
+紧急关闭页面时，将 `.env` 的 `FIRE_SAFETY_CHAT_PAGE_ENABLED` 改回 `false`，执行：
+
+~~~bash
+cd /home/firee-safety-ymd
+docker compose up -d --force-recreate --no-build
+curl -i https://agent.nianxx.com/chat
+curl -i https://agent.nianxx.com/chat/
+~~~
+
+确认两个路径直接 404（无 308），并按需检查 CSS/JavaScript 资源也为 404。该操作不会自动
+关闭兼容 completion；如需一并关闭 Chat，再按 Chat 总开关执行配置回滚。若页面版本或 Nginx
+版本导致故障，回到维护者指定的已验证 Git revision 或 root-only Nginx 备份，先 `nginx -t`
+再 reload；不要恢复旧的全路径 DashScope 代理、关闭 Go 鉴权或把 Secret 写入 Nginx。
+
+## 9. SuperAgent MCP 回调配置与冒烟

 在 SuperAgent 的工具/MCP 配置中新增远程 MCP 服务：

@@ -309,7 +395,7 @@ Authorization: Bearer <FIRE_SAFETY_MCP_AUTH_TOKEN>

 服务端兼容规则如下：对可解析的 JSON-RPC `initialize`，`params.protocolVersion` 的缺失、空值、非字符串或其他值都不作为版本拒绝条件，响应固定返回 `result.protocolVersion: "2025-06-18"`；`MCP-Protocol-Version` Header 的缺失或值也不作为版本拒绝条件。固定返回该版本不表示服务实现或声明支持任意客户端版本，`2025-03-26`、`2025-11-25` 等值也不改变服务端实现目标。兼容仅针对版本元数据，Bearer、`Content-Type`、非空 `Origin`、JSON-RPC 结构、只读工具、服务端数据范围和敏感字段边界仍严格执行。

-现场截图只证明公网 `/mcp` 已到达 Go 服务：Bearer、`Content-Type` 和 JSON-RPC 前置检查已通过，随后旧版本门禁返回错误。该历史截图没有捕获客户端版本字段是否存在、类型和值；同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定调用是兼容档案参照，但不是消防 MCP 成功证据。部署后通过 `direct_success`（客户端值为 `2025-06-18`）或 `compatibility_success`（版本字段缺失或其他值被兼容处理）日志分类确认，并完成完整调用链；服务端不得记录原始版本值。公网 SuperAgent 尚未调用消防数据库工具，因此不能把该截图当成公网部署或业务联调完成。
+现场日志已证明公网 `/mcp` 完成 initialize、notifications/initialized、tools/list，并成功调用一次 `fire_safety_search_place_candidates`；该证据只覆盖地点搜索，不能替代其余消防工具和完整多工具链验收。同一 SuperAgent 中 `th-hotel-simple-superagent` 已稳定调用是兼容档案参照。部署后继续通过 `direct_success`（客户端值为 `2025-06-18`）或 `compatibility_success`（版本字段缺失或其他值被兼容处理）日志分类确认，服务端不得记录原始版本值。

 如果修改了 MCP Handler 或握手协商逻辑，目标机必须拉取包含该修改的明确 revision 后重建镜像；仅 `docker compose restart` 不会更新镜像中的代码：

@@ -368,7 +454,7 @@ curl --fail \
 unset MCP_BEARER
 ~~~

-## 9. 更新、重启与回滚
+## 10. 更新、重启与回滚

 ### 发布新版本

@@ -429,15 +515,17 @@ cd /home/firee-safety-ymd
 docker compose down
 ~~~

-## 10. 完成判定与当前限制
+## 11. 完成判定与当前限制

 本手册完成不代表公网部署已完成。现场交付至少应记录：

 - 目标机 Compose 配置校验、build、up、健康检查和无 Secret 的有限日志结果。
 - 目标机 nginx -t 和 reload 成功；443 证书、DNS、安全组及旧 location / 已确认不再生效。
+- 页面开关关闭时 `/chat`、`/chat/`、`/chat/app.css`、`/chat/app.js` 直接返回 404；开启时 `/chat` 返回 308、`/chat/` 返回 200 HTML，两个资源返回 200；`FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 包含 `https://agent.nianxx.com`。
 - Chat 首轮/多轮 SSE、错误凭证、未知 app/path 的实际 HTTPS 响应。
+- 页面浏览器验收证明用户手动输入 xtoken、Token 不被页面持久化、兼容 completion SSE 及同页面 `session_id` 复用；这只是静态测试页面，不是生产认证。
 - 若为已交付旧客户端临时开启 Chat legacy 短凭证兼容，应记录受控迁移窗口，确认启动 warning 不含 Secret，并在凭证轮换后恢复 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false`。
- SuperAgent -> `/mcp` 的独立 Bearer、TLS/网络白名单、无版本配置 initialize 兼容响应、`notifications/initialized`、`tools/list` 和至少一个受控只读 `tools/call`。版本字段/Header 不作为配置或拒绝门禁；公网请求到达但没有完成这条调用链，不算完成。
+- SuperAgent -> `/mcp` 的独立 Bearer、TLS/网络白名单、无版本配置 initialize 兼容响应、`notifications/initialized`、`tools/list` 和全部 7 个受控只读 `tools/call`。现场已有地点搜索一次成功证据，但其余工具未验收；版本字段/Header 不作为配置或拒绝门禁；公网请求到达但没有完成这条调用链，不算完成。
 - 数据库未公开 5432，运行账号保持只读，PostGIS readiness warning 和 35 条无效面几何缺口已记录。

 若目标服务器无法使用 host.docker.internal、Compose 不支持 --quiet、Nginx include 目录不同、证书路径不同或 SuperAgent 对 MCP 的认证格式不同，应先记录实际环境并调整部署 Spec；不要通过放开端口、写入 Token、关闭 readiness 或恢复全路径反代规避问题。
--- a/docs/project/operations/nginx-public-entry.md
+++ b/docs/project/operations/nginx-public-entry.md
@@ -2,7 +2,7 @@

 | 项 | 内容 |
 | --- | --- |
-| 目标 | 让 `agent.nianxx.com` 通过 HTTPS 访问本项目的兼容对话接口和 MCP |
+| 目标 | 让 `agent.nianxx.com` 通过 HTTPS 访问本项目的可选测试页面、兼容对话接口和 MCP |
 | 状态 | 示例配置；公网机器、证书、网络白名单和真实鉴权仍待联调 |
 | 上游 | 仅反代本机 `127.0.0.1:16587`；容器内部仍监听 8080 |

@@ -27,6 +27,8 @@ Nginx 不再调用 DashScope，也不保存或注入 SuperAgent Open API Key、C
 | 路径 | 用途 | 鉴权与限制 |
 | --- | --- | --- |
 | `/api/v1/apps/<safe-app-id>/completion` | 截图所示的 DashScope-compatible 用户对话 SSE | Go 校验 `xtoken`；请求体 128 KiB；示例限流 5 req/s、burst 20 |
+| `/chat`、`/chat/` | 可选的受控测试对话页面 | `/chat` 由 Go 规范化重定向到 `/chat/`（308）；页面 GET 不要求 Token；Go 由 `FIRE_SAFETY_CHAT_PAGE_ENABLED` 决定返回 HTML 或 404；示例限流 5 req/s、burst 20 |
+| `/chat/app.css`、`/chat/app.js` | 测试页面静态资源 | 页面开关关闭时由 Go 返回 404；开启时返回对应资源；示例限流 5 req/s、burst 20 |
 | `/mcp` | SuperAgent 调用本项目的 MCP | Go 校验独立 `Authorization: Bearer`；请求体 256 KiB；示例限流 20 req/s、burst 40 |
 | `/health` | 可选进程存活检查 | 不访问数据库；如不希望公开可删除该 location |
 | 其他路径 | 不对外提供 | Nginx 固定返回 404 |
@@ -39,6 +41,20 @@ Nginx 不再调用 DashScope，也不保存或注入 SuperAgent Open API Key、C
 4. 直接在宿主机运行 Go 时，应选择未占用的回环端口并同步修改 Nginx upstream；使用本仓库 Compose 时，容器内监听 `:8080`，端口映射保持为 `127.0.0.1:16587:8080`。不要把 16587、容器 8080 或 PostgreSQL 5432 暴露到公网。
 5. 按环境配置 DNS、云防火墙/安全组和 SuperAgent 对 `/mcp` 的来源 IP/TLS 要求；这些部署事实尚未由本项目验证。

+示例中的 `location = /chat`、`location = /chat/`、`location = /chat/app.css` 和
+`location = /chat/app.js` 是页面及其资源的精确入口，均反代到同一个 `127.0.0.1:16587`
+上游。Nginx 不判断页面开关，也不提供备用 HTML、CSS 或 JavaScript：
+
+- `FIRE_SAFETY_CHAT_PAGE_ENABLED=true` 且依赖完整时，Go 返回页面 HTML；
+- 页面请求 `/chat` 时，Go 返回 308 并规范化到 `/chat/`；随后 `/chat/` 返回页面 HTML；
+- 页面请求 CSS/JavaScript 资源时，Go 返回资源内容；
+- 开关为 `false` 或页面依赖不满足时，Go 对页面和资源路径返回 404；
+- 不要把这些 location 改成旧配置的 `location /`，也不要在 Nginx 中注入 xtoken。
+
+页面默认关闭。测试开启时，Go 进程配置的 `FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 必须包含精确
+Origin `https://agent.nianxx.com`；该值是浏览器从页面同源发出 completion 请求时的来源。不要
+用 `*`，也不要把 Token 写入 Nginx。
+
 `limit_req_zone` 必须位于 Nginx `http` context，不能放进 `server` 或 `location`。示例文件假定它被 `conf.d/*.conf` 从 `http {}` 中 include；如果部署系统不是这样 include，应把两条 `limit_req_zone` 指令单独移到 `http {}`，并保留 `server`/`upstream` 在合法上下文。

 ## 3. Go 服务配置
@@ -60,6 +76,10 @@ FIRE_SAFETY_CHAT_AUTH_TOKEN=<chat-xtoken>
 # when an already-issued legacy Chat credential is shorter than 32 characters.
 FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_COMPAT_APP_ID=<same-safe-app-id-as-nginx-location>
+# Optional public test page; keep false unless this test surface is needed.
+FIRE_SAFETY_CHAT_PAGE_ENABLED=false
+# If the page is enabled, this exact same-origin value is required.
+FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=https://agent.nianxx.com

 FIRE_SAFETY_MCP_ENABLED=true
 FIRE_SAFETY_MCP_AUTH_TOKEN=<different-mcp-bearer-at-least-32-printable-ascii-characters>
@@ -74,6 +94,12 @@ FIRE_SAFETY_POSTGIS_DSN=<readonly-postgresql-dsn>
 - `FIRE_SAFETY_MCP_AUTH_TOKEN` 只用于 SuperAgent -> Go `/mcp`，不应复用 Chat Token。
 - Chat、SuperAgent、MCP 和 PostGIS 的完整配置校验以 `.env.example` 和对应项目文档为准。
 - 浏览器会看到 `xtoken`；它不能代表最终用户身份、角色、租户或数据授权。公网真实用户入口仍需身份提供方、动态授权、限流、Secret 轮换和持久审计。
+- `FIRE_SAFETY_CHAT_PAGE_ENABLED` 默认必须为 `false`。开启页面只适用于受控测试；页面 GET 本身
+  不需要 Token，用户在页面输入的 `xtoken` 只在当前页面内存中使用，不写入 HTML、Cookie、URL、
+  localStorage 或 sessionStorage。
+- 页面与兼容接口同源时，`FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 必须包含精确的
+  `https://agent.nianxx.com`。这不是把页面变成生产认证；Token 仍为静态测试凭证，必须由用户
+  手动输入并按测试范围管理。
 - Nginx 不读取、比较或存储 Chat Token，也不需要为 legacy 开关增加配置；请求 Header 原样转发给 Go 校验。开关启用时 Go 仅记录不含 Secret 的安全 warning，便于迁移完成后清理。

 测试服务器使用 Docker Compose 的完整目录、启动、更新和回滚步骤见 [`docker-test-deployment.md`](docker-test-deployment.md)。
@@ -135,6 +161,47 @@ curl -N --fail \

 如果目标客户端不接受 `text/event-stream` 或只需要一次性 JSON，应先以接口 Spec 为准；不要让 Nginx 擅自将 SSE 缓冲成普通 JSON。

+### 受控测试页面
+
+页面由 Go 在开关开启时提供，Nginx 只做四个精确路径的反代（页面、规范化入口和两个资源）：
+
+```bash
+curl -i https://agent.nianxx.com/chat
+curl -i https://agent.nianxx.com/chat/
+```
+
+预期行为：
+
+- `FIRE_SAFETY_CHAT_PAGE_ENABLED=false`：`/chat` 和 `/chat/` 均直接返回 HTTP 404；
+- `FIRE_SAFETY_CHAT_PAGE_ENABLED=true` 且 Chat 兼容配置完整：`/chat` 返回 HTTP 308，
+  `/chat/` 返回 HTTP 200，`Content-Type` 为 `text/html`；
+- 开启时页面加载的 `/chat/app.css` 和 `/chat/app.js` 也应返回 HTTP 200；关闭时均为 404。
+
+需要跟随 `/chat` 的规范化重定向时使用：
+
+```bash
+curl -iL https://agent.nianxx.com/chat
+```
+
+浏览器打开 `https://agent.nianxx.com/chat/` 后，手动输入受控测试 `xtoken` 和不含敏感信息的
+问题。页面使用 `fetch` 向同源的
+`/api/v1/apps/<same-safe-app-id>/completion` 发起 POST，Header 为 `xtoken`、
+`Content-Type: application/json`、`Accept: text/event-stream`，请求体仍是：
+
+```json
+{"input":{"prompt":"观水镇附近有哪些地点候选？"},"parameters":{}}
+```
+
+页面只在内存中保存最终成功的 `output.session_id`，下一轮把它放入 `input.session_id`；刷新或
+关闭页面后不恢复。只有 `finish_reason=stop` 才显示为成功，初始 `finish_reason=null`、HTTP
+错误、`event: error` 或断流不能当作完整答案。页面不会把 xtoken 写入 HTML、浏览器存储、Cookie、
+URL、Nginx 或日志。
+
+浏览器 Network 面板应能确认：请求为同源 POST、Origin 为 `https://agent.nianxx.com`、使用正确
+的公开 App ID、没有跨域失败，并且第二次请求包含上一轮返回的 `session_id`。如果出现 403，优先
+检查 `FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 是否包含精确 Origin；如果出现 404，检查页面开关和
+容器是否已 recreate；如果出现 401，重新输入正确的测试 xtoken。
+
 ### MCP 探活/初始化

 MCP 请求需要独立 Token，具体 JSON-RPC body 以 MCP Spec 为准：
@@ -166,13 +233,19 @@ curl --fail \
 完成 `nginx -t` 和 reload 后，应至少验证：

 1. `/health` 返回 200（如果保留可选 location）。
-2. 兼容对话首轮在正确 `xtoken` 下返回 SSE，末尾出现 `finish_reason: stop`；错误 Token 返回 401，且 Go 不会创建 SuperAgent Run。
-3. 兼容对话多轮使用返回的本地会话 ID；服务重启或会话失效后按契约返回会话不存在，不把 ID 当成 Provider Session。
-4. `/mcp` 使用独立 Bearer，错误或缺失 Bearer 返回 401；Nginx 没有注入任何 MCP Token。
-5. 未列出的路径（例如 `/api/chat`、`/api/v1/apps/other/completion` 和 `/anything`）返回 404。
+2. 页面开关关闭时 `/chat` 和 `/chat/` 均直接返回 404；开启且依赖完整时 `/chat` 返回 308、`/chat/` 返回 200 HTML，且两个资源路径返回 200。
+3. 兼容对话首轮在正确 `xtoken` 下返回 SSE，末尾出现 `finish_reason: stop`；错误 Token 返回 401，且 Go 不会创建 SuperAgent Run。
+4. 兼容对话多轮使用返回的本地会话 ID；服务重启或会话失效后按契约返回会话不存在，不把 ID 当成 Provider Session。
+5. `/mcp` 使用独立 Bearer，错误或缺失 Bearer 返回 401；Nginx 没有注入任何 MCP Token。
+6. 未列出的路径（例如 `/api/chat`、`/api/v1/apps/other/completion` 和 `/anything`）返回 404。

 如果 reload 后发现兼容路由、证书或 SSE 行为异常，先恢复上一个已验证的 Nginx 配置并保留 `nginx -t` 输出；不要通过放开 `location /`、关闭 Go 鉴权或把 Secret 写入 Nginx 来排障。

+如只需紧急关闭测试页面，不必改动 Nginx：将 Go 环境中的
+`FIRE_SAFETY_CHAT_PAGE_ENABLED` 改为 `false`，重新创建容器后确认 `/chat`、`/chat/` 和资源
+路径均直接返回 404。这样不会自动关闭兼容 completion；如果也要关闭对话 API，再按 Chat 配置和对应回滚流程
+处理。页面开关和 Nginx 路由均应保留清晰的变更记录。
+
 ## 7. 未确认事项

 - 目标公网机器的 Nginx 版本、include 层级、TLS 终止位置和证书续期方式；示例同时监听 80 做 HTTPS 跳转，安全组需按实际策略决定是否允许 80。