HyperFrames CLI 预览、播放、渲染与发布全指南：从 Studio 评审到成品交付

导读

本文档是 HyperFrames 命令行工作流中「服务、渲染、分享」三大环节的完整参考，覆盖 preview、play、render、feedback、publish 五个核心命令。你将掌握：如何为 Agent 与人类用户启动可热重载的 Studio 评审环境并正确交付项目 URL、如何用轻量 <hyperframes-player> 快速分享预览、如何用 40 余个渲染参数控制从草稿到 4K/HDR 的最终输出、如何提交结构化的渲染反馈报告，以及如何将项目发布为稳定、可公开的托管链接。读完即可在真实项目（如 codex-openai-video）上跑通「评审 → 渲染 → 反馈 → 发布」的完整流水线。

总览：一条命令覆盖全流程

本参考文档是技能 skills/hyperframes-cli 的组成部分，对应 CLI 包 packages/cli。五个命令在源码中分别由 preview.ts、play.ts、render.ts、feedback.ts、publish.ts 实现，职责划分如下：

命令	角色	服务表面	典型场景
preview	完整 Studio 评审环境	全功能时间线编辑器	手工调整、Agent 上下文桥接、渲染前评审
play	轻量播放器	可嵌入的 <hyperframes-player>	分享预览链接、无需编辑器
render	本地/容器化渲染	视频文件输出	从 draft 到 final 的交付渲染
feedback	渲染结果反馈	匿名遥测上报	维护者质量信号、bug 复现包
publish	项目托管发布	稳定公网 URL	分享、团队空间、公开链接

preview：打开完整 Studio 评审环境

preview 启动的不是普通查看器，而是完整的 Studio 时间线编辑器——用户可以播放视频、逐帧手工修改任何元素，这是「评审表面」（review surface）而非仅预览。源码中命令元信息明确写着「Start the studio for previewing compositions」（preview.ts）。

启动形态与端口

npx hyperframes preview                   # 前台运行（TTY）；在 Agent shell 中转为持久会话
npx hyperframes preview --background      # 显式持久后台会话
npx hyperframes preview --foreground --json # 输出 ready JSON，然后保持附着
npx hyperframes preview --background --port 4567 # Agent 安全的自定义端口（默认 3002）
npx hyperframes preview --selection --json # 打印当前 Studio 选中元素并退出
npx hyperframes preview --context --json  # 打印来自 Studio 的紧凑 Agent 上下文

端口默认值为 3002（preview.ts）。启动形态由 previewLaunchMode 决定（preview.ts）：显式 --background 直接进入后台；在非交互 shell（无 TTY）中，裸 preview 也会自动创建受管持久会话，这正是 Agent 场景下的默认行为；有 TTY 且非 dev 模式时走嵌入式（embedded）模式前台运行。--foreground 则强制在非交互 shell 中保持附着。此外还有 --force-new（已有服务时强制新建）、--status（查看后台会话状态与 PID/日志路径）、--list（列出全部活动服务）、--kill-all（终止全部服务）等生命周期参数（preview.ts）。多个生命周期动作互斥，与启动参数混用会被 previewLaunchModeError 拒绝（preview.ts）。

文件变更后自动热重载，并自动在浏览器中打开 Studio。启动前还会先运行一次 lint（lintProject），把问题直接呈现出来供 Agent 修复（preview.ts）。

交付 URL 的正确姿势：使用 Studio 项目 URL 而非 index.html

把项目交还给用户时，必须使用 Studio 项目 URL，而不是源码 index.html 路径：

http://localhost:<port>/#project/<project-name>

index.html 只是源码上下文，不是评审表面。例如在 codex-openai-video 目录下执行 npx hyperframes preview --background --port 3017 后，应交付 http://localhost:3017/#project/codex-openai-video。端口与项目目录名要使用实际值；HyperFrames 会对含路由元字符的项目名做 URL 编码，因此直接使用 CLI 打印出来的 URL 原样交付。

