Native KI

Mit Ihrem Agenten an einem Beam-Projekt arbeiten

Beam CLI ermöglicht einem externen Agenten, echte Screenshot- und Videoprojekte zu prüfen und zu bearbeiten. Lassen Sie ihn das Dokument lesen, eine Änderung vornehmen und das Ergebnis kontrollieren. Dasselbe Projekt bleibt in Beam bearbeitbar.

• Bearbeiten Sie native Inhalte: Kürzen oder verschieben Sie Clips, passen Sie Zooms und Hintergründe an oder ordnen Sie Screenshot-Ebenen, Gruppen und Effekte.
• Erstellen Sie HTML- und TypeScript-Grafiken, optional mit Vue, GSAP oder WebGL, und veröffentlichen Sie sie als Ebene.
• Prüfen Sie den Canvas in Echtzeit, machen Sie eine Änderung rückgängig und exportieren Sie mit Beams Renderer.

Kommandozeilenstarter einrichten

Verwenden Sie den mit Beam gelieferten Starter beam-cli. Ersetzen Sie bei einem Quellcode-Checkout beam-cli durch bun run beam und führen Sie den Befehl im Stammverzeichnis des Repositorys aus. Listen Sie zunächst die Tools auf und lesen Sie ihre Schemas; diese Suchbefehle funktionieren auch ohne die Desktop-App.

Toolaufrufe akzeptieren JSON direkt in der Befehlszeile, eine mit @ gekennzeichnete Argumentdatei oder einen Bindestrich für JSON über stdin. Ergebnisse gehen an stdout, Fehler an stderr mit einem Exitcode ungleich null. Inline-Beispiele verwenden POSIX-Anführungszeichen. Unter Windows vermeiden Argumentdateien Unterschiede bei Shell-Anführungszeichen. Pfade in einer Datei werden relativ zu dieser Datei aufgelöst; Inline-Pfade relativ zum Arbeitsverzeichnis.

beam-cli tools list
beam-cli tools describe html.publish
beam-cli docs agent
beam-cli docs html
beam-cli docs gradients
beam-cli docs commands
beam-cli commands

Beam-Skills installieren

Öffnen Sie im Projekt, in dem Ihr Agent arbeitet, ein Terminal und installieren Sie die Skills. Der Standardzielordner ist .agents/skills innerhalb dieses Projekts. Global wird nichts installiert, sofern Sie nicht ausdrücklich --global übergeben. Laden Sie anschließend die Skills des Agenten neu oder starten Sie eine neue Sitzung.

Das Paket enthält zehn spezialisierte Skills. Installieren Sie alle mit dem folgenden Befehl oder ergänzen Sie Namen für eine Auswahl, etwa beam-cli beam-design beam-composition beam-animation. Verwenden Sie für einen agentspezifischen Ordner --agent claude, --agent cursor oder --agent gemini; auch diese Ordner bleiben im aktuellen Projekt. Falls Ihre installierte CLI Skills noch nicht kennt, verwenden Sie einen neueren Beam-CLI-Build oder bun run beam aus einem aktuellen Beam-Quellcode-Checkout.

beam-cli skills install

Skills prüfen und aktualisieren

Führen Sie diese Befehle im selben Projektordner aus. check vergleicht die installierten Dateien mit dem Paket in BeamRecorder/Beam, ohne Änderungen vorzunehmen. Der JSON-Bericht nennt aktuelle, fehlende, veraltete, geänderte oder kollidierende Skills. Wenn ein ausgewählter Skill nicht aktuell ist, endet der Befehl mit Exitcode 1. update lädt das aktuelle Paket einschließlich fehlender Skills herunter und schützt Ihre lokalen Änderungen.

Das gepflegte Paket befindet sich im Beam-GitHub-Repository unter .skills/Beam-cli. Dateien werden vor der Installation überprüft. Updates erfolgen ausdrücklich; normale Bearbeitungsbefehle suchen nicht nach neuen Skills. Verwenden Sie --ref mit einem Tag oder Commit, wenn Sie eine bestimmte Version festschreiben möchten. Hinweise zu benutzerdefinierten Ordnern und geschützten lokalen Änderungen finden Sie in den Docs-Skills.

beam-cli skills check
beam-cli skills update
beam-cli docs skills

Projekt öffnen und Zustand auslesen

