---
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 电价模板构建/写入的完整字段字典、日类型配套逻辑、功率哨兵值、优先级→调度策略速查与请求体示例。