Idmp Easyuse

IDMP EasyUse 技能

作为 IDMP 项目的总控枢纽，静默调度四个子技能，实现从行业调研到数据建模、告警分析、可视化面板的一键式全流程自动化编排。

输入要求

常见陷阱（Gotchas）

以下规则是 Agent 在没有明确提示时最容易出错的地方，执行前必须阅读。

步骤顺序不可调换

• 必须严格按第一步→第二步→第三步→第四步→第五步→第六步→第七步顺序执行，不得并行或跳步。

调研文档是唯一设计基准

• 类别 1 执行第二步生成 outputs/industry_research.md 后，后续所有子技能必须以此文档为准，严禁自行修改层级结构、告警阈值或面板需求。

调研报告属性名规范 (Attribute Referencing)

• 在 outputs/industry_research.md 的第二节，采集指标建议采用 中文名 (English_Name) 格式。
• 在第三节（关键指标）和第四节（告警规则）中编写公式或条件时，必须统一使用 ${attributes['中文标题']} 的格式（如：${attributes['温度']} > 50）。
• 该中文标题必须与第二节中的名称完全一致，严禁直接使用英文标识符。

跨设备计算禁止

• 调研报告第三节（关键指标）、第四节（告警规则）、第五节（面板需求）中，不得生成任何跨设备计算的指标、告警或面板。

静默执行

• 六个步骤之间必须无缝衔接，全部完成后统一输出最终报告。除不可恢复的错误外，不得在中间请求用户确认。

面板和分析数量下限（类别 1）

• 面板总数和分析任务总数各不少于 5 个，且必须分布在不同设备或层级节点上，不得集中在单一节点。

MCP 工具优先级（⚠️ 必须遵守）

• 第四步（关键指标）、第五步（告警规则）、第六步（过程事件）：
  • ✅ 优先使用 add_analysis（自然语言描述方式）。该工具能自动推断触发类型、聚合函数和输出属性格式，避免 create_analysis 中 output、trigger 字段结构复杂、难以正确填写的问题。
  • ⚠️ 仅当 add_analysis 生成结果不符合调研文档要求时，才降级使用 create_analysis / create_alarm_rule 精确控制参数。
• 第七步（可视化面板）：
  • ✅ 优先使用 add_panel（自然语言描述方式）。该工具能自动解析属性名并填充完整的 PanelAttribute 对象（含 attributeExpression、expression、formula、window 等字段）。
  • ❌ 禁止直接使用 create_panel 的 ya_attributes/xa_attributes 参数：其 schema 仅标注为 array of object，未声明必要子字段，模型无法正确推断——直接传入会导致属性列为 null，面板报错 The column name of the data referred attribute null in the panel is empty。
  • ⚠️ 仅在 add_panel 无法匹配属性（如 L1 根节点无直接属性）时，才使用 create_panel，并从已有正常面板的 yaAttributes 结构中复制完整字段后修改。

状态驱动与内容压缩 (State-Driven & Compression)

• 全流程必须维护并更新项目根目录下的 outputs/state.json。
• 状态内容：必须包含场景名、项目路径、登录凭据、调研元数据（指标/告警列表）、资产树结构（含 Node ID）、已完成步骤。
• 动态寻址：所有文件读写均应基于 state.json 中的 project_root 进行相对或绝对路径计算。
• 上下文压缩：步骤间传递信息时，优先引用 state.json 中的字段，而非重复粘贴大量冗余文本，以保持 Token 高效利用。

执行流程

Telemetry (MUST)

调用 skill-telemetry，传入 name=idmp-easyuse version=0.4.1 author=Wang Zhe。 失败不阻塞，但必须尝试。详见 skill-telemetry。

第一步：初始化项目与状态机

1.1 输入与输出

• 类别 1：用户未提供任何数据结构文件（xlsx/文本文档）或 CSV 数据文件，仅有自然语言描述。
• 类别 2：用户提供了上述任意文件，或明确指定了面板展示要求和告警规则。

1.2 确定场景名称与项目目录

1. 环境检查：
   • 首先运行 python3 --version 检查环境中是否已安装 Python。
   • 若未安装，必须明确告知用户并询问是否允许自动安装（如 sudo apt update && sudo apt install python3 -y）。
   • 若用户拒绝安装，必须立即停止当前任务并友好告知原因。
