docs:补充AgentServer API Key签发与ToolBox配置写入、前端发布验证步骤

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

deploy/agent-assistant/SETUP.md

@@ -161,22 +161,62 @@ sudo rsync -a --delete ~/web/FranklinWH-ToolBox/deploy/agent-assistant/skills/ /
    - 系统提示词（可选）：“你是 FranklinWH ToolBox 的 AI 助手，回答 FranklinWH 储能产品与运维数据相关的问题。用中文回答。”
 5. **Profiles › 复制为 `fwh-assistant-ops`**（二期）：在上一个基础上加勾 MCP 服务 `fwhops`。
 6. **Playground**：选 `fwh-assistant`，问“站点 <SN> 的概况和最近 7 天告警”，确认时间线中出现 `custom-skills:fwh-assistant` 与 `fwh` 工具调用、不弹审批。
-7. **API Keys › 签发**：名称 `fwh-toolbox`，可用 Profile 勾选 `fwh-assistant`（及 `fwh-assistant-ops`），默认 `fwh-assistant`。Key 只显示一次，记下来；记下两个 Profile 的 ID（`prf_…`，Profiles 页可见）。
+7. **接入 › API Keys › 签发 Agent Key**（不是“签发 Bot Key”）：
+
+   | 项 | 填写 |
+   | --- | --- |
+   | 平台名称 | `fwh-toolbox` |
+   | 可用的 Profile | `fwh-assistant`（二期加 `fwh-assistant-ops`） |
+   | 默认 Profile | `fwh-assistant` |
+
+   - Key 的明文**只显示一次**，立即复制；丢失只能吊销后重新签发。
+   - 在 **能力 › Profiles** 记下各 Profile 的 ID（`prf_…`），第 6 节要用。
+   - 页面提示的“设置 › 安全”中的 CORS 来源**不需要配置**：浏览器只请求 ToolBox 后端，由后端代理访问 AgentServer，Key 不出后端。
 
 ## 6. ToolBox 后端配置
 
-主服务的 `/var/www/fwh-toolbox/server/config.env` 增加（不要新建 `.env`：程序优先读取 `.env`，存在时 `config.env` 整个不再生效）：
+主服务的 `/var/www/fwh-toolbox/server/config.env` 增加以下配置（不要新建 `.env`：程序优先读取 `.env`，存在时 `config.env` 整个不再生效）：
 
-```
+| 配置项 | 说明 |
+| --- | --- |
+| `AGENT_ENABLED` | `true` 开启；未开启时“AI 助手”页面显示暂未开放，`/agent/*` 接口返回 403 |
+| `AGENT_SERVER_URL` | `http://127.0.0.1:8787` |
+| `AGENT_SERVER_API_KEY` | 第 5 节第 7 步签发的 Key，只放后端 |
+| `AGENT_PROFILE_DEFAULT` | `fwh-assistant` 的 ID（`prf_…`）；留空时使用 Key 的默认 Profile |
+| `AGENT_PROFILE_BY_ROLE` | 可选：角色到 Profile，如 `ops:prf_yyy,admin:prf_zzz`，按顺序取第一个命中的 |
+| `AGENT_ALLOWED_ROLES` | 可选：允许使用的角色，逗号分隔；为空表示所有登录用户 |
+
+### 6.1 写入配置
+
+Key 不要贴到聊天、工单或命令行参数中。在服务器上执行下面的命令，粘贴 Key 时屏幕不回显：
+
+```bash
+cd /var/www/fwh-toolbox/server
+grep -n '^AGENT_\(ENABLED\|SERVER\|PROFILE\|ALLOWED\)' config.env && echo "已有 AGENT_ 配置，请先检查，避免重复"
+read -rsp "AgentServer API Key: " KEY; echo
+read -rp  "fwh-assistant 的 Profile ID (prf_...): " PRF
+cat >> config.env <<EOF
+
+# ---------- 新 AI 助手（AgentServer）----------
 AGENT_ENABLED=true
 AGENT_SERVER_URL=http://127.0.0.1:8787
-AGENT_SERVER_API_KEY=ask_xxx                       # 第 5.7 步签发的 Key
-AGENT_PROFILE_DEFAULT=prf_xxx                      # fwh-assistant 的 ID
-AGENT_PROFILE_BY_ROLE=                             # 可选：角色:ProfileID，逗号分隔，如 ops:prf_yyy
-AGENT_ALLOWED_ROLES=                               # 可选：为空表示所有登录用户可用
+AGENT_SERVER_API_KEY="$KEY"
+AGENT_PROFILE_DEFAULT=$PRF
+AGENT_PROFILE_BY_ROLE=
+AGENT_ALLOWED_ROLES=
+EOF
+unset KEY PRF
+sudo systemctl restart fwh-toolbox-server
 ```
 
-重启：`sudo systemctl restart fwh-toolbox-server`。前端重新构建发布后，左侧菜单出现“AI 助手”。
+更换 Key 时直接编辑 `config.env` 中的 `AGENT_SERVER_API_KEY` 后重启；旧 Key 在 AgentServer 后台吊销。
+
+### 6.2 发布前端并验证
+
+1. 前端用包含新助手的分支重新构建并发布：`pnpm build && pnpm install`（`install` 是本项目的发布脚本，拷贝到 `/var/www/fwh-toolbox/fwh-toolbox/`）。
+2. `journalctl -u fwh-toolbox-server -n 30 --no-pager` 无报错。
+3. 登录 ToolBox，打开左侧菜单“AI 助手”；新建会话、发一条消息，回答逐字流式出现。回答成段出现时按第 7 节关闭代理缓冲。
+4. 页面显示“AI 助手暂未开放”：后端 `/agent/config` 返回未开放。检查 `AGENT_ENABLED=true`、当前用户的角色是否在 `AGENT_ALLOWED_ROLES` 中（为空则不限制），以及是否已重启后端。菜单本身是静态的，不受这些配置影响。
 
 ## 7. 反向代理：关闭流式接口的缓冲
 

deploy/config.env.example

@@ -104,7 +104,7 @@ KIRO_RUN_AS_USER=jerry-remote
 KIRO_HOME=/home/jerry-remote
 
 # ---------- 新 AI 助手（AgentServer，可选）----------
-# 见 docs/ai-assistant-agentserver/technical-design.md §3.2；未开启时菜单与 /agent/* 接口不可用
+# 见 docs/ai-assistant-agentserver/technical-design.md §3.2；未开启时 AI 助手页面显示暂未开放、/agent/* 接口返回 403
 # AGENT_ENABLED=true
 # AGENT_SERVER_URL=http://127.0.0.1:8787
 # TODO: [必填] AgentServer 后台签发的平台 API Key（只放后端，勿提交真实值）