第一部分：AI Plugin 使用指南

第一章：产品介绍

1.1 这是什么

cloudapi2-ai-plugin是大疆上云 API 2 官方发布的 AI Plugin，安装在Claude Code中即可使用。
它把资深工程师的无人机开发工程规范沉淀为可自动触发的能力，让 AI 编程助手不再"上来就写代码"，而是结合无人机业务知识先想清、再动手。
产品由四部分组成：9个Skill（教 AI 写对代码 / 部署 / 排障）+ 4 个快捷指令（一键生成前端组件接入代码）+ MCP Server（让 AI 运行时直接操控设备） + 知识库（llms.txt 领域文档索引，可独立使用）。

1.2 能帮你做什么

Plugin 覆盖上云 API 2 的以下业务方向：

方向	覆盖内容
后端 SDK 集成	SDK 初始化、鉴权、飞控、任务、直播、媒体、错误码
前端组件接入	驾驶舱、航线编辑器、设备管理、飞行记录 4 大 PaaS 组件
设备管理	设备列表、状态订阅、HMS 告警、固件升级、上下线事件
实时遥测（SEI/OSD）	帧级位置数据、Cesium 视锥可视化、视频投影
MCP 工具调用	让 AI Agent 通过自然语言操控无人机 / 机场
部署引导	MCP Server / Skeleton 半自动部署到自有环境
知识库入库	外部文档一键收录到 knowledge/ 并维护索引
排障诊断	4 阶段 RCA + 错误码字典

Plugin 可以帮你：

✅ 代码生成：一键生成前端组件的完整 HTML 接入代码 / 后端 Java Service 代码
✅ 规范约束：自动加入 initialize 检查、listen/cancel 配对、控制权释放、危险操作风险提示等大疆专属硬性约束
✅ 错误诊断：4 阶段 RCA + 4001–7000 错误码字典，快速定位 SDK / 前端问题
✅ 运行时操控：搭配 MCP Server，让 AI 用自然语言直接创建航线任务、查询设备遥测、控制无人机
✅ 半自动部署：MCP Server / Skeleton 逐步引导（AI 生成命令，用户负责执行）
✅ 知识收录：外部文档一键收录到 knowledge/ 知识库并维护索引
✅ 接入排障：解决跨域、Mixed Content、Whistle 代理、初始化时序等常见接入问题

1.3 适用人群

正在接入上云 API 2 的 开发者（后端 Java + 前端 Web）
需要快速搭建可运行 Demo 的 前端工程师
需要让 AI Agent 直接操控无人机 / 机场的 AI Agent 开发者
负责将 MCP Server / Skeleton 部署到自有环境的 运维 / 平台工程师

1.4 我该从哪里开始（快速决策）

不必通读全文，先根据你的目标直接跳到对应章节：

你的目标	直接看
先把 Plugin 装上	第二章：安装 Plugin
想先看在线 DEMO 有什么效果	第二章末：在线 DEMO
不确定参数、遇到报错、想理解某个 API	3.1 方式一：直接对话
参数已确认，想立刻拿到可运行的前端 HTML	3.2 方式二：快捷指令
让 AI 直接操控无人机 / 机场（不写代码）	3.3 方式三 + 第五章
接入并使用 MCP Server	第六章：MCP Server 接入
想看常用操控场景示例	第八章：常用场景示例
想知道有哪些 Skill、怎么触发	第四章：Skill 清单
想把外部文档收录到知识库	第十章：知识库消费与维护
遇到错误码 / 安装问题	第十一章常见问题 + 第十二章错误码速查

术语（skeleton、SEI/OSD、RCA 等）不熟悉时，可随时查阅第十三章：术语表。

第二章：安装 Plugin

2.1 安装前准备

开始安装前，请确认以下已就绪：

Claude Code CLI ≥ v1.0（claude --version 查看）

2.2 安装步骤

推荐使用 Plugin 一键安装 方式（一次安装即可获得全部 9 个 Skill + 4 个快捷指令）。

第 1 步：添加 Marketplace

在终端执行：

claude plugin marketplace add <解压目录>

此命令将 cloudapi2 marketplace 注册到您的 Claude Code 配置中，只需执行一次。

第 2 步：安装 Plugin

claude plugin install cloudapi2@dji

此命令启用 cloudapi2@dji plugin，安装完成后新开一个 Claude Code 会话即生效。

其他安装方式

方式	场景	操作
方式 1：Plugin 一键安装	推荐（Claude Code）	上面 2 步
方式 2：手动配置 settings.json	已有全局 skill 目录	编辑 `~/.claude/settings.json` 添加 skill path
方式 3：保持在项目内（零配置）	日常在本仓库内工作	Claude Code 自动发现 `skills/` 目录

2.3 验证安装是否成功

安装完成后，可通过以下任意方式进行验证：

方法 A：查看已安装列表

在 Claude Code 会话中输入：

/plugins

输出中应包含 cloudapi2@dji (enabled)。

方法 B：测试指令补全

