AI native

Làm việc trên dự án Beam cùng agent

Beam CLI cho phép agent bên ngoài kiểm tra và chỉnh sửa dự án Screenshot và video thực. Yêu cầu agent đọc tài liệu, thực hiện thay đổi và kiểm tra kết quả. Dự án đó vẫn có thể chỉnh sửa trong Beam.

• Chỉnh nội dung gốc: cắt hoặc di chuyển clip, điều chỉnh phóng to và nền, hoặc sắp xếp lớp, nhóm và hiệu ứng Screenshot.
• Tạo nội dung HTML và TypeScript, tùy chọn dùng Vue, GSAP hoặc WebGL, rồi xuất bản dưới dạng lớp.
• Kiểm tra canvas trực tiếp, hoàn tác chỉnh sửa và xuất bằng trình kết xuất của Beam.

Thiết lập trình khởi chạy dòng lệnh

Dùng trình khởi chạy beam-cli đi kèm Beam. Với mã nguồn đã checkout, thay beam-cli bằng bun run beam và chạy từ thư mục gốc kho mã. Bắt đầu bằng liệt kê công cụ và đọc schema của chúng; các lệnh tìm hiểu này hoạt động mà không cần ứng dụng desktop.

Lời gọi công cụ nhận JSON trực tiếp, tệp đối số có tiền tố ký hiệu a còng hoặc dấu gạch ngang để đọc JSON từ stdin. Kết quả được ghi ra stdout; lỗi được ghi ra stderr kèm mã thoát khác 0. Ví dụ trực tiếp dùng cách trích dẫn POSIX. Trên Windows, tệp đối số tránh khác biệt về trích dẫn của shell. Đường dẫn trong tệp được tính từ vị trí tệp; đường dẫn trực tiếp được tính từ thư mục làm việc.

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

Cài các skill Beam

Mở terminal trong dự án nơi agent làm việc rồi cài các skill. Đích mặc định là .agents/skills bên trong dự án đó. Không cài gì trên toàn hệ thống trừ khi bạn truyền --global một cách rõ ràng. Sau đó, nạp lại skill của agent hoặc bắt đầu phiên mới.

Bộ này gồm mười skill chuyên biệt. Cài tất cả bằng lệnh bên dưới hoặc thêm tên để chọn một phần, chẳng hạn beam-cli beam-design beam-composition beam-animation. Để dùng thư mục riêng cho agent, thêm --agent claude, --agent cursor hoặc --agent gemini; chúng vẫn nằm trong dự án hiện tại. Nếu CLI đã cài chưa nhận diện skills, dùng bản Beam CLI mới hơn hoặc bun run beam từ mã nguồn Beam đã cập nhật.

beam-cli skills install

Kiểm tra và cập nhật skill

Chạy các lệnh này từ cùng thư mục dự án. check so sánh tệp đã cài với bộ trong BeamRecorder/Beam và không thay đổi gì. Báo cáo JSON xác định skill hiện hành, bị thiếu, lỗi thời, đã sửa hoặc xung đột; lệnh thoát với mã 1 khi có skill đã chọn không ở phiên bản hiện hành. update tải bộ hiện tại, bao gồm skill còn thiếu, và bảo vệ các chỉnh sửa cục bộ của bạn.

Bộ được duy trì nằm trong .skills/Beam-cli trên kho GitHub của Beam. Tệp được xác minh trước khi cài. Cập nhật chỉ chạy khi được yêu cầu rõ ràng; các lệnh chỉnh sửa thông thường không kiểm tra skill mới. Dùng --ref với tag hoặc commit khi cần ghim phiên bản, và đọc docs skills để biết thư mục tùy chỉnh và bảo vệ thay đổi cục bộ.

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

Mở dự án và đọc trạng thái

Mở Beam rồi liệt kê các dự án. Ví dụ tạo canvas Screenshot trong suốt. Thay PROJECT_UUID bằng id trả về, mở dự án và đợi projects.list liệt kê id đó trong open. Sau đó yêu cầu documents.snapshot để lấy tài liệu và revision hiện tại.

