HyperFrames Ops

Was macht HyperFrames Ops?

Beantworte Umgebungsfragen grundsätzlich erst, nachdem du die Datei experience.local.md im selben Verzeichnis gelesen hast, um die aktuellsten lokalen Fakten (Proxy-Befehle, Versions-Snapshots, historische QA) zu erhalten.

Null: Warum eine separate Ops-Schicht nötig ist

Skills von Drittanbietern beschreiben oft nur generische Fähigkeiten und können das Netzwerk, den Proxy, die Node-/FFmpeg-Version, den Font-Cache, den Login-Status und die Tool-Kombination jedes einzelnen Rechners nicht vorhersehen. Eine direkte Modifikation des offiziellen Skills würde zu Update-Konflikten führen und lokale Fakten mit den generischen Upstream-Beschreibungen vermischen.

Daher werden die beiden Schichten getrennt:

• Die offiziellen Skills sind die Fähigkeitsquellen, die aktualisierbar und ersetzbar bleiben.
• hyperframes-ops ist die lokale Anpassungsschicht, die Best Practices, Kompatibilitätsunterschiede, Fehlermodi und validierte Workarounds dokumentiert.
• Bei kreativen Problemen lies zuerst den offiziellen Skill; bei Problemen mit der Umgebung, Kombination, Version oder lokaler Anpassung lies diesen Skill.
• Wenn Upstream-Updates alte Erfahrungen ungültig machen, markiere sie in den lokalen Erfahrungen als ungültig und validiere neu; überschreibe neues Verhalten nicht mit alten Erfahrungen.

Eins: Projektidentität (generalisierte Fakten)

• HyperFrames ist das offizielle HeyGen Open-Source-Projekt: github.com/heygen-com/hyperframes, npm-Paketname hyperframes
• Zweck: CLI (npx hyperframes), das HTML verwendet, um Video-Compositing zu erstellen und über headless Chrome in mp4 zu rendern
• Systemvoraussetzungen: Node.js >= 22, FFmpeg

Zwei: Offizieller Skill-Verteilungsmechanismus

• Offizielle Skills werden zusammen mit dem CLI im selben Repository verwaltet, versioniert verteilt; das Manifest befindet sich im Stammverzeichnis des Repositorys: https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json
• Zusammensetzung: Kernset (hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes) + Workflow-Set (general-video, slideshow, motion-graphics, music-to-video, pr-to-video, product-launch-video, website-to-video, faceless-explainer, talking-head-recut, embedded-captions, media-use, figma). Die tatsächliche Ausgabe von skills check ist maßgeblich.
• Management-Befehle:
  • npx hyperframes skills check – Überprüft Versionen gegen das Manifest
  • npx hyperframes skills update – Aktualisiert alle installierten Skills und entfernt offiziell dekommissionierte
  • npx hyperframes init – Erzwingt Synchronisation der Skills auf den neuesten Stand (--skip-skills ist derzeit offiziell deaktiviert)
• Installationsort: Globales ~/.claude/skills/ (CLI erkennt claude-code automatisch)
• Namenssicherheit: Die Bereinigungslogik von skills update basiert auf der Lock-Datei und der "Herkunftszuordnung". Sie löscht nur Skills, die aus dem offiziellen Repository stammen und dekommissioniert wurden. Dieser Skill beginnt zwar mit hyperframes-, gehört aber nicht zur offiziellen Lock-Zuordnung und wird daher nicht fälschlicherweise vom offiziellen Updater gelöscht

Drei: Troubleshooting-Routing

Symptom	Routing
skills check/update/init wirft AbortError (fetchManifest-Timeout)	Netzwerkproblem: CLI verwendet Node's eingebautes fetch, um auf raw.githubusercontent.com zuzugreifen; bei direkter Verbindung muss ein Proxy verwendet werden. Lies experience.local.md, um den sofortigen Befehl für diesen Rechner zu erhalten
Andere Netzwerkfehler von npx hyperframes	Wie oben; beachte, dass Node's eingebautes fetch (undici) standardmäßig NICHT die HTTP_PROXY-Umgebungsvariable liest. Für Node 24+ muss NODE_USE_ENV_PROXY=1 (oder --use-env-proxy) gesetzt werden
Render-/Vorschau-Umgebungsfehler	npx hyperframes doctor, npx hyperframes browser zur Selbstprüfung; stelle sicher, dass Node >= 22 und FFmpeg verfügbar sind
Skill verhält sich wie alte Version	skills check zeigt Versionsunterschiede; skills update gleicht sie an
heygen auth login --oauth Token-Austausch schlägt fehl (api2.heygen.com connection refused) oder Musikbibliothek timeout	heyGen CLI ist ein Go-Programm und erkennt HTTP(S)_PROXY-Umgebungsvariablen (im Gegensatz zu Node fetch, kein zusätzlicher Schalter nötig); in eingeschränkten Netzwerken müssen alle heyGen-Befehle mit Proxy ausgeführt werden. Der OAuth-Callback-Dienst lebt nur 5 Minuten und benötigt eine interaktive Shell (Hintergrund/nohup-Start führt zu Timeout, da der Callback nicht empfangen wird). Rechnerspezifische Befehle siehe experience.local.md
Schriftart wird falsch dargestellt (Titel werden breiter, überlaufen den Container, lint/inspect zeigt alles grün)	Die eingebauten 18 Schriftarten werden zur Laufzeit bei Bedarf aus dem Netz geladen (@fontsource → ~/.cache/hyperframes/fonts); bei Fehlschlag erfolgt stilles Fallback auf Systemfonts. Lösung für eingeschränkte Netzwerke: lade woff2-Dateien herunter und hoste sie explizit mit @font-face im Projekt selbst
Kreative Fragen (Wie erstelle ich Compositing, Animationen, Rendering-Parameter)	Nicht zuständig für diesen Skill; gehe zum offiziellen hyperframes-Einstiegsskill mit seiner Routing-Tabelle

Vier: Erfahrungs-Rückschreibeprotokoll

• Schreibe in experience.local.md (rechnerprivat, durch .gitignore im selben Verzeichnis ignoriert): Neu entdeckte Fallstricke und validierte Lösungen, Versions-/Installationsstatus-Snapshots (mit Datum), rechnerspezifische Befehle, Proxy- und Netzwerkfakten, historische QA
• Schreibe zurück in diese SKILL.md (in Git, teilbar): Änderungen am offiziellen Mechanismus (Verteilungsart, Befehlssemantik, Bereinigungslogik), neue generalisierte Troubleshooting-Routen
• Entscheidungskriterium: Gilt die Erfahrung auch auf einem anderen Rechner? → In SKILL.md. Gilt sie nur für diesen Rechner? → In experience.local.md.
• Nach jedem Aufruf und gelöstem HyperFrames-Umgebungsproblem werden die Schlussfolgerungen gemäß dieser Schichtung zurückgeschrieben, mit Datumsangabe.