如果评审对象是故事板（Storyboard）而非时间线，把视图参数放到 hash 之前：

http://localhost:<port>/?view=storyboard#project/<project-name>

当还没有组装任何内容、index.html 尚不存在时，时间线阶段无内容可显示，裸项目 URL 会打开一个空播放器——此时应交付带 ?view=storyboard 的 URL。

交付前检查：两种「死链」形态

交还 URL 前务必检查两点，否则链接必死：

1. 缺少 #project/<project-name> hash：Studio 能加载，但没有项目可打开；
2. 服务实际未运行：后台会话已退出。

验证方法：确认打印的 URL 返回 HTTP 200，评审期间保持服务存活，结束后用 npx hyperframes preview --stop 显式停止。后台会话由 previewLifecycle.ts 管理（状态含 port/PID/logPath，可通过 --json 获取）；裸 preview 在非 TTY Agent shell 中会自动创建受管持久会话，--background 则是最清晰的显式形式。

Agent 上下文桥接：--context 与 --selection

preview --context 与 preview --selection 是 Agent 与运行中 Studio 会话的桥接通道：它们不会启动新服务，而是定位当前项目活动的 preview 服务、从 Studio 读取 Agent 可用的状态、打印后退出。

当用户给出指示性（deictic）编辑指令——「改这个」「移动选中的元素」「把我点的那张卡片放大」「修复当前选区」——时使用：

npx hyperframes preview --context --json --context-fields selection

紧凑上下文载荷包含：选中元素的源文件（sourceFile）、合成路径（compositionPath）、当前时间线时间（currentTime）、data-hf-id/选择器目标（target）、包围盒（boundingBox）、文本内容（textContent）以及选中元素的缩略图 URL（thumbnailUrl）。源码中该载荷由 CompactSelectionPayload 定义，取自 StudioSelectionSnapshot（preview.ts），字段包括 schemaVersion、projectId、label、tagName 等。

目标解析优先级：存在时优先用 selection.target.hfId（稳定的 data-hf-id）；仅在无稳定 data-hf-id 时才回退到 selection.target.selector。若 selection 为 null，检查 errors.selection.code（例如 no-selection）。

Agent 上下文要尽量精简，只请求需要的切片：

npx hyperframes preview --context --json --context-fields selection
npx hyperframes preview --context --json --context-fields lint
npx hyperframes preview --context --json --context-fields selection,lint

可用的 --context-fields 为 server,selection,lint,capabilities，默认全部包含（preview.ts）。--context-detail full 仅在编辑确实需要 computedStyles、inlineStyles、dataAttributes 或可编辑文本字段元数据等重型选区字段时才使用：

npx hyperframes preview --context --json --context-fields selection --context-detail full

--context-detail 默认为 compact（preview.ts）。当明确需要完整的选中元素载荷、且不需要 lint/服务上下文时，preview --selection --json 依然可用。

上下文桥接的失败模式

错误码	含义	处理建议
preview-not-running	Studio 未启动	先用 npx hyperframes preview --background 启动
ambiguous-preview-server	匹配到多个 Studio 服务	带上其中一个列出的 --port 重跑
preview-port-mismatch	请求的 --port 不在匹配的 Studio 服务中	换用候选端口重跑
no-selection	Studio 已打开，但用户尚未选中元素	请用户在 Studio 中点击目标元素后重跑命令
selection-unavailable	运行中的 preview 服务无法干净地暴露选区上下文	重启服务或更换端口重试

这些错误码在 preview.ts 与 preview.ts 的选区/上下文打印逻辑中分别产生。若服务错误列出了候选端口，用 --port <candidate> 重跑同一命令。不要在 CLI 能给出稳定元素目标时用截图去推断目标。

play：轻量播放器

play 通过可嵌入的 <hyperframes-player> Web 组件（packages/player）服务合成，而不是完整 Studio UI——没有编辑器、没有面板，适合分享预览链接或 Studio 显得过重的场景。

