Idmp Structure Exporter

IDMP 资产树导出工具

将 IDMP 系统的元素层级结构导出为标准化的递归嵌套 JSON 文件，供其他技能（如 idmp-sample-data-generator、分析技能）进行程序化读取，解决多技能协作中对资产树认知不统一的问题。

输入要求

| 参数 | 是否必需 | 说明 | |:--- |:--- |:--- | | state.json 路径 | 推荐 | 包含 idmp-login 字段的状态文件，由 idmp-easyuse 初始化生成 | | 输出路径 | ✅ 必传 | 导出 JSON 的目标路径，默认文件名 idmp_tree_structure.json | | --root-name | 二选一 | 按名称过滤，仅导出指定根节点及其子树 | | --sample-data | 二选一 | 指定 sample_data.json，自动从中提取 info.name 作为根节点过滤条件 | | --update | 可选 | 更新模式：从已有输出文件中提取根节点名称并重新拉取最新结构 | | IDMP 登录信息 | 降级备用 | 若无 state.json，从 login_info.txt 或用户输入获取 host、user、password |

---

常见陷阱（Gotchas）

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

严禁导出全系统资产树

• 由其他技能调用时，必须通过 --root-name 或 --sample-data 参数限定导出范围。
• 仅当用户明确要求"导出全部资产"时，才可省略过滤参数。

脚本路径必须动态定位

• 本技能的脚本相对位置固定为本 SKILL.md 同级的 scripts/export_idmp_tree.py。
• 执行前必须先定位本 SKILL.md 的绝对路径，并以此推导 SKILL_DIR，严禁硬编码绝对路径。

state.json 优先于直接登录参数

• 只要存在 state.json，必须通过 --state 参数传入，而不是手动传递 --host/--user/--password。

输出文件不得覆盖已有有效结果

• 若输出路径已存在文件，默认应追加时间戳以示区分，或在 --update 模式下原地更新。

---

执行流程

Telemetry (MUST)

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

---

第一步：环境检查与登录信息确认

1.1 定位技能脚本目录

本技能脚本相对位置固定（/scripts/export_idmp_tree.py），但安装路径因环境而异。执行前必须先定位本 SKILL.md 的绝对路径，再以此推导 SKILL_DIR：

# 找到本 SKILL.md 的位置，其所在目录即为 SKILL_DIR
SKILL_DIR="$(dirname "$(realpath "")")" 
ls "$SKILL_DIR/scripts/export_idmp_tree.py"

若文件不存在，立即停止并告知用户。

1.2 确定登录凭据来源

按以下优先级获取 IDMP 登录信息：

| 优先级 | 来源 | 说明 | |:--- |:--- |:--- | | 1（最高） | state.json 中的 idmp-login 字段 | 由 idmp-easyuse 初始化时生成 | | 2 | 用户指定的登录信息 | 包含 host、user、password | | 3（最低） | 直接向用户询问 | 仅在上述两种来源均不可用时执行 |

1.3 确定输出路径

• 若调用方（如 idmp-sample-data-generator）已明确传入输出路径，直接使用。
• 否则，在当前项目的 outputs/ 目录下生成，文件名默认为 idmp_tree.json。

---

第二步：执行资产树导出

根据输入参数，选择以下其中一条路径执行，严禁混用：

路径 A：基于 sample_data.json 过滤（优先路径 - 由其他技能调用时）

适用于 idmp-sample-data-generator 完成数据加载后需要同步资产树的场景：

python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
  --state  \
  --sample-data  \
  --output 

路径 B：按根节点名称过滤

适用于用户明确指定资产名称的场景：

python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
  --state  \
  --root-name "" \
  --output 

路径 C：更新已有结构文件

适用于资产树已导出过、需要刷新最新状态的场景：

python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
  --state  \
  --update \
  --output 

路径 D：导出全系统资产树（仅用户明确要求时）

python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
  --state  \
  --output 

---

第三步：验证与交付

3.1 JSON 格式验证

脚本执行完毕后，立即验证输出文件的语法正确性：

python3 -c "import json; data = json.load(open('')); print('节点总数：', sum(1 for _ in __import__('itertools').chain([data])))" && echo "JSON OK"

3.2 结果交付

向用户或调用方返回：

| 交付项 | 说明 | |:--- |:--- | | 输出文件绝对路径 | 供后续技能直接引用 |

---

执行完整性检查清单

• [ ] 脚本路径已确认：export_idmp_tree.py 存在于技能脚本目录
• [ ] 登录凭据已就绪：优先从 state.json 读取，其次 login_info.txt，最后询问用户
• [ ] 过滤参数已指定：除用户明确要求全量导出外，必须传入 --root-name、--sample-data 或 --update 之一
• [ ] 输出文件已验证：JSON 语法正确，根节点字段完整
• [ ] 结果已交付：已将文件路径和资产树概览返回给用户或调用方

## 注意事项

1. **登录信息**：如果 `login_info.txt` 不存在或不可读，请优先提示用户提供连接信息。
2. **大型资产树**：脚本已处理分页逻辑，但对于极端庞大的资产树（数万个节点），请注意内存占用并告知进度。
3. **文件命名**：默认输出文件名为 `idmp_tree.json`。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [taosdata](https://github.com/taosdata)
- **Source:** [taosdata/agent-skills](https://github.com/taosdata/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.