docs:删除旧AI助手（Kiro/ACP）文档，清理部署与设计文档中的旧助手和旧MCP引用

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

deploy/CHECKLIST.md

@@ -21,7 +21,7 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 | ☐ | **PostgreSQL 业务口令** | `init_databases.sh:PG_FWH_PASSWORD` + `config.env:POSTGRES_DSN` | `fwh_toolbox` 角色密码，两处必须**完全一致** |
 | ☐ | **MinIO 管理员账户** | `install_deps.sh` / `provision_minio.sh` 的 `MINIO_ROOT_USER/PASSWORD` | 勿用默认 `minioadmin/minioadmin` |
 | ☐ | **MinIO 业务密钥（后端）** | `config.env:MINIO_ACCESS_KEY / MINIO_SECRET_KEY` + `provision_minio.sh:MINIO_ACCESS_KEY/SECRET_KEY` | 账号 `fwh-toolbox`，写 `fwh-toolbox*` 桶；两处须一致 |
-| ☐ | **MinIO AI 密钥（MCP）** | `config.mcp.env:MINIO_ACCESS_KEY / MINIO_SECRET_KEY` + `provision_minio.sh:MINIO_AI_ACCESS_KEY/SECRET_KEY` | 账号 `fwh-toolbox-ai`，写 `fwh-toolbox-ai*` 桶；默认账号=密码 |
+| ☐ | **MinIO AI 密钥（fwh-agent-mcp）** | `config.agent-mcp.env:MINIO_ACCESS_KEY / MINIO_SECRET_KEY` + `provision_minio.sh:MINIO_AI_ACCESS_KEY/SECRET_KEY` | 账号 `fwh-toolbox-ai`，对 `fwh-toolbox` 桶只读；默认账号=密码。部署 AI 助手时才需要 |
 | ☐ | **postgres 超级用户密码** | `install_pgadmin.sh:POSTGRES_PASSWORD` | 供 pgAdmin4 登录连接；勿用默认占位 |
 | ☐ | **pgAdmin4 登录密码** | `install_pgadmin.sh:PGADMIN_PASSWORD` | Web 登录口令（邮箱 `liang_jlyx@163.com`） |
 | ☐ | **FWH 生产账号** | `config.env:FWH_USER / FWH_PASSWORD` | 密码填明文，后端自动 MD5 |
@@ -58,7 +58,7 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 | # | 项目 | 默认 | 位置 |
 |---|------|------|------|
 | ☐ | 部署根目录 | `/var/www/fwh-toolbox` | `setup.sh` / `deploy.sh:DEPLOY_ROOT` |
-| ☐ | 后端运行用户 | 当前用户 | `RUN_USER` / `config.env:KIRO_RUN_AS_USER` |
+| ☐ | 后端运行用户 | 当前用户 | `RUN_USER` |
 | ☐ | 后端端口 | `8301` | `config.env:APP_PORT` |
 | ☐ | Asynqmon 端口 | `8302` | `config.env:ASYNQMON_PORT` |
 | ☐ | MinIO 端口 | `9198`/`9199` | `install_deps.sh` |
@@ -66,9 +66,7 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 | ☐ | 运行环境 | `dev` | `config.env:APP_ENV`（生产改 `pro`） |
 | ☐ | Mongo 库名 | `FwhToolboxDb` | `config.env:MONGO_DSN`（开发 `FwhToolboxDbDev`） |
 | ☐ | MinIO bucket | `fwh-toolbox` | `config.env:MINIO_BUCKET_NAME`（与建桶一致） |
-| ☐ | MinIO AI bucket | `fwh-toolbox-ai-file` | `provision_minio.sh:MINIO_AI_BUCKET` / `filestore.AIFileBucket` |
 | ☐ | pgAdmin4 端口 | `5480`（仅绑 `127.0.0.1`） | `install_pgadmin.sh:PGADMIN_PORT/PGADMIN_BIND` |
-| ☐ | Kiro 用户/HOME | `jerry-remote` | `config.env:KIRO_RUN_AS_USER/KIRO_HOME` |
 
 ### A6. 可选功能
 
@@ -76,6 +74,7 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 |---|------|------|------|
 | ☐ | FWH 测试环境 | `config.env:FWH_TEST_*` + `server/cert/test/` | 连测试服才填 |
 | ☐ | Plane 集成 | `config.env:PLANE_*` | 启用反馈/任务同步才填 |
+| ☐ | AI 助手 | `config.env:AGENT_*` + `config.agent-mcp.env` | 启用 `/ai-assistant` 才需要，步骤见 `deploy/agent-assistant/SETUP.md` |
 
 ---
 
@@ -108,7 +107,7 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 - ☐ `PG_FWH_PASSWORD='强口令' deploy/scripts/init_databases.sh`（PG 建表 + Mongo/Redis 检查，不含 MinIO）
 - ☐ 验证：`psql -d fwh_toolbox_db -c "\dt alarm_snapshot.*"`
 - ☐ 创建 MinIO 桶 + 业务账号与策略：`MINIO_ROOT_USER=... MINIO_ROOT_PASSWORD=... MINIO_SECRET_KEY='强口令' MINIO_AI_SECRET_KEY='强口令' deploy/scripts/provision_minio.sh`
-- ☐ 验证：`mc ls fwhlocal/`（桶 `fwh-toolbox`、`fwh-toolbox-ai-file`）、`mc admin user list fwhlocal`（用户 `fwh-toolbox`、`fwh-toolbox-ai`）
+- ☐ 验证：`mc ls fwhlocal/`（桶 `fwh-toolbox`）、`mc admin user list fwhlocal`（用户 `fwh-toolbox`、`fwh-toolbox-ai`）
 
 ### B4.1 pgAdmin4（可选，数据库 Web 管理）
 
@@ -120,7 +119,6 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 ### B5. 配置后端
 
 - ☐ `cp deploy/config.env.example service/config.env`
-- ☐ `cp deploy/config.mcp.env.example service/config.mcp.env`（MCP 用 `fwh-toolbox-ai` 账号）
 - ☐ 按 A 节逐项填写 `config.env`（搜索文件内 `TODO`）
 - ☐ 放置 MQTT 证书到 `service/cert/pro/`（及 `test/`）
 
@@ -155,6 +153,6 @@ grep -rn 'TODO' deploy/scripts deploy/config.env.example
 - ☐ `config.env` 权限收紧，且**未**提交到 Git（含密钥/证书）
 - ☐ 数据库/MinIO/Redis 仅监听本地或受信网段
 - ☐ pgAdmin4（`5480`）未暴露公网；postgres 超级用户密码仅用于受控管理
-- ☐ MinIO 业务账号最小权限：后端用 `fwh-toolbox`、MCP 用 `fwh-toolbox-ai`，未用 root 跑业务
+- ☐ MinIO 业务账号最小权限：后端用 `fwh-toolbox`、fwh-agent-mcp 用 `fwh-toolbox-ai`，未用 root 跑业务
 - ☐ Caddy systemd 服务含明文 DNS token，权限 600 且未提交仓库
 - ☐ 备份策略：PostgreSQL（`pg_dump`）、MongoDB（`mongodump`）、MinIO 数据目录

deploy/DEPLOYMENT.md

@@ -38,7 +38,6 @@
 - [ ] 部署根目录 `DEPLOY_ROOT`（默认 `/var/www/fwh-toolbox`）与运行用户 `RUN_USER`。
 - [ ] 端口：后端 `APP_PORT=8301`、Asynqmon `8302`、MinIO `9198/9199`、Casdoor `8010`。
 - [ ] `APP_ENV`（pro/dev）、`MONGO_DSN` 库名（生产 `FwhToolboxDb`）、`MINIO_BUCKET_NAME`。
-- [ ] `KIRO_RUN_AS_USER`/`KIRO_HOME` 改成目标机实际用户。
 
 **可选（用到对应功能才填）**
 
@@ -80,7 +79,7 @@ chmod +x start.sh
 ```
 
 `start.sh` 会显示一个菜单：既可选「全流程一键部署」，也可只跑某个**单项功能**
-（依赖 / 初始化 DB / MinIO 账号 / pgAdmin4 / Casdoor / Caddy / Kiro CLI / 构建部署前后端）。
+（依赖 / 初始化 DB / MinIO 账号 / pgAdmin4 / Casdoor / Caddy / 构建部署前后端）。
 **无论全流程还是单项，都同样支持本地与远程（进入后会先询问 local/remote）。**
 
 单项也可用命令行直达（跳过菜单），本质是给向导传 `--only`：
@@ -92,7 +91,7 @@ chmod +x start.sh
 ./start.sh --help                # 查看全部可选项
 ```
 
-> 可选项：`deps casdoor initdb minioacct pgadmin caddy kiro deploy`。
+> 可选项：`deps casdoor initdb minioacct pgadmin caddy deploy`。
 > 单项模式仍会询问该步骤所需的参数（如 Caddy 的域名/DNS token）。
 
 向导流程：