2. 场景名称确定：
   • 优先使用用户在输入中明确提到的场景关键词（如“智慧工厂”、“中央空调”等）。
   • 若用户描述模糊，从描述中提取核心资产或业务目标，转化为简短的英文标识符（下划线连接，如 smart_factory）。
3. 项目目录初始化：
   • 使用本技能目录下的 scripts/prepare_project_dir.py 脚本自动创建项目目录。
   • 执行路径说明：由于客户启动 OpenCode 的工作目录不确定，必须先定位本 SKILL.md 所在的绝对路径，并以此为基准运行脚本。
   • 必须运行以下命令（传入确定的场景名称）：

     python3 <skill_dir>/scripts/prepare_project_dir.py <scenario_name>
     

   • 确认目录名后，所有子技能的文件操作均在此目录下进行，严格遵循：
     • 中间脚本 → scripts/ 子目录
     • 输出文件 → outputs/ 子目录
4. 初始化 state.json：
   • 在 outputs/ 下创建 state.json。
   • 同步登录信息：
     • 读取用户提供的凭据。
     • 更新 state.json 中的 tsdb-login 和 idmp-login 中的信息。
   • 样例结构：

     {
       "scenario": "smart_factory",
       "root": "/absolute/path/to/demo/smart_factory_20260331",
       "category": 1,
       "tsdb-login": { "url": "http://localhost:6041", "user": "root", "pass": "taosdata" },
       "idmp-login": { "url": "http://localhost:6042", "user": "admin", "pass": "password", "api_key": "api_xxx.yyy" },
       "steps": ["init"]
     }
     

5. MCP 服务器检查与创建：
   • 从 state.json 中的 idmp-login.url 提取 IDMP_HOST，检查是否存在 URL 为 http://<IDMP_HOST>:6042/api/v1/mcp/stream 的 MCP 服务器。
   • 若不存在，必须尝试根据 references/idmp_mcp_config.md 中的配置信息创建该 MCP 服务器。
   • 调用 scripts/prepare_mcp_config_content.py --state outputs/state.json 完成 API Key 的创建与获取，将输出的 API Key 写入 state.json 的 idmp-login.api_key 字段，并替换到 MCP 配置中。若 state.json 中已存在 idmp-login.api_key，则直接使用，跳过创建步骤。
   • 若创建失败，必须立即询问用户是否继续任务；若用户选择继续，则在明确告知 MCP 服务不可用的前提下进入后续步骤，否则停止当前流程。

第二步：行业场景深度调研（仅类别 1）

触发条件：类别 1 时执行；类别 2 直接跳至第三步。

对用户描述的行业/场景进行系统化深度建模，生成 outputs/industry_research.md。该文档必须严格遵循调研文档编写规范 references/research_specification.md，覆盖以下维度：

调研完成后生成的 outputs/industry_research.md 将作为后续所有步骤的统一设计基准（参见 Gotchas）。

第三步：数据与资产建模

调用 idmp-sample-data-generator 技能，传递以下内容：

第四步：关键指标配置

注意：本步骤必须使用 MCP (Model Context Protocol) 实现。

传递以下内容（供 MCP 工具使用）：

工具选择（必须遵守）：

• ✅ 优先调用 add_analysis，传入 element_id（目标节点）、root_element_id（L1 根节点）和中文自然语言 description。
• 描述需包含：指标名称、触发频率、聚合函数、属性名称（与调研文档一致的中文名）。
• 示例："每1分钟对1号气象站的风速做滑动最大值计算，输出属性名为'气象站1分钟最高风速'"
• ⚠️ add_analysis 失败或结果不符时，才降级使用 create_analysis 精确构造 trigger/output 参数。

> 执行完毕后，检查关键指标是否按照要求创建成功，如果不成功，列出未成功的指标和失败原因。然后必须调用 update_state.py 将 "indicators" 追加到 state.json 中。

第五步：告警规则配置 (MCP 模式实现)

注意：本步骤必须使用 MCP (Model Context Protocol) 实现。

传递以下内容（供 MCP 工具使用）：

工具选择（必须遵守）：