Starten Sie Beam und listen Sie die Projekte auf. Das Beispiel erstellt einen transparenten Screenshot-Canvas. Ersetzen Sie PROJECT_UUID durch die zurückgegebene ID, öffnen Sie das Projekt und warten Sie, bis projects.list diese ID unter open aufführt. Rufen Sie anschließend documents.snapshot für das aktuelle Dokument und seine Revision ab.

Verwenden Sie für Studio sowohl beim Erstellen als auch beim Öffnen kind: video. projects.open öffnet normalerweise einen neuen Editor; disposition: reuse ersetzt den aktiven Editor. Wenn mehrere Beam-Instanzen laufen, ergänzen Sie --instance PID mit einer ID aus instances.

beam-cli instances
beam-cli tools call projects.list
beam-cli tools call projects.create '{"kind":"image","name":"Feature card","width":1920,"height":1080}'
beam-cli tools call projects.open '{"projectId":"PROJECT_UUID","kind":"image"}'
beam-cli tools call documents.snapshot '{"projectId":"PROJECT_UUID"}'

Screenshot-Ebene bearbeiten

Verwenden Sie dieses Beispiel mit einem Projekt, das ein aufgenommenes Bild enthält, nicht mit dem oben erstellten leeren Canvas. Speichern Sie es als edit.json und ersetzen Sie SCREENSHOT_UUID sowie expectedRevision durch Werte aus documents.snapshot. Die aufgenommene Quellebene hat die ID image; die Transaktion benennt sie um und fügt einen 3D-Winkel hinzu.

Finden Sie weitere Ebenen-IDs im Snapshot. Die Befehlsschnittstelle unterstützt Platzierung, Zuschnitt, Gruppierung, Reihenfolge, Farbe, Effekte sowie PNG-/WebP-Einstellungen. Lesen Sie vor der Bearbeitung das Payload-Schema. Ein effects-Array ersetzt den gesamten Stapel; geben Sie daher vorhandene Effekte an, die erhalten bleiben sollen.

{
  "projectId": "SCREENSHOT_UUID",
  "expectedRevision": 0,
  "operationId": "screenshot-perspective-1",
  "commands": [
    {
      "type": "still.layer.rename",
      "payload": {
        "layerId": "image",
        "name": "Product capture"
      }
    },
    {
      "type": "still.layer.compositing",
      "payload": {
        "layerId": "image",
        "patch": {
          "rotation3d": {
            "x": 6,
            "y": -12,
            "perspective": 1200
          }
        }
      }
    }
  ]
}

Vorhandenen Videoclip bearbeiten

Verwenden Sie diese Transaktion stattdessen in edit.json für ein Videoprojekt mit einem Clip. Ersetzen Sie VIDEO_UUID, expectedRevision und CLIP_ID anhand eines aktuellen Snapshots. Sie stellt eine Hintergrundunschärfe ein und verschiebt den Clip auf Sekunde eins der Zeitleiste.

Videobefehle unterstützen außerdem Kürzen, Teilen, Wiedergabegeschwindigkeit, Lautstärke, Untertitel, Elemente, Szenengruppen, Eigenschaftsanimation und Zooms. assets.import kopiert Medien in das Projekt; platzieren Sie sie danach mit Dokumentbefehlen in der Zeitleiste.

{
  "projectId": "VIDEO_UUID",
  "expectedRevision": 0,
  "operationId": "video-layout-1",
  "commands": [
    {
      "type": "render.patch",
      "payload": {
        "blurPercent": 12
      }
    },
    {
      "type": "clip.move",
      "payload": {
        "clipId": "CLIP_ID",
        "startMs": 1000
      }
    }
  ]
}

Transaktion anwenden

Wenden Sie edit.json auf das darin beschriebene Projekt an. Die Befehle bilden eine atomare Bearbeitung und einen Rückgängig-Schritt. Ist der Stapel ungültig, wird keine Teiländerung übernommen. Gesperrte Inhalte bleiben geschützt.

Verwenden Sie für jede neue Bearbeitung eine neue operationId. Eine ID darf nur für einen identischen Wiederholungsversuch erneut verwendet werden. Sie können die Änderung in Beam rückgängig machen oder documents.undo/documents.redo mit der aktuellen expectedRevision und einer eindeutigen requestId aufrufen.

beam-cli tools call documents.transact @edit.json

Statische HTML-Karte erstellen