在 Claude Code 中输入 /cloudapi2:，如果弹出以下 4 个补全选项，说明快捷指令已注册：

wayline
cockpit
device
replay

方法 C：发一条测试消息

在 Claude Code 中发送：

帮我写一下初始化 FlightHub SDK代码

Claude 应自动触发 cloudapi2-sdk-core Skill，回复中应提到 "initialize 返回值必须检查" 等关键词。

2.4 搭配 superpowers 使用

Plugin 安装后，推荐再安装 superpowers 一起使用：

claude plugin install superpowers

为什么需要两个？

	superpowers	cloudapi2-ai-plugin
解决	"怎么思考和设计"	"怎么用大疆 SDK 实现"
举例	"从零设计一个设备监控架构" → 先发散再收敛	"在 skeleton 中加 OSD 订阅" → 直接给代码
类比	通用思维框架	领域专家手册

两者协作时 AI 会自动分工：superpowers 管方法论流程（brainstorming / TDD / debugging），cloudapi2-ai-plugin 管领域约束和代码模板。未安装 superpowers 时 cloudapi2-ai-plugin 仍可独立工作（使用内置 SOP 流程），但面对开放式设计问题时体验会降级。

2.5 在线 DEMO

想先看看Demo的效果，可查阅上云 API 2 二次开发 Demo - 无人机管理平台使用说明

2.6 升级 / 卸载 Plugin

升级：收到新版压缩包后，先卸载旧版，再下载新的AI Plugin文件重新安装。

卸载：

claude plugin uninstall cloudapi2@dji
claude plugin marketplace remove dji

第三章：如何使用 Plugin

Plugin 提供 3 种使用方式，可根据场景灵活选择。

3.1 方式一：直接对话

直接用自然语言说出你的需求，Claude 会根据关键词自动加载对应 Skill，生成代码或给出解答。

示例对话：

你的问题 / 需求	触发的 Skill	Claude 能做什么
"帮我写一下初始化 FlightHub SDK 代码"	`cloudapi2-sdk-core`	生成含 initialize 返回值检查的 Java 代码
"订阅无人机遥测数据的代码"	`cloudapi2-sdk-core`	生成 listen/cancel 配对的订阅代码
"让无人机返航 / 起飞 / 紧急停机的代码"	`cloudapi2-sdk-core`	生成飞控代码，附控制权 acquire/release 闭环 + 风险提示
"帮我写一个驾驶舱的 HTML 页面代码"	`cloudapi2-frontend-component`	生成完整驾驶舱接入页面
"接入航线编辑器组件代码"	`cloudapi2-frontend-component`	生成 WaylineEditor 完整初始化代码
"怎么获取帧级位置数据？"	`cloudapi2-sei-osd`	讲清 SEI vs OSD 差异，给出订阅代码
"在 skeleton 里加一个设备状态订阅 feature"	`cloudapi2-device-management`	生成 feature 模块骨架 + `@EventListener` 代码
"SDK 返回 error_code: 4001 是什么意思？"	`cloudapi2-troubleshooting`	走 4 阶段 RCA + 查错误码字典
"让 AI Agent 帮我查一下所有在线设备"	`cloudapi2-mcp-guide`	引导 AI 使用 `fh_device_list` MCP 工具
"帮我把 MCP Server 部署到 10.66.x.x"	`cloudapi2-mcp-deploy`	环境探测 + 逐步生成部署命令
"帮我把 skeleton 部署到这台机器"	`cloudapi2-skeleton-deploy`	三形态选型建议 + 逐步引导
"把 https://xxx 文档加到知识库"	`cloudapi2-knowledge-ingest`	模块归属分析 → 格式化 → 入库 + 索引重建

适合场景：不确定参数怎么写、遇到报错需要排查、想理解某个 API 的含义时，直接对话效率最高。

3.2 方式二：快捷指令

当你已知所有参数时，可直接输入快捷指令，Claude 立即生成对应的完整 HTML 代码，无需多轮对话。

4 条可用指令：

指令	生成内容	需要提供的参数
`/cloudapi2:wayline`	航线编辑器完整 HTML（创建 / 编辑 / 预览三种模式）	mode（`create`/`edit`/`preview`）、frontHost、baseUrl、waylineId（edit/preview 必填）
`/cloudapi2:cockpit`	驾驶舱完整 HTML	前端地址、基站序列号、无人机序列号
`/cloudapi2:device`	设备管理完整 HTML	前端地址、鉴权 token（可省略，按对话补）
`/cloudapi2:replay`	飞行记录回放完整 HTML	前端地址、taskId

驾驶舱指令详细示例：

/cloudapi2:cockpit http://xx.xx.xx.xx 7CTDL9K00A0040 1581F8HGD24BK0010105

三个参数依次对应：

位置	示例值	含义
第 1 个参数	`http://xx.xx.xx.xx`	前端服务地址（frontHost）
第 2 个参数	`7CTDL9K00A0040`	基站序列号（gatewaySn）
第 3 个参数	`1581F8HGD24BK0010105`	无人机序列号（droneSn）

