SKILL.md 14 KB
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 月份为yyyy-MM，Acceleronix 批量用量月份为YYYYMM。 - 分页：
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[写操作] 创建/更新标签（tagJSON：id 可选、name、color、description）。
需要 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_listJSON 数组 + 可选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（giccid19 位）——状态、平台、用量汇总。 - 月度每日用量：
service_sim_monthly_data（giccid+monthyyyy-MM）。
需要上游平台原始数据（Acceleronix / SmartHub 卡详情、流量池、批量用量）时用
data_sim_*，见 references/data-direct-query.md。
5. 站点分析任务（Site Analysis）
目标：对单站点在时间段内做 timeline + runtime 深度分析（异步任务）。
流程：
- 创建：
service_site_analysis_create[写操作]（sn+time_periodJSON["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[写操作]（ownerJSON 数组）；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+configJSON，含config.defaultType和config.specialType）；service_auto_update_delete_config（agate_version）。 - 升级包：
service_auto_update_create_package（package_type∈ system/aGate/subDevice/others +infoJSON，含 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（type0-系统/1-API/2-用户推荐；status0-未发布/2-已发布；search；分页）。 - 详情：
service_tou_template_detail（id数字）。
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_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 - 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_*）。