@@ -126,12 +125,12 @@ chmod +x start.sh
                         │   /fwh-toolbox/api/*  → 后端 API (:8301) │
                         └───────────────┬─────────────────────────┘
                                         │
-        ┌───────────────────────────────┼──────────────────────────────┐
-        ▼                               ▼                              ▼
-┌───────────────┐            ┌────────────────────┐          ┌──────────────────┐
-│ 前端静态文件   │            │ Go 后端            │          │ fwh-mcp-server   │
-│ Apache :8300  │            │ fwh-toolbox-server │          │ (MCP，可选)       │
-│ /var/www/...  │            │ localhost:8301     │          └──────────────────┘
+        ┌───────────────────────────────┤
+        ▼                               ▼
+┌───────────────┐            ┌────────────────────┐
+│ 前端静态文件   │            │ Go 后端            │
+│ Apache :8300  │            │ fwh-toolbox-server │
+│ /var/www/...  │            │ localhost:8301     │
 └───────────────┘            │ Asynqmon :8302     │
                              └─────────┬──────────┘
                                        │
@@ -180,8 +179,9 @@ chmod +x start.sh
 ├── fwh-toolbox/          # 前端构建产物（dist/* 拷贝到此）
 └── server/               # 后端运行目录
     ├── fwh-toolbox-server    # 后端主程序二进制
-    ├── fwh-mcp-server        # MCP 服务二进制（可选）
+    ├── fwh-agent-mcp         # AI 助手 MCP 服务二进制（可选，见 deploy/agent-assistant/SETUP.md）
     ├── config.env            # 后端配置（由 config.env.example 复制修改）
+    ├── config.agent-mcp.env  # fwh-agent-mcp 配置（可选）
     └── cert/                 # FWH MQTT 证书 (pro/ 与 test/)
 ```
 
@@ -355,12 +355,11 @@ MinIO 采用「一个管理员 + 两个业务账号」的划分，业务账号
 | 账号 | 用途 | 对 `fwh-toolbox*` 桶 | 对 `fwh-toolbox-ai*` 桶 | 对其余桶 |
 |------|------|----------------------|-------------------------|----------|
 | `MINIO_ROOT_USER`（root） | 建桶 / 建用户 / 设策略（全局管理） | 全权 | 全权 | 全权 |
-| `fwh-toolbox` | **后端主服务**（`config.env`） | 读写（含删除） | 读写（含删除）※ | 只读 |
-| `fwh-toolbox-ai` | **MCP Server**（`config.mcp.env`） | 只读 | 读写（含删除） | 只读 |
+| `fwh-toolbox` | **后端主服务**（`config.env`） | 读写（含删除） | 读写（含删除） | 只读 |
+| `fwh-toolbox-ai` | **AI 助手 MCP 服务 fwh-agent-mcp**（`config.agent-mcp.env`） | 只读 | 读写（含删除） | 只读 |
 
-> ※ `fwh-toolbox-ai-file` 同时匹配 `fwh-toolbox*` 与 `fwh-toolbox-ai*` 两个前缀，
-> 因此后端账号 `fwh-toolbox` 对 AI 桶也有写权限——这是前缀通配策略的必然结果。
-> MCP 工具本身仅做只读访问（`list/read object`），只读权限即可满足。
+> 目前没有 `fwh-toolbox-ai*` 前缀的桶。fwh-agent-mcp 只读取 `fwh-toolbox` 桶中的故障录波文件
+> （`fault-record/` 前缀），只读权限即可满足。
 
 两个业务账号由脚本 `deploy/scripts/provision_minio.sh` 用 root 通过 `mc admin`
 创建（建桶 → 建策略 → 建用户 → 绑定策略，均幂等）：
@@ -375,11 +374,11 @@ MINIO_SECRET_KEY='业务强密码' MINIO_AI_SECRET_KEY='AI强密码' \
 
 - 后端 `config.env` 的 `MINIO_ACCESS_KEY/MINIO_SECRET_KEY` = `provision_minio.sh` 的
   `MINIO_ACCESS_KEY/MINIO_SECRET_KEY`（默认 `fwh-toolbox`）；
-- MCP `config.mcp.env` 的 `MINIO_ACCESS_KEY/MINIO_SECRET_KEY` = `provision_minio.sh` 的
+- fwh-agent-mcp `config.agent-mcp.env` 的 `MINIO_ACCESS_KEY/MINIO_SECRET_KEY` = `provision_minio.sh` 的
   `MINIO_AI_ACCESS_KEY/MINIO_AI_SECRET_KEY`（默认账号=密码=`fwh-toolbox-ai`）。
 
-> `setup.sh` 会分别生成 `config.env`（后端）与 `config.mcp.env`（MCP）两份配置，
-> MCP 那份的 MinIO 凭据默认使用 `fwh-toolbox-ai`。
+> `setup.sh` 只生成后端的 `config.env`；`config.agent-mcp.env` 按
+> `deploy/agent-assistant/SETUP.md` 第 1.1 节手动创建。
 
 ### 4.5 远端 MySQL
 
@@ -459,7 +458,7 @@ MINIO_AI_SECRET_KEY='AI账号强密码' \
 ```
 
 完成后确保：`config.env` 用 `fwh-toolbox`（`MINIO_ACCESS_KEY/SECRET_KEY`），
-`config.mcp.env` 用 `fwh-toolbox-ai`（默认账号=密码=`fwh-toolbox-ai`）。
+`config.agent-mcp.env` 用 `fwh-toolbox-ai`（默认账号=密码=`fwh-toolbox-ai`）。
 
 ### 5.3 MongoDB
 
@@ -528,10 +527,9 @@ cp deploy/config.env.example service/config.env
 ```bash
 cd service
 GOOS=linux GOARCH=amd64 go build -o fwh-toolbox-server ./
-GOOS=linux GOARCH=amd64 go build -o fwh-mcp-server ./cmd/mcp/
 
 sudo mkdir -p /var/www/fwh-toolbox/server
-sudo mv fwh-toolbox-server fwh-mcp-server /var/www/fwh-toolbox/server/
+sudo mv fwh-toolbox-server /var/www/fwh-toolbox/server/
 sudo cp config.env /var/www/fwh-toolbox/server/config.env
 # 拷贝证书目录
 sudo cp -r cert /var/www/fwh-toolbox/server/
@@ -564,7 +562,7 @@ sudo systemctl enable --now fwh-toolbox-server
 sudo systemctl status fwh-toolbox-server --no-pager
 ```
 
-> `User` 应与配置的 `KIRO_RUN_AS_USER` 一致，并保证该用户对
+> `User` 应为部署时的运行用户（`RUN_USER`），并保证该用户对
 > `WorkingDirectory` 及 `cert/`、`function/` 等目录有读写权限。
 
 ### 7.3 一键脚本
@@ -897,7 +895,7 @@ service/cmd/showTodayErrorLog.sh
 | `deploy/scripts/deploy.sh` | 构建并部署前端/后端（`all`/`frontend`/`backend`） |
 | `deploy/config.env.example` | 后端配置模板 |
 | `service/cmd/deploy_toolbox.sh` | 仅构建部署后端主程序（历史脚本） |
-| `service/cmd/deploy_mcp.sh` | 仅构建部署 MCP（历史脚本） |
+| `service/cmd/deploy_agent_mcp.sh` | 构建部署 AI 助手 MCP 服务 fwh-agent-mcp（见 `deploy/agent-assistant/SETUP.md`） |
 
 ### 全新服务器最短部署路径
 

deploy/agent-assistant/SETUP.md

@@ -1,6 +1,6 @@
 # 新 AI 助手部署与配置
 
-新 AI 助手（`/ai-assistant` 页面）基于 AgentServer。设计见 `docs/ai-assistant-agentserver/`。本文是上线前需要**手动**完成的配置，按顺序执行。旧 Kiro 助手不受影响，不需要改动。
+新 AI 助手（`/ai-assistant` 页面）基于 AgentServer。设计见 `docs/ai-assistant-agentserver/`。本文是上线前需要**手动**完成的配置，按顺序执行。
 
 涉及的组件（同一台机器）：
 
@@ -18,14 +18,13 @@
 | --- | --- | --- |
 | `config.env` | 主服务 `fwh-toolbox-server` | 第 6 节的 `AGENT_*` 加在这里。**不要新建 `.env`**：程序优先读取 `./.env`，存在时 `config.env` 整个不再生效 |
 | `config.agent-mcp.env` | `fwh-agent-mcp` | 独立配置（第 1.1 节），不读 `config.env` |
-| `config.mcp.env` | 旧 Kiro MCP | 与新助手无关 |
 | `emspara.db` | 主服务、`fwh-agent-mcp` | EMS 参数（PID / VID）字典。部署脚本由 EMS 头文件生成并拷贝到这里（`service/cmd/deploy_emspara.sh`，`deploy_toolbox.sh` 与 `deploy_agent_mcp.sh` 都会调用）；进程启动时加载到 Redis，Redis 中没有字典时自动重新加载。缺失时 `ems_param_lookup` 查不到任何编号 |
 
 ## 1. 部署 fwh-agent-mcp
 
 ### 1.1 创建独立配置 `config.agent-mcp.env`
 
-fwh-agent-mcp 只读自己的配置文件（`-config` 可指定，默认工作目录下的 `./config.agent-mcp.env`），文件缺失时拒绝启动。它只需要数据库与 Redis、FWH 生产与测试 API、Plane Web，这些值与 `config.env` 相同，可以照抄；令牌新生成。
+fwh-agent-mcp 只读自己的配置文件（`-config` 可指定，默认工作目录下的 `./config.agent-mcp.env`），文件缺失时拒绝启动。它只需要数据库与 Redis、FWH 生产与测试 API、Plane Web、MinIO（只读故障录波文件），这些值除 MinIO 账号外与 `config.env` 相同，可以照抄；令牌新生成。MinIO 使用只读账号 `fwh-toolbox-ai`（对 `fwh-toolbox` 桶只读，由 `deploy/scripts/provision_minio.sh` 创建），不要用主服务的 `fwh-toolbox` 账号。
 
 下面的命令以示例文件为模板，从 `config.env` 原样复制同名配置，并生成新令牌（不在终端输出任何值）：
 
@@ -43,6 +42,8 @@ awk -v token="$TOKEN" '
 grep -n CHANGE_ME config.agent-mcp.env | cut -d= -f1   # 应无输出；有输出的项需要手动填写
 ```
 
+上面的命令会把 `config.env` 中的 `MINIO_ACCESS_KEY`/`MINIO_SECRET_KEY`（主服务账号）一并复制过来，生成后改回 `fwh-toolbox-ai` 账号及其密码。
+
 也可以手动 `cp deploy/config.agent-mcp.env.example /var/www/fwh-toolbox/server/config.agent-mcp.env` 后按 `CHANGE_ME` 逐项填写，令牌用 `openssl rand -hex 32` 生成。
 
 文件权限保持 `600`（服务以 root 运行，可以读取）。

deploy/kiro/skills/fwh-toolbox-rules/SKILL.md

@@ -1,48 +0,0 @@
----
-name: fwh-toolbox-rules
-description: FranklinWH 工具箱平台的操作规则集。当涉及以下任一场景时必须使用本技能并加载对应参考规则：(1) 通过 storage_file_* 工具读取/写入/上传文件，或向用户提供文件下载、导出、生成报告；(2) 通过 @officecli 工具批量写入 .xlsx/.docx/.pptx；(3) 使用公司 PPT 模板生成演示文稿（用户提到“公司模板/company template/用模板生成 PPT”）；(4) 需要用 Python3 运行自定义脚本做数据处理/计算/转换（只能通过沙箱执行器 fwh-pyrun 运行）。本技能规定这些操作的强制参数、输出标记、批量写入方式、模板路径与 Python3 沙箱运行方式。
----
-
-# FranklinWH 工具箱操作规则
-
-本技能汇总平台在“文件输出、officecli 批量写入、PPT 模板、Python3 沙箱执行”四类操作上的强制规则。按下面的对照表，在对应操作前加载相应参考文件并严格遵循。
-
-## 何时加载哪份规则
-
-| 操作场景 | 必读参考 |
-| --- | --- |
-| 任何 `storage_file_write` / `storage_file_upload` / `storage_file_read*` / `storage_file_list` 调用；给用户下载/导出/生成报告 | `references/file-output-rules.md` |
-| 通过 `@officecli` 批量写入 `.xlsx` / `.docx` / `.pptx` | `references/officecli-batch-rules.md` |
-| 使用公司 PPT 模板生成演示文稿 | `references/ppt-template-rules.md` |
-| 需要用 Python3 做自定义数据处理/计算/转换（现成工具无法覆盖时） | `references/python-rules.md` |
-
-## 文件输出：两条必守硬约束（无条件遵守，无需展开也要执行）
-
-1. 调用 `storage_file_write` / `storage_file_upload` **必须**传 `userId` 和 `sessionId`，取自用户消息开头的 `[context] userId=xxx sessionId=xxx` 行。
-2. 写入/上传**成功后**，**必须**在回复中独占一行输出下载标记（不要放进代码块）：
-   ```
-   $$FILE_DOWNLOAD:{"key":"<返回的key>","fileName":"<文件名>","size":<文件大小>}$$
-   ```
-   完整的读/写策略、判断标准与示例见 `references/file-output-rules.md`。
-
-## officecli 批量写入：核心红线
-
-- **永远不要**用 `--input -`（stdin），MCP 环境无 stdin 管道，会永久卡住。
-- 批量首选 `batch <file> --commands '[...]' --json` 一次内联完成；仅超大批量才用 `--input <真实文件路径>`。
-- 详细决策顺序与转义规则见 `references/officecli-batch-rules.md`。
-
-## PPT 模板：要点
-
-- 用户提到“公司模板 / company template / 用模板生成 PPT”时，使用 `__KIRO_HOME__/templates/company-template.pptx`，先拷贝到 `/tmp/fwh-toolbox-agent/ppt/` 再编辑。
-- 布局/配色/首尾页规则见 `references/ppt-template-rules.md`。
-
-## Python3 沙箱执行：核心红线
-
-- 仅当现成工具（`@fwh-tools` / `@officecli` / `knowledge`）**无法完成**时才写 Python3。
-- Python3 **只能**通过沙箱执行器运行，命令固定为：
-  `__KIRO_HOME__/bin/fwh-pyrun /tmp/fwh-toolbox-agent/scripts/<name>.py [参数...]`。
-- **禁止**直接 `python3` / `python -c` / 命令拼接 / 管道（配置层会拒绝）。
-- 脚本只能读写 `/tmp/fwh-toolbox-agent/` 内文件、**无网络**、**仅标准库**；输入先用
-  `storage_file_read_to_local` 下载进沙箱，产物交付用户走 `storage_file_upload` + 下载标记。
-- 资源限额：CPU ≤ 30s、内存 ≤ 1GB、总运行 ≤ 60s，超限即被终止。
-- 完整规则见 `references/python-rules.md`。

deploy/kiro/skills/fwh-toolbox-rules/references/file-output-rules.md

@@ -1,116 +0,0 @@
-# 文件输出规则（完整）
-
-## 调用规范
-
-调用 `storage_file_write` 或 `storage_file_upload` 时，**必须**填写 `userId` 和 `sessionId` 参数：
-
-- `userId`：从消息开头的 `[context] userId=xxx` 中获取
-- `sessionId`：从消息开头的 `[context] sessionId=xxx` 中获取
-- 每条用户消息开头都会包含 `[context]` 行，请从中提取这两个值
-
-## 文件下载事件
-
-当你通过 `storage_file_write` 或 `storage_file_upload` 工具成功写入/上传文件后，**必须**在回复中输出以下标记，让前端生成下载按钮：
-
-$$FILE_DOWNLOAD:{"key":"<返回的key>","fileName":"<文件名>","size":<文件大小>}$$
-
-### 规则
-
-1. 标记必须独占一行
-2. 使用返回的 `key`、`fileName`、`size` 字段原样填入
-3. 不要将标记放在代码块（```）内
-4. 一次回复中可输出多个标记（多个文件）
-5. 标记前后可以正常写文字说明
-
-### 示例
-
-调用 `storage_file_write`：
-
-```json
-{
-  "fileName": "report.csv",
-  "content": "id,name,value\n1,test,100",
-  "userId": "jerry",
-  "sessionId": "sess_abc123"
-}
-```
-
-返回结果：
-
-```json
-{
-  "message": "文件写入成功",
-  "fileName": "report.csv",
-  "size": 2048,
-  "key": "download/jerry/sess_abc123/a1b2c3d4_report.csv"
-}
-```
-
-则你的回复中需要包含：
-
-已为您生成报告文件：
-
-```
-$$FILE_DOWNLOAD:{"key":"download/jerry/sess_abc123/a1b2c3d4_report.csv","fileName":"report.csv","size":2048}$$
-```
-
-## 读文件策略
-
-> 说明：读取工具 `storage_file_read` / `storage_file_read_to_local` 通过 `key` 参数定位文件；`key` 来自 `storage_file_write` / `storage_file_upload` 的返回值，或 `storage_file_list` 列出的文件项。`storage_file_list` 可传入 `userId` / `sessionId` 限定范围（取值方式同上，来自消息开头的 `[context]` 行）。
-
-根据文件类型选择不同的读取方式：
-
-### storage_file_read（文本文件）
-
-- 适用于：CSV、JSON、TXT、Markdown、代码文件等文本类型
-- 入参：`key`（对象 key）
-- 返回纯文本内容，可直接用于分析
-
-### storage_file_read_to_local（任意文件）
-
-- 适用于：图片、PDF、压缩包、Excel 等二进制文件
-- 入参：`key`（对象 key）
-- 将文件下载到本地临时路径（`/tmp/fwh-toolbox-agent/downloads/`），返回本地文件路径 `localPath`
-- **图片文件**（png/jpg/gif/webp）下载后可通过本地路径进行 AI 视觉分析
-- 其他二进制文件下载后主要用于中转（如重新上传、返回给前端下载）
-
-### 判断标准
-
-- 用户要求分析文本文件 → `storage_file_read`
-- 用户要求分析图片/二进制内容 → `storage_file_read_to_local`
-- 需要获取文件原始数据（中转、转发） → `storage_file_read_to_local`
-- 不确定文件类型或不知道 key 时 → 先用 `storage_file_list` 查看文件信息（含 key），再选择合适的读取方式
-
-## 写文件策略
-
-根据文件用途选择不同的输出方式：
-
-### 需要给用户下载的文件
-
-#### 文本文件（CSV、JSON、Markdown、代码等）
-
-- 使用 `storage_file_write` 工具写入（最大 20MB）
-- 尽量传入 `userId` 和 `sessionId`
-- 写入成功后输出 `$$FILE_DOWNLOAD:...$$` 标记
-- 适用场景：导出数据、生成报告、分析结果文件
-
-#### 任意类型文件（二进制文件、图片、PDF、压缩包、Excel 等）
-
-- 使用 `storage_file_upload` 工具上传（最大 100MB）
-- 直接传入本地文件的绝对路径 `localPath` 参数（无需 base64 编码）
-- 可选传入 `fileName` 参数指定上传后的文件名（不传则使用本地文件名）
-- 尽量传入 `userId` 和 `sessionId`
-- 上传成功后同样输出 `$$FILE_DOWNLOAD:...$$` 标记
-
-### 临时文件（中间处理、缓存等）
-
-- 写入 `/tmp/fwh-toolbox-agent/` 目录
-- 处理完成后无需输出下载标记
-
-### 判断标准
-
-- 用户说“下载”、“导出”、“生成报告”、“保存为文件” → 使用 storage_file_write 或 storage_file_upload + 输出标记
-- 文本内容直接写入 → `storage_file_write`
-- 本地已有文件需要上传 / 二进制文件 → `storage_file_upload`（传入 `localPath`）
-- 中间计算结果、日志 → 写入 /tmp/fwh-toolbox-agent
-- 不确定时 → 询问用户

deploy/kiro/skills/fwh-toolbox-rules/references/officecli-batch-rules.md

@@ -1,49 +0,0 @@
-# officecli 批量写入规则
-
-本规则适用于通过 `@officecli` MCP 工具操作 `.xlsx` / `.docx` / `.pptx` 的所有批量写入场景。
-
-## 核心约束
-
-### 1. 禁止使用 stdin（`--input -`）
-当前 agent 通过 MCP 调用 officecli，只能传递一个 `command` 字符串参数，**没有 stdin 管道**。
-`--input -` 会让进程启动后一直阻塞等待标准输入，永远等不到数据，表现为“卡住无响应”直到被取消。
-
-- 禁止：`batch <file> --input -`
-- 禁止：任何依赖管道 `|` 或 heredoc `<<EOF` 向 officecli 喂数据的写法（MCP 环境不存在 shell 管道）
-
-### 2. 批量写入首选 `--commands` 内联
-把批量操作的 JSON 直接作为 `--commands` 的参数值内联传入，一次调用完成，不经过 stdin、不写临时文件。
-
-```
-batch <file> --commands '[
-  {"command":"set","path":"/Sheet1/A1","props":{"value":"字段","bold":"true"}},
-  {"command":"set","path":"/Sheet1/A2","props":{"value":"数据"}}
-]' --json
-```
-
-- 始终带 `--json`，便于读取 `matched` / 成功失败计数 / `atomicRolledBack` 等结构化结果。
-- batch 默认原子执行：任一条失败则整批回滚，文件保持批处理前的状态。需要“保留已成功项”时才加 `--best-effort`。
-
-### 3. 不要退化成逐条 `set`
-逐条 `set`（一格/一行一条命令）只作为**最后兜底**，不是默认方案。
-能用一次 `batch --commands` 解决的，不要拆成几十次调用。
-
-### 4. 超大批量才考虑临时文件
-仅当批量 JSON 大到 `--commands` 内联不现实时，才改用 `--input <真实文件路径>`：
-
-- 必须是 officecli 进程有权读取、且**真实存在**的文件路径。
-- 用 `write` 工具写 JSON 时，路径必须落在 `write.allowedPaths` 允许的目录内。
-- 写完后用 `batch <file> --input /真实/路径/ops.json --json` 读取。
-- 绝不使用 `--input -`。
-
-## 参数拼写与转义
-
-- 路径含 `[N]` 时整体加引号：`'/Sheet1/A1'`、`"/slide[1]"`。
-- 文本含 `$`、换行等特殊字符时，优先放进 `--commands` 的 JSON 里，避免 shell 层转义问题（MCP 透传虽不经 shell，但 JSON 内保持规范更稳妥）。
-
-## 决策顺序（从优到劣）
-
-1. `batch --commands '[...]' --json` —— 默认，绝大多数场景用这个
-2. `batch --input <真实文件> --json` —— 仅超大批量
-3. 逐条 `set` —— 仅当以上都不可行时的兜底
-4. `--input -`（stdin） —— **永远不用**

deploy/kiro/skills/fwh-toolbox-rules/references/ppt-template-rules.md

@@ -1,17 +0,0 @@
-# PPT 模板规则
-
-## 触发条件
-当用户提到以下关键词时，自动使用公司 PPT 模板：
-- “公司模板”
-- “company template”
-- “用模板生成 PPT”
-
-## 模板路径
-- 默认模板：`__KIRO_HOME__/templates/company-template.pptx`
-- 拷贝模版：`cp __KIRO_HOME__/templates/company-template.pptx /tmp/fwh-toolbox-agent/ppt/{file_name}.pptx`
-- 如有多个模板，用户指定名称时匹配对应文件
-
-## 生成规则
-- 优先使用模板中已有的幻灯片布局
-- 保持模板的配色和字体风格
-- 第一页使用标题布局，最后一页使用结束/感谢布局

deploy/kiro/skills/fwh-toolbox-rules/references/python-rules.md

@@ -1,49 +0,0 @@
-# Python3 使用规则（沙箱内执行）
-
-本平台的 Python3 只能通过沙箱执行器 `fwh-pyrun` 运行。`fwh-pyrun` 用 bwrap 建立强制隔离，
-并施加资源限额；**沙箱是内核级强制边界**，以下约束即便脚本不遵守也会被系统拦截，但仍需遵守
-以免脚本报错或产出无效结果。
-
-## 何时使用 Python3
-
-- 仅当 `@fwh-tools` / `@officecli` / `knowledge` 等工具**无法完成**的自定义数据处理、计算、格式转换时，才写 Python。
-- 能用现成工具完成的，优先用工具，不要写 Python 重复实现。
-
-## 唯一允许的运行方式
-
-1. 先用 `write` 把脚本写到沙箱目录，建议放 `/tmp/fwh-toolbox-agent/scripts/<name>.py`。
-2. 通过下面的命令执行（这是**唯一**被放行的方式）：
-   ```
-   __KIRO_HOME__/bin/fwh-pyrun /tmp/fwh-toolbox-agent/scripts/<name>.py [参数...]
-   ```
-3. **禁止**以下写法（配置层 `allowedCommands` 会直接拒绝，不要尝试）：
-   - 直接 `python3 xxx` / `python xxx`
-   - `python3 -c "..."`（内联代码）
-   - 任何命令拼接或管道：`; | &`
-   - 运行沙箱目录之外、或非 `.py` 结尾的脚本
-
-## 脚本内约束（沙箱已强制，遵守以免失败）
-
-- **文件范围**：只能读写 `/tmp/fwh-toolbox-agent/` 下的文件。沙箱外路径（`/home`、项目目录、
-  `/etc` 写入、凭据等）不可见或不可写，访问会抛 `FileNotFoundError` / `PermissionError`。
-- **无网络**：沙箱内没有网络接口。不要 `import requests` / `urllib` / `socket` 发起网络请求，会失败。
-  需要外部数据时，改用 MCP 数据工具（`@fwh-tools/data_*` 等）取回后再交给脚本处理。
-- **仅标准库**：只用 Python 标准库。不要 `pip install`（沙箱只读且无网，必然失败）。
-- **输入文件**：需要处理的远端/对象存储文件，先用 `storage_file_read_to_local` 下载到
-  `/tmp/fwh-toolbox-agent/downloads/`，再在脚本里按本地路径读取。
-- **输出文件**：脚本产物写到 `/tmp/fwh-toolbox-agent/` 下；若需交付用户，脚本运行后由你用
-  `storage_file_upload` 上传并按 `references/file-output-rules.md` 输出 `$$FILE_DOWNLOAD:...$$` 标记
-  （上传动作由工具完成，不在脚本内做）。
-
-## 资源限制（会被强制，超限即终止）
-
-- CPU 时间 ≤ 30 秒，虚拟内存 ≤ 1GB，单文件写入 ≤ ~128MB，总运行 ≤ 60 秒。
-- 若数据量大导致超时/超内存：改为分批处理、流式读取，或改用 MCP 数据工具在数据侧聚合，
-  减少 Python 侧的数据量。
-
-## 典型流程示例
-
-1. `write` → `/tmp/fwh-toolbox-agent/scripts/analyze.py`（只用标准库，读写沙箱内路径）。
-2. 若需输入数据：先 `@fwh-tools` 查询或 `storage_file_read_to_local` 下载到沙箱。
-3. 执行：`__KIRO_HOME__/bin/fwh-pyrun /tmp/fwh-toolbox-agent/scripts/analyze.py`。
-4. 读取脚本产物（沙箱内），如需交付用户再 `storage_file_upload` + 输出下载标记。

deploy/kiro/skills/fwh-toolbox-workflow/SKILL.md

@@ -1,260 +0,0 @@
----
-name: fwh-toolbox-workflow
-description: FranklinWH 工具箱（fwh-toolbox）平台的操作流程指南。当用户需要查询站点/设备信息、运维监控与告警、停机/告警看板、SIM 卡管理、站点分析任务、批量数据下载、自动升级配置、TOU（分时电价）调度模板的查询/构建/新增/更新（含时段策略、光伏/负载优先级、充放电功率、省市选择）、故障录波/日志召唤、Plane 反馈协作，或需要用 fwh-tools MCP 工具做数据分析、生成报告文件时，使用本技能。它说明每类业务应该调用哪些 MCP 工具、调用顺序、参数约定以及文件输出规范。
----
-# fwh-toolbox 平台操作流程
-
-FranklinWH 工具箱是内部运维分析平台，通过 `fwh-tools` MCP Server（v2.0.0）暴露 AI 接口层。本技能描述平台所有业务的标准操作流程，指导应调用哪些工具、以何种顺序、注意哪些参数与约束。
-
-## 工具分层原则
-
-MCP 工具按访问层级分为五类，**选择工具时严格遵循以下优先级**：
-
-| 层级       | 前缀          | 说明                                                                | 何时使用                                                       |
-| ---------- | ------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- |
-| 业务逻辑层 | `service_*` | 调用后端 Service 层，含业务校验、数据聚合与格式化                   | **首选**。常规业务查询与操作                             |
-| 数据直查层 | `data_*`    | 直接读数据库/缓存/上游 API，跳过业务逻辑，**只读**            | 仅当 service 层无法满足（自定义 filter、聚合、上游原始数据）时 |
-| 对象存储层 | `storage_*` | 文件与对象存储。`storage_file_*` 可读写；`storage_minio_*` 只读 | 读取用户上传文件、导出报告、浏览已下载对象                     |
-| 辅助工具   | `util_*`    | 纯函数，不涉及持久化                                                | SN 解析等本地计算                                              |
-| Plane 原生 | `plane_*`   | Plane 官方 MCP 工具（需 workspace_slug/project_id）                 | 深入的项目管理操作，详见 references/plane-collaboration.md     |
-
-核心原则：
-
-1. 优先 `service_*`，它包含完整业务逻辑与格式化输出。
-2. 仅在 service 层不足时才用 `data_*` 直查，且只读。
-3. 描述中标注 `[写操作]` 的工具会由 Agent 权限管控，执行前需用户确认。
-4. `data_mongo_*` 有 collection 白名单，`storage_minio_*` 有 bucket 白名单（见对应章节）。
-5. 不要臆造工具名。全部可用工具见本文件与 references/ 下的清单；找不到合适工具时如实说明。
-
-## 通用约定
-
-- **站点标识 SN**：设备序列号，多数站点工具的主键。格式见 `util_parse_sn`。
-- **SIM 标识**：SmartHub 用 `GICCID`（19 位），Acceleronix 用 `ICCID`。
-- **日期格式**：`yyyy-MM-dd`；时间范围类为 `yyyy-MM-dd HH:mm:ss`；SIM 月份 service 层用 `yyyy-MM`，Acceleronix 批量用量月份为 `YYYYMM`。**注意**：直查 `data_mongo_*` 时，`SimCardManage`/`SimCardMonthlyData` 的 `month` 字段库内存在 `yyyy-MM` 与 `yyyyMM` 两种格式并存，按月过滤/分组须兼容两者（写法见 `references/data-direct-query.md` 的「month 字段双格式」）。
-- **分页**：`page` 从 1 开始，`size` 默认 10~20（各工具不同，见清单）。
-- **任务 ID**：批量下载、站点分析等任务 ID 为 MongoDB ObjectID hex 字符串。
-
----
-
-## 业务操作流程
-
-### 1. 站点 / 设备查询
-
-目标：查设备详情、状态、功率流、工作模式、告警。
-
-标准流程：
-
-1. **定位站点** — 已知 SN 直接用 `service_site_query_info`（单站点详情：版本、网络状态、激活状态、固件等）；只有关键字/名称时先 `service_site_search`（分页 `keyword`）拿到 SN。
-2. **批量基本信息** — 多个 SN 时用 `service_site_monitor_base_info`（`site_list` 为 JSON 数组），返回激活状态、国家、版本等。
-3. **功率流** — `service_site_power_flow`（`sn` + `date`），返回 PV、Grid、aPower、HomeLoad、Generator 各通道数据。
-4. **工作模式** — `service_site_monitor_mode_info` 或 `service_site_monitor_alarm_list`（当前告警列表）。
-5. **SN 语义解析** — `util_parse_sn` 解析产品代码/硬件版本/工厂/年周/序号（aGate=1006, aPower=1005, aHub/PowerLink=1002）。
-
-站点信息表维护：
-
-- `service_site_info_update_status` 查最近一次同步状态。
-- `service_site_info_trigger_update` **[写操作]** 从 FWH Pro 同步最新站点数据到本地表。
-- 标签：`service_site_info_tags_list` 查列表；`service_site_info_tag_update` **[写操作]** 创建/更新标签（`tag` JSON：id 可选、name、color、description）。
-
-#### ⚠️ 使用站点信息前必做：数据新鲜度检查（强约束）
-
-> **凡是要「使用本地站点信息表数据」的任务，开始前必须先执行本检查。** 涉及的工具包括但不限于：`service_site_query_info`、`service_site_search`、`service_site_monitor_base_info`、站点信息导出、以及依赖本地站点信息表的分析类任务。若一次会话中已检查过且距离上次检查未超过阈值，可复用上次结论、不必重复检查。
-
-**判定依据**：`service_site_info_update_status` 返回 `domain.SiteInfoUpdateRecord`：
-
-- `progress`：本次同步任务状态，枚举 `pending | running | complete | failed | error`。
-- `updateTime`：**数据实际同步完成的时刻**（仅当 `progress=complete` 时才刷新），新鲜度以此为准。
-- `createTime`：本次同步任务的创建时刻，用于估算「更新中」还剩多久。
-- `total`：站点总数。
-
-**决策流程**：
-
-1. 调用 `service_site_info_update_status` 获取 `progress`、`updateTime`、`createTime`。
-
-2. **判断 `progress`**：
-   - 若 `progress ∈ {pending, running}` → **正在更新中**：**不要**触发新的更新，也不要用当前数据得出确定结论。告知用户数据正在同步、整个过程约需 **1.5 小时**，并按 `createTime + 1.5h` 给出建议的重试时间，询问用户是「稍后再试」还是「先用当前（可能偏旧的）数据继续」。
-   - 否则（`complete / failed / error` 或已完成）进入第 3 步。
-
-3. **计算新鲜度** = 当前时间 − `updateTime`：
-   - **< 24 小时** → 直接继续任务，并在回复中**明确标注数据更新时间**（见文案模板）。
-   - **≥ 24 小时** → 停下来让用户三选一：**①更新**（调用 `service_site_info_trigger_update`，属 **[写操作]**，须先获得用户确认后再触发；触发后提示约 1.5 小时完成、期间可稍后再查）／**②跳过**（用现有旧数据继续，但结论须标注数据已过期）／**③放弃任务**。
-
-4. **无记录**（`update_status` 返回空）→ 视为从未同步，按「≥ 24 小时」分支处理，询问是否执行首次同步。
-
-**文案模板**（按实际值填充；`{n}` 为距今时长）：
-
-- 数据较新：`ℹ️ 站点信息数据更新于 {updateTime}（约 {n} 小时前），以下结果基于该时间的数据。`
-- 数据过期：`⚠️ 站点信息数据上次更新于 {updateTime}，已超过 24 小时（约 {n} 天前），可能不是最新状态。请选择：①更新（触发同步，约需 1.5 小时）②跳过（用现有数据继续）③放弃任务。`
-- 更新中：`⏳ 站点信息正在同步中（progress={progress}，任务开始于 {createTime}），整个过程约需 1.5 小时，预计约 {createTime + 1.5h} 完成。是否先用当前数据继续，还是稍后再试？`
-
-> 需要 FWH Pro 上游原始数据（如工作模式、功率流的原始返回）时，可用 `data_fwh_query_*`，见 references/fwh-pro-api.md。
-
-### 2. 站点监控配置
-
-目标：把一组站点组织成命名监控分组，供看板/批量操作复用。
-
-- 列表：`service_site_monitor_config_list`（全部配置）/ `service_site_monitor_name_list`（仅名称）。
-- 详情：`service_site_monitor_config_get`（按 `name`）。
-- 创建：`service_site_monitor_config_create` **[写操作]**（`name` + `site_list` JSON 数组 + 可选 `description`）。
-- 更新：`service_site_monitor_config_update` **[写操作]**（按 `name`）。
-- 删除：`service_site_monitor_config_delete` **[写操作]**（按 `name`）。
-
-### 3. 运维监控与看板（统计）
-
-目标：查看按日期汇总的告警/停机统计与明细。
-
-- 告警统计（按日汇总各类告警数量）：`service_monitor_alarm_stats`（`date` 可空=最新）。
-- 停机统计（按日汇总停机站点）：`service_monitor_shutdown_stats`（`date` 可空=最新）。
-- 看板明细：
-  - `service_dashboard_shutdown_date` — 先查停机统计最新可用日期。
-  - `service_dashboard_shutdown_detail`（`date` 可空）— 各站点停机明细。
-  - `service_dashboard_alarm_detail`（`date` 可空）— 各站点告警码统计明细。
-
-典型流程：先 `service_dashboard_shutdown_date` 得到可用日期 → 再拉对应 `*_detail`。
-
-### 4. SIM 卡管理
-
-目标：查 SIM 状态、平台归属、用量。
-
-- 搜索：`service_sim_search`（`search`=GICCID、`platform`=SmartHub/Acceleronix、`status`=UNKNOWN/NOT_ACTIVATED/ACTIVATED/DEACTIVATED/RETIRED，逗号分隔多选，分页）。
-- 单卡详情：`service_sim_query`（`giccid` 19 位）——状态、平台、用量汇总。
-- 月度每日用量：`service_sim_monthly_data`（`giccid` + `month` yyyy-MM）。
-
-> 需要上游平台原始数据（Acceleronix / SmartHub 卡详情、流量池、批量用量）时用 `data_sim_*`，见 references/data-direct-query.md。
-
-### 5. 站点分析任务（Site Analysis）
-
-目标：对单站点在时间段内做 timeline + runtime 深度分析（异步任务）。
-
-流程：
-
-1. **创建**：`service_site_analysis_create` **[写操作]**（`sn` + `time_period` JSON `["start","end"]` yyyy-MM-dd；可选 `enable_runtime`/`enable_timeline` 默认 true；`description`）。任务自动入队执行。
-2. **查进度**：`service_site_analysis_list`（按 `sn`/`progress` 筛选，progress ∈ pending/running/success/failed）。
-3. **查配置**：`service_site_analysis_get_config`（`id`）。
-4. **取结果**：`service_site_analysis_data`（`id`）——返回 timeline + runtime 数据。
-5. 维护：`service_site_analysis_update_desc` **[写操作]** 改描述；`service_site_analysis_delete` **[写操作]** 删除。
-
-任务运行状态也可用 `service_background_task_list` 查看（含状态、重试次数、参数）。
-
-### 6. 批量数据下载（Batch Download）
-
-目标：为一批站点在时间段内批量导出诊断数据（打包为 tar.gz 存入 MinIO）。
-
-流程：
-
-1. **创建**：`service_batch_download_create` **[写操作]**：
-   - `sn`：站点 SN 列表 JSON 数组。
-   - `time_period`：JSON 数组 `["2024-01-01","2024-01-31"]`。
-   - `options`：下载选项 JSON，字段：`powerFlow`(bool)、`mqttLogs`(string[])、`eventAlarm`(bool)、`alarmSnapshot`(bool)、`emsLogs`(string[])、`faultRecord`(bool)、`updateLog`(bool)、`settings`(bool)。
-   - 可选 `description`。任务自动入队。
-2. **查列表/进度**：`service_batch_download_list`（按 `sn`/`progress` 筛选）。
-3. **看产物目录**：`service_batch_download_path`（`id`）查任务文件目录结构；`service_batch_download_file_tree`（`file_path`）查某 tar.gz 内部结构。
-4. **读取产物**：用 `storage_minio_list_objects` / `storage_minio_read_object` 浏览与读取（bucket 白名单见存储章节）。
-5. 维护：`service_batch_download_update_desc` **[写操作]**；`service_batch_download_update_owner` **[写操作]**（`owner` JSON 数组）；`service_batch_download_delete` **[写操作]**。
-
-### 7. 自动升级配置（Auto Update）
-
-目标：管理按 aGate 硬件版本下发的自动升级策略与升级包，并导出配置 Excel。
-
-查询：
-
-- `service_auto_update_get_options` — 升级包列表 + aGate 版本列表（配置前先看选项）。
-- `service_auto_update_get_apower_version` — aPower 硬件版本列表。
-- `service_auto_update_get_config`（`agate_version`）— 指定 aGate 版本的配置。
-- `service_auto_update_get_package`（`file_name`）— 指定升级包详情。
-- `service_auto_update_file_list` — 已生成的配置 Excel 文件列表（分页）。
-
-变更（均为 **[写操作]**）：
-
-- 配置：`service_auto_update_update_config`（`agate_version` + `config` JSON，含 `config.defaultType` 和 `config.specialType`）；`service_auto_update_delete_config`（`agate_version`）。
-- 升级包：`service_auto_update_create_package`（`package_type` ∈ system/aGate/subDevice/others + `info` JSON，含 id=文件名、title、invVersion[]）；`service_auto_update_update_package`（`file_name` + `info`）；`service_auto_update_delete_package`（`package_type` + `file_name`）。
-- 导出：`service_auto_update_create_file` — 生成新的自动升级配置 Excel。
-
-典型流程：`get_options` → 按需 `update_config`/`create_package`（确认后执行）→ `create_file` 导出 → 提示用户下载。
-
-### 8. TOU 电价模板
-
-目标：查询、构建、新增/更新分时电价（Time-Of-Use）调度模板。一个模板 = 基础信息 + 一个或多个「季节/日类型」策略；每个策略 = 覆盖一整天的时段列表。
-
-工具：
-
-- 列表：`service_tou_template_list`（`type` 0-系统/1-API/2-用户推荐；`status` 0-未发布/2-已发布；`search`；分页；默认 `env:"pro"`）。
-- 详情：`service_tou_template_detail`（`id` 数字；默认 `env:"pro"`）。
-- 省/市：`service_tou_template_cites`（拿 `countryId`/`provinceId`；查某国家省/市需传 `country_id` 且 `type:1`，都不传则返回国家列表；**仅支持 `env:"test"`**）。
-- 保存：`service_tou_template_save` **[写操作]**（`payload` 为字符串化 JSON `{"template":{...},"strategyList":[...],"lang":"ZH_CN"}`；`template.templateId` 有值=更新、省略=新增；`sourceType` 当前仅 `0` 系统模板可写；**仅支持 `env:"test"`**）。
-
-标准流程：
-
-1. 查询/取蓝本：`service_tou_template_list` → `service_tou_template_detail`（要读测试环境模板加 `env:"test"`）。
-2. 定地区：`service_tou_template_cites { "env":"test", "country_id":<id>, "type":1 }` 拿 `provinceId`。
-3. 构建 `payload`：按字段字典填 `template` + `strategyList[].detailVoList[]`；数值字段传数字，可选数值字段未设置时**省略该 key**（不传 `""`/`null`）；每个策略时段必须覆盖 00:00→24:00。
-4. **写确认**：`save` 前先向用户摘要「新增/更新、模板名、地区、策略与关键时段/电价」，明确写入 **test** 环境，得到用户同意后才调用。
-5. 保存后用返回的 `templateId` 调 `service_tou_template_detail { "env":"test", "id":<id> }` 回读校验。
-
-> 完整字段字典、日类型配套逻辑、功率哨兵值、优先级→调度策略速查、请求体示例：见 references/tou-template.md。
-> FWH Pro 上游的 TOU 模板（`data_fwh_query_tou_template_list` / `_detail`）见 references/fwh-pro-api.md。
-
-### 9. 后台任务监控
-
-`service_background_task_list` — 查看当前所有后台任务（批量下载、站点分析、站点信息同步等）的状态、重试次数与参数。排查任务卡住/失败时先看这里。
-
-### 10. 反馈协作（Plane Intake）
-
-目标：把用户的 bug/需求反馈提交到 Plane。
-
-- 提交：`service_feedback_create` **[写操作]**（`title` + `type`=bug/feature；`category`：bug 类=bug/ui/performance/other，feature 类=new/improvement/experience；`priority`=urgent/high/medium/low/none 默认 medium；`description`）。
-- 历史：`service_feedback_history` — 带 Feedback 标签的 Intake Issue 提交记录。
-
-更深入的 Plane 项目管理（工作项、迭代、模块、评论、附件等）见 references/plane-collaboration.md。
-
----
-
-## 数据直查层（data_*）速览
-
-仅在 `service_*` 无法满足时使用，全部只读。详细流程见 references：
-
-- **FWH Pro 上游 API**：`data_fwh_query_*`（站点列表/基本信息/功率流/工作模式、当前告警、告警统计、告警快照、事件/告警日志、MQTT 日志、EMS 日志召唤记录、故障录波列表/子记录/可召唤列表/召唤记录、aHub/系统升级记录、Shutdown 列表、TOU 模板）→ references/fwh-pro-api.md
-- **MongoDB / Redis / PgSQL / EMS 参数 / SIM 上游**：`data_mongo_find`、`data_mongo_count`、`data_mongo_export`（全量流式导出）、`data_mongo_aggregate`（聚合管道，支持 `$lookup` 跨集合关联/分组统计，在 DB 侧一步完成"过滤+JOIN+聚合"，大数据量关联首选）、`data_redis_get`、`data_redis_exists`、`data_pgsql_query_snapshot_data`、`data_pgsql_query_snapshot_file_record`、`data_emspara_pid_info`、`data_emspara_vid_info`、`data_sim_*` → references/data-direct-query.md（含字段字典、JOIN 关系图谱与聚合配方）
-- **Plane 直查（V1 封装）**：`data_plane_*` → references/plane-collaboration.md
-
----
-
-## 对象存储与文件输出
-
-### 读取用户上传文件
-
-用户经前端上传的文件位于 `/uploads/` 路径下：
-
-- `storage_file_list` — 列出当前会话上传的所有文件（名称、路径、大小）。
-- `storage_file_read`（`path`=/uploads/{filename}）— 读文本文件内容（CSV/JSON/TXT/MD/代码）。
-- `storage_file_read_to_local`（`path`）— 下载任意文件（图片/PDF/压缩包）到本地临时路径，返回本地路径供后续处理。
-
-### 浏览 MinIO（只读，bucket 白名单：fwh-toolbox、fwh-toolbox-ai-file）
-
-- `storage_minio_list_objects`（`bucket` + 可选 `prefix`/`limit`）— 列对象。
-- `storage_minio_read_object`（`bucket` + `key`）— 读文本对象（最大 1MB）。
-
-### 生成文件给用户下载 —— 必读规则
-
-> 详见 steering：`.kiro/steering/file-output-rules.md`
-
-1. **文本文件**（CSV/JSON/Markdown/代码，≤20MB）：用 `storage_file_write`（`path`=/uploads/{filename} + `content`）。
-2. **二进制/大文件**（图片/PDF/压缩包/Excel，≤100MB）：本地文件用 `storage_file_upload`（`localPath`，无需 base64）。
-3. **必须传 `userId` 和 `sessionId`**：从每条用户消息开头的 `[context] userId=xxx` / `sessionId=xxx` 中提取。
-4. 写入/上传成功后，**必须在回复中独占一行输出下载标记**（不要放进代码块）：
-
-   ```
-   $$FILE_DOWNLOAD:{"key":"<返回的key>","fileName":"<文件名>","size":<大小>}$$
-   ```
-
-   `key`/`fileName`/`size` 用工具返回值原样填入；一次回复可输出多个标记。
-5. 中间产物写 `/tmp/fwh-toolbox-agent/`，无需输出下载标记。
-
----
-
-## 参考文件索引
-
-- `references/fwh-pro-api.md` — `data_fwh_*` FWH Pro 上游直查 API 全量清单与流程。
-- `references/data-direct-query.md` — MongoDB/Redis/PgSQL/EMS 参数/SIM 上游直查流程与白名单。
-- `references/plane-collaboration.md` — 反馈协作与 Plane 项目管理（`service_feedback_*`、`data_plane_*`、`plane_*`）。
-- `references/tou-template.md` — TOU 电价模板构建/写入的完整字段字典、日类型配套逻辑、功率哨兵值、优先级→调度策略速查与请求体示例。

deploy/kiro/skills/fwh-toolbox-workflow/references/data-direct-query.md

@@ -1,210 +0,0 @@
-# 数据直查层（`data_*` 数据库 / 缓存 / 上游）
-
-直接读数据库、缓存或上游平台，跳过 Service 层。**全部只读**。仅当 `service_*` 工具无法满足（自定义 filter、聚合统计、上游原始数据）时使用。
-
-## MongoDB
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_mongo_find` | `collection`(必填)、`filter`(JSON)、`fields`(字段投影数组)、`limit`(默认10,最大100)、`skip`、`sort`(JSON) | 查询集合文档 |
-| `data_mongo_count` | `collection`(必填)、`filter`(JSON,可空) | 统计符合条件的文档数 |
-| `data_mongo_export` | `collection`(必填)、`filter`(JSON)、`fields`(数组)、`sort`(JSON)、`max_docs` | 全量导出到 NDJSON 文件，游标流式、内存常数级；仅回 localPath+count+summary |
-| `data_mongo_aggregate` | `collection`(必填)、`pipeline`(JSON数组字符串,必填)、`max_docs` | **聚合管道**：在数据库侧完成过滤+关联(JOIN)+分组统计，结果流式落盘 |
-
-**collection 白名单**（仅以下集合可查；`$lookup`/`$graphLookup`/`$unionWith` 引用的集合也必须在此列表内）：
-`SiteInfoManageData`、`SiteInfoManageRecord`、`SimCardManage`、`SimCardMonthlyData`、`BatchDownloadConfig`、`SiteAnalysisConfig`、`StatisticsShutdown`、`StatisticsAlarm`、`SiteMonitorConfig`、`AutoUpdateConfigOption`、`AutoUpdateConfig`
-
-> 注意：`UserInfo`（内部用户身份数据）与 `AiChatSessions`（历史对话自由文本）已从白名单**移除**，不可直查，也不可作为 `$lookup`/`$unionWith` 的目标。
-
-find/export 示例：
-```json
-{ "collection": "SiteInfoManageData", "filter": "{\"sn\": \"xxx\"}", "limit": 10, "sort": "{\"createdAt\": -1}" }
-```
-
-用法提示：
-- `filter` / `sort` / `pipeline` 都是 JSON **字符串**（如 `"{\"sn\":\"xxx\"}"`）。
-- 分页用 `skip` + `limit`；大数据量导出用 `data_mongo_export`（不受 100 条上限）。
-- 优先用对应的 `service_*` 工具；直查仅用于灵活筛选/聚合/关联。
-- **所有 `data_mongo_*` 返回都无条件落盘**：仅返回 `localPath` + `summary`，需用文件读取工具按 `localPath` 读取完整数据。
-
-### data_mongo_aggregate（聚合 / 跨集合 JOIN）
-
-在**数据库侧**一次性完成"过滤 + 关联(JOIN) + 分组统计"，避免多次取数与 Agent 侧拼接，是大数据量关联任务的首选。
-
-**允许的只读阶段**：`$match`、`$project`、`$addFields`/`$set`、`$unset`、`$group`、`$sort`、`$limit`、`$skip`、`$count`、`$unwind`、`$lookup`、`$graphLookup`、`$unionWith`、`$facet`、`$bucket`/`$bucketAuto`、`$sortByCount`、`$replaceRoot`/`$replaceWith`、`$sample`、`$redact`、`$setWindowFields`。
-
-**禁止的阶段**（会被拒绝）：`$out`、`$merge`（写集合）、`$function`、`$accumulator`、`$where`（执行 JS）。
-
-**安全约束**：
-- `collection` 及 `$lookup`/`$graphLookup`/`$unionWith` 引用的集合都必须在白名单内（含嵌套 pipeline，递归校验）。
-- 每个阶段必须恰好一个顶层操作符。
-- 结果超过 `max_docs`（默认 50000）会被截断。
-
-#### 字段字典（写 pipeline 必读）
-
-**`SiteInfoManageData`（站点信息，`_id` = 站点 SN）关键字段**：
-- `_id`（站点 SN，20位）、`iccId`（SIM 卡 ICCID，20位；**前 19 位 = GICCID**）
-- `province`（州/省，如 `"Puerto Rico"`）、`city`、`country`（`"United States"`）、`countryId`、`provinceId`
-- `activeStatus`(1=已激活)、`status`(在线状态)、`runStatus`、`connType`、`signal`、`batterySoc`
-- `installerName`、`version`、`realSysHdVersion`、`site`(站点编码)、`siteId`
-- 敏感字段（会被脱敏）：`address`/`deviceAddress`、`longitude`/`latitude`、`contactNumber`、`userName`/`firstName`/`lastName`、`account`、`mac`/`deviceIp`/`imei`
-
-**`SimCardManage`（SIM 卡，`_id` = GICCID 19位）关键字段**：
-- `_id`（GICCID，19位）、`status`（UNKNOWN/NOT_ACTIVATED/ACTIVATED/DEACTIVATED/RETIRED）、`platform`（SmartHub/Acceleronix）
-- `allDataUsage`（累计用量，**单位 KB**）、`month`（统计月份，**格式不统一，见下方「month 字段双格式」**）、`expirationTime`、`updateTime`
-- 敏感字段（会被脱敏）：`imei`、`imsi`、`msisdn`
-
-**`SimCardMonthlyData`（SIM 月用量）**：`simId`(GICCID)、`month`（**格式不统一，见下方「month 字段双格式」**）、`allDataUsage`（**单位 KB**）、`dailyUsage`。
-
-> **流量单位换算（写阈值必看）**：`allDataUsage`、`dailyUsage.dataUsage` 一律为 **KB**。
-> 换算：1 MB = 1024 KB，1 GB = 1048576 KB。
-> 常用阈值：**200MB = 204800**、500MB = 512000、1GB = 1048576、2GB = 2097152。
-> 因此"流量大于 200M"应写 `{"allDataUsage": {"$gt": 204800}}`，不要用 200 或 200000000。
-
-> **⚠️ month 字段双格式（按 month 过滤/分组必看）**：`SimCardManage.month` 与 `SimCardMonthlyData.month` 历史上存在**两种写法并存**：
-> - `yyyy-MM`（带连字符，如 `2026-01`）——SmartHub 平台写入。
-> - `yyyyMM`（无连字符，如 `202601`）——Acceleronix 平台写入。
->
-> 因此**不能只用一种格式做等值匹配**，否则会漏掉另一半数据。按月份筛选时用以下任一兼容写法：
-> - **枚举两种格式**（推荐，简单可用索引）：
->   `{"month": {"$in": ["2026-01", "202601"]}}`
-> - **归一化后匹配**（在 pipeline 里先去掉连字符再比）：
->   ```json
->   { "$addFields": { "monthNorm": { "$replaceAll": { "input": "$month", "find": "-", "replacement": "" } } } },
->   { "$match": { "monthNorm": "202601" } }
->   ```
-> 按 month 分组统计时同理，建议先用上面的 `$addFields` 归一化出 `monthNorm` 再 `$group`，避免同一个月被拆成两组。
-> `service_sim_monthly_data` 等 service 层工具入参仍用 `yyyy-MM`（由后端处理），此双格式问题**仅影响 `data_mongo_*` 直查**。
-
-#### JOIN 关系图谱（跨集合关联键）
-
-- **站点 ↔ SIM**：`SiteInfoManageData.iccId` 取**前 19 位** = `SimCardManage._id`（GICCID）。
-  在 pipeline 中先用 `$addFields` 计算 `giccid = $substrBytes(iccId, 0, 19)`，再 `$lookup` 关联。
-- **SIM ↔ 月用量**：`SimCardManage._id` = `SimCardMonthlyData.simId`。
-
-#### 配方：波多黎各站点关联 SIM 信息（一步完成）
-
-```json
-[
-  { "$match": { "province": "Puerto Rico" } },
-  { "$addFields": { "giccid": { "$substrBytes": ["$iccId", 0, 19] } } },
-  { "$lookup": {
-      "from": "SimCardManage",
-      "localField": "giccid",
-      "foreignField": "_id",
-      "as": "sim"
-  }},
-  { "$project": {
-      "sn": "$_id", "city": 1, "giccid": 1,
-      "simStatus": { "$arrayElemAt": ["$sim.status", 0] },
-      "simPlatform": { "$arrayElemAt": ["$sim.platform", 0] },
-      "dataUsage": { "$arrayElemAt": ["$sim.allDataUsage", 0] }
-  }}
-]
-```
-调用（pipeline 作为 JSON 字符串传入）：
-```json
-{ "collection": "SiteInfoManageData", "pipeline": "[{\"$match\":{\"province\":\"Puerto Rico\"}}, ...]" }
-```
-
-#### 配方：按 SIM 流量阈值反向筛出站点信息（如"流量 > 200M 的站点"）
-
-从 SIM 侧起点：先按用量过滤 SIM，再关联回站点，一步得到"高流量站点"清单。
-关键点：起点集合是 `SimCardManage`，用量阈值按 **KB**（200MB = 204800）；
-站点侧 `iccId` 前 19 位才等于 GICCID，故在 `$lookup` 的子 pipeline 里用 `$substrBytes` 对齐后再匹配。
-
-```json
-[
-  { "$match": { "allDataUsage": { "$gt": 204800 } } },
-  { "$lookup": {
-      "from": "SiteInfoManageData",
-      "let": { "giccid": "$_id" },
-      "pipeline": [
-        { "$addFields": { "siteGiccid": { "$substrBytes": ["$iccId", 0, 19] } } },
-        { "$match": { "$expr": { "$eq": ["$siteGiccid", "$$giccid"] } } },
-        { "$project": { "sn": "$_id", "province": 1, "city": 1, "activeStatus": 1 } }
-      ],
-      "as": "sites"
-  }},
-  { "$match": { "sites": { "$ne": [] } } },
-  { "$project": {
-      "giccid": "$_id", "allDataUsage": 1, "platform": 1, "simStatus": "$status",
-      "sites": 1
-  }}
-]
-```
-调用（pipeline 作为 JSON 字符串传入）：
-```json
-{ "collection": "SimCardManage", "pipeline": "[{\"$match\":{\"allDataUsage\":{\"$gt\":204800}}}, ...]" }
-```
-说明：
-- 阈值改其它值时按 KB 换算（见上面「流量单位换算」）。
-- 只关心站点、不关心 SIM 明细时，可在末尾加 `{"$unwind":"$sites"}` + `{"$replaceRoot":{"newRoot":"$sites"}}` 直接输出站点文档。
-- 只要计数（"有多少个这样的站点"）时，末尾用 `{"$unwind":"$sites"}` 后接 `{"$count":"siteCount"}`，不要把明细拉回上下文。
-
-#### 配方：按州统计站点数与激活率
-
-```json
-[
-  { "$group": {
-      "_id": "$province",
-      "total": { "$sum": 1 },
-      "active": { "$sum": { "$cond": [{ "$eq": ["$activeStatus", 1] }, 1, 0] } }
-  }},
-  { "$sort": { "total": -1 } }
-]
-```
-
-#### 约束与反模式
-
-- **跨集合关联必须在库侧一步完成（硬约束）**：凡是"站点 ↔ SIM ↔ 月用量"之间的关联/条件筛选（如"流量>200M的站点""某州站点的SIM状态"），**必须**用 `data_mongo_aggregate` 的 `$lookup` 在数据库侧完成。**禁止**分别 `data_mongo_find`/`data_sim_*` 拉两张表的明细，再在 Agent 上下文里手工遍历、匹配、过滤——这会把大量数据灌入上下文导致膨胀/超时，正是要避免的反模式。
-- 若一次聚合难以表达，可先用 `$match`+`$group`/`$count` 在库侧收敛出**少量键**（如符合条件的 GICCID/SN 列表），再用该小列表做下一步；始终让"大数据量筛选"发生在数据库侧。
-- **不要**用 `$project`/`$group` 把敏感字段（`contactNumber`/`imei`/`longitude` 等）**重命名**成新字段名或拼接进字符串——脱敏按字段名匹配，改名可能绕过脱敏，导致隐私外泄。保留敏感字段原名或直接不输出。
-- `$lookup` 关联大集合时注意被关联集合的关联字段应有索引（`SimCardManage._id`、`SimCardMonthlyData.simId` 已有）。
-- 只需计数/分组时优先 `$group`，不要把明细 `$push` 出来再在 Agent 侧数。
-- 需要把结果交给用户或后续脚本时，按 `localPath` 读取 NDJSON 文件处理。
-
-
-## Redis
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_redis_get` | `key`、`type`(string默认/hash/list/set) | 读取 key 的值（仅支持 string 和 hash） |
-| `data_redis_exists` | `key` | 检查 key 是否存在并返回 TTL |
-
-## PostgreSQL（告警快照）
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_pgsql_query_snapshot_data` | `sn`、`date` | 按 SN 和日期查告警快照数据 |
-| `data_pgsql_query_snapshot_file_record` | `file_name` | 查告警快照文件的解析记录 |
-
-## EMS 参数字典
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_emspara_pid_info` | `id`(PID ID 数字字符串) | 通过 PID ID 查宏名和描述 |
-| `data_emspara_vid_info` | `id`(VID ID 数字字符串) | 通过 VID ID 查宏名和描述 |
-
-用于把 EMS 日志/参数中的数字 PID/VID 翻译成可读含义。
-
-## SIM 上游平台
-
-优先用 `service_sim_*`（见主 SKILL.md 第 4 节）；需上游原始数据时用：
-
-**Acceleronix**
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_sim_acceleronix_card_info` | `iccid` | 单张 SIM 详情 |
-| `data_sim_acceleronix_card_list` | `page`、`size` | SIM 卡列表 |
-| `data_sim_acceleronix_batch_data_info` | `iccid_list`(逗号分隔)、`month`(YYYYMM) | 批量用量信息 |
-| `data_sim_acceleronix_data_pool_list` | `page`、`size` | 流量池列表 |
-| `data_sim_acceleronix_data_pool_sim_info` | `data_pool_id`、`page`、`size` | 流量池中的 SIM 详情 |
-
-**SmartHub**
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_sim_smarthub_card_info` | `giccid` | 单张 SIM 详细信息 |
-| `data_sim_smarthub_batch_info` | `page`、`size` | 批量 SIM 信息 |
-
-注意：Acceleronix 用 `iccid`，SmartHub 用 `giccid`；月份参数 Acceleronix 批量用量为 `YYYYMM`。

deploy/kiro/skills/fwh-toolbox-workflow/references/fwh-pro-api.md

@@ -1,69 +0,0 @@
-# FWH Pro 上游直查 API（`data_fwh_*`）
-
-`data_fwh_*` 直接调用 FranklinWH Pro 的上游 API，返回原始数据，跳过本地 Service 层的聚合与格式化。**全部只读**。
-
-**何时用**：`service_*` 无法满足时，例如需要事件/告警日志、MQTT 日志、故障录波、升级记录明细、告警快照等 service 层未封装的原始数据。
-
-**通用参数约定**：
-- `sn`：站点 SN。
-- 日期：`yyyy-MM-dd`；时间范围：`start_time` / `end_time` 为 `yyyy-MM-dd HH:mm:ss`。
-- `country`：国家 ID，0-全部（默认）、2-美国、3-澳大利亚。
-- `page` / `size`：分页，page 从 1 开始，size 默认 20。
-- ⚠️ 大时间范围的日志类查询（事件/告警、MQTT）可能较慢，尽量收窄时间窗。
-
-## 站点信息
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_fwh_query_site_list` | `sn`(搜索,可空)、`page`、`size` | 站点列表（支持 SN 搜索） |
-| `data_fwh_query_site_base_info_list` | `sn`(多个逗号分隔,可空)、`page`、`size` | 站点基本信息列表 |
-| `data_fwh_query_site_mode_info` | `sn` | 站点工作模式信息 |
-| `data_fwh_query_site_power_flow` | `sn`、`date` | 指定日期功率流数据 |
-
-## 告警
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_fwh_query_site_alarm_list` | `sn` | 站点当前告警列表 |
-| `data_fwh_query_alarm_statistics` | `country`、`page` | 实时告警统计数据 |
-| `data_fwh_query_alarm_statistics_from_code` | `alarm_code`(必填)、`country`、`page` | 按告警码查触发站点列表 |
-| `data_fwh_query_alarm_snapshot` | `sn`、`date` | 站点告警快照信息 |
-| `data_fwh_query_shutdown_list` | `date`(必填)、`country` | Shutdown 站点列表 |
-
-## 日志
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_fwh_query_event_alarm_list` | `sn`、`start_time`、`end_time`、`type`(all/event/alarm) | 时间范围内事件/告警日志 |
-| `data_fwh_query_mqtt_log_list` | `sn`、`cmd_type`(如 0/101/201)、`start_time`、`end_time` | 时间范围内 MQTT 日志 |
-| `data_fwh_query_ems_log_record` | `sn` | EMS 日志召唤记录 |
-
-## 故障录波（Fault Record）
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_fwh_query_fault_record_list` | `sn`、`start_time`、`end_time` | 故障录波日志列表 |
-| `data_fwh_query_fault_record_sub_list` | `fault_id` | 故障录波子记录 |
-| `data_fwh_query_fault_record_callable_list` | `sn`、`dev_type`(0-aPower/1-aGate/2-MPPT/3-aHub，默认1) | 设备可召唤的故障录波数据列表 |
-| `data_fwh_query_fault_record_call_record_list` | 无 | 故障录波召唤记录 |
-
-典型流程：`callable_list` 看可召唤项 → `list` 查已生成录波 → `sub_list` 展开某条记录的子项；`call_record_list` 查召唤动作历史。
-
-## 升级记录
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_fwh_query_system_update_log` | `sn` | 系统升级记录 |
-| `data_fwh_query_system_update_log_detail` | `order_id` | 系统升级记录详情（升级单） |
-| `data_fwh_query_ahub_update_log` | `sn` | aHub 升级记录 |
-
-流程：`system_update_log` 拿到升级单 → 用其 `order_id` 调 `_detail` 看明细。
-
-## TOU 模板（上游）
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `data_fwh_query_tou_template_list` | `search`、`page`、`size` | 上游 TOU 模板列表 |
-| `data_fwh_query_tou_template_detail` | `id` | 上游 TOU 模板详情 |
-
-> 平台本地的 TOU 模板请优先用 `service_tou_template_list` / `service_tou_template_detail`（见主 SKILL.md 第 8 节）。

deploy/kiro/skills/fwh-toolbox-workflow/references/plane-collaboration.md

@@ -1,73 +0,0 @@
-# 反馈协作与 Plane 项目管理
-
-平台通过 Plane 做问题反馈与项目管理。共有三组工具：
-
-- `service_feedback_*` — 面向终端用户的反馈提交（首选）。
-- `data_plane_*` — 平台封装的 Plane **V1 API**，多数无需 workspace/project 参数，直接查当前配置的项目。**只读**。
-- `plane_*` — Plane 官方 MCP 工具，需显式传 `workspace_slug` / `project_id`，覆盖更完整的对象层级。**只读**。
-
-优先级：普通反馈用 `service_feedback_*`；查看/分析项目数据优先 `data_plane_*`（参数少）；需要跨工作空间或更细粒度对象时用 `plane_*`。
-
-## 1. 反馈提交（service_feedback_*）
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `service_feedback_create` **[写操作]** | `title`(必填)、`type`(bug/feature,必填)、`category`、`priority`、`description` | 创建 Plane Intake Issue |
-| `service_feedback_history` | 无 | 查带 Feedback 标签的提交历史 |
-
-- `category`：bug 类 = `bug`/`ui`/`performance`/`other`；feature 类 = `new`/`improvement`/`experience`。
-- `priority`：`urgent`/`high`/`medium`/`low`/`none`（默认 medium）。
-
-## 2. Plane V1 直查（data_plane_*，参数简洁）
-
-项目 / 成员 / 状态 / 标签：
-| 工具 | 参数 |
-|------|------|
-| `data_plane_list_projects` | 无 |
-| `data_plane_get_project` | `project_id` |
-| `data_plane_get_project_summary` | `project_id`、`fields`(逗号分隔) |
-| `data_plane_list_project_members` | 无 |
-| `data_plane_list_workspace_members` | 无 |
-| `data_plane_list_states` | 无 |
-| `data_plane_list_labels` | 无 |
-
-工作项（Work Item）：
-| 工具 | 参数 |
-|------|------|
-| `data_plane_list_work_items` | `assignee`、`label`、`priority`、`state`（均可选过滤） |
-| `data_plane_get_work_item` | `work_item_id` |
-| `data_plane_get_work_item_by_identifier` | `identifier`(如 PROJ)、`sequence_id`(如 42) |
-| `data_plane_search_work_items` | `query`、`limit`(默认20) |
-| `data_plane_list_work_item_activities` | `work_item_id` |
-| `data_plane_list_work_item_comments` | `work_item_id` |
-| `data_plane_list_work_item_attachments` | `work_item_id` |
-| `data_plane_list_work_item_links` | `work_item_id` |
-| `data_plane_list_work_item_relations` | `work_item_id` |
-
-迭代（Cycle） / 模块（Module） / Intake：
-| 工具 | 参数 |
-|------|------|
-| `data_plane_list_cycles` | 无 |
-| `data_plane_get_cycle` | `cycle_id` |
-| `data_plane_list_cycle_issues` | `cycle_id` |
-| `data_plane_list_modules` | 无 |
-| `data_plane_get_module` | `module_id` |
-| `data_plane_list_module_issues` | `module_id` |
-| `data_plane_get_intake_issue_list` | 无 |
-| `data_plane_get_intake_issue_detail` | `intake_id` |
-
-典型流程：`list_projects` → `list_work_items`（按 state/assignee 过滤）→ `get_work_item` + `list_work_item_comments/activities` 看详情；或用 `get_work_item_by_identifier`（PROJ-42）直达。
-
-## 3. Plane 官方工具（plane_*，需 workspace_slug/project_id）
-
-用于需要指定工作空间/项目的场景。先 `plane_list_workspaces` 拿 slug，再 `plane_list_projects` 拿 project_id。
-
-工作空间 / 项目：
-`plane_list_workspaces`(无)、`plane_get_workspace`(`workspace_slug`)、`plane_list_workspace_members`(`workspace_slug`)、`plane_list_stickies`(`workspace_slug`)、`plane_list_projects`(`workspace_slug`)、`plane_get_project`(`workspace_slug`,`project_id`)、`plane_list_project_members`、`plane_list_states`、`plane_list_labels`（后三者均需 `workspace_slug`+`project_id`）。
-
-工作项 / 收件箱：
-`plane_list_issues`(`workspace_slug`,`project_id`)、`plane_get_issue`(+`issue_id`)、`plane_get_issue_activity`(+`issue_id`)、`plane_get_sub_issues`(+`issue_id`)、`plane_list_intake_issues`(`workspace_slug`,`project_id`,`status`)、`plane_get_intake_issue`(+`issue_id`)。
-> `status` 过滤如 `-2,-1,0,1,2`。
-
-迭代 / 模块 / 页面：
-`plane_list_cycles`、`plane_get_cycle`(+`cycle_id`)、`plane_list_modules`、`plane_get_module`(+`module_id`)、`plane_list_pages`、`plane_get_page`(+`page_id`)、`plane_get_page_description`(+`page_id`)（均需 `workspace_slug`+`project_id`，get 类再加对应对象 id）。

deploy/kiro/skills/fwh-toolbox-workflow/references/tou-template.md

@@ -1,240 +0,0 @@
-# TOU 电价模板：构建、字段与规则（`service_tou_template_*`）
-
-用于构建并保存 EMS 调度（TOU）模板。一个模板 = 基础信息 + 一个或多个「季节/日类型」策略；每个策略 = 覆盖一整天的时段列表。对应云端 `updateOrSaveIotTouTemplate` 接口和设备侧 355/357 调度协议。
-
-协议原文（完整语义）：`__WIKI_DOCS__/Software/ScriptingForSchedulingConfiguration.md`
-字段权威定义（Go DTO）：`service/dto/fwhTestTouTemplateDTO.go`
-
-> 只读查询与基本流程见主 SKILL.md 第 8 节。本文件是**写入/构建**时的字段字典与规则。
-
----
-
-## MCP 工具
-
-所有工具都接受可选参数 `env`：`pro`（生产）或 `test`（测试）。
-
-| 工具                          | 用途                                         | env 默认值           |
-| ----------------------------- | -------------------------------------------- | -------------------- |
-| `service_tou_template_list`   | 查询模板列表（按类型/状态/关键字筛选）       | `pro`                |
-| `service_tou_template_detail` | 按`id` 查询单个模板详情                      | `pro`                |
-| `service_tou_template_save`   | 新增/更新模板，返回 templateId**【写操作】** | `test`（当前仅支持） |
-| `service_tou_template_cites`  | 查询某国家下的省/市列表                      | `test`（当前仅支持） |
-
-save 与 cites 目前仅支持 `test`。读操作默认走 `pro`，需要读测试环境时传 `env:"test"`。`cites` 查某国家省/市时需传 `country_id` 且 `type:1`；都不传则返回国家列表。
-
-典型流程：`cites`（拿 countryId/provinceId）→ 构建 payload → `save` → `detail` 校验。
-
----
-
-## 请求体结构（`service_tou_template_save` 的 `payload`）
-
-`payload` 是**字符串化的 JSON**。顶层结构（`FwhTestUpdateOrSaveTouTemplatePayload`）：
-
-```json
-{
-  "template": {
-    /* 模板主体，见下表 */
-  },
-  "strategyList": [
-    {
-      /* 策略，见下表 */
-    }
-  ],
-  "lang": "ZH_CN"
-}
-```
-
-- 字段按真实类型传值：**数值字段传数字（不是字符串）**，字符串字段传字符串。**可选的数值字段未设置时直接省略该 key**（不要传空串 `""`，也不要传 `null`）。
-- `template.templateId`：**创建模板时不需要此字段（省略）；更新模板时必须带此字段并填入模板 ID（数值）**。读取（`detail`/`list` 返回）时该字段必定存在。
-- `template.sourceType`：**必填**（数值）。当前**仅允许写入系统模板 `0`**（`1`API模板 / `2`用户推荐 暂不支持写入，`save` 会拒绝）。
-
-### 1. `template`（模板主体 · `FwhTestTouTemplateInfo`）
-
-| 字段                 | 类型              | 含义 / 取值                                                                                             |
-| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
-| `countryId`          | number            | 国家 ID                                                                                                 |
-| `provinceId`         | number            | 州/省 ID                                                                                                |
-| `derSchdule`         | string            | DER 调度配置                                                                                            |
-| `eleCompanyFullName` | string            | 电力公司全称                                                                                            |
-| `electricCompany`    | string            | 电力公司（简称）                                                                                        |
-| `gridType`           | string            | 电网类型 / 套餐类型                                                                                     |
-| `electricityType`    | number            | 电价类型：`1`分时电价 `2`阶梯电价 `3`固定电价 `4`分时&阶梯电价 `5`BB套餐 `6`Peak Demand                 |
-| `name`               | string            | 模板/策略表名称                                                                                         |
-| `mookRunCount`       | number            | 模式执行次数(loop)：`0`不限次数 `1`执行一次                                                             |
-| `priority`           | number            | 模式优先级，默认`0`；`0` 最低，数字越大优先级越高                                                       |
-| `env`                | number(位域)      | 模式使用条件，默认`0`；bit0~1 光伏；bit2~3 馈网；bit4~5 电网充电                                        |
-| `templateId`         | number            | 模板 ID。**创建时不需要（省略此字段）；更新时必须带上并填 ID**。读取（detail/list）返回时该字段必定存在 |
-| `sourceType`         | number(必填)      | 模板类型。**必填，当前仅允许 `0`系统模板**（`1`API模板 `2`用户推荐 暂不支持写入）                       |
-
-### 2. `strategyList[]`（策略 · `FwhTestTouTemplateStrategy`）
-
-一个策略 = 一组「季节/日类型」+ 覆盖一整天的时段列表。
-
-| 字段           | 类型         | 含义 / 取值                                                      |
-| -------------- | ------------ | ---------------------------------------------------------------- |
-| `ccociateType` | number       | 关联类型：`1`每天 `2`工作日 `3`周末/节假日（与 `dayType`/`dayName` 配套，见下方「日类型配套逻辑」） |
-| `ccociateSn`   | string       | 关联序号：每天为`""`；工作日与其配对的周末/节假日共用同一序号(从 `"0"` 递增) |
-| `detailVoList` | array        | 时段明细表，**所有时段必须覆盖一整天**（见下表）                 |
-| `seasonName`   | string       | 季节名，用于标识策略范围，可自定义，如`summer`、`All months`     |
-| `month`        | string       | 逗号分隔的月份，如`1,2,3,4,5,6,7,8,9,10,11,12`                   |
-| `dayName`      | string       | 日类型可读名：每天=`Every day` 工作日=`Weekdays` 周末/节假日=`Weekends,Holidays`（与 `dayType` 对应） |
-| `dayType`      | number       | 日类型编码：`1`工作日 `2`周末/节假日 `3`每天（可读名见 `dayName`） |
-
-#### 日类型配套逻辑（`ccociateType` / `ccociateSn` / `dayType` / `dayName`）
-
-这四个字段必须成套填写，用于表示策略的「日类型」及工作日与周末/节假日的配对关系：
-
-| 日类型         | `ccociateType` | `ccociateSn`                 | `dayType` | `dayName`             |
-| -------------- | :------------: | ---------------------------- | :-------: | --------------------- |
-| 每天           | `1`            | `""`                         | `3`       | `Every day`           |
-| 工作日         | `2`            | 序号(从 `"0"` 递增)          | `1`       | `Weekdays`            |
-| 周末或节假日   | `3`            | 同组工作日的序号             | `2`       | `Weekends,Holidays`   |
-
-- **每天**是独立策略，无需配对，`ccociateSn` 恒为空串 `""`。
-- **工作日(2) 与 周末/节假日(3) 成对出现**，通过**相同的 `ccociateSn`** 关联为同一组。
-- `ccociateSn` 是从 `"0"` 开始的序号字符串：第一对「工作日+周末/节假日」用 `"0"`，第二对用 `"1"`，以此类推（每新增一对 +1）。
-- 因此，用「每天」时只有 1 条策略；用「工作日/周末」时至少成对出现 2 条策略（一条 `type=2`、一条 `type=3`，共用同一 `ccociateSn`）。
-
-**策略级电价字段（可选）**：以下字段描述该策略各时段的电价，**类型为数值（number）；未设置时直接省略该 key**（不要传 `""` 或 `null`）。
-
-| 字段                     | 类型   | 含义                    |
-| ------------------------ | ------ | ----------------------- |
-| `eleticRatePeak`         | number | 峰时购电电价            |
-| `eleticRateShoulder`     | number | 平时购电电价            |
-| `eleticRateValley`       | number | 谷时购电电价            |
-| `eleticRateSharp`        | number | 尖峰购电电价            |
-| `eleticRateSuperOffPeak` | number | 超低谷购电电价          |
-| `eleticRateGridFee`      | number | 电网附加费              |
-| `eleticSellPeak`         | number | 峰时卖电（上网）电价    |
-| `eleticSellShoulder`     | number | 平时卖电（上网）电价    |
-| `eleticSellValley`       | number | 谷时卖电（上网）电价    |
-| `eleticSellSharp`        | number | 尖峰卖电（上网）电价    |
-| `eleticSellSuperOffPeak` | number | 超低谷卖电（上网）电价  |
-
-### 3. `detailVoList[]`（时段明细 · `FwhTestTouTemplateDetailVo`）
-
-同一策略内的所有时段必须铺满一整天：每个 `endHourTime` 等于下一段的 `startHourTime`，第一段是 `00:00`，最后一段是 `24:00`。**数值字段传数字**（`waveType`、`solarCutoff` 每段必填；功率/SOC/使能等为可选）；**可选数值字段未设置时直接省略该 key**（不要传 `""` 或 `null`）。字符串字段（时间、名称、优先级、`powerOffApower`）传字符串。
-
-| 字段               | 类型              | 含义 / 取值                                                                                                                                                       |
-| ------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `startHourTime`    | string            | 开始时间，格式`HH:mm`，如 `06:30`                                                                                                                                 |
-| `endHourTime`      | string            | 结束时间，格式`HH:mm`；需与下一段 `startHourTime` 衔接，所有时段覆盖一整天                                                                                        |
-| `waveType`         | number(flag,必填) | 峰平谷定义：`0`谷/off-peak `1`平/mid-peak `2`峰/on-peak `3`尖峰/super-on-peak `4`低谷/super-off-peak                                                              |
-| `name`             | string            | 时段名，一般为`supper-off-peak`、`off-peak`、`mid-peak`、`on-peak`、`supper-on-peak` 等                                                                           |
-| `briefDescribe`    | string            | 时段描述，如`Self-consumption`                                                                                                                                    |
-| `solarPriority`    | string            | **光伏供电优先级**，格式 `"市电,负载,FHP"`，如 `"1,3,2"`；优先级 `0/1/2/3`，可相同(表示按比例/功率分配)，`0`=不涉及，数字越大优先级越高                           |
-| `loadPriority`     | string            | **负载取电优先级**，格式 `"市电,光伏,FHP"`，如 `"1,3,2"`；优先级 `0/1/2/3`，可相同(按比例/功率分配)，`0`=不使用此源，数字越大优先级越高                           |
-| `gridDischargeMax` | number(kW,0.1,可选) | 电池最大允许馈网功率；可选，默认`0` 不能馈网；`0`不可馈网，`-1`不限制                                                                                             |
-| `gridChargeMax`    | number(kW,0.1,可选) | 电网允许最大充电功率；可选，默认`0` 不允许；`0`不允许，`-1`不限制                                                                                                 |
-| `chargePower`      | number(kW,0.1,可选) | 固定电池充电功率，按单台功率计算；可选，默认`-1` 未设置                                                                                                           |
-| `dischargePower`   | number(kW,0.1,可选) | 固定电池放电功率，按单台功率计算；可选，默认`-1` 未设置                                                                                                           |
-| `chargeMax`        | number(kW,0.1,可选) | 电池最大允许充电功率，按单台功率计算；`-1`无限制，默认 `-1`                                                                                                       |
-| `dischargeMax`     | number(kW,0.1,可选) | 电池最大允许放电功率，按单台功率计算；`-1`无限制，默认 `-1`                                                                                                       |
-| `gcaoMax`          | number(kW,0.1,可选) | GCAO(grid charge after an outage)：停电后补电至预留 SOC 的单台市电取电功率；可选；`0`不允许，`-1`不限制；默认未设置(`-3`)；使能后未设值则为 `5kw*N`(用 `-2` 标识) |
-| `gridFeedMax`      | number(kW,0.1,可选) | 电网允许最大馈网功率；可选，默认`-2`；`0`不允许，`-1`不限制，`-2`未设置                                                                                           |
-| `gridMax`          | number(kW,0.1,可选) | 电网允许最大取电功率；可选，默认`-1` 不限制；`0`不允许，`-1`不限制                                                                                                |
-| `minDischargeSoc`  | number(%,整数,可选) | 放电截止 SOC；达到此 SOC 后电池不放电，可选，默认`0%`；若 `reserved_soc` 大于此值则以 `reserved_soc` 为准                                                         |
-| `maxChargeSoc`     | number(%,整数,可选) | 充电截止 SOC；可选，默认`100%`                                                                                                                                    |
-| `heatEnable`       | number(可选)      | 充电加热使能：`0`未设置(默认) `1`不使能 `2`使能                                                                                                                   |
-| `powerOffApower`   | string            | 主动关闭 APower；可选，`0`不控制(默认) `1`关机 `2`开机(预留)                                                                                                      |
-| `rampTime`         | number(秒,可选)   | 爬坡时间，`0~300`；默认 `0`，BB套餐默认 `300`                                                                                                                     |
-| `offGrid`          | number(可选)      | 主动断开市电继电器：`0`不控制(默认) `1`断开 `2`闭合(预留)                                                                                                         |
-| `solarCutoff`      | number(必填)      | 主动断开光伏继电器：`0`不控制(默认) `1`断开 `2`闭合(预留)                                                                                                         |
-
-**要点**：
-
-- `solarPriority` / `loadPriority` 是 3 值字符串，顺序 `[市电, 负载或光伏, FHP/aPower]`；`0`=不参与，数字越大优先级越高，相同非 0 值=按比例分配。
-- 功率字段单位 **kW、精度 0.1**，按单台 aPower 计（总功率 = 值 × 台数 N）：`gridChargeMax`、`gridDischargeMax`、`gridFeedMax`、`gridMax`、`chargePower`、`dischargePower`、`chargeMax`、`dischargeMax`、`gcaoMax`。常见哨兵值：`-1`不限制、`0`不允许/不可、`-2`未设置(仅 `gridFeedMax`/`gcaoMax`)、`-3`未设置(仅 `gcaoMax`)。
-
-### 完整 detailVoList 单段示例
-
-未设置的可选功率/SOC 字段直接省略（下例只保留有值字段）：
-
-```json
-{
-  "startHourTime": "00:00",
-  "endHourTime": "11:00",
-  "waveType": 1,
-  "name": "mid-peak",
-  "briefDescribe": "Self-consumption",
-  "solarPriority": "1,3,2",
-  "loadPriority": "1,3,2",
-  "solarCutoff": 0,
-  "powerOffApower": ""
-}
-```
-
-带部分功率设置的示例段（有值传数字，其余省略）：
-
-```json
-{
-  "startHourTime": "18:00",
-  "endHourTime": "21:00",
-  "waveType": 2,
-  "name": "on-peak",
-  "briefDescribe": "Zero Import",
-  "solarPriority": "9,9,9",
-  "loadPriority": "9,9,9",
-  "gridDischargeMax": 0.1,
-  "gridFeedMax": 0.1,
-  "dischargePower": 10,
-  "gridMax": 0,
-  "gcaoMax": 0,
-  "heatEnable": 1,
-  "solarCutoff": 0,
-  "powerOffApower": ""
-}
-```
-
-### selectCitesList 返回结构（`service_tou_template_cites`）
-
-`FwhTestCitesListData`：`countryList` / `provinceList` / `cityList` 三个数组。各项字段（注意此接口返回中 `id` 为**数值**，非字符串）：
-
-| 结构                  | 字段                                                                 |
-| --------------------- | -------------------------------------------------------------------- |
-| `FwhTestCountryInfo`  | `id`(int), `nameEn`, `nameZh`, `latitude`, `longitude`               |
-| `FwhTestProvinceInfo` | `id`(int), `nameEn`, `nameZh`, `latitude`, `longitude`, `cityList[]` |
-| `FwhTestCityInfo`     | `id`(int), `nameEn`, `nameZh`, `latitude`, `longitude`               |
-
----
-
-## 优先级 → 调度策略 速查
-
-常见 `solarPriority`/`loadPriority` 组合及其含义（来自 `templateTable.vue`）：
-
-| 光伏优先级 | 负载优先级 | 策略                                                          |
-| ---------- | ---------- | ------------------------------------------------------------- |
-| `1,2,0`    | `1,3,2`    | A                                                             |
-| `1,2,0`    | `1,2,0`    | B —— 电池不参与调度（光伏优先供载，剩余馈网，市电补充）       |
-| `1,3,2`    | `1,2,0`    | C —— 光伏剩余充电（光伏优先供载，剩余给电池充电，电池不放电） |
-| `1,3,2`    | `1,3,2`    | D —— 自发自用（标准，最常用）                                 |
-| `1,2,3`    | `1,2,0`    | E/G —— 光伏优先充电                                           |
-| `1,2,0`    | `1,2,3`    | F/H —— 电池优先供载                                           |
-
-标准模板（来自 wiki《常规调度配置》）：
-
-- **自发自用**：`solarPriority:"1,3,2"`，`loadPriority:"1,3,2"`，describe `"Self-consumption"`。
-- **仅备电**：`gridChargeMax:"-1"`（不限充），`chargePower:"8"`（约 8kW 满充），describe `"Emergency backup"`。
-- **强制放电/馈网收益**：`gridDischargeMax:"-1"`（不限馈网），`dischargePower:"10"`（约 10kW 满放）。
-
----
-
-## 规则
-
-1. **时间覆盖**：每个策略的 `detailVoList` 必须覆盖 00:00→24:00，无空档、无重叠；`endHourTime` == 下一段 `startHourTime`；时间格式 `HH:mm`。
-2. **按真实类型传值**：数值字段传数字（不是字符串）；可选数值字段未设置时**省略该 key**（不传 `""`、不传 `null`）。字符串字段（时间、名称、优先级、`powerOffApower`）传字符串。
-3. **功率单位是 kW**（步进 0.1），按单台 aPower 计。不要对这些模板字段套用设备侧的 W 或 `5kw*N/-2` 约定。
-4. **优先级是 3 值字符串** `"a,b,c"`，顺序为 `[市电, 负载/光伏, aPower]`。
-5. **新增 vs 更新**：`template.templateId` 留空为新增；填入 ID 为更新。
-6. **写操作走 `test`**：`service_tou_template_save` 仅支持 `env:"test"`。保存前先与用户确认（会修改服务器数据）。保存后用 `service_tou_template_detail`（带 `env:"test"`）校验。
-7. 执行写操作前，需要和用户确认最终写入或更新的信息，确认后才能调用 `service_tou_template_save` 创建或更新
-8. 不确定某国家的 `provinceId` 时，先调用 `service_tou_template_cites` 传 `country_id`（且 `type:1`）。
-
----
-
-## 示例流程：构建一个标准自发自用模板
-
-1. `service_tou_template_cites { "env":"test", "country_id": 3, "type": 1 }` → 选出 `provinceId`。
-2. 构建一个策略（「每天」类型：`ccociateType:1`、`ccociateSn:""`、`dayType:3`、`dayName:"Every day"`），用策略 D（`solarPriority:"1,3,2"`，`loadPriority:"1,3,2"`）铺一整天单一时段，或拆成 off/mid/on-peak 多个时段。若需区分工作日与周末/节假日，则改用成对策略（见「日类型配套逻辑」）。
-3. `service_tou_template_save { "env":"test", "payload": "<json>" }` → 记下返回的 `templateId`。
-4. `service_tou_template_detail { "env":"test", "id": <templateId> }` 确认结果。

deploy/kiro/steering/graphify.md

@@ -1,5 +0,0 @@
----
-inclusion: always
----
-
-graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.

deploy/kiro/steering/mcp-data-guard.md

@@ -1,49 +0,0 @@
----
-inclusion: always
----
-
-# MCP 数据与工作流约束
-
-本 Agent 依赖 MCP 工具（如 `@fwh-tools`）在服务端完成数据查询与分析，目标是**避免把大量原始数据灌入模型上下文**，防止上下文膨胀导致超时。以下规则强制遵守。
-
-## 核心原则：不用大量数据填充上下文
-
-- **禁止**将大批量原始数据（如整表记录、长时间段的功率流/告警明细、成百上千行日志或 CSV）读入上下文，再在模型里做过滤、聚合、统计或计算。这类操作必须交给 MCP 工具在服务端完成，只把**结果或摘要**返回。
-- 需要数据时，优先调用能直接返回结果的 MCP 工具，并**在工具侧完成筛选、分页、聚合**（传入时间范围、站点、limit、聚合维度等参数），只取回必要字段。
-- 不要用「先全量拉取、再自己遍历」的方式绕过工具能力。
-
-## 找不到可用工具时：直接返回，并说明缺口 + 给出建议
-
-当某个工作流**没有对应的 MCP 工具**可用时，**不要**通过读取大量数据 + 在上下文里手工处理的方式去「凑」出结果。应**停止该操作**，并向用户返回一份清晰、简明的说明，必须包含以下三部分：
-
-1. **缺少什么工具/能力**：具体说明缺的是哪一类工具或哪个操作，而不是笼统地说「做不了」。
-   - 说清楚这个工作流需要什么样的能力，例如：「按站点+时间范围聚合功率流的工具」「批量导出告警统计的工具」「对日志做服务端筛选的工具」等。
-   - 若已有相近但不完全匹配的工具，指出它缺哪个参数或维度（如缺少时间范围过滤、缺少聚合选项、缺少分页）。
-
-2. **原本需要它做什么**：一句话说明该工具在此工作流中承担的职责，方便用户判断如何补齐。
-
-3. **给出可行建议**（至少一条）：
-   - 补充/启用对应的 MCP 工具，并简述期望的输入参数与输出（如入参：站点、时间范围、聚合维度；出参：聚合后的结果）；
-   - 缩小数据范围，使其落入「小范围定点读取」的允许区间；
-   - 由用户直接提供已在数据侧聚合好的结果，再由我基于结果继续分析；
-   - 若存在相近工具，建议改用它或为其补充所需参数。
-
-宁可返回「当前无法完成，因为缺少 X 工具」+ 上述说明，也不要为了完成任务而把大量数据塞进上下文。
-
-**建议的回复模板**：
-
-> 这个操作我暂时无法完成，因为缺少可用工具。
-> - 缺少的能力：<具体的工具/操作，例如"按站点与时间范围在服务端聚合功率流的工具">
-> - 它的作用：<在本工作流中负责做什么>
-> - 建议：<补充该 MCP 工具 / 缩小数据范围 / 提供已聚合数据 / 改用相近工具并补参数>
-
-## 判断标准（满足任一即视为"大量数据"，应改走工具或直接告知用户）
-
-- 预计需要读取或处理的数据超过约数百行 / 数十 KB 文本；
-- 需要跨多条记录做聚合、统计、排序、去重等本应由数据层完成的计算；
-- 需要遍历一个时间段的时序数据（功率流、告警、日志等明细）。
-
-## 例外
-
-- 用户**明确要求**查看原始明细，且数据量可控（在上述阈值内）时，可按需返回。
-- 少量、定点的数据读取（单条记录、单个字段、明确的小范围）不受此限制。

deploy/kiro/steering/skill-routing.md

@@ -1,45 +0,0 @@
----
-inclusion: always
----
-
-# 操作前强制路由（动手前必对照）
-
-本表是**门卫**：每轮对话强制注入。执行任何下列操作**之前**，先在本表找到匹配行，
-**必须先读**该行指定的文件，再动手。**任务看起来简单也不例外**——字段名直白 ≠ 没有坑。
-本表只给「触发信号 → 必读文件 → 一句话红线」，完整规则以被指向的文件为准。
-
-> 路径基准：skill 位于 `skills/<name>/`；下表 `references/...` 指对应 skill 目录内的参考文件。
-
-## A. 数据查询（fwh-toolbox-workflow）
-
-| 触发信号（要做什么） | 动手前必读 | 一句话红线 |
-| --- | --- | --- |
-| 直查 `data_mongo_*` 查 `SimCardManage` / `SimCardMonthlyData` | `fwh-toolbox-workflow/references/data-direct-query.md` | `month` 有 `yyyy-MM` 与 `yyyyMM` 双格式并存（用 `$in` 枚举两种，只按一种会漏一半）；用量单位是 **KB**（200MB=204800） |
-| 跨集合关联（站点↔SIM↔月用量）、聚合/分组统计 | `fwh-toolbox-workflow/references/data-direct-query.md` | 必须用 `data_mongo_aggregate` 的 `$lookup` 在库侧一步完成；禁止分别拉表再在上下文里手工匹配 |
-| 使用本地站点信息表（`service_site_query_info` / `_search` / `_monitor_base_info` 及依赖它的分析） | `fwh-toolbox-workflow/SKILL.md` 第 1 节「数据新鲜度检查」 | 开始前先 `service_site_info_update_status` 查新鲜度；≥24h 或更新中要按流程让用户选择，勿直接用旧数据下结论 |
-| 需要 FWH Pro 上游原始数据（`data_fwh_*`） | `fwh-toolbox-workflow/references/fwh-pro-api.md` | 仅在 `service_*` 不足时用，只读 |
-| 任何 `data_*` / 大批量取数 | （always）`mcp-data-guard.md` | 筛选/聚合/分页在工具侧完成，只取回结果/摘要；不要把整表灌进上下文 |
-
-## B. 写操作与业务流程（fwh-toolbox-workflow）
-
-| 触发信号 | 动手前必读 | 一句话红线 |
-| --- | --- | --- |
-| 保存/新增/更新 TOU 电价模板（`service_tou_template_save`） | `fwh-toolbox-workflow/references/tou-template.md` | 写前先向用户摘要确认；**仅 test 环境**可写；时段须覆盖 00:00→24:00；可选数值未设置就省略 key |
-| 任何标注 `[写操作]` 的 `service_*`（同步、创建/更新/删除、触发任务、提交反馈等） | `fwh-toolbox-workflow/SKILL.md` 对应章节 | 执行前先向用户摘要将写入什么、写到哪，取得确认后再调用 |
-| Plane 反馈/项目管理（`service_feedback_*` / `data_plane_*` / `plane_*`） | `fwh-toolbox-workflow/references/plane-collaboration.md` | 按其参数约定与流程执行 |
-
-## C. 文件 / 脚本输出（fwh-toolbox-rules）
-
-| 触发信号 | 动手前必读 | 一句话红线 |
-| --- | --- | --- |
-| 任何 `storage_file_write` / `storage_file_upload` / `storage_file_read*`；给用户下载/导出/生成报告 | `fwh-toolbox-rules/references/file-output-rules.md` | 必传 `userId`+`sessionId`；成功后独占一行输出 `$$FILE_DOWNLOAD:{...}$$`（勿放进代码块） |
-| 通过 `@officecli` 批量写 `.xlsx`/`.docx`/`.pptx` | `fwh-toolbox-rules/references/officecli-batch-rules.md` | **永不**用 `--input -`（stdin 会永久卡住）；批量首选 `batch ... --commands '[...]' --json` |
-| 用公司 PPT 模板生成演示文稿 | `fwh-toolbox-rules/references/ppt-template-rules.md` | 用 `__KIRO_HOME__/templates/company-template.pptx`，先拷到 `/tmp/fwh-toolbox-agent/ppt/` 再编辑 |
-| 需要写 Python3 做数据处理/计算/转换 | `fwh-toolbox-rules/references/python-rules.md` | 仅现成工具无法覆盖时才写；**只能**经 `__KIRO_HOME__/bin/fwh-pyrun` 运行；无网络、仅标准库 |
-
-## 使用规则
-
-1. 命中多行时，逐行都要满足（先读全部相关文件再动手）。
-2. 同一会话中已读过某文件且约束未变，可复用，不必重复读。
-3. 找不到匹配行 ≠ 没有约束：仍需遵守其它 always steering 与对应 skill 的 `description`。
-4. 本表只增指路、不替代正文；正文/reference 与本表冲突时，以正文/reference 为准。

docs/ACP_Protocol_Specification.md

@@ -1,833 +0,0 @@
-# ACP (Agent Client Protocol) 协议详细描述文档
-
-> 基于 `vscode-acp` 项目源码分析提取，SDK 版本：`@agentclientprotocol/sdk ^0.21.1`
-
----
-
-## 1. 协议概述
-
-ACP (Agent Client Protocol) 是一种用于 **AI 编程代理（Agent）与客户端（Client/IDE）之间通信** 的标准化协议。它定义了客户端如何启动、管理和与 AI 代理交互的完整生命周期，类似于 LSP (Language Server Protocol) 的设计理念，但专门面向 AI 代理场景。
-
-### 1.1 核心设计理念
-
-- **进程隔离**：Agent 以独立子进程方式运行，通过 stdin/stdout 与客户端通信
-- **协议版本化**：每次连接通过 `initialize` 握手交换 `protocolVersion`
-- **能力协商**：客户端和代理通过初始化阶段声明各自支持的能力
-- **会话管理**：支持创建、加载、恢复、列举会话
-- **双向通信**：代理可以向客户端发起请求（如文件读写、终端操作、权限请求）
-
-### 1.2 传输层
-
-| 属性       | 描述                                                                        |
-| ---------- | --------------------------------------------------------------------------- |
-| 传输方式   | 子进程的 stdin（写入）/ stdout（读取）                                      |
-| 序列化格式 | **ND-JSON**（Newline Delimited JSON）                                 |
-| 流适配     | Node.js Stream → Web Streams API (`ReadableStream` / `WritableStream`) |
-| SDK 入口   | `ndJsonStream(writable, readable)` 创建双向流                             |
-
----
-
-## 2. 连接生命周期
-
-### 2.1 Agent 进程启动
-
-```
-Client                                          Agent Process
-  |                                                  |
-  |--- spawn(command, args, {stdio: pipe}) --------->|
-  |                                                  |
-  |<========= stdin/stdout pipe established ========>|
-```
-
-Agent 配置结构：
-
-```typescript
-interface AgentConfigEntry {
-  command: string;       // 启动命令，如 "npx"
-  args?: string[];       // 命令行参数
-  env?: Record<string, string>;  // 环境变量
-  displayName?: string;  // 显示名称
-}
-```
-
-### 2.2 初始化握手（Initialize）
-
-连接建立后，客户端必须发送 `initialize` 请求：
-
-**请求方向**：Client → Agent
-
-```typescript
-// 客户端发送的初始化参数
-{
-  protocolVersion: PROTOCOL_VERSION,   // 协议版本号
-  clientInfo: {
-    name: 'vscode-acp-client',         // 客户端名称
-    version: '0.2.0',                  // 客户端版本
-  },
-  clientCapabilities: {
-    fs: {
-      readTextFile: true,              // 支持文件读取
-      writeTextFile: true,             // 支持文件写入
-    },
-    terminal: true,                    // 支持终端操作
-  },
-}
-```
-
-**响应结构** (`InitializeResponse`)：
-
-```typescript
-interface InitializeResponse {
-  agentInfo?: {
-    name: string;         // Agent 名称
-    title?: string;       // Agent 显示标题
-    version?: string;     // Agent 版本
-  };
-  agentCapabilities?: AgentCapabilities;  // Agent 能力声明
-  authMethods?: AuthMethod[];              // 支持的认证方式
-}
-
-interface AgentCapabilities {
-  sessionCapabilities?: {
-    list?: boolean;    // 是否支持 session/list
-    resume?: boolean;  // 是否支持 session/resume
-  };
-  loadSession?: boolean;  // 是否支持 session/load
-}
-
-interface AuthMethod {
-  id: string;           // 认证方式 ID
-  name: string;         // 认证方式名称
-  description?: string; // 认证方式描述
-}
-```
-
-### 2.3 认证流程（Authentication）
-
-当 Agent 需要认证时（错误码 `-32000`），客户端启动认证流程：
-
-```
-Client                                Agent
-  |                                     |
-  |-- newSession() ------------------->|
-  |<-- Error: auth required (-32000) --|
-  |                                     |
-  |-- authenticate({methodId}) ------->|
-  |<-- success ------------------------|
-  |                                     |
-  |-- newSession() (retry) ----------->|
-  |<-- NewSessionResponse -------------|
-```
-
-认证请求：
-
-```typescript
-{ methodId: string }  // 用户选择的认证方式 ID
-```
-
----
-
-## 3. 会话管理（Session Management）
-
-### 3.1 创建新会话（session/new）
-
-**请求方向**：Client → Agent
-
-```typescript
-// 请求参数
-interface NewSessionRequest {
-  cwd: string;              // 工作目录路径
-  mcpServers: any[];        // MCP 服务器列表（当前为空数组）
-}
-
-// 响应
-interface NewSessionResponse {
-  sessionId: string;                       // 会话唯一标识
-  modes?: SessionModeState;                // 可用模式（legacy）
-  models?: SessionModelState;              // 可用模型（experimental）
-  configOptions?: SessionConfigOption[];   // 通用配置选项（新版，优先级高于 modes/models）
-}
-```
-
-### 3.2 列举会话（session/list）
-
-**前提**：Agent 在初始化时声明 `sessionCapabilities.list = true`
-
-```typescript
-// 请求参数
-interface ListSessionsRequest {
-  cwd?: string;      // 按工作目录过滤
-  cursor?: string;   // 分页游标
-}
-
-// 响应
-interface ListSessionsResponse {
-  sessions: SessionInfo[];   // 会话列表
-  nextCursor?: string;       // 下一页游标（分页）
-}
-
-interface SessionInfo {
-  sessionId: string;
-  title?: string;
-  createdAt?: string;
-  updatedAt?: string;
-}
-```
-
-### 3.3 加载会话（session/load）
-
-**前提**：Agent 声明 `loadSession = true`
-
-重量级操作，完整重放会话历史：
-
-```typescript
-// 请求参数
-interface LoadSessionRequest {
-  sessionId: string;
-  cwd: string;
-  mcpServers: any[];
-}
-
-// 响应（同 NewSessionResponse）
-interface LoadSessionResponse {
-  modes?: SessionModeState;
-  models?: SessionModelState;
-  configOptions?: SessionConfigOption[];
-}
-```
-
-加载过程中 Agent 会通过 `session/update` 通知回放所有历史消息。
-
-### 3.4 恢复会话（session/resume）
-
-**前提**：Agent 声明 `sessionCapabilities.resume = true`
-
-轻量级操作，不回放历史：
-
-```typescript
-// 请求参数
-interface ResumeSessionRequest {
-  sessionId: string;
-  cwd: string;
-  mcpServers: any[];
-}
-
-// 响应
-interface ResumeSessionResponse {
-  modes?: SessionModeState;
-  models?: SessionModelState;
-  configOptions?: SessionConfigOption[];
-}
-```
-
----
-
-## 4. 对话交互（Prompt/Response）
-
-### 4.1 发送提示（prompt）
-
-**请求方向**：Client → Agent
-
-```typescript
-// 请求参数
-interface PromptRequest {
-  sessionId: string;
-  prompt: ContentBlock[];    // 内容块数组
-}
-
-interface ContentBlock {
-  type: 'text';              // 内容类型
-  text: string;              // 文本内容
-}
-
-// 响应
-interface PromptResponse {
-  stopReason: string;   // 停止原因："end_turn" | "error" | "cancelled" 等
-  usage?: {             // Token 用量统计（可选）
-    // 具体字段取决于 Agent 实现
-  };
-}
-```
-
-### 4.2 取消当前轮次（cancel）
-
-**请求方向**：Client → Agent
-
-```typescript
-interface CancelRequest {
-  sessionId: string;
-}
-```
-
----
-
-## 5. 会话实时通知（Session Notifications）
-
-Agent 通过 `session/update` 向客户端推送实时状态更新。这是 ACP 协议中最丰富的通知机制。
-
-**通知方向**：Agent → Client
-
-```typescript
-interface SessionNotification {
-  sessionId: string;
-  update: SessionUpdate;  // 更新内容（以下各种类型之一）
-}
-```
-
-### 5.1 消息流（Streaming）
-
-#### `agent_message_chunk` — Agent 文本流式输出
-
-```typescript
-{
-  sessionUpdate: 'agent_message_chunk',
-  content: {
-    type: 'text',
-    text: string     // 增量文本片段
-  }
-}
-```
-
-#### `user_message_chunk` — 用户消息回放（仅 session/load 使用）
-
-```typescript
-{
-  sessionUpdate: 'user_message_chunk',
-  content: {
-    type: 'text',
-    text: string
-  }
-}
-```
-
-#### `agent_thought_chunk` — Agent 思维过程流式输出
-
-```typescript
-{
-  sessionUpdate: 'agent_thought_chunk',
-  content: {
-    type: 'text',
-    text: string     // 思考过程增量文本
-  }
-}
-```
-
-### 5.2 工具调用（Tool Calls）
-
-#### `tool_call` — 新工具调用
-
-```typescript
-{
-  sessionUpdate: 'tool_call',
-  toolCallId: string,        // 工具调用唯一ID
-  title: string,             // 工具调用标题/描述
-  status: 'pending' | 'running' | 'completed' | 'failed'
-}
-```
-
-#### `tool_call_update` — 工具调用状态更新
-
-```typescript
-{
-  sessionUpdate: 'tool_call_update',
-  toolCallId: string,        // 对应的工具调用ID
-  status: 'pending' | 'running' | 'completed' | 'failed',
-  title?: string             // 可选的标题更新
-}
-```
-
-### 5.3 计划（Plan）
-
-#### `plan` — Agent 执行计划
-
-```typescript
-{
-  sessionUpdate: 'plan',
-  entries: PlanEntry[]
-}
-
-interface PlanEntry {
-  title?: string;
-  description?: string;
-  content?: string;
-  status: 'pending' | 'in_progress' | 'completed'
-}
-```
-
-### 5.4 会话配置更新
-
-#### `current_mode_update` — 模式变更通知
-
-```typescript
-{
-  sessionUpdate: 'current_mode_update',
-  currentModeId: string     // 新的当前模式 ID
-}
-```
-
-#### `config_option_update` — 配置选项全量更新
-
-```typescript
-{
-  sessionUpdate: 'config_option_update',
-  configOptions: SessionConfigOption[]   // 完整的配置选项数组
-}
-```
-
-#### `available_commands_update` — 可用命令更新
-
-```typescript
-{
-  sessionUpdate: 'available_commands_update',
-  availableCommands: AvailableCommand[]
-}
-
-interface AvailableCommand {
-  name: string;              // 命令名（用于 /slash 命令）
-  description: string;       // 命令描述
-  input?: {
-    hint?: string;           // 输入提示文字
-  };
-}
-```
-
-#### `session_info_update` — 会话元信息更新
-
-```typescript
-{
-  sessionUpdate: 'session_info_update',
-  title?: string | null,     // 会话标题（null 表示清除）
-  updatedAt?: string | null  // 最后更新时间（ISO 格式）
-}
-```
-
----
-
-## 6. Agent → Client 请求（反向调用）
-
-Agent 可以向客户端发起以下请求，由客户端实现 `Client` 接口来处理。
-
-### 6.1 文件系统操作
-
-#### `readTextFile` — 读取文本文件
-
-```typescript
-// 请求
-interface ReadTextFileRequest {
-  path: string;        // 文件绝对路径
-  line?: number;       // 起始行号（1-based）
-  limit?: number;      // 读取行数限制
-}
-
-// 响应
-interface ReadTextFileResponse {
-  content: string;     // 文件内容
-}
-```
-
-**实现特性**：
-
-- 优先读取编辑器中未保存的内容（dirty buffer）
-- 支持行范围读取（line + limit）
-
-#### `writeTextFile` — 写入文本文件
-
-```typescript
-// 请求
-interface WriteTextFileRequest {
-  path: string;        // 文件绝对路径
-  content: string;     // 要写入的内容
-}
-
-// 响应
-interface WriteTextFileResponse {}  // 空响应表示成功
-```
-
-**实现特性**：
-
-- 自动创建父目录
-- 写入后在编辑器中打开文件
-
-### 6.2 终端操作
-
-#### `createTerminal` — 创建终端
-
-```typescript
-// 请求
-interface CreateTerminalRequest {
-  command: string;             // 要执行的命令
-  args?: string[];             // 命令参数
-  cwd?: string;               // 工作目录
-  env?: EnvVar[];              // 环境变量列表
-  outputByteLimit?: number;    // 输出缓冲区大小限制（默认 1MB）
-}
-
-interface EnvVar {
-  name: string;
-  value: string;
-}
-
-// 响应
-interface CreateTerminalResponse {
-  terminalId: string;          // 终端唯一标识
-}
-```
-
-#### `terminalOutput` — 获取终端输出
-
-```typescript
-// 请求
-interface TerminalOutputRequest {
-  terminalId: string;
-}
-
-// 响应
-interface TerminalOutputResponse {
-  output: string;              // 累积的输出内容
-  truncated: boolean;          // 是否因超出限制被截断
-  exitStatus?: {               // 进程已退出时提供
-    exitCode: number | null;
-    signal: string | null;
-  };
-}
-```
-
-#### `waitForTerminalExit` — 等待终端退出
-
-```typescript
-// 请求
-interface WaitForTerminalExitRequest {
-  terminalId: string;
-}
-
-// 响应
-interface WaitForTerminalExitResponse {
-  exitCode: number | null;
-  signal: string | null;
-}
-```
-
-#### `killTerminal` — 终止终端
-
-```typescript
-// 请求
-interface KillTerminalRequest {
-  terminalId: string;
-}
-
-// 响应
-interface KillTerminalResponse {}  // 空响应
-```
-
-#### `releaseTerminal` — 释放终端资源
-
-```typescript
-// 请求
-interface ReleaseTerminalRequest {
-  terminalId: string;
-}
-
-// 响应
-interface ReleaseTerminalResponse {}  // 空响应
-```
-
-**实现特性**：
-
-- 如果进程仍在运行，先发送 SIGTERM
-- VS Code 终端保持可见（不自动关闭），符合 ACP 规范
-
-### 6.3 权限请求
-
-#### `requestPermission` — 请求用户授权
-
-```typescript
-// 请求
-interface RequestPermissionRequest {
-  toolCall?: {
-    title?: string;            // 权限请求标题
-  };
-  options: PermissionOption[]; // Agent 提供的选项列表
-}
-
-interface PermissionOption {
-  optionId: string;            // 选项唯一 ID
-  name: string;                // 选项显示名称
-  kind: 'allow_once' | 'allow_always' | 'deny' | string;  // 选项类型
-}
-
-// 响应
-interface RequestPermissionResponse {
-  outcome: {
-    outcome: 'selected' | 'cancelled';
-    optionId?: string;         // 用户选择的选项 ID
-  };
-}
-```
-
----
-
-## 7. 会话配置系统
-
-### 7.1 Session Mode（模式 — Legacy）
-
-```typescript
-interface SessionModeState {
-  currentModeId: string;
-  availableModes: SessionMode[];
-}
-
-interface SessionMode {
-  id: string;
-  name: string;
-  description?: string;
-}
-```
-
-**设置模式**：Client → Agent
-
-```typescript
-// setSessionMode 请求
-{ sessionId: string; modeId: string; }
-```
-
-### 7.2 Session Model（模型 — Experimental）
-
-```typescript
-interface SessionModelState {
-  currentModelId: string;
-  availableModels: SessionModel[];
-}
-
-interface SessionModel {
-  modelId: string;
-  name: string;
-  description?: string;
-}
-```
-
-**设置模型**：Client → Agent（unstable API）
-
-```typescript
-// unstable_setSessionModel 请求
-{ sessionId: string; modelId: string; }
-```
-
-### 7.3 Session Config Options（通用配置选项 — 推荐）
-
-这是取代 modes/models 的新统一 API。当 Agent 同时提供 `configOptions` 和 `modes` 时，客户端**必须**仅使用 `configOptions`。
-
-```typescript
-interface SessionConfigOption {
-  id: string;                              // 配置项唯一 ID
-  type: 'select';                          // 配置类型（目前仅支持 select）
-  name: string;                            // 配置项名称
-  description?: string;                    // 配置项描述
-  category: 'mode' | 'model' | 'thought_level' | string;  // 分类
-  currentValue: string;                    // 当前值
-  options: SelectOption[] | GroupedOptions[];  // 可选值列表
-}
-
-interface SelectOption {
-  value: string;
-  name: string;
-  description?: string;
-}
-
-interface GroupedOptions {
-  group: string;
-  name?: string;
-  options: SelectOption[];
-}
-```
-
-**设置配置选项**：Client → Agent
-
-```typescript
-// setSessionConfigOption 请求
-{
-  sessionId: string;
-  configId: string;
-  value: string;
-}
-
-// 响应 — 包含更新后的完整 configOptions（级联更新）
-{
-  configOptions: SessionConfigOption[];
-}
-```
-
----
-
-## 8. 协议错误码
-
-| 错误码     | 含义                     | 触发场景                                                |
-| ---------- | ------------------------ | ------------------------------------------------------- |
-| `-32000` | 需要认证 (Auth Required) | `newSession` / `listSessions` 调用时 Agent 需要认证 |
-
-错误通过 `RequestError` 类传递：
-
-```typescript
-class RequestError extends Error {
-  code: number;
-  message: string;
-}
-```
-
----
-
-## 9. 完整交互流程示例
-
-```
-┌─────────┐                                    ┌─────────┐
-│  Client │                                    │  Agent  │
-└────┬────┘                                    └────┬────┘
-     │                                              │
-     │──── spawn process (stdin/stdout pipe) ──────>│
-     │                                              │
-     │──── initialize ─────────────────────────────>│
-     │<─── InitializeResponse (agentInfo, caps) ────│
-     │                                              │
-     │──── newSession({cwd, mcpServers}) ──────────>│
-     │<─── NewSessionResponse {sessionId, modes} ───│
-     │                                              │
-     │<─── session/update: available_commands ───────│
-     │<─── session/update: config_option_update ────│
-     │                                              │
-     │──── prompt({sessionId, prompt}) ────────────>│
-     │                                              │
-     │<─── session/update: agent_thought_chunk ─────│ (思考过程)
-     │<─── session/update: agent_thought_chunk ─────│
-     │                                              │
-     │<─── session/update: tool_call ───────────────│ (工具调用)
-     │                                              │
-     │<─── requestPermission ───────────────────────│ (请求权限)
-     │──── {outcome: 'selected', optionId} ────────>│
-     │                                              │
-     │<─── readTextFile({path}) ────────────────────│ (读取文件)
-     │──── {content} ──────────────────────────────>│
-     │                                              │
-     │<─── writeTextFile({path, content}) ──────────│ (写入文件)
-     │──── {} ─────────────────────────────────────>│
-     │                                              │
-     │<─── createTerminal({command, args}) ─────────│ (创建终端)
-     │──── {terminalId} ───────────────────────────>│
-     │                                              │
-     │<─── waitForTerminalExit({terminalId}) ───────│
-     │──── {exitCode} ────────────────────────────>│
-     │                                              │
-     │<─── session/update: tool_call_update ────────│ (工具完成)
-     │<─── session/update: agent_message_chunk ─────│ (回复内容)
-     │<─── session/update: agent_message_chunk ─────│
-     │                                              │
-     │<─── PromptResponse {stopReason: 'end_turn'}──│
-     │                                              │
-     │<─── session/update: session_info_update ─────│ (标题更新)
-     │                                              │
-     │──── cancel({sessionId}) ────────────────────>│ (可选：取消)
-     │                                              │
-     │──── [kill process] ─────────────────────────>│ (断开连接)
-     │                                              │
-```
-
----
-
-## 10. Agent 注册表
-
-ACP 提供了公共的 Agent 注册表服务：
-
-- **注册表地址**：`https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`
-- **缓存策略**：客户端缓存 5 分钟
-
-注册表数据结构：
-
-```typescript
-interface Registry {
-  agents: RegistryAgent[];
-}
-
-interface RegistryAgent {
-  name: string;
-  description?: string;
-  command: string;
-  args?: string[];
-  homepage?: string;
-}
-```
-
----
-
-## 11. 已知兼容的 ACP Agent
-
-| Agent 名称     | 命令         | 参数                                                        |
-| -------------- | ------------ | ----------------------------------------------------------- |
-| GitHub Copilot | `npx`      | `@github/copilot-language-server@latest --acp`            |
-| Claude Code    | `npx`      | `@agentclientprotocol/claude-agent-acp@latest`            |
-| Gemini CLI     | `npx`      | `@google/gemini-cli@latest --experimental-acp`            |
-| Qwen Code      | `npx`      | `@qwen-code/qwen-code@latest --acp --experimental-skills` |
-| Auggie CLI     | `npx`      | `@augmentcode/auggie@latest --acp`                        |
-| Qoder CLI      | `npx`      | `@qoder-ai/qodercli@latest --acp`                         |
-| Codex CLI      | `npx`      | `@zed-industries/codex-acp@latest`                        |
-| OpenCode       | `npx`      | `opencode-ai@latest acp`                                  |
-| OpenClaw       | `npx`      | `openclaw acp`                                            |
-| Kiro CLI       | `kiro-cli` | `acp`                                                     |
-| Hermes Agent   | `hermes`   | `acp`                                                     |
-
----
-
-## 12. 客户端能力声明（Client Capabilities）
-
-客户端在 `initialize` 时声明支持的能力：
-
-```typescript
-interface ClientCapabilities {
-  fs?: {
-    readTextFile?: boolean;   // 支持 Agent 读取文件
-    writeTextFile?: boolean;  // 支持 Agent 写入文件
-  };
-  terminal?: boolean;          // 支持 Agent 操作终端
-}
-```
-
-Agent 据此判断可以向客户端发起哪些反向请求。
-
----
-
-## 13. 协议设计特点总结
-
-1. **基于 JSON-RPC 风格**：请求-响应模式 + 通知模式
-2. **ND-JSON 传输**：轻量级，易于解析和调试
-3. **流式输出**：通过 `*_chunk` 通知实现实时流式展示
-4. **双向通信**：Agent 既接收指令，也可主动向客户端发起操作请求
-5. **能力协商**：初始化时双方声明能力，避免调用不支持的功能
-6. **认证集成**：支持多种认证方式，认证失败后自动重试
-7. **会话持久化**：支持会话的创建、列举、加载（回放历史）和轻量恢复
-8. **配置灵活性**：从 legacy modes/models 到统一的 configOptions，平滑演进
-9. **权限控制**：Agent 操作需要用户授权，支持自动批准策略
-10. **版本化设计**：通过 `protocolVersion` 确保客户端和代理的兼容性
-
----
-
-## 14. 附录：消息流方向汇总
-
-| 方法                         | 方向            | 类型         | 说明                 |
-| ---------------------------- | --------------- | ------------ | -------------------- |
-| `initialize`               | Client → Agent | Request      | 协议握手             |
-| `authenticate`             | Client → Agent | Request      | 认证                 |
-| `newSession`               | Client → Agent | Request      | 创建会话             |
-| `listSessions`             | Client → Agent | Request      | 列举会话             |
-| `loadSession`              | Client → Agent | Request      | 加载会话（重放历史） |
-| `resumeSession`            | Client → Agent | Request      | 恢复会话（无重放）   |
-| `prompt`                   | Client → Agent | Request      | 发送提示             |
-| `cancel`                   | Client → Agent | Request      | 取消当前轮次         |
-| `setSessionMode`           | Client → Agent | Request      | 设置模式             |
-| `setSessionConfigOption`   | Client → Agent | Request      | 设置配置选项         |
-| `unstable_setSessionModel` | Client → Agent | Request      | 设置模型             |
-| `session/update`           | Agent → Client | Notification | 会话状态推送         |
-| `readTextFile`             | Agent → Client | Request      | 读取文件             |
-| `writeTextFile`            | Agent → Client | Request      | 写入文件             |
-| `createTerminal`           | Agent → Client | Request      | 创建终端             |
-| `terminalOutput`           | Agent → Client | Request      | 获取终端输出         |
-| `waitForTerminalExit`      | Agent → Client | Request      | 等待终端退出         |
-| `killTerminal`             | Agent → Client | Request      | 终止终端             |
-| `releaseTerminal`          | Agent → Client | Request      | 释放终端             |
-| `requestPermission`        | Agent → Client | Request      | 请求用户授权         |

docs/ai-assistant-agentserver/README.md

@@ -2,8 +2,6 @@
 
 本目录是 ToolBox **新 AI 助手**的需求与设计。新助手基于 AgentServer（`~/web/AgentServer`，自托管的 Claude Code / Codex Agent 服务）：对话、事件、文件、审批、沙箱由 AgentServer 提供，ToolBox 负责入口、鉴权、会话归属，业务数据由新建的、无用户状态的 MCP 服务 fwh-agent-mcp 提供。
 
-新助手与旧 Kiro 助手**相互独立**：新代码、新数据集合、新 MCP 服务，不修改、不复用旧助手；两者可并存，旧助手的下线另行决定。
-
 当前状态：需求与设计初稿（2026-10-24），尚未编码。AgentServer 已支持第三方 MCP 服务（ADR-0021）；还需要一处通用的结果处理改动（agent-mcp 5.2）。
 
 建议阅读顺序：requirements → technical-design → ui-design → agent-mcp。
@@ -15,11 +13,10 @@
 | [requirements.md](requirements.md) | 新助手的目标、功能与非功能需求、待确认事项 | 确定做什么、讨论验收范围时 |
 | [technical-design.md](technical-design.md) | 总体架构、ToolBox 前后端新模块（会话归属与代理）、AgentServer 配置、技能、实施步骤与验收用例 | 实现 ToolBox 侧、排期时 |
 | [ui-design.md](ui-design.md) | 独立页面的路由与菜单、三栏布局、欢迎页、交互细节、主题与代码结构 | 实现或评审前端页面时 |
-| [agent-mcp.md](agent-mcp.md) | fwh-agent-mcp：定位、与旧 MCP 的区别、框架、工具清单、大数据处理、部署与接入、写工具规划 | 实现业务工具时 |
-| [legacy-kiro-assistant.md](legacy-kiro-assistant.md) | 旧助手的实现、能力清单与问题 | 核对新助手要覆盖的能力时 |
+| [agent-mcp.md](agent-mcp.md) | fwh-agent-mcp：定位、框架、工具清单、大数据处理、部署与接入、写工具规划 | 实现业务工具时 |
 
 AgentServer 自身的设计以其仓库 `docs/` 为准，重点参考：`docs/integration.md`、`docs/design/04-api.md`、`docs/design/08-platform-connectors.md`、`docs/adr/0021-third-party-mcp-via-gateway.md`、`docs/design/06-security.md`。
 
 ## 维护方式
 
-范围变化更新 `requirements.md` 并关闭对应待确认条目；ToolBox 侧设计变化写入 `technical-design.md`，页面调整写入 `ui-design.md`，MCP 设计变化写入 `agent-mcp.md`；`legacy-kiro-assistant.md` 只描述旧助手，不随新代码更新。编码开始后另建 `implementation-status.md`。
+范围变化更新 `requirements.md` 并关闭对应待确认条目；ToolBox 侧设计变化写入 `technical-design.md`，页面调整写入 `ui-design.md`，MCP 设计变化写入 `agent-mcp.md`。编码开始后另建 `implementation-status.md`。

docs/ai-assistant-agentserver/agent-mcp.md

@@ -1,6 +1,6 @@
 # FWH Agent MCP：设计
 
-> 状态：设计初稿，2026-10-24。基于 ToolBox master `a10cbda`、AgentServer `969a993`（ADR-0021 第三方 MCP 服务）。本文描述为新 AI 助手**新建**的 MCP Server（下称 Agent MCP），与旧助手的 `service/cmd/mcp` 无关：旧 MCP 保持现状继续服务 Kiro，新 MCP 不复用其工具代码。
+> 状态：设计初稿，2026-10-24。基于 ToolBox master `a10cbda`、AgentServer `969a993`（ADR-0021 第三方 MCP 服务）。本文描述为新 AI 助手**新建**的 MCP Server（下称 Agent MCP）。
 
 ## 1. 定位
 
@@ -10,17 +10,15 @@ Agent MCP 是 FWH 业务数据的**无用户状态的工具服务**：
 - 由 AgentServer 后台“MCP 服务”登记为远程 HTTP 服务（ADR-0021），经 MCP Gateway 转接给 Agent。Gateway 用固定请求头连接、多个会话共用连接，本来就不传会话信息，与“无用户”的定位一致。
 - 谁能用、能用到什么程度，由 ToolBox 和 AgentServer 在上层控制：ToolBox 决定用户能否使用 AI 助手、创建会话时选用哪个 Profile；Profile 决定勾选哪些 MCP 服务；AgentServer 按工具策略决定是否审批。调用追溯走“ToolBox 会话归属 → AgentServer 审计（gateway_call 含参数）”，见 [technical-design.md](technical-design.md)。
 
-### 1.1 为什么不沿用旧 MCP
+### 1.1 框架带来的约束
 
-| 旧 MCP 的做法 | 在新框架下的问题 |
+| 约束 | 对工具设计的要求 |
 | --- | --- |
-| 工具参数里带 `userId`/`sessionId`，由模型填写（`storage_*`、反馈、批量下载 owner 等） | 身份不可信；新框架不传用户信息，参数失去意义 |
-| 大结果写到 `/tmp/fwh-toolbox-agent/results` 并返回本地路径 | AgentServer 的 Agent 在沙箱里，看不到这个目录 |
-| 文件经 MinIO `upload/`、`download/` 前缀与 Agent 交换 | 新框架的上传和产出都在 AgentServer 会话工作区 |
-| 222 个工具都没有声明 `readOnlyHint` | ADR-0021 默认策略下全部变成“跟随权限模式”，每次查询都弹审批；逐个手工设置也难以维护 |
-| 大量一对一包装接口和原始存储访问（`data_mongo_*`、`data_redis_*`、`data_pgsql_*`、Plane 全量接口） | 工具多、描述短，模型选错工具；原始访问的结果大、难控制 |
-| 只有 stdio | 只能作为本地进程接入；本地进程在 AgentServer 的 bwrap 沙箱中运行，要开放网络和读取 `.env`，不合适 |
-| 依赖 Kiro steering 中的路由表决定用哪个工具 | 新框架没有 steering，工具描述要能自解释 |
+| AgentServer 不向 MCP 传用户信息 | 工具参数不带 `userId`/`sessionId`，身份由上层控制 |
+| Agent 在 AgentServer 沙箱中运行，看不到 MCP 所在机器的本地目录；上传与产出文件都在会话工作区 | 大结果不能写本地文件再返回路径，要以导出资源交给 Agent（第 5 节） |
+| ADR-0021 默认策略下，未声明 `readOnlyHint` 的工具“跟随权限模式”，每次查询都弹审批 | 每个工具都声明注解，由约束测试保证 |
+| stdio 本地进程要在 bwrap 沙箱中运行，需开放网络和读取 `.env` | 只提供远程 HTTP 接入 |
+| 没有外部路由表；工具多、描述短或暴露原始存储访问时，模型容易选错工具，结果也难控制 | 任务粒度、描述自解释（第 2 节） |
 
 ## 2. 设计原则
 
@@ -55,7 +53,7 @@ service/
       readonly.go                只读工具集
       ops.go                     写工具集（第 7 节，二期）
     agentmcp_test.go             约束测试（第 3.5 节）
-  utils/pii/                     从 cmd/mcp/tools/helper 的 pii_*.go 拷贝为独立包（旧 MCP 不改）
+  utils/pii/                     PII 脱敏（独立包）
 ```
 
 一个进程、一个端口加载多个工具集，按路径区分（`-set` 逗号分隔，省略时加载全部）：