执行后，Claude 会输出一份完整可运行的驾驶舱 HTML 页面，以上参数已自动填入代码中，可直接使用。

航线编辑器指令详细示例：

create 模式（3 个参数，无需航线 ID）：

/cloudapi2:wayline create http://xx.xx.xx.xx http://xx.xx.xx.xx:xxxxx/gateway

edit / preview 模式（4 个参数，第 4 个为航线 ID，必填）：

/cloudapi2:wayline edit http://xx.xx.xx.xx http://xx.xx.xx.xx:xxxxx/gateway 510a56b9-4d6d-4f2e-8a1b-0c9d8e7f6a5b

参数依次对应：

位置	示例值	含义
第 1 个参数	`create` / `edit` / `preview`	模式（创建 / 编辑 / 预览）
第 2 个参数	`http://xx.xx.xx.xx`	前端服务地址
第 3 个参数	`http://xx.xx.xx.xx:xxxxx/gateway`	后端网关地址
第 4 个参数	`510a56b9-4d6d-...`	航线 ID（`edit` / `preview` 必填，`create` 不需要）

参数还没确认怎么办？
直接输入 /cloudapi2:cockpit（不带任何参数），Claude 会用占位符生成模板，并标注需要您替换的位置。

适合场景：参数已全部确认、需要快速拿到可用代码时，使用快捷指令效率最高。

3.3 方式三：搭配 MCP Server 直接操控设备

不再需要写代码，让 AI Agent 直接调用 MCP 工具操控无人机 / 机场。

示例对话（Claude Code 已配置 MCP Server）：

"帮我查一下工作空间下所有在线的机场"
"把这条航线上传到机场 GW12345678"
"让无人机 DV12345678 起飞、飞到坐标 (113.9, 22.6)、然后返航"
"订阅这架无人机的实时位置遥测 5 秒"

Claude 会通过 cloudapi2-mcp-guide Skill 判断该调用哪个 MCP 工具，编排多步调用链，返回结构化结果。

适合场景：AI Agent 开发、无人机运维自动化、Prompt 调试演示。MCP Server 接入方式见 第六章。

第二部分：Skill 详解

第四章：Skill 清单

4.1 9 个 Skill 一览

Skill	层级	方向	说明
`cloudapi2-sdk-core`	水平基础	后端 Java SDK	6 条核心规则 + 场景范本 + 代码模板，教 AI 写正确的 SDK 集成代码
`cloudapi2-frontend-component`	水平基础	前端组件	上云 API 2 4 大前端组件（航线 / 驾驶舱 / 设备 / 回放）接入助手
`cloudapi2-mcp-guide`	水平基础	MCP 工具路由	教 AI 在运行时选对 MCP Tool、编排多步调用（三问决策法）
`cloudapi2-device-management`	垂直场景	设备管理	skeleton 后端项目扩展设备管理功能（OSD 订阅 / HMS 告警 / feature 模块创建）
`cloudapi2-sei-osd`	垂直场景	SEI/OSD 遥测	帧级位置数据（SEI）+ 设备遥测（OSD）接入，含前端 Cesium 可视化
`cloudapi2-mcp-deploy`	垂直场景	部署引导	半自动引导将 MCP Server 部署到自有环境（SSE / stdio）
`cloudapi2-skeleton-deploy`	垂直场景	部署引导	半自动引导将 Skeleton 部署到自有环境（普通机器 / Docker Compose / K8s）
`cloudapi2-knowledge-ingest`	横切	知识库入库	将外部文档自动收录到 knowledge/ 知识库并重建索引
`cloudapi2-troubleshooting`	横切	排障	4 阶段 RCA + 错误码字典，快速定位 SDK / 前端问题

层级说明：水平基础层教通用规则（被垂直层引用）；垂直场景层教具体业务接入（引用水平层）；横切层不受场景限制，任何时候遇错/入库都可触发。

4.2 各 Skill 触发场景

Skill 无需手动调用，Claude 会根据您的输入自动匹配加载。下面每个 Skill 都给出了中文自然语言关键词与英文 API / 标识符关键词两类，日常用中文描述需求即可命中。

cloudapi2-sdk-core — 后端 SDK 集成

中文触发关键词：初始化 SDK、飞控、起飞、降落、返航、紧急停机、一键起飞、订阅遥测、取消订阅、获取无人机实例、获取机场实例、获取控制权、释放控制权、鉴权、错误码处理、写 Java 接入代码、后端集成
英文触发关键词：FlightHub、initialize、getDroneInstance、getDockInstance、listen* / cancelListen*、acquireFlightControlAuthority、takeoff / returnHome / emergencyStop、errorCode
典型场景：写 Java 代码调用 SDK、实现飞控逻辑、生成 Spring Boot Service 集成层

cloudapi2-frontend-component — 前端组件接入

