用途 HyperFrames CLI 面向动效视频项目的开发与制作流程，覆盖从项目脚手架到最终渲染交付的各环节。命令以 npx hyperframes ... 形式运行；若项目提供了 wrapper，则按 wrapper 执行。环境要求为 Node.js 22 或更高版本，并需要 FFmpeg。
主要能力
- 脚手架与示例：npx hyperframes init <project> 创建居中空白项目；可用 --example=<name> 从命名示例起步。
- 动效检索与安装：写动效前先用 npx hyperframes catalog --query "<英文描述的动效>" 查找现成原语，再用 npx hyperframes add <name> 安装；只有确实无匹配时才手写。
- 时间线查看：npx hyperframes timeline --json 输出轨道、片段、起止时间与所属文件，嵌套行携带绝对时间 absStart/absEnd；建议优先用 --json。
- 快速反馈：首次 HTML 编写后及结构性改动后运行 npx hyperframes lint。
- 最终门禁：npx hyperframes check 会先跑 lint，再用单次浏览器会话审计运行时错误、失败请求、布局、*.motion.json 断言与 WCAG 对比度；持续性问题影响退出码，瞬时进出场问题仅作提示。--strict 可让警告也参与门禁。
- 子合成检查：npx hyperframes snapshot --at <t1>,<t2>,<t3>；或 --composition <id> --frames 8、--range 3:5 --frames 8 抽样。无样式的小内容、画布尺寸图标、缺失主视觉元素、时间线注册超时视为阻塞渲染的挂载缺陷。
- 预览：check 通过后运行 npx hyperframes preview --background，确认 URL 返回 HTTP 200，把时间线项目 URL 交给用户并询问是否修改或渲染。渲染前必须获得用户对最终视频的明确批准。
- 渲染质量：--quality draft 用于迭代，--quality looks 用于首次真实编码（CLI 默认），--quality delivery 用于最终交付。
- 其他渲染方式：--docker --strict（可复现容器渲染）、--batch rows.json（本地变量驱动批处理）、cloud render（HeyGen 托管）、lambda render（自管 AWS）、cloudrun render（自管 GCP）。
- 输出核验：确认文件存在且非空，读取渲染摘要第二行（beginframe vs screenshot、GPU、各阶段耗时），用 ffprobe 检查时长与帧率是否匹配根 data-duration，并像预览时一样对解码帧做视觉检查。
- 项目历史：每一笔写入都保留为可撤销条目。每轮开始运行 history begin --who <name> --label "..."，再用 history --since mine --who <name> 查看他人在上一轮后的改动；检查失败或用户反馈变差时用 history undo --who <name> 撤销自己最新一轮；每轮结束运行 history end。一轮打开期间，连续 10 分钟无写入则自动结束。
- Studio 选区查询：用户提到“这个元素”或当前选区时，用 npx hyperframes preview --context --json --context-fields selection 查询，取 selection.target.hfId，否则用其 selector 与源文件；返回 no-selection 时请用户点击元素后重试。
- 目录检索：搜索完全在本地进行，无需账号，查询文本不外发。默认按名称、标题、描述、标签的词面匹配；加 --on-device 可按语义排序，需一次性约 33 MB 下载（bge-small-en-v1.5 量化 ONNX 及分词器，缓存于 ~/.hyperframes/），须先向用户说明体积并取得同意，不可静默启用。查询用英文描述，即使成片是其他语言。--json 返回 query、tier、tier_detail、dropped、unindexed、shown、total、results 及可能的 top_score、warnings 与 report_gap。dropped 与 unindexed 是两种相反的偏差，改查询措辞无法解决；unindexed 大于零时可重跑 --on-device 重新拉取索引，纯 over-coverage 偏差只能清理 ~/.hyperframes/catalog/。
- 搜索无果反馈：npx hyperframes feedback --search-miss "<查询>" --wanted "<所需动效>" --tier <tier>，这是唯一会把查询发送出去的路径，且需显式执行。
使用约定
- 代理与 CI 调用优先加 --json；服务端模式的 render、preview、play 不提供普通 JSON 输出，preview --selection --json 与 preview --context --json 为查询模式例外。
- doctor --json 总是退出码 0，需用 jq -e '.ok' 判断结果。
- 同一验证循环中的所有命令使用同一个 HYPERFRAMES_RUN_ID。
- 磁盘紧张时运行 npx hyperframes clean（先 --dry-run 查看清单），只清理失效渲染残留和可重建的空闲缓存，不动输出、源码或运行中渲染所用内容；不要整体删除 .hyperframes（其中含项目历史）。
- 需要以警告、变量或 CI 条件作为门禁时使用 --strict、--strict-all、--strict-variables。
- 长渲染若会被工具随进程组一起终止，可用 HYPERFRAMES_RENDER_DETACHED=1 在独立进程组中启动。
- 渲染不得仅因检查通过就自动进行，必须在最终预览处暂停等待批准。
- JSON 路径中的家目录以 $HOME 脱敏，不要尝试还原。
- 云端托管项目接近或超过 200 MB 上传限制时，用 cloud render --dry-run --json 并参考 .hyperframesignore 处理，不要仅因文件大就忽略资源。
适用场景 适合需要以命令行走完动效视频“检索组件—编写—静态检查—运行时审计—截帧核验—预览—渲染”闭环的开发者与自动化流程，也适合需要 Docker 可复现渲染、批处理变量渲染或托管/分布式渲染的团队。
限制与未提供信息 依赖 Node.js 22+ 与 FFmpeg；语义检索需额外下载约 33 MB 模型；catalog 索引为英文，非英文查询无法检索；lint 仅识别静态 shader 表达式，软件渲染可能漏掉硬件相关的无效像素；渲染前必须取得最终批准。官方资料未提供具体的收费与价格信息，暂未提供。