@@ -152,7 +150,7 @@ schema 由 mcp-go 依赖的 `google/jsonschema-go` 生成：`jsonschema` 标签
 
 统一限制：单次结果（非导出）不超过 30,000 字符；超过时按行截断并标明 `truncated`，附一句“请缩小范围或使用 xxx_export”。这样不会触发 AgentServer 的 10 万字截断（那条路径会把前 10 万字仍放进上下文）。
 
-所有对象和行在序列化前经过 `utils/pii` 脱敏（规则沿用旧 MCP：用户姓名、电话、邮箱、详细地址等）。
+所有对象和行在序列化前经过 `utils/pii` 脱敏（用户姓名、电话、邮箱、详细地址等）。
 
 ### 3.4 中间件与运行约束
 
@@ -276,8 +274,8 @@ ADR-0021 的结果处理（`mcp-gateway/server.ts` 的 `postProcess`）目前：
 ### 6.1 Agent MCP
 
 - systemd 单元 `fwh-agent-mcp.service`：`fwh-agent-mcp -set=readonly,ops -listen=127.0.0.1:8091`，工作目录与主服务相同。
-- 独立配置文件 `config.agent-mcp.env`（`-config` 可指定，示例 `deploy/config.agent-mcp.env.example`）：`AGENT_MCP_TOKEN`（Bearer 令牌）、`AGENT_MCP_TOKEN_<工具集大写>`（可选，单个工具集的令牌）、`AGENT_MCP_MAX_CONCURRENCY`（每个工具集各自计数）、`AGENT_MCP_LOG_PATH`，以及工具用到的数据库、Redis、FWH 生产/测试 API、Plane Web。不读主服务的 `config.env` 与旧 MCP 的 `config.mcp.env`，只放自己需要的凭证；文件缺失时拒绝启动。
-- 部署脚本：新增 `service/cmd/deploy_agent_mcp.sh`（构建、拷贝、重启），不改动旧 MCP 的 `deploy_mcp.sh`。
+- 独立配置文件 `config.agent-mcp.env`（`-config` 可指定，示例 `deploy/config.agent-mcp.env.example`）：`AGENT_MCP_TOKEN`（Bearer 令牌）、`AGENT_MCP_TOKEN_<工具集大写>`（可选，单个工具集的令牌）、`AGENT_MCP_MAX_CONCURRENCY`（每个工具集各自计数）、`AGENT_MCP_LOG_PATH`，以及工具用到的数据库、Redis、FWH 生产/测试 API、Plane Web。不读主服务的 `config.env`，只放自己需要的凭证；文件缺失时拒绝启动。
+- 部署脚本：`service/cmd/deploy_agent_mcp.sh`（构建、拷贝、重启）。
 - AgentServer 与 ToolBox 不在同一台机器时，监听内网地址，防火墙只放行 AgentServer 主机（见 requirements Q-01）。
 
 ### 6.2 AgentServer 登记
