DJI 上云技能家族

处理大疆行业无人机云平台接入的 Agent 技能集合。当前包含两个技能：

dji-wpml：处理大疆 WPML 航线文件（template.kml / waylines.wpml / .kmz 归档）的生成、解析、修改与校验
cloud-api：处理大疆上云 API（MQTT/HTTPS/WebSocket/JSBridge）的接入、解析、调试与问题定位（机场 / DJI Pilot 2 上云）

这是什么

符合 Anthropic 开放 Skill 标准（agentskills.io）的技能包。让 AI 在处理大疆航线文件、云平台接入时自动加载 DJI 官方规范，产出符合标准的文件/接口，而不是靠猜测。

知识来源：完全基于 DJI 官方文档（docs/Cloud-API-Doc，即官方 dji-sdk/Cloud-API-Doc 仓库的 clone），与任何项目实现无关。官方文档版权归 DJI，不随本仓库分发，使用前需自行 clone（见"使用前提"）。

商标声明：DJI、大疆及其相关名称、Logo 均为大疆创新科技有限公司（SZ DJI Technology Co., Ltd.）或其关联方的注册商标。本仓库仅为技术学习/参考用途，与 DJI 无隶属、赞助或背书关系，不代表 DJI 官方立场。仓库自身代码按 LICENSE 授权。

内容声明：本仓库 reference/ 下的参考文档为 DJI 官方文档的学习笔记式提炼（非原文），并含少量基于 DJI Pilot 2 实际导出文件的字段整理（已做占位化处理）。不替代官方文档，正式开发请以官方文档为准；其中大疆相关内容版权归 DJI 所有。

目录结构

git-skill/
├── README.md                  # 本文件
├── README_EN.md               # 英文版 README
├── docs/Cloud-API-Doc/        # DJI 官方文档仓库（知识源，需自行 clone，不随仓库分发）
├── dji-wpml/
│   ├── SKILL.md               # 技能主入口（何时用、硬性规则、按需加载路由）
│   ├── reference/
│   │   ├── template-kml.md    # template.kml 参考（创建/任务/模板信息、各模板字段）
│   │   ├── waylines-wpml.md   # waylines.wpml 参考（执行文件）
│   │   ├── common-elements.md # 共用元素（机型/负载/动作/偏航/转弯参数）
│   │   └── kmz-archive.md     # KMZ 归档规则
│   ├── scripts/
│   │   ├── validate_wayline.py # 校验脚本（纯 Python 标准库）
│   │   └── package_kmz.py      # KMZ 打包脚本（纯 Python 标准库）
│   ├── examples/
│   │   ├── waypoint.kml        # 航点飞行模板示例
│   │   ├── mapping.kml         # 建图航拍模板示例
│   │   ├── mapping3d.kml       # 倾斜摄影模板示例
│   │   ├── mappingStrip.kml    # 航带飞行模板示例
│   │   └── targetdetection.kml # 目标检测巡逻模板示例（+ targetdetection.wpml 执行文件示例）
│   └── template/
│       └── template.kml        # 标准骨架模板
└── cloud-api/
    ├── SKILL.md                # 技能主入口（架构/通信协议/硬性规则/路由）
    ├── scripts/
    │   ├── build_mqtt.py       # MQTT 消息构造脚本（补齐公共字段）
    │   └── validate_mqtt.py    # MQTT 消息校验脚本
    └── reference/
        ├── basic-concepts.md   # 基础概念（物模型/MQTT/HTTPS/WebSocket/JSBridge）
        ├── mqtt-topics.md      # MQTT Topic 定义与消息结构
        ├── pilot-to-cloud.md   # Pilot 侧接口（MQTT/HTTPS/WebSocket/JSBridge）
        ├── dock-to-cloud.md    # Dock 机场侧接口（MQTT 主题）
        ├── feature-set.md      # 功能集概览（Pilot 9 + Dock 12）
        ├── error-code.md       # 错误码规范
        ├── extended-topics.md  # 扩展主题（PSDK/喊话器/AirSense/FlySafe/自定义飞行区/多机场/遥控器）
        └── deploy-debug.md     # 部署（源码/Docker）与调试（MQTTX/日志导出）