Với Studio, dùng kind: video cho cả tạo và mở. projects.open thường mở trình chỉnh sửa mới; disposition: reuse thay trình chỉnh sửa đang hoạt động. Nếu nhiều phiên Beam cùng chạy, thêm --instance PID với id từ 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"}'

Chỉnh sửa lớp Screenshot

Dùng ví dụ này với dự án có ảnh chụp, không phải canvas trống vừa tạo. Lưu thành edit.json và thay SCREENSHOT_UUID cùng expectedRevision bằng giá trị từ documents.snapshot. Lớp nguồn đã chụp có id image; giao dịch đổi tên nó và thêm góc 3D.

Tìm id của các lớp khác trong snapshot. Giao diện lệnh hỗ trợ bố trí, cắt, nhóm, thứ tự, màu, hiệu ứng và cài đặt PNG/WebP. Đọc schema dữ liệu trước khi chỉnh sửa. Mảng effects thay thế toàn bộ ngăn xếp, vì vậy hãy đưa vào các hiệu ứng hiện có muốn giữ.

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

Chỉnh sửa clip video hiện có

Với dự án video có clip, dùng giao dịch này làm edit.json thay thế. Thay VIDEO_UUID, expectedRevision và CLIP_ID bằng dữ liệu từ snapshot mới. Giao dịch đặt độ mờ nền và chuyển clip đến giây thứ nhất trên timeline.

Các lệnh video còn hỗ trợ cắt, tách, tốc độ phát, âm lượng, phụ đề, phần tử, nhóm cảnh, chuyển động thuộc tính và phóng to. assets.import sao chép media vào dự án; sau đó dùng lệnh tài liệu để đặt lên timeline.

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

Áp dụng giao dịch

Áp dụng edit.json cho dự án được mô tả. Các lệnh tạo thành một chỉnh sửa nguyên tử và một bước hoàn tác: nếu loạt lệnh không hợp lệ, không có chỉnh sửa từng phần nào được ghi nhận. Nội dung bị khóa vẫn được bảo vệ.

Mỗi chỉnh sửa mới cần operationId mới. Chỉ dùng lại id cho lần thử lại giống hệt. Bạn có thể hoàn tác trong Beam hoặc gọi documents.undo/documents.redo với expectedRevision hiện tại và requestId duy nhất.

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

Tạo thẻ HTML tĩnh

Tạo composition/index.html bằng ví dụ bên dưới. Giữ phông chữ, kiểu và media cục bộ. HTML và TypeScript hoạt động không cần Vue; cài các thư viện được import trong dự án nguồn này.

Thẻ tĩnh không cần đồng hồ chuyển động. Beam đợi phông chữ cục bộ và giải mã ảnh. Với khởi tạo bất đồng bộ, cung cấp promise ready trên 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>

Chuẩn bị yêu cầu xuất bản

Lưu publish.json cạnh thư mục composition. Dùng id và revision hiện tại của dự án Screenshot đang mở. Width và height là kích thước canvas HTML theo pixel. Xuất bản vào Screenshot yêu cầu durationMs: 0. Dùng framework: html hoặc vue cho nguồn Vue.

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

Thêm thẻ vào Beam

html.publish biên dịch nguồn, lưu nguồn và bundle trong dự án rồi chèn một lớp HTML. Lệnh trả về layerId và revision mới. Dự án Screenshot còn lưu PNG đã kết xuất của lớp đó.

Với phiên bản khác của cùng thẻ, giữ layerId được trả về trong publish.json và cập nhật expectedRevision. Cập nhật giữ nguyên bố trí, thứ tự lớp, khả năng hiển thị và hiệu ứng. Các phiên bản nguồn đã xuất bản vẫn có sẵn trong dự án mở lại và lịch sử hoàn tác.

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

Tạo chuyển động cho lớp video bằng đồng hồ có thể tua

Để thẻ chuyển động trong năm giây, cài GSAP trong dự án nguồn và lưu mã bên dưới thành composition/main.ts. Thêm script module cho ./main.ts vào index.html. Trong publish.json, dùng id của dự án video đang mở, durationMs: 5000 và fps: 30. Bỏ layerId của Screenshot trước lần xuất bản đầu tiên vào video này.

