Skill di integrazione
Cos'è la FH2 Integration Skill
La FH2 Integration Skill è un pacchetto di conoscenze di dominio progettato per gli assistenti di codifica AI. Una volta installata, ogni volta che presenti un requisito di integrazione di FlightHub 2 al tuo assistente AI, l'assistente risponde secondo una metodologia validata invece di indovinare dalla memoria o inventare interfacce. Supporta i principali assistenti di codifica come Claude Code, Cursor, OpenCode, Trae e Tongyi Lingma.
La Skill copre due flussi di lavoro di integrazione principali — risposta di emergenza DFR e ispezione / pattugliamento — e include un insieme completo di risorse come la base di conoscenze, un'implementazione demo di riferimento e casi di valutazione.
Problemi che risolve
| Senza la Skill | Con la Skill |
|---|---|
| L'AI può inventare endpoint API che non esistono | L'anti-allucinazione è applicata: quando non è sicura, lo dichiara e indica la documentazione ufficiale per la verifica |
| Le interfacce Public Cloud e On-Premises vengono mescolate | Il modello di distribuzione viene confermato per primo e i confini delle API sono rigorosamente separati |
| Le pratiche di invio di emergenza vengono applicate alle ispezioni di routine | Lo scenario viene confermato per primo e i due flussi di lavoro vengono progettati separatamente |
| La documentazione ufficiale è dispersa e difficile da navigare | Tabelle di selezione organizzate per dominio di capacità, più corrispondenza requisiti-endpoint |
| Il codice generato manca di misure di sicurezza | Requisiti minimi integrati per verifica della firma, idempotenza, autorizzazioni e audit |
L'Integration Skill non scrive il tuo codice aziendale al posto tuo. Garantisce che, all'interno del dominio FlightHub 2, l'AI non inventi nulla, non superi i confini e non ometta elementi di sicurezza.
Chi dovrebbe usarla e come
Utenti senza esperienza di sviluppo personalizzato
Obiettivo: comprendere cosa può fare FlightHub 2.
Basta chiedere all'assistente AI in linguaggio semplice. La Skill presenta le capacità attraverso un menu delle capacità, quindi elabora una soluzione adatta al tuo business tramite una conversazione multi-turno.
Domanda di esempio: Vogliamo utilizzare i droni per la sicurezza del campus. Quali capacità può fornire FlightHub 2?
Utenti con una certa esperienza di sviluppo che necessitano di una demo rapida
Obiettivo: far funzionare rapidamente una demo.
Utilizza la demo eseguibile inclusa nella Skill. Inserisci la chiave dell'organizzazione FlightHub 2 per provare il flusso di lavoro completo.
Domanda di esempio: Voglio eseguire rapidamente una demo da mostrare al mio responsabile. Come inizio?
Sviluppatori esperti
Obiettivo: mappare i requisiti su interfacce specifiche e iniziare a scrivere codice.
Fai sì che l'assistente AI mappi i tuoi requisiti su endpoint specifici, quindi inizi la codifica una volta prodotta la tabella di corrispondenza.
Domanda di esempio: Devo integrare il livestreaming. Aiutami a identificare quali endpoint corrispondono e dove sono le lacune.
Installazione e ambiente consigliato
Inserisci la directory scaricata fh2-integration-skill/ nella directory delle skill del tuo assistente di codifica AI, oppure configura il suo contenuto come file di regole a livello di progetto. Non sono richieste dipendenze aggiuntive. Dopo l'installazione, basta porre domande su FlightHub 2 / DFR / ispezione per attivarla automaticamente.
Strumenti di codifica
| Strumento di codifica | Come caricarla |
|---|---|
| Claude Code | Inseriscila in ~/.claude/skills/fh2-integration-skill/ |
| OpenCode | Inseriscila in ~/.config/opencode/skills/fh2-integration-skill/ |
| Cursor | Copia il contenuto di adapters/cursor-rules.md in .cursor/rules/fh2-integration.mdc |
| Trae / Tongyi Lingma | Configurala come regola di progetto o montala come base di conoscenze del progetto |
I percorsi dei file di regole variano tra le versioni degli strumenti; fai riferimento alla documentazione ufficiale di ciascuno strumento. Il principio fondamentale è rendere SKILL.md e references/ una parte persistente del contesto dell'AI.
Modelli consigliati
Questa Skill è un insieme piuttosto lungo di vincoli comportamentali e contenuti della base di conoscenze e richiede forti capacità di comprensione del contesto lungo e di seguire le istruzioni. Sono consigliati i seguenti modelli:
| Modello | Fornitore |
|---|---|
| DeepSeek V4 Pro e versioni successive | DeepSeek |
| Qwen 3.8 Max | Alibaba Cloud |
| Claude Opus 5 | Anthropic |
| GPT-5.6 Sol | OpenAI |
Nota
La capacità del modello non modifica i confini di sicurezza della Skill. Indipendentemente dal modello utilizzato, la Skill applica i vincoli anti-allucinazione e i due gate di conferma. Se un modello salta frequentemente le domande di follow-up o inventa endpoint, passa a un modello con capacità più forti di seguire le istruzioni.
Facoltativo: montare l'OpenAPI MCP
Se il tuo ambiente fornisce l'MCP OpenAPI di FlightHub 2 / Apifox, questa Skill preferisce leggere endpoint e schema reali tramite l'MCP per completare la corrispondenza dei requisiti e la modifica del codice, invece di richiedere di navigare tu stesso nella documentazione. Senza un MCP, ripiega sui link alla documentazione ufficiale. In nessun caso inventa endpoint.
Meccanismo principale: due gate
Questo è il design più importante di questa Skill. Prima di fornire qualsiasi raccomandazione API, l'assistente AI deve superare in sequenza due gate di conferma.
Primo gate · Gate della distribuzione
Conferma il modello di distribuzione di FlightHub 2: Public Cloud / On-Premises / AIO
L'ambito delle API e il modello di autenticazione differiscono tra i modelli di distribuzione, quindi questo passaggio determina i confini per la successiva selezione delle interfacce.
Secondo gate · Gate dello scenario
Conferma la categoria di flusso di lavoro da integrare: risposta di emergenza DFR / ispezione e pattugliamento / entrambe
Scenari diversi differiscono significativamente nella selezione delle interfacce, nel flusso dei dati e nell'attenzione alla sicurezza.
Dopo aver superato entrambi i gate
Solo allora la Skill inizia a fornire: progettazione dell'architettura → mappatura delle interfacce → piano di implementazione → misure di sicurezza → piano di test.
Perché l'AI "chiede prima a te" invece di rispondere direttamente
Questo è intenzionale. Modelli di distribuzione diversi espongono API completamente diverse e scenari diversi richiedono interfacce diverse. È esplicitamente vietato alla Skill dedurre il modello di distribuzione da indizi come il formato del token, l'URL, il dominio o la regione: il costo di indovinare male è una soluzione che non funziona.
Differenze tra i due scenari
| Dimensione | DFR / Emergenza | Ispezione / Pattugliamento |
|---|---|---|
| Origine del trigger | Allarmi esterni, gestione chiamate CAD | Piani, programmi, cicli |
| Tempestività | Risposta di emergenza a livello di secondi | Operazione periodica regolare |
| Interfacce principali | Flusso di lavoro di invio automatico | Wayline + attività pianificate |
| Focus del flusso di dati | Livestream in tempo reale, presa in carico umana | Acquisizione → analisi → condivisione |
| Post-elaborazione | Gestione sul posto, archiviazione delle prove | Riconoscimento dei difetti AI / VLM, ricostruzione 3D |
Ambito delle capacità
DFR / Risposta di emergenza
- Sistemi CAD e allarmi → middleware di invio di FlightHub 2
- Integrazione del livestream dei droni nelle visualizzazioni VMS / sala di controllo
- Integrazione della telemetria nelle piattaforme GIS / PSIM di consapevolezza situazionale
- Pipeline di archiviazione di file multimediali e prove
Ispezione / Pattugliamento
- Caricamento delle wayline, sincronizzazione nella libreria wayline di FlightHub 2 e invio di attività pianificate
- File multimediali di ispezione → analisi dei difetti AI / VLM → piattaforme di terze parti
- Sincronizzazione dei risultati di ricostruzione 3D / nuvole di punti
Capacità comuni
- Ricezione e gestione dei callback dell'Event API
- Selezione delle interfacce tra FlightHub Sync / OpenAPI / MQTT Bridge
- Verifica dei confini API tra Public Cloud e On-Premises
- Integrazione delle capacità di FlightHub 2 in una piattaforma esistente (progettazione del livello adapter)
- Piani di implementazione, piani di test e misure di sicurezza
Come formulare le domande
Non è richiesta una sintassi speciale; basta descrivere normalmente i tuoi requisiti. Gli esempi seguenti possono essere riutilizzati direttamente:
Consulenza sulle capacità:
Vogliamo usare i droni per l'ispezione delle sottostazioni. Quali capacità può fornire FlightHub 2? Aiutami a mettere insieme una soluzione.
Progettazione dell'integrazione DFR:
Utilizziamo FlightHub 2 Public Cloud. Aiutami a progettare un middleware che vada dagli allarmi CAD all'invio.
Progettazione dell'integrazione per ispezione:
Siamo su una distribuzione On-Premises. Progetta un middleware di invio attività per l'ispezione termica programmata di una sottostazione.
Integrazione con un sistema esistente:
Disponiamo già di una piattaforma di gestione e manutenzione e vogliamo portarvi le capacità di FlightHub 2, invece di distribuire un altro sistema autonomo.
Mappatura delle interfacce:
Devo integrare il livestreaming. Aiutami a identificare quali endpoint corrispondono e a produrre una tabella di corrispondenza requisiti-endpoint.
Consiglio per le domande
Se conosci già il tuo modello di distribuzione e il tuo scenario, comunicali nella prima frase (ad esempio, "Siamo On-Premises, facciamo ispezione"). Questo ti consente di saltare le domande di follow-up dei due gate e passare direttamente alla progettazione della soluzione.
Demo inclusa
La Skill include un'implementazione di riferimento eseguibile di integrazione con la Public Cloud di FlightHub 2, situata in examples/dfr-public-cloud-demo/.
| Pagina | Funzione | Capacità corrispondente |
|---|---|---|
| Mappa del progetto | Seleziona un obiettivo e invia | Flusso di lavoro di invio automatico |
| Informazioni MQTT | Sottoscrivi la telemetria dei droni | Inoltro della telemetria |
| Wayline di ispezione | Carica le wayline e sincronizzale nella libreria wayline di FlightHub 2 | Bucket esterno FlightHub Sync |
| Informazioni Event API | Ricevi e visualizza i messaggi di callback | Event API |
| Bucket S3 | Gestione di file multimediali e prove | Storage di oggetti |
| Impostazioni di configurazione | Inserisci tutti i parametri di connessione | — |
Guida rapida
Backend:
cd examples/dfr-public-cloud-demo/backend
npm install && npm start # 默认 http://localhost:3000
Frontend (in un terminale separato):
cd examples/dfr-public-cloud-demo/frontend
npm install && npm run serve
Per i passaggi dettagliati, consulta QUICKSTART.md nella directory della demo. Per la distribuzione nel cloud, consulta deploy/README.md.
L'invio reale può essere provato localmente
Finché hai una chiave dell'organizzazione FlightHub 2, il tuo
localhostlocale può emettere comandi di invio reali — non sono richiesti server cloud, IP pubblico o tunneling intranet. L'invio è una richiesta puramente in uscita (browser → backend locale → FlightHub Cloud) e attraversa il NAT senza difficoltà. Questo è il percorso più rapido da "leggere la documentazione" a "vedere il Dock aprire il coperchio".
Riferimento per la disponibilità locale
| Funzione | Direzione del traffico | Disponibile esclusivamente in locale |
|---|---|---|
| Invio | Tu → FlightHub Cloud | ✅ Disponibile |
| Callback Event API | FlightHub Cloud → Tu | ❌ Richiede un punto di ingresso pubblico |
| Telemetria MQTT | FlightHub Cloud → il tuo broker | ❌ Richiede un punto di ingresso pubblico |
| Sincronizzazione wayline | FlightHub Cloud → il tuo bucket S3 | ❌ Richiede un punto di ingresso pubblico |
Le ultime tre richiedono che FlightHub 2 avvii connessioni verso la tua macchina, ciò che può essere abilitato con strumenti di tunneling intranet come ngrok o cpolar.
⚠️ L'invio pilota apparecchiature reali
Questa non è una simulazione — il Dock aprirà effettivamente il coperchio e il drone decollerà. Prima di emettere un comando, conferma la conformità dello spazio aereo e la supervisione sul posto e usa un Dock di test quando possibile.
Preparazione prima della prova
- Chiave dell'organizzazione: FlightHub 2 → La mia organizzazione → Impostazioni dell'organizzazione → OpenAPI → copia la chiave
- UUID del progetto: ottienilo chiamando l'interfaccia "Get project list under an organization"
- (Facoltativo) MinIO / S3, broker MQTT, server di streaming
⚠️ La demo ha scopo didattico, non è di livello produttivo
Per ridurre la curva di apprendimento, la demo omette deliberatamente alcuni elementi essenziali di produzione (come la verifica della firma dell'Event API e l'archiviazione nel database). Usarla direttamente in produzione non è sicuro. Assicurati di leggere
LIMITATIONS.mdnella directory della demo, che elenca tutte le limitazioni note e una checklist di preparazione alla produzione.
Informazioni sulle mappe
La demo seleziona automaticamente una mappa di base in base alla lingua del browser (Amap per gli utenti cinesi, Google per gli altri). Tutte le mappe di base presentano un avviso di offset del sistema di coordinate — la posizione sulla mappa non è la posizione di volo reale del drone; usa la posizione del Dock come riferimento. Inoltre, i tile Google utilizzati dalla demo provengono da un'interfaccia non ufficiale e sono solo a scopo dimostrativo; gli ambienti di produzione devono passare all'API ufficiale.
Confini di sicurezza
La Skill include un insieme di vincoli obbligatori. Comprenderli ti aiuta a giudicare meglio l'affidabilità dell'output dell'AI.
Situazioni in cui l'AI si ferma e chiede
| Condizione di attivazione | Cosa devi confermare |
|---|---|
| Modello di distribuzione sconosciuto | Public Cloud / On-Premises / AIO |
| Modalità di autenticazione poco chiara | Token / OAuth / SSO e quali valori sono segnaposto |
| Coinvolge controllo di volo, invio, payload o configurazione del dispositivo | Ambiente autorizzato, intervento umano, percorso di revisione della sicurezza |
| Operare su un sistema cliente reale | Autorizzazione esplicita e ambiente di destinazione |
| Endpoint non confermato nella documentazione | Verifica rispetto alla documentazione ufficiale |
Cosa non farà mai
- Inventare endpoint, campi di richiesta, tipi di eventi o topic MQTT
- Mescolare API Public Cloud e On-Premises
- Consigliare capacità solo-On-Premises per la Public Cloud
- Trattare i risultati di riconoscimento AI come base direttamente utilizzabile per decisioni di risposta
- Omettere vincoli di sicurezza del volo come human-in-the-loop e geofencing
Se l'AI dice "non posso confermare questa capacità"
Non è una mancanza di capacità — è progettato così. Rispetto a inventare un endpoint che sembra ragionevole ma non funziona, dichiarare chiaramente l'incertezza e indicare la documentazione ufficiale è più prezioso per te.
Struttura della directory
fh2-integration-skill/
├── SKILL.md Skill entry: workflow, checkpoints, output templates
├── README.md / README.zh-CN.md Project overview (English and Chinese)
├── references/ Knowledge base (12 documents + Chinese reading guide)
│ ├── README.zh-CN.md Chinese reading guide index; recommended starting point
│ ├── api-guardrails.md Security baseline and anti-hallucination rules (highest priority)
│ ├── capability-overview.md Capability overview menu (for non-developers)
│ ├── scenario-dfr-vs-inspection.md Scenario decision
│ ├── dfr-integration-architecture.md DFR architecture and interface selection
│ ├── inspection-integration-architecture.md Inspection architecture and interface selection
│ ├── integrate-with-existing-system.md Integrating with an existing platform
│ ├── middleware-patterns.md 9 middleware design patterns
│ ├── demo-localization.md Multi-language and localization
│ └── ... Deployment boundaries, API capability panorama, source provenance
├── adapters/ Claude Code / Cursor adaptation guides
├── evals/ 14 quality evaluation cases
└── examples/
└── dfr-public-cloud-demo/ Runnable reference implementation
Per saperne di più sulla base di conoscenze, apri
references/README.zh-CN.md, che spiega cosa copre ogni file e quando viene utilizzato.
FAQ
D: Perché l'AI chiede sempre prima delle domande invece di rispondere direttamente?
Perché il modello di distribuzione e lo scenario fondamentalmente cambiano quali interfacce sono disponibili. Questo è un design centrale della Skill, non verbosità. Puoi comunicare entrambi i punti nella tua prima frase per saltare le domande di follow-up.
D: I file di conoscenza nella Skill sono in inglese. Possono essere tradotti?
I documenti destinati agli esseri umani (README, guide all'uso, runbook di valutazione, documentazione della demo) forniscono tutti versioni cinesi. SKILL.md e references/ sono file di vincoli comportamentali letti dall'AI e sono intenzionalmente mantenuti in inglese — le istruzioni in inglese producono una maggiore precisione di aderenza ed evitano regole in conflitto causate dalla deriva di traduzione. Se devi comprendere un file specifico, basta chiedere all'AI di spiegartelo in cinese.
D: Gli endpoint forniti dall'AI possono essere usati direttamente?
Non direttamente in produzione. La Skill segna quale contenuto necessita di verifica. Conferma sempre il corpo della richiesta esatto, i campi della risposta e i requisiti di autorizzazione rispetto alla documentazione ufficiale Apifox prima di andare in produzione.
D: La demo può essere adattata al nostro sistema?
Sì, ma si consiglia di trattarla come uno scheletro di livello adapter piuttosto che come un prodotto finito. Fai riferimento a ARCHITECTURE.md nella directory della demo, che mappa ogni modulo sulla base di conoscenze ed elenca gli elementi richiesti per passare dalla dimostrazione alla produzione.
D: Questa Skill può essere utilizzata per distribuzioni On-Premises?
Sì. La Skill copre sia Public Cloud sia On-Premises / AIO e distingue rigorosamente i loro confini di interfaccia. Nota, tuttavia, che la demo inclusa è scritta per la Public Cloud. Le distribuzioni On-Premises hanno una superficie di interfaccia più ampia e possono utilizzare metodi di autenticazione diversi, quindi non copiare direttamente il codice della demo.
L'FH2 Integration Skill è uno strumento di assistenza alla progettazione dell'integrazione. Non può sostituire la documentazione ufficiale DJI, la revisione di sicurezza del cliente, la revisione legale, l'approvazione aeronautica o la validazione in produzione.