Normas de desarrollo de componentes de iPolloWork Video
El resultado debe ser un componente que pueda colocarse en un video, ajustarse mediante formularios compartidos, seguir el tema del proyecto y ser procesado por IA. No cree un editor, panel de parámetros, renderizador o plugin de host separado para un componente.
1. Antes de empezar: Basarse en el convenio de código actual
Lea AGENTS.md y las normas de mantenimiento en la raíz del repositorio de iPolloWork. Primero busque componentes similares y luego decida si extender o crear uno nuevo. Las siguientes rutas son relativas a la raíz del repositorio:
vendor/hyperframes/registry/blocks/world-map/: Referencia para mapas, herencia de temas y datos estructurados.vendor/hyperframes/registry/blocks/metric-signal/: Referencia para visualización de datos y recetas de animación opcionales.vendor/hyperframes/packages/core/src/registry/types.ts: Clasificación de componentes y contrato del manifiesto.vendor/hyperframes/packages/core/src/registry/componentData.ts: Estructuras de datos compartidas y reglas de análisis.vendor/hyperframes/packages/core/schemas/registry-item.json,packages/types/src/hyperframes.ts: Esquemas de registro y contrato de validación del host.vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts: Método de instalación real, integración de temas y variables.
No copie estos esquemas ni cree otro protocolo de datos. Cuando las normas no coincidan con el código, verifique primero el consumidor actual, no use ejemplos antiguos para adivinar la interfaz.
2. Estructura de entrega mínima
Normalmente, solo necesita colocar en vendor/hyperframes/registry/blocks/<slug>/:
registry-item.json # Metadatos, variables, categoría, archivos y declaración de capacidades
<slug>.html # Imagen y animación
Si es realmente necesario, agregue imágenes locales, fuentes, datos o archivos de vista previa; todos los archivos necesarios para la instalación deben declararse en files, con rutas relativas al paquete. Regístrese en el vendor/hyperframes/registry/registry.json existente, no cree un servicio de directorio de componentes separado.
En el producto se denominan "componentes", pero el tipo subyacente debe ser preciso: los mapas, clasificaciones, etc., que tienen lienzo y duración independientes suelen ser hyperframes:block; los fragmentos que se inyectan en una imagen existente son hyperframes:component. Las plantillas de proyecto completo son otro tipo de entrega, no se mezclen.
3. Variables: Pocas y útiles, formularios compartidos
- Declare en
variablesdel manifiestoidestable,labelcomprensible, tipo y valor predeterminado, coherente condata-composition-variablesdel HTML. - Use los tipos existentes
string / number / color / boolean / enum; para números, proporcione un rango razonable; para enumerados, opciones; para texto largo, restricciones de longitud. No agregue tipos de objeto arbitrariamente. - Exponga solo contenido, datos, resaltados y decisiones de diseño necesarias del usuario; no convierta cada valor CSS en un parámetro. Los colores predeterminados provienen del tema, el usuario no debe tener que configurar cada elemento para poder usarlo.
update: livesolo para parámetros que puedan actualizarse instantáneamente; para cambios de estructura o animación, userebuild / reloadsegún el mecanismo existente, la declaración debe ser coherente con el comportamiento real.- Conecte al mecanismo de actualización de variables existente; después de la actualización, el DOM y la animación deben reflejar los nuevos valores y mantener la posición de reproducción actual del host. No cambie solo el texto mientras la línea de tiempo aún apunta al elemento antiguo.
- Use formularios de variables y tablas de datos compartidos, no escriba un nuevo panel para un solo componente. Los campos de control del sistema como
motionCueTimes,motionStyleno se tratan como parámetros de usuario comunes.
4. Datos: Estructura para IA, tabla para usuario
Los componentes de datos como mapas, rutas, gráficos, clasificaciones usan visualComponent.data, declarando columnas, semántica, identificador de fila, límite de filas y enlace. Use los tipos existentes category-value / region-value / point-value / route-value / series-value, eligiendo el que realmente coincida con los datos.
Los datos estándar para IA son:
{
"version": 1,
"kind": "region-value",
"rows": [
{ "region": "China", "value": 96 },
{ "region": "Japón", "value": 77 }
]
}
Los nombres de columna los determina el columns del componente, no todos los componentes usan fijamente region. rowId debe ser estable y único, los números deben mantener el tipo numérico; declare unidades, precisión, resaltado y semántica de reemplazo/cobertura según el contrato existente.
binding.variable debe corresponder a una variable real. El nivel subyacente puede usar la codificación existente json / key-value-list / route-value-list / label-detail-list, pero la capa de adaptación compartida la transforma; no obligue al usuario a escribir comas, dos puntos, etc. No cree otro estado JSON no sincronizado. Para datos inválidos, proporcione mensajes claros, no ignore filas silenciosamente ni genere valores ficticios.
5. Tema y clasificación
- Declare
visualComponent.version: 1,themeMode: inherit, completesurfacessegún capacidades; prefieravideo, no afirme soporte para PPT o web hasta que esté verificado. - Use la clasificación actual
VISUAL_COMPONENT_CATEGORIES, por ejemplo mapasmaps, datosdata, diagramasdiagrams. Para aperturas y cierres, use también ellibrarySectionexistente; no cree otro árbol de clasificación. - Use las variables de tema existentes, por ejemplo
--ipw-color-bg,--ipw-color-surface,--ipw-color-text,--ipw-color-primary,--ipw-color-border,--ipw-font-display,--ipw-font-body,--ipw-card-radius. - Proporcione valores de respaldo predeterminados para vista previa independiente, pero no sobrescriba el tema del host. Después de cambiar el tema, el fondo, el texto, los gráficos, los bordes y las fuentes deben cambiar coordinadamente; los colores semánticos de los datos son una excepción y requieren una justificación clara.
- Mantenga una jerarquía clara, espaciado razonable y legibilidad en chino. Use degradados o efectos de vidrio esmerilado con moderación, no reemplace la expresión de información con efectos especiales.
6. Animación y línea de tiempo
- Por defecto: HTML + CSS + GSAP; prefiera reutilizar gráficos existentes y SVG local. Solo considere Three.js cuando sea necesario un 3D real, no agregue dependencias pesadas para mapas simples.
- Use el nodo raíz de composición, el tamaño, la duración y el mecanismo de instalación existentes; regístrese en la línea de tiempo GSAP pausada de
window.__timelines[compositionId], controlada por HyperFrames para reproducción, pausa y seek. - Los selectores, estados y líneas de tiempo de cada instancia solo afectan a sí mismos. Al reconstruir, limpie las animaciones antiguas sin sobrescribir otras instancias.
- En un momento dado, se debe obtener la misma imagen: no use temporizadores independientes, bucles de reproducción automática, números aleatorios no fijados o animaciones CSS autoejecutadas para contenido clave. Las imágenes reales, el audio y el video siguen el método de sincronización de medios existente.
- La animación sirve al orden de explicación: aparición clara, énfasis, pausa, salida; deje suficiente tiempo de lectura para texto y datos. Evite que todos los componentes tengan la misma entrada, y evite el movimiento continuo solo por ostentación.
- Los componentes normales no deben forzar la adición de
motionRecipe. Solo cuando se necesite que la IA invoque recetas de animación según la narración, use el contrato de recetas existente; los eventos, enlaces de cue y elementos reales deben ser coherentes, la capacidad y las limitaciones de texto deben basarse en datos reales, no fabrique tiempo de voz.
7. Espacio de procesamiento de IA
Use visualComponent.ai.slots para declarar áreas editables estables y agregue data-ipw-ai-slot en las posiciones correspondientes del HTML. instructions debe explicar brevemente el propósito, las reglas de entrada y la estructura que debe conservarse.
La IA puede reemplazar contenido, ajustar el diseño, reducir el mapa y agregar explicaciones al lado, etc.; mantenga los IDs de variables, los enlaces de datos, la herencia de temas y la conexión de la línea de tiempo sin cambios. No obligue a que todo el procesamiento se convierta en parámetros de formulario, ni mantenga otra copia de la imagen para la IA.
El texto externo se trata como texto, no se incrusta en HTML ejecutable; no ejecute scripts en los datos de entrada, no incruste claves secretas. Para recursos como mapas, fuentes, imágenes, conserve la fuente y la licencia; cuando falten materiales, indíquelo claramente, no los reemplace silenciosamente en línea.
8. Aceptación y entrega
- El manifiesto, las variables HTML, los slots de IA, los enlaces de datos y las rutas de instalación son coherentes; pase las validaciones correspondientes del repositorio actual y las pruebas afectadas.
- Instale el componente en el Studio existente; el formulario compartido puede modificar la imagen real, la tabla de datos puede agregar, eliminar y editar filas válidas.
- Verifique los valores predeterminados, los límites, los valores nulos, el texto largo en chino, los datos incorrectos y los dos temas; las múltiples instancias no deben interferir entre sí.
- Verifique la reproducción desde el principio, seek intermedio, arrastre al inicio y seek después de la actualización de parámetros; la imagen y la línea de tiempo deben ser coherentes.
- Exporte un video corto con material real, confirme que la vista previa del navegador y la salida sean coherentes; no se puede aprobar solo con capturas de pantalla.
- Entregue los archivos del componente, los recursos necesarios con su origen, ejemplos de parámetros/datos, resultados de pruebas reales y elementos no verificados. No copie Studio, no modifique el comportamiento de las plantillas existentes, no deje implementaciones alternativas.
Esta norma solo guía el desarrollo de componentes. Publicar en npm, modificar plugins de host, enviar PR o cargar al mercado de componentes requiere seguir los permisos del usuario y los procesos de publicación existentes por separado.