Erstellen Sie composition/index.html anhand des folgenden Beispiels. Bewahren Sie Schriftarten, Styles und Medien lokal auf. HTML und TypeScript funktionieren ohne Vue; installieren Sie importierte Bibliotheken in diesem Quellprojekt.

Eine statische Karte benötigt keine Animationsuhr. Beam wartet auf lokale Schriftarten und die Bilddekodierung. Stellen Sie für eine asynchrone Initialisierung ein ready-Promise auf window.beamComposition bereit.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <style>
      html, body { margin: 0; width: 100%; height: 100%;
        overflow: hidden; background: transparent; }
      .card { position: absolute; inset: 100px; padding: 80px;
        border-radius: 40px; background: #151517; color: white;
        font: 64px sans-serif; }
    </style>
  </head>
  <body><div class="card">Beam feature</div></body>
</html>

Veröffentlichungsanfrage vorbereiten

Speichern Sie publish.json neben dem Kompositionsordner. Verwenden Sie ID und aktuelle Revision des geöffneten Screenshot-Projekts. Width und height geben die Abmessungen des HTML-Canvas in Pixeln an. Für Screenshot-Veröffentlichungen ist durationMs: 0 erforderlich. Verwenden Sie framework: html oder für eine Vue-Quelle vue.

{
  "projectId": "SCREENSHOT_UUID",
  "expectedRevision": 0,
  "entry": "./composition/index.html",
  "width": 1920,
  "height": 1080,
  "durationMs": 0,
  "framework": "html",
  "name": "Feature card"
}

Karte zu Beam hinzufügen

html.publish kompiliert die Quelle, speichert Quelltext und Bundle im Projekt und fügt eine HTML-Ebene ein. Zurückgegeben werden layerId und die neue Revision. Ein Screenshot-Projekt speichert außerdem ein gerendertes PNG dieser Ebene.

Lassen Sie für eine weitere Version derselben Karte die zurückgegebene layerId in publish.json stehen und aktualisieren Sie expectedRevision. Die Aktualisierung erhält Platzierung, Ebenenreihenfolge, Sichtbarkeit und Effekte. Veröffentlichte Quellversionen bleiben im erneut geöffneten Projekt und im Rückgängig-Verlauf verfügbar.

beam-cli tools call html.publish @publish.json

Videoebene mit einer navigierbaren Uhr animieren

Installieren Sie GSAP im Quellprojekt und speichern Sie den folgenden Code als composition/main.ts, um die Karte fünf Sekunden lang zu animieren. Fügen Sie in index.html ein Modulskript für ./main.ts hinzu. Verwenden Sie in publish.json die ID eines geöffneten Videoprojekts, durationMs: 5000 und fps: 30. Entfernen Sie vor der ersten Veröffentlichung in dieses Video die Screenshot-layerId.

Stellen Sie window.beamComposition.seek(timeMs) bereit. Beam fordert genaue Zeitpunkte in Millisekunden an und kann rückwärts suchen. Lassen Sie GSAP pausiert und setzen Sie die Zeit seiner Zeitleiste ausdrücklich. Warten Sie bei Vue auf reaktive Aktualisierungen; zeichnen Sie bei WebGL das vollständige Bild. seek kann für asynchrone Vorbereitung ein Promise zurückgeben.

import { gsap } from 'gsap';

const timeline = gsap.timeline({ paused: true });
timeline.fromTo('.card',
  { opacity: 0, y: 80 },
  { opacity: 1, y: 0, duration: 1 }, 0);
timeline.to('.card', { scale: 1.05, duration: 3 }, 1);
timeline.to('.card', { opacity: 0, duration: 1 }, 4);

Object.assign(window, {
  beamComposition: {
    seek(timeMs: number) {
      timeline.time(timeMs / 1000, false);
    },
  },
});

Quellspeicherungen in Beam in der Vorschau anzeigen

Lassen Sie eine vorhandene layerId in publish.json stehen und starten Sie html watch. Die Quelle wird einmal veröffentlicht; vor weiteren Aktualisierungen wird die aktuelle Revision gelesen. Nach dem Speichern der Quelle wird erneut veröffentlicht. Ctrl+C beendet die Überwachung. Bei Kompilierungs- oder Revisionsfehlern bleibt die zuvor veröffentlichte Ebene verfügbar.

