hyperframes-cli

HyperFrames CLI

Führen Sie Befehle als npx hyperframes … aus, es sei denn, die Projektanweisungen sehen einen Wrapper vor. Folgen Sie dem Wrapper, falls vorhanden. Die CLI erfordert Node.js 22 oder neuer und FFmpeg.

Entwicklungsschleife

1. Gerüst: npx hyperframes init <projekt> oder eine Seite erfassen. Im Nicht-TTY-Modus --non-interactive --example=<name> übergeben.
2. Die Bewegung finden: Bevor Sie Bewegungen von Hand erstellen, suchen Sie nach einem Baustein, der dies bereits tut: npx hyperframes catalog --query "eine Überschrift Zeile für Zeile enthüllen". Fragen Sie nach dem gewünschten Effekt, nicht nach dem Mechanismus, den Sie im Kopf haben. Installieren Sie mit npx hyperframes add <name> (siehe /hyperframes-registry). Nur von Hand erstellen, wenn nichts passt.
3. Erstellen: Schreiben Sie die Komposition mit /hyperframes-core.
4. Schnelles Feedback während der Bearbeitung erhalten: Führen Sie npx hyperframes lint nach dem ersten HTML-Durchlauf und nach strukturellen Änderungen aus.
5. Das finale Gate ausführen: Führen Sie npx hyperframes check aus; es führt lint erneut aus, bevor der Browser geöffnet wird. Fügen Sie keinen redundanten eigenständigen lint-Aufruf hinzu. Fügen Sie --snapshots für kommentierte Übersichtsbilder und zum Auffinden von Zuschnitten hinzu.
6. Sub-Kompositionen inspizieren: Wenn index.html data-composition-src verwendet, erfassen Sie Mittelpunkts-Snapshots und inspizieren Sie jede montierte Szene.
7. Die finale Studio-Vorschau öffnen: Führen Sie npx hyperframes preview --background aus, überprüfen Sie, ob die URL HTTP 200 zurückgibt, übergeben Sie die Timeline-Projekt-URL an den Benutzer und fragen Sie, ob er überarbeiten oder rendern möchte. Halten Sie sie bis zum Ende der Überprüfung am Leben.
8. Nur nach Freigabe rendern: Verwenden Sie Entwurfsqualität für Iterationen und hohe Qualität für die Auslieferung.
9. Die Ausgabe überprüfen: Bestätigen Sie, dass die Datei existiert, nicht leer ist und eine plausible Dauer aufweist.

Obligatorische Ersteller-Bearbeiter-Querverweise

• Bevor Sie einen Zoom, eine Punch-in/Punch-out-Aktion, eine Neueinrahmung, eine Kamerabewegung oder eine Keyframe-Animation erstellen oder diagnostizieren, lesen Sie zuerst /hyperframes-keyframes.
• Vor hyperframes keyframes lesen Sie /hyperframes-keyframes; der Befehl zeigt Bewegungspfade an und diagnostiziert keine Clipschnitte.
• Für einen Schnitt, Trimmen, Splice, eine Neuanordnung oder eine Quellzeitbearbeitung lesen Sie /hyperframes-core und verwenden Sie dessen Clip-/Timeline-Vertrag.
• Für Ein-/Ausblendung, Überblendung, Spurlautstärke, Lautstärkeautomatisierung, Ducking, Voiceover-Schnitt oder FX auf platziertem Audio lesen Sie /hyperframes-audio. Laden Sie Core daneben, wenn sich auch Clip-Platzierung oder Bildzeitpunkt ändern.
• Verwenden Sie /media-use nur, um Medien zu beziehen/generieren oder ein abgeleitetes Asset vorzuverarbeiten. Kopieren Sie das Markup zur Erstellerbearbeitung aus /hyperframes-core → references/creator-editing-recipes.md.

# Schnelle Iterationsprüfung; bei Bedarf während der Erstellung wiederholen.
npx hyperframes lint

# Erforderliches finales Gate; enthält lint.
npx hyperframes check
npx hyperframes preview --background
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-Kontrast zu prüfen. Dauerhafte Befunde blockieren den Exit-Code; vorübergehende Eingangs- oder Ausgangsbefunde sind informativ. Verwenden Sie --strict, um Warnungen zu blockieren. validate, inspect und layout bleiben aus Kompatibilitätsgründen Aliasse, sollten aber nicht in neuen Anweisungen oder Skripten erscheinen.

