# 新 AI 助手部署与配置

新 AI 助手（`/ai-assistant` 页面）基于 AgentServer。设计见 `docs/ai-assistant-agentserver/`。本文是上线前需要**手动**完成的配置，按顺序执行。旧 Kiro 助手不受影响，不需要改动。

涉及的组件（同一台机器）：

| 组件 | 地址 | 说明 |
| --- | --- | --- |
| AgentServer | `http://127.0.0.1:8787`，后台 `/admin/` | systemd `agent-server`，用户 `agentsvc` |
| fwh-agent-mcp（只读） | `http://127.0.0.1:8091/mcp` | systemd `fwh-agent-mcp` |
| fwh-agent-mcp（写，二期） | `http://127.0.0.1:8092/mcp` | 可选，见第 2.3 节 |
| ToolBox 后端 | `127.0.0.1:8301`，路由前缀 `/api` | systemd `fwh-toolbox-server` |
| 对外入口 | Caddy → Apache `:8300` → `/fwh-toolbox/api` → `:8301/api` | 见第 6 节 |

## 1. 生成令牌

fwh-agent-mcp 用 Bearer 令牌鉴权，AgentServer 连接时携带。生成一个随机值，后面两处都要用：

```bash
openssl rand -hex 32
```

## 2. 部署 fwh-agent-mcp

### 2.1 配置 `service/.env`（部署目录 `/var/www/fwh-toolbox/server/.env`）

```
AGENT_MCP_TOKEN=<第 1 步生成的令牌>
AGENT_MCP_LISTEN=127.0.0.1:8091
AGENT_MCP_MAX_CONCURRENCY=8
AGENT_MCP_LOG_PATH=/var/www/fwh-toolbox/server/logs/agent-mcp.log
```

### 2.2 安装服务

```bash
cd service/cmd && ./deploy_agent_mcp.sh                         # 构建并拷贝到部署目录、重启服务
sudo cp deploy/systemd/fwh-agent-mcp.service /etc/systemd/system/  # 首次
sudo systemctl daemon-reload && sudo systemctl enable --now fwh-agent-mcp
curl -s http://127.0.0.1:8091/healthz                            # 返回 200 即可
journalctl -u fwh-agent-mcp -f                                   # 查看日志
```

### 2.3 写工具服务（二期，可选）

复制一份 unit 为 `fwh-agent-mcp-ops.service`，启动参数改为 `-set=ops -listen=127.0.0.1:8092`，令牌可以与只读服务相同或单独生成。

## 3. 同步资料库

AgentServer 开启了 `ProtectHome`，读不到 `/home` 下的 Wiki，需要拷贝到 `/srv/agent-server/knowledge/`：

```bash
deploy/scripts/sync_agent_knowledge.sh                    # 需要 sudo
AGENT_KB_DRY_RUN=y deploy/scripts/sync_agent_knowledge.sh # 预演
```

源目录可用环境变量覆盖（`WIKI_DOCS_DIR`、`DATA_KB_DIR`），说明见脚本头部。同步采用**手动**方式：Wiki 或数据知识库更新后，需要时再运行一次上面的命令，不配置定时任务。

注意：`docs/knowledge` 目前是空目录，数据知识库需要补充内容后才有意义。

## 4. 部署技能 `fwh-assistant`

技能源码在本仓库 `deploy/agent-assistant/skills/fwh-assistant/`（SKILL.md、references/、templates/company-template.pptx），不放进 AgentServer 仓库。

AgentServer 目前没有自定义技能的入口，需求见 AgentServer 仓库 `docs/design/12-custom-skills.md`。该功能实现后，把这个目录作为技能源导入（或打包为 zip 上传），在 Profile 中勾选 `custom-skills:fwh-assistant`。在此之前 Profile 不加载该技能。

## 5. AgentServer 后台配置

打开 `http://127.0.0.1:8787/admin/`。

1. **概览**：确认 Claude 已登录（未登录时点“登录”）。
2. **MCP 服务 › 添加**：

   | 项 | 只读服务 | 写服务（二期） |
   | --- | --- | --- |
   | 名称 | `fwh` | `fwhops` |
   | 标题 | FWH 业务数据 | FWH 业务操作 |
   | 传输 | 远程 HTTP | 远程 HTTP |
   | 地址 | `http://127.0.0.1:8091/mcp` | `http://127.0.0.1:8092/mcp` |
   | 请求头 | `Authorization` = `Bearer <令牌>` | 同左 |

   点“测试连接”能列出工具后保存。只读服务的工具策略保持默认“直接调用”；写服务保持“跟随权限模式”。名称必须用 `fwh` / `fwhops`，技能中的工具名依赖它。