Rufen Sie html.source mit dem HTML-Deskriptor aus documents.snapshot auf, um zum Code einer gespeicherten Ebene zurückzukehren. Kopieren Sie die gespeicherte Quelle vor der Bearbeitung in einen Arbeitsordner; veröffentlichte Quellversionen sind unveränderlich. Die Vorschau kann Anforderungen zusammenfassen, während beim Export jedes angeforderte Zeitleistenbild gerendert wird.

beam-cli html watch @publish.json

Bilder und Schriftarten hinzufügen

• Bewahren Sie lokale Bilder und Schriftarten im Quellordner auf oder geben Sie references-Einträge mit den Feldern name und source an. Beam kopiert diese Dateien in den Ordner references neben der HTML-Datei.
• Fügen Sie für eine Medienreferenz aus einem anderen gespeicherten Projekt dessen projectId hinzu. assets.resolve findet eine projektzugehörige Datei zur Prüfung; html.publish kann sie in das Bundle kopieren.
• Verwenden Sie nativen Text, wenn Sie Formulierungen in Beam bearbeiten möchten: still.layer.add für Screenshots oder clip.insert für Videoelemente. Text in HTML wird im Quellcode geändert.
• fonts.import akzeptiert TTF, OTF, WOFF und WOFF2. Setzen Sie text.style.fontFamily und text.style.fontAssetId auf die zurückgegebene Familie und ID, damit bearbeitbarer Text diese Schrift in Vorschau und Export verwendet.

beam-cli tools call fonts.list
beam-cli tools call fonts.import '{"source":"./fonts/HankenGrotesk.ttf"}'

Ergebnis prüfen und exportieren

Installieren Sie einmalig das Chromium-Backend der CLI oder setzen Sie BEAM_CHROMIUM_EXECUTABLE auf einen kompatiblen Browser. Lassen Sie Beam während des Exports eines geöffneten Projekts mit HTML-Ebenen laufen; Beam stellt deren gerenderte Bilder bereit. Ersetzen Sie die IDs unten und wählen Sie einen Zeitpunkt innerhalb der Videodauer aus.

Screenshot verwendet die PNG-/WebP-Einstellungen seines Dokuments; passen Sie die Ausgabedateiendung an das Format an. Video unterstützt MP4 und WebM mit Ebenen, Untertiteln und Zooms der Komposition. Um ein bestehendes Ziel absichtlich zu ersetzen, geben Sie overwrite: true an.

beam-cli browser install
beam-cli tools call render.export '{"projectId":"SCREENSHOT_UUID","output":"feature.png"}'
beam-cli tools call render.export '{"projectId":"VIDEO_UUID","output":"demo.mp4","format":"mp4"}'
beam-cli tools call render.frame '{"projectId":"VIDEO_UUID","timeMs":2000,"output":"frame.png"}'

Bilddatei ohne Desktop-App bearbeiten

Verwenden Sie ein vorhandenes PNG mit seinen tatsächlichen Abmessungen. Speichern Sie nur das commands-Array der Screenshot-Transaktion in edits.json, und erstellen, bearbeiten und exportieren Sie dann das eigenständige Dokument unten. Dieser Ablauf ändert ein Dateidokument, keinen geöffneten Beam-Editor.

Standalone edit und serve benötigen keine Desktop-App. Für den Export wird das Chromium-Backend der CLI benötigt. Verwenden Sie für ein HTML-Video ohne Editor motion mit einer Jobdatei. beam-cli docs html beschreibt Einstieg, Abmessungen, Dauer in Sekunden, fps und Format.

beam-cli create image capture.png 1920 1080 screenshot.json
beam-cli edit screenshot.json edits.json edited-screenshot.json
beam-cli export edited-screenshot.json finished.png

Verstehen, was lokal ausgeführt wird

Die CLI verbindet sich über einen authentifizierten lokalen Endpunkt mit dem Desktop. Beam rendert lokal. Veröffentlichtes HTML läuft in isolierten Fenstern ohne Node-Zugriff oder Beam-Preload; externe Netzwerkanfragen sind blockiert, daher müssen Ressourcen lokal gebündelt werden.

Sie stellen Agent und Modell bereit. Die Datenverarbeitung hängt vom gewählten Anbieter ab. Beam stellt Dokumentwerkzeuge und eine Rendering-Schnittstelle bereit, aber kein KI-Chat-Abo, keinen MCP-stdio-Server und keine gemeinsame Bearbeitung über das Netzwerk.