新 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 连接时携带。生成一个随机值，后面两处都要用：

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 安装服务

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/：

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/。

概览：确认 Claude 已登录（未登录时点“登录”）。
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，技能中的工具名依赖它。

资料库 › 新增：
- 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 有内容后再登记）。
Profiles › 新建 fwh-assistant：
- 引擎 Claude，模型按需（如 sonnet）；
- 权限模式“需审批”；
- 技能：report-conventions；AgentServer 支持自定义技能后加勾 custom-skills:fwh-assistant（§4）；
- 资料库：fwh-wiki（以及有内容后的 fwh-data-knowledge）；
- MCP 服务：fwh；
- 文件访问：受限（只写工作区）；
- 系统提示词（可选）：“你是 FranklinWH ToolBox 的 AI 助手，回答 FranklinWH 储能产品与运维数据相关的问题。用中文回答。”
Profiles › 复制为 fwh-assistant-ops（二期）：在上一个基础上加勾 MCP 服务 fwhops。
Playground：选 fwh-assistant，问“站点的概况和最近 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`）

现有配置：

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

在它之前加一条（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 响应默认会立即刷新，通常不用改。若仍有缓冲，把现有块：

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

改为：

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/，上下文中没有明细
用另一个账号打开别人的会话链接，提示无权访问

SETUP.md 7.9 KB 히스토리 Raw