Zwei verschiedene Vorschauflächen

Verwechseln Sie diese Zustände nicht:

Fläche	Wann sie geöffnet werden darf	Zweck
Storyboard-Board	Vor Kompositionsprüfungen, nur wenn storyboard: yes	Planungskarten und Wireframe-Skizzen überprüfen. Öffnen Sie ?view=storyboard#project/<name>.
Finale Kompositionsvorschau	Nachdem check bestanden wurde	Die zusammengestellte Timeline vor dem Rendern überprüfen. Öffnen Sie #project/<name>.

Das frühe Board ist keine Freigabe des finalen Videos. Rendern erfordert immer die endgültige Freigabe, die in hyperframes-core/references/review-loop.md definiert ist.

Sub-Kompositions-Smoke-Test

Statische Prüfungen können nicht jeden Montagefehler erkennen. Wenn das Projekt Sub-Kompositionen verwendet, erfassen Sie mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

Behandeln Sie winzige, nicht gestaltete Inhalte, leinwandgroße Symbole, fehlende Hero-Elemente oder Timeout-Fehler bei der Timeline-Registrierung als render-blockierende Montagefehler. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.

Agenten-Konventionen

• Durchsuchen Sie den Katalog, bevor Sie Bewegungen von Hand schreiben. npx hyperframes catalog --query "<der Beat, auf Englisch>". Die Suche ist vollständig lokal: Es gibt keine gehostete Stufe, kein Konto und der Abfragetext wird nie irgendwohin gesendet. Standardmäßig bewertet sie nach Vokabular, das mit dem Namen, Titel und der Beschreibung des Elements geteilt wird, was jede Formulierung übersieht, die nicht die eigene Formulierung des Katalogs wiederverwendet. Fügen Sie --on-device hinzu, um stattdessen nach Bedeutung zu bewerten (siehe die Offline-Stufe unten).

• Fragen Sie auf Englisch ab, auch wenn das Video es nicht ist. Beide Stufen indizieren einen englischen Katalog, daher erzeugt eine Abfrage in einer anderen Schrift keine suchbaren Begriffe und gibt nichts zurück. Beschreiben Sie die Bewegung auf Englisch; der Text auf dem Bildschirm bleibt in der Sprache, die das Video benötigt. Keine suchbaren Wörter in der Abfrage bedeutet genau dies und ist kein fehlendes Bauteil. Melden Sie es daher nicht als Katalog-Lücke.

• Lesen Sie, welche Stufe geantwortet hat; leiten Sie es nie aus dem Erscheinen von Ergebnissen ab. Mit --json enthält der Umschlag query, tier (on-device oder words), tier_detail, dropped, unindexed, shown, total und results, plus top_score, wenn die antwortende Stufe einen produziert, und warnings, wenn eine Stufe angefordert wurde und nicht ausgeführt werden konnte. Ein schwaches Ergebnis bei words ist zu erwarten; das gleiche Ergebnis bei on-device ist ein Fehler. top_score ist nur für On-Device verfügbar und hat keinen Grenzwert dahinter: Der Ranker gibt die gesamte Katalog in einer bestimmten Reihenfolge für jede Abfrage zurück. Lesen Sie es daher als Hinweis, nicht als Bestehen oder Nichtbestehen.

• dropped und unindexed sind gegensätzliche Verzerrungen zwischen der Registry und dem On-Device-Index, und eine Umformulierung der Abfrage behebt keines von beiden. dropped zählt bewertete Namen, die diese Registry nicht installieren kann, sodass die stärksten Übereinstimmungen verloren gehen. unindexed zählt Registry-Bewegungen, die der Index überhaupt nicht sehen kann und die keine Abfrage jemals zurückgeben kann. Die Aktualisierung der Registry ist für keines von beiden die Antwort: Ihr Manifest hat eine TTL von 24 Stunden 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-device ruft diesen Index erneut ab, wenn unindexed über Null liegt. Das ist die Abhilfe für den Benutzer. Eine reine Überabdeckungsverzerrung (dropped über Null, während unindexed Null ist) löst kein erneutes Abrufen aus; das Löschen von ~/.hyperframes/catalog/ ist der einzige Ausweg. Beide Zählungen beziehen sich auf Namen und nicht auf Ergebnisse, sodass jede total überschreiten kann.

