Skill de integração
O que é a FH2 Integration Skill
A FH2 Integration Skill é um pacote de conhecimento de domínio desenvolvido para assistentes de programação com IA. Depois de instalada, sempre que você apresentar ao seu assistente de IA um requisito de integração com o FlightHub 2, o assistente responderá de acordo com uma metodologia validada, em vez de deduzir a partir da memória ou inventar interfaces. Há suporte para os principais assistentes de programação, como Claude Code, Cursor, OpenCode, Trae e Tongyi Lingma.
A Skill abrange dois fluxos de trabalho de integração predominantes — resposta a emergências DFR e inspeção / patrulhamento — e inclui um conjunto completo de recursos, como a base de conhecimento, uma implementação de demonstração de referência e casos de avaliação.
Problemas que ela resolve
| Sem a Skill | Com a Skill |
|---|---|
| A IA pode inventar endpoints de API que não existem | A prevenção de alucinações é aplicada: em caso de incerteza, ela declara isso e indica a documentação oficial para verificação |
| As interfaces de nuvem pública e de implantação local se confundem | O modelo de implantação é confirmado primeiro e os limites das APIs são estritamente separados |
| Práticas de despacho de emergência são aplicadas a inspeções de rotina | O cenário é confirmado primeiro e os dois fluxos de trabalho são projetados separadamente |
| A documentação oficial está dispersa e é difícil de navegar | Tabelas de seleção organizadas por domínio de capacidade, além da correspondência entre requisitos e endpoints |
| O código gerado não possui salvaguardas de segurança | Requisitos mínimos integrados de verificação de assinatura, idempotência, permissões e auditoria |
A Integration Skill não escreve o código de negócio por você. Ela garante que, dentro do domínio do FlightHub 2, a IA não invente informações, não ultrapasse limites e não omita itens de segurança.
Quem deve usar e como
Usuários sem experiência em desenvolvimento personalizado
Objetivo: entender o que o FlightHub 2 pode fazer.
Basta perguntar ao assistente de IA em linguagem natural. A Skill apresenta as capacidades por meio de um menu de recursos e, em seguida, elabora uma solução adequada ao seu negócio por meio de uma conversa em várias etapas.
Exemplo de pergunta: Queremos usar drones para segurança de campus. Quais capacidades o FlightHub 2 pode oferecer?
Usuários com alguma experiência em desenvolvimento que precisam de uma demonstração rápida
Objetivo: colocar uma demonstração em funcionamento rapidamente.
Use a demonstração executável que acompanha a Skill. Insira a chave da sua organização do FlightHub 2 para experimentar o fluxo de trabalho completo.
Exemplo de pergunta: Quero executar rapidamente uma demonstração para mostrar ao meu gestor. Como começo?
Desenvolvedores experientes
Objetivo: mapear os requisitos para interfaces específicas e começar a programar.
Peça ao assistente de IA para mapear seus requisitos para endpoints específicos e comece a programar assim que a tabela de correspondência for gerada.
Exemplo de pergunta: Preciso integrar transmissão ao vivo. Ajude-me a identificar quais endpoints correspondem e onde estão as lacunas.
Instalação e ambiente recomendado
Coloque o diretório fh2-integration-skill/ baixado no diretório de skills do seu assistente de programação com IA ou configure o conteúdo como arquivos de regras no nível do projeto. Não são necessárias dependências adicionais. Após a instalação, basta fazer perguntas sobre FlightHub 2 / DFR / inspeção para acioná-la automaticamente.
Ferramentas de programação
| Ferramenta de programação | Como carregar |
|---|---|
| Claude Code | Coloque em ~/.claude/skills/fh2-integration-skill/ |
| OpenCode | Coloque em ~/.config/opencode/skills/fh2-integration-skill/ |
| Cursor | Copie o conteúdo de adapters/cursor-rules.md para .cursor/rules/fh2-integration.mdc |
| Trae / Tongyi Lingma | Configure como regra de projeto ou monte como base de conhecimento do projeto |
Os caminhos dos arquivos de regras variam conforme a versão da ferramenta; consulte a documentação oficial de cada ferramenta. O princípio central é tornar SKILL.md e references/ uma parte persistente do contexto da IA.
Modelos recomendados
Esta Skill é um conjunto bastante extenso de restrições comportamentais e conteúdo de base de conhecimento, exigindo forte capacidade de compreensão de contexto longo e de seguimento de instruções. Os seguintes modelos são recomendados:
| Modelo | Fornecedor |
|---|---|
| DeepSeek V4 Pro ou superior | DeepSeek |
| Qwen 3.8 Max | Alibaba Cloud |
| Claude Opus 5 | Anthropic |
| GPT-5.6 Sol | OpenAI |
Observação
A capacidade do modelo não altera os limites de segurança da Skill. Independentemente do modelo utilizado, a Skill aplica restrições contra alucinações e as duas etapas de confirmação. Se um modelo frequentemente ignorar as perguntas de acompanhamento ou inventar endpoints, mude para um modelo com maior capacidade de seguir instruções.
Opcional: montar o OpenAPI MCP
Se o seu ambiente disponibilizar o OpenAPI MCP do FlightHub 2 / Apifox, esta Skill dá preferência à leitura de endpoints e esquemas reais por meio do MCP para concluir a correspondência de requisitos e a modificação de código, em vez de exigir que você mesmo consulte a documentação. Sem um MCP, ela recorre aos links da documentação oficial. Em nenhum dos casos ela inventa endpoints.
Mecanismo central: duas etapas de verificação
Este é o aspecto mais importante do design desta Skill. Antes de fornecer qualquer recomendação de API, o assistente de IA deve passar por duas etapas de confirmação em sequência.
Etapa um · Verificação de implantação
Confirme o modelo de implantação do FlightHub 2: nuvem pública / implantação local / AIO
O escopo das APIs e o modelo de autenticação diferem entre os modelos de implantação, portanto esta etapa determina os limites para a seleção posterior de interfaces.
Etapa dois · Verificação de cenário
Confirme a categoria do fluxo de trabalho a ser integrado: resposta a emergências DFR / inspeção e patrulhamento / ambos
Cenários diferentes apresentam diferenças significativas na seleção de interfaces, no fluxo de dados e no foco de segurança.
Após passar pelas duas etapas
Somente então a Skill começa a fornecer: projeto de arquitetura → mapeamento de interfaces → plano de implementação → salvaguardas de segurança → plano de testes.
Por que a IA "pergunta primeiro" em vez de responder diretamente
Isso é intencional. Modelos de implantação diferentes expõem APIs completamente distintas, e cenários diferentes exigem interfaces diferentes. A Skill é expressamente proibida de inferir o modelo de implantação a partir de indícios como formato do token, URL, domínio ou região — o custo de errar é uma solução que não funciona.
Diferenças entre os dois cenários
| Dimensão | DFR / Emergência | Inspeção / Patrulhamento |
|---|---|---|
| Origem do acionamento | Alarmes externos, atendimento de chamadas CAD | Planos, agendamentos, ciclos |
| Tempestividade | Resposta de emergência em nível de segundos | Operação periódica regular |
| Interfaces principais | Fluxo de despacho automático | Rotas de voo + tarefas planejadas |
| Foco do fluxo de dados | Transmissão ao vivo em tempo real, assunção de controle por humano | Captura → análise → compartilhamento |
| Pós-processamento | Tratamento no local, arquivamento de evidências | Reconhecimento de defeitos por IA / VLM, reconstrução 3D |
Escopo de capacidades
DFR / Resposta a emergências
- Sistemas CAD e de alarme → middleware de despacho do FlightHub 2
- Integração da transmissão ao vivo do drone em VMS / telas do centro de comando
- Integração de telemetria em plataformas de consciência situacional GIS / PSIM
- Pipelines de arquivamento de mídia e evidências
Inspeção / Patrulhamento
- Upload de rotas de voo, sincronização com a biblioteca de rotas do FlightHub 2 e despacho de tarefas planejadas
- Mídia de inspeção → análise de defeitos por IA / VLM → plataformas de terceiros
- Sincronização de resultados de reconstrução 3D / nuvem de pontos
Capacidades comuns
- Recepção e tratamento de callbacks da Event API
- Seleção de interface entre FlightHub Sync / OpenAPI / MQTT Bridge
- Verificação de limites de API entre nuvem pública e implantação local
- Integração das capacidades do FlightHub 2 em uma plataforma existente (design da camada de adaptação)
- Planos de implementação, planos de teste e salvaguardas de segurança
Como fazer perguntas
Nenhuma sintaxe especial é necessária; basta descrever seus requisitos normalmente. Os exemplos a seguir podem ser reutilizados diretamente:
Consulta de capacidades:
Queremos usar drones para inspeção de subestações. Quais capacidades o FlightHub 2 pode oferecer? Ajude-me a montar uma solução.
Projeto de integração DFR:
Usamos o FlightHub 2 em nuvem pública. Ajude-me a projetar um middleware que vá dos alarmes CAD até o despacho.
Projeto de integração de inspeção:
Estamos em uma implantação local. Projete um middleware de despacho de tarefas para inspeção térmica programada de uma subestação.
Integração com um sistema existente:
Já temos uma plataforma de O&M e queremos incorporar nela as capacidades do FlightHub 2, em vez de implantar outro sistema independente.
Mapeamento de interfaces:
Preciso integrar transmissão ao vivo. Ajude-me a identificar quais endpoints correspondem e a gerar uma tabela de correspondência entre requisitos e endpoints.
Dica para perguntar
Se você já conhece seu modelo de implantação e seu cenário, informe-os na primeira frase (por exemplo, "Estamos em implantação local, fazendo inspeção"). Isso permite pular as perguntas de acompanhamento das duas etapas e ir direto ao projeto da solução.
Demonstração incluída
A Skill inclui uma implementação de referência executável de integração com a nuvem pública do FlightHub 2, localizada em examples/dfr-public-cloud-demo/.
| Página | Função | Capacidade correspondente |
|---|---|---|
| Mapa do projeto | Selecionar um alvo e despachar | Fluxo de despacho automático |
| Informações MQTT | Assinar a telemetria do drone | Encaminhamento de telemetria |
| Rotas de inspeção | Fazer upload de rotas e sincronizar com a biblioteca de rotas do FlightHub 2 | Bucket externo do FlightHub Sync |
| Informações da Event API | Receber e exibir mensagens de callback | Event API |
| Bucket S3 | Gerenciamento de arquivos de mídia e evidências | Armazenamento de objetos |
| Definições de configuração | Inserir todos os parâmetros de conexão | — |
Início rápido
Backend:
cd examples/dfr-public-cloud-demo/backend
npm install && npm start # 默认 http://localhost:3000
Frontend (em um terminal separado):
cd examples/dfr-public-cloud-demo/frontend
npm install && npm run serve
Para etapas detalhadas, consulte QUICKSTART.md no diretório da demonstração. Para implantação na nuvem, consulte deploy/README.md.
O despacho real pode ser testado localmente
Desde que você tenha uma chave de organização do FlightHub 2, o seu
localhostlocal pode emitir comandos de despacho reais — sem servidor na nuvem, sem IP público e sem túnel de intranet. O despacho é uma solicitação puramente de saída (navegador → backend local → FlightHub Cloud) e atravessa NAT sem dificuldade. Este é o caminho mais rápido de "ler a documentação" até "ver o Dock abrir a tampa".
Referência de disponibilidade local
| Função | Direção do tráfego | Disponível apenas localmente |
|---|---|---|
| Despacho | Você → FlightHub Cloud | ✅ Disponível |
| Callback da Event API | FlightHub Cloud → Você | ❌ Requer um ponto de entrada público |
| Telemetria MQTT | FlightHub Cloud → seu broker | ❌ Requer um ponto de entrada público |
| Sincronização de rotas de voo | FlightHub Cloud → seu bucket S3 | ❌ Requer um ponto de entrada público |
Os três últimos exigem que o FlightHub 2 inicie conexões em direção à sua máquina, o que pode ser viabilizado com ferramentas de túnel de intranet como ngrok ou cpolar.
⚠️ O despacho aciona equipamentos reais
Isto não é uma simulação — o Dock realmente abrirá a tampa e o drone decolará. Antes de emitir um comando, confirme a conformidade do espaço aéreo e a supervisão no local e utilize um Dock de teste sempre que possível.
Preparação antes do teste
- Chave da organização: FlightHub 2 → Minha organização → Configurações da organização → OpenAPI → copie a chave
- UUID do projeto: obtenha-o chamando a interface "Obter a lista de projetos de uma organização"
- (Opcional) MinIO / S3, broker MQTT, servidor de streaming
⚠️ A demonstração é didática, não de nível de produção
Para reduzir a curva de aprendizado, a demonstração omite deliberadamente certos elementos essenciais de produção (como a verificação de assinatura da Event API e o armazenamento em banco de dados). Usá-la diretamente em produção não é seguro. Leia atentamente o
LIMITATIONS.mdno diretório da demonstração, que lista todas as limitações conhecidas e uma lista de verificação de prontidão para produção.
Sobre os mapas
A demonstração seleciona automaticamente um mapa base de acordo com o idioma do navegador (Amap para usuários em chinês, Google para os demais). Todos os mapas base trazem um aviso de deslocamento do sistema de coordenadas — a posição no mapa não é a posição real de voo do drone; use a posição do Dock como referência. Além disso, os tiles do Google usados pela demonstração provêm de uma interface não oficial e servem apenas para demonstração; ambientes de produção devem migrar para a API oficial.
Limites de segurança
A Skill inclui um conjunto de restrições obrigatórias. Compreendê-las ajuda você a julgar melhor a confiabilidade da saída da IA.
Situações em que a IA vai parar e perguntar
| Condição de acionamento | O que você precisa confirmar |
|---|---|
| Modelo de implantação desconhecido | Nuvem pública / implantação local / AIO |
| Modo de autenticação não esclarecido | Token / OAuth / SSO e quais valores são espaços reservados |
| Envolve controle de voo, despacho, cargas úteis ou configuração de dispositivos | Ambiente autorizado, intervenção humana, caminho de revisão de segurança |
| Operação de um sistema real do cliente | Autorização explícita e ambiente de destino |
| Endpoint não confirmado na documentação | Verificar na documentação oficial |
O que ela nunca fará
- Inventar endpoints, campos de requisição, tipos de evento ou tópicos MQTT
- Misturar APIs de nuvem pública e de implantação local
- Recomendar para a nuvem pública capacidades exclusivas da implantação local
- Tratar resultados de reconhecimento por IA como base diretamente acionável para decisões de resposta
- Omitir restrições de segurança de voo, como human-in-the-loop e geofencing
Se a IA disser "não consigo confirmar esta capacidade"
Isso não é falta de capacidade — é intencional. Em comparação com inventar um endpoint que parece razoável, mas não funciona, declarar claramente a incerteza e apontar para a documentação oficial é mais valioso para você.
Estrutura de diretórios
fh2-integration-skill/
├── SKILL.md Entrada da Skill: fluxo de trabalho, pontos de verificação, modelos de saída
├── README.md / README.zh-CN.md Visão geral do projeto (inglês e chinês)
├── references/ Base de conhecimento (12 documentos + guia de leitura em chinês)
│ ├── README.zh-CN.md Índice do guia de leitura em chinês; ponto de partida recomendado
│ ├── api-guardrails.md Linha de base de segurança e regras antialucinação (prioridade máxima)
│ ├── capability-overview.md Menu geral de capacidades (para não desenvolvedores)
│ ├── scenario-dfr-vs-inspection.md Decisão de cenário
│ ├── dfr-integration-architecture.md Arquitetura DFR e seleção de interfaces
│ ├── inspection-integration-architecture.md Arquitetura de inspeção e seleção de interfaces
│ ├── integrate-with-existing-system.md Integração com uma plataforma existente
│ ├── middleware-patterns.md 9 padrões de design de middleware
│ ├── demo-localization.md Multi-idioma e localização
│ └── ... Limites de implantação, panorama de capacidades da API, proveniência das fontes
├── adapters/ Guias de adaptação para Claude Code / Cursor
├── evals/ 14 casos de avaliação de qualidade
└── examples/
└── dfr-public-cloud-demo/ Implementação de referência executável
Para saber mais sobre a base de conhecimento, abra
references/README.zh-CN.md, que explica o que cada arquivo abrange e quando é utilizado.
Perguntas frequentes
P: Por que a IA sempre faz perguntas primeiro, em vez de responder diretamente?
Porque o modelo de implantação e o cenário alteram fundamentalmente quais interfaces estão disponíveis. Este é um design central da Skill, não prolixidade. Você pode informar ambos os pontos na primeira frase para pular as perguntas de acompanhamento.
P: Os arquivos de conhecimento da Skill estão em inglês. Podem ser traduzidos?
Os documentos destinados a pessoas (README, guias de uso, runbook de avaliação, documentação da demonstração) possuem versões em chinês. SKILL.md e references/ são arquivos de restrição comportamental lidos pela IA e são mantidos intencionalmente em inglês — instruções em inglês proporcionam maior precisão de aderência e evitam regras conflitantes causadas por desvios de tradução. Se você precisar entender um arquivo específico, basta pedir à IA que o explique para você em chinês.
P: Os endpoints fornecidos pela IA podem ser usados diretamente?
Não diretamente em produção. A Skill indica quais conteúdos precisam de verificação. Sempre confirme o corpo exato da requisição, os campos de resposta e os requisitos de permissão na documentação oficial do Apifox antes de entrar em produção.
P: A demonstração pode ser adaptada para o nosso próprio sistema?
Sim, mas recomenda-se tratá-la como um esqueleto da camada de adaptação, e não como um produto acabado. Consulte o ARCHITECTURE.md no diretório da demonstração, que mapeia cada módulo para a base de conhecimento e lista os itens necessários para passar da demonstração à produção.
P: Esta Skill pode ser usada em implantações locais?
Sim. A Skill abrange tanto a nuvem pública quanto a implantação local / AIO e distingue rigorosamente os limites de suas interfaces. Observe, no entanto, que a demonstração incluída foi escrita para a nuvem pública. As implantações locais possuem uma superfície de interfaces mais ampla e podem usar métodos de autenticação diferentes, portanto não copie o código da demonstração diretamente.
A FH2 Integration Skill é uma ferramenta de apoio ao projeto de integração. Ela não substitui a documentação oficial da DJI, a revisão de segurança do cliente, a revisão jurídica, a aprovação aeronáutica ou a validação em produção.