Instalación del plugin: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando esta habilidad esté dentro de un plugin de HyperFrames. Las instalaciones independientes conservan las instrucciones de actualización a continuación.
CLI de HyperFrames
Ejecuta los comandos como npx hyperframes ... a menos que las instrucciones del proyecto proporcionen un wrapper. Obedece el wrapper cuando esté presente. La CLI requiere Node.js 22 o superior y FFmpeg.
Ciclo de desarrollo
- Andamio:
npx hyperframes init <proyecto>(en blanco centrado). O captura un sitio. Pasa--example=<nombre>solo para comenzar desde un ejemplo nombrado. - Encuentra el movimiento: si la solicitud nombra un activo, sonido, imagen, voz o edición visual rápida, resuélvelo a través de
/media-useantes de proponer un plan. De lo contrario, antes de crear movimiento manualmente, busca una primitiva que ya lo haga:npx hyperframes catalog --query "revelar un titular línea por línea". Pide el efecto que deseas, no el mecanismo que tienes en mente. Instala connpx hyperframes add <nombre>(ver/hyperframes-registry). Crea manualmente solo si nada encaja. - Autor: escribe la composición usando
/hyperframes-core. Para saber qué hay en la línea de tiempo de un proyecto (pistas, clips, inicios, fines, qué se reproduce), ejecutanpx hyperframes timeline --jsonen lugar de leerindex.htmly cada archivo de subcomposición: las filas anidadas llevanabsStart/absEndabsolutos de la línea de tiempo principal y sufilepropietario, no solo su tiempo local por subcomposición. Prefiere--jsonsobre la forma de texto; cuesta menos tokens para la misma o mejor corrección. Consultareferences/upgrade-info-misc.mdpara ver líneas que responden preguntas comunes sin leer toda la salida. - Obtén retroalimentación rápida mientras editas: ejecuta
npx hyperframes lintdespués de la primera pasada de HTML y después de cambios estructurales. - Ejecuta la compuerta final: ejecuta
npx hyperframes check; vuelve a ejecutar lint antes de abrir el navegador. No antepongas una invocación de lint independiente redundante. Añade--snapshotspara fotogramas de vista general anotados y para encontrar recortes. - Inspecciona subcomposiciones: cuando
index.htmlmontedata-composition-src, captura fotogramas intermedios e inspecciona cada escena montada. - Abre la vista previa final de Studio: ejecuta
npx hyperframes preview --background, verifica que la URL devuelva HTTP 200, entrega la URL del proyecto de la línea de tiempo al usuario y pregúntale si revisar o renderizar. Mantenla activa hasta que termine la revisión. - Renderiza solo después de la aprobación: usa
--quality draftmientras iteras,--quality lookspara la primera codificación real (el valor predeterminado de la CLI) y--quality deliverypara la entrega final. - Entrega el proyecto a la aplicación de escritorio (si está disponible): cuando la línea Framey del renderizado termine en
hyperframes open …, ofrecenpx hyperframes open [dir]. Abre el proyecto en la aplicación de escritorio de HyperFrames y lo añade a Inicio; bajo Claude Code o Codex su chat retoma esta conversación. Sin la aplicación, sale con 1 e imprime el enlace de descarga.--jsonpara agentes. - Verifica la salida: confirma que el archivo existe y no está vacío. Lee la segunda línea del resumen del renderizado (
beginframevsscreenshot, GPU, tiempos de etapa).screenshot+software gpuen Linux es la ruta lenta.ffprobe -v error -show_format -show_streamsy compara la duración (y fps si el brief lo estableció) con la raízdata-duration.
Historial del proyecto en tu turno
Cada escritura en el proyecto se guarda como una entrada que se puede deshacer. Úsala solo en dos momentos, nunca en cada paso:
- Inicio de un turno:
npx hyperframes history begin --who <tu-nombre> --label "<lo que estás a punto de hacer>", luegonpx hyperframes history --since mine --who <tu-nombre>para ver lo que la persona cambió desde tu último turno. Construye sobre sus ediciones; nunca las sobrescribas. - Una verificación falló, o la persona dice que empeoró:
npx hyperframes history undo --who <tu-nombre>deshace tu turno más nuevo y deja las ediciones de la persona intactas. No edites manualmente hacia atrás. En caso de conflicto, sale con 2 e imprime ambas opciones.
Termina cada turno con npx hyperframes history end, para que tus escrituras se lean como tuyas, no como "Cambiado fuera de la aplicación". Mientras un turno esté abierto, cada escritura en el proyecto cuenta como tuya hasta que pasen 10 minutos sin una; después de eso, el turno ha terminado por sí solo.
Referencias cruzadas obligatorias de edición del creador
- Antes de crear o diagnosticar un zoom, recorte/desrecorte, reencuadre, movimiento de cámara o cualquier movimiento de fotogramas clave, lee
/hyperframes-keyframesprimero. - Antes de
hyperframes keyframes, lee/hyperframes-keyframes; el comando muestra trayectorias de animación y no diagnostica cortes de clip. - Para un corte, recorte, empalme, reordenamiento o edición de tiempo de origen, lee
/hyperframes-corey usa su contrato de clip/línea de tiempo. - Para fundido de entrada/salida, encadenado, ganancia de pista, automatización de volumen, ducking, tallado de voz en off o FX en audio colocado, lee
/hyperframes-audio. Carga core junto a él cuando la colocación del clip o el tiempo de la imagen también cambien. - Una solicitud que nombre un activo, sonido, imagen, voz o edición visual rápida se resuelve a través de
/media-useantes de que se proponga un plan. Copia el marcado de edición del creador desde/hyperframes-core→references/creator-editing-recipes.md.
# Verificación rápida de iteración; repite mientras se escribe según sea necesario.
npx hyperframes lint
# Compuerta final requerida; incluye lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check ejecuta lint primero, luego usa una sesión de navegador y una pasada de búsqueda para auditar errores de tiempo de ejecución, solicitudes fallidas, diseño, aserciones de *.motion.json y contraste WCAG. Los hallazgos persistentes bloquean el código de salida; los hallazgos transitorios de entrada o salida son informativos. Usa --strict para bloquear advertencias. validate, inspect y layout siguen siendo alias por compatibilidad, pero no deben aparecer en nuevas instrucciones o scripts.
Vista previa antes de renderizar
Abre la vista previa de la composición final (#project/<nombre>) solo después de que check pase, para revisar la línea de tiempo ensamblada. El plan en el chat y la hoja de bocetos storyboard.html no son aprobación del video final. El renderizado siempre requiere la aprobación final definida por hyperframes/references/review-loop.md.
Prueba de humo de subcomposición
Las auditorías estáticas no pueden detectar todas las fallas de montaje. Cuando el proyecto use subcomposiciones, captura al menos un punto medio visible para cada ranura anfitriona:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trata el contenido pequeño sin estilo, los iconos del tamaño del lienzo, los elementos principales faltantes o los tiempos de espera de registro de línea de tiempo como defectos de montaje que bloquean el renderizado. Consulta hyperframes-core/references/sub-compositions.md para las correcciones correspondientes.
Convenciones del agente
-
Busca en el catálogo antes de escribir movimiento manualmente.
npx hyperframes catalog --query "<el ritmo, en inglés sencillo>". La búsqueda es completamente local: no hay un nivel alojado, ni cuenta, y el texto de la consulta nunca se envía a ninguna parte. Por defecto, clasifica según el vocabulario compartido con el nombre, título, descripción y etiquetas del elemento, lo que omite cualquier frase que no reutilice la redacción del propio catálogo. Añade--on-devicepara clasificar por significado en su lugar (ver el nivel fuera de línea a continuación). -
Consulta en inglés incluso cuando el video no lo esté. Ambos niveles indexan un catálogo en inglés, por lo que una consulta en otro script no produce términos buscables y no devuelve nada. Describe el movimiento en inglés; el texto en pantalla permanece en el idioma que necesite el video.
No searchable words in querysignifica exactamente esto y no es un componente faltante, así que no lo informes como una brecha en el catálogo. -
Lee qué nivel respondió; nunca lo infieras de los resultados que aparecen. Con
--json, el envoltorio llevaquery,tier(on-deviceowords),tier_detail,dropped,unindexed,shown,totalyresults, además detop_scorecuando el nivel respondedor produce uno ywarningscuando se solicitó un nivel y no pudo ejecutarse, o cuando una búsqueda no devolvió nada y un nivel mejor aún está esperando el consentimiento de alguien. Un resultado débil enwordses esperado; el mismo resultado enon-devicees un error.top_scorees solo para on-device y no tiene un umbral detrás: el clasificador devuelve todo el catálogo en algún orden para cada consulta, así que léelo como evidencia en lugar de como aprobado o fallido. -
droppedyunindexedson sesgos opuestos entre el registro y el índice del dispositivo, y reformular la consulta no arregla ninguno.droppedcuenta nombres clasificados que este registro no puede instalar, por lo que las coincidencias más fuertes se están perdiendo.unindexedcuenta movimientos del registro que el índice no puede ver en absoluto, que ninguna consulta puede devolver nunca. Actualizar el registro no es la respuesta a ninguno de los dos: su manifiesto lleva un TTL de 24 horas y se cura solo, mientras que los vectores son un artefacto publicado por separado que se obtiene en~/.hyperframes/catalog/. Volver a ejecutar con--on-devicevuelve a buscar ese índice cuandounindexedes mayor que cero, por lo que ese es el remedio para darle al usuario. Un sesgo puro de sobrecobertura (droppedpor encima de cero mientrasunindexedes cero) no desencadena la recuperación; borrar~/.hyperframes/catalog/es la única salida para ese caso. Ambos recuentos son de nombres en lugar de resultados, por lo que cualquiera puede excedertotal. -
Cuando una búsqueda no devuelve nada que valga la pena instalar, dilo.
npx hyperframes feedback --search-miss "<la consulta que ejecutaste>" --wanted "<el movimiento que necesitabas>" --tier <el nivel que respondió>. No tienes que ensamblar esa línea:catalog --queryla imprime prellenada, y cada envoltorio de búsqueda--jsonla lleva comoreport_gapcon la consulta y el nivel ya correctos: completa--wantedy envía. Este es el único camino que envía una consulta a algún lugar, y es un comando deliberado separado precisamente para que el simplecatalog --querymantenga su promesa de no enviar nada. Informa en cualquier nivel, siempre que los resultados no hagan lo que se necesita; no esperes al nivel on-device, que necesita una descarga consentida de 33 MB y por lo tanto está desactivado en la mayoría de las ejecuciones del agente; esperarlo significa nunca informar en absoluto. El nivel viaja en el informe, por lo que un error de vocabulario se mantiene distinguible de un error de significado sin que tengas que juzgar cuál golpeaste. Lo que regresa es una lista de movimientos que el catálogo aún no tiene, leída directamente en lugar de adivinada a partir de los recuentos de instalación, por lo que la redacción que importa es el efecto que querías, no el nombre del elemento que imaginaste. No lleva calificación y nunca llega a la métrica de calificación. -
Ofrece el nivel fuera de línea; nunca lo habilites silenciosamente. Una descarga única de ~33 MB (una compilación ONNX cuantizada de
bge-small-en-v1.5más su tokenizador, fijada a una revisión fija) y los vectores del catálogo del registro, ambos almacenados en caché bajo~/.hyperframes/, ninguno añadido al proyecto o a ningún paquete. Una vez en caché, clasifica por significado sin enviar nada. Di el tamaño en voz alta y deja que la persona decida, luego pasa--on-device(con-ypara omitir el aviso) una vez que estén de acuerdo. La oferta interactiva solo se activa en una TTY. Bajo--jsonno hay aviso, pero una búsqueda que no encontró nada coloca la misma solicitud enwarnings, así que lee ese array y pon la decisión al usuario tú mismo. Cuando la persona pregunte qué es la descarga, por qué este modelo o qué sale de la máquina, dirígelos a https://hyperframes.heygen.com/developers/catalog-search. -
Prefiere
--jsonpara llamadas de agente y CI. Los modos de servidorrender,previewyplayno proporcionan salida JSON ordinaria;preview --selection --jsonypreview --context --jsonson excepciones de modo de consulta. -
doctor --jsonsiempre sale con cero. Verifica su carga útil:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
El modo no TTY es automático y crea el andamio en blanco centrado. Pasa
--examplesolo para comenzar desde un ejemplo nombrado. Usa--non-interactivepara forzar el modo solo de banderas en una TTY. -
Usa un solo
HYPERFRAMES_RUN_IDpara todos los comandos en el mismo bucle de verificación. -
Cuando el disco esté ajustado, ejecuta
npx hyperframes clean(--dry-runpara listar primero); elimina lo que dejaron los renderizados muertos y los cachés inactivos que se reconstruyen solos, nunca salidas, fuentes ni nada que use un renderizado en ejecución. Escribe los fotogramas de control de calidad en un directorio temporal, no en el proyecto. -
Usa
--strict,--strict-ally--strict-variablescuando las advertencias, variables o condiciones de CI correspondientes deban bloquear el renderizado. -
Las rutas JSON redactan el directorio de inicio como
$HOME; no intentes revertir la redacción. -
Cuando un proyecto en la nube alojada se acerque o supere el límite de carga de 200 MB, usa
cloud render --dry-run --jsony sigue la investigación de.hyperframesignoreenreferences/cloud.md. Nunca ignores un activo simplemente porque sea grande. -
Nunca renderices solo porque las verificaciones pasen. Haz una pausa en la vista previa final y espera la aprobación.
Ediciones dirigidas por Studio
Cuando el usuario se refiera a "este elemento" o a la selección actual, consulta a Studio en lugar de adivinar:
npx hyperframes preview --context --json --context-fields selection
Usa selection.target.hfId cuando esté disponible, de lo contrario su selector y archivo fuente. Si el resultado informa no-selection, pídele al usuario que haga clic en el elemento y vuelva a ejecutar. Solicita solo las partes de contexto que necesites; usa --context-detail full solo para estilos calculados o metadatos de texto editables. El comportamiento completo y los códigos de fallo se encuentran en references/preview-render.md.
Opciones de renderizado
| Necesidad | Comando |
|---|---|
| Iteración local rápida | npx hyperframes render --quality draft |
| Primera codificación real | npx hyperframes render --quality looks --output out.mp4 |
| Entrega local final | npx hyperframes render --quality delivery --output out.mp4 |
| Renderizado reproducible en contenedor | `npx hyperframes render -- |