中文触发关键词：航线编辑器、驾驶舱、设备管理组件、飞行记录回放、嵌入前端组件、前端接入、前端地址、加载驾驶舱、初始化配置、写一个 HTML 页面、Vue 页面接入
英文触发关键词：paas.js、WaylineEditor、FlyDataReplay、UranusDeviceManagerApp、loadCockpit、initConfig、frontHost / serverHost / wssHost
典型场景：在 skeleton/web（Vue 3）或独立 HTML 页面中接入 4 大前端组件

cloudapi2-mcp-guide — MCP 工具路由

中文触发关键词：创建任务、执行任务、上传航线、设备列表、查询设备、让 AI 操控无人机、该用哪个工具、选哪个工具、编排调用、用自然语言控制机场
英文触发关键词：fh_flight_task、fh_workspace、fh_wayline_upload、fh_device、fh_drone_control
典型场景：AI Agent 通过 MCP 连接 FlightHub Server 并需要调用 fh_* 工具时

cloudapi2-device-management — 设备管理

中文触发关键词：设备管理、设备列表、设备状态订阅、在线离线事件、上下线事件、固件升级、HMS 告警、新建 feature 模块、扩展后端功能、设备拓扑
英文触发关键词：OsdUpdateEvent、HmsAlertEvent、DeviceOnlineEvent、feature 模块、@EventListener
典型场景：在 skeleton 后端项目中扩展设备管理功能、新建自定义 feature 模块

cloudapi2-sei-osd — SEI / OSD 遥测

中文触发关键词：帧级位置、实时位置数据、遥测数据、视锥、相机视场、视频投影、地图可视化、像素反算经纬度、SEI 和 OSD 区别
英文触发关键词：SEI、OSD、FOV、subscribeArSeiInfo、Cesium
典型场景：获取无人机帧级位置、地图上可视化相机视锥 / 视频投影

cloudapi2-mcp-deploy — MCP Server 部署引导

中文触发关键词：MCP 部署、部署 MCP Server、SSE 部署、Docker 部署 MCP、stdio 部署、本地开发部署
英文触发关键词：deploy MCP、FH_SSE_AUTH_TOKEN、FH_MAX_SECURITY_LEVEL
典型场景：Docker Compose 远程 SSE 部署、stdio 本地开发配置、Claude Code / Cursor MCP 接入配置、部署排障

cloudapi2-skeleton-deploy — Skeleton 部署引导

中文触发关键词：skeleton 部署、部署到服务器、Docker 部署 skeleton、K8s 部署、systemd、环境探测
英文触发关键词：deploy skeleton、docker-compose、kubectl
典型场景：Skeleton 三形态部署引导（普通机器 / Docker Compose / K8s）、环境探测与选型建议、密钥生成与配置填写、部署排障

cloudapi2-knowledge-ingest — 知识库入库

中文触发关键词：加到知识库、入库、知识库收录、把这个文档加到知识库、重建索引
英文触发关键词：ingest、rebuild index、llms.txt
典型场景：本地文件 / URL / Confluence / 粘贴文本入库；索引重建

cloudapi2-troubleshooting — 排障

中文触发关键词：报错、错误码、排查、定位问题、修复 bug、白屏、加载失败、连不上、鉴权失败、跨域问题、初始化失败、怎么解决
英文触发关键词：error、errorCode、4001–7000、bug、RCA
典型场景：SDK 返回错误、前端组件白屏、任何时候需要走 4 阶段 RCA 定位问题

4.3 SDK 集成 6 条核心规则

cloudapi2-sdk-core 内置以下 6 条硬约束，代码生成时会自动加入，AI 不会漏掉：

规则	说明	典型错误
规则 1	`initialize()` 必须先完成且检查返回值	未检查返回值就调用其他 API → null
规则 2	所有回调必须检查 `errorCode`	errorCode 非 SUCCESS 时直接使用 data → NPE
规则 3	`listenId` 必须保存，关闭时 `cancel`	不保存 listenId → 回调泄漏
规则 4	飞控指令必须先抢权、用完释放	未 acquire 就发指令 → 权限错误
规则 5	`getInstance` 可能返回 null，必须 null 防御	不做 null 检查 → NPE
规则 6	危险操作必须先输出风险警告	生成 `takeoff` / 紧急停机代码时未提醒用户确认 → 误操作

第三部分：MCP Server 集成指南

第五章：MCP Server 是什么

FlightHub MCP Server 是一个符合 MCP 规范的中间服务，将 DJI FlightHub PaaS SDK 的常用能力（设备管理、飞行控制、媒体管理、航线任务等）暴露为 AI 工具可调用的标准接口。

简单来说：配置完成后，你可以用自然语言让 AI 帮你操控无人机和机场。

