Agent Skill 实战：我把大疆行业无人机上云的坑，固化成了一个技能包
引子：AI 很强，但它在行业场景会"一本正经地胡说"
让 AI 写一个 Vue 组件、调一个 REST 接口，现在都很顺滑。但如果你让它生成一份大疆航线文件（WPML） ，或者对接大疆上云 API（Cloud API），事情就完全不一样了：
- WPML 是 KML 2.2 的扩展标准，
template.kml和waylines.wpml两套文件、两套高度体系，字段名拼错一个就解析失败； - 航点
index必须从 0 开始单调连续，finishAction只能取goHome/noAction/autoLand/gotoFirstWaypoint，速度范围 1,15 m/s------AI 靠训练数据"猜"出来的枚举值，十有八九是错的； - 上云 API 分
sys/和thing/两层 Topic，消息必须带tid/bid，回复类消息必须有data.result，错误码还是ABCDEF六位结构......
于是我做了一个开源项目：DJI 上云技能家族（git-skill），把大疆行业无人机开发中"硬邦邦的规则"固化成了 AI Agent 可以按需加载的技能包。
什么是 Agent Skill？
Skill 是 Anthropic 提出的开放标准（agentskills.io）：一个文件夹 + 一个 SKILL.md 主文件，加上可选的 reference/（参考资料）、scripts/（工具脚本）、examples/（示例）。
text
dji-wpml/
├── SKILL.md # 技能主入口（何时用、硬性规则、按需加载路由）
├── reference/ # template.kml / waylines.wpml / KMZ 归档 参考
├── scripts/ # validate_wayline.py / package_kmz.py（纯标准库）
├── examples/ # 5 种模板示例（航点/建图/倾斜/航带/目标检测）
└── template/ # 标准骨架模板关键点：技能不是让 AI 死记硬背，而是"按需加载" 。SKILL.md 只放路由规则和硬性约束，具体细节放在 reference/ 里，AI 遇到对应任务才加载对应文档，避免污染上下文。
为什么做这个技能包？
三个直接原因：
- AI 生成行业格式文件质量不可控：航线文件是"格式敏感"的，一个枚举值写错，DJI Pilot 2 / 司空 2 直接拒绝解析，飞行计划就废了；
- 官方文档太重：大疆 Cloud-API-Doc 仓库几百个 Markdown，让 AI 每次现翻不现实，而且容易把文档里"建议值"当成"必填值"；
- 踩坑经验值得沉淀：上云接入中的常见问题（设备不上线、订阅不到 OSD、下发指令无响应、HMS 告警看不懂）其实都有固定的排查路径，可以固化成"调试速查表"。
技能包总览
仓库包含两个互补的技能：
| 技能 | 处理对象 | 核心价值 |
|---|---|---|
| dji-wpml | WPML 航线文件（template.kml / waylines.wpml / .kmz） |
生成、解析、修改、校验符合官方标准的航线文件 |
| cloud-api | 大疆上云 API（MQTT / HTTPS / WebSocket / JSBridge） | 接入、解析、调试与问题定位（机场 / DJI Pilot 2 上云） |
设计要点一：把最容易出错的规则写成"硬性规则"
SKILL.md 里有一节专门叫"硬性规则"，每条都是踩坑的结晶。例如 dji-wpml：
- 文件头必须是
<?xml version="1.0" encoding="UTF-8"?>+ 双命名空间<kml>； - 航点
wpml:index从 0 开始单调连续递增，范围 0, 65535； missionConfig下六个字段必填，droneInfo/payloadInfo必填；- 两种高度体系千万别混 ：
template.kml用heightMode+height（编辑体系），waylines.wpml用executeHeightMode+executeHeight（执行体系）； - 注意"条件必需"规则：
waypointSpeed仅在useGlobalSpeed=0时必需，executeRCLostAction仅在exitOnRCLost=executeLostAction时必需。
cloud-api 侧也有类似的硬性规则：
- 无人机不能直接上云，必须经机场/遥控器网关代理；
sys/product/{gateway_sn}与thing/product/{sn}两层 Topic 不要混用；osd定频上报（pushmode=0）、state事件性上报（pushmode=1）；tid事务 UUID +bid业务 UUID 必带，回复必须带result；- 错误码
ABCDEF六位：A 来源、BC 模块、DEF 自定义。
设计要点二：用脚本做"格式兜底"
规则再清楚，AI 也可能手滑。所以每个技能都配了纯 Python 标准库的校验/构造脚本，零第三方依赖，Windows/macOS/Linux 都能跑：
bash
# dji-wpml：校验航线文件（0 通过 / 1 不通过 / 2 参数错误）
python dji-wpml/scripts/validate_wayline.py <文件.kmz|.kml|.wpml>
# dji-wpml：打包 KMZ
python dji-wpml/scripts/package_kmz.py <template.kml> <waylines.wpml> -o <输出.kmz>
# cloud-api：构造标准 MQTT 消息（自动补 tid/timestamp）
python cloud-api/scripts/build_mqtt.py <template.json> --gateway <sn>
# cloud-api：校验消息合法性
python cloud-api/scripts/validate_mqtt.py <message.json> --topic <topic>SKILL.md 里明确要求："生成后必须校验"------生成或修改文件后，必须运行脚本检查，校验通过才算交付。
设计要点三：安全与隐私边界（这个最重要）
做行业无人机的技能，必须把"安全"写进技能本身 。两个 SKILL.md 都有"安全与隐私边界"章节，要求 AI 严格遵守：
- 执行前用户确认：航线执行前必须由用户确认坐标、飞行高度、返航高度、失控动作等关键参数；
- 不写入用户真实数据：示例文件全部使用虚构坐标，设备 SN、Token、密钥输出前必须脱敏；
- 高风险动作再次确认：远程起飞、返航、指飞（DRC）、航线任务下发等动作，必须再次确认；
- 校验通过 ≠ 飞行安全：校验脚本只验证格式合法，不代表适航或符合当地法规；
- 不主动提权：未经用户要求不得连接设备、读取日志或进行网络操作。
设计要点四：知识来源与版权合规
技能的知识完全来自 DJI 官方文档（dji-sdk/Cloud-API-Doc）。出于版权考虑，官方文档不随仓库分发，使用前需自行 clone：
bash
git clone https://github.com/dji-sdk/Cloud-API-Doc.git docs/Cloud-API-Doc仓库里还做了三件事保证合规：
reference/下的参考文档是官方文档的"学习笔记式提炼"（非原文）；- 基于 DJI Pilot 2 实际导出整理的字段全部做了占位化处理；
- 新增
THIRD_PARTY_NOTICES.md，逐文件声明第三方内容来源；MIT License 也加了授权范围限定，明确排除 DJI/OGC 第三方内容。
实际使用效果
装到 Claude Code（复制到 ~/.claude/skills/ 即可），然后直接对话：
dji-wpml：
"帮我生成一条航点飞行航线 kmz，经过以下三个点：..."
cloud-api：
"机场上线后我怎么订阅它的 OSD 数据？" "这个 HMS 错误码 312022 是什么意思？"
AI 会自动加载对应技能，按 DJI 标准生成/解析，并且生成后跑校验脚本。
下一步计划
我正在规划一个教学协作版工具链 dji-wayline-tools：解析 → 校验 → 打包 → 生成 → 地图可视化，Python 3.10+，核心零依赖，folium/shapely 放可选 extra，CLI 用 typer。目标不只是"好用"，更是开源引流 + Python 练手 + 比赛素材。
总结
Agent Skill 的价值在于：把领域专家的经验、格式规范、安全边界，变成 AI 可以主动遵守的行为约束。它解决的不是"模型能力"问题，而是"行业知识注入"问题。
DJI 上云技能家族（git-skill）是这套思路的一个完整落地案例：
- 两个互补技能覆盖航线文件 + 云平台接入；
- 硬性规则 + 校验脚本双保险；
- 安全边界写进技能本身；
- 版权合规处理到位。
仓库地址：git-skill（含 dji-wpml / cloud-api），欢迎 star、fork，或提 issue 讨论你在大疆行业无人机开发中遇到的坑。
声明：本文项目与 DJI（大疆创新）无隶属、赞助或背书关系，仅为技术学习/参考用途。相关商标归大疆所有。