3. **资料库 › 新增**：
   - `fwh-wiki`：路径 `/srv/agent-server/knowledge/fwh-wiki`，说明“FranklinWH 产品文档：硬件（aGate/aPower 等）、软件（PCS、调度、OTA 等）、系统（告警码表、事件列表、系统配置）”，只读；
   - `fwh-data-knowledge`：路径 `/srv/agent-server/knowledge/fwh-data-knowledge`，说明“ToolBox 数据字段与业务术语说明”，只读（`docs/knowledge` 有内容后再登记）。
4. **Profiles › 新建 `fwh-assistant`**：
   - 引擎 Claude，模型按需（如 sonnet）；
   - 权限模式“需审批”；
   - 技能：`report-conventions`；AgentServer 支持自定义技能后加勾 `custom-skills:fwh-assistant`（§4）；
   - 资料库：`fwh-wiki`（以及有内容后的 `fwh-data-knowledge`）；
   - MCP 服务：`fwh`；
   - 文件访问：受限（只写工作区）；
   - 系统提示词（可选）：“你是 FranklinWH ToolBox 的 AI 助手，回答 FranklinWH 储能产品与运维数据相关的问题。用中文回答。”
5. **Profiles › 复制为 `fwh-assistant-ops`**（二期）：在上一个基础上加勾 MCP 服务 `fwhops`。
6. **Playground**：选 `fwh-assistant`，问“站点 <SN> 的概况和最近 7 天告警”，确认工具能调用、不弹审批。
7. **API Keys › 签发**：名称 `fwh-toolbox`，可用 Profile 勾选 `fwh-assistant`（及 `fwh-assistant-ops`），默认 `fwh-assistant`。Key 只显示一次，记下来；记下两个 Profile 的 ID（`prf_…`，Profiles 页可见）。

## 6. ToolBox 后端配置

`/var/www/fwh-toolbox/server/.env` 增加：

```
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=                               # 可选：为空表示所有登录用户可用
```

重启：`sudo systemctl restart fwh-toolbox-server`。前端重新构建发布后，左侧菜单出现“AI 助手”。

## 7. 反向代理：关闭流式接口的缓冲

对话事件流的对外路径为 `/fwh-toolbox/api/agent/v1/sessions/<会话ID>/stream`（SSE）。中间任何一层缓冲都会导致回答一段一段地出现或很久才出现。

### 7.1 Apache（`/etc/apache2/sites-available/006-fwh-toolbox.conf`）

现有配置：

```apache
ProxyPass       /fwh-toolbox/api http://localhost:8301/api
ProxyPassReverse        /fwh-toolbox/api http://localhost:8301/api
```

在它**之前**加一条（Apache 按配置顺序匹配，必须放在前面）：

```apache
# 新 AI 助手事件流（SSE）：立即转发，长连接
ProxyPassMatch  "^/fwh-toolbox/api/agent/v1/sessions/([^/]+)/stream$" "http://localhost:8301/api/agent/v1/sessions/$1/stream" flushpackets=on timeout=3600
```

然后 `sudo apachectl configtest && sudo systemctl reload apache2`。

### 7.2 Caddy（`/etc/caddy/sites/002-lmt.zenpower.cc.caddy`、`001-link-ser.dev.caddy` 中的 fwh-toolbox 块）

Caddy 对 `text/event-stream` 响应默认会立即刷新，通常不用改。若仍有缓冲，把现有块：

```caddy
handle /fwh-toolbox/* {
        reverse_proxy localhost:8300
}
```

改为：

```caddy
handle /fwh-toolbox/* {
        reverse_proxy localhost:8300 {
                flush_interval -1
        }
}
```

然后 `sudo caddy reload --config /etc/caddy/Caddyfile --force`。

### 7.3 上传大小

AgentServer 默认单文件上限 50MB；ToolBox 后端代理与 Apache 不应小于这个值（Apache 默认不限制请求体；Fiber 的 `BodyLimit` 由后端配置）。

## 8. 验证清单

- [ ] `curl http://127.0.0.1:8091/healthz` 返回 200；AgentServer 后台 MCP 服务 `fwh` 状态正常
- [ ] Playground 用 `fwh-assistant` 能查询站点数据
- [ ] ToolBox 登录后左侧有“AI 助手”，能新建会话并得到流式回答（文字逐字出现）
- [ ] 回答中引用 Wiki 文档时能给出路径
- [ ] 多日功率流分析时，导出文件出现在工作区 `.agent/mcp/`，上下文中没有明细
- [ ] 用另一个账号打开别人的会话链接，提示无权访问