安装（Claude Code）

方式一：复制到个人技能目录

mkdir -p ~/.claude/skills
cp -r dji-wpml ~/.claude/skills/
cp -r cloud-api ~/.claude/skills/

方式二：注册为插件市场

cd /path/to/git-skill
# 在项目内创建 .claude-plugin/marketplace.json，或通过 /plugin marketplace add 添加

使用示例

安装后，直接对 AI 说：

dji-wpml（航线文件）：

"帮我生成一条航点飞行航线 kmz，经过以下三个点：..."
"解析这个 template.kml 的测区多边形和重叠率"
"把这条航线的飞行速度改成 10m/s"
"检查这个 kmz 有没有缺字段"

cloud-api（上云对接）：

"机场上线后我怎么订阅它的 OSD 数据？"
"下发一条航线任务到机场，流程是怎样的？"
"这个 HMS 错误码 312022 是什么意思？"
"Pilot 直播能力在哪个 topic 里上报？"

AI 会自动加载对应技能并按 DJI 标准生成/解析。

脚本用法

dji-wpml（航线文件）：

# 打包成 KMZ
python dji-wpml/scripts/package_kmz.py <template.kml> <waylines.wpml> -o <输出.kmz> [--res <res目录>]

# 校验
python dji-wpml/scripts/validate_wayline.py <文件.kmz|.kml|.wpml>

package_kmz.py：纯标准库，把两个 XML（+可选 res/）按规范打包为 .kmz，退出码 0 成功
validate_wayline.py：校验 XML 合法性、命名空间、必需字段、枚举值（含 targetdetection 模板）、坐标格式、航点序号连续性
.kmz 会自动解包并分别校验 template.kml 与 waylines.wpml
校验退出码：0 通过；1 不通过；2 参数错误；加 --strict 将警告也视为失败

cloud-api（MQTT 消息）：

# 构造消息（自动补齐 tid/timestamp 等公共字段）
python cloud-api/scripts/build_mqtt.py <template.json> [--gateway <sn>] [--bid] [-o <out.json>]

# 校验消息（公共字段/UUID/时间戳/method/result 规则）
python cloud-api/scripts/validate_mqtt.py <message.json> [--topic <topic>] [--strict]

build_mqtt.py：读入模板 JSON，自动生成 tid/timestamp（--bid 生成业务 UUID，--gateway 写网关 SN），退出码 0 成功
validate_mqtt.py：校验消息合法性，回复类 Topic（如 services_reply）要求 data.result 必填；退出码 0 通过；1 不通过；2 参数错误
两脚本均兼容 Windows 常见 UTF-8 BOM 文件

使用前提

两个技能做深度查询时需要 docs/Cloud-API-Doc（DJI 官方文档）在场。由于版权原因，官方文档不随本仓库分发，请先自行 clone：

git clone https://github.com/dji-sdk/Cloud-API-Doc.git docs/Cloud-API-Doc

更新知识源

cd docs/Cloud-API-Doc && git pull

验证

# 示例文件应全部通过校验
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/waypoint.kml
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/waypoint.wpml
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/mapping.kml
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/mapping3d.kml
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/mappingStrip.kml
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/targetdetection.kml
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/targetdetection.wpml
python dji-wpml/scripts/validate_wayline.py dji-wpml/template/template.kml

# 负例应报错（非法枚举/越界值/跳序航点），退出码 1
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/_bad.kml

# 负例应报错（第一个坐标合法、第二个坐标非法，验证全坐标校验），退出码 1
python dji-wpml/scripts/validate_wayline.py dji-wpml/examples/_bad_coords.kml

分发注意

请使用 Git 分发本仓库（clone / GitHub 归档），不要直接压缩整个工作目录：docs/ 下的 DJI 官方文档已由 .gitignore 排除、不随 Git 提交，但直接压缩会把它们连同嵌套的 .git 历史一并打包进去。

Refactored System

At a glance

README