AI 네이티브

에이전트와 Beam 프로젝트 작업

Beam CLI를 사용하면 외부 에이전트가 실제 Screenshot 및 동영상 프로젝트를 살펴보고 편집할 수 있습니다. 문서를 읽고 변경한 후 결과를 확인하도록 요청하세요. 같은 프로젝트를 Beam에서도 계속 편집할 수 있습니다.

• 기본 콘텐츠 편집: 클립을 자르거나 이동하고 확대 및 배경을 조정하거나 Screenshot 레이어, 그룹, 효과를 배치합니다.
• 필요에 따라 Vue, GSAP 또는 WebGL을 사용해 HTML 및 TypeScript 아트워크를 만들고 레이어로 게시합니다.
• 실시간 캔버스를 확인하고 편집을 실행 취소한 다음 Beam 렌더러로 내보냅니다.

명령줄 실행 프로그램 설정

Beam에 포함된 beam-cli 실행 프로그램을 사용하세요. 소스 체크아웃에서는 beam-cli를 bun run beam으로 바꾸고 저장소 루트에서 실행하세요. 먼저 도구 목록을 확인하고 스키마를 읽으세요. 검색 명령은 데스크톱 앱 없이 작동합니다.

도구 호출에는 인라인 JSON, @로 시작하는 인수 파일 또는 stdin JSON을 의미하는 대시를 사용할 수 있습니다. 결과는 stdout에, 오류는 0이 아닌 종료 코드와 함께 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을 명시하지 않으면 전역으로 설치되지 않습니다. 설치 후 에이전트 스킬을 다시 불러오거나 새 세션을 시작하세요.

이 팩에는 특정 작업에 집중한 스킬 10개가 포함됩니다. 아래 명령으로 모두 설치하거나 beam-cli beam-design beam-composition beam-animation처럼 이름을 덧붙여 일부만 선택하세요. 에이전트 전용 폴더에는 --agent claude, --agent cursor 또는 --agent gemini를 사용하세요. 이 스킬도 현재 프로젝트 안에 설치됩니다. 설치된 CLI가 아직 스킬을 인식하지 못하면 최신 Beam CLI 빌드 또는 최신 Beam 소스 체크아웃의 bun run beam을 사용하세요.

beam-cli skills install

스킬 확인 및 업데이트

같은 프로젝트 폴더에서 명령을 실행하세요. check는 설치된 파일과 BeamRecorder/Beam 팩을 비교하며 아무것도 변경하지 않습니다. JSON 보고서에서 최신, 누락, 오래됨, 수정됨, 충돌하는 스킬을 확인할 수 있습니다. 선택한 스킬 중 최신이 아닌 것이 있으면 종료 코드 1을 반환합니다. update는 누락된 스킬을 포함해 최신 팩을 다운로드하며 로컬 편집을 보호합니다.

관리되는 스킬 팩은 Beam GitHub 저장소의 .skills/Beam-cli에 있습니다. 설치 전에 파일을 검증합니다. 업데이트는 명시적으로 실행해야 하며 일반 편집 명령은 새 스킬을 확인하지 않습니다. 특정 버전을 고정하려면 --ref와 태그 또는 커밋을 사용하고 사용자 지정 폴더 및 로컬 변경 보호에 대해서는 docs 스킬을 읽으세요.

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

프로젝트를 열고 상태 읽기

Beam을 시작한 뒤 프로젝트를 나열하세요. 예시에서는 투명 Screenshot 캔버스를 만듭니다. PROJECT_UUID를 반환된 ID로 바꾸고 열어 projects.list의 open에 해당 ID가 포함될 때까지 기다리세요. 그런 다음 현재 문서와 리비전에 대해 documents.snapshot을 요청합니다.

Studio에서는 생성과 열기 모두 kind: video를 사용합니다. projects.open은 일반적으로 새 편집기를 열며 disposition: reuse는 현재 편집기를 대체합니다. Beam 인스턴스가 여러 개 실행 중이면 instances에서 얻은 ID를 사용해 --instance PID를 덧붙이세요.

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의 값으로 바꾸세요. 캡처 소스 레이어의 ID는 image이며 이 트랜잭션은 이름을 바꾸고 3D 각도를 적용합니다.

스냅샷에서 다른 레이어 ID를 확인하세요. 명령 인터페이스는 배치, 자르기, 그룹화, 순서, 색상, 효과, 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로 바꿉니다. 배경을 흐리게 하고 클립을 타임라인 1초 위치로 옮깁니다.

동영상 명령은 자르기, 분할, 재생 속도, 볼륨, 캡션, 요소, 장면 그룹, 속성 애니메이션, 확대도 지원합니다. assets.import는 미디어를 프로젝트로 복사하며 이후 document 명령으로 타임라인에 배치합니다.

