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 в репозитории Beam на GitHub. Файлы проверяются перед установкой. Обновления запускаются явно; обычные команды редактирования не проверяют новые навыки. Используйте --ref с тегом или коммитом для закрепления версии, а документацию навыков — для пользовательских папок и защищенных локальных изменений.

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 рядом с папкой композиции. Укажите идентификатор и текущую ревизию открытого проекта 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-сервер или совместное сетевое редактирование.