• ✅ 优先调用 add_analysis，传入 element_id、root_element_id 和中文自然语言 description。
• 描述需包含：告警名称、触发条件（含属性名和阈值）、持续时长、恢复条件、告警级别（Critical/Major/Warning/Minor）。
• 示例："当变桨电池电压低于360V持续1分钟时触发Major告警，命名为'变桨电池欠压告警'，恢复条件为电压大于等于360V"
• ⚠️ add_analysis 失败或结果不符时，才降级使用 create_alarm_rule 精确构造参数。

> 执行完毕后，检查告警规则是否按照要求创建成功，如果不成功，列出未成功的告警规则和失败原因。然后必须调用 update_state.py 将 "alarms" 追加到 state.json 中。

第六步：过程事件配置 (MCP 模式实现)

注意：本步骤必须使用 MCP (Model Context Protocol) 实现。

传递以下内容（供 MCP 工具使用）：

工具选择（必须遵守）：

• ✅ 优先调用 add_analysis，传入 element_id、root_element_id 和中文自然语言 description。
• 描述需包含：事件名称、开始触发条件、持续时长、结束条件、事件级别、需在事件窗口内捕获的统计量。
• 示例："当有功功率低于10kW且风速大于5m/s持续5分钟时，记录一次Critical级别的'机组非计划停机事件'，统计事件窗口内的平均风速，结束条件为有功功率大于等于10kW或风速小于等于5m/s"
• ⚠️ add_analysis 失败或结果不符时，才降级使用 create_analysis（trigger_type=Event）精确构造参数。

> 执行完毕后，检查关键事件是否按照要求创建成功，如果不成功，列出未成功的关键事件和失败原因。然后必须调用 update_state.py 将 "events" 追加到 state.json 中。

第七步：可视化面板配置 (MCP 模式实现)

注意：本步骤必须使用 MCP (Model Context Protocol) 实现。

传递以下内容（供 MCP 工具使用）：

工具选择（必须遵守）：

• ✅ 优先调用 add_panel，传入 element_id（目标节点）和中文自然语言 description。
• 描述需包含：图表类型（折线/散点/柱状/状态时间轴等）、所需属性名称（与调研文档一致的中文名）、时间范围和业务含义。
• 示例："折线图，展示过去7天1号气象站的风速和1分钟最高风速随时间变化"
• ⚠️ 已知行为：add_panel 没有独立的 name 参数，面板名称（name/fileName）会被设置为完整的 description 字符串，这是该工具的固有机制，属于预期行为，无需额外处理。若要精确控制面板名称，须改用 create_panel（参见下方降级说明）。
• ❌ 禁止直接使用 create_panel 的 ya_attributes/xa_attributes 参数：其 schema 仅标注为 array of object，未声明必要子字段（attributeExpression、expression、formula、window 等），直接传入会导致属性列为 null，面板报错 The column name of the data referred attribute null in the panel is empty。
• ⚠️ 仅当 add_panel 因节点无直接属性而失败（如 L1 根节点），或业务要求精确面板名称时，才使用以下两步流程：① 先用 add_panel 生成草稿，从返回的 draft_result.yaAttributes 获取完整属性结构；② 立即删除草稿，再用 create_panel 指定 name + 复用步骤①的属性对象重建。

> 执行完毕后，检查面板是否按照要求创建成功，如果不成功，列出未成功的面板和失败原因。然后必须调用 update_state.py 将 "panels" 追加到 state.json 中。

第八步：生成报告

将以下内容汇总生成 outputs/final_report.md 并保存至项目 outputs/ 目录，同时在终端向用户展示摘要：

编排完整性检查清单

全流程执行完毕后，逐条确认以下项目，有遗漏立即补充执行：

• 类别 1 调研完成：outputs/industry_research.md 已生成且包含五个完整维度
• 项目目录唯一：项目根目录名称含时间戳，未覆盖已有目录
• 流程执行完整：idmp-sample-data-generator、MCP 可视化面板配置 均已按序完成
• 上下文传递完整：每个子技能调用时均传递了项目目录路径和前置步骤关键信息
• 数量达标（类别 1）：面板总数 ≥ 5 个，分析任务总数 ≥ 5 个，且均分布在多个节点
• 报告已生成：outputs/final_report.md 已保存