测试本地 CLI 变更
当你修改了 CLI 或它打包的任何包（core、engine、producer、studio）时，你需要在 monorepo _外部_的真实项目上测试这些变更——就像终端用户运行 hyperframes preview 一样。
前置条件
首先构建 monorepo。每次修改源文件后，测试前请重新构建。
# 在 monorepo 根目录下
bun run build
方案 1：bun link（推荐）
bun link 使 $PATH 中的 hyperframes 二进制文件指向你的本地构建。它在终端会话间保持有效，并且无需重新链接即可自动获取新构建。
# 如果你之前全局安装了 hyperframes，请先移除——
# 全局安装优先于 bun link，会遮蔽你的本地构建。
npm uninstall -g hyperframes 2>/dev/null
# 链接你的本地构建
cd packages/cli
bun link
# 验证——应该打印你的本地版本并指向 monorepo
hyperframes --version
which hyperframes
现在你可以在任何目录中正常使用 hyperframes：
cd ~/my-video-project
hyperframes preview .
每次 bun run build 后，链接的二进制文件已经是最新的——无需重新链接。
完成后恢复已发布的版本：
bun unlink hyperframes
npm install -g hyperframes@latest
方案 2：node 别名（不修改 PATH）
如果你不想修改全局 $PATH，可以添加 shell 别名或直接调用 node：
# 当前 shell 会话的临时别名
alias hyperframes="node /path/to/hyperframes/packages/cli/dist/cli.js"
# 或直接调用
node /path/to/hyperframes/packages/cli/dist/cli.js preview .
请将 /path/to/hyperframes 替换为你的 monorepo 实际路径。
方案 3：npm pack（测试精确的发布产物）
当你想验证实际发布的内容（包括打包的 studio 和示例）时使用此方案。
cd packages/cli
npm pack
# 创建：hyperframes-<version>.tgz
# 在隔离目录中测试
mkdir /tmp/pack-test && cd /tmp/pack-test
npx /path/to/hyperframes/packages/cli/hyperframes-<version>.tgz init my-video
cd my-video
npx /path/to/hyperframes/packages/cli/hyperframes-<version>.tgz preview .
测试修复分支
验证特定 bug 修复时，解压一个测试项目归档并运行场景：
# 示例：测试 audio-after-seek 修复
unzip golden-lyric-video.zip && cd golden-lyric-video
hyperframes preview .
# 1. 按播放——确认音频播放
# 2. 将时间轴拖拽到不同位置
# 3. 再次按播放——音频应从 seek 的位置恢复播放
常见测试场景：
| Bug | 项目 | 步骤 |
|---|---|---|
| Seek 后音频静音 | golden-lyric-video | 播放 → seek → 再次播放，验证音频 |
| 渲染卡在 0% | 任意 | 渲染选项卡 → 导出 → 观察进度条 |
| 重启后下载 404 | 任意 | 完成一次渲染 → Ctrl+C → 重启 → 下载 |
| 时间轴提前停止 | intro-vid | 播放 → 应到达 0:05，而非停在 0:03 |
| Lottie 缺失 | hyperframe-build-up-demo | 播放 → 0-2 秒期间火箭应可见 |
| 缩略图空白 | 任意 | Composition 侧边栏应显示预览 |
故障排除
bun run build 后变更未生效
CLI 二进制文件是位于 packages/cli/dist/cli.js 的单个打包文件。如果你的变更在 @hyperframes/core 或其他 workspace 包中，请确保 bun run build 重新构建了_所有_包——CLI 在构建时打包其依赖。
hyperframes 仍然显示旧版本 / 旧界面
全局安装的 hyperframes 包会遮蔽 bun link。检查哪个二进制文件处于活动状态：
which hyperframes
如果它指向全局存储而非你的 monorepo，请移除全局安装并重新链接：
npm uninstall -g hyperframes
cd packages/cli && bun link
端口已被占用
hyperframes preview 默认使用端口 3002，如果被占用会自动递增。传入 --port 指定端口：
hyperframes preview . --port 4000