{
  "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을 해당 프로젝트에 적용하세요. 명령은 원자적 편집 1회와 실행 취소 단계 1회를 구성합니다. 배치가 유효하지 않으면 일부만 적용되지 않습니다. 잠긴 콘텐츠는 계속 보호됩니다.

새 편집마다 새 operationId를 지정하세요. 같은 요청을 재시도할 때만 ID를 재사용합니다. Beam에서 실행 취소하거나 현재 expectedRevision과 고유 requestId를 사용해 documents.undo/documents.redo를 호출할 수 있습니다.

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

정적 HTML 카드 만들기

아래 예시로 composition/index.html을 만드세요. 글꼴, 스타일, 미디어는 로컬에 두세요. HTML 및 TypeScript는 Vue 없이 작동하며 가져온 라이브러리는 이 소스 프로젝트에 설치하세요.

정적 카드에는 애니메이션 시계가 필요하지 않습니다. Beam은 로컬 글꼴과 이미지 디코딩을 기다립니다. 비동기 초기화를 위해 window.beamComposition에 ready promise를 노출하세요.

<!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 프로젝트 ID와 현재 리비전을 사용합니다. 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

시킹 가능한 시계로 동영상 레이어 애니메이션

카드를 5초간 애니메이션하려면 소스 프로젝트에 GSAP를 설치하고 아래 코드를 composition/main.ts로 저장하세요. index.html에 ./main.ts용 모듈 스크립트를 추가합니다. publish.json에는 열린 동영상 프로젝트 ID, 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에서 미리 보기

publish.json에 기존 layerId를 유지하고 html watch를 시작하세요. 한 번 게시한 다음 후속 업데이트 전에 현재 리비전을 읽고 소스를 저장하면 다시 게시합니다. Ctrl+C로 감시를 중지합니다. 컴파일 또는 리비전 오류가 발생해도 이전 게시 레이어는 유지됩니다.

저장된 레이어 코드로 돌아가려면 documents.snapshot의 HTML 설명자를 사용해 html.source를 호출하세요. 편집 전에 저장된 소스를 작업 폴더에 복사하세요. 게시된 소스 버전은 변경할 수 없습니다. 미리 보기 요청은 합쳐질 수 있지만 내보내기는 요청된 각 타임라인 프레임을 렌더링합니다.

beam-cli html watch @publish.json

이미지 및 글꼴 가져오기

• 로컬 이미지와 글꼴을 소스 폴더에 두거나 name 및 source 필드가 있는 references 항목을 제공하세요. Beam은 이 파일을 HTML 옆의 references 폴더에 복사합니다.
• 다른 저장 프로젝트의 미디어를 참조하려면 해당 projectId를 포함하세요. assets.resolve는 확인할 프로젝트 소유 파일을 찾고 html.publish는 번들로 복사할 수 있습니다.
• Beam에서 문구를 편집하려면 기본 텍스트를 사용하세요. Screenshot은 still.layer.add, 동영상 요소는 clip.insert를 사용합니다. HTML 내 텍스트는 소스 코드에서 편집합니다.
• fonts.import는 TTF, OTF, WOFF, WOFF2를 지원합니다. 반환된 패밀리와 ID를 text.style.fontFamily 및 text.style.fontAssetId에 설정하면 편집 가능한 텍스트가 미리 보기와 내보내기에서 해당 글꼴을 사용합니다.

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

결과 확인 및 내보내기

CLI Chromium 백엔드를 한 번 설치하거나 BEAM_CHROMIUM_EXECUTABLE에 호환 브라우저 경로를 지정하세요. HTML 레이어가 있는 열린 프로젝트를 내보낼 때 Beam을 실행 상태로 유지하세요. 렌더링 프레임을 제공합니다. 아래 ID를 바꾸고 동영상 길이 내에서 프레임 시각을 선택하세요.

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와 실제 치수로 시작하세요. Screenshot 트랜잭션의 commands 배열만 edits.json으로 저장한 다음 아래 독립형 문서를 만들고 편집 및 내보내기 하세요. 이 흐름은 열린 Beam 편집기가 아닌 파일 문서를 변경합니다.

독립형 편집과 제공에는 데스크톱 앱이 필요하지 않습니다. 내보내기에는 CLI Chromium 백엔드가 필요합니다. 편집기 없이 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 접근이나 Beam preload 없이 샌드박스 창에서 실행됩니다. 외부 네트워크 요청이 차단되므로 리소스를 로컬에 묶어 두세요.

에이전트와 모델은 사용자가 제공합니다. 데이터 처리는 선택한 공급자에 따라 달라집니다. Beam은 문서 도구와 렌더링 인터페이스를 제공하지만 AI 채팅 구독, MCP stdio 서버, 공유 네트워크 편집은 포함하지 않습니다.