@@ -315,7 +313,7 @@ Profile `fwh-assistant` 勾选 `fwh`。工具使用的业务说明（字段含
 
 | 编号 | 问题 | 建议 |
 | --- | --- | --- |
-| Q-01 | 一期工具清单（第 4 节）是否覆盖主要使用场景，是否有遗漏的高频查询 | 按旧助手的调用日志统计高频工具补充 |
+| Q-01 | 一期工具清单（第 4 节）是否覆盖主要使用场景，是否有遗漏的高频查询 | 按 AgentServer 审计中的工具调用统计高频查询补充 |
 | Q-02 | 是否需要原始存储查询工具（Mongo / PG） | 一期不做；收集到具体场景后补任务级工具 |
 | Q-03 | 故障录波、日志包等二进制数据是否需要交给 Agent 分析 | 先提供解析后的 CSV；原始文件待 5.2 改动后再评估 |
 | Q-04 | 5.2 的 AgentServer 改动是否接受 | 建议做，导出类工具依赖它 |

docs/ai-assistant-agentserver/legacy-kiro-assistant.md

@@ -1,83 +0,0 @@
-# 旧 AI 助手（Kiro）参考
-
-> 状态：2026-10-23 梳理，基于 master `a10cbda`。新 AI 助手与旧助手**相互独立**，不修改、不复用旧助手的代码和 MCP；本文只用于核对新助手需要覆盖的能力（第 4 节）和需要避免的问题（第 5 节）。新助手的需求见 [requirements.md](requirements.md)。
-
-## 1. 架构概览
-
-```
-浏览器（顶栏 AiChat 抽屉，自写聊天 UI）
-  │ POST /ai/chat（SSE）、/ai/sessions/*、/ai/permission、/ai/files/*
-  ▼
-ToolBox Go 后端（Fiber）
-  ACPManager：每个用户一个 kiro-cli 子进程（降权到 KIRO_RUN_AS_USER）
-  │ JSON-RPC over stdio（ACP 协议 + _kiro.dev/* 扩展）
-  ▼
-kiro-cli acp --agent fwh-toolbox-agent
-  ├─ 内置工具：read / write / grep / glob / code / shell(白名单) / web_* / knowledge / subagent …
-  ├─ knowledgeBase：FranklinWH-Wiki 文档（语义索引）
-  ├─ skills / steering：deploy/kiro/
-  └─ MCP（stdio）：fwh-tools（./fwh-mcp-server，222 个工具）、drawio、officecli、markitdown
-                    │
-                    └─ PostgreSQL / MongoDB / Redis / FWH 云平台 API / Plane / SIM 平台 / MinIO
-```
-
-## 2. 代码入口
-
-| 层 | 位置 | 现状 |
-| --- | --- | --- |
-| 前端入口 | `src/layout/header/Actions/AiChat/index.vue` | 顶栏按钮 + 可拖拽宽度的 NDrawer |
-| 前端面板 | `ChatPanel.vue`、`MessageItem.vue` | 自写消息列表、工具标签、权限卡片、文件下载按钮、会话列表 |
-| 前端逻辑 | `useAiChat.ts`（916 行） | 手写 SSE 解析；`$$FILE_DOWNLOAD$$` 标记解析为下载片段；剥离 `[context]` 前缀 |
-| 前端缓存 | `chatDB.ts` | IndexedDB 缓存会话消息（服务端只有 Kiro 回放，没有完整事件流） |
-| 前端 API | `src/service/aiChat/index.ts` | 13 个接口（见第 3 节） |
-| 路由/控制器 | `service/routes/aiChatRoutes.go`、`service/controllers/aiChatControllers.go` | SSE 输出、文件上传下载（MinIO） |
-| 会话管理 | `service/services/aiChatServices.go` | 内存 map（userId → 会话 + 子进程）、Redis 活跃会话与历史列表（上限 50）、Mongo 会话记录 |
-| ACP 客户端 | `service/utils/acp/acp.go`（1569 行） | 进程管理、JSON-RPC、session/update 映射、反向请求（readTextFile/writeTextFile 走 MinIO，权限请求转前端，10 分钟超时拒绝） |
-| 文件存储 | `service/utils/filestore/`、`service/utils/agentfiles/` | MinIO `upload/`、`download/` 前缀按 userId/sessionId 隔离；`/tmp/fwh-toolbox-agent` 定时清理 |
-| MCP Server | `service/cmd/mcp/`（设计见 `DESIGN.md`） | stdio；PII 脱敏、大结果落盘到 `/tmp/fwh-toolbox-agent/results`、调用日志 |
-| Agent 配置 | `deploy/kiro/agents/fwh-toolbox-agent.json` | 工具白名单、shell 正则白名单、读写路径、MCP 定义 |
-| 技能/引导 | `deploy/kiro/skills/fwh-toolbox-{rules,workflow}/`、`deploy/kiro/steering/*.md` | 操作路由表、数据防护规则、TOU/Plane/直连查询参考、PPT/Python/文件输出规范 |
-| 部署 | `deploy/scripts/{install_kiro_cli,deploy_kiro_cli,sync_kiro_config}.sh` | 安装 kiro-cli、同步配置并替换 `__WIKI_DOCS__` 等占位符 |
-| 配置 | `service/.env`：`KIRO_RUN_AS_USER`、`KIRO_HOME`、`KIRO_DEBUG_LOG` | `service/main.go` 调用 `controllers.InitAIChat` |
-
-## 3. 后端接口
-
-| 接口 | 用途 |
-| --- | --- |
-| `POST /ai/chat` | 发消息，SSE 返回 `session_info`、`welcome`、`text`、`tool_call`、`tool_update`、`permission`、`metadata`、`done`、`error` |
-| `GET /ai/sessions/list`、`GET /ai/sessions/current` | 会话列表；当前会话的 agent / model / 上下文用量 |
-| `POST /ai/sessions/new`、`POST /ai/sessions/:id`、`GET /ai/sessions/:id/load` | 新建；切换（重启子进程并 session/load）；SSE 推送回放消息 |
-| `PATCH`、`DELETE /ai/sessions/:id` | 改标题；删除（超过 50 条时调用 `kiro-cli chat --delete-session`） |
-| `POST /ai/cancel`、`POST /ai/permission` | 取消本轮；回复权限请求 |
-| `POST /ai/files/upload`、`GET /ai/files/download`、`GET /ai/files/list` | 上传（≤2MB，文本）、下载、列出 MinIO 中的上传/产出文件 |
-
-## 4. 现有能力清单
-
-新助手需要覆盖的能力（编号供 requirements 引用）：
-
-| 编号 | 能力 | 实现方式 |
-| --- | --- | --- |
-| C-01 | 流式对话、思考过程 | ACP `agent_message_chunk` / `agent_thought_chunk`（思考与正文混在同一文本流） |
-| C-02 | 工具调用展示 | `tool_call` / `tool_call_update`，`acp.DescribeTool` 生成中文简述 |
-| C-03 | 业务数据查询与操作 | fwh-tools MCP：站点、告警、停机、功率流、录波、MQTT/EMS 日志、TOU 模版、SIM、Plane、Mongo/PG/Redis 直查、批量下载、站点分析、自动升级配置等 |
-| C-04 | 产品知识问答 | Kiro knowledgeBase 索引 FranklinWH-Wiki Markdown |
-| C-05 | 文件上传分析 | 上传到 MinIO，Agent 经 `readTextFile` 反向请求读取；仅文本、≤2MB |
-| C-06 | 报告/文档生成 | Python（`fwh-pyrun`）、officecli、drawio MCP 生成到 `/tmp/fwh-toolbox-agent`，再经 MCP 上传 MinIO；回复中输出 `$$FILE_DOWNLOAD$$` 标记供前端渲染下载按钮 |
-| C-07 | 写操作审批 | Kiro 权限请求 → 前端卡片 → `/ai/permission` |
-| C-08 | 会话管理 | 新建、切换、回放、改标题、删除；按 ToolBox 登录用户隔离 |
-| C-09 | 取消 | `/ai/cancel` → ACP `session/cancel`；连接断开时也取消 |
-| C-10 | 提交反馈 | MCP `service_feedback_create` → Plane Intake |
-| C-11 | 数据防护 | MCP 侧 PII 脱敏、大结果落盘；steering 禁止把大批量数据读进上下文 |
-
-## 5. 问题清单
-
-| 编号 | 问题 |
-| --- | --- |
-| P-01 | **维护成本高**：ACP 客户端、Kiro 扩展通知、会话恢复、回放、进程降权都由 ToolBox 自己维护，Kiro 协议或版本变化需要跟着改（`acp.go` 1569 行 + `useAiChat.ts` 916 行）。 |
-| P-02 | **资源模型**：每个在线用户常驻一个 kiro-cli 子进程，切换会话要重启进程；没有全局并发上限和排队。 |
-| P-03 | **身份靠提示词传递**：`[context] userId=…, sessionId=…` 拼在用户消息前，MCP 工具的 `userId`/`sessionId` 由模型自己填写，可被省略或伪造；前端还要剥离这段前缀。 |
-| P-04 | **写操作审批不完整**：`allowedTools` 中 `@fwh-tools` 整体自动信任，`service_tou_template_save`、`service_auto_update_delete_*`、`service_site_info_update_status` 等写工具调用时没有人工确认。 |
-| P-05 | **事件不完整、不可续传**：服务端只有 Kiro 的回放文本，工具调用、权限记录不落库；前端用 IndexedDB 补；SSE 断开即丢失本轮输出。 |
-| P-06 | **文件链路绕**：产出文件靠模型在回复里输出 `$$FILE_DOWNLOAD$$` 标记，漏写或写错就没有下载入口；上传只支持 2MB 文本，不支持截图、Excel、PDF。 |
-| P-07 | **沙箱弱**：隔离依赖 Kiro 的工具白名单和 shell 正则，没有 OS 级沙箱；`read` 允许 `./**`（服务目录，含 `.env`）。 |
-| P-08 | **可观测性弱**：没有按会话的用量统计、审计日志和管理后台，调试依赖 `KIRO_DEBUG_LOG` 打开 kiro-chat.log。 |

