AI native

Работете с агента си по проект на Beam

Beam CLI позволява на външен агент да проверява и редактира истински проекти Screenshot и видео. Помолете го да прочете документа, да направи промяна и да провери резултата. Проектът остава редактируем в Beam.

• Редактирайте вградено съдържание: изрязвайте или местете клипове, настройвайте приближавания и фонове или подреждайте слоеве, групи и ефекти в Screenshot.
• Създавайте художествено съдържание с HTML и TypeScript, по избор с Vue, GSAP или WebGL, и го публикувайте като слой.
• Прегледайте платното на живо, отменете редакция и експортирайте с рендериращата система на Beam.

Настройте стартера за командния ред

Използвайте стартера beam-cli, включен в Beam. От изходно хранилище заменете beam-cli с bun run beam и стартирайте от корена на хранилището. Започнете с показване на инструментите и прочитане на схемите им; тези команди за откриване работят и без настолното приложение.

Извикванията на инструменти приемат вграден JSON, файл с аргументи, предшестван от @, или тире за JSON от stdin. Резултатите отиват в stdout; грешките — в stderr с ненулев код за изход. Вградените примери използват POSIX кавички. В Windows файловете с аргументи избягват различията в кавичките на обвивката. Пътищата във файл се разрешават спрямо него; вградените пътища — спрямо работната директория.

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

Отворете терминал в проекта, в който работи агентът ви, и инсталирайте уменията. Местоназначението по подразбиране е .agents/skills в този проект. Нищо не се инсталира глобално, освен ако изрично не подадете --global. След това презаредете уменията на агента или започнете нова сесия.

Пакетът включва десет специализирани умения. Инсталирайте всички с командата по-долу или добавете имена, за да изберете подмножество, например beam-cli beam-design beam-composition beam-animation. За папка, специфична за агент, използвайте --agent claude, --agent cursor или --agent gemini; те също остават в текущия проект. Ако инсталираният CLI все още не разпознава уменията, използвайте по-нова компилация на Beam CLI или bun run beam от актуално изходно хранилище на Beam.

beam-cli skills install

Проверете и актуализирайте уменията

Стартирайте тези команди от същата папка на проекта. check сравнява инсталираните файлове с пакета в BeamRecorder/Beam и не променя нищо. JSON отчетът посочва текущи, липсващи, остарели, променени или конфликтни умения; кодът за изход е 1, ако избрано умение не е актуално. update изтегля текущия пакет, включително липсващите умения, и защитава локалните ви редакции.

Поддържаният пакет се намира в .skills/Beam-cli в GitHub хранилището на Beam. Файловете се проверяват преди инсталиране. Актуализациите се изпълняват изрично; обичайните команди за редактиране не проверяват за нови умения. Използвайте --ref с етикет или commit, когато ви трябва фиксирана версия, и прочетете документацията на уменията за персонализирани папки и защитени локални промени.

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

Отворете проекта и прочетете състоянието му

Стартирайте Beam и изведете списъка с проекти. Примерът създава прозрачно платно Screenshot. Заменете PROJECT_UUID с върнатия идентификатор, отворете го и изчакайте projects.list да включи този идентификатор в open. След това поискайте documents.snapshot за текущия документ и ревизия.

За Studio използвайте kind: video както при създаване, така и при отваряне. Обикновено projects.open отваря нов редактор; disposition: reuse заменя активния редактор. Ако работят няколко екземпляра Beam, добавете --instance PID с идентификатор от 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

Използвайте този пример с проект, съдържащ заснето изображение, а не с празното платно по-горе. Запазете го като edit.json и заменете SCREENSHOT_UUID и expectedRevision със стойностите от documents.snapshot. Изходният слой на заснетото изображение има идентификатор image; транзакцията го преименува и добавя 3D ъгъл.

Намерете идентификаторите на други слоеве в моментната снимка. Интерфейсът на командите поддържа позициониране, изрязване, групиране, подреждане, цвят, ефекти и настройки PNG/WebP. Прочетете схемата на данните преди редактиране. Масив effects заменя целия стек, затова включете съществуващите ефекти, които искате да запазите.

{
  "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
          }
        }
      }
    }
  ]
}

Редактирайте съществуващ видеоклип

За видео проект с клип използвайте вместо това тази транзакция като edit.json. Заменете VIDEO_UUID, expectedRevision и CLIP_ID със стойности от нова моментна снимка. Тя задава замъгляване на фона и премества клипа на една секунда във времевата линия.

Командите за видео обхващат и изрязване, разделяне, скорост на възпроизвеждане, сила на звука, надписи, елементи, групи сцени, анимация на свойства и приближавания. assets.import копира медиите в проекта; след това използвайте командите за документи, за да ги поставите във времевата линия.

{
  "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
      }
    }
  ]
}

Приложете транзакция

Приложете edit.json към описания в него проект. Командите образуват една атомарна редакция и една стъпка за отмяна: ако пакетът е невалиден, частични редакции не се записват. Заключеното съдържание остава защитено.

Задайте нов operationId за всяка нова редакция. Използвайте същия идентификатор само при идентичен повторен опит. Можете да отмените в Beam или да извикате documents.undo/documents.redo с текущия expectedRevision и уникален requestId.

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

