视频编辑者速查表

当你在指导代理、剪辑时间、进行视觉布局调整、预览和分享 HyperFrames 项目时，将此作为快速参考。

快速循环

npx hyperframes init my-video --example blank
cd my-video
npx hyperframes preview

在代理编辑 index.html 或 compositions/ 中的文件时保持预览运行。Studio 自动更新，因此你可以指导代理、拖动查看结果、手动进行视觉调整，然后重复。

大多数生产工作应该像这样：

1. 要求代理进行初剪、场景、字幕、过渡或清理。
2. 使用 Studio 预览和时间轴检查时间。
3. 使用手动 DOM 编辑进行类似 Figma 的布局调整：选择元素、移动它们、直接调整视觉属性。
4. 要求代理清理或泛化你手动更改的任何内容。
5. Lint、验证、渲染、发布。

在展示或渲染项目之前：

npx hyperframes lint
npx hyperframes validate
npx hyperframes render --quality standard --output review.mp4

快速迭代渲染使用草稿质量：

npx hyperframes render --quality draft --output draft.mp4

最终交付：

npx hyperframes render --quality high --fps 30 --output final.mp4

终端快捷方式

快速在项目间导航：

pwd                 # show current folder
ls                  # list files
cd my-video         # enter a project folder
cd ..               # go up one folder
cd -                # jump back to the previous folder
open .              # open the current folder in Finder on macOS
code .              # open the current folder in VS Code, if installed

常见的 HyperFrames 项目文件夹：

cd assets           # source videos, images, audio
cd compositions     # reusable scenes and overlays
cd ..               # back to the project root

在项目根目录（index.html 所在位置）运行 HyperFrames 命令。如果你不确定在哪里，运行 pwd 然后 ls。如果看到 index.html，你就在正确的位置。

预览快捷方式

启动 Studio：

npx hyperframes preview

如果 3002 端口已被占用，使用其他端口：

npx hyperframes preview --port 4567

在 Studio 内部，快捷方式的分组与播放栏的 ⌨ 面板相同——播放优先，然后是工作区标记、视图控制和应用级命令。打开播放栏中的 ⌨ 面板查看应用内速查表、帧跳转输入和入点/出点的实时读数。

播放

J 和 L 构成经典的 NLE 穿梭：每次重复都会提升播放速率。在穿梭间按 K 停止。按住 K 时，按 J 或 L 向该方向逐帧前进。

工作区（入点 / 出点）

入点和出点定义一个工作区。开启循环时，正向和反向播放都在这些边界内循环——适用于收紧过渡或在不裁剪单个片段的情况下拖动查看。搜索条在入点和出点之间渲染一个青色带，并在每个点上显示刻度标记。从 ⌨ 面板或使用 Shift+I 和 Shift+O 清除标记。

视图

应用

💡 Tip

预览使用与渲染相同的运行时，因此视觉帧与输出匹配。如果预览在重帧上卡顿但渲染正常，这是预期的——预览实时播放，渲染逐帧捕获。

代理主导的编辑

要求代理在浏览器中验证可见更改。对于用户可见的编辑，一个好的交接是：

Run the preview, check it with agent-browser, take a screenshot, and render a draft MP4 to take a look at the frames with ffmpeg.

手动 DOM 编辑

在 Studio 中，你可以可视化编辑 DOM，进行最后 10% 的创意调整——此时拖动比描述更快。

手动 DOM 编辑用于：

• 将标题、字幕、产品卡片、logo 和覆盖层移动到正确位置
• 调整大小、间距、透明度、颜色和其他视觉属性
• 在精确时间戳检查合成平衡
• 进行类似 Figma 的位置调整

使用代理用于：

• 从零创建场景
• 重构重复的视觉模式
• 连接 GSAP 时间轴
• 修复损坏的时间、布局溢出或渲染错误
• 将手动视觉调整转化为可复用的干净 HTML/CSS

手动 DOM 编辑后，要求代理检查差异并保持源代码干净：

I moved the hero title and resized the CTA manually in Studio. Inspect the changes, clean up the CSS if needed, then run lint and validate.

编辑者最常用的 CLI 命令

时间速查表

每个可见的定时层通常应该是一个片段：

<h1
class="clip"
data-start="0"
data-duration="3"
data-track-index="0"
>
Opening title
</h1>

像时间轴控件一样使用这些属性：

对于 GSAP 动画，为每个合成注册一个暂停的时间轴：

<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });

l.from("#title", { opacity: 0, y: 40, duration: 0.6 });
l.set({}, {}, 5); // keeps the timeline at least 5 seconds long

window.__timelines["main"] = tl;
</script>

⚠️ Warning

如果视频提前截断，检查 GSAP 时间轴是否至少与预期编辑一样长。最后的 tl.set({}, {}, 5) 模式是修复方法。

渲染预设

透明覆盖层、字幕和底部字幕条使用 WebM。需要跨不同机器像素一致的输出时使用 --docker。

发布和分享

当你想分享可编辑项目（而非仅渲染的 MP4）时使用 publish：

npx hyperframes publish

Publish 将当前项目打包为 zip，上传，并打印一个稳定的 hyperframes.dev URL。URL 包含认领令牌，接收者可以打开它、认领项目并继续在 Web 应用中编辑。

npx hyperframes publish ./my-video   # publish a specific folder
npx hyperframes publish --yes        # skip the confirmation prompt in scripts

Publish 期望项目根目录有 index.html。它忽略 .git、node_modules、dist、.next 和 coverage。

什么是 Agent Browser

agent-browser 是面向 AI 代理的浏览器自动化工具。它打开 Chrome，导航到你的预览，点击控件，读取页面状态，并捕获截图。这是代理证明视频预览确实有效的方式，而不仅仅是说代码看起来正确。

典型验证流程：

agent-browser open http://localhost:3002
agent-browser snapshot -i
agent-browser screenshot --screenshot-dir ./qa

当你想让代理打开 HyperFrames Studio 预览、播放或拖动视频、点击时间轴控件、检查可见 UI 文本、捕获截图审查，或记录已测试流程的证据时使用。

对于面向编辑器的更改，保持 npx hyperframes preview 运行，然后让代理使用 agent-browser 对本地预览 URL 操作。

快速修复

• 提示词指南 如何指导 AI 代理构建更好的视频
• 时间轴编辑 时间、轨道和 GSAP 时间轴模式
• 常见错误 Linter 无法捕获的陷阱
• CLI 参考 完整命令参考