docs/ai-assistant-agentserver/requirements.md

@@ -1,21 +1,19 @@
 # 新 AI 助手：需求
 
-> 状态：需求初稿，2026-10-24（取代 10-23 的“迁移”版本：新助手与旧 Kiro 助手相互独立，业务工具改用无用户状态的新 MCP）。实现方式见 [technical-design.md](technical-design.md) 与 [agent-mcp.md](agent-mcp.md)；旧助手的能力与问题见 [legacy-kiro-assistant.md](legacy-kiro-assistant.md)。
+> 状态：需求初稿，2026-10-24（业务工具使用无用户状态的新 MCP）。实现方式见 [technical-design.md](technical-design.md) 与 [agent-mcp.md](agent-mcp.md)。
 
 ## 1. 目标与范围
 
 在 ToolBox 中新建一个基于 AgentServer 的 AI 助手：
 
-1. 业务能力覆盖旧助手的主要场景（legacy 第 4 节 C-01～C-11）；
+1. 业务能力覆盖主要场景：流式对话与工具调用展示、业务数据查询、产品知识问答、文件上传分析、报告/文档生成、写操作审批、会话管理、取消、提交反馈、数据防护（PII 脱敏、大结果不进上下文）；
 2. Agent 运行、事件、文件、审批、沙箱都交给 AgentServer，ToolBox 只负责入口、鉴权、会话归属和业务数据工具；
-3. 业务数据工具是新建的、无用户状态的 MCP 服务；
-4. 与旧助手相互独立：不修改、不复用旧助手的代码、数据和 MCP，两者可以同时使用，旧助手的下线另行决定。
+3. 业务数据工具是新建的、无用户状态的 MCP 服务。
 
 **范围内**：ToolBox 新前端模块与后端模块、新 MCP 服务 fwh-agent-mcp、AgentServer 上的 Profile / 技能 / 资料库 / MCP 服务配置，以及 AgentServer 结果处理的一处通用改动（agent-mcp 5.2）。
 
 **范围外**：
 
-- 旧助手的任何改动和数据迁移（Kiro 会话不迁移）；
 - 模型凭证（ToolBox 只作为 AgentServer API 的调用方）；
 - 一期不做写操作工具（agent-mcp 第 7 节）；
 - Codex 引擎（引擎固定 Claude，由 Profile 决定）。
@@ -25,7 +23,6 @@
 ### FR-01 页面与对话
 
 - 新助手以独立的大页面展示：左侧菜单新增“AI 助手”，不放在顶栏右上角；页面布局为会话栏、对话区、文件栏（[ui-design.md](ui-design.md)）。
-- 旧助手的顶栏入口保持不变，两者并存。
 - 流式显示正文；思考过程单独折叠。
 - 工具调用以卡片显示中文标题、参数摘要和状态（运行中 / 成功 / 失败 / 拒绝），可展开查看结果。
 - 可中断当前运行；切换标签页、关闭标签页或刷新页面都不中断运行，回到会话后从断点继续显示。
@@ -82,7 +79,6 @@
 | NF-03 追溯 | 每次工具调用可追溯到 ToolBox 用户：ToolBox 会话归属 → AgentServer 审计（gateway_call 含参数） |
 | NF-04 并发 | 多用户同时使用时排队而非失败；fwh-agent-mcp 有自己的并发上限，保护业务系统 |
 | NF-05 性能 | 单个查询工具 60 秒内返回（导出 300 秒）；超时给出明确错误 |
-| NF-06 独立 | 新模块上线、下线不影响旧助手；新代码不引用旧助手的包 |
 
 ## 4. 待确认事项
 
@@ -92,7 +88,6 @@
 | Q-02 | 新助手对哪些角色开放、是否需要按角色区分 Profile | 先对所有登录用户开放同一个只读 Profile |
 | Q-03 | 每用户会话数量上限与保留期 | 50 条；更早的会话在 AgentServer 侧归档 |
 | Q-04 | Wiki 知识库同步频率 | 已定：复制到 `/srv/agent-server/knowledge/`，需要时手动运行同步脚本，不配置定时任务 |
-| Q-05 | 旧助手何时下线 | 新助手验收后观察一段时间再定 |
 | Q-06 | drawio 图表能力是否需要 | 先不做，按反馈决定 |
 
 MCP 相关的待确认事项见 [agent-mcp.md](agent-mcp.md) 第 8 节。

docs/ai-assistant-agentserver/technical-design.md

@@ -4,12 +4,11 @@
 
 ## 1. 总体架构
 
-新助手是 ToolBox 中**独立的新模块**：独立的入口、前后端代码、数据集合和 MCP 服务；旧 Kiro 助手（[legacy-kiro-assistant.md](legacy-kiro-assistant.md)）原样保留，两者互不调用、互不共享数据。
+新助手是 ToolBox 中**独立的模块**：独立的入口、前后端代码、数据集合和 MCP 服务。
 
 ```
 浏览器（ToolBox）
-  ├─ 旧：顶栏 AiChat → /ai/*（不改动）
-  └─ 新：菜单「AI 助手」页面（/ai-assistant）→ 会话栏 + <AgentChat> + 文件栏
+  └─ 菜单「AI 助手」页面（/ai-assistant）→ 会话栏 + <AgentChat> + 文件栏
          │ @agent-server/client：baseUrl = <ToolBox API>/agent，Authorization = ToolBox 登录令牌
          ▼
 ToolBox Go 后端（新模块 agent）
@@ -38,7 +37,7 @@ FWH 云 API / PostgreSQL / MongoDB / Redis / Plane / SIM 平台
 
 | 编号 | 决策 | 理由 |
 | --- | --- | --- |
-| D-01 | 新助手与旧助手完全分开：新路由前缀 `/agent`、新集合、新前端目录、新 MCP 服务 | 旧助手可以继续使用到新助手验收完成，下线时直接删除整块旧代码，没有交叉依赖 |
+| D-01 | 新助手是独立模块：路由前缀 `/agent`、独立集合、独立前端目录、独立 MCP 服务 | 与 ToolBox 其他业务代码没有交叉依赖，可以单独上线、调整 |
 | D-02 | 业务工具用**无用户状态**的新 MCP（agent-mcp.md） | AgentServer Gateway 以固定请求头连接 MCP、多会话共用连接，不传会话信息；身份由上层控制更简单可靠 |
 | D-03 | 用户隔离在 ToolBox 后端实现：浏览器只持有 ToolBox 登录令牌，所有 AgentServer 请求经代理并校验会话归属 | AgentServer 不区分使用者，同一 API Key 下的会话彼此可见；API Key 不出后端 |
 | D-04 | 用户能力差异通过 **Profile** 表达：ToolBox 创建会话时按用户角色选择 Profile，Profile 决定技能、资料库和勾选的 MCP 服务 | MCP 无用户后，权限边界上移到“会话用哪个 Profile” |
@@ -58,8 +57,6 @@ FWH 云 API / PostgreSQL / MongoDB / Redis / Plane / SIM 平台
 | `service/controllers/agentControllers.go` | HTTP 处理 |
 | `service/routes/agentRoutes.go` | 路由注册（`routes.go` 中调用 `AgentSetup`） |
 
-不引用 `utils/acp`、`services/aiChatServices.go`、`utils/filestore` 等旧助手代码。
-
 ### 3.2 配置
 
 ```
@@ -75,7 +72,7 @@ API Key 在 AgentServer 后台签发时，勾选上述全部 Profile 为可用
 
 ### 3.3 数据
 
-`AgentSessions`（新集合，不复用 `AiChatSessions`）：
+`AgentSessions`（新集合）：
 
 | 字段 | 说明 |
 | --- | --- |
@@ -133,8 +130,6 @@ API Key 在 AgentServer 后台签发时，勾选上述全部 Profile 为可用
 
 新助手是菜单路由 `/ai-assistant` 下的独立大页面（左侧会话栏、中间对话、右侧文件栏），不放在顶栏。路由、布局、交互与代码结构见 [ui-design.md](ui-design.md)；代码在 `src/views/ai-assistant/` 与 `src/service/agent/`。
 
-不修改顶栏的 `Actions/AiChat/` 和 `src/service/aiChat/`，旧助手入口保持不变。
-
 ### 4.2 客户端
 
 ```ts
@@ -163,11 +158,11 @@ const client = new AgentClient({
 
 ## 6. 技能 `fwh-assistant`
 
-从头编写，旧的 `deploy/kiro/skills/`、`deploy/kiro/steering/` 只作为素材，不迁移、不改动。内容：
+从头编写，内容：
 
 - **业务背景**：产品线（aGate、aPower 等）、站点与设备的关系、SN 规则、时区与单位约定；
 - **工具使用**：每类问题的推荐工具组合（例如“站点故障排查：`site_get` → `alarm_events` → `mqtt_log_search` → `fault_record_list`”）；何时用 `*_export` 并在工作区用 pandas 分析；
-- **数据防护**：不把大批量明细读进上下文（原 `mcp-data-guard.md` 的规则，改写为面向新工具）；工具不足时说明缺口，不用其他方式拼凑；
+- **数据防护**：不把大批量明细读进上下文；工具不足时说明缺口，不用其他方式拼凑；
 - **产出规范**：报告结构、图表、公司 PPT 模版 `templates/company-template.pptx`（随技能分发）；产出写入 `outputs/`；
 - **references/**：告警码与事件说明、TOU 模版字段（来自调度配置文档）、功率流字段解读等，按需读取。
 
@@ -183,8 +178,7 @@ const client = new AgentClient({
 | S4 | 技能 `fwh-assistant`、资料库同步、Profile、API Key；在 Playground 回归第 8 节业务用例 | S1、S2 | Playground 通过 |
 | S5 | ToolBox 后端新模块：配置、集合、会话接口、代理 | — | 接口与代理单测通过 |
 | S6 | ToolBox 前端新页面（ui-design.md） | S5 | 本地联调通过 |
-| S7 | 测试环境上线，新页面与旧助手并存，用户验收第 8 节用例 | S4～S6 | 验收通过 |
-| S8 | 决定旧助手下线时间；下线时删除旧助手全部代码、`cmd/mcp`、`deploy/kiro/`、Kiro 配置与部署脚本 | S7 | 单独评审 |
+| S7 | 测试环境上线，用户验收第 8 节用例 | S4～S6 | 验收通过 |
 
 S1～S4（MCP 与 AgentServer 侧）和 S5～S6（ToolBox 前后端）可以并行。
 
@@ -202,4 +196,3 @@ S1～S4（MCP 与 AgentServer 侧）和 S5～S6（ToolBox 前后端）可以并
 | T-07 | 配置了角色映射时，不同角色的用户新建会话使用不同 Profile；无权使用的用户看不到“AI 助手”菜单、接口返回 403 | Profile 选择 |
 | T-08 | 让 Agent 读取 ToolBox `service/.env`、`~/.ssh`：被拦截并写入 AgentServer 审计 | 沙箱 |
 | T-09 | 重启 ToolBox 后端、AgentServer、fwh-agent-mcp 后，历史会话时间线完整且可继续对话；fwh-agent-mcp 停止时，工具返回“暂不可用”而不是挂起 | 可恢复 |
-| T-10 | 旧 AI 助手在新模块上线后功能不受影响 | 相互独立 |

docs/ai-assistant-agentserver/ui-design.md

@@ -10,7 +10,7 @@
 {
   path: 'ai-assistant',
   name: 'aiAssistant',
-  icon: 'i-ph:sparkle',          // 与旧助手的 i-ph:chat-circle-dots 区分
+  icon: 'i-ph:sparkle',
   label: 'AI 助手',
   meta: {
     componentName: 'AiAssistant',
@@ -24,7 +24,6 @@
 - 当前会话写在查询参数 `?session=ses_xxx`（切换会话时 `router.replace`）：刷新页面、从浏览器历史返回都能回到同一个会话；链接发给别人时，对方打开会因归属校验失败而回到新会话。
 - 页面组件名为 `AiAssistant`，进入标签页的 KeepAlive：切换到其他标签时组件不销毁，进行中的回答继续接收；关闭标签时 `dispose` 订阅（运行本身不中断，下次打开从断点继续显示）。
 - 菜单可见性按现有菜单权限机制配置为 FR-03 允许的角色；`AGENT_ENABLED=false` 时不注册该菜单。
-- 旧助手顶栏按钮保持不变，两者并存。
 
 ## 2. 布局
 
@@ -123,5 +122,3 @@ src/views/ai-assistant/
     useSessionFiles.ts         文件列表与 file.changed 刷新
 src/service/agent/index.ts     /agent/sessions/* 接口
 ```
-
-不修改 `src/layout/header/Actions/AiChat/`、`src/service/aiChat/`。

docs/ai-assistant-plan.md