┌─────────────────────┐         JSON-RPC          ┌─────────────────────────┐
│   AI Agent / LLM    │ ◀────────────────────────▶ │  FlightHub MCP Server   │
│    (Claude Code)    │   stdio 或 SSE transport   │  (Spring Boot, Java 17) │
└─────────────────────┘                            └────────────┬────────────┘
                                                                │  JNI / SDK
                                                   ┌────────────▼────────────┐
                                                   │  FlightHub PaaS SDK     │
                                                   │  (Linux x86_64 native)  │
                                                   └────────────┬────────────┘
                                                                │  HTTPS/WebSocket
                                                   ┌────────────▼────────────┐
                                                   │  FlightHub 云端平台      │
                                                   └────────────┬────────────┘
                                                                │  4G/5G/RC
                                                   ┌────────────▼────────────┐
                                                   │  无人机 + 机场（Dock）   │
                                                   └─────────────────────────┘

典型场景：

AI 辅助巡检调度：用自然语言描述巡检路线，Agent 自动生成航线并执行飞行任务
无人机状态监控：AI 持续查询设备遥测，异常时自动触发告警或返航
开发调试加速：开发者在 Claude Code 中直接对话 FlightHub，无需切换控制台

第六章：MCP Server 接入

6.1 前置条件

条件	说明
支持 MCP 的 AI 工具	Claude Code
MCP 接入地址与 Token	由平台侧提供

注意：MCP Server 由平台侧统一部署，用户无需自行安装或运行任何服务。

6.2 接入 Claude Code

获取 token 的方式：

本地 pc 执行：

sshpass -p '1234' ssh fhaio@127.0.0.1 "echo 1234 | sudo -S docker inspect pf-devkit-mcp --format '{{range .Config.Env}}{{println .}}{{end}}'" | grep '^FH_SSE_AUTH_TOKEN='

注意：其中，1234替换为密码；fhaio替换为远程机器用户，127.0.0.1替换为远程机器IP。若未安装 sshpass 可以安装后再次执行，若执行异常可前往所在服务端执行第二条命令。

服务端执行：

sudo -S docker inspect pf-devkit-mcp --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^FH_SSE_AUTH_TOKEN=' | cut -d= -f2-

接入 claude code

在终端执行：

claude mcp add dji-cloud-api2 http://<ip>:<port>/pf-devkit/ai-plugin/mcp/sse --transport sse -s user -H "Authorization: Bearer <token>"

修改 token 和 ip:port 配置完成后重启 Claude Code 即可生效。建议您自行修改MCP Server服务的token，以免默认 token 泄露出现安全风险。port填写：30812

卸载 MCP 的命令：

claude mcp remove dji-cloud-api2

第七章：MCP 使用说明

MCP Server 提供 50+ 个工具。以下是常用工具速查：

模块	代表工具	说明
连接管理	`fh_connect` / `fh_disconnect`	初始化 SDK 会话、断开会话
工作空间	`fh_workspace_info` / `fh_workspace_device_topo`	查询工作空间、设备拓扑
设备管理	`fh_device_list` / `fh_device_info` / `fh_device_status`	查询设备列表、详情、状态
飞行任务	`fh_flight_task_create` / `fh_flight_task_execute` / `fh_flight_task_pause` / `fh_flight_task_resume`	创建 / 执行 / 暂停 / 恢复任务
航线管理	`fh_wayline_upload` / `fh_wayline_list` / `fh_wayline_delete`	上传 KMZ 航线、查询、删除
飞控	`fh_drone_takeoff` / `fh_drone_return_home` / `fh_drone_emergency_stop` / `fh_drone_flyto`	起飞 / 返航 / 紧急停机 / 飞往坐标
控制权	`fh_control_acquire` / `fh_control_release`	获取 / 释放飞行控制权
直播	`fh_livestream_start` / `fh_livestream_stop`	启动 / 停止直播
HMS	`fh_hms_query` / `fh_hms_subscribe`	查询 / 订阅健康告警
媒体	`fh_media_list` / `fh_media_download_url`	媒体文件列表、下载 URL

AI 无需记忆工具名：cloudapi2-mcp-guide Skill 会引导 AI 根据用户诉求选对工具、编排调用顺序。

7.1 基本使用流程

所有操作遵循以下基本流程：

1. 建立会话      fh_connect（所有操作的前提，必须第一步）
       │
2. 查询设备      fh_device_list → 获取设备 SN
       │
3. 获取状态      fh_drone_snapshot / fh_dock_snapshot
       │
4. 执行操作      飞行控制 / 航线任务 / 媒体管理 / ...
       │
5. 释放资源      fh_control_release（如有获取控制权）

7.2 飞行操作的前置条件链

如果你需要实时控制无人机飞行（指点飞行、环绕飞行等），需要按以下顺序建立前置条件：

fh_connect                → 建立会话
  └── fh_control_acquire  → 获取飞行控制权（互斥资源）
        └── fh_drc_connect → 建立 DRC 低延迟链路
              └── fh_takeoff / fh_flyto / fh_poi ...  → 执行飞行指令
              └── fh_drc_disconnect → 断开 DRC
        └── fh_control_release → 释放控制权（必须！即使出错也要释放）

不用担心记不住这个链路——AI 会自动按正确顺序调用。你只需要用自然语言描述你想做什么。

第八章：常用场景示例

场景 1：查询设备列表

你说：