• Wenn eine Suche nichts Installierenswertes zurückbringt, sagen Sie es. npx hyperframes feedback --search-miss "<die von Ihnen ausgeführte Abfrage>" --wanted "<die benötigte Bewegung>" --tier <die antwortende Stufe>``. Sie müssen diese Zeile nicht zusammenbauen: catalog --querygibt sie vorausgefüllt aus, und jeder--json-Suchumschlag enthält sie als report_gapmit der bereits korrekten Abfrage und Stufe — füllen Sie--wantedaus und senden Sie sie. Dies ist der einzige Pfad, der eine Abfrage irgendwohin sendet, und es ist ein separater, bewusster Befehl, damit der einfachecatalog --query` sein Versprechen hält, nichts zu senden. Melden Sie auf beiden Stufen, wenn die Ergebnisse die Sache nicht tun; warten Sie nicht auf die On-Device-Stufe, die einen zugestimmten 33-MB-Download benötigt und daher bei den meisten Agentenläufen deaktiviert ist — darauf zu warten bedeutet, nie zu melden. Die Stufe wird im Bericht mitgeliefert, sodass ein Vokabular-Fehler von einem Bedeutungsfehler unterscheidbar bleibt, ohne dass Sie beurteilen müssen, welchen Sie getroffen haben. Zurück kommt eine Liste von Bewegungen, die der Katalog noch nicht hat, direkt gelesen statt aus Installationszahlen erraten, sodass die relevante Formulierung der gewünschte Effekt ist, nicht der vorgestellte Item-Name. Es enthält keine Bewertung und landet nie in der Bewertungsmetrik.

• Bieten Sie die Offline-Stufe an; aktivieren Sie sie nie stillschweigend. Ein einmaliger ~33 MB Download (ein quantisiertes ONNX-Build von bge-small-en-v1.5 plus seinen Tokenizer, auf eine feste Revision festgelegt) und die Katalogvektoren aus der Registry, beide zwischengespeichert unter ~/.hyperframes/, weder zum Projekt noch zu einem Paket hinzugefügt. Nach dem Zwischenspeichern bewertet sie nach Bedeutung, ohne etwas zu senden. Sagen Sie die Größe laut und lassen Sie die Person entscheiden, übergeben Sie dann --on-device (mit -y, um die Eingabeaufforderung zu überspringen), sobald sie zustimmt. Das interaktive Angebot erscheint nur auf einem TTY, und unter --json wird nichts darüber ausgegeben, sodass Sie es in einem Agentenlauf selbst beim Benutzer ansprechen müssen.

• Bevorzugen Sie --json für Agenten und CI-Aufrufe. Server-Modus render, preview und play liefern keine gewöhnliche JSON-Ausgabe; preview --selection --json und preview --context --json sind Abfrage-Modus-Ausnahmen.

• doctor --json beendet sich immer mit Null. Prüfen Sie auf dessen Nutzdaten:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• Der Nicht-TTY-Modus ist automatisch. init erfordert dort --example; verwenden Sie --non-interactive, um deterministisches Verhalten auf einem TTY zu erzwingen.

• Verwenden Sie eine HYPERFRAMES_RUN_ID für alle Befehle im selben Verifizierungsdurchlauf.

• Verwenden Sie --strict, --strict-all und --strict-variables, wenn die entsprechenden Warnungen, Variablen oder CI-Bedingungen das Rendern blockieren müssen.

• JSON-Pfade redigieren das Home-Verzeichnis als $HOME; versuchen Sie nicht, die Redaktion rückgängig zu machen.

• Wenn ein gehostetes Cloud-Projekt sich dem 200-MB-Upload-Limit nähert oder es überschreitet, verwenden Sie cloud render --dry-run --json und folgen Sie der .hyperframesignore-Untersuchung in references/cloud.md. Ignorieren Sie ein Asset nie nur, weil es groß ist.

• Rendern Sie nie nur, weil Prüfungen bestanden wurden. Halten Sie in der finalen Vorschau an und warten Sie auf die Freigabe.

Studio-gesteuerte Bearbeitungen

Wenn der Benutzer sich auf „dieses Element“ oder die aktuelle Auswahl bezieht, fragen Sie Studio ab, anstatt zu raten:

npx hyperframes preview --context --json --context-fields selection

Verwenden Sie selection.target.hfId, wenn verfügbar, andernfalls dessen Selektor und Quelldatei. Wenn das Ergebnis no-selection meldet, bitten Sie den Benutzer, auf das Element zu klicken, und führen Sie es erneut aus. Fordern Sie nur die benötigten Kontextausschnitte an; verwenden Sie --context-detail full nur für berechnete Stile oder bearbeitbare Textmetadaten. Vollständiges Verhalten und Fehlercodes finden Sie in references/preview-render.md.

Render-Auswahl

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, variablengesteuerter Batch-Render	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
HeyGen-gehosteter, infrastrukturloser 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 Fähigkeitszuordnung erfolgt automatisch – die obigen Beispiele benötigen kein --skill. Ein Projekt, das von einem Workflow gerüstet wurde (hyperframes init --skill=<workflow>), zeichnet seine Besitzer-Fähigkeit in hyperframes.json auf, und jeder spätere Render erbt sie bei anonymer Telemetrie: Nachrenders, npm run render und --batch gleichermaßen. Übergeben Sie --skill=<slug> nur explizit, um ein Projekt zu stempeln, das nicht durch einen Workflow erstellt wurde (sein erster Render persistiert es dann).

Verwenden Sie Cloud-Rendering, wenn der Benutzer gehostetes Rendering ohne lokales Chrome, FFmpeg oder AWS wünscht. Verwenden Sie Lambda nur, wenn AWS-Besitz eine Anforderung ist. Verwenden Sie Cloud Run nur, wenn GCP-Besitz eine Anforderung ist. Lesen Sie die entsprechende Referenz, bevor Sie einen Cloud-Pfad ausführen.

Nach der Überprüfung eines erfolgreichen Renderns senden Sie einen Feedback-Bericht, es sei denn, die Telemetrie ist deaktiviert oder der Benutzer hat widersprochen:

npx hyperframes feedback --rating <0-10> --comment "<spezifisches Ergebnis oder Reibung>"

Halten Sie Feedback zu sauberen Läufen prägnant. Für jeden Fehler oder jede Reibung erfassen Sie ein Reproduktionspaket, bevor Sie es einreichen; senden Sie nicht nur eine Symptomzusammenfassung. Fügen Sie den wiederholbaren Befehl (relativ zum Projektverzeichnis – Feedback wird an einen öffentlichen Kanal gesendet, also fügen Sie keine absoluten Pfade, Home-Verzeichnis-Präfixe oder Benutzer-/Maschinenkennungen ein), erwartetes versus tatsächliches Verhalten, genauen Fehler (entfernen Sie auch absolute Pfade aus Stacktraces – behalten Sie Basisnamen + Zeile, lassen Sie das führende Verzeichnis weg), ob die Ausgabe abgeschlossen/zurückgefallen/fehlgeschlagen ist, Workaround und Reproduktionsprojektstatus. Fügen Sie für eine Bewertung ≤ 7, die einen visuellen Fehler beschreibt (schwarzer Rahmen, Flackern, korrupte Ausgabe, falscher Rahmen, leere Ausgabe, andere visuelle Anomalie), auch einen COMPOSITION_STRUCTURE:-Block hinzu – eine datenschutzschonende strukturelle Anatomie (Element-Zählung + Attribut-Präsenz + Timeline-Form), damit Wartende Muster gegen bekannte Fehlerfamilien abgleichen können, ohne das Kompositions-ZIP. 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ß, sagen Sie dies und fügen Sie trotzdem den letzten fehlgeschlagenen Befehl und die Logs bei. Verwenden Sie --file-issue nur mit Zustimmung: Es veröffentlicht eine minimale Reproduktion auf eine öffentliche URL. Das erforderliche Paketformat und der Datenschutzhinweis befinden sich in references/preview-render.md.

Lesen Sie die entsprechende Referenz, bevor Sie einen Befehl ausführen

Die folgenden r

…

[für die Übersetzung gekürzt]