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

核心原则：

优先 service_*，它包含完整业务逻辑与格式化输出。
仅在 service 层不足时才用 data_* 直查，且只读。
描述中标注 [写操作] 的工具会由 Agent 权限管控，执行前需用户确认。
data_mongo_* 有 collection 白名单，storage_minio_* 有 bucket 白名单（见对应章节）。
不要臆造工具名。全部可用工具见本文件与 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. 站点 / 设备查询

目标：查设备详情、状态、功率流、工作模式、告警。

标准流程：

定位站点 — 已知 SN 直接用 service_site_query_info（单站点详情：版本、网络状态、激活状态、固件等）；只有关键字/名称时先 service_site_search（分页 keyword）拿到 SN。
批量基本信息 — 多个 SN 时用 service_site_monitor_base_info（site_list 为 JSON 数组），返回激活状态、国家、版本等。
功率流 — service_site_power_flow（sn + date），返回 PV、Grid、aPower、HomeLoad、Generator 各通道数据。
工作模式 — service_site_monitor_mode_info 或 service_site_monitor_alarm_list（当前告警列表）。
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：站点总数。

决策流程：

调用 service_site_info_update_status 获取 progress、updateTime、createTime。
判断 progress：
- 若 progress ∈ {pending, running} → 正在更新中：不要触发新的更新，也不要用当前数据得出确定结论。告知用户数据正在同步、整个过程约需 1.5 小时，并按 createTime + 1.5h 给出建议的重试时间，询问用户是「稍后再试」还是「先用当前（可能偏旧的）数据继续」。
- 否则（complete / failed / error 或已完成）进入第 3 步。
计算新鲜度 = 当前时间 − updateTime：
- < 24 小时 → 直接继续任务，并在回复中明确标注数据更新时间（见文案模板）。
- ≥ 24 小时 → 停下来让用户三选一：①更新（调用 service_site_info_trigger_update，属 [写操作]，须先获得用户确认后再触发；触发后提示约 1.5 小时完成、期间可稍后再查）／②跳过（用现有旧数据继续，但结论须标注数据已过期）／③放弃任务。
无记录（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 深度分析（异步任务）。

流程：

创建：service_site_analysis_create [写操作]（sn + time_period JSON ["start","end"] yyyy-MM-dd；可选 enable_runtime/enable_timeline 默认 true；description）。任务自动入队执行。
查进度：service_site_analysis_list（按 sn/progress 筛选，progress ∈ pending/running/success/failed）。
查配置：service_site_analysis_get_config（id）。
取结果：service_site_analysis_data（id）——返回 timeline + runtime 数据。
维护：service_site_analysis_update_desc [写操作] 改描述；service_site_analysis_delete [写操作] 删除。

任务运行状态也可用 service_background_task_list 查看（含状态、重试次数、参数）。

6. 批量数据下载（Batch Download）

目标：为一批站点在时间段内批量导出诊断数据（打包为 tar.gz 存入 MinIO）。

流程：

创建：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。任务自动入队。
查列表/进度：service_batch_download_list（按 sn/progress 筛选）。
看产物目录：service_batch_download_path（id）查任务文件目录结构；service_batch_download_file_tree（file_path）查某 tar.gz 内部结构。
读取产物：用 storage_minio_list_objects / storage_minio_read_object 浏览与读取（bucket 白名单见存储章节）。
维护：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"）。

标准流程：

查询/取蓝本：service_tou_template_list → service_tou_template_detail（要读测试环境模板加 env:"test"）。
定地区：service_tou_template_cites { "env":"test", "country_id":<id>, "type":1 } 拿 provinceId。
构建 payload：按字段字典填 template + strategyList[].detailVoList[]；数值字段传数字，可选数值字段未设置时省略该 key（不传 ""/null）；每个策略时段必须覆盖 00:00→24:00。
写确认：save 前先向用户摘要「新增/更新、模板名、地区、策略与关键时段/电价」，明确写入 test 环境，得到用户同意后才调用。
保存后用返回的 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

文本文件（CSV/JSON/Markdown/代码，≤20MB）：用 storage_file_write（path=/uploads/{filename} + content）。
二进制/大文件（图片/PDF/压缩包/Excel，≤100MB）：本地文件用 storage_file_upload（localPath，无需 base64）。
必须传 userId 和 sessionId：从每条用户消息开头的 [context] userId=xxx / sessionId=xxx 中提取。
写入/上传成功后，必须在回复中独占一行输出下载标记（不要放进代码块）：
```
$$FILE_DOWNLOAD:{"key":"<返回的key>","fileName":"<文件名>","size":<大小>}$$
```

key/fileName/size 用工具返回值原样填入；一次回复可输出多个标记。

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

SKILL.md 19 KB Түүх Анхны өгөгдөл