npx hyperframes play                  # 当前项目，端口 3003
npx hyperframes play ./my-video       # 指定项目
npx hyperframes play --port 8080      # 自定义端口

play 默认端口为 3003（play.ts）。它报告裸 http://localhost:<port> URL——不带 #project/<name> 片段，因为那是仅 preview 使用的 Studio 路由约定。实现上 play 通过 Hono 服务 /player.js、/runtime.js 与 /composition/* 路由（含字节级 Range 支持、?hf-proxy= 媒体代理分支与路径穿越防护，见 play.ts）；若端口被占用会打印提示并自动改用空闲端口（play.ts）。

播放器的 playback-rate 属性（预览倍速控制，驱动时间线的 timeScale）被限制在 [0.1, 5] 区间；值 ≤ 0 或非有限值回退为 1。这是预览/播放旋钮，不是合成的 data-* 属性——作者创作的动画仍以 1× 渲染。

用外部浏览器启动（preview 与 play 通用）

preview 与 play 都可以在显式指定的 Chromium 兼容浏览器中打开，而不是系统默认浏览器。两个用例：隔离的 Chromium 配置文件，或外部 CDP 附加（DevTools / Playwright / Puppeteer / browser-MCP）。HyperFrames 本身不拥有 CDP 自动化——这里只是暴露端点，连上之后做什么由你负责。不要与 --browser-gpu（render 中控制捕获时 Chrome GPU 访问的标志）混淆。

标志	类型	说明
--browser-path	path	Chromium 兼容可执行文件的绝对路径（/usr/bin/chromium、/Applications/Brave Browser.app/...）
--user-data-dir	path	Chromium 兼容配置文件目录。需要 --browser-path。用一次性目录避免把状态带进主配置文件
--remote-debugging-port	integer 1-65535	在给定端口开放 Chromium CDP 端点。同时需要 --browser-path 与 --user-data-dir，否则拒绝——避免 CDP 端点意外泄漏进主配置文件

# 在隔离的 Chromium 配置文件中打开 preview
npx hyperframes preview --background --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile

# 同样方式并外加 :9222 上的 CDP 端点（附加 DevTools / Playwright 等）
npx hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222

依赖校验在任何服务启动之前运行：validateRemoteDebuggingPortDeps 检查缺少依赖即返回错误（openBrowser.ts），parseRemoteDebuggingPort 保证端口为 1-65535 整数（openBrowser.ts），因此非法值会干净退出，不会留下监听中的 socket（play.ts 的注释明确说明了这一顺序设计）。

render：从草稿到成片

原则：只有在用户在 preview 中评审并批准后才渲染。检查通过也不自动渲染。

npx hyperframes render                                # 从当前目录渲染标准 MP4
npx hyperframes render ./my-video --output ./out.mp4  # 从项目目录外渲染
npx hyperframes render --output final.mp4             # 命名输出（无时间戳）
npx hyperframes render -c compositions/intro.html -o intro.mp4  # 渲染指定子合成文件
npx hyperframes render --quality draft                # 快速迭代
npx hyperframes render --fps 60 --quality high        # 最终交付
npx hyperframes render --format webm                  # 透明 WebM
npx hyperframes render --docker                       # 跨主机字节一致

默认 --output 为 renders/<project-name>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>——每次渲染都带时间戳，连续运行不会互相覆盖。传 --output 可获得稳定文件名。

render 的整个执行流程在 render.ts 中：createRenderPlan 构建渲染计划，presentRenderPlan 展示，executeRenderPlan 执行（render.ts）。

渲染参数总表