帮我查看当前工作空间里有哪些设备在线

AI 将调用： fh_connect → fh_device_list

返回： 所有设备的名称、SN、类型、在线状态。

场景 2：获取无人机实时状态

你说：

查看无人机 4TADL9D0020B5H 的当前状态

AI 将调用： fh_drone_snapshot 或 fh_osd_snapshot

返回： 位置（经纬度/高度）、电量、速度、飞行模式、GPS 信号等。

场景 3：一键起飞并飞到指定位置

你说：

让无人机 4TADL9D0020B5H 起飞到 50 米高度位置

AI 将调用：

fh_control_acquire — 获取控制权
fh_drc_connect — 建立 DRC 链路
fh_takeoff — 起飞到 50 米 ⚠️ 需要你确认
fh_flyto — 飞到目标坐标 ⚠️ 需要你确认
飞行完成后 fh_drc_disconnect + fh_control_release — 释放资源

所有 L2 飞行操作都会弹窗要求你确认后才执行。

场景 4：执行航线任务

你说：

查看机场 7CZDM680C200EP 可用的航线，选一条适合的执行飞行任务

AI 将调用：

fh_wayline_recommend — 推荐该机场可飞的航线
fh_flight_task(action=create) — 创建飞行任务
fh_wayline_execute — 执行航线 ⚠️ 需要你确认

场景 5：拍照与录像

你说：

让无人机拍一张照片

AI 将调用： fh_camera(action=camera_photo)

你说：

开始录像，30 秒后停止

AI 将调用： fh_camera(action=camera_video_start) → 等待 → fh_camera(action=camera_video_stop)

场景 6：环绕兴趣点飞行

你说：

让无人机围绕机场的位置，以 50 米半径、5 米/秒的速度顺时针环绕飞行

AI 将调用：

fh_dock_snapshot — 获取机场 GPS 坐标作为环绕中心
fh_poi(action=start) — 开始环绕 ⚠️ 需要你确认

注意：环绕中心不能是无人机当前位置，需要是一个地面目标（如机场、建筑物）。

场景 7：紧急返航

你说：

让无人机立即返航

AI 将调用： fh_return_home(action=start) ⚠️ 需要你确认

如果遇到紧急情况需要立即悬停：

紧急停止无人机！

AI 将调用： fh_emergency_stop ⚠️ L3 级别，需要提供原因并确认

第九章：安全机制

MCP Server 内置 4 级安全等级，防止 AI 误操作真实设备。

9.1 SecurityLevel 分级

等级	名称	举例	默认允许
L0	只读	`fh_device_list` / `fh_workspace_info`	✅ 是
L1	快照	`fh_drone_snapshot`（取一次快照，非持续订阅）	✅ 是
L2	常规控制	`fh_flight_task_execute` / `fh_wayline_upload`	✅ 是
L3	紧急 / 危险	`fh_drone_takeoff` / `fh_drone_emergency_stop`	⚠️ 需显式提升

L1 说明：遥测类工具默认按"取一次快照"计为 L1；若需要持续订阅推流，会按更高等级处理。

9.2 安全等级上限

平台管理员可通过 FH_MAX_SECURITY_LEVEL 环境变量设置全局上限：

设为 1：只允许读取和可逆操作，所有飞行指令被拒绝
设为 2：允许飞行操作，禁止紧急停止（生产环境推荐）
设为 3：允许所有操作（仅限紧急场景）

获取安全等级的方式：

本地 pc 执行：

sshpass -p '1234' ssh fhaio@127.0.0.1 "echo 1234 | sudo -S docker inspect pf-devkit-mcp --format '{{range .Config.Env}}{{println .}}{{end}}'" | grep '^FH_MAX_SECURITY_LEVEL='

注意：其中，1234替换为密码；fhaio替换为远程机器用户，127.0.0.1替换为远程机器IP。若未安装 sshpass 可以安装后再次执行，若执行异常可前往所在服务端执行第二条命令

服务端执行：

sudo -S docker inspect pf-devkit-mcp --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^FH_MAX_SECURITY_LEVEL=' | cut -d= -f2-

配置方式： 修改容器的环境变量

FH_MAX_SECURITY_LEVEL=2      # 生产建议：只放开到 L2，禁止起飞 / 紧急停机
FH_MAX_SECURITY_LEVEL=3      # 演示 / 开发：允许全部工具

危险工具二次确认： 对于 L3 级工具，Claude Code 会在调用前弹窗询问用户确认，无需额外配置。

9.3 dry_run 预览模式

所有 L1 及以上的工具支持 dry_run=true 参数。当使用 dry_run 时：

参数校验和前置条件检查正常执行
不会实际调用 SDK 或执行飞行操作
返回"如果真正执行会做什么"的预览信息

适用场景：

首次使用时验证参数是否正确
演示操作流程但不实际执行
教学和培训场景

使用方式： 告诉 AI "用 dry_run 模式预览一下" 或 "不要真的执行，先给我看看会怎样"。

第四部分：知识库

