taosdata 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 |
可选 | 更新模式：从已有输出文件中提取根节点名称并重新拉取最新结构 |
--api-key |
可选 | 直接使用 API Key 进行鉴权，优先级高于用户名/密码；今优先从 state.json 的 idmp-login.api_key 读取 |
| IDMP 登录信息 | 降级备用 | 若无 state.json 且无 API Key，从 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 与 API Key 优先于直接登录参数
- 只要存在
state.json，必须通过--state参数传入。 - 脚本会自动从
state.json的idmp-login.api_key字段读取 API Key，有则跳过登录流程。 - 无 API Key 时，降级使用 host/user/password 登录。
输出文件不得覆盖已有有效结果
- 若输出路径已存在文件，默认应追加时间戳以示区分，或在
--update模式下原地更新。
执行流程
Telemetry (MUST)
调用
skill-telemetry，传入name=idmp-structure-exporter version=0.3.0 author=Wang Zhe。 失败不阻塞，但必须尝试。详见skill-telemetry。
第一步：环境检查与登录信息确认
1.1 定位技能脚本目录
本技能脚本相对位置固定（<skill_dir>/scripts/export_idmp_tree.py），但安装路径因环境而异。执行前必须先定位本 SKILL.md 的绝对路径，再以此推导 SKILL_DIR：
# 找到本 SKILL.md 的位置，其所在目录即为 SKILL_DIR
SKILL_DIR="$(dirname "$(realpath "<本SKILL.md的绝对路径>")")"
ls "$SKILL_DIR/scripts/export_idmp_tree.py"
若文件不存在，立即停止并告知用户。
1.2 确定登录凭据来源
按以下优先级获取 IDMP 登录信息：
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1（最高） | state.json 中的 idmp-login.api_key 字段 |
API Key 鉴权，无需登录流程 |
| 2 | state.json 中的 idmp-login 字段（user/pass） |
由 idmp-easyuse 初始化时生成 |
| 3 | 用户指定的登录信息 | 包含 host、user、password |
| 4（最低） | 直接向用户询问 | 仅在上述三种来源均不可用时执行 |
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 <STATE_JSON_PATH> \
--sample-data <SAMPLE_DATA_JSON_PATH> \
--output <OUTPUT_PATH>
路径 B：按根节点名称过滤
适用于用户明确指定资产名称的场景：
python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
--state <STATE_JSON_PATH> \
--root-name "<ROOT_ELEMENT_NAME>" \
--output <OUTPUT_PATH>
路径 C：更新已有结构文件
适用于资产树已导出过、需要刷新最新状态的场景：
python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
--state <STATE_JSON_PATH> \
--update \
--output <OUTPUT_PATH>
路径 D：导出全系统资产树（仅用户明确要求时）
python3 "$SKILL_DIR/scripts/export_idmp_tree.py" \
--state <STATE_JSON_PATH> \
--output <OUTPUT_PATH>
第三步：验证与交付
3.1 JSON 格式验证
脚本执行完毕后，立即验证输出文件的语法正确性：
python3 -c "import json; data = json.load(open('<OUTPUT_PATH>')); 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`。