@@ -1,1226 +0,0 @@
-# FranklinWH-ToolBox AI 助手方案
-
-## 1. 协议栈说明
-
-| 协议                             | 用途                   | 状态                               |
-| -------------------------------- | ---------------------- | ---------------------------------- |
-| **MCP** (Model Context Protocol) | AI Agent ↔ 工具/数据源 | Kiro CLI 原生支持，主力协议        |
-| **A2A** (Agent2Agent Protocol)   | Agent ↔ Agent 协作     | Linux Foundation 维护，v1.0 已发布 |
-| ~~ACP~~                          | ~~Agent 通信~~         | 2025.8 已合并入 A2A，不再独立存在  |
-
-**建议：** 项目内 AI 助手核心是 **Kiro CLI + 自定义 MCP Server**。如果后续需要多 Agent 协作再引入 A2A。
-
----
-
-## 2. 现有系统架构
-
-### 2.1 前端（src/）
-
-| 项目       | 说明                                             |
-| ---------- | ------------------------------------------------ |
-| 框架       | Vue 3 + TypeScript + Vite                        |
-| UI 库      | Naive UI                                         |
-| 状态管理   | Pinia（自定义 defineSetupStore 模板）            |
-| 样式       | UnoCSS (Tailwind 兼容)                           |
-| 图表       | @antv/g2                                         |
-| HTTP       | 自定义 FetchClient（支持拦截器、download、blob） |
-| 代码编辑器 | Monaco Editor                                    |
-
-**前端目录结构：**
-
-```
-src/
-├── composable/        # 组合式函数
-├── components/        # 公共组件
-├── event/             # 事件系统
-├── injection/         # 依赖注入
-├── router/            # 路由配置
-├── service/           # API 层（按模块分目录：feedback/, siteInfoManage/, simCardManage/ 等）
-├── stores/            # Pinia Store（modules/data/, modules/views/）
-├── theme/             # 主题配置
-├── types/             # 全局类型
-├── utils/             # 工具函数
-└── views/             # 页面视图（按功能模块分目录）
-    ├── feedback/
-    ├── site-info-manage/
-    ├── sites-monitor/
-    ├── sim-card-manage/
-    ├── batch-download/
-    └── ...
-```
-
-### 2.2 后端（service/）
-
-| 项目     | 说明                                                                   |
-| -------- | ---------------------------------------------------------------------- |
-| 框架     | Go + Fiber v2                                                          |
-| 数据库   | MongoDB + PostgreSQL + MySQL                                           |
-| 缓存     | Redis（自定义 cache 层）                                               |
-| 对象存储 | MinIO                                                                  |
-| 任务队列 | Asynq (Redis-based)                                                    |
-| 外部 API | FranklinWH Energy API、Plane V2 Web API、Acceleronix API、SmartHub API |
-| 认证     | Casdoor JWT                                                            |
-| MQTT     | FWH Pro MQTT                                                           |
-
-**后端目录结构：**
-
-```
-service/
-├── main.go                 # 入口（初始化所有依赖 + 启动 HTTP 服务）
-├── config/                 # 配置加载（Viper，从 .env 读取）
-├── controllers/            # HTTP 路由处理器（Fiber Handler）
-├── services/               # 业务逻辑层
-├── repositories/           # 数据访问层
-│   ├── mongo/              # MongoDB 操作
-│   ├── redis/              # Redis 操作
-│   ├── pgsql/              # PostgreSQL 操作
-│   ├── mysql/              # MySQL 操作
-│   ├── api/                # 外部 API 客户端
-│   │   ├── fwh_pro/        # FranklinWH Energy/OSS API
-│   │   ├── plane_v1/       # Plane V1 API（API Key 认证）
-│   │   ├── plane_v2/       # Plane V2 Web API（Session 认证）
-│   │   ├── acceleronix/    # Acceleronix SIM 卡 API
-│   │   └── smartHub/       # SmartHub SIM 卡 API
-│   ├── mqtt/               # MQTT 通信
-│   └── events/             # 事件通信（xLog TCP）
-├── routes/                 # 路由注册
-├── middleware/             # 中间件（认证等）
-├── domain/                 # 领域模型
-├── dto/                    # 数据传输对象
-├── database/               # 数据库连接初始化
-├── cache/                  # Redis 缓存封装
-├── task/                   # 任务队列（Asynq）
-├── scheduler/              # 定时任务
-├── jobs/                   # 后台作业
-└── utils/                  # 工具包
-```
-
-### 2.3 后端各层职责
-
-```
-HTTP Request
-    │
-    ▼
-┌──────────────┐
-│ controllers/ │  解析参数、校验、调用 service、返回 JSON
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│  services/   │  业务逻辑编排、数据转换、调用多个 repository
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│repositories/ │  数据库 CRUD、外部 API 调用、缓存操作
-└──────────────┘
-```
-
----
-
-## 3. 整体架构（AI 助手视角）
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        开发者终端                                  │
-│                        Kiro CLI                                   │
-│                    (AI Agent / Host)                              │
-└────────────┬────────────────────────────────┬────────────────────┘
-             │ MCP (stdio)                    │ MCP (stdio)
-             ▼                                ▼
-┌────────────────────────┐      ┌──────────────────────────────┐
-│   内部工具 MCP Server   │      │      外部服务 MCP Server      │
-│        (Go)            │      │        (社区开源)              │
-├────────────────────────┤      ├──────────────────────────────┤
-│• query_site_info       │      │• AWS Docs 搜索               │
-│• search_sites          │      │• Brave 网络搜索              │
-│• query_sim_card        │      └──────────────────────────────┘
-│• query_power_flow      │
-│• create_plane_issue    │
-│• query_plane_issues    │
-│• query_alarm_stats     │
-└────────────┬───────────┘
-             │ 直接 import 复用
-             ▼
-┌────────────────────────────────────────────────────────────────┐
-│                    现有后端 service/ 代码                         │
-├────────────────────────────────────────────────────────────────┤
-│  services/          │  repositories/         │  domain/dto     │
-│  (业务逻辑)         │  (数据访问+外部API)     │  (数据模型)      │
-└─────────┬───────────┴──────────┬─────────────┴─────────────────┘
-          │                      │
-          ▼                      ▼
-┌──────────────┐  ┌──────────────────────────────────────────────┐
-│  MongoDB     │  │  外部系统                                      │
-│  PostgreSQL  │  │  • FranklinWH Energy API                      │
-│  Redis       │  │  • Plane V2 Web API                           │
-│  MinIO       │  │  • Acceleronix / SmartHub API                 │
-└──────────────┘  └──────────────────────────────────────────────┘
-```
-
-### 3.1 MCP Tools Server 与现有后端的关系
-
-**核心原则：MCP Tools Server 是现有后端 service 层的另一个入口，不是独立系统。**
-
-| 对比     | 现有 HTTP Server (`main.go`)          | MCP Tools Server                   |
-| -------- | ------------------------------------- | ---------------------------------- |
-| 入口     | Fiber HTTP 路由                       | stdio JSON-RPC                     |
-| 调用方   | 前端浏览器                            | Kiro CLI (AI Agent)                |
-| 认证     | Casdoor JWT                           | 无需（本地 stdio 进程）            |
-| 复用层   | controllers → services → repositories | **直接调用 services/repositories** |
-| 输出格式 | JSON HTTP Response                    | MCP Tool Result (text/JSON)        |
-
-**具体复用方式：**
-
-```go
-// MCP Tools Server 的 go.mod 中引用现有 service 模块
-// 方式一：同一 module，不同 main 入口
-//   service/cmd/mcp/main.go  (MCP Server 入口)
-//   service/main.go          (HTTP Server 入口)
-
-// 方式二：独立 module，replace 引用
-// mcp-servers/tools/go.mod:
-//   require fwh-toolbox-server v0.0.0
-//   replace fwh-toolbox-server => ../../service
-```
-
-**推荐方式一**（同一 module）：在 `service/cmd/mcp/` 下创建 MCP Server 入口，共享整个 service 代码库。
-
-```
-service/
-├── main.go                    # 现有 HTTP Server 入口
-├── cmd/
-│   └── mcp/
-│       └── main.go            # MCP Tools Server 入口
-├── services/                  # 共享：业务逻辑
-├── repositories/              # 共享：数据访问
-├── domain/                    # 共享：领域模型
-├── dto/                       # 共享：DTO
-├── config/                    # 共享：配置
-├── database/                  # 共享：数据库连接
-└── cache/                     # 共享：缓存
-```
-
-**MCP Server 入口初始化流程：**
-
-```go
-// service/cmd/mcp/main.go
-func main() {
-    // 1. 加载配置（同 HTTP Server）
-    cfg, _ := config.LoadConfig()
-
-    // 2. 初始化数据库连接（同 HTTP Server）
-    database.Init(&cfg.App)
-    cache.Init(cfg.App.RedisAddr)
-    repositories.PlaneWebHttpInit(&cfg.PlaneWebApi)
-
-    // 3. 创建 MCP Server（替代 Fiber HTTP 路由）
-    s := server.NewMCPServer("fwh-tools", "1.0.0",
-        server.WithToolCapabilities(false),
-        server.WithRecovery(),
-    )
-
-    // 4. 注册 Tools（调用 services/ 层函数）
-    tools.RegisterSiteInfoTools(s)
-    tools.RegisterSimCardTools(s)
-    tools.RegisterPowerFlowTools(s)
-    tools.RegisterAlarmTools(s)
-    tools.RegisterShutdownTools(s)
-    tools.RegisterPlaneTools(s)
-
-    // 5. 启动 stdio 通信（替代 app.Listen）
-    server.ServeStdio(s)
-}
-```
-
-**不需要的部分：**
-
-- 不需要 Fiber 框架
-- 不需要 controllers/ 层（MCP handler 直接调用 services）
-- 不需要 middleware/（stdio 无需 HTTP 认证）
-- 不需要 routes/（MCP 用 tool 注册替代）
-
----
-
-## 4. 知识库 MCP Server（独立 VitePress 项目）
-
-知识库是一个独立的 VitePress 文档项目，通过 `vitepress-plugin-mcp` 插件将文档暴露为 MCP Server。
-
-### 4.1 概述
-
-| 项目     | 说明                                               |
-| -------- | -------------------------------------------------- |
-| 位置     | 独立 Git 仓库（不在 FranklinWH-ToolBox 内）        |
-| 框架     | VitePress（Markdown 文档站）                       |
-| 内容     | 团队知识：编码规范、架构模板、技术文档、最佳实践等 |
-| MCP 插件 | `vitepress-plugin-mcp`（npm 包）                   |
-| MCP 传输 | Streamable HTTP（远程 MCP Server）                 |
-| 配置层级 | `./.kiro/settings/mcp.json`（后端运行目录级别）    |
-
-### 4.2 VitePress 知识库项目搭建
-
-**Step 1：创建 VitePress 项目**
-
-```bash
-mkdir team-knowledge && cd team-knowledge
-pnpm init
-pnpm add -D vitepress vitepress-plugin-mcp
-mkdir docs
-```
-
-**Step 2：编写文档内容**
-
-```
-team-knowledge/
-├── docs/
-│   ├── index.md                    # 首页
-│   ├── coding/
-│   │   ├── frontend.md             # 前端编码规范
-│   │   ├── backend.md              # 后端编码规范
-│   │   └── git.md                  # Git 提交规范
-│   ├── architecture/
-│   │   ├── vue-project.md          # Vue 项目架构模板
-│   │   ├── go-service.md           # Go 后端架构模板
-│   │   └── mcp-server.md           # MCP Server 开发指南
-│   ├── devops/
-│   │   ├── deployment.md           # 部署流程
-│   │   └── monitoring.md           # 监控方案
-│   └── troubleshooting/
-│       ├── common-issues.md        # 常见问题排查
-│       └── fwh-specific.md         # FranklinWH 业务相关
-├── .vitepress/
-│   └── config.ts                   # VitePress + MCP 配置
-├── package.json
-└── pnpm-lock.yaml
-```
-
-**Step 3：配置 VitePress + MCP 插件**
-
-```ts
-// .vitepress/config.ts
-import { defineConfig } from 'vitepress'
-import { MCPPlugin } from 'vitepress-plugin-mcp'
-
-export default defineConfig({
-  title: 'Team Knowledge Base',
-  description: '团队知识库',
-  themeConfig: {
-    search: {
-      provider: 'local', // 必须启用 local search（插件依赖它的索引）
-      options: {},
-    },
-    sidebar: [
-      {
-        text: '编码规范',
-        items: [
-          { text: '前端', link: '/coding/frontend' },
-          { text: '后端', link: '/coding/backend' },
-          { text: 'Git', link: '/coding/git' },
-        ],
-      },
-      {
-        text: '架构模板',
-        items: [
-          { text: 'Vue 项目', link: '/architecture/vue-project' },
-          { text: 'Go 后端', link: '/architecture/go-service' },
-        ],
-      },
-    ],
-  },
-  vite: {
-    plugins: [
-      MCPPlugin({ port: 4100 }), // MCP Server 监听端口
-    ],
-  },
-})
-```
-
-**Step 4：启动**
-
-```bash
-# 开发模式（同时启动 VitePress + MCP Server）
-pnpm vitepress dev docs
-
-# MCP Server 自动在 http://localhost:4100 启动
-```
-
-**Step 5：验证 MCP Server**
-
-```bash
-# 测试 MCP Server 是否可用
-curl http://localhost:4100/mcp
-```
-
-### 4.3 插件暴露的 Tools
-
-`vitepress-plugin-mcp` 自动提供以下工具：
-
-| Tool 名称              | 描述                                                 | 参数            |
-| ---------------------- | ---------------------------------------------------- | --------------- |
-| `search_documentation` | 全文搜索文档内容（基于 VitePress local search 索引） | `query: string` |
-| `get_page_content`     | 获取指定页面的完整 Markdown 内容                     | `path: string`  |
-| `list_pages`           | 列出所有文档页面                                     | 无              |
-
-### 4.4 在 Kiro 中配置连接
-
-知识库是**远程 MCP Server**（HTTP），在后端运行目录的 Kiro 配置中使用 `url` 字段连接：
-
-**`./.kiro/settings/mcp.json` 中添加：**
-
-```json
-{
-  "mcpServers": {
-    "team-knowledge": {
-      "url": "http://lochost:4100/mcp"
-    }
-  }
-}
-```
-
-### 4.5 部署方案
-
-| 环境     | 方式                                 | 地址                                 |
-| -------- | ------------------------------------ | ------------------------------------ |
-| 本地开发 | `pnpm vitepress dev docs`            | `http://localhost:4100/mcp`          |
-| 团队共享 | 部署到内网服务器（PM2/systemd 常驻） | `http://knowledge.internal:4100/mcp` |
-| Docker   | 容器化部署                           | `http://knowledge:4100/mcp`          |
-
-**PM2 部署示例：**
-
-```bash
-# ecosystem.config.js
-module.exports = {
-  apps: [{
-    name: 'knowledge-mcp',
-    script: 'npx',
-    args: 'vitepress dev docs --port 5173',
-    cwd: '/opt/team-knowledge',
-    env: { NODE_ENV: 'production' }
-  }]
-}
-```
-
-**注意：** `vitepress-plugin-mcp` 的 MCP Server 与 VitePress dev server 绑定运行。生产环境需要保持 `vitepress dev` 常驻运行（不是 `vitepress build`）。
-
-### 4.6 使用效果
-
-配置完成后，在 Kiro CLI 中可以直接使用知识库：
-
-```
-> 帮我查一下前端编码规范中关于组件命名的约定
-
-Kiro 会自动调用 team-knowledge MCP Server 的 search_documentation 工具，
-搜索知识库内容并返回相关文档片段。
-```
-
-### 4.7 添加新文档的流程
-
-```
-1. 在 team-knowledge 仓库中编写 Markdown 文件
-2. git commit && git push
-3. 服务器自动重启（PM2 watch 或 CI/CD）
-4. MCP Server 自动索引新内容
-5. Kiro 下次搜索即可获取新文档
-```
-
----
-
-## 5. 内部工具 MCP Server 详细设计
-
-### 5.1 技术选型
-
-| 项目      | 选择                          | 理由                                   |
-| --------- | ----------------------------- | -------------------------------------- |
-| 语言      | Go                            | 与后端一致，直接 import service 层代码 |
-| SDK       | `github.com/mark3labs/mcp-go` | 社区最活跃的 Go MCP SDK                |
-| Transport | stdio                         | Kiro CLI 本地调用，最简单              |
-| 构建产物  | 单二进制`fwh-mcp-server`      | `go build -o fwh-mcp-server ./cmd/mcp` |
-
-### 5.2 暴露的 Tools 清单
-
-| Tool 名称                   | 输入参数                              | 描述                    | 复用的 service 函数               |
-| --------------------------- | ------------------------------------- | ----------------------- | --------------------------------- |
-| `query_site_info`           | `sn: string`                          | 查询站点设备详细信息    | `services.GetSiteInfoData`        |
-| `search_sites`              | `page, size: int, keyword?: string`   | 搜索站点列表            | `services.QuerySiteInfoDataList`  |
-| `query_sim_card`            | `giccid: string`                      | 查询单张 SIM 卡状态     | `services.GetSimCardInfo`         |
-| `search_sim_cards`          | `page, size: int, status?, platform?` | 搜索 SIM 卡列表         | `services.GetSimCardBatchInfo`    |
-| `query_power_flow`          | `sn: string, date: string`            | 查询站点功率流数据      | `services.QuerySitePowerFlow`     |
-| `query_alarm_statistics`    | `date?: string`                       | 查询告警统计            | `services.GetAlarmStatistics`     |
-| `query_shutdown_statistics` | `date: string`                        | 查询停机统计            | `services.GetShutdownStatistics`  |
-| `create_feedback`           | `title, type, priority, description`  | 创建 Plane Intake Issue | `services.SubmitFeedback`         |
-| `query_feedback_history`    | 无                                    | 查询 Feedback 提交历史  | `services.GetFeedbackHistory`     |
-
-### 5.3 代码结构
-
-```
-service/
-├── cmd/
-│   └── mcp/
-│       ├── main.go              # MCP Server 入口
-│       └── tools/
-│           ├── siteInfo.go      # 站点信息相关 tools
-│           ├── simCard.go       # SIM 卡相关 tools
-│           ├── powerFlow.go     # 功率流相关 tools
-│           ├── alarm.go         # 告警统计 tools
-│           ├── shutdown.go      # 停机统计 tools
-│           └── plane.go         # Plane/Feedback tools
-├── main.go                      # 现有 HTTP Server（不改动）
-├── services/                    # 共享
-├── repositories/                # 共享
-└── ...
-```
-
-### 5.4 代码示例
-
-**入口 `service/cmd/mcp/main.go`：**
-
-```go
-package main
-
-import (
-    "fmt"
-    "log"
-    "os"
-
-    "github.com/mark3labs/mcp-go/server"
-
-    "fwh-toolbox-server/cache"
-    "fwh-toolbox-server/config"
-    "fwh-toolbox-server/database"
-    "fwh-toolbox-server/repositories"
-
-    "fwh-toolbox-server/cmd/mcp/tools"
-)
-
-func main() {
-    // 加载配置
-    cfg, err := config.LoadConfig()
-    if err != nil {
-        log.Fatalf("加载配置失败: %v", err)
-    }
-
-    // 初始化基础设施（与 HTTP Server 相同）
-    if err := database.Init(&cfg.App); err != nil {
-        log.Fatalf("数据库初始化失败: %v", err)
-    }
-    cache.Init(cfg.App.RedisAddr)
-    repositories.PlaneWebHttpInit(&cfg.PlaneWebApi)
-
-    // 创建 MCP Server
-    s := server.NewMCPServer(
-        "fwh-tools",
-        "1.0.0",
-        server.WithToolCapabilities(false),
-        server.WithRecovery(),
-    )
-
-    // 注册所有 Tools
-    tools.RegisterSiteInfoTools(s)
-    tools.RegisterSimCardTools(s)
-    tools.RegisterPowerFlowTools(s)
-    tools.RegisterAlarmTools(s)
-    tools.RegisterShutdownTools(s)
-    tools.RegisterPlaneTools(s)
-
-    // 启动 stdio 通信
-    fmt.Fprintln(os.Stderr, "[fwh-mcp-server] started (stdio)")
-    if err := server.ServeStdio(s); err != nil {
-        log.Fatalf("[fwh-mcp-server] error: %v", err)
-    }
-}
-```
-
-**工具示例 `service/cmd/mcp/tools/siteInfo.go`：**
-
-```go
-package tools
-
-import (
-    "context"
-    "encoding/json"
-    "fmt"
-
-    "github.com/mark3labs/mcp-go/mcp"
-    "github.com/mark3labs/mcp-go/server"
-
-    "fwh-toolbox-server/services"
-)
-
-func RegisterSiteInfoTools(s *server.MCPServer) {
-    // Tool: 查询站点信息
-    s.AddTool(
-        mcp.NewTool("query_site_info",
-            mcp.WithDescription("查询单个站点设备的详细信息，包括版本、网络状态、激活状态、SN、固件等"),
-            mcp.WithString("sn", mcp.Required(), mcp.Description("站点 SN 序列号")),
-        ),
-        handleQuerySiteInfo,
-    )
-
-    // Tool: 搜索站点列表
-    s.AddTool(
-        mcp.NewTool("search_sites",
-            mcp.WithDescription("搜索站点设备列表，支持分页"),
-            mcp.WithNumber("page", mcp.Description("页码，从1开始，默认1")),
-            mcp.WithNumber("size", mcp.Description("每页数量，默认10")),
-            mcp.WithString("keyword", mcp.Description("搜索关键字（匹配 SN、设备名）")),
-        ),
-        handleSearchSites,
-    )
-}
-
-func handleQuerySiteInfo(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    sn, err := req.RequireString("sn")
-    if err != nil {
-        return mcp.NewToolResultError("参数 sn 必填"), nil
-    }
-
-    data, err := services.GetSiteInfoData(sn)
-    if err != nil {
-        return mcp.NewToolResultError(fmt.Sprintf("查询失败: %v", err)), nil
-    }
-
-    jsonBytes, _ := json.MarshalIndent(data, "", "  ")
-    return mcp.NewToolResultText(string(jsonBytes)), nil
-}
-
-func handleSearchSites(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    page := int(req.GetFloat("page", 1))
-    size := int(req.GetFloat("size", 10))
-    keyword := req.GetString("keyword", "")
-
-    data, err := services.QuerySiteInfoDataList(uint(page), uint(size), keyword, nil, nil, nil)
-    if err != nil {
-        return mcp.NewToolResultError(fmt.Sprintf("搜索失败: %v", err)), nil
-    }
-
-    jsonBytes, _ := json.MarshalIndent(data, "", "  ")
-    return mcp.NewToolResultText(string(jsonBytes)), nil
-}
-```
-
----
-
-## 6. 外部服务 MCP Server
-
-直接使用社区开源 Server，不需要自己实现。**不使用 Git MCP Server。**
-
-| Server            | 用途                     | 包名                                       |
-| ----------------- | ------------------------ | ------------------------------------------ |
-| AWS Documentation | 搜索 AWS 文档、最佳实践  | `@aws/aws-documentation-mcp-server`        |
-| Brave Search      | 网络搜索（技术问题排查） | `@modelcontextprotocol/server-bravesearch` |
-
----
-
-## 7. Kiro CLI 配置
-
-所有 Kiro 配置基于后端程序运行目录（`service/`）的相对路径 `./.kiro/`。
-
-### 7.1 工作区 MCP 配置
-
-**`service/.kiro/settings/mcp.json`：**
-
-```json
-{
-  "mcpServers": {
-    "fwh-tools": {
-      "command": "./fwh-mcp-server",
-      "args": [],
-      "env": {
-        "MONGO_DSN": "${MONGO_DSN}",
-        "REDIS_ADDR": "${REDIS_ADDR}",
-        "PLANE_WEB_HOST": "${PLANE_WEB_HOST}",
-        "PLANE_WEB_EMAIL": "${PLANE_WEB_EMAIL}",
-        "PLANE_WEB_PASSWORD": "${PLANE_WEB_PASSWORD}",
-        "PLANE_WEB_WORKSPACE_SLUG": "${PLANE_WEB_WORKSPACE_SLUG}",
-        "PLANE_WEB_PROJECT_ID": "${PLANE_WEB_PROJECT_ID}"
-      }
-    },
-    "team-knowledge": {
-      "url": "http://knowledge.internal:4100/mcp"
-    },
-    "aws-docs": {
-      "command": "npx",
-      "args": ["-y", "@aws/aws-documentation-mcp-server"]
-    },
-    "web-search": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-bravesearch"],
-      "env": {
-        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-### 7.2 Steering 文件
-
-**`service/.kiro/steering/project.md`：**
-
-```markdown
-# FranklinWH-ToolBox 项目上下文
-
-## 项目概述
-
-内部工具平台，前端 Vue3 + Naive UI，后端 Go Fiber + MongoDB。
-
-## 可用 MCP 工具
-
-- fwh-tools: 查询站点、SIM卡、功率流、告警、Plane Issue
-- team-knowledge: 搜索团队知识库文档
-- aws-docs: 搜索 AWS 文档
-- web-search: 网络搜索
-
-## 注意事项
-
-- 不要直接操作 Git
-- 修改代码后需 go build / npm run build 验证
-- 后端分层：controllers → services → repositories
-```
-
-### 7.3 部署目录结构
-
-```
-/var/www/fwh-toolbox/server/          # 后端运行目录（WorkingDirectory）
-├── fwh-toolbox-server                # HTTP Server 二进制
-├── fwh-mcp-server                    # MCP Tools Server 二进制
-├── .kiro/
-│   ├── settings/
-│   │   └── mcp.json                  # MCP Server 配置（command: "./fwh-mcp-server"）
-│   └── steering/
-│       └── project.md                # Agent 指令文件
-└── .env                              # 环境变量配置
-```
-
-**源码目录结构：**
-
-```
-service/
-├── .kiro/                            # Kiro 配置（开发环境 + 部署时拷贝）
-│   ├── settings/
-│   │   └── mcp.json
-│   └── steering/
-│       └── project.md
-├── cmd/
-│   └── mcp/
-│       ├── main.go                   # MCP Server 入口
-│       └── tools/                    # 各工具实现
-│           ├── siteInfo.go
-│           ├── simCard.go
-│           ├── powerFlow.go
-│           ├── alarm.go
-│           ├── shutdown.go
-│           └── plane.go
-├── main.go                           # HTTP Server 入口
-└── ...
-```
-
-### 7.4 后端 ACP Client 引用
-
-ACP Client 启动 `kiro-cli acp` 时指定工作目录为后端运行目录，Kiro 自动从 `./.kiro/settings/mcp.json` 加载配置：
-
-```go
-cmd := exec.Command("kiro-cli", "acp")
-cmd.Dir = serviceDir  // 后端运行目录（含 .kiro/ 和 fwh-mcp-server）
-```
-
----
-
-## 8. 构建与运行
-
-### 8.1 构建 MCP Tools Server
-
-```bash
-cd service
-go build -o fwh-mcp-server ./cmd/mcp
-```
-
-### 8.2 本地测试
-
-```bash
-# 直接运行测试
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./fwh-mcp-server
-
-# 通过 Kiro CLI 测试（在 service/ 目录下）
-kiro chat  # 然后在对话中使用工具
-```
-
----
-
-## 9. 实现步骤
-
-| 阶段        | 内容                                  | 输出物                         | 预估时间 |
-| ----------- | ------------------------------------- | ------------------------------ | -------- |
-| **Phase 1** | 创建`service/cmd/mcp/` 目录结构和入口 | main.go + go build 通过        | 0.5 天   |
-| **Phase 2** | 实现站点信息 Tools                    | tools/siteInfo.go              | 1 天     |
-| **Phase 3** | 实现 SIM 卡 + 功率流 Tools            | tools/simCard.go, powerFlow.go | 1 天     |
-| **Phase 4** | 实现告警 + Plane Tools                | tools/alarm.go, plane.go       | 1 天     |
-| **Phase 5** | 配置`.kiro/` + Steering + 联调        | 配置文件 + 端到端测试          | 0.5 天   |
-| **Phase 6** | 配置外部 MCP Server (AWS Docs, Brave) | npm 安装 + 环境变量配置        | 0.5 天   |
-
-**总计：约 4.5 天**
-
----
-
-## 10. 前端 AI Chat 与后端通讯设计
-
-### 10.1 架构概览
-
-```
-┌────────────────────────────────┐
-│        前端 (Vue 3)             │
-│   src/views/ai-chat/           │
-│  ┌──────────────────────────┐  │
-│  │   ChatPanel 组件          │  │
-│  │  • 消息列表 (Markdown)    │  │
-│  │  • 输入框                 │  │
-│  │  • 流式输出显示           │  │
-│  └────────────┬─────────────┘  │
-│               │ SSE / fetch     │
-└───────────────┼────────────────┘
-                │
-                ▼
-┌────────────────────────────────┐
-│        后端 (Go Fiber)          │
-│   service/controllers/          │
-│   aiChatControllers.go          │
-│  ┌──────────────────────────┐  │
-│  │  POST /ai/chat            │  │
-│  │  • 接收用户消息           │  │
-│  │  • 调用 LLM API          │  │
-│  │  • SSE 流式返回           │  │
-│  └────────────┬─────────────┘  │
-│               │                 │
-│               ▼                 │
-│  ┌──────────────────────────┐  │
-│  │  LLM Provider             │  │
-│  │  • Claude API (Anthropic) │  │
-│  │  • 或 OpenAI API          │  │
-│  │  • 或 AWS Bedrock         │  │
-│  └──────────────────────────┘  │
-│               │                 │
-│               ▼                 │
-│  ┌──────────────────────────┐  │
-│  │  MCP Tools (可选)         │  │
-│  │  • 复用 services 层       │  │
-│  │  • AI 可调用内部工具      │  │
-│  └──────────────────────────┘  │
-└────────────────────────────────┘
-```
-
-### 10.2 通讯协议：SSE（Server-Sent Events）
-
-选择 SSE 而非 WebSocket 的原因：
-
-- AI 对话是单向流（服务端推送 token 流给前端）
-- SSE 基于 HTTP，天然支持认证 header
-- 无需额外的连接管理
-- 断线自动重连
-
-### 10.3 后端引擎：Kiro ACP Client
-
-后端实现 ACP (Agent Client Protocol) Client，通过 JSON-RPC 2.0 与 `kiro-cli acp` 子进程结构化通讯。
-
-**为什么选 ACP 而非直接 exec Kiro CLI：**
-
-| 对比项         | exec kiro chat        | ACP Client                                 |
-| -------------- | --------------------- | ------------------------------------------ |
-| 通讯格式       | 非结构化文本输出      | JSON-RPC 2.0 结构化                        |
-| 会话管理       | 自己实现              | Kiro 原生支持（session/new, session/load） |
-| 工具调用可见性 | 无法感知              | ToolCall/ToolCallUpdate 实时事件           |
-| 取消操作       | kill 进程             | session/cancel 优雅取消                    |
-| 会话持久化     | 自己实现 history.json | Kiro 自动持久化到 ~/.kiro/sessions/        |
-| 协议稳定性     | CLI 输出格式可能变    | ACP 是开放标准                             |
-
-**架构：**
-
-```
-前端 SSE ←── 后端 (ACP Client) ←── JSON-RPC stdin/stdout ←── kiro-cli acp
-                                                                    │
-                                                                    ├── 自动调用 MCP Server
-                                                                    ├── 自动管理会话上下文
-                                                                    └── 自动持久化对话历史
-```
-
-### 10.4 后端接口设计
-
-**`POST /api/ai/chat`** — 发送消息
-
-请求：
-
-```json
-{
-  "message": "帮我查一下 SN 为 ABC123 的站点信息",
-  "sessionId": "sess_abc123" // 可选，不传则使用默认会话
-}
-```
-
-响应（SSE 流，将 ACP 事件转发给前端）：
-
-```
-Content-Type: text/event-stream
-
-event: message
-data: {"type":"text","content":"正在查询站点信息..."}
-
-event: tool_call
-data: {"type":"tool_call","name":"query_site_info","status":"running"}
-
-event: tool_update
-data: {"type":"tool_update","name":"query_site_info","status":"completed"}
-
-event: message
-data: {"type":"text","content":"该站点的固件版本是 v3.2.1..."}
-
-event: done
-data: {"type":"done","sessionId":"sess_abc123"}
-```
-
-**SSE 事件映射：**
-
-| SSE Event     | ACP Update Type     | 说明                  |
-| ------------- | ------------------- | --------------------- |
-| `message`     | `AgentMessageChunk` | AI 文本流（逐块推送） |
-| `tool_call`   | `ToolCall`          | Kiro 调用 MCP 工具    |
-| `tool_update` | `ToolCallUpdate`    | 工具执行进度          |
-| `done`        | `TurnEnd`           | 本轮对话结束          |
-| `error`       | -                   | 错误                  |
-
-**其他接口：**
-
-| 接口               | 方法   | 描述                   |
-| ------------------ | ------ | ---------------------- |
-| `/ai/chat`         | POST   | 发送消息，SSE 流式返回 |
-| `/ai/sessions`     | GET    | 获取当前用户会话列表   |
-| `/ai/sessions/new` | POST   | 创建新会话             |
-| `/ai/sessions/:id` | DELETE | 删除会话               |
-| `/ai/cancel`       | POST   | 取消当前操作           |
-
-### 10.5 后端 ACP Client 实现
-
-**核心数据结构：**
-
-```go
-// ACPSession 单个用户的 ACP 连接
-type ACPSession struct {
-    UserId     string
-    SessionId  string           // Kiro ACP session ID
-    Process    *exec.Cmd        // kiro-cli acp 长驻进程
-    Stdin      io.WriteCloser   // JSON-RPC 请求写入
-    Stdout     *bufio.Reader    // JSON-RPC 响应/通知读取
-    Mutex      sync.Mutex       // 同一用户串行对话
-    LastActive time.Time
-    RequestId  int64            // JSON-RPC 请求 ID 自增
-}
-
-// ACPManager 管理所有用户的 ACP 会话
-type ACPManager struct {
-    sessions    map[string]*ACPSession  // userId -> session
-    mu          sync.RWMutex
-    maxIdle     time.Duration           // 空闲超时
-    projectDir  string                  // 项目目录
-}
-```
-
-**完整通讯流程：**
-
-```go
-// 1. 启动 kiro-cli acp（每用户一个长驻进程）
-func (m *ACPManager) GetOrCreate(userId string) (*ACPSession, error) {
-    if sess, exists := m.sessions[userId]; exists {
-        sess.LastActive = time.Now()
-        return sess, nil
-    }
-
-    cmd := exec.Command("kiro-cli", "acp")
-    cmd.Dir = m.projectDir  // 含 .kiro/settings/mcp.json
-
-    stdin, _ := cmd.StdinPipe()
-    stdout, _ := cmd.StdoutPipe()
-    cmd.Start()
-
-    sess := &ACPSession{
-        UserId:  userId,
-        Process: cmd,
-        Stdin:   stdin,
-        Stdout:  bufio.NewReader(stdout),
-    }
-
-    // 2. initialize 握手
-    sess.sendRPC("initialize", map[string]any{
-        "protocolVersion": 1,
-        "clientCapabilities": map[string]any{
-            "fs": map[string]any{"readTextFile": true, "writeTextFile": true},
-        },
-        "clientInfo": map[string]any{"name": "fwh-toolbox", "version": "1.0.0"},
-    })
-
-    // 3. 创建会话
-    result := sess.sendRPC("session/new", map[string]any{"cwd": m.projectDir})
-    sess.SessionId = result.SessionId
-
-    m.sessions[userId] = sess
-    return sess, nil
-}
-
-// 4. 发送消息并流式读取
-func (sess *ACPSession) Prompt(message string, events chan<- SSEEvent) {
-    sess.Mutex.Lock()
-    defer sess.Mutex.Unlock()
-
-    sess.sendRPC("session/prompt", map[string]any{
-        "sessionId": sess.SessionId,
-        "content":   []map[string]any{{"type": "text", "text": message}},
-    })
-
-    // 持续读取 session/notification 直到 TurnEnd
-    for {
-        notif := sess.readNotification()
-        switch notif.Params.UpdateType {
-        case "AgentMessageChunk":
-            events <- SSEEvent{Type: "message", Content: notif.Params.Text}
-        case "ToolCall":
-            events <- SSEEvent{Type: "tool_call", Name: notif.Params.ToolName}
-        case "ToolCallUpdate":
-            events <- SSEEvent{Type: "tool_update", Name: notif.Params.ToolName}
-        case "TurnEnd":
-            events <- SSEEvent{Type: "done", SessionId: sess.SessionId}
-            close(events)
-            return
-        }
-    }
-}
-
-// 5. 取消操作
-func (sess *ACPSession) Cancel() {
-    sess.sendRPC("session/cancel", map[string]any{"sessionId": sess.SessionId})
-}
-```
-
-**Controller 层：**
-
-```go
-func AiChat(c *fiber.Ctx) error {
-    userId := middleware.AuthGetUserName(c)
-    var req struct {
-        Message   string `json:"message"`
-        SessionId string `json:"sessionId"`
-    }
-    c.BodyParser(&req)
-
-    sess, err := acpManager.GetOrCreate(userId)
-    if err != nil {
-        return Error(c, "AI 会话创建失败")
-    }
-
-    // SSE 流式响应
-    c.Set("Content-Type", "text/event-stream")
-    c.Set("Cache-Control", "no-cache")
-
-    c.Context().SetBodyStreamWriter(func(w *bufio.Writer) {
-        events := make(chan SSEEvent, 50)
-        go sess.Prompt(req.Message, events)
-
-        for event := range events {
-            fmt.Fprintf(w, "event: %s\ndata: %s\n\n", event.Type, event.JSON())
-            w.Flush()
-        }
-    })
-    return nil
-}
-```
-
-### 10.6 多会话管理（ACP 原生能力）
-
-Kiro ACP 原生支持多会话，后端无需自己实现持久化。
-
-**ACP 会话方法：**
-
-| 方法             | 用途                                   |
-| ---------------- | -------------------------------------- |
-| `session/new`    | 创建新会话（Kiro 分配 ID，自动持久化） |
-| `session/load`   | 按 ID 恢复历史会话                     |
-| `session/prompt` | 在指定会话中对话                       |
-| `session/cancel` | 取消当前操作                           |
-
-**会话生命周期：**
-
-```
-用户首次 → 启动 kiro-cli acp 进程 → initialize → session/new
-                                                       │
-用户对话 → session/prompt → 读取 notifications → SSE   │ Kiro 自动
-                                                       │ 持久化
-用户加载历史 → session/load(sessionId)                  │
-                                                       ▼
-空闲 30min → kill 进程 → 下次使用时重启 + session/load 恢复
-```
-
-**Kiro 自动持久化目录：**
-
-```
-~/.kiro/sessions/cli/
-├── <session-id>.json       # 会话元数据
-└── <session-id>.jsonl      # 对话事件日志
-```
-
-### 10.7 限制与注意事项
-
-| 项目       | 说明                                                    |
-| ---------- | ------------------------------------------------------- |
-| 并发限制   | 同一用户 Mutex 串行（ACP 不支持同 session 并行 prompt） |
-| 最大进程数 | 限制 20 个并发 kiro-cli acp 进程                        |
-| 空闲超时   | 30 分钟无活动 kill 进程（再次使用时自动恢复）           |
-| 请求超时   | 单次 prompt 最多等待 120 秒                             |
-| MCP 配置   | 所有会话共享项目 .kiro/settings/mcp.json                |
-| Kiro 订阅  | 需确保服务器上 Kiro 已登录且订阅有效                    |
-
-### 10.8 前端实现要点
-
-**实现位置：** `src/layout/header/Actions` 中，作为顶部栏全局操作按钮，点击展开 AI Chat 侧边抽屉。
-
-**目录结构：**
-
-```
-src/layout/header/Actions/
-├── AiChat/
-│   ├── index.vue             # 入口按钮 + NDrawer 容器
-│   ├── ChatPanel.vue         # 聊天面板（消息列表 + 输入）
-│   ├── MessageItem.vue       # 单条消息（支持 Markdown 渲染）
-│   ├── ToolCallCard.vue      # 工具调用展示卡片
-│   ├── StreamingText.vue     # 流式文本显示组件
-│   ├── useAiChat.ts          # 核心逻辑：SSE 连接、消息管理
-│   └── interface.ts          # 类型定义
-```
-
-**入口组件 `AiChat/index.vue`：**
-
-```vue
-<template>
-  <!-- 顶部栏按钮 -->
-  <NButton text @click="drawerShow = true">
-    <template #icon>
-      <span class="i-ph:chat-circle-dots" />
-    </template>
-  </NButton>
-
-  <!-- 侧边抽屉 -->
-  <NDrawer v-model:show="drawerShow" :width="480" placement="right">
-    <NDrawerContent title="AI 助手" closable>
-      <ChatPanel />
-    </NDrawerContent>
-  </NDrawer>
-</template>
-```
-
-**`useAiChat.ts` 核心逻辑：**
-
-```typescript
-export function useAiChat() {
-  const messages = ref<ChatMessage[]>([])
-  const isStreaming = ref(false)
-
-  async function sendMessage(content: string) {
-    // 添加用户消息
-    messages.value.push({ role: 'user', content })
-    isStreaming.value = true
-
-    // 添加 AI 消息占位
-    const aiMessage: ChatMessage = { role: 'assistant', content: '', toolCalls: [] }
-    messages.value.push(aiMessage)
-
-    // 发起 SSE 请求（使用框架的 fetch，自动带 token）
-    const response = await fetch(baseUrl + '/ai/chat', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({
-        message: content,
-        history: messages.value.slice(0, -1), // 不含当前占位
-      }),
-    })
-
-    // 读取 SSE 流
-    const reader = response.body!.getReader()
-    const decoder = new TextDecoder()
-
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-
-      const text = decoder.decode(value)
-      // 解析 SSE 事件，逐步更新 aiMessage.content
-      parseSSEEvents(text, aiMessage)
-    }
-
-    isStreaming.value = false
-  }
-
-  return { messages, isStreaming, sendMessage }
-}
-```
-
-**`ChatPanel.vue` 基本结构：**
-
-```vue
-<template>
-  <div class="flex h-full flex-col">
-    <!-- 消息列表 -->
-    <div class="flex-1 overflow-y-auto p-4 space-y-4">
-      <MessageItem v-for="msg in messages" :key="msg.id" :message="msg" />
-      <!-- 流式输出中的光标闪烁 -->
-      <span v-if="isStreaming" class="animate-pulse">▊</span>
-    </div>
-
-    <!-- 输入区域 -->
-    <div class="border-t p-4">
-      <NInput
-        v-model:value="inputText"
-        type="textarea"
-        :autosize="{ minRows: 1, maxRows: 4 }"
-        placeholder="输入消息...（Shift+Enter 换行）"
-        @keydown.enter.exact.prevent="handleSend"
-      />
-    </div>
-  </div>
-</template>
-```
-
-### 10.9 消息渲染
-
-| 内容类型 | 渲染方式                           |
-| -------- | ---------------------------------- |
-| 普通文本 | Markdown 渲染（支持代码高亮）      |
-| 工具调用 | 折叠卡片，显示工具名 + 参数 + 结果 |
-| 表格数据 | 自动识别 JSON 数组，渲染为表格     |
-| 错误信息 | 红色提示卡片                       |
-
-## 11. 安全考虑
-
-| 风险            | 措施                                                         |
-| --------------- | ------------------------------------------------------------ |
-| AI 误操作 Git   | 不配置 Git MCP Server                                        |
-| 敏感数据泄露    | Tools 只返回必要字段，不返回密码/token/密钥                  |
-| AI 误操作 Plane | create_feedback 限制只能创建 Intake，不能删除/修改已有 Issue |
-| MCP Server 崩溃 | 使用`server.WithRecovery()` 中间件恢复 panic                 |
-| 环境变量泄露    | 使用`${VAR}` 引用，不硬编码                                  |
-| 数据量过大      | Tools 返回结果限制最大条目数，分页查询                       |
-| Kiro 进程泄漏   | SessionManager 定时扫描超时进程并 kill                       |
-| 用户并发冲突    | 同一用户 Mutex 锁，防止并行调用 Kiro                         |
-| 磁盘占用        | 会话目录定期清理，限制历史文件大小                           |
-| Kiro 订阅额度   | 监控使用量，超额时返回友好提示                               |
-
----
-
-## 12. 关于 A2A（原 ACP）
-
-当前阶段不需要 A2A。适合引入的场景：
-
-- 多个独立 AI Agent 协作（代码审查 Agent + 测试 Agent + 部署 Agent）
-- 跨团队/跨系统的 Agent 通信
-
-如果后续需要：
-
-- A2A Go SDK: `github.com/a2aproject/a2a-go`
-- A2A 规范: `https://a2aprotocol.ai`

docs/data-download/archive/data-download-integrated-design-2026-09-21.md

@@ -2,6 +2,8 @@
 
 > 状态：历史归档，不再作为 AI 默认入口或当前事实的唯一来源。当前文档导航见 [`../README.md`](../README.md)。本文保留拆分前的完整上下文，供追溯原始决策和章节编号。
 >
+> 注：文中的 `cmd/mcp`（旧 MCP 服务）已删除，相关 MCP 接入方案仅作历史记录；DataDownload 当前没有 MCP 接入，见 [`../implementation-status.md`](../implementation-status.md)。
+>
 > 独立问题台账：[`docs/issues/data-download-open-issues.md`](../../issues/data-download-open-issues.md)。后续问题状态、优先级、验收条件和关闭记录统一在该文档维护。
 >
 > 用途：供后续会话实施。本文记录已经确认的边界、接口、数据结构、并发语义和现有代码问题；剩余重试次数、租约时长、轮询频率等均为部署或实现参数，不再作为产品待决策事项。

docs/data-download/implementation-status.md

@@ -17,7 +17,7 @@
 - partial ZIP 成功文件及 `DataDownloadReport.json`；
 - owner/admin 任务隔离和 task-scoped 文件入口；
 - 管理员 FaultRecord 文件清单、单文件下载和物理删除；
-- MCP 固定非管理员 owner `USER_AI`，其任务查询限制为自身。
+- 暂无 MCP 接入：原 MCP 接入（固定 owner `USER_AI`）已随旧 MCP 服务一并删除，fwh-agent-mcp 目前没有 DataDownload 工具。
 
 ## 2. 主要代码入口
 
@@ -37,7 +37,6 @@
 | MinIO repository | `service/repositories/minio/dataDownloadRepo.go` |
 | Queue | `service/task/queue/dataDownloadQueue/dataDownloadQueue.go` |
 | HTTP controller/routes | `service/controllers/dataDownloadControllers.go`、`service/routes/dataDownloadRoutes.go` |
-| MCP | `service/cmd/mcp/tools/service/data_download.go` |
 | Frontend | `src/views/data-download/`、`src/service/dataDownload/` |
 
 ## 3. 已知设计差异
@@ -52,7 +51,7 @@
 | Renderer | MQTT/EventAlarm 固定列，PowerFlow 基础 HTML | PowerFlow ECharts、UpdateLog 双 Sheet、JSON envelope |
 | 前端预览 | 下载为主 | HTML/CSV/XLSX/JSON/TXT 真实预览、tar 浏览 |
 | 批量操作 | 后端支持多 Task 打包，页面单任务整包 | 多选、部分文件选择、批量删除 |
-| MCP | 自身任务列表、创建、全局文档分页 | 条件过滤、详情/读取、存在性判断、覆盖检查与幂等创建 |
+| MCP | 无（旧 MCP 已删除） | 按 requirements 第 8 节在 fwh-agent-mcp 中重新实现 |
 | 大对象 | HTTP 读取流式；上游与 ZIP 多处 `[]byte` | 流式生成/上传或临时文件 |
 | FaultRecord 召唤轮询 | 每轮查询一次并延迟约 60 秒重入队，释放 worker；持久化任务信息和召唤占用，最长 2 小时 | 实际轮询间隔受队列调度影响 |
 | FaultRecord 设备发现 | 站点和设备基本信息只规划 aGate/aPower | MPPT/aHub 本阶段不处理；未来启用前确定设备 SN 来源 |
