HyperFrames CLI
Führe Befehle als npx hyperframes ... aus, es sei denn, die Projektanweisungen geben einen Wrapper vor. Befolge den Wrapper, falls vorhanden. Die CLI erfordert Node.js 22 oder neuer und FFmpeg.
Entwicklungsschleife
- Gerüst erstellen:
npx hyperframes init <projekt>oder eine Website erfassen. Im Nicht-TTY-Modus übergib--non-interactive --example=<name>. - Die Bewegung finden: Bevor du von Hand animierst, suche nach einem Primitive, das dies bereits tut:
npx hyperframes catalog --query "eine Überschrift zeilenweise enthüllen". Frage nach dem gewünschten Effekt, nicht nach dem Mechanismus, den du im Kopf hast. Installiere mitnpx hyperframes add <name>(siehe/hyperframes-registry). Schreibe nur von Hand, wenn nichts passt. - Erstellen: Schreibe die Komposition mit
/hyperframes-core. - Schnelles Feedback während der Bearbeitung erhalten: Führe
npx hyperframes lintnach dem ersten HTML-Durchlauf und nach strukturellen Änderungen aus. - Letzte Prüfung durchführen: Führe
npx hyperframes checkaus; es führt lint erneut aus, bevor der Browser geöffnet wird. Stelle keinen redundanten, eigenständigen lint-Aufruf voran. Füge--snapshotsfür kommentierte Übersichtsbilder und das Auffinden von Ausschnitten hinzu. - Unterkompositionen prüfen: Wenn
index.htmldata-composition-srceinbindet, erfasse Mittelpunkts-Snapshots und prüfe jede eingebundene Szene. - Die finale Studio-Vorschau öffnen: Führe
npx hyperframes previewaus, übergib dem Benutzer die Timeline-Projekt-URL und frage, ob er überarbeiten oder rendern möchte. - Nur nach Genehmigung rendern: Verwende Entwurfsqualität für Iterationen und hohe Qualität für die Auslieferung.
- Die Ausgabe überprüfen: Bestätige, dass die Datei existiert, nicht leer ist und eine plausible Dauer hat.
# Schnelle Iterationsprüfung; während der Bearbeitung nach Bedarf wiederholen.
npx hyperframes lint
# Erforderliche letzte Prüfung; beinhaltet lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check führt zuerst lint aus, verwendet dann eine Browsersitzung und einen Suchdurchlauf, um Laufzeitfehler, fehlgeschlagene Anfragen, Layout, *.motion.json-Assertions und WCAG-Kontraste zu prüfen. Dauerhafte Befunde blockieren den Exit-Code; vorübergehende Ein- oder Ausgangsbefunde sind informativ. Verwende --strict, um Warnungen als Fehler zu behandeln. validate, inspect und layout bleiben aus Kompatibilitätsgründen Aliase, sollten aber nicht in neuen Anweisungen oder Skripten vorkommen.
Zwei verschiedene Vorschauoberflächen
Verwechsle diese Zustände nicht:
| Oberfläche | Wann sie geöffnet werden kann | Zweck |
|---|---|---|
| Storyboard-Board | Vor Kompositionsprüfungen, nur bei storyboard: yes | Planungskarten und Drahtgittermodelle überprüfen. Öffne ?view=storyboard#project/<name>. |
| Finale Kompositionsvorschau | Nach bestandenem check | Zusammengestellte Timeline vor dem Rendern überprüfen. Öffne #project/<name>. |
Das frühe Board ist keine Genehmigung des finalen Videos. Rendern erfordert immer die endgültige Genehmigung, definiert in hyperframes-core/references/review-loop.md.
Unterkompositions-Smoke-Test
Statische Prüfungen können nicht jeden Einbauf ehler erkennen. Wenn das Projekt Unterkompositionen verwendet, erfasse mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Behandle winzigen, ungestylten Inhalt, leinwandgroße Symbole, fehlende Hero-Elemente oder Timeouts bei der Timeline-Registrierung als rende rblockierende Einbauf ehler. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.
Agenten-Konventionen
-
Durchsuche den Katalog, bevor du Bewegungen von Hand schreibst.
npx hyperframes catalog --query "<der Beat, in einfacher Sprache>". Die Suche ist vollständig lokal: Es gibt keinen gehosteten Dienst, kein Konto und der Abfragetext wird nie an Dritte gesendet. Standardmäßig bewertet sie basierend auf dem Vokabular, das mit Name, Titel und Beschreibung des Eintrags geteilt wird, was jede Formulierung übersieht, die nicht die eigene Terminologie des Katalogs wiederverwendet. Füge--on-devicehinzu, um stattdessen nach Bedeutung zu bewerten (siehe den Offline-Tier unten). -
Lies, welcher Tier geantwortet hat; leite dies nie nur aus dem Erscheinen von Ergebnissen ab. Mit
--jsonenthält das Envelopequery,tier(on-deviceoderwords),tier_detail,dropped,unindexed,shown,totalundresults, sowietop_score, wenn der antwortende Tier einen produziert, undwarnings, wenn ein Tier angefordert wurde, aber nicht ausgeführt werden konnte. Ein schwaches Ergebnis beiwordsist erwartet; dasselbe Ergebnis beion-deviceist ein Fehler.top_scoregibt es nur bei on-device und hat keinen Schwellenwert dahinter: der Ranker gibt den gesamten Katalog in einer bestimmten Reihenfolge für jede Abfrage zurück, lies es also als Hinweis und nicht als Bestehen/Nichtbestehen. -
droppedundunindexedsind entgegengesetzte Verzerrungen zwischen dem Registry und dem On-Device-Index, und das Umformulieren der Abfrage behebt keines von beiden.droppedzählt bewertete Namen, die diese Registry nicht installieren kann, sodass die stärksten Übereinstimmungen diejenigen sind, die verloren gehen.unindexedzählt Registry-Änderungen, die der Index überhaupt nicht sehen kann, was keine Abfrage jemals zurückgeben kann. Die Aktualisierung der Registry ist die Antwort auf keines von beiden: Ihr Manifest hat eine 24h-TTL und heilt sich selbst, während die Vektoren ein separat veröffentlichtes Artefakt sind, das in~/.hyperframes/catalog/abgerufen wird. Die erneute Ausführung mit--on-deviceruft diesen Index erneut ab, wennunindexedgrößer als Null ist, das ist also das Mittel, das du dem Benutzer geben kannst. Eine reine Überdeckungsverzerrung (droppedgrößer als Null beiunindexedgleich Null) löst den erneuten Abruf nicht aus; das Löschen von~/.hyperframes/catalog/ist der einzige Weg, damit umzugehen. Beide Werte zählen Namen und nicht Ergebnisse, daher kann jedertotalüberschreiten. -
Wenn die Bedeutungssuche nichts Installationswürdiges findet, sag es.
npx hyperframes feedback --search-miss "<die von dir ausgeführte Abfrage>" --wanted "<die benötigte Bewegung>" --tier on-device. Dies ist der einzige Pfad, der eine Abfrage an Dritte sendet, und es ist ein separater bewusster Befehl, damitcatalog --querygenau sein Versprechen hält, nichts zu senden. Melde den Fehlschlag, wenn der On-Device-Tier geantwortet hat und die besten Treffer die Sache immer noch nicht erledigen; ein schwaches Ergebnis imwords-Tier ist erwartet und eine Meldung nicht wert. Zurück kommt eine Liste von Bewegungen, die der Katalog noch nicht hat, direkt gelesen und nicht anhand von Installationszahlen geschätzt, sodass die relevante Formulierung der gewünschte Effekt ist, nicht der von dir vorgestellte Eintragsname. Es enthält keine Bewertung und landet nie in der Bewertungsmetrik. -
Biete den Offline-Tier an; aktiviere ihn nie stillschweigend. Ein einmaliger Download von ~33 MB (ein quantisiertes ONNX-Build von
bge-small-en-v1.5plus Tokenizer, auf eine feste Revision gepinnt) und die Katalogvektoren aus der Registry, beide unter~/.hyperframes/zwischengespeichert, keinem Projekt oder Paket hinzugefügt. Einmal zwischengespeichert, bewertet er nach Bedeutung, ohne etwas zu senden. Sage die Größe laut und lass die Person entscheiden, übergib dann--on-device(mit-y, um die Eingabeaufforderung zu überspringen), sobald sie zustimmt. Das interaktive Angebot erscheint nur auf einem TTY und wird unter--jsonüberhaupt nicht ausgegeben, also musst du es in einem Agentenlauf selbst beim Benutzer ansprechen. -
Bevorzuge
--jsonfür Agent- und CI-Aufrufe. Der Server-Modus vonrender,previewundplaybietet keine normale JSON-Ausgabe;preview --selection --jsonundpreview --context --jsonsind Ausnahmen im Abfragemodus. -
doctor --jsonendet immer mit Exit-Code 0. Prüfe auf sein Payload:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Der Nicht-TTY-Modus ist automatisch.
initerfordert dort--example; verwende--non-interactive, um deterministisches Verhalten auf einem TTY zu erzwingen. -
Verwende eine einzige
HYPERFRAMES_RUN_IDfür alle Befehle im gleichen Verifikationsdurchlauf. -
Verwende
--strict,--strict-allund--strict-variables, wenn die entsprechenden Warnungen, Variablen oder CI-Bedingungen das Rendern blockieren müssen. -
JSON-Pfade schwärzen das Home-Verzeichnis als
$HOME; versuche nicht, die Schwärzung rückgängig zu machen. -
Wenn ein gehostetes Cloud-Projekt sich dem Upload-Limit von 200 MB nähert oder es überschreitet, verwende
cloud render --dry-run --jsonund befolge die.hyperframesignore-Untersuchung inreferences/cloud.md. Ignoriere niemals eine Datei nur, weil sie groß ist. -
Rendere niemals nur, weil die Prüfungen bestanden sind. Halte bei der endgültigen Vorschau inne und warte auf die Genehmigung.
Studio-gesteuerte Bearbeitungen
Wenn der Benutzer sich auf "dieses Element" oder die aktuelle Auswahl bezieht, frage Studio ab, anstatt zu raten:
npx hyperframes preview --context --json --context-fields selection
Verwende selection.target.hfId, wenn verfügbar, ansonsten dessen Selektor und Quelldatei. Wenn das Ergebnis no-selection meldet, bitte den Benutzer, auf das Element zu klicken und den Befehl erneut auszuführen. Fordere nur die Kontextteile an, die du benötigst; verwende --context-detail full nur für berechnete Stile oder bearbeitbare Textmetadaten. Vollständiges Verhalten und Fehlercodes befinden sich in references/preview-render.md.
Render-Optionen
| Bedarf | Befehl |
|---|---|
| Schnelle lokale Iteration | npx hyperframes render --quality draft |
| Finale lokale Auslieferung | npx hyperframes render --quality high --output out.mp4 |
| Reproduzierbarer Container-Render | npx hyperframes render --docker --strict --output out.mp4 |
| Lokaler variablengetriebener Batch-Render | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen-gehosteter Zero-Infrastructure-Render | npx hyperframes cloud render |
| Selbstverwalteter verteilter AWS-Render | npx hyperframes lambda render <projekt> --width 1920 --height 1080 --wait |
| Selbstverwalteter verteilter GCP-Render | npx hyperframes cloudrun render <projekt> --width 1920 --height 1080 --wait |
Die Skill-Zuordnung erfolgt automatisch – die obigen Beispiele benötigen kein --skill. Ein Projekt, das von einem Workflow erstellt wurde (hyperframes init --skill=<workflow>), zeichnet seinen zugehörigen Skill in hyperframes.json auf, und jeder spätere Render erbt ihn in der anonymen Telemetrie: Neu-Renderings, npm run render und --batch gleichermaßen. Übergib --skill=<slug> nur explizit, um ein Projekt zu kennzeichnen, das nicht über einen Workflow erstellt wurde (sein erster Render speichert ihn dann dauerhaft).
Verwende Cloud-Rendering, wenn der Benutzer gehostetes Rendering ohne lokales Chrome, FFmpeg oder AWS wünscht. Verwende Lambda nur, wenn AWS-Besitz eine Anforderung ist. Verwende Cloud Run nur, wenn GCP-Besitz eine Anforderung ist. Lies die entsprechende Referenz, bevor du einen Cloud-Pfad ausführst.
Sende nach dem Verifizieren eines erfolgreichen Rendervorgangs einen Feedback-Bericht, es sei denn, die Telemetrie ist deaktiviert oder der Benutzer hat abgelehnt:
npx hyperframes feedback --rating <0-10> --comment "<spezifisches Ergebnis oder Reibung>"
Halte Feedback zu sauberen Ausführungen kurz. Halte für jeden Fehler oder jede Reibung ein Reproduktionspaket bereit, bevor du es einreichst; sende keine reine Symptomzusammenfassung. Füge den wiederholbaren Befehl hinzu (relativ zum Projektverzeichnis – Feedback wird an einen öffentlichen Kanal gesendet, also füge keine absoluten Pfade, Home-Verzeichnis-Präfixe oder Benutzer-/Maschinenkennungen ein), erwartetes versus tatsächliches Verhalten, genauen Fehler (entferne auch absolute Pfade aus Stack-Traces – behalte Basisname + Zeile, lass das führende Verzeichnis weg), ob die Ausgabe abgeschlossen/zurückgefallen/fehlgeschlagen ist, Workaround und Reproduktions-Projektstatus. Beschreibe für eine Bewertung ≤ 7, die einen visuellen Fehler beschreibt (schwarzer Rahmen, Flackern, fehlerhafte Ausgabe, falscher Frame, leere Ausgabe, andere visuelle Anomalien), auch einen COMPOSITION_STRUCTURE:-Block – eine datenschutzfreundliche strukturelle Anatomie (Elementzählung + Attributpräsenz + Timeline-Form), damit Wartungsteams Muster mit bekannten Fehlerfamilien abgleichen können, ohne das Kompositions-ZIP zu benötigen. Agenten füllen dies automatisch über den Kompositions-Zensus-Helfer aus; der menschliche Benutzer füllt es nicht von Hand aus. Wenn sich das Problem nicht erneut reproduzieren ließ, sag das und füge trotzdem den letzten fehlgeschlagenen Befehl und die Logs bei. Verwende --file-issue nur mit Zustimmung: es veröffentlicht eine minimale Reproduktion unter einer öffentlichen URL. Das erforderliche Paketformat und der Datenschutzhinweis befinden sich in references/preview-render.md.
Lies die passende Referenz, bevor du einen Befehl ausführst
Die folgenden Referenzen und zugehörigen Skills sind verbindliche Befehlsverträge, keine optionale Hintergrundlektüre. Bevor du einen Befehl in der Tabelle ausführst, lies die entsprechende Zeile.
| Bedarf | Referenz |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, Bewegungs-Sidecars, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, variablengetriebenes render --batch | references/compare-and-batch.md |
beats für das Studio-Beat-Grid eines bestehenden Projekts | references/beats.md |
preview, play, render, publish, Studio-Kontext, Feedback | references/preview-render.md |
doctor, Browser-Management | references/doctor-browser.md |
auth, HeyGen-gehostetes Cloud-Rendering und Template-Variablen | references/cloud.md |
| AWS Lambda-Bereitstellung und -Rendering | references/lambda.md |
| Google Cloud Run-Bereitstellung und -Rendering | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, Telemetrie, Medienvorverarbeitung | references/upgrade-info-misc.md |
Für Kompositionsvariablen alle …