AI 原生工作流

使用智能体处理 Beam 项目

Beam CLI 可让外部智能体检查和编辑真实的 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

在智能体工作的项目中打开终端，然后安装 skills。默认安装位置为该项目中的 .agents/skills。除非明确传入 --global，否则不会进行全局安装。之后请重新加载智能体的 skills，或启动新会话。

该技能包包含十个专用 skills。使用下方命令全部安装，或在命令后添加名称选择部分技能，例如 beam-cli beam-design beam-composition beam-animation。若要使用特定智能体的文件夹，请使用 --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；外部网络请求会被阻止，因此请将其资源打包到本地。

智能体和模型由你提供，其数据处理方式取决于你选择的服务提供商。Beam 提供文档工具和渲染接口，但不包含 AI 聊天订阅、MCP stdio 服务器或共享网络编辑功能。