标志	选项	默认	说明
dir（位置参数）	path	cwd	项目目录。省略则使用当前工作目录
--composition, -c	合成文件路径	index.html	渲染指定合成文件（如 compositions/intro.html）而非项目的 index.html；使用 <template> 包装的子合成必须通过 data-composition-src 从 index.html 引用（render.ts）
--output, -o	path	renders/<project>_<ts>.<ext>	输出路径。默认为时间戳命名
--fps	24, 30, 60（源码还接受 25, 50, 120, 240 及 ffmpeg 有理数如 30000/1001，范围 1-240）	30（或合成根 data-fps）	60fps 渲染时间翻倍；未指定时回退合成根 data-fps，否则 30（render.ts）
--quality	draft, standard, high	standard	draft 用于迭代
--format	mp4, webm, mov, gif, png-sequence	mp4	WebM/MOV 支持透明；gif 用于 GitHub PR/README/文档内联自动播放（两遍调色板编码，fps 上限 30——推荐 --fps 15——无音频、仅 1-bit 透明、HDR 回退 SDR）；png-sequence 将 RGBA 帧写入目录（供 AE/Nuke/Fusion 摄取）
--gif-loop	0-65535	0	GIF 循环次数；0 为无限循环。仅配合 --format gif
--resolution	landscape, portrait, landscape-4k, portrait-4k, square, square-4k（别名 1080p, 4k, uhd 等）	—	通过 Chrome deviceScaleFactor 超采样。宽高比必须与合成匹配；缩放必须为整数倍。不可与 --hdr 同用（render.ts）
--crf	0-51	—	编码器 CRF（数值越低质量越高）。与 --video-bitrate 互斥，MOV 不支持
--video-bitrate	如 10M, 5000k	—	目标码率。与 --crf 互斥，MOV 不支持
--hdr	flag	off	即使源为 SDR 也强制 HDR 输出。仅 MP4
--sdr	flag	off	即使源为 HDR 也强制 SDR 输出
--workers	number 或 auto	auto	每个 worker 会启动一个 Chrome（约 256 MB）
--docker	flag	off	跨主机可复现输出
--gpu	flag	off	GPU 加速 FFmpeg 编码（NVENC / VideoToolbox / VAAPI / QSV）
--browser-gpu / --no-browser-gpu	flag	auto（本地），off（docker）	Chrome/WebGL 捕获用主机 GPU；--no-browser-gpu 强制 SwiftShader 软件路径
--browser-timeout	秒（0.001-86400）	60	入口 HTML 的 Puppeteer 页面导航超时。重合成（多视频/字体/远程资源）在 60s 默认值内无法到达 domcontentloaded 时调大；环境变量回退 PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS（render.ts）
--quiet	flag	off	抑制冗长输出
--strict	flag	off	lint 错误即失败
--strict-all	flag	off	lint 错误和警告都失败
--variables	JSON 对象	—	覆盖 data-composition-variables 中声明的值
--variables-file	path	—	含变量值的 JSON 文件（--variables 的替代方案）
--strict-variables	flag	off	--variables 中出现未声明键或类型不匹配即渲染失败

质量指导：迭代用 draft，评审用 standard，最终交付用 high。

参数化渲染：data-composition-variables 与 getVariables

合成在 <html> 根元素上用 data-composition-variables 声明变量——一个 JSON 声明数组（每项 {id, type, label, default}），构成变量的 schema。合成内部脚本通过 window.__hyperframes.getVariables() 读取解析后的值。CLI 的 --variables '{"title":"Q4 Report"}' 是一个按 id 为键的 JSON 对象，仅覆盖本次渲染的声明默认值；缺失的键自动透传，因此同一个合成在开发预览与生产渲染中可原样运行（render.ts）。子合成宿主还可以用 data-variable-values 做按实例覆盖。完整模式见 hyperframes-core 技能（skills/hyperframes-core）。

补充渲染细节

• 渲染前也会执行 lint（runRenderLint），--strict/--strict-all 控制失败阈值；
• --batch 支持「每行变量一次输出」的批量渲染：--batch rows.json --output "renders/{name}.mp4"，--batch-concurrency 控制并行行数（默认 1，因为每次渲染内部已跨 worker 并行），--batch-fail-fast 首行失败即停（render.ts）；
• --video-frame-format auto|jpg|png 控制源视频帧提取格式，UI 录制/屏幕录制/对色彩敏感的源视频用 png（render.ts）；
• --low-memory-mode 自动按总内存检测（≤8 GB 启用），强制 1 worker + 截图捕获以避免内存抖动（render.ts）；
• --frames-cache-dir 可将内容寻址的抽帧缓存移出系统盘（Windows C: 空间不足时），支持别名禁用缓存（render.ts）。

