增加调试前端页面

docs/workflows/user-chat.md

@@ -11,13 +11,44 @@
 
 客户端只有在收到 `done` 后才把本轮标记为成功，并保存 `conversation_id`。
 
-## 2. 后续对话
+## 2. 受控测试页面
+
+当 `FIRE_SAFETY_CHAT_PAGE_ENABLED=true` 时，Go 服务提供 `GET /chat` 和 `GET /chat/`。页面只
+用于测试，不是新的对话协议或生产用户入口；关闭开关时两个路径都返回 404。Nginx 可以保留这
+两个精确反代路径，最终是否可用由 Go 开关决定。
+
+页面与既有第三方客户端使用完全相同的兼容接口：
+
+```text
+页面 GET /chat/
+  -> 同源 POST /api/v1/apps/<FIRE_SAFETY_CHAT_COMPAT_APP_ID>/completion
+  -> xtoken + input.prompt + parameters
+  -> event: result SSE
+```
+
+页面打开后由用户手动输入受控测试 `xtoken`。页面不在 HTML、JavaScript 常量、Cookie、URL、
+localStorage 或 sessionStorage 中嵌入/保存 Token，也不把 Token 发送到除同源 completion 之外
+的地址；页面只在当前 JavaScript 内存中使用它。首轮返回的 `output.session_id` 也只保存在页面
+内存中，并在同一页面的后续请求中作为 `input.session_id` 发送。刷新、关闭或新开页面都会丢弃
+Token 和 Session。
+
+浏览器页面的 Origin 是 `https://agent.nianxx.com`，所以服务器配置
+`FIRE_SAFETY_CHAT_ALLOWED_ORIGINS` 必须包含该精确值，不得用 `*`。页面 GET 本身不要求 Token，
+但 completion 仍由 Go 校验 `xtoken`；静态测试 Token 不是最终用户认证。
+
+页面验收时打开 `https://agent.nianxx.com/chat/`，输入测试 Token 和不含敏感信息的问题。浏览器
+Network 应显示同源 POST 到精确 app ID 的 completion 路径，Request Headers 含 `xtoken`，请求
+体为兼容 JSON，响应为 `event: result` SSE。只有 `output.finish_reason=stop` 才算本轮成功；再
+发送第二个问题时，应在第二次请求中看到上一轮返回的 `session_id` 被放入 `input.session_id`。不要把初始 `finish_reason=null` 或
+断流内容当作最终答案。
+
+## 3. 后续对话
 
 后续请求同时发送 `message` 和前一轮保存的 `conversation_id`。成功流中的 `conversation` 事件返回 `reused=true`，说明复用了原 SuperAgent Session 上下文。
 
 同一对话在收到 `done` 或终止 `error` 前不得再次提交。若服务端返回 `CHAT_CONVERSATION_BUSY`，客户端应保留当前流并稍后重试，不能自动改用同一个问题创建多轮并发 Run。
 
-## 3. 失败处理
+## 4. 失败处理
 
 - HTTP JSON 错误：SSE 尚未开始；按 HTTP 状态和 `error.code` 处理。
 - SSE `error`：流已经开始，但本轮没有可信最终回答；不得把此前进度当作答案。
@@ -25,7 +56,7 @@
 - 上游超时、协议错误、Run 失败或客户端中途断开：当前实现会使会话映射失效，以免继续复用可能仍有活动 Run 的 Provider Session。
 - 网络断开且没有看到 `done`：结果未知；首版不自动重放原消息，避免重复 Run。
 
-## 4. curl 联调
+## 5. curl 联调
 
 先把 `.env` 显式加载到当前 shell，再启动服务；Go 程序不会自动读取 `.env`：
 
@@ -60,7 +91,7 @@ curl -N \
 
 浏览器前端还必须把其精确 Origin 加入 `FIRE_SAFETY_CHAT_ALLOWED_ORIGINS`，例如 `http://localhost:5173`。静态 Chat Bearer 会被浏览器用户看到，因此只适用于受控联调，不能直接作为公网最终用户鉴权。
 
-## 5. 既有 DashScope 风格客户端
+## 6. 既有 DashScope 风格客户端
 
 设置 `FIRE_SAFETY_CHAT_COMPAT_APP_ID` 后，同一个 Chat Service 还会注册：
 
@@ -80,4 +111,4 @@ curl -N \
 
 兼容流先返回 `finish_reason: "null"` 和本地 `session_id`，严格成功后返回 `finish_reason: "stop"` 与最终 `text`。后续轮次把该 `session_id` 放入 `input.session_id`。客户端不得使用 URL 中的 App ID、静态 token 或 session ID推断身份与权限，也不得把未出现 `stop` 的断流结果当作成功答案。
 
-公网 Nginx 示例和完整 curl 见 [`../project/operations/nginx-public-entry.md`](../project/operations/nginx-public-entry.md)。兼容字段的唯一项目契约见 [`../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md`](../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md)。
+公网 Nginx 示例和完整 curl 见 [`../project/operations/nginx-public-entry.md`](../project/operations/nginx-public-entry.md)。兼容字段的唯一项目契约见 [`../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md`](../specs/fire-safety-ymd-dashscope-compatible-chat-v1.md)。页面开关、Docker 重建、浏览器验收和回滚见 [`../specs/fire-safety-ymd-chat-page-v1.md`](../specs/fire-safety-ymd-chat-page-v1.md)。