Plugin-Installationen: Führe vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln aus, wenn sich dieses Skill innerhalb eines HyperFrames-Plugins befindet. Eigenständige Installationen befolgen die unten stehenden Aktualisierungshinweise.
Was macht HyperFrames CLI?
Führe Befehle als npx hyperframes ... aus, sofern die Projektanweisungen keinen Wrapper bereitstellen. Verwende den Wrapper, falls vorhanden. Die CLI erfordert Node.js 22 oder neuer und FFmpeg.
Entwicklungsschleife
- Gerüst:
npx hyperframes init <projekt>(zentriert leer). Oder erfasse eine Website. Verwende--example=<name>nur, um von einem benannten Beispiel zu starten. - Den Move finden: Wenn die Anfrage ein Asset, Sound, Bild, eine Stimme oder eine schnelle visuelle Bearbeitung benennt, löse es über
/media-useauf, bevor du einen Plan vorschlägst. Suche andernfalls, bevor du manuell eine Bewegung erstellst, nach einem Primitive, das dies bereits tut:npx hyperframes catalog --query "Eine Überschrift Zeile für Zeile 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). Erstelle nur manuell, wenn nichts passt. - Erstellen: Schreibe die Komposition mit
/hyperframes-core. Um zu erfahren, was sich auf der Timeline eines Projekts befindet (Spuren, Clips, Start, Ende, was abgespielt wird), führenpx hyperframes timeline --jsonaus, anstattindex.htmlund jede Unterkompositionsdatei zu lesen: Verschachtelte Zeilen tragen absolute Haupt-Timeline-WerteabsStart/absEndund ihre zugehörigefile, nicht nur ihre lokale, pro-Unterkompositions-Zeit. Bevorzuge--jsongegenüber der Textform; es verbraucht weniger Token bei gleicher oder besserer Korrektheit. Siehereferences/upgrade-info-misc.mdfür Einzeiler, die häufige Fragen beantworten, ohne die gesamte Ausgabe zu lesen. - Schnelles Feedback beim Bearbeiten erhalten: Führe
npx hyperframes lintnach dem ersten HTML-Durchlauf und nach strukturellen Änderungen aus. - Den finalen Check durchführen: Führe
npx hyperframes checkaus; es führt lint erneut aus, bevor der Browser geöffnet wird. Hänge keinen redundanten eigenständigen lint-Aufruf an. Füge--snapshotsfür kommentierte Übersichtsbilder und zum Auffinden von Ausschnitten hinzu. - Unterkompositionen inspizieren: Wenn
index.htmldata-composition-srclädt, erstelle Momentaufnahmen von der Mitte und inspiziere jede eingebundene Szene. - Die finale Studio-Vorschau öffnen: Führe
npx hyperframes preview --backgroundaus, überprüfe, ob die URL HTTP 200 zurückgibt, übergib dem Benutzer die Timeline-Projekt-URL und frage, ob überarbeitet oder gerendert werden soll. Halte sie am Leben, bis die Überprüfung abgeschlossen ist. - Rendere erst nach Genehmigung: Verwende
--quality draftwährend der Iteration,--quality looksfür die erste echte Kodierung (CLI-Standard) und--quality deliveryfür die endgültige Auslieferung. - Das Projekt an die Desktop-App übergeben (auf Angebot): Wenn die Framey-Zeile des Renders mit
hyperframes open …endet, bietenpx hyperframes open [verz]an. Es öffnet das Projekt in der HyperFrames Desktop-App und fügt es dem Startbildschirm hinzu; unter Claude Code oder Codex übernimmt der Chat diese Konversation. Ohne die App wird mit Exit 1 beendet und der Download-Link ausgegeben.--jsonfür Agenten. - Die Ausgabe überprüfen: Bestätige, dass die Datei existiert und nicht leer ist. Lies die zweite Zeile der Render-Zusammenfassung (
beginframevsscreenshot, GPU, Stage-Timings).screenshot+software gpuunter Linux ist der langsame Pfad.ffprobe -v error -show_format -show_streamsund vergleiche die Dauer (und fps, falls in der Aufgabenstellung festgelegt) mit dem Root-data-duration.
Projektverlauf in deinem Zug
Jeder Schreibvorgang in das Projekt wird als Eintrag gespeichert, der rückgängig gemacht werden kann. Verwende es nur in zwei Momenten, niemals bei jedem Schritt:
- Zu Beginn eines Zugs:
npx hyperframes history begin --who <dein-name> --label "<was du gleich tun wirst>", dannnpx hyperframes history --since mine --who <dein-name>, um zu sehen, was die Person seit deinem letzten Zug geändert hat. Baue auf ihren Bearbeitungen auf; überschreibe sie niemals. - Ein Check ist fehlgeschlagen, oder die Person sagt, es sei schlechter geworden:
npx hyperframes history undo --who <dein-name>macht deinen neuesten Zug rückgängig und lässt die Bearbeitungen der Person in Ruhr. Mache keine manuellen Rückgängig-Änderungen. Bei einem Konflikt wird mit Exit 2 beendet und beide Optionen ausgegeben.
Beende jeden Zug mit npx hyperframes history end, damit deine Schreibvorgänge als deine und nicht als „Außerhalb der App geändert“ gelesen werden. Während ein Zug geöffnet ist, zählt jeder Schreibvorgang in das Projekt als deiner, bis 10 Minuten ohne einen solchen vergangen sind; danach ist der Zug von selbst beendet.
Obligatorische Querverweise für Erstellerbearbeitungen
- Bevor du einen Zoom, Punch-In/Punch-Out, Reframe, Kamerabewegung oder jegliche Keyframe-Bewegung erstellst oder diagnostizierst, lies zuerst
/hyperframes-keyframes. - Vor
hyperframes keyframeslies/hyperframes-keyframes; der Befehl zeigt Animations-Trajektorien an und diagnostiziert keine Clipschnitte. - Für einen Schnitt, Trim, Splice, Neuordnung oder Quell-Zeit-Bearbeitung lies
/hyperframes-coreund verwende dessen Clip/Timeline-Vertrag. - Für Ein-/Ausblendungen, Crossfade, Spurverstärkung, Lautstärkeautomatisierung, Ducking, Voiceover-Carve oder FX auf platziertem Audio lies
/hyperframes-audio. Lade Core daneben, wenn auch Clip-Platzierung oder Bild-Timing geändert werden. - Eine Anfrage, die ein Asset, Sound, Bild, eine Stimme oder eine schnelle visuelle Bearbeitung benennt, wird über
/media-useaufgelöst, bevor ein Plan vorgeschlagen wird. Kopiere die Erstellerbearbeitungs-Markierung aus/hyperframes-core→references/creator-editing-recipes.md.
# Schnelle Iterationsprüfung; bei Bedarf während der Bearbeitung wiederholen.
npx hyperframes lint
# Erforderlicher finaler Check; enthält 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 führt zuerst lint aus, verwendet dann eine Browser-Session und einen Suchdurchlauf, um Laufzeitfehler, fehlgeschlagene Anfragen, Layout, *.motion.json-Assertions und WCAG-Kontrast zu prüfen. Permanente Befunde blockieren den Exit-Code; vorübergehende Befunde beim Eintreten oder Verlassen sind informativ. Verwende --strict, um Warnungen zu blockieren. validate, inspect und layout bleiben aus Kompatibilitätsgründen als Aliase erhalten, dürfen aber nicht in neuen Anweisungen oder Skripten erscheinen.
Vorschau vor dem Rendern
Öffne die finale Kompositionsvorschau (#project/<name>) erst, nachdem check bestanden ist, um die zusammengestellte Timeline zu überprüfen. Der Plan im Chat und das storyboard.html-Skizzenblatt stellen keine Genehmigung des endgültigen Videos dar. Das Rendern erfordert immer die endgültige Genehmigung, die in hyperframes/references/review-loop.md definiert ist.
Unterkompositions-Smoke-Test
Statische Überprüfungen können nicht jeden Mount-Fehler erkennen. Wenn das Projekt Unterkompositionen verwendet, erfasse mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Behandle kleine, unstylische Inhalte, leinwandgroße Symbole, fehlende Hero-Elemente oder Timeout bei der Timeline-Registrierung als renderblockierende Mount-Defekte. 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 einfachem Englisch>". Die Suche ist vollständig lokal: Es gibt keine gehostete Stufe, kein Konto und der Abfragetext wird nie irgendwohin gesendet. Standardmäßig sortiert sie nach Vokabular, das mit dem Namen, Titel, der Beschreibung und den Tags des Elements geteilt wird, was jede Formulierung übersieht, die die eigene Wortwahl des Katalogs nicht wiederverwendet. Füge--on-devicehinzu, um stattdessen nach Bedeutung zu sortieren (siehe die Offline-Stufe unten). -
Frage auf Englisch, auch wenn das Video nicht auf Englisch ist. Beide Stufen indizieren einen englischen Katalog, daher erzeugt eine Abfrage in einer anderen Schrift keine durchsuchbaren Begriffe und gibt nichts zurück. Beschreibe den Move auf Englisch; der Text auf dem Bildschirm bleibt in der Sprache, die das Video benötigt.
Keine durchsuchbaren Wörter in der Abfragebedeutet genau dies und ist keine fehlende Komponente, also melde es nicht als Katalog-Lücke. -
Lies, welche Stufe geantwortet hat; leite es niemals aus den Ergebnissen ab. Mit
--jsonträgt der Umschlagquery,tier(on-deviceoderwords),tier_detail,dropped,unindexed,shown,totalundresults, plustop_score, wenn die antwortende Stufe eine solche erzeugt, undwarnings, wenn eine Stufe angefordert wurde und nicht ausgeführt werden konnte, oder wenn eine Suche nichts zurückgegeben hat und eine bessere Stufe noch auf die Zustimmung von jemandem wartet. Ein schwaches Ergebnis aufwordsist zu erwarten; das gleiche Ergebnis aufon-deviceist ein Fehler.top_scoreist nur auf dem Gerät vorhanden und hat keinen dahinterliegenden Schwellenwert: Der Ranker gibt für jede Abfrage den gesamten Katalog in einer bestimmten Reihenfolge zurück, lies ihn also als Hinweis und nicht als Bestehen oder Nichtbestehen. -
droppedundunindexedsind entgegengesetzte Verzerrungen zwischen der Registry und dem On-Device-Index, und eine Umformulierung der Abfrage behebt keines von beiden.droppedzählt die Namen, die diese Registry nicht installieren kann, sodass die stärksten Übereinstimmungen diejenigen sind, die verloren gehen.unindexedzählt Registry-Einträge, die der Index überhaupt nicht sehen kann, die keine Abfrage jemals zurückgeben kann. Die Registry zu aktualisieren ist keine Antwort auf beides: Ihr Manifest hat eine 24-Stunden-TTL und heilt sich selbst, während die Vektoren ein separat veröffentlichtes Artefakt sind, das in~/.hyperframes/catalog/abgerufen wird. Ein erneuter Lauf mit--on-deviceruft diesen Index erneut ab, wennunindexedüber Null liegt, das ist das Mittel, das dem Benutzer angeboten werden soll. Eine reine Überdeckungsverzerrung (droppedüber Null währendunindexedNull ist) löst den erneuten Abruf nicht aus; das Leeren von~/.hyperframes/catalog/ist der einzige Ausweg daraus. Beide Zählungen beziehen sich auf Namen und nicht auf Ergebnisse, sodass jede dietotal-Anzahl überschreiten kann. -
Wenn eine Suche nichts Installationswürdiges zurückbringt, sag es.
npx hyperframes feedback --search-miss "<die von dir ausgeführte Abfrage>" --wanted "<der von dir benötigte Move>" --tier <die antwortende Stufe>. Du musst diese Zeile nicht selbst zusammenbauen:catalog --querygibt sie vorausgefüllt aus, und jeder--json-Suchumschlag trägt sie alsreport_gapmit bereits korrekter Abfrage und Stufe — fülle--wantedaus und sende sie ab. Dies ist der einzige Pfad, der eine Abfrage irgendwohin sendet, und es ist ein separater bewusster Befehl, damit die einfachecatalog --queryihr Versprechen hält, nichts zu senden. Melde auf beiden Stufen, wann immer die Ergebnisse die Sache nicht tun; warte 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 reist im Bericht mit, sodass eine Vokabular-Lücke von einer Bedeutungs-Lücke unterscheidbar bleibt, ohne dass du beurteilen musst, welche du getroffen hast. Was zurückkommt, ist eine Liste von Moves, 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 Elementname. Es trägt keine Bewertung und landet nie in der Bewertungsmetrik. -
Biete die Offline-Stufe an; aktiviere sie niemals stillschweigend. Ein einmaliger ~33-MB-Download (ein quantisierter ONNX-Build von
bge-small-en-v1.5plus sein Tokenizer, auf eine feste Revision gepinnt) und die Katalogvektoren aus der Registry, beide unter~/.hyperframes/zwischengespeichert, werden weder dem Projekt noch irgendeinem Paket hinzugefügt. Einmal zwischengespeichert sortiert es 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 wird nur auf einem TTY ausgelöst. Unter--jsongibt es keine Eingabeaufforderung, aber eine Suche, die nichts gefunden hat, platziert die gleiche Frage inwarnings, lies also dieses Array und übergib die Entscheidung selbst an den Benutzer. Wenn die Person fragt, was der Download ist, warum dieses Modell oder was das Gerät verlässt, verweise sie auf https://hyperframes.heygen.com/developers/catalog-search. -
Bevorzuge
--jsonfür Agenten- und CI-Aufrufe. Server-Modusrender,previewundplayliefern keine normale JSON-Ausgabe;preview --selection --jsonundpreview --context --jsonsind Ausnahmen im Abfrage-Modus. -
doctor --jsonwird immer mit Exit 0 beendet. Prüfe anhand seiner Nutzdaten:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Der Nicht-TTY-Modus ist automatisch und erstellt das zentriert leere Gerüst. Verwende
--examplenur, um von einem benannten Beispiel zu starten. Verwende--non-interactive, um den Nur-Flag-Modus auf einem TTY zu erzwingen. -
Verwende eine
HYPERFRAMES_RUN_IDfür alle Befehle im selben Verifizierungsdurchlauf. -
Wenn der Speicherplatz knapp ist, führe
npx hyperframes cleanaus (--dry-run, um zuerst aufzulisten); es entfernt, was tote Render hinterlassen haben und Leer-Caches, die sich selbst wieder aufbauen, niemals Ausgaben, Quellen oder irgendetwas, das ein laufender Render verwendet. Schreibe QC-Frames in ein temporäres Verzeichnis, nicht in das Projekt. -
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 der 200 MB Upload-Grenze nähert oder diese überschreitet, verwende
cloud render --dry-run --jsonund folge der.hyperframesignore-Untersuchung inreferences/cloud.md. Ignoriere niemals ein Asset nur, weil es groß ist. -
Rendere niemals nur, weil Prüfungen bestanden sind. Mache eine Pause bei der endgültigen Vorschau 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, andernfalls 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 Kontext-Slices an, die du benötigst; verwende --context-detail full nur für berechnete Styles oder bearbeitbare Text-Metadaten. Vollständiges Verhalten und Fehlercodes findest du in references/preview-render.md.
Render-Wahlmöglichkeiten
| Bedarf | Befehl |
|---|---|
| Schnelle lokale Iteration | npx hyperframes render --quality draft |
| Erste echte Kodierung | npx hyperframes render --quality looks --output out.mp4 |
| Endgültige lokale Auslieferung | npx hyperframes render --quality delivery --output out.mp4 |
| Reproduzierbarer Container-Render | `npx hyperframes render -- |