feedback：渲染后的结构化反馈

渲染验证完成后，每个任务发送一行反馈。这是维护者的主要信号——静默完成的渲染对他们毫无信息量。

npx hyperframes feedback --rating 10                              # 干净运行，无备注
npx hyperframes feedback --rating 6 --comment "bg <video> renders grey in multi-scene; worked around with --format png-sequence"

--rating 为 0-10 的整数（必需）；--comment 为自由文本。反馈是匿名的，并自动附带 doctorSummary（OS/Node/CPU/mem/ffmpeg），所以不要重复这些字段（feedback.ts）。干净运行只需一句简短结果。

复现包模板

发送任何 bug、变通方案或困惑行为之前，收集这个紧凑复现包：

REPRO COMMAND: <HF_*/PRODUCER_* env> npx hyperframes <exact command>   # 从项目目录运行；不要粘贴绝对路径
EXPECTED / ACTUAL: <期望行为> / <观察到的行为与隔离后的触发条件>
EXACT ERROR: <逐字错误或警告；视觉缺陷需包含帧/时间戳>
OUTCOME: <output correct | output corrupt | fallback succeeded | hard exit | command hung>
WORKAROUND: <精确变通方案，或 none>
COMPOSITION_STRUCTURE:
  elements: video=<n> audio=<n> img=<n> svg=<n> canvas=<n> subComps=<n>
  attributes: <逗号连接的 clip-path, filter, mix-blend-mode, transform, mask, position:fixed, overflow:hidden, z-index, data-has-audio, data-duration, data-start, data-composition-src, background-image:url, mask-image:url 子集 —— 或 "(none present)">
  timeline: <flat | nested (<n> sub-comps)>; driver=<gsap | data-timeline | gsap+data-timeline | none>
  delta: <变通方案渲染与损坏的默认渲染之间差异>
  defect: <空间位置 + 帧索引范围，如 top-left / frames 0-30 —— 非视觉缺陷可省略>

COMPOSITION_STRUCTURE: 是保护隐私的结构解剖：只有计数与存在性标志，没有文件路径、src URL 或用户文本。它让维护者能对照已知 bug 族做模式匹配（如「子合成挂载 + clip-path」「GSAP 时间线 + z-index」），而无需接收合成 ZIP。评分 ≤ 7 且描述视觉缺陷（黑帧、闪烁、输出损坏、错帧、空白输出或其他视觉异常）时必须提供；更高评分可选但欢迎。Agent 可通过调用 compositionCensus.ts 中的 buildCompositionCensus(html) 与 renderCompositionCensusBlock(census) 对已有合成 HTML 自动填充该块——无需人工手填。

COMPOSITION_STRUCTURE 的实现细节（compositionCensus.ts）：

• 元素计数覆盖 video/audio/img/svg/canvas 及 data-composition-src 子合成挂载点；
• 结构属性探测同时检查内联样式与 <style> 标签内容，position:fixed 按值匹配避免与 position:absolute 误报；""/initial/inherit/revert 等空值不计数，而显式 none 视为作者意图、仍计入（compositionCensus.ts）；
• 时间线形状区分 flat 与 nested（子合成数），驱动源检测 GSAP（按 <script> src 或 gsap.timeline/to/from/fromTo/set 调用）与 data-start/data-duration 数据时间线（compositionCensus.ts）；
• 输入 HTML 超过 20 MB 上限时短路返回全零统计，避免 linkedom 被恶意文件打爆内存（compositionCensus.ts）。

匿名化与软警告

