Plugin-Installation: Führe vor Setup- oder Freshness-Befehlen die Plugin-Ausführungsregeln aus, wenn sich dieses Skill in einem HyperFrames-Plugin befindet. Bei eigenständigen Installationen gelten die unten stehenden Update-Anweisungen.
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>(zentriert, leer). Oder eine Website erfassen. Übergib--example=<name>nur, um von einem benannten Beispiel zu starten. - Die richtige Bewegung finden: Falls die Anfrage ein Asset, einen Sound, ein Bild, eine Stimme oder eine schnelle visuelle Bearbeitung nennt, löse sie über
/media-useauf, bevor du einen Plan vorschlägst. Andernfalls suche, bevor du Bewegungen von Hand erstellst, nach einem Primitive, das dies bereits tut:npx hyperframes catalog --query "Einen Titel Zeile für Zeile einblenden". 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 von Hand, wenn nichts passt. - Erstellen: Schreibe die Komposition mit
/hyperframes-core. Um zu erfahren, was in der Timeline eines Projekts ist (Tracks, Clips, Starts, Enden, was abgespielt wird), führenpx hyperframes timeline --jsonaus, anstattindex.htmlund jede Unterkompositionsdatei zu lesen: verschachtelte Zeilen führen absoluteabsStart/absEndder Haupt-Timeline und ihre zugehörigefile, nicht nur ihre lokale, pro Unterkompositionszeit. Bevorzuge--jsongegenüber der Textform; es verbraucht weniger Tokens 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. - Endgültige Prüfung ausführen: Führe
npx hyperframes checkaus; es führt lint vor dem Öffnen des Browsers erneut aus. Hänge keinen redundanten, eigenständigen lint-Befehl voran. Füge--snapshotsfür kommentierte Übersichtsbilder und zum Finden von Bildausschnitten hinzu. - Unterkompositionen überprüfen: Wenn
index.htmldata-composition-srceinbindet, erfasse Zwischenpunkt-Snapshots und überprüfe jede eingebundene Szene. - Endgültige Studio-Vorschau öffnen: Führe
npx hyperframes preview --backgroundaus, überprüfe, ob die URL HTTP 200 zurückgibt, übergib die Timeline-Projekt-URL dem Benutzer und frage, ob überarbeitet oder gerendert werden soll. Halte sie bis zum Ende der Überprüfung geöffnet. - Nur nach Genehmigung rendern: Verwende
--quality draftwährend der Iteration,--quality looksfür die erste echte Kodierung (CLI-Standard) und--quality deliveryfür die endgültige Auslieferung. - Ausgabe überprüfen: Bestätige, dass die Datei existiert und nicht leer ist. Lies die zweite Zeile der Render-Zusammenfassung (
beginframevsscreenshot, GPU, Stufen-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 der rootdata-duration.
Projekthistorie in deinem Zug
Jeder Schreibvorgang im Projekt wird als Eintrag gespeichert, der rückgängig gemacht werden kann. Verwende es nur zu zwei Zeitpunkten, niemals bei jedem Schritt:
- Beginn eines Zuges:
npx hyperframes history begin --who <dein-name> --label "<was du 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. - Eine Prüfung ist fehlgeschlagen, oder die Person sagt, es sei schlimmer geworden:
npx hyperframes history undo --who <dein-name>macht deinen neuesten Zug rückgängig und lässt die Bearbeitungen der Person in Ruhr. Bearbeite nicht von Hand zurück zurück. Bei einem Konflikt wird mit Exit-Code 2 beendet und beide Optionen ausgegeben.
Beende jeden Zug mit npx hyperframes history end, damit deine Schreibvorgänge als deine gelesen werden, nicht als "Außerhalb der App geändert". Während ein Zug geöffnet ist, zählt jeder Schreibvorgang im Projekt als deiner, bis 10 Minuten ohne einen solchen vergangen sind; danach endet der Zug von selbst.
Erforderliche Ersteller-Bearbeiten-Kreuzverweise
- Bevor du einen Zoom, Punch-In/Punch-Out, Reframe, Kamerabewegung oder eine Keyframe-Bewegung erstellst oder diagnostizierst, lies zuerst
/hyperframes-keyframes. - Vor
hyperframes keyframeslies/hyperframes-keyframes; der Befehl zeigt Animationsverläufe an und diagnostiziert keine Clip-Schnitte. - Für einen Schnitt, Trimmen, Splice, Neuanordnung oder Quell-Timing-Bearbeitung lies
/hyperframes-coreund verwende dessen Clip/Timeline-Vertrag. - Für Ein-/Ausblenden, Crossfade, Track-Verstärkung, Lautstärkeautomatisierung, Ducking, Sprachüberlagerung oder FX auf platziertem Audio lies
/hyperframes-audio. Lade core zusammen damit, wenn auch die Clip-Platzierung oder Bild-Timings geändert werden. - Eine Anfrage, die ein Asset, einen Sound, ein Bild, eine Stimme oder eine schnelle visuelle Bearbeitung nennt, wird über
/media-useaufgelöst, bevor ein Plan vorgeschlagen wird. Kopiere das Ersteller-Bearbeiten-Markup aus/hyperframes-core→references/creator-editing-recipes.md.
# Schnelle Iterationsprüfung; während des Erstellens nach Bedarf wiederholen.
npx hyperframes lint
# Erforderliche Endkontrolle; beinhaltet 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 Browsersitzung und einen Seek-Durchlauf, um Laufzeitfehler, fehlgeschlagene Anfragen, Layout, *.motion.json-Zusicherungen und WCAG-Kontrast zu prüfen. Dauerhafte Befunde blockieren den Exit-Code; vorübergehende Ein- oder Austrittsbefunde informieren nur. Verwende --strict, um Warnungen zu blockieren. validate, inspect und layout bleiben Aliase aus Kompatibilitätsgründen, dürfen aber nicht in neuen Anweisungen oder Skripten vorkommen.
Vorschau vor dem Rendern
Öffne die endgültige Kompositionsvorschau (#project/<name>) erst, nachdem check bestanden wurde, um die zusammengestellte Timeline zu überprüfen. Der Plan im Chat und das storyboard.html-Skizzenblatt sind keine Genehmigung des endgültigen Videos. Das Rendern erfordert immer die endgültige Genehmigung, die in hyperframes/references/review-loop.md definiert ist.
Sub-Composition-Smoke-Test
Statische Audits können nicht jeden Mount-Fehler erkennen. Wenn das Projekt Sub-Compositions verwendet, erfasse mindestens einen sichtbaren Mittelpunkt für jeden Host-Slot:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Behandle winzige, ungestylte Inhalte, leinwandgroße Icons, fehlende Hero-Elemente oder Timeout bei Timeline-Registrierung als renderblockierende Mount-Fehler. Siehe hyperframes-core/references/sub-compositions.md für die entsprechenden Korrekturen.
Agentenkonventionen
-
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 niemals irgendwohin gesendet. Standardmäßig bewertet sie nach Vokabular, das mit dem Namen, Titel, der Beschreibung und den Tags des Elements geteilt wird, was jede Formulierung übersieht, die nicht die eigene Wortwahl des Katalogs verwendet. Füge--on-devicehinzu, um stattdessen nach Bedeutung zu bewerten (siehe die Offline-Stufe unten). -
Frage auf Englisch ab, auch wenn das Video es nicht ist. Beide Stufen indexieren einen englischen Katalog, daher erzeugt eine Abfrage in einer anderen Schrift keine durchsuchbaren Begriffe und gibt nichts zurück. Beschreibe die Bewegung auf Englisch; der Bildschirmtext bleibt in der Sprache, die das Video benötigt.
No searchable words in querybedeutet genau dies und ist keine fehlende Komponente, also melde es nicht als Katalog-Lücke. -
Lies, welche Stufe geantwortet hat; schließe niemals von den Ergebnissen darauf. Bei
--jsonträgt der Umschlagquery,tier(on-deviceoderwords),tier_detail,dropped,unindexed,shown,totalundresults, plustop_score, wenn die antwortende Stufe eine erzeugt, undwarnings, wenn eine Stufe angefordert wurde und nicht ausgeführt werden konnte, oder wenn eine Suche nichts zurückgab und eine bessere Stufe noch auf die Zustimmung von jemandem wartet. Ein schwaches Ergebnis beiwordsist erwartet; das gleiche Ergebnis beion-deviceist ein Fehler.top_scoreist nur für On-Device und hat keinen Schwellenwert dahinter: Der Ranker gibt den gesamten Katalog für jede Abfrage in einer bestimmten Reihenfolge zurück, also lies es als Hinweis und nicht als Bestehen/Nichtbestehen. -
droppedundunindexedsind gegensätzliche Abweichungen zwischen der Registry und dem On-Device-Index, und eine Neufassung 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-Bewegungen, die der Index überhaupt nicht sehen kann, was 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. Die erneute Ausführung mit--on-deviceruft diesen Index erneut ab, wennunindexedgrößer als Null ist, also ist dies das Mittel, das dem Benutzer gegeben werden sollte. Eine reine Überabdeckungsabweichung (dropped> 0 währendunindexed= 0) löst den erneuten Abruf nicht aus; das Löschen von~/.hyperframes/catalog/ist der einzige Weg daraus. Beide Zählungen sind Namen und nicht Ergebnisse, daher kann jedetotalüberschreiten. -
Wenn eine Suche nichts Installationswürdiges zurückbringt, sag es.
npx hyperframes feedback --search-miss "<die von dir ausgeführte Abfrage>" --wanted "<die benötigte Bewegung>" --tier <die antwortende Stufe>. Du musst diese Zeile nicht zusammenbauen:catalog --querygibt sie vorausgefüllt aus, und jeder--json-Suchumschlag trägt sie alsreport_gapmit der bereits korrekten 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 einfachescatalog --querysein Versprechen hält, nichts zu senden. Melde auf jeder Stufe, wenn die Ergebnisse die Sache nicht tun; warte nicht auf die On-Device-Stufe, die einen zugestimmten 33 MB Download benötigt und daher in den meisten Agentenläufen deaktiviert ist – darauf zu warten bedeutet, niemals zu melden. Die Stufe reist im Bericht mit, sodass ein Vokabularfehlschlag von einem Bedeutungsfehlschlag unterscheidbar bleibt, ohne dass du beurteilen musst, welchen du getroffen hast. Zurück kommt eine Liste von Bewegungen, die der Katalog noch nicht hat, direkt gelesen, nicht aus Installationszahlen abgeleitet, daher ist die relevante Formulierung der gewünschte Effekt, nicht der vorgestellte Item-Name. 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 quantisiertes ONNX-Build von
bge-small-en-v1.5plus sein Tokenizer, auf eine feste Revision festgelegt) und die Katalogvektoren aus der Registry, beide unter~/.hyperframes/zwischengespeichert, werden weder zum Projekt noch zu einem Paket hinzugefügt. Nach dem Caching bewertet 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 feuert nur auf einem TTY. Unter--jsongibt es keine Eingabeaufforderung, aber eine Suche, die nichts gefunden hat, platziert die gleiche Frage inwarnings, also lies dieses Array und übergib die Entscheidung selbst an den Benutzer. Wenn die Person fragt, was der Download ist, warum dieses Modell oder was die Maschine verlässt, verweise sie auf https://hyperframes.heygen.com/developers/catalog-search. -
Bevorzuge
--jsonfür Agenten- und CI-Aufrufe. Die Servermodirender,previewundplaybieten keine normale JSON-Ausgabe;preview --selection --jsonundpreview --context --jsonsind Ausnahmen im Abfragemodus. -
doctor --jsonbeendet sich immer mit Exit-Code 0. Prüfe auf seine Nutzlast:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Der Nicht-TTY-Modus ist automatisch und erstellt das zentrierte leere Gerüst. Übergib
--examplenur, um von einem benannten Beispiel zu starten. Verwende--non-interactive, um den Nur-Flag-Modus auf einem TTY zu erzwingen. -
Verwende eine einzige
HYPERFRAMES_RUN_IDfür alle Befehle im selben Verifikationsloop. -
Wenn der Speicherplatz knapp ist, führe
npx hyperframes cleanaus (--dry-run, um zuerst aufzulisten); es entfernt, was tote Render hinterlassen haben und im Leerlauf befindliche Caches, die sich selbst neu 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 redigieren das Home-Verzeichnis als
$HOME; versuche nicht, die Redaktion rückgängig zu machen. -
Wenn ein gehostetes Cloud-Projekt sich dem 200 MB Upload-Limit nähert oder es überschreitet, verwende
cloud render --dry-run --jsonund befolge die.hyperframesignore-Untersuchung inreferences/cloud.md. Ignoriere niemals ein Asset nur, weil es groß ist. -
Rendere niemals nur, weil die Prüfungen bestanden sind. Halte in der endgültigen Vorschau an 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 benötigten Kontext-Slices an; 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-Auswahl
| 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 --docker --strict --output out.mp4 |
| Lokales variablengesteuertes Batch-Rendering | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen-gehostetes Zero-Infrastructure-Rendering | npx hyperframes cloud render |
| Selbstverwaltetes verteiltes AWS-Rendering | npx hyperframes lambda render ... |
Render-Ausgabe überprüfen
# Prüfe, ob die Ausgabedatei existiert und nicht leer ist
test -s out.mp4 && echo "Datei existiert und ist nicht leer" || echo "Ausgabedatei fehlt oder ist leer"
# Detaillierte Medieninformationen
ffprobe -v error -show_format -show_streams out.mp4
Fehlerbehebung
| Problem | Diagnostic-Befehl |
|---|---|
| Allgemeine Laufzeitfehler | npx hyperframes doctor |
| Lizenz- oder Auth-Probleme | npx hyperframes auth status |
| Projekt-Inspektion | npx hyperframes info |
| Upgrade-Check | npx hyperframes upgrade --check |
| Cache leeren | npx hyperframes clean |
| Vollständige CLI-Hilfe | npx hyperframes --help |
Telemetrie und Feedback
- Telemetrie wird mit
npx hyperframes telemetry statusgesteuert. - Einreichungen nach einer verpassten Katalog-Suche mit
npx hyperframes feedback --search-miss ...helfen, die Suchergebnisse zu verbessern.