第十章：知识库消费与维护

cloudapi2-knowledge-ingest Skill 背后的 knowledge/ 目录是一个可独立消费的领域知识库，回答"SDK 是怎么工作的"，与 Skills（"写代码时该怎么做"）和 MCP Server（"帮我执行操作"）互补。

10.1 知识库内容概览

当前版本（v1.0.0，适用 SDK 3.1.1）包含 7 个模块：

模块	覆盖内容
getting-started	SDK 初始化、环境配置
architecture	系统架构全景、飞控权限模型
api-reference	核心规则、错误码、飞控 API、设备管理
operations	部署架构与运维
faq	高频问题汇总
scenarios	场景包（建设中）
migration	从 API 1 迁移（建设中）

10.2 四种消费方式

消费者	入口	适用场景
AI Agent / LLM	`llms.txt`（索引）/ `llms-full.txt`（全量）	Prompt 注入领域知识，辅助代码生成和决策
Claude Code 用户	Skills 自动引用	编码时自动获取 SDK 知识（无需手动操作）
RAG Pipeline	frontmatter + `.md`	向量检索、语义搜索
人类开发者	直接阅读 `.md`	SDK 接入参考、问题排查

10.3 通过 Skill 自动入库（推荐）

安装了 cloudapi2@dji Skills 后，直接对 Claude 说：

"把这个文档加到知识库：<本地路径 / URL / 飞书 / Confluence 页面 ID>"

Skill 会自动完成：内容获取 → 模块归属分析 → 格式化（含 YAML frontmatter）→ 写入 + 索引重建 + Git 提交。

支持的输入源：本地文件、URL、飞书文档、Confluence 页面、直接粘贴文本。

10.4 手动新增与索引重建

在对应模块目录下创建 .md 文件，添加 YAML frontmatter（必填字段：title、module、tags、audience、summary、last_updated）。然后：

./knowledge/scripts/rebuild-index.sh          # 重建索引
./knowledge/scripts/rebuild-index.sh --check  # 检查索引是否过期（可接入 CI pre-commit hook）

脚本会扫描所有 .md 的 frontmatter，按 metadata.yaml 声明的模块顺序生成 llms.txt，更新各模块目录下的 index.md，调用 build-llms-full.sh 生成 llms-full.txt。

第五部分：附录

第十一章：常见问题

11.1 Plugin 安装与使用

Q：claude plugin marketplace add 报错 "command not found"？

您的 Claude Code 版本可能低于 v1.0，请升级 Claude Code。

Q：Plugin 安装后 Skill 没触发怎么办？

确认 /plugins 输出中 cloudapi2-ai-plugin@cloudapi2 状态为 enabled
确认 JSON 格式正确 —— 运行 cat ~/.claude/settings.json | python3 -m json.tool 验证
新开一个 Claude Code 会话（旧会话不生效）

Q：Skill 生成的代码质量怎么样？

Skill 内置了资深开发工程师截止目前已积累的 5 条硬约束：

initialize() 返回值必须检查
所有 listen* 必须配 cancelListen*
飞行控制权 acquire 后必须 release
getDroneInstance / getDockInstance 返回值必须 null 防御
错误码非 0 必须显式处理

代码生成时这些约束会自动加入，AI 不会漏掉。

Q：搭配 superpowers 会不会冲突？

不会。两者协作时 AI 会自动分工：superpowers 管方法论流程（brainstorming / TDD / debugging），cloudapi2-ai-plugin 管领域约束和代码模板。未安装 superpowers 时 cloudapi2-ai-plugin 独立工作，使用内置 SOP 流程。

11.2 MCP 使用

Q：MCP 连接失败，提示 "401 Unauthorized"

MCP Token 无效或已过期。请重新获取 Token 并更新配置。

Q：连接成功但调用工具时提示 "session not found"

会话可能已超时断开（默认 30 分钟无操作）。重新发送"连接 FlightHub"即可恢复。

Q：操作被拒绝，提示 "security level exceeded"

你尝试执行的操作超过了平台管理员设置的安全等级上限。请联系管理员调整 FH_MAX_SECURITY_LEVEL 或改用低等级操作。

Q：飞行指令失败，提示 "control authority not acquired"

飞行操作前需要先获取控制权。正常情况下 AI 会自动处理，如果仍然失败，可能是其他 session 持有控制权，等待对方释放或联系管理员。

Q：无人机显示 offline，无法操作

机场内的无人机在待机时通常是离线状态（断电存储），这是正常现象。只要机场（Airport/Dock）在线即可执行起飞等操作。

Q：如何在不实际飞行的情况下测试？

使用 dry_run 模式——所有 L1+ 工具支持 dry_run=true，只校验不执行。

Q：操作执行后无人机没反应

请检查：

设备是否在线（fh_device_list）
是否已建立 DRC 链路（fh_session_info 查看链路状态）
无人机是否在机场内（需要先起飞）
信号是否正常（查看 OSD 中的 GPS 和链路质量）

Q：如何查看操作历史？

