Навык интеграции
Что такое FH2 Integration Skill
FH2 Integration Skill — это пакет предметных знаний, разработанный для ИИ-ассистентов программирования. После установки, когда вы формулируете ИИ-ассистенту задачу интеграции с FlightHub 2, ассистент отвечает в соответствии с проверенной методологией, а не догадывается по памяти и не выдумывает интерфейсы. Поддерживаются основные ассистенты программирования, такие как Claude Code, Cursor, OpenCode, Trae и Tongyi Lingma.
Skill охватывает два основных сценария интеграции — экстренное реагирование DFR и инспекция / патрулирование — и включает полный набор ресурсов: базу знаний, эталонную демонстрационную реализацию и оценочные кейсы.
Какие задачи решает
| Без Skill | С Skill |
|---|---|
| ИИ может выдумать несуществующие эндпоинты API | Применяется защита от галлюцинаций: при неуверенности ИИ прямо сообщает об этом и указывает на официальную документацию для проверки |
| Интерфейсы публичного облака и локального развертывания смешиваются | Сначала подтверждается модель развертывания, границы API строго разделяются |
| Практики экстренного назначения применяются к плановой инспекции | Сначала подтверждается сценарий, два рабочих процесса проектируются раздельно |
| Официальная документация разрознена и трудна для навигации | Таблицы выбора, сгруппированные по областям возможностей, плюс сопоставление требований с эндпоинтами |
| В сгенерированном коде отсутствуют механизмы защиты | Встроенные минимальные требования к проверке подписи, идемпотентности, правам доступа и аудиту |
Integration Skill не пишет за вас бизнес-код. Она гарантирует, что в предметной области FlightHub 2 ИИ ничего не выдумывает, не выходит за границы и не упускает пункты безопасности.
Кому и как использовать
Пользователи без опыта пользовательской разработки
Цель: понять, что умеет FlightHub 2.
Просто спросите ИИ-ассистента обычным языком. Skill представляет возможности через меню функций, а затем в ходе многошагового диалога вырабатывает решение, подходящее вашему бизнесу.
Пример вопроса: Мы хотим использовать дроны для охраны кампуса. Какие возможности может предоставить FlightHub 2?
Пользователи с некоторым опытом разработки, которым нужна быстрая демонстрация
Цель: быстро запустить демо.
Используйте готовое к запуску демо, входящее в состав Skill. Введите ключ вашей организации FlightHub 2, чтобы пройти полный рабочий процесс.
Пример вопроса: Я хочу быстро запустить демо, чтобы показать руководителю. С чего начать?
Опытные разработчики
Цель: сопоставить требования с конкретными интерфейсами и приступить к написанию кода.
Попросите ИИ-ассистента сопоставить ваши требования с конкретными эндпоинтами и начинайте писать код, как только будет готова таблица соответствия.
Пример вопроса: Мне нужно интегрировать прямую трансляцию. Помоги определить, какие эндпоинты подходят и где есть пробелы.
Установка и рекомендуемая среда
Поместите загруженный каталог fh2-integration-skill/ в каталог skills вашего ИИ-ассистента программирования либо настройте его содержимое как файлы правил уровня проекта. Дополнительные зависимости не требуются. После установки достаточно задать вопрос о FlightHub 2 / DFR / инспекции, чтобы автоматически активировать Skill.
Инструменты программирования
| Инструмент программирования | Способ загрузки |
|---|---|
| Claude Code | Поместите в ~/.claude/skills/fh2-integration-skill/ |
| OpenCode | Поместите в ~/.config/opencode/skills/fh2-integration-skill/ |
| Cursor | Скопируйте содержимое adapters/cursor-rules.md в .cursor/rules/fh2-integration.mdc |
| Trae / Tongyi Lingma | Настройте как правило проекта или подключите как базу знаний проекта |
Пути к файлам правил различаются в зависимости от версии инструмента; обращайтесь к официальной документации каждого инструмента. Основной принцип — сделать SKILL.md и references/ постоянной частью контекста ИИ.
Рекомендуемые модели
Эта Skill представляет собой довольно объёмный набор поведенческих ограничений и содержимого базы знаний и требует сильных способностей к пониманию длинного контекста и следованию инструкциям. Рекомендуются следующие модели:
| Модель | Поставщик |
|---|---|
| DeepSeek V4 Pro и выше | DeepSeek |
| Qwen 3.8 Max | Alibaba Cloud |
| Claude Opus 5 | Anthropic |
| GPT-5.6 Sol | OpenAI |
Примечание
Возможности модели не изменяют границы безопасности Skill. Независимо от используемой модели Skill обеспечивает соблюдение ограничений против галлюцинаций и двух этапов подтверждения. Если модель часто пропускает уточняющие вопросы или выдумывает эндпоинты, перейдите на модель с более высокой способностью следовать инструкциям.
Опционально: подключение OpenAPI MCP
Если в вашей среде доступен OpenAPI MCP FlightHub 2 / Apifox, данная Skill отдаёт предпочтение чтению реальных эндпоинтов и схем через MCP для сопоставления требований и изменения кода, вместо того чтобы требовать от вас самостоятельного изучения документации. При отсутствии MCP она использует ссылки на официальную документацию. Ни в одном из случаев она не выдумывает эндпоинты.
Ключевой механизм: два этапа проверки
Это важнейший элемент архитектуры данной Skill. Прежде чем дать какие-либо рекомендации по API, ИИ-ассистент должен последовательно пройти два этапа подтверждения.
Этап первый · Проверка развертывания
Подтвердите модель развертывания FlightHub 2: публичное облако / локальное развертывание / AIO
Область действия API и модель аутентификации различаются в зависимости от модели развертывания, поэтому данный шаг определяет границы для последующего выбора интерфейсов.
Этап второй · Проверка сценария
Подтвердите категорию интегрируемого рабочего процесса: экстренное реагирование DFR / инспекция и патрулирование / оба варианта
Различные сценарии существенно отличаются по выбору интерфейсов, потоку данных и акцентам безопасности.
После прохождения обоих этапов
Только после этого Skill начинает предоставлять: проектирование архитектуры → сопоставление интерфейсов → план реализации → механизмы защиты безопасности → план тестирования.
Почему ИИ «сначала спрашивает вас», а не отвечает сразу
Это сделано намеренно. Разные модели развертывания открывают совершенно разные API, а разные сценарии требуют разных интерфейсов. Skill прямо запрещено выводить модель развертывания по таким признакам, как формат токена, URL, домен или регион, — цена ошибки в догадке — нерабочее решение.
Различия между двумя сценариями
| Параметр | DFR / Экстренное реагирование | Инспекция / Патрулирование |
|---|---|---|
| Источник запуска | Внешние тревоги, обработка вызовов CAD | Планы, расписания, циклы |
| Оперативность | Экстренное реагирование в пределах секунд | Регулярная периодическая работа |
| Основные интерфейсы | Процесс автоматического назначения | Маршруты + плановые задачи |
| Акцент потока данных | Прямая трансляция в реальном времени, передача управления оператору | Съёмка → анализ → обмен |
| Постобработка | Обработка на месте, архивирование доказательств | Распознавание дефектов ИИ / VLM, 3D-реконструкция |
Область возможностей
DFR / Экстренное реагирование
- Системы CAD и тревожной сигнализации → связующее ПО назначения FlightHub 2
- Интеграция прямой трансляции с дрона в VMS / экраны командного центра
- Интеграция телеметрии в платформы ситуационной осведомлённости GIS / PSIM
- Конвейеры архивирования медиафайлов и доказательств
Инспекция / Патрулирование
- Загрузка маршрутов, синхронизация с библиотекой маршрутов FlightHub 2 и назначение плановых задач
- Медиафайлы инспекции → анализ дефектов ИИ / VLM → сторонние платформы
- Синхронизация результатов 3D-реконструкции / облака точек
Общие возможности
- Приём и обработка обратных вызовов Event API
- Выбор интерфейса между FlightHub Sync / OpenAPI / MQTT Bridge
- Проверка границ API между публичным облаком и локальным развертыванием
- Встраивание возможностей FlightHub 2 в существующую платформу (проектирование слоя адаптации)
- Планы реализации, планы тестирования и механизмы защиты безопасности
Как формулировать вопросы
Специальный синтаксис не требуется — просто опишите свои требования обычным образом. Приведённые ниже примеры можно использовать напрямую:
Консультация по возможностям:
Мы хотим использовать дроны для инспекции подстанций. Какие возможности может предоставить FlightHub 2? Помоги составить решение.
Проектирование интеграции DFR:
Мы используем FlightHub 2 в публичном облаке. Помоги спроектировать связующее ПО от тревог CAD до назначения задач.
Проектирование интеграции инспекции:
У нас локальное развертывание. Спроектируй связующее ПО назначения задач для планового тепловизионного обследования подстанции.
Интеграция с существующей системой:
У нас уже есть платформа эксплуатации и обслуживания, и мы хотим встроить в неё возможности FlightHub 2, а не разворачивать ещё одну отдельную систему.
Сопоставление интерфейсов:
Мне нужно интегрировать прямую трансляцию. Помоги определить подходящие эндпоинты и составить таблицу соответствия требований и эндпоинтов.
Совет по формулировке вопросов
Если вы уже знаете свою модель развертывания и сценарий, укажите их в первой же фразе (например, «У нас локальное развертывание, занимаемся инспекцией»). Это позволит пропустить уточняющие вопросы двух этапов и сразу перейти к проектированию решения.
Демо в комплекте
Skill включает готовую к запуску эталонную реализацию интеграции с публичным облаком FlightHub 2, расположенную в examples/dfr-public-cloud-demo/.
| Страница | Функция | Соответствующая возможность |
|---|---|---|
| Карта проекта | Выбор цели и назначение задачи | Процесс автоматического назначения |
| Информация MQTT | Подписка на телеметрию дрона | Пересылка телеметрии |
| Маршруты инспекции | Загрузка маршрутов и синхронизация с библиотекой маршрутов FlightHub 2 | Внешний бакет FlightHub Sync |
| Информация Event API | Приём и отображение сообщений обратного вызова | Event API |
| Бакет S3 | Управление медиафайлами и файлами доказательств | Объектное хранилище |
| Параметры конфигурации | Ввод всех параметров подключения | — |
Быстрый старт
Бэкенд:
cd examples/dfr-public-cloud-demo/backend
npm install && npm start # 默认 http://localhost:3000
Фронтенд (в отдельном терминале):
cd examples/dfr-public-cloud-demo/frontend
npm install && npm run serve
Подробные шаги см. в файле QUICKSTART.md в каталоге демо. Для развертывания в облаке см. deploy/README.md.
Реальное назначение задач можно опробовать локально
Достаточно иметь ключ организации FlightHub 2 — ваш локальный
localhostможет отправлять реальные команды назначения задач: не требуются ни облачный сервер, ни публичный IP, ни туннелирование во внутреннюю сеть. Назначение задачи — это исключительно исходящий запрос (браузер → локальный бэкенд → FlightHub Cloud), который беспрепятственно проходит через NAT. Это самый быстрый путь от «чтения документации» до «наблюдения за тем, как ангар открывает крышку».
Справка по локальной доступности
| Функция | Направление трафика | Доступно исключительно локально |
|---|---|---|
| Назначение задач | Вы → FlightHub Cloud | ✅ Доступно |
| Обратный вызов Event API | FlightHub Cloud → Вы | ❌ Требуется публичная точка входа |
| Телеметрия MQTT | FlightHub Cloud → ваш брокер | ❌ Требуется публичная точка входа |
| Синхронизация маршрутов | FlightHub Cloud → ваш бакет S3 | ❌ Требуется публичная точка входа |
Последние три требуют, чтобы FlightHub 2 инициировал подключения к вашей машине; это можно обеспечить с помощью инструментов туннелирования во внутреннюю сеть, таких как ngrok или cpolar.
⚠️ Назначение задач управляет реальным оборудованием
Это не симуляция: ангар действительно откроет крышку, а дрон взлетит. Перед отправкой команды убедитесь в соответствии требованиям к воздушному пространству и наличии наблюдения на месте, и по возможности используйте тестовый ангар.
Подготовка перед пробным запуском
- Ключ организации: FlightHub 2 → Моя организация → Настройки организации → OpenAPI → скопируйте ключ
- UUID проекта: получите его, вызвав интерфейс «Получение списка проектов организации»
- (Опционально) MinIO / S3, брокер MQTT, сервер потоковой передачи
⚠️ Демо носит учебный характер и не является промышленным решением
Чтобы снизить порог входа, в демо намеренно опущены некоторые обязательные для промышленной эксплуатации элементы (например, проверка подписи Event API и хранение в базе данных). Использовать его напрямую в промышленной среде небезопасно. Обязательно прочитайте
LIMITATIONS.mdв каталоге демо, где перечислены все известные ограничения и контрольный список готовности к промышленной эксплуатации.
О картах
Демо автоматически выбирает базовую карту в соответствии с языком браузера (Amap для китайскоязычных пользователей, Google для остальных). Все базовые карты содержат предупреждение о смещении системы координат — положение на карте не является фактическим положением дрона в полёте; используйте положение ангара в качестве ориентира. Кроме того, тайлы Google, используемые в демо, поступают из неофициального интерфейса и предназначены только для демонстрации; в промышленной среде необходимо перейти на официальный API.
Границы безопасности
Skill содержит набор обязательных ограничений. Их понимание поможет вам точнее оценивать надёжность результатов работы ИИ.
Ситуации, когда ИИ остановится и задаст вопрос
| Условие срабатывания | Что необходимо подтвердить |
|---|---|
| Модель развертывания неизвестна | Публичное облако / локальное развертывание / AIO |
| Режим аутентификации не определён | Token / OAuth / SSO и какие значения являются заполнителями |
| Затрагивается управление полётом, назначение задач, полезные нагрузки или конфигурация устройств | Авторизованная среда, вмешательство человека, путь проверки безопасности |
| Работа с реальной системой заказчика | Явная авторизация и целевая среда |
| Эндпоинт не подтверждён в документации | Проверить по официальной документации |
Чего она никогда не сделает
- Не выдумает эндпоинты, поля запросов, типы событий или топики MQTT
- Не смешает API публичного облака и локального развертывания
- Не порекомендует для публичного облака возможности, доступные только при локальном развертывании
- Не будет рассматривать результаты распознавания ИИ как непосредственное основание для принятия решений о реагировании
- Не опустит ограничения безопасности полёта, такие как human-in-the-loop и геозоны
Если ИИ говорит «я не могу подтвердить эту возможность»
Это не недостаток возможностей — это предусмотрено архитектурой. По сравнению с выдумыванием эндпоинта, который выглядит правдоподобно, но не работает, чёткое указание на неопределённость и ссылка на официальную документацию для вас ценнее.
Структура каталогов
fh2-integration-skill/
├── SKILL.md Точка входа Skill: рабочий процесс, контрольные точки, шаблоны вывода
├── README.md / README.zh-CN.md Обзор проекта (на английском и китайском)
├── references/ База знаний (12 документов + руководство по чтению на китайском)
│ ├── README.zh-CN.md Оглавление руководства по чтению на китайском; рекомендуемая отправная точка
│ ├── api-guardrails.md Базовые требования безопасности и правила против галлюцинаций (высший приоритет)
│ ├── capability-overview.md Обзорное меню возможностей (для неразработчиков)
│ ├── scenario-dfr-vs-inspection.md Выбор сценария
│ ├── dfr-integration-architecture.md Архитектура DFR и выбор интерфейсов
│ ├── inspection-integration-architecture.md Архитектура инспекции и выбор интерфейсов
│ ├── integrate-with-existing-system.md Интеграция с существующей платформой
│ ├── middleware-patterns.md 9 шаблонов проектирования связующего ПО
│ ├── demo-localization.md Многоязычность и локализация
│ └── ... Границы развертывания, панорама возможностей API, происхождение источников
├── adapters/ Руководства по адаптации для Claude Code / Cursor
├── evals/ 14 кейсов оценки качества
└── examples/
└── dfr-public-cloud-demo/ Готовая к запуску эталонная реализация
Чтобы подробнее ознакомиться с базой знаний, откройте
references/README.zh-CN.md, где поясняется, что охватывает каждый файл и когда он используется.
Часто задаваемые вопросы
В: Почему ИИ всегда сначала задаёт вопросы, а не отвечает сразу?
Потому что модель развертывания и сценарий принципиально меняют набор доступных интерфейсов. Это ключевой элемент архитектуры Skill, а не многословие. Вы можете указать оба пункта в первой же фразе, чтобы пропустить уточняющие вопросы.
В: Файлы знаний в Skill написаны на английском. Можно ли их перевести?
Документы, предназначенные для людей (README, руководства по использованию, runbook по оценке, документация демо), имеют версии на китайском языке. SKILL.md и references/ — это файлы поведенческих ограничений, читаемые ИИ, и они намеренно сохранены на английском: инструкции на английском обеспечивают более высокую точность соблюдения и позволяют избежать противоречивых правил из-за смещения смысла при переводе. Если вам нужно разобраться в конкретном файле, просто попросите ИИ объяснить его вам на китайском.
В: Можно ли использовать предоставленные ИИ эндпоинты напрямую?
Не напрямую в промышленной среде. Skill отмечает, какое содержимое требует проверки. Перед выводом в промышленную эксплуатацию всегда сверяйте точное тело запроса, поля ответа и требования к правам доступа с официальной документацией Apifox.
В: Можно ли адаптировать демо под нашу собственную систему?
Да, но рекомендуется рассматривать его как каркас слоя адаптации, а не как готовый продукт. Обратитесь к ARCHITECTURE.md в каталоге демо, где каждый модуль сопоставлен с базой знаний и перечислены пункты, необходимые для перехода от демонстрации к промышленной эксплуатации.
В: Можно ли использовать эту Skill для локальных развертываний?
Да. Skill охватывает как публичное облако, так и локальное развертывание / AIO и строго различает границы их интерфейсов. Однако учтите, что входящее в комплект демо написано для публичного облака. Локальные развертывания имеют более широкий набор интерфейсов и могут использовать иные методы аутентификации, поэтому не копируйте код демо напрямую.
FH2 Integration Skill — это вспомогательный инструмент для проектирования интеграций. Он не может заменить официальную документацию DJI, проверку безопасности заказчиком, юридическую экспертизу, получение разрешений авиационных органов или валидацию в промышленной среде.