AI 原生工作流

使用AI 代理程式處理 Beam 專案

Beam CLI 可讓外部 AI 代理程式檢查和編輯真實的 Screenshot 與影片專案。你可以讓它讀取文件、進行修改並檢查結果。同一專案仍可在 Beam 中編輯。

• 編輯原生內容：修剪或移動片段、調整縮放和背景，或排列 Screenshot 圖層、編組和效果。
• 建立 HTML 和 TypeScript 作品，可選用 Vue、GSAP 或 WebGL，並將其釋出為圖層。
• 檢視即時畫布、撤銷編輯，並使用 Beam 渲染器匯出。

設定命令列啟動器

使用 Beam 附帶的 beam-cli 啟動器。在原始碼檢出目錄中，將 beam-cli 替換為 bun run beam，並從儲存庫根目錄執行。首先列出工具並讀取其結構；這些發現命令無需桌面應用程式即可執行。

工具呼叫可接受內聯 JSON、字首為 at sign 的引數檔案，或表示從 stdin 讀取 JSON 的短橫線。結果輸出至 stdout；錯誤輸出至 stderr，並回傳非零退出程式碼。內聯範例使用 POSIX 引號。在 Windows 上，引數檔案可避免 shell 引號差異。檔案中的路徑相對於該檔案解析；內聯路徑則相對於工作目錄解析。

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

在AI 代理程式工作的專案中開啟終端，然後安裝 skills。預設安裝位置為該專案中的 .agents/skills。除非明確傳入 --global，否則不會進行全域安裝。之後請重新載入AI 代理程式的 skills，或啟動新工作階段。

該技能包包含十個專用 skills。使用下方命令全部安裝，或在命令後新增名稱選擇部分技能，例如 beam-cli beam-design beam-composition beam-animation。若要使用特定 AI 代理程式的資料夾，請使用 --agent claude、--agent cursor 或 --agent gemini；這些目錄也位於目前專案內。如果已安裝的 CLI 尚不識別 skills，請使用較新的 Beam CLI 建置版本，或在最新的 Beam 原始碼檢出目錄中執行 bun run beam。

beam-cli skills install

檢查並更新 skills

在同一專案資料夾中執行這些命令。check 會將已安裝檔案與 BeamRecorder/Beam 中的技能包進行比較，但不會修改任何內容。其 JSON 報告會列出最新、缺失、過時、已修改或衝突的 skills；所選技能中有任一項不是最新版本時，退出程式碼為 1。update 會下載目前技能包，包括缺失的 skills，並保護本機修改。

維護中的技能包位於 Beam GitHub 儲存庫的 .skills/Beam-cli。安裝前會驗證檔案。更新需要明確執行；常規編輯命令不會檢查新 skills。需要固定版本時，可將標籤或提交與 --ref 一起使用；自訂目錄和保護本機修改請參閱 docs skills。

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，並使用 documents.snapshot 中的值替換 SCREENSHOT_UUID 和 expectedRevision。錄製源圖層的 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 會將媒體複製到專案中；之後使用文件命令將其放置到時間軸上。

{
  "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。僅在完全相同的重試中重用 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。

要釋出同一卡片的新版本，請在 publish.json 中保留回傳的 layerId，並更新 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。將 text.style.fontFamily 和 text.style.fontAssetId 設定為回傳的字型系列和 id，以便可編輯文字在預覽和匯出中使用該字型。

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；外部網路請求會被阻止，因此請將其資源打包到本機。

AI 代理程式和模型由你提供，其資料處理方式取決於你選擇的服務提供商。Beam 提供檔案工具和渲染介面，但不包含 AI 聊天訂閱、MCP stdio 伺服器或共享網路編輯功能。