Създайте статична HTML картичка

Създайте composition/index.html с примера по-долу. Съхранявайте шрифтовете, стиловете и медиите локално. HTML и TypeScript работят и без Vue; инсталирайте всички импортирани библиотеки в това изходно хранилище.

Статичната картичка не се нуждае от часовник за анимация. Beam изчаква локалните шрифтове и декодирането на изображенията. За асинхронна инициализация задайте готовност чрез promise в window.beamComposition.

<!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>

Подгответе заявката за публикуване

Запазете publish.json до папката composition. Използвайте идентификатора и текущата ревизия на отворения проект Screenshot. Width и height са размерите на HTML платното в пиксели. За публикации Screenshot задайте durationMs: 0. Използвайте framework: html или vue за източник Vue.

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

Добавете картичката в Beam

html.publish компилира източника, съхранява кода и пакета му в проекта и вмъква HTML слой. Връща layerId и новата ревизия. Проект Screenshot също запазва рендиран PNG на слоя.

За нова версия на същата картичка оставете върнатия layerId в publish.json и обновете expectedRevision. Обновяването запазва разположението, реда на слоевете, видимостта и ефектите. Публикуваните версии на източника остават достъпни за повторно отворения проект и историята на отмяната.

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

Анимирайте видео слой с часовник, който може да се превърта

За да анимирате картичката за пет секунди, инсталирайте GSAP в изходния проект и запазете кода по-долу като composition/main.ts. Добавете към index.html модулен скрипт за ./main.ts. В publish.json задайте идентификатор на отворен видео проект, durationMs: 5000 и fps: 30. Преди първото публикуване във видеото премахнете Screenshot layerId.

Задайте window.beamComposition.seek(timeMs). Beam иска точни времена в милисекунди и може да превърта назад. Оставете GSAP на пауза и задавайте изрично времето на времевата му линия. При Vue изчакайте реактивните обновявания; при WebGL изчертайте готовия кадър. seek може да връща promise за асинхронна подготовка.

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);
    },
  },
});

Прегледайте запазванията на източника в Beam

Оставете съществуващ layerId в publish.json и стартирайте html watch. Той публикува веднъж, преди следващи обновявания прочита актуалната ревизия и публикува отново след запазване на източника. Ctrl+C спира наблюдението. Грешка при компилиране или ревизия оставя предишния публикуван слой наличен.

За да получите кода на запазен слой, извикайте html.source с HTML описанието от documents.snapshot. Копирайте съхранения източник в работна папка, преди да го редактирате; публикуваните версии са неизменяеми. Прегледът може да обединява заявки, докато експортирането рендира всеки поискан кадър от времевата линия.

beam-cli html watch @publish.json

Добавете изображения и шрифтове

• Съхранявайте локалните изображения и шрифтове в изходната папка или подайте записи references с полета name и source. Beam копира тези файлове в references до HTML файла.
• За препратка към медия в проект от друг запазен проект включете projectId. assets.resolve намира файл, собственост на проекта, за проверка; html.publish може да го копира в пакета.
• Използвайте вграден текст, когато искате да редактирате формулировката в Beam: still.layer.add за Screenshot или clip.insert за видео елементи. Текстът в HTML се редактира в изходния код.
• fonts.import приема TTF, OTF, WOFF и WOFF2. Задайте text.style.fontFamily и text.style.fontAssetId на върнатите семейство и идентификатор, за да използва редактируемият текст този шрифт в прегледа и експорта.

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

Проверете и експортирайте резултата

Инсталирайте веднъж бекенда Chromium на CLI или задайте BEAM_CHROMIUM_EXECUTABLE към съвместим браузър. При експортиране на отворен проект с HTML слоеве оставете Beam да работи: той предоставя рендираните кадри. Заменете идентификаторите по-долу и изберете време на кадъра в рамките на продължителността на видеото.

Screenshot използва настройките PNG/WebP на документа; разширението на изхода трябва да съответства на този формат. Видео поддържа MP4 и WebM със слоевете, надписите и приближаванията на композицията. За умишлено заместване на съществуващо местоназначение подайте overwrite: true.

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"}'

Редактирайте файл с изображение без настолното приложение

Започнете със съществуващ PNG и действителните му размери. Запазете само масива commands от транзакцията Screenshot като edits.json, след което създайте, редактирайте и експортирайте самостоятелния документ по-долу. Този процес променя документ във файл, а не отворен редактор на Beam.

Самостоятелните edit и serve не изискват настолното приложение. Експортирането изисква бекенда Chromium на CLI. За HTML видео без редактор използвайте motion с файл на задача; beam-cli docs html описва входа, размерите, продължителността в секунди, fps и формата.

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

Разберете какво работи локално

CLI се свързва с настолното приложение чрез удостоверена локална крайна точка. Beam рендира локално. Публикуваният HTML работи в изолирани прозорци без достъп до Node или preload на Beam; външните мрежови заявки са блокирани, затова включете ресурсите локално.

Вие предоставяте агента и модела. Обработката на данните им зависи от избрания доставчик. Beam предоставя инструментите за документи и интерфейса за рендиране; той не включва абонамент за AI чат, MCP stdio сървър или съвместно мрежово редактиране.