反馈提交到公开渠道——发送前必须匿名化。 脱敏绝对路径（泄漏用户主目录与机器身份）、路径中嵌入的用户/项目名、密钥与凭据。命令中的路径参数应保持相对于项目目录（./renders/out.mp4 而非 /Users/<user>/Documents/…/out.mp4；.hf-tmp/ 而非 /home/<user>/projects/<real-name>/.hf-tmp/）。同样从 EXACT ERROR: 的堆栈与日志摘录中剥离绝对路径——保留文件名基名与行号，去掉前导目录。HF_* / PRODUCER_* 变量与标志原样保留。若失败不再复现，附上最后一次失败的命令与日志摘录（同样脱敏）。仅在已有且可安全分享时才分享项目链接。

hyperframes feedback 会在两类情况下给出软警告：非 10 分的 --comment 缺少 REPRO COMMAND:，以及评分 ≤ 7 的视觉缺陷注释缺少 COMPOSITION_STRUCTURE:。警告打印在提交确认上方、不阻止提交——有些正当报告（如一行「cloudrun 配额昨天提升了，现在没事了」）本就不符合模板。补齐复现包后重跑即可消除警告。实现见 feedbackLint.ts，其中 COMPOSITION_STRUCTURE_RATING_CEILING = 7 定义了强制阈值（feedbackLint.ts）。

提交 GitHub issue

遇到可复现的 bug？加 --file-issue（可选加 --dir <project> 与 --yes 用于非交互 shell）可额外把最小复现发布到公网 URL，并打开一个预填好的 GitHub bug issue 草稿供维护者提交。这会公开发布项目，因此是 opt-in 且需同意；issue 从不自动提交。

publish：发布为稳定托管 URL

npx hyperframes publish              # 私有上传当前项目，返回稳定 URL
npx hyperframes publish ./my-video   # 指定项目
npx hyperframes publish --public     # 允许任何持链接者查看该项目
npx hyperframes publish --yes        # 跳过确认提示（脚本/CI）

上传项目的源（HTML + 资源）并返回一个可在浏览器中渲染的稳定托管 URL。新发布默认私有，需要认证并有访问权才能查看；--public 允许任何持链接者查看。原地更新项目保持其既有可见性：不带 --public 重新发布绝不会把公开项目变回私有；--yes 只跳过确认提示，不改变可见性。登出状态下发布返回的是需要认证的 claim URL，而非公开播放 URL。lint 发现会在上传前呈现，但不阻塞发布。

源码中 publish.ts 还暴露了更多形态：--update <url|id> 原地更新已发布项目（从 /p/<id> 路径提取 id 的解析见 parseUpdateTarget，publish.ts）、--space <space-id> 发布到共享团队空间，以及 --no-proxy 跳过为浏览器不友好视频编码（如 HEVC）烘焙 H.264 代理（publish.ts）。上传前若默认入口 index.html 为空（hasDefinitiveEntryMismatch），发布会中止并给出迁移建议——publish 接受项目目录而非单个 HTML 文件（publish.ts）。

完整工作流速查

以 Agent 交付一个视频项目为例：

1. 评审：npx hyperframes preview --background --port 3017，交付 http://localhost:3017/#project/<name>（或 storyboard 视图 URL）；Agent 用 preview --context --json 桥接选区信息执行用户指示性编辑；
2. 批准后渲染：迭代用 --quality draft，评审用 standard，交付用 --fps 60 --quality high；参数化项目用 --variables '{"title":"Q4 Report"}'；跨主机一致用 --docker；
3. 反馈：npx hyperframes feedback --rating 10；非干净运行附完整复现包（COMPOSITION_STRUCTURE 由 buildCompositionCensus 自动生成）；
4. 分享：npx hyperframes play（轻量播放器链接）或 npx hyperframes publish --public（稳定托管 URL），用 --yes 适配 CI 脚本。

参考资料：本技能其余命令见 skills/hyperframes-cli，技能根说明见 SKILL.md；渲染/预览相关的底层实现可继续阅读 render/plan.ts 与 render/execute.ts，选区快照类型定义在 packages/studio-server。