@@ -86,7 +85,7 @@
 
 ```bash
 cd service
-GOCACHE=/tmp/fwh-toolbox-go-cache go test ./services ./cmd/mcp/tools/service ./controllers ./routes ./task/queue/dataDownloadQueue ./repositories/mongo ./repositories/pgsql
+GOCACHE=/tmp/fwh-toolbox-go-cache go test ./services ./controllers ./routes ./task/queue/dataDownloadQueue ./repositories/mongo ./repositories/pgsql
 
 cd ..
 pnpm exec vue-tsc --build

docs/despatch-config/README.md

@@ -14,7 +14,7 @@
 | technical-design.md（待写） | 统一类型、环境参数化、调度模式识别、校验、对比算法、编辑分层 | 讨论如何实现时 |
 | ui-design.md（待写） | 菜单、列表、详情、编辑器、对比页面的布局和交互 | 实现或评审前端页面时 |
 
-字段的权威定义暂以 `service/dto/fwhTestTouTemplateDTO.go` 和 `deploy/kiro/skills/fwh-toolbox-workflow/references/tou-template.md` 为准；协议原文为 wiki《ScriptingForSchedulingConfiguration》。
+字段的权威定义暂以 `service/dto/fwhTestTouTemplateDTO.go` 和 `deploy/agent-assistant/skills/fwh-assistant/references/tou-template.md` 为准；协议原文为 wiki《ScriptingForSchedulingConfiguration》。
 
 ## 维护方式
 

docs/despatch-config/current-state.md

@@ -19,8 +19,8 @@
 | Repo（生产）    | `service/repositories/api/fwh_pro/fwh_touTemplate.go`                                          | `selectIotTouTemplateList`、`getIotTouTemplateDetailById`，结果为 `interface{}` 透传                |
 | Repo（测试）    | `service/repositories/api/fwh_test/fwh_touTemplate.go`                                         | 另有 `updateOrSaveIotTouTemplate`、`selectCitesList`                                                  |
 | DTO             | `service/dto/fwhTestTouTemplateDTO.go`、`service/dto/touTemplateDTO.go`                      | 测试服写入 DTO 完整；`TouTemplateItemInfo` 未被使用                                                     |
-| MCP             | `service/cmd/mcp/tools/service/tou_template.go`                                                | `service_tou_template_list/detail/save/cites`；save、cites 仅测试服                                     |
-| 知识文档        | `deploy/kiro/skills/fwh-toolbox-workflow/references/tou-template.md`                           | 字段字典、日类型配对、校验规则，是目前最完整的字段说明                                                    |
+| MCP             | `service/agentmcp/tools/tou.go`、`service/agentmcp/tools/ops.go`                               | fwh-agent-mcp 的 `tou_template_list/get`（生产、测试）与 `tou_template_save`（写工具集，仅测试服）      |
+| 知识文档        | `deploy/agent-assistant/skills/fwh-assistant/references/tou-template.md`                       | 字段字典、日类型配对、校验规则，是目前最完整的字段说明                                                    |
 | 相关模块        | `src/views/local-utils/log-357-parser/func/parseScheduling.ts`                                 | 357 日志解析中另一套“优先级 → 调度类型”映射                                                            |
 
 ## 2. 云端接口（hes-gateway）

docs/despatch-config/requirements.md

@@ -161,4 +161,4 @@
 ## 5. 第二阶段（暂不实现）
 
 - 模块接入 MCP，让 AI 完成模版编辑，复用本阶段的统一类型、校验规则和调度模式识别。
-- 现有 MCP 工具 `service_tou_template_*` 在第二阶段改为调用重构后的服务层。
+- fwh-agent-mcp 现有的 `tou_template_*` 工具在第二阶段改为调用重构后的服务层。

docs/issues/data-download-open-issues.md

@@ -227,7 +227,7 @@
 
 ### DD-021 MCP 能力不完整
 
-- 当前只有任务列表、创建任务和文档分页列表。
+- 原 MCP 接入（任务列表、创建任务和文档分页列表）已随旧 MCP 服务删除，目前没有 MCP 接入；需要时在 fwh-agent-mcp 中重新实现。
 - 缺少文档过滤/详情/读取、tar.gz 浏览、存在性判断、AI 活跃任务覆盖判断。
 - “检查已有文档/任务后创建”没有规范化指纹或 Redis 锁，重复请求会创建重复任务。
 

docs/kiro-cli-agent-implementation.md

@@ -1,594 +0,0 @@
-# FWH ToolBox Agent — Kiro CLI 配置实现方案
-
-> 创建日期：2026-08-04
-> 状态：方案设计（未实施）
-
----
-
-## 目录
-
-1. [概述](#1-概述)
-2. [配置文件清单](#2-配置文件清单)
-3. [Agent 配置详解](#3-agent-配置详解)
-4. [MCP Server 接入](#4-mcp-server-接入)
-5. [知识库接入](#5-知识库接入)
-6. [权限控制与文件生成策略](#6-权限控制与文件生成策略)
-7. [Steering 引导文件](#7-steering-引导文件)
-8. [启动与使用方式](#8-启动与使用方式)
-9. [注意事项与限制](#9-注意事项与限制)
-10. [后续扩展计划](#10-后续扩展计划)
-
----
-
-## 1. 概述
-
-### 1.1 目标
-
-创建名为 `fwh-toolbox-agent` 的 Kiro CLI Agent，用于：
-
-- 通过 MCP Server 查询 FranklinWH ToolBox 的业务数据（站点、SIM卡、告警、停机、功率流等）
-- 结合产品知识库和数据知识库，提供智能问答与数据分析
-- 生成数据统计报告或技术文档（Excel/PDF/Markdown），通过临时目录或 MinIO 提供下载
-- 提交问题反馈到 Plane 项目管理系统
-
-### 1.2 核心约束
-
-| 约束项         | 说明                                      |
-| -------------- | ----------------------------------------- |
-| 不可修改源码   | Agent 完全没有项目源码的写权限            |
-| 只读访问       | 可读取项目文件用于理解上下文              |
-| 可创建临时文件 | 仅限指定临时目录，用于导出数据/文档       |
-| MCP 数据接入   | 通过 stdio 模式的 MCP Server 获取业务数据 |
-| 知识库驱动     | 两套知识库：产品知识 + 数据字段解释       |
-
-### 1.3 技术架构
-
-```
-┌─────────────────────────────────────────────────┐
-│                Kiro CLI Chat                      │
-│            (fwh-toolbox-agent)                    │
-├─────────────────────────────────────────────────┤
-│  Tools: read, grep, glob, code, knowledge        │
-│  (无 write / shell 仅限安全命令)                  │
-├──────────┬──────────────┬───────────────────────┤
-│ MCP Server│  知识库(产品) │  知识库(数据)          │
-│ (stdio)   │  Wiki MD源码  │  docs/knowledge       │
-└──────────┴──────────────┴───────────────────────┘
-```
-
----
-
-## 2. 配置文件清单
-
-实施时需要创建/修改的文件：
-
-```
-.kiro/
-├── agents/
-│   └── fwh-toolbox-agent.json    # Agent 主配置
-├── steering/
-│   └── fwh-toolbox-context.md    # 业务上下文引导文件
-├── settings/
-│   └── cli.json                  # Workspace 级设置（可选）
-└── skills/
-    └── data-export/
-        └── SKILL.md              # 数据导出技能（按需加载）
-```
-
----
-
-## 3. Agent 配置详解
-
-### 3.1 配置文件位置
-
-```
-.kiro/agents/fwh-toolbox-agent.json
-```
-
-### 3.2 配置结构说明
-
-```jsonc
-{
-  "name": "fwh-toolbox-agent",
-  "description": "FranklinWH ToolBox 数据查询与分析助手，可查询站点/SIM卡/告警/停机数据，生成统计报告，提交问题反馈",
-  "prompt": "file://.kiro/prompts/fwh-toolbox-agent.md",
-
-  // === 可用工具 ===
-  "tools": [
-    "read",           // 读取文件
-    "grep",           // 搜索文件内容
-    "glob",           // 查找文件路径
-    "code",           // 代码智能（AST搜索）
-    "knowledge",      // 知识库检索
-    "shell",          // Shell（严格限制）
-    "web_search",     // 网页搜索（技术文档查找）
-    "web_fetch"       // 网页抓取
-  ],
-
-  // === 自动信任的工具（无需用户确认） ===
-  "allowedTools": [
-    "read",
-    "grep",
-    "glob",
-    "code",
-    "knowledge",
-    "web_search",
-    "web_fetch",
-    "@fwh-mcp/*"
-  ],
-
-  // === 工具细粒度设置 ===
-  "toolsSettings": {
-    "shell": {
-      "allowedCommands": [
-        "date",
-        "cat /tmp/fwh-export/.*",
-        "ls /tmp/fwh-export/.*",
-        "wc .*"
-      ],
-      "deniedCommands": [
-        "rm .*",
-        "mv .*",
-        "cp .*",
-        "sudo .*",
-        "chmod .*",
-        "chown .*",
-        "git .*",
-        "npm .*",
-        "pnpm .*",
-        "go .*"
-      ],
-      "denyByDefault": true
-    },
-    "web_fetch": {
-      "trusted": [
-        ".*docs\\.franklinwh\\.com.*",
-        ".*franklinwh\\.com.*"
-      ],
-      "blocked": [
-        ".*github\\.com.*"
-      ]
-    }
-  },
-
-  // === 上下文资源 ===
-  "resources": [
-    "file://docs/knowledge/**/*.md",
-    "skill://.kiro/skills/**/SKILL.md"
-  ],
-
-  // === MCP Server ===
-  "mcpServers": {
-    "fwh-mcp": {
-      "command": "/var/www/fwh-toolbox/server/fwh-mcp-server",
-      "args": [],
-      "env": {},
-      "timeout": 30000
-    }
-  },
-
-  // === 欢迎消息 ===
-  "welcomeMessage": "FWH ToolBox Agent 已就绪。我可以帮你查询站点信息、SIM卡状态、告警/停机统计、功率流数据，也可以生成数据报告或提交问题反馈。请问有什么需要？"
-}
-```
-
-### 3.3 字段说明
-
-| 字段              | 用途             | 备注                                     |
-| ----------------- | ---------------- | ---------------------------------------- |
-| `name`          | Agent 标识名     | 文件名必须与此一致（不含 .json）         |
-| `description`   | 简短描述         | 用于`agent list` 展示                  |
-| `prompt`        | 系统提示词       | 引用外部 md 文件，便于维护               |
-| `tools`         | 可用工具白名单   | **不包含 `write`**，确保无写权限 |
-| `allowedTools`  | 自动信任列表     | 所有 MCP tools 自动信任                  |
-| `toolsSettings` | 工具级别权限     | shell 严格限制为安全只读命令             |
-| `resources`     | 始终加载的上下文 | 数据知识库 + 技能文件                    |
-| `mcpServers`    | MCP 服务器定义   | stdio 模式本地二进制                     |
-
-### 3.4 关于 `write` 工具的缺失
-
-**设计决策**：`tools` 列表中不包含 `write` 工具，这意味着 Agent 完全无法创建或修改任何文件。
-
-**文件生成替代方案**（见第 6 节详述）：
-
-- 通过 `shell` 的白名单命令写入 `/tmp/fwh-export/` 目录
-- 或扩展 MCP Server 增加文件导出相关 Tool
-
----
-
-## 4. MCP Server 接入
-
-### 4.1 服务信息
-
-| 项目       | 值                                                      |
-| ---------- | ------------------------------------------------------- |
-| 二进制路径 | `/var/www/fwh-toolbox/server/fwh-mcp-server`          |
-| 通信模式   | stdio（标准输入/输出）                                  |
-| 协议       | MCP (Model Context Protocol)                            |
-| 依赖       | 数据库(MySQL/PostgreSQL/MongoDB)、Redis、配置文件(.env) |
-| 源码位置   | `service/cmd/mcp/main.go`                             |
-| 部署脚本   | `service/cmd/deploy_mcp.sh`                           |
-
-### 4.2 注册的 Tools 清单
-
-| Tool 名称                     | 功能描述                                                          | 必选参数                          | 可选参数                                                 |
-| ----------------------------- | ----------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------- |
-| `query_site_info`           | 查询单个站点设备详细信息（版本、网络、激活状态、固件、SN 等）     | `sn` (站点序列号)               | —                                                       |
-| `search_sites`              | 搜索站点设备列表，支持分页和关键字                                | —                                | `page`, `size`, `keyword`                          |
-| `query_power_flow`          | 查询站点指定日期的功率流数据（PV/Grid/aPower/HomeLoad/Generator） | `sn`, `date` (yyyy-MM-dd)     | —                                                       |
-| `query_sim_card`            | 查询单张 SIM 卡详细信息（状态、平台、用量）                       | `giccid` (19位)                 | —                                                       |
-| `search_sim_cards`          | 搜索 SIM 卡列表，支持状态/平台过滤                                | —                                | `page`, `size`, `search`, `status`, `platform` |
-| `query_alarm_statistics`    | 查询告警统计数据（按日期汇总各类告警数量）                        | —                                | `date` (yyyy-MM-dd，不传则查最新)                      |
-| `query_shutdown_statistics` | 查询停机统计数据（按日期汇总停机站点信息）                        | —                                | `date` (yyyy-MM-dd，不传则查最新)                      |
-| `create_feedback`           | 在 Plane 创建 Intake Issue（问题反馈/需求提交）                   | `title`, `type` (bug/feature) | `priority`, `description`, `category`              |
-| `query_feedback_history`    | 查询 Plane Intake Issue 提交历史                                  | —                                | —                                                       |
-
-### 4.3 Agent 配置中的 MCP 定义
-
-```jsonc
-"mcpServers": {
-  "fwh-mcp": {
-    "command": "/var/www/fwh-toolbox/server/fwh-mcp-server",
-    "args": [],
-    "env": {
-      // 若 MCP Server 需要额外环境变量可在此配置
-      // 例如："CONFIG_PATH": "/var/www/fwh-toolbox/server/.env"
-    },
-    "timeout": 30000
-  }
-}
-```
-
-### 4.4 注意事项
-
-1. **工作目录问题**：MCP Server 启动时的工作目录（cwd）决定了它能否找到 `.env` 配置文件。Kiro CLI 以 stdio 模式启动 MCP 进程时，cwd 默认为 Kiro CLI 的当前目录（即项目根目录），而非 `/var/www/fwh-toolbox/server`。
-
-   **解决方案**（任选其一）：
-
-   - **(推荐)** 在 MCP Server 代码中用绝对路径加载配置，不依赖 cwd
-   - 将 `.env` 软链接到项目根目录
-   - 使用 wrapper script 先 cd 到目标目录再启动
-2. **进程冲突**：如果 MCP Server 已通过 systemd 开机自启在后台运行，Kiro CLI 再启动一个新进程可能导致端口/资源冲突。但由于 MCP Server 使用 stdio 模式（无端口监听），且数据库连接是独立的，所以**可以安全并行运行**。
-3. **超时配置**：默认 30 秒超时。若某些查询（如大范围搜索）耗时较长，可适当调大 `timeout` 值。
-4. **环境变量传递**：如果 MCP Server 的 `.env` 依赖 `GIN_MODE`、`DB_HOST` 等环境变量，需要在 `env` 字段中显式传递，或确保这些变量在 Kiro CLI 的 shell 环境中已设置。
-
----
-
-## 5. 知识库接入
-
-### 5.1 两套知识库概览
-
-| 知识库     | 用途                              | 源路径                                                       | 格式     |
-| ---------- | --------------------------------- | ------------------------------------------------------------ | -------- |
-| 产品知识库 | FranklinWH 产品硬件/软件/系统知识 | `/home/jerry-remote/web/FranklinWH-Wiki/client/docs`       | Markdown |
-| 数据知识库 | 数据库字段解释、业务数据说明      | `/home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge` | Markdown |
-
-### 5.2 产品知识库
-
-**源路径**：`/home/jerry-remote/web/FranklinWH-Wiki/client/docs`
-
-**内容分类**：
-
-```
-docs/
-├── Hardware/          # 硬件知识
-│   ├── Gate/          #   aGate 系列（1.0, 1.2, 1.3, MSA_C）
-│   ├── Power/         #   aPower 系列（1.0, 1.2, 1.3, 2, S）
-│   └── Other/         #   其他配件（SplitCT, MeterKit, aPBox 等）
-├── Software/          # 软件知识
-│   ├── PCS.md         #   PCS 控制策略
-│   ├── EnergyStatistics.md  # 能量统计
-│   ├── ScriptingForSchedulingConfiguration.md  # 调度脚本
-│   └── ...            #   OTA、VPP、黑启动、电池加热等
-├── System/            # 系统知识
-│   ├── AlarmTable.md  #   告警代码表（重要！）
-│   ├── EventMessage.md#   事件消息列表
-│   ├── SystemConfig.md#   系统配置
-│   └── SystemDistribution.md  # 系统分布
-└── Other/             # 其他
-    ├── HostSideSoftware.md
-    └── TariffScheduleTemplates.md
-```
-
-**接入方式 — Kiro Knowledge 工具索引**：
-
-```bash
-# 在 Kiro CLI 中执行（首次需要手动索引）
-/knowledge add "FWH-Wiki-产品知识库" /home/jerry-remote/web/FranklinWH-Wiki/client/docs
-```
-
-**排除项**（索引时应排除）：
-
-- `.vitepress/` — VitePress 配置和缓存
-- `public/` — 静态资源（PDF、PPT、图片）
-- `index.md` — 仅导航页，无实质内容
-- `casdoor/` — 认证相关，非产品知识
-
-**为什么选择 Markdown 源码而非 HTML**：
-
-- Markdown 语义清晰，AI 理解效率高
-- 文件体积小，索引速度快
-- 直接与源码仓库同步，无需构建
-- 无 HTML 标签/CSS/JS 噪音
-
-### 5.3 数据知识库
-
-**源路径**：`/home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge`
-
-**当前状态**：目录已创建，内容待补充。
-
-**规划内容**：
-
-- 数据库表字段含义说明
-- MCP Tool 返回数据字段解释
-- 业务术语表（SN、GICCID、告警码含义等）
-- 功率流数据解读指南
-- 常见查询场景示例
-
-**建议的文件结构**：
-
-```
-docs/knowledge/
-├── README.md                    # 知识库说明
-├── site-info-fields.md          # 站点信息字段解释
-├── power-flow-guide.md          # 功率流数据解读
-├── alarm-codes.md               # 告警代码与严重程度
-├── sim-card-status.md           # SIM卡状态说明
-├── shutdown-analysis.md         # 停机统计分析指南
-└── glossary.md                  # 业务术语表
-```
-
-**接入方式**：
-
-```bash
-# 数据知识库索引
-/knowledge add "FWH-数据知识库" /home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge
-```
-
-### 5.4 知识库配置建议（Workspace Settings）
-
-在 `.kiro/settings/cli.json` 中可配置知识库参数：
-
-```jsonc
-{
-  "knowledge.defaultIncludePatterns": ["**/*.md"],
-  "knowledge.defaultExcludePatterns": [
-    "**/node_modules/**",
-    "**/.vitepress/**",
-    "**/public/**",
-    "**/cache/**"
-  ],
-  "knowledge.indexType": "best",   // 语义搜索（推荐）
-  "knowledge.chunkSize": 1000,
-  "knowledge.chunkOverlap": 200
-}
-```
-
-### 5.5 Agent resources 配置
-
-对于始终需要加载的关键知识（如术语表），可通过 `resources` 字段直接引入：
-
-```jsonc
-"resources": [
-  "file://docs/knowledge/**/*.md",           // 数据知识库全量加载
-  "skill://.kiro/skills/**/SKILL.md"         // 技能按需加载
-]
-```
-
-> **注意**：产品知识库文件较多且体积大，不适合通过 `resources` 全量加载到上下文，应通过 `knowledge` 工具按需检索。
-
----
-
-## 6. 权限控制与文件生成策略
-
-### 6.1 权限模型
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    权限控制总览                            │
-├─────────────────────┬───────────────────────────────────┤
-│ 读取项目文件         │ ✅ 允许（read/grep/glob/code）     │
-│ 修改项目源码         │ ❌ 禁止（不包含 write 工具）       │
-│ 执行 shell 命令     │ ⚠️  严格白名单（denyByDefault）    │
-│ 调用 MCP Tools      │ ✅ 允许（自动信任）                 │
-│ 搜索知识库          │ ✅ 允许（自动信任）                 │
-│ 创建临时文件        │ ✅ 仅限 /tmp/fwh-export/ 目录      │
-│ 上传到 MinIO        │ ✅ 通过扩展 MCP Tool 实现          │
-└─────────────────────┴───────────────────────────────────┘
-```
-
-### 6.2 文件生成方案
-
-由于 Agent 没有 `write` 工具，不能直接创建文件。需要通过以下两种方案实现文件生成：
-
-#### 方案 A：Shell 白名单 + 临时目录（轻量方案）
-
-**原理**：在 `shell` 工具的 `allowedCommands` 中加入写入临时目录的命令。
-
-**配置**：
-
-```jsonc
-"toolsSettings": {
-  "shell": {
-    "allowedCommands": [
-      "mkdir -p /tmp/fwh-export",
-      "tee /tmp/fwh-export/.*",
-      "cat .* > /tmp/fwh-export/.*",
-      "ls -la /tmp/fwh-export/.*",
-      "date",
-      "wc .*"
-    ],
-    "deniedCommands": [
-      "rm -rf .*",
-      "sudo .*",
-      "chmod .*",
-      "chown .*"
-    ],
-    "denyByDefault": true
-  }
-}
-```
-
-**限制**：
-
-- 只能生成纯文本/Markdown/CSV 文件
-- 无法生成 Excel(.xlsx) 或 PDF 二进制文件
-- 用户需要通过 `scp` 或 SSH 文件浏览器下载
-
-#### 方案 B：扩展 MCP Server（推荐方案）
-
-**原理**：在 MCP Server 中新增文件生成相关 Tool，由 Go 后端调用 `excelize`（Excel）或其他库生成文件，上传到 MinIO 并返回下载链接。
-
-**需要新增的 MCP Tools**：
-
-| Tool 名称          | 功能                     | 参数                                                                    |
-| ------------------ | ------------------------ | ----------------------------------------------------------------------- |
-| `export_report`  | 生成数据统计报告         | `type`(excel/pdf/csv), `template`, `data_query`, `expire_hours` |
-| `get_export_url` | 获取已生成文件的下载链接 | `file_id`                                                             |
-| `list_exports`   | 列出已生成的导出文件     | `page`, `size`                                                      |
-
-**实现示例（伪代码）**：
-
-```go
-// service/cmd/mcp/tools/export.go
-func RegisterExportTools(s *server.MCPServer) {
-    s.AddTool(
-        mcp.NewTool("export_report",
-            mcp.WithDescription("生成数据统计报告并上传到 MinIO，返回有时效的下载链接"),
-            mcp.WithString("type", mcp.Required(), mcp.Description("文件类型：excel, pdf, csv, markdown")),
-            mcp.WithString("title", mcp.Required(), mcp.Description("报告标题")),
-            mcp.WithString("content", mcp.Required(), mcp.Description("报告内容（JSON 结构化数据或 Markdown 文本）")),
-            mcp.WithNumber("expire_hours", mcp.Description("下载链接过期时间（小时），默认 24")),
-        ),
-        handleExportReport,
-    )
-}
-
-func handleExportReport(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    // 1. 解析参数
-    // 2. 根据 type 生成文件（excelize / go-pdf / csv / md）
-    // 3. 上传到 MinIO（设置过期策略）
-    // 4. 生成预签名下载 URL（带 expire_hours 过期）
-    // 5. 返回下载 URL 给 Agent
-}
-```
-
-**MinIO 过期策略**：
-
-- 使用 MinIO 的 Presigned URL（`GetPresignedURL`），URL 自带过期时间
-- 或配置 Bucket Lifecycle Rule，自动清理 N 天前的临时文件
-- 建议 Bucket 名：`fwh-export-temp`，Lifecycle 设为 7 天自动删除
-
-**优势**：
-
-- 可生成 Excel/PDF 等二进制格式
-- 返回可直接访问的下载链接
-- 过期自动清理，不占用长期存储
-- Agent 只需描述要导出的数据，后端负责格式化
-
-### 6.3 推荐实施路径
-
-```
-第一阶段：使用方案 A（shell 白名单写入临时目录）
-    ↓ 验证 Agent 工作流可行
-第二阶段：实现方案 B（MCP export_report Tool）
-    ↓ 支持 Excel/PDF 二进制文件生成
-第三阶段：前端集成下载入口（可选）
-    ↓ ToolBox Web UI 中展示导出历史和下载链接
-```
-
-### 6.4 提示词中的权限引导
-
-在 Agent 的系统提示词中需要明确告知权限限制：
-
-```markdown
-## 权限说明
-- 你没有写入项目文件的权限。如果用户要求修改代码，告知没有操作权限。
-- 你可以通过 export_report 工具生成数据报告，会返回带过期时间的下载链接。
-- 如果 export_report 工具不可用，你可以将内容输出为 Markdown 格式直接展示在对话中。
-- 任何需要持久化的操作都应通过 MCP Tools 完成。
-```
-
----
-
-## 7. Steering 引导文件
-
-### 7.1 文件位置
-
-```
-.kiro/steering/fwh-toolbox-context.md
-```
-
-### 7.2 内容规划
-
-```markdown
-# FWH ToolBox Agent 业务上下文
-
-## 产品背景
-FranklinWH 是一家家用储能系统公司，核心产品包括：
-- aGate：家庭能源管理网关（1.0/1.2/1.3/MSA_C 系列）
-- aPower：储能逆变器（1.0/1.2/1.3/2/S 系列）
-- 其他配件：SplitCT、MeterKit、aPBox、Generator Module
-
-## ToolBox 平台说明
-FWH ToolBox 是内部运维工具平台，提供：
-- 站点设备信息管理与查询
-- SIM 卡管理（SmartHub / Acceleronix 平台）
-- 告警/停机统计分析
-- 功率流数据可视化
-- 固件配置管理
-- 批量数据下载
-- 问题反馈提交（对接 Plane 项目管理）
-
-## 数据查询约定
-- 站点通过 SN（序列号）唯一标识
-- SIM 卡通过 GICCID（19位）唯一标识
-- 日期格式统一为 yyyy-MM-dd
-- 分页默认 page=1, size=10
-
-## 回复规范
-- 数据查询结果以结构化表格展示
-- 告警代码需关联知识库中的 AlarmTable 解释含义
-- 功率流数据回复时注明单位（W/kW/kWh）
-- 涉及多个站点时优先汇总统计，再按需展开详情
-```
-
-### 7.3 Prompt 文件
-
-建议创建独立的 prompt 文件，Agent 配置中通过 `file://` 引用：
-
-**文件位置**：`.kiro/prompts/fwh-toolbox-agent.md`
-
-**内容要点**：
-
-```markdown
-# FWH ToolBox Agent
-
-你是 FranklinWH ToolBox 平台的数据查询与分析助手。
-
-## 核心能力
-1. 通过 MCP Tools 查询站点、SIM卡、告警、停机、功率流等业务数据
-2. 结合产品知识库解答 FranklinWH 产品相关技术问题
-3. 生成数据统计报告（Excel/PDF/Markdown）
-4. 向 Plane 提交问题反馈和功能需求
-
-## 权限约束
-- ❌ 不能修改任何项目源码文件
-- ❌ 不能执行危险 shell 命令
-- ✅ 可以读取项目文件以理解代码逻辑
-- ✅ 可以通过 MCP Tools 查询和操作业务数据
-- ✅ 可以生成报告到临时目录或 MinIO
-
-## 工作流程
-1. 理解用户需求
-2. 如需产品知识 → 检索知识库
-3. 如需业务数据 → 调用 MCP Tools
-4. 如需生成文件 → 调用 export_report 或输出 Markdown
-5. 组织结果，清晰回复
-
-## 回复风格
-- 使用中文回复
-- 数据展示优先使用表格格式
-- 技术解释简洁清晰
-- 不确定的信息明确标注
-```

docs/kiro-cli-configuration-guide.md

