Skill de integración
- Qué es el FH2 Integration Skill
- Problemas que resuelve
- A quién está dirigido y cómo utilizarlo
- Instalación y entorno recomendado
- Mecanismo central: dos puntos de control
- Alcance de las capacidades
- Cómo formular las preguntas
- Demostración incluida
- Límites de seguridad
- Estructura de directorios
- Preguntas frecuentes
Qué es el FH2 Integration Skill
El FH2 Integration Skill es un paquete de conocimiento especializado diseñado para asistentes de codificación con IA. Una vez instalado, cada vez que plantee un requisito de integración de FlightHub 2 a su asistente de IA, este responderá conforme a una metodología validada, en lugar de adivinar de memoria o inventar interfaces. Es compatible con los principales asistentes de codificación, como Claude Code, Cursor, OpenCode, Trae y Tongyi Lingma.
El Skill abarca dos flujos de integración habituales — respuesta de emergencia DFR e inspección / patrullaje — e incluye un conjunto completo de recursos: base de conocimiento, una implementación de demostración de referencia y casos de evaluación.
Problemas que resuelve
| Sin el Skill | Con el Skill |
|---|---|
| La IA puede inventar endpoints de API que no existen | Se aplica la prevención de alucinaciones: ante la incertidumbre, lo indica y remite a la documentación oficial para su verificación |
| Se mezclan las interfaces de nube pública (Public Cloud) y locales (On-Premises) | Primero se confirma el modelo de implementación y los límites de la API se separan estrictamente |
| Las prácticas de despacho de emergencia se aplican a la inspección rutinaria | Primero se confirma el escenario y ambos flujos se diseñan por separado |
| La documentación oficial está dispersa y es difícil de recorrer | Tablas de selección organizadas por ámbito de capacidad, además de la correspondencia entre requisitos y endpoints |
| El código generado carece de mecanismos de protección de seguridad | Requisitos mínimos integrados de verificación de firma, idempotencia, permisos y auditoría |
El Integration Skill no escribe el código de negocio por usted. Garantiza que, dentro del ámbito de FlightHub 2, la IA no invente datos, no traspase los límites y no omita aspectos de seguridad.
A quién está dirigido y cómo utilizarlo
Usuarios sin experiencia en desarrollo personalizado
Objetivo: comprender qué puede hacer FlightHub 2.
Basta con preguntar al asistente de IA en lenguaje natural. El Skill presenta las capacidades mediante un menú de capacidades y, a continuación, elabora una solución adecuada a su negocio a través de una conversación de varios turnos.
Pregunta de ejemplo: Queremos utilizar drones para la seguridad de un campus. ¿Qué capacidades puede proporcionar FlightHub 2?
Usuarios con cierta experiencia en desarrollo que necesitan una demostración rápida
Objetivo: poner en marcha una demostración rápidamente.
Utilice la demostración ejecutable incluida en el Skill. Introduzca la clave de organización de FlightHub 2 para experimentar el flujo completo.
Pregunta de ejemplo: Quiero ejecutar rápidamente una demostración para mostrársela a mi responsable. ¿Cómo empiezo?
Desarrolladores con experiencia
Objetivo: asociar los requisitos a interfaces concretas y comenzar a programar.
Pida al asistente de IA que asocie sus requisitos a endpoints concretos y comience a programar una vez elaborada la tabla de correspondencias.
Pregunta de ejemplo: Necesito integrar la transmisión en directo. Ayúdame a identificar qué endpoints se corresponden y dónde están las carencias.
Instalación y entorno recomendado
Coloque el directorio fh2-integration-skill/ descargado en el directorio de skills de su asistente de codificación con IA, o configure su contenido como archivos de reglas a nivel de proyecto. No se requieren dependencias adicionales. Tras la instalación, basta con formular preguntas sobre FlightHub 2 / DFR / inspección para activarlo automáticamente.
Herramientas de codificación
| Herramienta de codificación | Forma de carga |
|---|---|
| Claude Code | Colocar en ~/.claude/skills/fh2-integration-skill/ |
| OpenCode | Colocar en ~/.config/opencode/skills/fh2-integration-skill/ |
| Cursor | Copiar el contenido de adapters/cursor-rules.md en .cursor/rules/fh2-integration.mdc |
| Trae / Tongyi Lingma | Configurar como regla de proyecto o montar como base de conocimiento del proyecto |
Las rutas de los archivos de reglas varían según la versión de cada herramienta; consulte la documentación oficial correspondiente. El principio fundamental consiste en que SKILL.md y references/ formen parte permanente del contexto de la IA.
Modelos recomendados
Este Skill constituye un conjunto bastante extenso de restricciones de comportamiento y contenidos de base de conocimiento, y requiere una sólida comprensión de contextos largos y una elevada capacidad de seguimiento de instrucciones. Se recomiendan los siguientes modelos:
| Modelo | Proveedor |
|---|---|
| DeepSeek V4 Pro y superiores | DeepSeek |
| Qwen 3.8 Max | Alibaba Cloud |
| Claude Opus 5 | Anthropic |
| GPT-5.6 Sol | OpenAI |
Nota
La capacidad del modelo no altera los límites de seguridad del Skill. Sea cual sea el modelo utilizado, el Skill impone las restricciones de prevención de alucinaciones y los dos puntos de confirmación. Si un modelo omite con frecuencia las preguntas de seguimiento o inventa endpoints, cambie a un modelo con mayor capacidad de seguimiento de instrucciones.
Opcional: montar el MCP de OpenAPI
Si su entorno proporciona el MCP de OpenAPI de FlightHub 2 / Apifox, este Skill da preferencia a la lectura de endpoints y esquemas reales a través del MCP para llevar a cabo la correspondencia de requisitos y la modificación del código, en lugar de exigirle consultar la documentación por su cuenta. Sin MCP, recurre a los enlaces de la documentación oficial. En ninguno de los dos casos inventa endpoints.
Mecanismo central: dos puntos de control
Este es el aspecto de diseño más importante de este Skill. Antes de ofrecer cualquier recomendación de API, el asistente de IA debe superar sucesivamente dos puntos de confirmación.
Punto de control 1 · Implementación
Confirmar el modelo de implementación de FlightHub 2: Public Cloud / On-Premises / AIO
El alcance de la API y el modelo de autenticación difieren según el modelo de implementación, por lo que este paso determina los límites de la posterior selección de interfaces.
Punto de control 2 · Escenario
Confirmar la categoría de flujo que se va a integrar: respuesta de emergencia DFR / inspección y patrullaje / ambas
Los distintos escenarios presentan diferencias considerables en cuanto a selección de interfaces, flujo de datos y prioridades de seguridad.
Tras superar ambos puntos de control
Solo entonces el Skill comienza a proporcionar: diseño de arquitectura → correspondencia de interfaces → plan de implementación → mecanismos de protección de seguridad → plan de pruebas.
Por qué la IA «pregunta primero» en lugar de responder directamente
Es intencionado. Los distintos modelos de implementación exponen API completamente diferentes, y los distintos escenarios requieren interfaces diferentes. Al Skill se le prohíbe expresamente inferir el modelo de implementación a partir de indicios como el formato del token, la URL, el dominio o la región: el coste de una suposición errónea es una solución que no funciona.
Diferencias entre ambos escenarios
| Dimensión | DFR / emergencia | Inspección / patrullaje |
|---|---|---|
| Origen de la activación | Alarmas externas, gestión de llamadas CAD | Planes, calendarios, ciclos |
| Inmediatez | Respuesta de emergencia en segundos | Operación periódica regular |
| Interfaces principales | Flujo de despacho automático | Rutas de vuelo + tareas planificadas |
| Prioridad del flujo de datos | Transmisión en directo en tiempo real, toma de control humana | Captura → análisis → uso compartido |
| Posprocesamiento | Actuación in situ, archivo de pruebas | Reconocimiento de defectos mediante IA / VLM, reconstrucción 3D |
Alcance de las capacidades
DFR / respuesta de emergencia
- Sistemas CAD y de alarma → middleware de despacho de FlightHub 2
- Integración de la transmisión en directo del dron en las pantallas de VMS / centro de mando
- Integración de la telemetría en plataformas de conciencia situacional GIS / PSIM
- Cadenas de archivo de material multimedia y pruebas
Inspección / patrullaje
- Carga de rutas de vuelo, sincronización con la biblioteca de rutas de FlightHub 2 y envío de tareas planificadas
- Material multimedia de inspección → análisis de defectos mediante IA / VLM → plataformas de terceros
- Sincronización de resultados de reconstrucción 3D / nubes de puntos
Capacidades comunes
- Recepción y tratamiento de devoluciones de llamada de la Event API
- Selección de interfaz entre FlightHub Sync / OpenAPI / MQTT Bridge
- Comprobación de los límites de API entre Public Cloud y On-Premises
- Integración de las capacidades de FlightHub 2 en una plataforma existente (diseño de la capa de adaptación)
- Planes de implementación, planes de pruebas y mecanismos de protección de seguridad
Cómo formular las preguntas
No se requiere ninguna sintaxis especial; basta con describir sus requisitos con normalidad. Los siguientes ejemplos pueden reutilizarse directamente:
Consulta sobre capacidades:
Queremos utilizar drones para la inspección de subestaciones eléctricas. ¿Qué capacidades puede proporcionar FlightHub 2? Ayúdame a elaborar una solución.
Diseño de integración DFR:
Utilizamos FlightHub 2 Public Cloud. Ayúdame a diseñar un middleware que abarque desde las alarmas CAD hasta el despacho.
Diseño de integración de inspección:
Contamos con una implementación On-Premises. Diseña un middleware de envío de tareas para la inspección térmica programada de una subestación eléctrica.
Integración con un sistema existente:
Ya disponemos de una plataforma de operación y mantenimiento y queremos incorporar en ella las capacidades de FlightHub 2, en lugar de implementar otro sistema independiente.
Correspondencia de interfaces:
Necesito integrar la transmisión en directo. Ayúdame a identificar qué endpoints se corresponden y elabora una tabla de correspondencias entre requisitos y endpoints.
Consejo para formular preguntas
Si ya conoce su modelo de implementación y su escenario, indíquelos en la primera frase (por ejemplo, «Somos On-Premises y hacemos inspección»). De este modo omitirá las preguntas de seguimiento de ambos puntos de control y pasará directamente al diseño de la solución.
Demostración incluida
El Skill incluye una implementación de referencia ejecutable de la integración con FlightHub 2 Public Cloud, ubicada en examples/dfr-public-cloud-demo/.
| Página | Función | Capacidad correspondiente |
|---|---|---|
| Mapa del proyecto | Seleccionar un objetivo y despachar | Flujo de despacho automático |
| Información MQTT | Suscribirse a la telemetría del dron | Reenvío de telemetría |
| Rutas de inspección | Cargar rutas y sincronizarlas con la biblioteca de rutas de FlightHub 2 | Bucket externo de FlightHub Sync |
| Información de la Event API | Recibir y mostrar mensajes de devolución de llamada | Event API |
| Bucket de S3 | Gestión de archivos multimedia y de pruebas | Almacenamiento de objetos |
| Ajustes de configuración | Introducir todos los parámetros de conexión | — |
Inicio rápido
Backend:
cd examples/dfr-public-cloud-demo/backend
npm install && npm start # 默认 http://localhost:3000
Frontend (en un terminal independiente):
cd examples/dfr-public-cloud-demo/frontend
npm install && npm run serve
Para conocer los pasos detallados, consulte QUICKSTART.md en el directorio de la demostración. Para la implementación en la nube, consulte deploy/README.md.
El despacho real puede probarse en local
Siempre que disponga de una clave de organización de FlightHub 2, su
localhostlocal puede emitir órdenes de despacho reales, sin necesidad de servidor en la nube, IP pública ni túnel de intranet. El despacho es una solicitud puramente saliente (navegador → backend local → FlightHub Cloud) y atraviesa el NAT sin dificultad. Es la vía más rápida para pasar de «leer la documentación» a «ver cómo el Dock abre su cubierta».
Referencia de disponibilidad en local
| Función | Sentido del tráfico | Disponible solo en local |
|---|---|---|
| Despacho | Usted → FlightHub Cloud | ✅ Disponible |
| Devolución de llamada de la Event API | FlightHub Cloud → usted | ❌ Requiere un punto de entrada público |
| Telemetría MQTT | FlightHub Cloud → su broker | ❌ Requiere un punto de entrada público |
| Sincronización de rutas | FlightHub Cloud → su bucket de S3 | ❌ Requiere un punto de entrada público |
Los tres últimos casos requieren que FlightHub 2 inicie conexiones hacia su equipo, lo que puede habilitarse con herramientas de túnel de intranet como ngrok o cpolar.
⚠️ El despacho acciona equipos reales
No se trata de una simulación: el Dock abrirá realmente su cubierta y el dron despegará. Antes de emitir una orden, confirme el cumplimiento del espacio aéreo y la supervisión in situ, y utilice siempre que sea posible un Dock de pruebas.
Preparativos antes de la prueba
- Clave de organización: FlightHub 2 → Mi organización → Configuración de la organización → OpenAPI → copiar la clave
- UUID del proyecto: se obtiene llamando a la interfaz «Obtener la lista de proyectos de una organización»
- (Opcional) MinIO / S3, broker MQTT, servidor de transmisión
⚠️ La demostración tiene carácter didáctico y no es apta para producción
Para reducir la curva de aprendizaje, la demostración omite deliberadamente determinados elementos esenciales en producción (como la verificación de firma de la Event API y el almacenamiento en base de datos). Su uso directo en producción no es seguro. Asegúrese de leer
LIMITATIONS.mden el directorio de la demostración, donde se enumeran todas las limitaciones conocidas y una lista de comprobación de preparación para producción.
Acerca de los mapas
La demostración selecciona automáticamente un mapa base según el idioma del navegador (Amap para usuarios chinos y Google para el resto). Todos los mapas base incluyen una advertencia sobre el desplazamiento del sistema de coordenadas: la posición en el mapa no es la posición real de vuelo del dron; utilice la posición del Dock como referencia. Además, las teselas de Google empleadas por la demostración proceden de una interfaz no oficial y sirven únicamente para fines de demostración; los entornos de producción deben cambiar a la API oficial.
Límites de seguridad
El Skill incorpora un conjunto de restricciones obligatorias. Conocerlas le ayudará a valorar mejor la fiabilidad de los resultados de la IA.
Situaciones en las que la IA se detiene y pregunta
| Condición de activación | Lo que debe confirmar |
|---|---|
| Modelo de implementación desconocido | Public Cloud / On-Premises / AIO |
| Modo de autenticación poco claro | Token / OAuth / SSO, y qué valores son marcadores de posición |
| Afecta al control de vuelo, el despacho, las cargas útiles o la configuración de los dispositivos | Entorno autorizado, intervención humana, ruta de revisión de seguridad |
| Operación de un sistema real de un cliente | Autorización explícita y entorno de destino |
| Endpoint no confirmado en la documentación | Verificación con la documentación oficial |
Lo que nunca hará
- Inventar endpoints, campos de solicitud, tipos de eventos o temas MQTT
- Mezclar las API de Public Cloud y On-Premises
- Recomendar para Public Cloud capacidades exclusivas de On-Premises
- Tratar los resultados del reconocimiento por IA como base directamente aplicable para las decisiones de respuesta
- Omitir restricciones de seguridad de vuelo como la intervención humana en el bucle y el geovallado
Si la IA indica «no puedo confirmar esta capacidad»
No se trata de una falta de capacidad, sino de una decisión de diseño. Frente a la invención de un endpoint aparentemente razonable pero inoperante, resulta más útil para usted que se exprese claramente la incertidumbre y se remita a la documentación oficial.
Estructura de directorios
fh2-integration-skill/
├── SKILL.md Punto de entrada del Skill: flujo, puntos de control, plantillas de salida
├── README.md / README.zh-CN.md Descripción general del proyecto (inglés y chino)
├── references/ Base de conocimiento (12 documentos + guía de lectura en chino)
│ ├── README.zh-CN.md Índice de la guía de lectura en chino; punto de partida recomendado
│ ├── api-guardrails.md Referencia de seguridad y reglas contra las alucinaciones (máxima prioridad)
│ ├── capability-overview.md Menú de descripción de capacidades (para no desarrolladores)
│ ├── scenario-dfr-vs-inspection.md Decisión de escenario
│ ├── dfr-integration-architecture.md Arquitectura DFR y selección de interfaces
│ ├── inspection-integration-architecture.md Arquitectura de inspección y selección de interfaces
│ ├── integrate-with-existing-system.md Integración con una plataforma existente
│ ├── middleware-patterns.md 9 patrones de diseño de middleware
│ ├── demo-localization.md Multilingüismo y localización
│ └── ... Límites de implementación, panorama de capacidades de API, procedencia de las fuentes
├── adapters/ Guías de adaptación para Claude Code / Cursor
├── evals/ 14 casos de evaluación de calidad
└── examples/
└── dfr-public-cloud-demo/ Implementación de referencia ejecutable
Para obtener más información sobre la base de conocimiento, abra
references/README.zh-CN.md, donde se explica qué abarca cada archivo y cuándo se utiliza.
Preguntas frecuentes
P: ¿Por qué la IA siempre pregunta primero en lugar de responder directamente?
Porque el modelo de implementación y el escenario cambian de forma fundamental las interfaces disponibles. Se trata de un elemento central del diseño del Skill, no de verbosidad. Puede indicar ambos aspectos en la primera frase para omitir las preguntas de seguimiento.
P: Los archivos de conocimiento del Skill están en inglés. ¿Se pueden traducir?
Los documentos dirigidos a personas (README, guías de uso, manual de evaluación y documentación de la demostración) disponen todos de versión en chino. SKILL.md y references/ son archivos de restricciones de comportamiento que lee la IA y se mantienen deliberadamente en inglés: las instrucciones en inglés ofrecen una mayor precisión de cumplimiento y evitan reglas contradictorias derivadas de desviaciones de traducción. Si necesita comprender un archivo concreto, basta con pedir a la IA que se lo explique en chino.
P: ¿Pueden utilizarse directamente los endpoints proporcionados por la IA?
No directamente en producción. El Skill señala qué contenidos requieren verificación. Confirme siempre el cuerpo exacto de la solicitud, los campos de respuesta y los requisitos de permisos en la documentación oficial de Apifox antes de pasar a producción.
P: ¿Puede adaptarse la demostración a nuestro propio sistema?
Sí, aunque se recomienda considerarla un esqueleto de capa de adaptación y no un producto acabado. Consulte ARCHITECTURE.md en el directorio de la demostración, donde se asocia cada módulo a la base de conocimiento y se enumeran los elementos necesarios para pasar de la demostración a la producción.
P: ¿Puede utilizarse este Skill en implementaciones On-Premises?
Sí. El Skill abarca tanto Public Cloud como On-Premises / AIO, y distingue estrictamente sus límites de interfaz. No obstante, tenga en cuenta que la demostración incluida está escrita para Public Cloud. Las implementaciones On-Premises presentan un conjunto de interfaces más amplio y pueden emplear métodos de autenticación diferentes, por lo que no debe copiarse directamente el código de la demostración.
El FH2 Integration Skill es una herramienta de asistencia al diseño de integraciones. No puede sustituir a la documentación oficial de DJI, la revisión de seguridad del cliente, la revisión jurídica, la aprobación aeronáutica ni la validación en producción.