HyperFrames — 请先阅读此文档
开始任何 HyperFrames 任务前请先阅读此处 — 尤其是当项目中不存在代理配置文件(CLAUDE.md / AGENTS.md / .cursorrules)时。下面是能力地图和视频路由指南。
能力地图 — 根据意图选择对应技能
| 你想… | 前往 |
|---|---|
| 制作视频(来自 URL、需求简述、主题、GitHub PR、现有素材或单个需要动画的元素) | 请见下方的视频路由(§ 视频路由) |
创作/编辑 HTML 组合 — data-* 契约、剪辑片段、时间轨、子组合、变量 | /hyperframes-core |
| 制作动画 — 原子运动规则、场景蓝图、过渡效果、运行时适配器(GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | /hyperframes-animation |
创意指导 — design.md、调色板、字体排印、旁白、节奏规划、音频响应式处理 | /hyperframes-creative |
| 媒体预处理 — TTS 语音合成、背景音乐、字幕转录、背景去除、封闭字幕 | /hyperframes-media |
| CLI 开发循环 — 初始化、lint 检查、校验、预览、渲染、发布、诊断 | /hyperframes-cli |
安装注册表块/组件(hyperframes add) | /hyperframes-registry |
组合创作契约(每个时间元素需要
data-start/data-duration/data-track-index;时间元素需要class="clip";GSAP 时间线必须暂停并注册到window.__timelines;只能使用确定性逻辑——禁止Date.now()/Math.random()/ 网络调用)在此不再重复——请参见/hyperframes-core。在编写组合 HTML 之前请先阅读该文档。
HyperFrames 不能做什么 — 请先确认此项
HyperFrames 通过代码创作 HTML 组合并渲染为 MP4。这种模式有严格的限制。如果一个请求超出了这些限制,这并非路由选择问题——而是超出范围,因此应拒绝(或指向正确的工具),而不是尝试进入某个工作流。这些限制源自其架构,并非来自单个请求:
- 渲染是确定性的且自包含的。 每个值、资源和文本在创作时就被注入;渲染过程不进行网络调用,也不在渲染时拉取实时数据(核心规则:禁止
Date.now()/Math.random()/ 网络调用)。"在渲染时刷新实时数据"是不允许的——请在创作时一次性获取数据并注入,否则请拒绝。 - 现有视频只能被叠加,而不能被编辑。 HyperFrames 在源剪辑片段之上组合帧——
/embedded-captions添加字幕层,/graphic-overlays添加精心设计的图形卡片(下方三分之一、数据标注、标题)——而底层的剪辑片段不变,但无法后期处理编码后的视频流。改变素材本身(其时间、色彩、构图、顺序或音频)属于 NLE 风格编辑,超出范围。 - Remotion 导入是单向的。
/remotion-to-hyperframes将 Remotion 框架的源码转换为 HyperFrames。不存在反向转换(HyperFrames → Remotion,或 → 任何其他框架——超出范围),而且非 Remotion 的 React/Web 动画源码本身就不具有 Remotion 源码可转换——请通过/general-video重新创建。 - 无法凭空产生它不拥有的输入。 不支持屏幕/会话录制、摄像头捕获、AI 虚拟主播/唇形同步头像生成。如果素材或资源尚不存在,HyperFrames 无法凭空生成——请要求用户先提供(或使用正确的捕获工具)。
其他所有情况——来自 URL、需求简述、主题、PR、需要标注的素材或单个需要动画的元素——都属于范围内,请按下方规则路由。
视频路由
本节仅了解顶层工作流。它不加载工作流内部的阶段、领域技能(hyperframes-*——请参见上方的能力地图)或技术参考。
决策表
输入类型(意图)是主要维度;输出长度仅作为上限,而非门控条件。 对于匹配的输入,专用工作流可处理最长约 3 分钟的内容——选择哪个工作流由意图(输入类型,对于文本则是主题)决定,而非长度。长度仅在高端有意义:真正更长的片段(3-5 分钟的教程,5 分钟以上的深度探索)属于不同格式,应路由到 /general-video。在 ≤~3 分钟区间内,第三个维度区分了两个基于文本的工作流——主题:被营销的产品 vs 被解释的概念(请参见下方步骤 3 中的消歧规则)。
| 长度 / 输入 | 产品发布(URL / 简述 / 脚本) | 通用网站 / URL | GitHub PR / 代码变更 | 主题 / 文章 / 笔记(无产品、无 URL) | 现有视频(人物出镜)† |
|---|---|---|---|---|---|
| ≤ ~3 分钟 | /product-launch-video | /website-to-video | /pr-to-video | /faceless-explainer | /embedded-captions · /graphic-overlays † |
| 3-5 分钟教程 | /general-video | /general-video | /general-video | /general-video | /embedded-captions · /graphic-overlays † |
| 5 分钟以上深度探索 | /general-video | /general-video | /general-video | /general-video | /embedded-captions · /graphic-overlays † |
| 静态 / 循环 | /general-video | /general-video | /general-video | /general-video | /general-video |
当前覆盖范围:≤ ~3 分钟区间拥有针对产品发布 / 通用网站 / GitHub PR / 主题输入的专用工作流(URL 先按种类再按意图拆分——请参见步骤 3),而现有视频列支持任何长度——由 /embedded-captions(字幕/标题)或 /graphic-overlays(设计好的图形叠加)按照意图拆分(请参见步骤 2)。其他所有单元格均为 /general-video——通用的 HTML 组合创作流程(对输入和长度无感):包括所有超过约 3 分钟的情况(3-5 分钟 / 5 分钟以上的行)以及所有静态/循环格式。路由器不会在可创作的视频上走入死胡同;唯一真正的“通用/无”答案是指超出 HyperFrames 范围本身的请求(例如对已完成视频文件进行 NLE 风格编辑——重新调整时长、重新着色、重新构图、重新排序、重新配置音频)。
† 现有素材按意图而非长度拆分。 字幕/标题 → /embedded-captions;设计好的图形叠加/包装——下方三分之一、数据标注、带标题的卡片、引用块 → /graphic-overlays。两者均在剪辑片段之上叠加,底层片段保持不变;两者都不编辑素材本身。
类型短路(优先于上表)。 短小(约 10 秒以下)、无旁白、以设计为主导的动效图形——动态排版、统计数据/图表展示、标志片头、下方三分之一/叠加层、或动画推文/标题/捕获页面高亮——路由到 /motion-graphics,无论输入是什么。它是一种 输出类型,而非输入类型,因此当请求明显是以动效为先且无旁白时(请参见步骤 2),它优先于上述的输入类型表。较长或带有旁白的处理方式将根据输入类型路由,或路由至 /general-video。
迁移现有组合(特殊情况)
上表适用于根据输入创作视频。有一个工作流不在其中:如果用户明确要求将现有的 Remotion (React) 组合移植/转换/迁移到 HyperFrames → /remotion-to-hyperframes。这是源码翻译,而非从输入创作,因此它没有 输入 × 长度 单元格。仅在出现明确的迁移语言("移植我的 Remotion 项目"、"转换这个 Remotion 组合"、"将其重写为 HyperFrames")时路由至此——随意提及 Remotion 并不触发;默认使用创作表或 /hyperframes-core。
路由流程
- 确定输入类型 + 目标长度。 路由需要知道视频的内容——其主题和输入。如果主题本身未明确(例如"制作一个关于我们产品的视频"但没有提供 URL、命名产品、主题或素材),或输入类型未知,请在进入任何工作流之前询问——先澄清;不要先调用工作流技能然后再问,因为承诺某个工作流本身就是路由决策。最多提出 2 个澄清问题:
- "你的输入是什么——产品(URL 或简述)、通用网站/URL、GitHub PR/代码变更、要解释的主题或文章、还是需要添加字幕的现有出镜视频?"
- "目标时长——约 3 分钟以内,还是更长(3-5 分钟的教程 / 5 分钟以上的深度探索)?"
- 规格默认值——直接陈述,无需询问(这些不会影响路由,因此永远不要阻塞路由):宽高比 16:9(引擎也支持 9:16 竖向——仅在用户指定了竖向投放平台(如 TikTok / Reels / Shorts)时切换);旁白/字幕语言 = 用户的。仅在用户反驳时确认;所选工作流会在其步骤 0 中重新确认自身具体参数。
- 首先按输入类型(意图)选择;长度仅作为上限,而非门控条件。
- 简短且以设计为主导的动效图形(类型短路,优先于输入表) ——动效本身就是信息:动态排版、统计数据/数字递增、图表展示、标志片头、下方三分之一/叠加层、或动画推文/标题/捕获页面高亮;通常小于约 10 秒,无旁白/配音 →
/motion-graphics。这是输出类型,而非输入类型——当请求明显是一个快速、无旁白、以设计为主导的动效作品时,无论输入是什么都路由至此。较长或带有旁白的相同素材处理方式不属于此类型(应根据输入类型路由,或路由至/general-video)。 - 现有出镜视频(用户有一段剪辑片段,并希望在其上添加内容)→ 按意图拆分,无论长度(输入类型优先于长度):字幕/标题(将口语转换为可读文本)→
/embedded-captions;设计好的图形叠加——下方三分之一、数据标注、带标题的信息卡片、引用块、图形包装后的编辑 →/graphic-overlays。(编辑素材本身——重新调整时长、重新着色、重新构图、重新排序、音频——属于 NLE 风格,超出范围;请参见 § HyperFrames 不能做什么。) - GitHub PR / 代码变更(
github.com/<owner>/<repo>/pull/<N>链接、owner/repo#N引用或"这个 PR")→/pr-to-video(最长约 3 分钟)。 - 其他情况(产品 URL / 简述 / 主题文本):意图通过步骤 3 选择工作流,并且可以处理最长约 3 分钟的内容——15-30 秒的短预告和约 100 秒的讲解视频都按意图而非长度路由。仅当目标明显长于约 3 分钟(3-5 分钟的教程,5 分钟以上的深度探索)时,路由至
/general-video(对长度无感的后备方案——请参见步骤 4)。切勿将真正长的作品强行放入 ≤~3 分钟的工作流——意图在区间内决定,其余由/general-video覆盖。
- 简短且以设计为主导的动效图形(类型短路,优先于输入表) ——动效本身就是信息:动态排版、统计数据/数字递增、图表展示、标志片头、下方三分之一/叠加层、或动画推文/标题/捕获页面高亮;通常小于约 10 秒,无旁白/配音 →
- 消歧 ≤~3 分钟的 URL / 文本输入(意图拆分)。 两种拆分方式:
- URL 种类 + 意图——URL 不再自动归为 PLV;其种类然后意图决定:GitHub PR 链接(
.../pull/<N>、owner/repo#N、"这个 PR")→/pr-to-video;否则网站 URL 按意图拆分——营销/发布/推广特定产品或 SaaS →/product-launch-video;通用网站 → 视频(网站介绍、作品集/博客/落地页展示、网站自身视觉素材的社交媒体片段,或仅"把这个网站做成视频")→/website-to-video。两者都使用 headless Chrome 爬取;PR URL 通过gh读取。当确实不清楚某个网站 URL 是产品发布还是通用网站视频时,请提出一个问题。 - 产品 vs 主题(文本,无 URL)——决定性问题是视频是关于什么的,而非输入格式:
- 正在被营销、发布或推广的具体产品/公司/SaaS/应用/网站 →
/product-launch-video。 - 正在被解释的概念/主题/文章/某事物的工作原理,且没有产品和 URL →
/faceless-explainer。 - 决胜规则:"推广 / 发布 / 销售 / 我们的产品"的措辞 → PLV。"解释 / 教学 / X 如何工作 / 什么是 X"且无产品 → faceless。faceless 的默认风格始终是
pin-and-paper。 - 已命名网站但未粘贴 URL 仍属于 PLV。 提及产品或其网站的脚本("我们的网站是 acme.io"、"推广 <品牌>")即使没有可点击的链接也路由至 PLV——PLV 可以网络搜索该网站并爬取其品牌资源(除非用户拒绝,→ 无捕获预设模式)。不粘贴 URL 并不会使其成为 faceless / 无捕获任务。提供脚本时,逐字使用 vs 重新组织的选择是 PLV 内部的事,从不改变路由。
- 冲突线索 → 询问,不要猜测。 如果提供的来源是产品自身的营销材料(其落地页、关于他们平台的促销博客),但用户明确要求去除促销性质——对底层概念的中立解释,而非广告——应视为存在真正的歧义(该视频是...
- 正在被营销、发布或推广的具体产品/公司/SaaS/应用/网站 →
- URL 种类 + 意图——URL 不再自动归为 PLV;其种类然后意图决定:GitHub PR 链接(
…
[因长度限制,原文已截断]