Cung cấp window.beamComposition.seek(timeMs). Beam yêu cầu thời điểm chính xác tính bằng mili giây và có thể tua ngược. Giữ GSAP tạm dừng và đặt thời gian timeline rõ ràng. Với Vue, đợi cập nhật phản ứng; với WebGL, vẽ khung hình hoàn chỉnh. seek có thể trả về promise cho bước chuẩn bị bất đồng bộ.

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

Xem trước các lần lưu nguồn trong Beam

Giữ layerId hiện có trong publish.json và chạy html watch. Lệnh xuất bản một lần, đọc revision trực tiếp trước các lần cập nhật tiếp theo rồi xuất bản lại sau khi lưu nguồn. Ctrl+C dừng theo dõi. Lỗi biên dịch hoặc revision không làm mất lớp đã xuất bản trước đó.

Để quay lại mã của một lớp đã lưu, gọi html.source với mô tả HTML từ documents.snapshot. Sao chép nguồn đã lưu vào thư mục làm việc trước khi chỉnh sửa; các phiên bản nguồn đã xuất bản là bất biến. Xem trước có thể gộp các yêu cầu, trong khi xuất kết xuất từng khung hình timeline được yêu cầu.

beam-cli html watch @publish.json

Thêm ảnh và phông chữ

• Giữ ảnh và phông chữ cục bộ trong thư mục nguồn, hoặc cung cấp các mục references với trường name và source. Beam sao chép các tệp này vào references cạnh HTML.
• Với tham chiếu project-media từ dự án đã lưu khác, đưa vào projectId của nó. assets.resolve tìm tệp thuộc dự án để kiểm tra; html.publish có thể sao chép nó vào bundle.
• Dùng văn bản gốc khi muốn chỉnh câu chữ trong Beam: still.layer.add cho Screenshot hoặc clip.insert cho phần tử video. Văn bản bên trong HTML được chỉnh qua mã nguồn.
• fonts.import nhận TTF, OTF, WOFF và WOFF2. Đặt text.style.fontFamily và text.style.fontAssetId bằng family và id trả về để văn bản chỉnh sửa được dùng phông đó trong xem trước và xuất.

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

Kiểm tra và xuất kết quả

Cài backend Chromium của CLI một lần hoặc trỏ BEAM_CHROMIUM_EXECUTABLE đến trình duyệt tương thích. Giữ Beam chạy trong lúc xuất dự án đang mở có lớp HTML: ứng dụng cung cấp khung hình đã kết xuất của các lớp đó. Thay các id bên dưới và chọn thời điểm khung hình trong thời lượng video.

Screenshot dùng cài đặt PNG/WebP của tài liệu; phần mở rộng đầu ra phải khớp định dạng. Video hỗ trợ MP4 và WebM với lớp, phụ đề và phóng to của bố cục. Để chủ động thay thế đích hiện có, truyền 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"}'

Chỉnh sửa tệp ảnh không cần ứng dụng desktop

Bắt đầu bằng PNG hiện có và kích thước thực. Chỉ lưu mảng commands từ giao dịch Screenshot thành edits.json, rồi tạo, chỉnh sửa và xuất tài liệu độc lập bên dưới. Quy trình này thay đổi tài liệu tệp, không phải trình chỉnh sửa Beam đang mở.

Các lệnh độc lập edit và serve không cần ứng dụng desktop. Xuất cần backend Chromium của CLI. Để tạo video HTML không có trình chỉnh sửa, dùng motion với tệp job; beam-cli docs html mô tả entry, kích thước, thời lượng theo giây, fps và định dạng.

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

Hiểu phần nào chạy cục bộ

CLI kết nối với desktop qua endpoint cục bộ có xác thực. Beam kết xuất ngay trên máy. HTML đã xuất bản chạy trong cửa sổ sandbox không có quyền Node hoặc preload Beam; yêu cầu mạng bên ngoài bị chặn, vì vậy hãy đóng gói tài nguyên cục bộ.

Bạn cung cấp agent và mô hình. Cách xử lý dữ liệu của chúng phụ thuộc vào nhà cung cấp bạn chọn. Beam cung cấp công cụ tài liệu và giao diện kết xuất; nó không bao gồm gói chat AI, máy chủ MCP stdio hoặc chỉnh sửa chia sẻ qua mạng.