@@ -1,1269 +0,0 @@
-# Kiro CLI 运行环境配置详细指南
-
-本文档详细描述 Kiro CLI 的所有配置项、配置文件位置、参数说明及示例。
-
----
-
-## 目录
-
-1. [配置体系概览](#1-配置体系概览)
-2. [目录结构](#2-目录结构)
-3. [全局设置 (cli.json)](#3-全局设置-clijson)
-4. [Agent 配置](#4-agent-配置)
-5. [Steering 文件（引导文件）](#5-steering-文件引导文件)
-6. [Skills 技能文件](#6-skills-技能文件)
-7. [Hooks 钩子系统](#7-hooks-钩子系统)
-8. [MCP 服务器配置](#8-mcp-服务器配置)
-9. [LSP 代码智能配置](#9-lsp-代码智能配置)
-10. [环境变量](#10-环境变量)
-11. [常用命令速查](#11-常用命令速查)
-
----
-
-## 1. 配置体系概览
-
-Kiro CLI 的配置分为多个层级，优先级从高到低：
-
-```
-Session（会话级）> Workspace（工作区级）> Global（全局级）
-```
-
-| 层级      | 说明                       | 适用范围   |
-| --------- | -------------------------- | ---------- |
-| Session   | 当前会话临时设置           | 仅当前会话 |
-| Workspace | 项目目录下的`.kiro/`     | 仅当前项目 |
-| Global    | 用户主目录下的`~/.kiro/` | 所有项目   |
-
----
-
-## 2. 目录结构
-
-### 全局目录 `~/.kiro/`
-
-```
-~/.kiro/
-├── agents/                    # 全局 Agent 配置
-│   ├── my-agent.json
-│   └── rust-expert.json
-├── prompts/                   # 全局提示词文件
-│   └── rust-expert.txt
-├── skills/                    # 全局技能文件
-│   └── my-skill/
-│       └── SKILL.md
-├── steering/                  # 全局引导文件
-│   ├── coding-standards.md
-│   └── preferences.md
-├── settings/
-│   ├── cli.json               # 全局设置
-│   └── mcp.json               # 全局 MCP 配置
-├── hooks/                     # 钩子脚本存放目录（可自定义）
-│   └── validate-write.sh
-├── sessions/cli/              # 保存的聊天会话
-└── .cli_bash_history          # Shell 命令历史
-```
-
-### 工作区目录 `.kiro/`（项目根目录下）
-
-```
-.kiro/
-├── agents/                    # 工作区 Agent 配置（优先级高于全局）
-│   └── project-helper.json
-├── skills/                    # 工作区技能文件
-│   └── db-helper/
-│       └── SKILL.md
-├── steering/                  # 工作区引导文件
-│   └── team-conventions.md
-└── settings/
-    ├── cli.json               # 工作区设置（覆盖全局）
-    └── mcp.json               # 工作区 MCP 配置
-```
-
-### 项目根目录其他配置文件
-
-```
-项目根目录/
-├── AGENTS.md                  # 项目 Agent 指令（自动加载）
-├── README.md                  # 项目说明（自动加载）
-├── AmazonQ.md                 # 旧版项目指令（如存在则加载）
-├── lsp.json                   # LSP 代码智能配置
-└── .amazonq/                  # 旧版配置（向后兼容）
-    ├── mcp.json
-    └── rules/**/*.md
-```
-
----
-
-## 3. 全局设置 (cli.json)
-
-### 文件位置
-
-| 作用域 | 文件路径                      |
-| ------ | ----------------------------- |
-| 全局   | `~/.kiro/settings/cli.json` |
-| 工作区 | `.kiro/settings/cli.json`   |
-
-### 完整设置项列表
-
-#### 3.1 Chat 聊天相关
-
-| 设置项                                     | 类型    | 默认值      | 说明                                      |
-| ------------------------------------------ | ------- | ----------- | ----------------------------------------- |
-| `chat.defaultAgent`                      | string  | _(无)_    | 新会话使用的默认 Agent 名称               |
-| `chat.defaultModel`                      | string  | _(无)_    | 默认 AI 模型 ID                           |
-| `chat.enableThinking`                    | boolean | -           | 启用思考工具                              |
-| `chat.showThinking`                      | boolean | `false`   | 显示思考/推理块（仅启动时生效）           |
-| `chat.enableKnowledge`                   | boolean | -           | 启用知识库功能                            |
-| `chat.enableCodeIntelligence`            | boolean | -           | 启用代码智能（LSP）                       |
-| `chat.enableSubagent`                    | boolean | -           | 启用子 Agent 功能                         |
-| `chat.enableTodoList`                    | boolean | -           | 启用待办列表功能                          |
-| `chat.enableNotifications`               | boolean | -           | 启用桌面通知                              |
-| `chat.greeting.enabled`                  | boolean | -           | 启动时显示欢迎消息                        |
-| `chat.allowAnimations`                   | boolean | `true`    | 启用加载动画（旋转、进度条）              |
-| `chat.allowAsciiArt`                     | boolean | `true`    | 启用 Unicode 符号，false 则降级为纯 ASCII |
-| `chat.allowIcons`                        | boolean | `true`    | 显示状态指示图标                          |
-| `chat.terminalTitle`                     | boolean | `false`   | 通过 OSC 0 更新终端窗口标题               |
-| `chat.disableAutoCompaction`             | boolean | -           | 禁用自动上下文压缩                        |
-| `chat.disableGranularTrust`              | boolean | -           | 禁用细粒度信任选项                        |
-| `chat.disableInheritingDefaultResources` | boolean | `false`   | 禁用自定义 Agent 继承默认资源             |
-| `chat.autoExpandToolOutput`              | boolean | -           | 始终展示完整工具输出                      |
-| `chat.disableWrap`                       | boolean | -           | 禁用聊天输出自动换行                      |
-| `chat.historyMode`                       | string  | `session` | 提示历史范围：`session` 或 `global`   |
-
-#### 3.2 快捷键
-
-| 设置项                            | 类型   | 默认值     | 说明           |
-| --------------------------------- | ------ | ---------- | -------------- |
-| `chat.keybindings.cancelStream` | string | `esc`    | 取消流式输出   |
-| `chat.keybindings.closeMenu`    | string | `esc`    | 关闭菜单/面板  |
-| `chat.keybindings.quit`         | string | `ctrl+c` | 退出（需双击） |
-
-快捷键语法：`修饰符+键`，大小写不敏感。
-
-- 修饰符：`ctrl`、`shift`、`alt`（别名 `meta`、`cmd`）
-- 键名：`esc`、`enter`、`tab`、`up`/`down`/`left`/`right`、`space`、`backspace`、`delete`、`home`、`end`、`pageup`/`pagedown`、`a-z`、`0-9`
-
-#### 3.3 遥测
-
-| 设置项                | 类型    | 默认值 | 说明                                                |
-| --------------------- | ------- | ------ | --------------------------------------------------- |
-| `telemetry.enabled` | boolean | -      | 启用/禁用遥测（**全局设置，不可工作区覆盖**） |
-
-#### 3.4 知识库
-
-| 设置项                               | 类型   | 默认值 | 说明                                              |
-| ------------------------------------ | ------ | ------ | ------------------------------------------------- |
-| `knowledge.defaultIncludePatterns` | array  | -      | 索引时包含的文件 glob 模式                        |
-| `knowledge.defaultExcludePatterns` | array  | -      | 索引时排除的文件 glob 模式                        |
-| `knowledge.maxFiles`               | number | -      | 索引的最大文件数                                  |
-| `knowledge.chunkSize`              | number | -      | 文本分块大小                                      |
-| `knowledge.chunkOverlap`           | number | -      | 分块之间的重叠大小                                |
-| `knowledge.indexType`              | string | -      | 索引类型：`fast`（BM25）或 `best`（语义搜索） |
-
-#### 3.5 API
-
-| 设置项                        | 类型   | 默认值 | 说明                                     |
-| ----------------------------- | ------ | ------ | ---------------------------------------- |
-| `api.timeout`               | number | -      | API 请求超时（毫秒）                     |
-| `api.codewhisperer.service` | string | -      | CodeWhisperer 端点（**全局设置**） |
-| `api.q.service`             | string | -      | Q 服务端点（**全局设置**）         |
-
-#### 3.6 MCP
-
-| 设置项                       | 类型   | 默认值 | 说明                         |
-| ---------------------------- | ------ | ------ | ---------------------------- |
-| `mcp.initTimeout`          | number | -      | MCP 服务器初始化超时（毫秒） |
-| `mcp.noInteractiveTimeout` | number | -      | 非交互式 MCP 超时（毫秒）    |
-
-#### 3.7 上下文压缩
-
-| 设置项                                     | 类型   | 默认值 | 说明                           |
-| ------------------------------------------ | ------ | ------ | ------------------------------ |
-| `compaction.excludeContextWindowPercent` | number | -      | 从压缩中排除的上下文窗口百分比 |
-| `compaction.excludeMessages`             | number | -      | 从压缩中排除的最近消息数量     |
-
-#### 3.8 Hooks
-
-| 设置项               | 类型    | 默认值 | 说明                                            |
-| -------------------- | ------- | ------ | ----------------------------------------------- |
-| `hooks.showStatus` | boolean | -      | 是否显示 hook 执行状态（设为 false 则静默运行） |
-
-### cli.json 完整示例
-
-**文件位置：`~/.kiro/settings/cli.json`**
-
-```json
-{
-  "chat.defaultAgent": "my-vue-agent",
-  "chat.defaultModel": "anthropic.claude-3-5-sonnet-20241022-v2:0",
-  "chat.enableThinking": true,
-  "chat.showThinking": false,
-  "chat.enableKnowledge": true,
-  "chat.enableCodeIntelligence": true,
-  "chat.enableSubagent": true,
-  "chat.enableTodoList": true,
-  "chat.enableNotifications": true,
-  "chat.greeting.enabled": true,
-  "chat.allowAnimations": true,
-  "chat.allowAsciiArt": true,
-  "chat.allowIcons": true,
-  "chat.terminalTitle": false,
-  "chat.disableAutoCompaction": false,
-  "chat.disableGranularTrust": false,
-  "chat.disableInheritingDefaultResources": false,
-  "chat.autoExpandToolOutput": false,
-  "chat.disableWrap": false,
-  "chat.historyMode": "global",
-  "chat.keybindings.cancelStream": "esc",
-  "chat.keybindings.closeMenu": "esc",
-  "chat.keybindings.quit": "ctrl+c",
-  "telemetry.enabled": true,
-  "knowledge.defaultIncludePatterns": ["**/*.ts", "**/*.vue", "**/*.md"],
-  "knowledge.defaultExcludePatterns": ["node_modules/**", "dist/**"],
-  "knowledge.maxFiles": 1000,
-  "knowledge.chunkSize": 512,
-  "knowledge.chunkOverlap": 50,
-  "knowledge.indexType": "best",
-  "api.timeout": 30000,
-  "mcp.initTimeout": 120000,
-  "mcp.noInteractiveTimeout": 30000,
-  "compaction.excludeContextWindowPercent": 10,
-  "compaction.excludeMessages": 5
-}
-```
-
----
-
-## 4. Agent 配置
-
-### 文件位置
-
-| 作用域 | 文件路径                       | 优先级                   |
-| ------ | ------------------------------ | ------------------------ |
-| 工作区 | `.kiro/agents/<name>.json`   | 高（覆盖同名全局 Agent） |
-| 全局   | `~/.kiro/agents/<name>.json` | 低                       |
-
-文件名（不含 `.json`）即为 Agent 名称。
-
-### 所有字段说明
-
-| 字段                 | 类型         | 必填 | 说明                                                      |
-| -------------------- | ------------ | ---- | --------------------------------------------------------- |
-| `name`             | string       | 否   | Agent 名称标识                                            |
-| `description`      | string       | 否   | 人类可读描述                                              |
-| `prompt`           | string       | 否   | 系统提示词（支持内联文本或`file:///path` 引用外部文件） |
-| `model`            | string       | 否   | 指定模型 ID，未指定则使用默认模型                         |
-| `tools`            | array        | 否   | 可用工具列表                                              |
-| `allowedTools`     | array        | 否   | 自动批准的工具（无需用户确认），支持通配符                |
-| `toolsSettings`    | object       | 否   | 工具级别的详细配置                                        |
-| `resources`        | array        | 否   | 上下文资源列表                                            |
-| `hooks`            | object/array | 否   | 触发器钩子配置                                            |
-| `mcpServers`       | object       | 否   | MCP 服务器配置                                            |
-| `toolAliases`      | object       | 否   | 工具名称重映射（解决命名冲突）                            |
-| `useLegacyMcpJson` | boolean      | 否   | 是否加载旧版`mcp.json` 配置                             |
-| `keyboardShortcut` | string       | 否   | 快速切换到此 Agent 的快捷键                               |
-| `welcomeMessage`   | string       | 否   | 切换到此 Agent 时显示的欢迎消息                           |
-
-### 内置工具列表
-
-以下工具可在 `tools` 字段中使用：
-
-| 工具名         | 别名                              | 说明                      |
-| -------------- | --------------------------------- | ------------------------- |
-| `read`       | `fs_read`, `fsRead`           | 读取文件/目录/图片        |
-| `write`      | `fs_write`, `fsWrite`         | 创建/编辑文件             |
-| `shell`      | `execute_bash`, `execute_cmd` | 执行终端命令              |
-| `grep`       | -                                 | 正则文本搜索              |
-| `glob`       | -                                 | 文件路径模式匹配          |
-| `code`       | -                                 | 代码智能（AST 搜索、LSP） |
-| `use_aws`    | -                                 | AWS CLI API 调用          |
-| `web_fetch`  | `webFetch`                      | 获取 URL 内容             |
-| `web_search` | -                                 | 网络搜索                  |
-| `knowledge`  | -                                 | 知识库索引和搜索          |
-| `subagent`   | `agent_crew`, `use_subagent`  | 子 Agent 流水线           |
-| `todo_list`  | `task`, `todo`                | 待办任务管理              |
-| `introspect` | -                                 | 查询 Kiro CLI 自身文档    |
-
-特殊值：
-
-- `"*"` — 所有工具（仅用于 `tools` 字段）
-- `"@builtin"` — 所有内置工具（可用于 `allowedTools`）
-
-### tools 与 allowedTools 的区别
-
-- **`tools`**：Agent 能使用哪些工具（能力范围）
-- **`allowedTools`**：哪些工具使用时无需用户确认（信任范围）
-
-### allowedTools 通配符模式
-
-```json
-{
-  "allowedTools": [
-    "read",              // 精确匹配内置工具
-    "fs_*",             // 前缀通配：匹配 fs_read, fs_write
-    "@git/git_status",  // 精确匹配 MCP 工具
-    "@server/read_*",   // MCP 工具通配
-    "@git",             // 该 MCP 服务器的所有工具
-    "@builtin"          // 所有内置工具
-  ]
-}
-```
-
-### toolsSettings 详细配置
-
-#### write 工具设置
-
-```json
-{
-  "toolsSettings": {
-    "write": {
-      "allowedPaths": ["src/**", "tests/**"],
-      "deniedPaths": ["node_modules/**", "/etc/**"]
-    }
-  }
-}
-```
-
-| 参数             | 类型  | 说明                     |
-| ---------------- | ----- | ------------------------ |
-| `allowedPaths` | array | 允许写入的路径 glob 模式 |
-| `deniedPaths`  | array | 禁止写入的路径 glob 模式 |
-
-#### shell 工具设置
-
-```json
-{
-  "toolsSettings": {
-    "shell": {
-      "allowedCommands": ["git status", "npm test", "pnpm build"],
-      "deniedCommands": ["rm -rf *", "sudo *", "shutdown"],
-      "autoAllowReadonly": true,
-      "denyByDefault": false
-    }
-  }
-}
-```
-
-| 参数                  | 类型    | 默认值    | 说明                                                  |
-| --------------------- | ------- | --------- | ----------------------------------------------------- |
-| `allowedCommands`   | array   | -         | 自动批准的命令（正则模式）                            |
-| `deniedCommands`    | array   | -         | 始终拒绝的命令（正则模式）                            |
-| `autoAllowReadonly` | boolean | -         | 自动批准只读命令（如`ls`、`cat`、`git status`） |
-| `denyByDefault`     | boolean | `false` | 默认拒绝未在 allowedCommands 中的命令                 |
-
-#### web_fetch 工具设置
-
-```json
-{
-  "toolsSettings": {
-    "web_fetch": {
-      "trusted": [".*docs\\.aws\\.amazon\\.com.*", ".*vuejs\\.org.*"],
-      "blocked": [".*pastebin\\.com.*"]
-    }
-  }
-}
-```
-
-| 参数        | 类型  | 说明                                          |
-| ----------- | ----- | --------------------------------------------- |
-| `trusted` | array | 自动允许的 URL 正则模式                       |
-| `blocked` | array | 始终阻止的 URL 正则模式（优先级高于 trusted） |
-
-### resources 资源配置
-
-支持两种 URI 协议：
-
-| 协议         | 加载方式 | 说明                                         |
-| ------------ | -------- | -------------------------------------------- |
-| `file://`  | 始终加载 | 内容始终存在于上下文窗口                     |
-| `skill://` | 按需加载 | 仅元数据（名称、描述）初始加载，内容按需加载 |
-
-```json
-{
-  "resources": [
-    "file://README.md",
-    "file://src/**/*.vue",
-    "file://docs/api.md",
-    "skill://.kiro/skills/**/SKILL.md"
-  ]
-}
-```
-
-### 默认资源继承
-
-自定义 Agent 默认会自动继承以下资源：
-
-| 资源                                  | 说明               |
-| ------------------------------------- | ------------------ |
-| `file://AGENTS.md`                  | 项目 Agent 指令    |
-| `file://README.md`                  | 项目说明           |
-| `skill://.kiro/skills/*/SKILL.md`   | 工作区技能         |
-| `skill://~/.kiro/skills/*/SKILL.md` | 全局技能           |
-| `file://~/.kiro/steering/**/*.md`   | 全局引导文件       |
-| `file://.kiro/steering/**/*.md`     | 工作区引导文件     |
-| `file://AmazonQ.md`                 | 旧版指令（如存在） |
-
-设置 `chat.disableInheritingDefaultResources` 为 `true` 可禁用此继承。
-
-### Agent 完整示例
-
-**文件位置：`.kiro/agents/vue-dev.json`**
-
-```json
-{
-  "name": "vue-dev",
-  "description": "Vue 3 + TypeScript 开发助手",
-  "prompt": "你是一个 Vue 3 + TypeScript 专家。使用 Composition API、Naive UI 组件库和 UnoCSS。遵循项目现有的代码风格和架构。",
-  "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
-  "tools": [
-    "read", "write", "shell", "grep", "glob", "code", "web_fetch", "knowledge"
-  ],
-  "allowedTools": [
-    "read", "grep", "glob", "code"
-  ],
-  "toolsSettings": {
-    "write": {
-      "allowedPaths": ["src/**", "docs/**", "tests/**"],
-      "deniedPaths": ["node_modules/**", "dist/**"]
-    },
-    "shell": {
-      "allowedCommands": [
-        "pnpm (dev|build|test|lint)",
-        "git (status|diff|log|branch)",
-        "npx vue-tsc"
-      ],
-      "deniedCommands": ["rm -rf", "sudo"],
-      "autoAllowReadonly": true
-    },
-    "web_fetch": {
-      "trusted": [".*vuejs\\.org.*", ".*naiveui\\.com.*"],
-      "blocked": [".*pastebin\\.com.*"]
-    }
-  },
-  "resources": [
-    "file://src/**/*.vue",
-    "file://src/**/*.ts",
-    "file://package.json",
-    "file://tsconfig.json",
-    "skill://.kiro/skills/**/SKILL.md"
-  ],
-  "hooks": {
-    "agentSpawn": [
-      { "command": "git branch --show-current && node -v" }
-    ],
-    "preToolUse": [
-      {
-        "matcher": "write",
-        "command": "echo 'Writing file...'"
-      }
-    ]
-  },
-  "mcpServers": {
-    "git": {
-      "command": "mcp-server-git",
-      "args": ["--stdio"]
-    }
-  },
-  "keyboardShortcut": "ctrl+shift+v",
-  "welcomeMessage": "Vue 3 开发助手已就绪！有什么可以帮你的？"
-}
-```
-
----
-
-## 5. Steering 文件（引导文件）
-
-Steering 文件是持久化的指令文档，用于在所有会话中引导 Agent 行为。
-
-### 文件位置
-
-| 作用域 | 目录路径              |
-| ------ | --------------------- |
-| 工作区 | `.kiro/steering/`   |
-| 全局   | `~/.kiro/steering/` |
-
-目录会被递归扫描，任何层级的 `.md` 文件都会被加载。
-
-### 加载规则
-
-- **内置默认 Agent (`kiro_default`)**：自动加载 steering 文件
-- **自定义 Agent**：需要手动在 `resources` 中声明：
-  ```json
-  { "resources": ["file://.kiro/steering/**/*.md"] }
-  ```
-
-### inclusion 控制
-
-Steering 文件支持可选的 YAML frontmatter 来控制加载时机：
-
-| inclusion 值         | 行为                                   |
-| -------------------- | -------------------------------------- |
-| `always`           | 始终加载（默认，等同于无 frontmatter） |
-| `fileMatch`        | 仅在处理匹配文件时加载（排除自动加载） |
-| `manual`           | 仅通过`/context add` 手动加载        |
-| _(无 frontmatter)_ | 始终加载                               |
-
-### Steering 文件示例
-
-**文件位置：`.kiro/steering/coding-standards.md`**
-
-```markdown
-# 项目编码规范
-
-## Vue 组件
-- 使用 Composition API + `<script setup>` 语法
-- 组件命名使用 PascalCase
-- Props 必须使用 TypeScript 类型定义
-- 使用 Naive UI 组件库
-
-## TypeScript
-- 严格模式，禁止 `any`
-- 函数参数和返回值必须有类型标注
-- 使用 `es-toolkit` 代替 lodash
-
-## 样式
-- 使用 UnoCSS 原子类
-- 避免写自定义 CSS，除非必要
-- 暗色模式必须适配
-```
-
-**文件位置：`~/.kiro/steering/personal-preferences.md`**
-
-```markdown
-# 个人偏好
-
-- 回答使用中文
-- 代码注释使用英文
-- 优先给出完整可运行的代码
-- 修改代码前先阅读现有实现
-- 保持简洁，不要过度设计
-```
-
-**带 inclusion 控制的示例：`.kiro/steering/vue-rules.md`**
-
-```markdown
----
-inclusion: always
----
-
-# Vue 开发规则
-
-- 所有组件必须定义 `name` 选项
-- 使用 `defineProps` 和 `defineEmits` 宏
-- 大型表单使用 Naive UI 的 NForm
-```
-
----
-
-## 6. Skills 技能文件
-
-Skills 是按需加载的资源，启动时仅加载元数据，实际内容在需要时才加载，节省上下文窗口空间。
-
-### 文件位置
-
-| 作用域 | 目录路径                                 |
-| ------ | ---------------------------------------- |
-| 工作区 | `.kiro/skills/<skill-name>/SKILL.md`   |
-| 全局   | `~/.kiro/skills/<skill-name>/SKILL.md` |
-
-### 格式要求
-
-Skill 文件**必须**以 YAML frontmatter 开头：
-
-```markdown
----
-name: vue-component-patterns
-description: Vue 3 组件设计模式指南。在设计新组件或重构现有组件时使用。
----
-
-# Vue 3 组件设计模式
-
-## Compound Components Pattern
-
-...详细内容...
-```
-
-| frontmatter 字段 | 必填 | 说明                                     |
-| ---------------- | ---- | ---------------------------------------- |
-| `name`         | 是   | 技能名称                                 |
-| `description`  | 是   | 描述（Agent 根据此决定是否加载完整内容） |
-
-### 在 Agent 中引用 Skills
-
-```json
-{
-  "resources": [
-    "skill://.kiro/skills/**/SKILL.md",
-    "skill://~/.kiro/skills/**/SKILL.md"
-  ]
-}
-```
-
-### Skills 示例
-
-**文件位置：`.kiro/skills/naive-ui-patterns/SKILL.md`**
-
-```markdown
----
-name: naive-ui-patterns
-description: Naive UI 组件库常用模式和最佳实践。在使用 Naive UI 组件开发界面时参考。
----
-
-# Naive UI 常用模式
-
-## 表格 (DataTable)
-
-使用 `NDataTable` 时的标准模式：
-
-\`\`\`vue
-<script setup lang="ts">
-import { NDataTable } from 'naive-ui'
-import type { DataTableColumns } from 'naive-ui'
-
-interface RowData {
-  id: string
-  name: string
-}
-
-const columns: DataTableColumns<RowData> = [
-  { title: 'ID', key: 'id' },
-  { title: '名称', key: 'name' }
-]
-</script>
-\`\`\`
-
-## 表单 (Form)
-
-...
-```
-
----
-
-## 7. Hooks 钩子系统
-
-Hooks 允许在 Agent 生命周期的特定时间点执行自定义命令。
-
-### 配置位置
-
-Hooks 配置在 **Agent 配置文件** 中（`.kiro/agents/<name>.json` 或 `~/.kiro/agents/<name>.json`）。
-
-### 触发时机
-
-| 触发器               | 时机                 | 可否阻止工具执行       |
-| -------------------- | -------------------- | ---------------------- |
-| `agentSpawn`       | Agent 初始化时       | -                      |
-| `userPromptSubmit` | 用户提交消息时       | -                      |
-| `preToolUse`       | 工具执行前           | ✅ 可通过退出码 2 阻止 |
-| `postToolUse`      | 工具执行后           | -                      |
-| `stop`             | Assistant 完成回复时 | -                      |
-
-### 退出码含义
-
-| 退出码 | 含义                                             |
-| ------ | ------------------------------------------------ |
-| `0`  | 成功，STDOUT 加入 Agent 上下文                   |
-| `2`  | （仅 preToolUse）阻止工具执行，STDERR 返回给 LLM |
-| 其他   | 失败，STDERR 作为警告显示给用户                  |
-
-### 两种配置格式
-
-#### Object 格式（推荐）
-
-```json
-{
-  "hooks": {
-    "agentSpawn": [
-      {
-        "command": "git status && git branch --show-current",
-        "timeout_ms": 5000,
-        "cache_ttl_seconds": 0
-      }
-    ],
-    "userPromptSubmit": [
-      { "command": "date '+%Y-%m-%d %H:%M:%S'" }
-    ],
-    "preToolUse": [
-      {
-        "matcher": "write",
-        "command": "~/.kiro/hooks/validate-write.sh",
-        "timeout_ms": 10000,
-        "max_output_size": 10240
-      }
-    ],
-    "postToolUse": [
-      {
-        "matcher": "shell",
-        "command": "echo 'Command executed'"
-      }
-    ],
-    "stop": [
-      { "command": "echo 'Turn complete'" }
-    ]
-  }
-}
-```
-
-Object 格式字段：
-
-| 字段                  | 必填 | 类型   | 默认值    | 说明                                      |
-| --------------------- | ---- | ------ | --------- | ----------------------------------------- |
-| `command`           | 是   | string | -         | 要执行的命令                              |
-| `matcher`           | 否   | string | -         | 工具匹配模式（仅 preToolUse/postToolUse） |
-| `timeout_ms`        | 否   | number | `10000` | 最大执行时间（毫秒）                      |
-| `max_output_size`   | 否   | number | `10240` | 最大输出字节数（超出则截断）              |
-| `cache_ttl_seconds` | 否   | number | `0`     | 缓存成功结果的秒数（0=不缓存）            |
-
-#### Array 格式
-
-```json
-{
-  "hooks": [
-    {
-      "name": "show-git-status",
-      "trigger": "agentSpawn",
-      "action": { "type": "command", "command": "git status" },
-      "timeout": 10,
-      "enabled": true
-    },
-    {
-      "name": "validate-write",
-      "trigger": "preToolUse",
-      "matcher": "write",
-      "action": { "type": "command", "command": "~/.kiro/hooks/validate-write.sh" },
-      "timeout": 30,
-      "enabled": true
-    }
-  ]
-}
-```
-
-Array 格式字段：
-
-| 字段        | 必填 | 类型    | 默认值   | 说明                                        |
-| ----------- | ---- | ------- | -------- | ------------------------------------------- |
-| `name`    | 否   | string  | -        | 可读名称                                    |
-| `trigger` | 是   | string  | -        | 触发器名称                                  |
-| `matcher` | 否   | string  | -        | 工具匹配模式                                |
-| `action`  | 是   | object  | -        | `{ "type": "command", "command": "..." }` |
-| `timeout` | 否   | number  | `10`   | 最大执行时间（**秒**）                |
-| `enabled` | 否   | boolean | `true` | 设为 false 可禁用而不删除                   |
-
-### Matcher 匹配模式
-
-| 模式               | 说明                      | 示例                     |
-| ------------------ | ------------------------- | ------------------------ |
-| 精确匹配           | 匹配特定工具              | `"write"`、`"shell"` |
-| 通配符             | 匹配工具名模式            | `"fs_*"`               |
-| MCP 服务器全部工具 | 匹配某个 MCP 服务器       | `"@git"`               |
-| MCP 特定工具       | 匹配 MCP 服务器的特定工具 | `"@git/status"`        |
-| 所有工具           | 匹配所有                  | `"*"`                  |
-| 所有内置工具       | 仅内置                    | `"@builtin"`           |
-| 无 matcher         | 应用于所有工具            | _(不设置)_             |
-
-### Hook 收到的 STDIN 数据
-
-Hook 通过 STDIN 接收 JSON 格式的事件数据：
-
-```json
-{
-  "hook_event_name": "preToolUse",
-  "cwd": "/home/user/project",
-  "tool_name": "fs_write",
-  "tool_input": {
-    "path": "/home/user/project/src/App.vue",
-    "command": "create",
-    "content": "..."
-  }
-}
-```
-
-### 环境变量
-
-Hook 脚本可访问 `KIRO_SESSION_ID` 环境变量（当前会话 UUID）。
-
-### Hook 脚本示例
-
-**文件位置：`~/.kiro/hooks/validate-write.sh`**
-
-```bash
-#!/bin/bash
-# 读取 hook 事件
-EVENT=$(cat)
-
-# 提取文件路径
-FILE=$(echo "$EVENT" | jq -r '.tool_input.path // empty')
-
-# 阻止写入 .env 文件
-if [[ "$FILE" == *".env"* ]]; then
-  echo "禁止修改 .env 文件" >&2
-  exit 2  # 退出码 2 = 阻止工具执行
-fi
-
-exit 0  # 允许执行
-```
-
----
-
-## 8. MCP 服务器配置
-
-MCP (Model Context Protocol) 服务器为 Agent 提供额外的工具能力。
-
-### 配置位置
-
-MCP 服务器可在以下位置配置：
-
-| 位置       | 路径                                                | 说明                           |
-| ---------- | --------------------------------------------------- | ------------------------------ |
-| Agent 配置 | `.kiro/agents/<name>.json` 的 `mcpServers` 字段 | 特定 Agent 专用                |
-| 全局 MCP   | `~/.kiro/settings/mcp.json`                       | 所有 Agent 可用                |
-| 工作区 MCP | `.kiro/settings/mcp.json`                         | 当前项目所有 Agent 可用        |
-| 旧版全局   | `~/.aws/amazonq/mcp.json`                         | 需要`useLegacyMcpJson: true` |
-| 旧版工作区 | `.amazonq/mcp.json`                               | 需要`useLegacyMcpJson: true` |
-
-### 三种服务器类型
-
-#### 8.1 本地 (stdio) 服务器
-
-通过子进程启动，使用标准输入/输出通信。
-
-```json
-{
-  "mcpServers": {
-    "git": {
-      "command": "mcp-server-git",
-      "args": ["--stdio"],
-      "env": {
-        "GIT_DIR": "/path/to/repo"
-      },
-      "timeout": 120000,
-      "disabled": false,
-      "disabledTools": ["dangerous_tool"]
-    }
-  }
-}
-```
-
-| 字段              | 必填 | 类型    | 默认值     | 说明                   |
-| ----------------- | ---- | ------- | ---------- | ---------------------- |
-| `command`       | 是   | string  | -          | 启动服务器的命令       |
-| `args`          | 否   | array   | -          | 命令参数               |
-| `env`           | 否   | object  | -          | 环境变量               |
-| `timeout`       | 否   | number  | `120000` | 请求超时（毫秒）       |
-| `disabled`      | 否   | boolean | `false`  | 是否禁用此服务器       |
-| `disabledTools` | 否   | array   | -          | 禁用该服务器的特定工具 |
-
-#### 8.2 远程 (HTTP) 服务器
-
-通过 HTTP/SSE 连接远程服务器。
-
-```json
-{
-  "mcpServers": {
-    "remote-api": {
-      "url": "https://mcp.example.com/sse",
-      "headers": {
-        "Authorization": "Bearer $API_TOKEN"
-      },
-      "timeout": 120000,
-      "disabled": false,
-      "disabledTools": [],
-      "forceAuth": false
-    }
-  }
-}
-```
-
-| 字段              | 必填 | 类型    | 默认值     | 说明                         |
-| ----------------- | ---- | ------- | ---------- | ---------------------------- |
-| `url`           | 是   | string  | -          | HTTP 端点 URL                |
-| `headers`       | 否   | object  | -          | HTTP 请求头                  |
-| `oauth`         | 否   | object  | -          | OAuth 配置对象               |
-| `oauthScopes`   | 否   | array   | -          | OAuth 作用域                 |
-| `timeout`       | 否   | number  | `120000` | 请求超时（毫秒）             |
-| `disabled`      | 否   | boolean | `false`  | 是否禁用                     |
-| `disabledTools` | 否   | array   | -          | 禁用特定工具                 |
-| `forceAuth`     | 否   | boolean | `false`  | 跳过无认证尝试，直接走 OAuth |
-
-**OAuth 配置对象**：
-
-```json
-{
-  "mcpServers": {
-    "slack": {
-      "url": "https://mcp.slack.com/mcp",
-      "oauth": {
-        "clientId": "my-app-id",
-        "clientSecret": "my-secret",
-        "redirectUri": "http://localhost:7778/oauth/callback",
-        "oauthScopes": ["search:read", "channels:read"]
-      }
-    }
-  }
-}
-```
-
-| oauth 字段       | 说明                                                  |
-| ---------------- | ----------------------------------------------------- |
-| `clientId`     | 预注册的 OAuth 客户端 ID（设置后跳过动态客户端注册）  |
-| `clientSecret` | OAuth 客户端密钥（机密客户端）                        |
-| `redirectUri`  | 回调 URI（格式：`host:port`、`:port` 或完整 URL） |
-| `oauthScopes`  | 请求的 OAuth 作用域                                   |
-
-#### 8.3 Registry 服务器
-
-从组织 MCP 注册表解析的服务器（企业版功能）。
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "type": "registry",
-      "env": {
-        "GITHUB_TOKEN": "$GITHUB_TOKEN"
-      },
-      "timeout": 60000
-    }
-  }
-}
-```
-
-| 字段        | 必填 | 类型   | 说明                               |
-| ----------- | ---- | ------ | ---------------------------------- |
-| `type`    | 是   | string | 必须为`"registry"`               |
-| `env`     | 否   | object | 环境变量（覆盖注册表默认值）       |
-| `headers` | 否   | object | HTTP 头（远程 registry 服务器）    |
-| `timeout` | 否   | number | 请求超时                           |
-| `oauth`   | 否   | object | OAuth 配置（远程 registry 服务器） |
-
-### MCP 配置完整示例
-
-**在 Agent 配置中（`.kiro/agents/full-stack.json`）：**
-
-```json
-{
-  "name": "full-stack",
-  "tools": ["read", "write", "shell", "code"],
-  "mcpServers": {
-    "git": {
-      "command": "mcp-server-git",
-      "args": ["--stdio"]
-    },
-    "github": {
-      "command": "mcp-server-github",
-      "args": ["--stdio"],
-      "env": {
-        "GITHUB_TOKEN": "$GITHUB_TOKEN"
-      }
-    },
-    "postgres": {
-      "command": "mcp-server-postgres",
-      "args": ["--stdio"],
-      "env": {
-        "DATABASE_URL": "$DATABASE_URL"
-      },
-      "disabledTools": ["drop_table", "truncate"]
-    }
-  }
-}
-```
-
----
-
-## 9. LSP 代码智能配置
-
-### 文件位置
-
-项目根目录下的 `lsp.json`。
-
-### 初始化
-
-```bash
-# 在聊天中执行
-/code init
-
-# 强制重新初始化
-/code init -f
-```
-
-首次执行 `/code init` 后会创建 `lsp.json`，后续启动时自动加载。删除 `lsp.json` 即可禁用。
-
-### 预配置的语言服务器
-
-| 语言          | 文件扩展名                        | 服务器                     | 安装命令                                                     |
-| ------------- | --------------------------------- | -------------------------- | ------------------------------------------------------------ |
-| TypeScript/JS | `.ts` `.js` `.tsx` `.jsx` | typescript-language-server | `npm install -g typescript-language-server typescript`     |
-| Rust          | `.rs`                           | rust-analyzer              | `rustup component add rust-analyzer`                       |
-| Python        | `.py`                           | pyright                    | `pip install pyright`                                      |
-| Go            | `.go`                           | gopls                      | `go install golang.org/x/tools/gopls@latest`               |
-| Java          | `.java`                         | jdtls                      | `brew install jdtls` (macOS)                               |
-| Kotlin        | `.kt` `.kts`                  | kotlin-lsp                 | [GitHub 下载](https://github.com/fwcd/kotlin-language-server) |
-| Ruby          | `.rb`                           | solargraph                 | `gem install solargraph`                                   |
-| C/C++         | `.c` `.cpp` `.h` `.hpp`   | clangd                     | `apt install clangd` (Linux)                               |
-
-### 自定义语言服务器
-
-**文件位置：项目根目录 `lsp.json`**
-
-```json
-{
-  "languages": {
-    "vue": {
-      "name": "vue-language-server",
-      "command": "vue-language-server",
-      "args": ["--stdio"],
-      "file_extensions": ["vue"],
-      "project_patterns": ["package.json", "vite.config.ts"],
-      "exclude_patterns": ["**/node_modules/**", "**/dist/**"],
-      "multi_workspace": false,
-      "initialization_options": {
-        "typescript": {
-          "tsdk": "node_modules/typescript/lib"
-        }
-      },
-      "request_timeout_secs": 60
-    }
-  }
-}
-```
-
-| 字段                       | 必填 | 类型    | 默认值    | 说明                            |
-| -------------------------- | ---- | ------- | --------- | ------------------------------- |
-| `name`                   | 是   | string  | -         | 语言服务器显示名                |
-| `command`                | 是   | string  | -         | 启动命令                        |
-| `args`                   | 否   | array   | -         | 命令参数（通常`["--stdio"]`） |
-| `file_extensions`        | 是   | array   | -         | 处理的文件扩展名                |
-| `project_patterns`       | 否   | array   | -         | 项目根标识文件                  |
-| `exclude_patterns`       | 否   | array   | -         | 排除的 glob 模式                |
-| `multi_workspace`        | 否   | boolean | `false` | 是否支持多工作区                |
-| `initialization_options` | 否   | object  | -         | LSP 初始化选项                  |
-| `request_timeout_secs`   | 否   | number  | `60`    | 请求超时（秒）                  |
-
----
-
-## 10. 环境变量
-
-以下环境变量可影响 Kiro CLI 的运行行为：
-
-| 变量名                  | 说明                                             |
-| ----------------------- | ------------------------------------------------ |
-| `KIRO_HOME`           | 覆盖全局配置目录（默认`~/.kiro`）              |
-| `KIRO_DATA_DIR`       | 覆盖运行时数据目录（默认因平台而异）             |
-| `KIRO_ASCII_MODE=1`   | 强制 ASCII 模式，忽略`chat.allowAsciiArt` 设置 |
-| `KIRO_CHAT_LOG_FILE`  | 自定义日志文件路径                               |
-| `KIRO_LOG_NO_COLOR=1` | 禁用日志中的 ANSI 颜色                           |
-| `KIRO_SESSION_ID`     | （Hook 脚本可用）当前会话 UUID                   |
-| `$EDITOR`             | 编辑 Agent 配置时使用的编辑器                    |
-
-### 数据目录默认位置
-
-| 平台    | 路径                                       |
-| ------- | ------------------------------------------ |
-| macOS   | `~/Library/Application Support/kiro-cli` |
-| Linux   | `~/.local/share/kiro-cli`                |
-| Windows | `%LOCALAPPDATA%\kiro-cli`                |
-
-### 日志文件默认位置
-
-| 平台    | 路径                                        |
-| ------- | ------------------------------------------- |
-| macOS   | `$TMPDIR/kiro-log/kiro-chat.log`          |
-| Linux   | `$XDG_RUNTIME_DIR/kiro-log/kiro-chat.log` |
-| Windows | `%TEMP%/kiro-log/logs/kiro-chat.log`      |
-
-### 示例
-
-```bash
-# 使用自定义配置目录
-KIRO_HOME=/opt/team/kiro kiro-cli chat
-
-# 使用自定义数据目录（企业部署场景）
-KIRO_DATA_DIR=/opt/kiro/data kiro-cli chat
-
-# 自定义日志路径
-KIRO_CHAT_LOG_FILE=/tmp/kiro-debug.log kiro-cli chat
-
-# 强制 ASCII 模式（SSH/无 Unicode 终端）
-KIRO_ASCII_MODE=1 kiro-cli chat
-```
-
----
-
-## 11. 常用命令速查
-
-### 设置管理
-
-```bash
-# 查看所有可用设置
-kiro-cli settings list --all
-
-# 获取设置值
-kiro-cli settings chat.defaultModel
-
-# 修改设置
-kiro-cli settings chat.defaultModel "anthropic.claude-3-5-sonnet-20241022-v2:0"
-kiro-cli settings chat.defaultAgent "vue-dev"
-kiro-cli settings telemetry.enabled false
-kiro-cli settings knowledge.indexType "best"
-
-# 删除设置（恢复默认）
-kiro-cli settings --delete chat.defaultModel
-
-# 通配符删除
-kiro-cli settings --delete "knowledge.*"
-
-# 在编辑器中打开设置文件
-kiro-cli settings open
-```
-
-### Agent 管理
-
-```bash
-# 列出所有 Agent
-kiro-cli agent list
-
-# 创建 Agent
-kiro-cli agent create my-agent
-kiro-cli agent create my-agent --from kiro_default
-kiro-cli agent create my-agent --directory .kiro/agents
-
-# 编辑 Agent
-kiro-cli agent edit my-agent
-
-# 验证配置
-kiro-cli agent validate --path .kiro/agents/my-agent.json
-
-# 设置默认 Agent
-kiro-cli agent set-default my-agent
-```
-
-### 聊天会话
-
-```bash
-# 启动聊天
-kiro-cli chat
-
-# 使用指定 Agent 和模型
-kiro-cli chat --agent vue-dev --model <model-id>
-
-# 信任所有工具（无需确认）
-kiro-cli chat --trust-all-tools
-
-# 信任特定工具
-kiro-cli chat --trust-tools=read,grep,code
-
-# 恢复上次会话
-kiro-cli chat --resume
-
-# 选择会话恢复
-kiro-cli chat --resume-picker
-
-# 无头模式（自动化）
-kiro-cli chat --no-interactive --trust-all-tools "运行测试并汇总结果"
-
-# 设置推理强度
-kiro-cli chat --effort high "Review this code"
-```
-
-### TUI 内斜杠命令
-
-```
-/settings              打开设置菜单
-/settings display      显示设置（动画、ASCII、图标）
-/settings theme        主题设置
-/settings terminal     终端多行输入配置
-/settings history      历史记录范围
-
-/agent                 列出/切换 Agent
-/agent create          创建新 Agent
-/agent edit            编辑当前 Agent
-
-/model                 切换模型
-/tools                 查看可用工具
-/hooks                 查看当前 Hook 配置
-/context               查看上下文窗口使用情况
-/context show          显示上下文文件详情
-/context add <path>    添加临时上下文文件
-
-/code init             初始化代码智能
-/code init -f          强制重新初始化
-/code status           查看 LSP 状态
-/code overview         代码库概览
-
-/mcp                   查看 MCP 服务器状态
-/mcp add               添加 MCP 服务器
-/mcp remove            移除 MCP 服务器
-
-/chat save             保存当前会话
-/chat load             加载历史会话
-
-/guide                 切换到帮助 Agent
-/help                  查看所有斜杠命令
-```
-
----
-
-## 快速上手：为当前项目配置 Kiro CLI
-
-### 步骤 1：创建工作区配置目录
-
-```bash
-mkdir -p .kiro/agents .kiro/steering .kiro/skills
-```
-
-### 步骤 2：创建项目 Agent
-
-创建 `.kiro/agents/project-dev.json`：
-
-```json
-{
-  "name": "project-dev",
-  "description": "FranklinWH ToolBox 项目开发助手",
-  "prompt": "你是一个 Vue 3 + TypeScript + Naive UI 项目的开发助手。项目使用 Vite 构建，pnpm 管理依赖，UnoCSS 编写样式。",
-  "tools": ["read", "write", "shell", "grep", "glob", "code", "web_fetch"],
-  "allowedTools": ["read", "grep", "glob", "code"],
-  "toolsSettings": {
-    "shell": {
-      "allowedCommands": ["pnpm", "npx", "git (status|diff|log|branch)"],
-      "autoAllowReadonly": true
-    },
-    "write": {
-      "deniedPaths": ["node_modules/**", "dist/**"]
-    }
-  },
-  "resources": [
-    "file://src/**/*.vue",
-    "file://src/**/*.ts",
-    "file://package.json"
-  ],
-  "hooks": {
-    "agentSpawn": [
-      { "command": "git branch --show-current" }
-    ]
-  }
-}
-```
-
-### 步骤 3：添加引导文件
-
-创建 `.kiro/steering/project-rules.md`：
-
-```markdown
-# 项目规范
-
-- 使用 Vue 3 Composition API + <script setup>
-- UI 库：Naive UI
-- 样式：UnoCSS 原子类
-- 工具函数库：es-toolkit
-- 日期处理：dayjs
-- 图表：@antv/g2 和 uplot
-- 包管理器：pnpm（使用 pnpm@10）
-```
-
-### 步骤 4：设为默认 Agent
-
-```bash
-kiro-cli settings chat.defaultAgent project-dev
-```
-
----
-
-> 本文档基于 Kiro CLI 官方文档整理，配置项可能随版本更新而变化。使用 `kiro-cli settings list --all` 查看当前版本支持的所有设置。

service/.kiro/steering/project.md

@@ -1,25 +0,0 @@
-# FranklinWH-ToolBox 项目上下文
-
-## 项目概述
-FranklinWH-ToolBox 是 FranklinWH 内部工具平台。
-- 前端：Vue 3 + Naive UI + TypeScript + Vite
-- 后端：Go (Fiber) + MongoDB + PostgreSQL + Redis
-- 部署：Linux 服务器
-
-## 可用 MCP 工具
-- fwh-tools: 查询站点信息、SIM卡数据、功率流、告警统计、Plane Issue
-- team-knowledge: 搜索团队知识库文档
-- aws-docs: 搜索 AWS 文档
-- web-search: 网络搜索技术资料
-
-## 开发规范
-- 前端组件使用 Composition API + script setup
-- 后端采用 Controller → Service → Repository 分层
-- API 路由注册在 service/routes/
-- Plane V2 Web API 用于项目管理集成
-
-## 注意事项
-- 不要直接操作 Git（无 Git MCP Server）
-- 修改代码前先查阅项目规范
-- 后端修改后需要 go build 验证
-- 前端修改后需要 npm run build 验证