使用 fh_flight_record 查询飞行记录，或使用 fh_hms 查询健康告警历史。所有 L1+ 操作都有审计日志。

Q：支持同时控制多台无人机吗？

当前 MCP Server 单个 session 一次只能控制一台无人机（控制权互斥）。可在释放控制权后切换到另一台。查询和监控操作不受此限制，可同时查看多台设备状态。

第十二章：错误码速查

FH_ 前缀 SDK 错误码：

错误码	含义	常见排查方向
`4001`	WebSocket 鉴权失败	检查 token 是否过期、`authKeys` 是否与网关配置一致
`4002`	WebSocket 连接断开	检查网络、`wssUrl` 路径
`5000`	API 请求失败	检查 `serverUrl`、服务端日志
`5001`	API 鉴权失败（401 / 403）	检查 token、账号权限
`6000`	航线数据解析失败	检查 KMZ 格式
`6001`	WASM 模块加载失败	检查前端资源路径、跨域
`6002`	地图初始化失败	检查 Cesium 资源、DOM 容器尺寸
`7000`	OSS 上传失败	检查 OSS 凭证、网络

触发 cloudapi2-troubleshooting Skill 直接问： "error_code 4001 怎么排查？" —— Claude 会自动走 4 阶段 RCA（Reproduce → Locate → Fix → Verify）+ 查错误码字典给出定位。

第十三章：术语表

正文首次出现、可能不熟悉的术语集中解释如下：

术语	含义
上云 API 2 / Cloud API 2	大疆面向企业的第二代无人机上云接入接口体系，本 Plugin 即围绕其接入而构建
PaaS 组件	以前端组件形式提供的能力（驾驶舱 / 航线编辑器 / 设备管理 / 飞行记录），可嵌入自有页面
skeleton	cloudapi2-ai-plugin 提供的后端脚手架项目（Spring Boot），供 ISV 在其上扩展 feature 模块
feature 模块	skeleton 中一个自包含的业务功能单元（如设备状态订阅），可独立新增
SEI	Supplemental Enhancement Information，随视频帧下发的帧级位置等元数据
OSD	On-Screen Display，设备遥测数据（位置、电量、姿态等）的周期性推送
视锥 / FOV	相机视场（Field of View）在三维空间中的锥体，用于在地图上可视化拍摄范围
RCA	Root Cause Analysis 根因分析，排障采用 4 阶段：Reproduce → Locate → Fix → Verify
MCP	Model Context Protocol，AI 工具与外部能力交互的开放协议
DRC	无人机低延迟控制链路，实时飞行控制（指点 / 环绕等）前需先建立
JNI	Java Native Interface，Java 调用本地（native）库的机制；SDK 原生库仅支持 Linux x86_64
Whistle 代理	一款前端抓包 / 代理调试工具，接入调试时常用于解决跨域、Mixed Content 等问题
Mixed Content	HTTPS 页面加载 HTTP 资源被浏览器拦截的问题，接入前端组件时常见
gatewaySn / droneSn	基站（机场 / 网关）序列号 / 无人机序列号，前端组件与飞控接口的关键入参

上云 API 2 AI Plugin 使用指南

第一部分：AI Plugin 使用指南

第一章：产品介绍

1.1 这是什么

1.2 能帮你做什么

1.3 适用人群

1.4 我该从哪里开始（快速决策）

第二章：安装 Plugin

2.1 安装前准备

2.2 安装步骤

2.3 验证安装是否成功

2.4 搭配 superpowers 使用

2.5 在线 DEMO

2.6 升级 / 卸载 Plugin

第三章：如何使用 Plugin

3.1 方式一：直接对话

3.2 方式二：快捷指令

3.3 方式三：搭配 MCP Server 直接操控设备

第二部分：Skill 详解

第四章：Skill 清单

4.1 9 个 Skill 一览

4.2 各 Skill 触发场景

4.3 SDK 集成 6 条核心规则

第三部分：MCP Server 集成指南

第五章：MCP Server 是什么

第六章：MCP Server 接入

6.1 前置条件

6.2 接入 Claude Code

获取 token 的方式：

接入 claude code

第七章：MCP 使用说明

7.1 基本使用流程

7.2 飞行操作的前置条件链

第八章：常用场景示例

场景 1：查询设备列表

场景 2：获取无人机实时状态

场景 3：一键起飞并飞到指定位置

场景 4：执行航线任务

场景 5：拍照与录像

场景 6：环绕兴趣点飞行

场景 7：紧急返航

第九章：安全机制

9.1 SecurityLevel 分级

9.2 安全等级上限

获取安全等级的方式：

9.3 dry_run 预览模式

第四部分：知识库

第十章：知识库消费与维护

10.1 知识库内容概览

10.2 四种消费方式

10.3 通过 Skill 自动入库（推荐）

10.4 手动新增与索引重建

第五部分：附录

第十一章：常见问题

11.1 Plugin 安装与使用

11.2 MCP 使用

第十二章：错误码速查

第十三章：术语表