HyperFrames — 先读这个
对于任何 HyperFrames 任务,请从这里开始 — 尤其是在没有项目代理配置(CLAUDE.md / AGENTS.md / .cursorrules)的情况下。以下是能力地图和视频路由表。
能力地图 — 哪种技能对应哪种意图
| 你想做什么… | 请前往 |
|---|---|
| 制作视频(基于 URL、简短描述、主题、GitHub PR、现有素材或单个要动画化的元素) | 下面的 视频路由表(§ 视频路由) |
| 编写幻灯片 / 演示文稿 / 提案 — 离散幻灯片、片段、分支、热点区域 | /slideshow |
编写/编辑 HTML 合成 — data-* 契约、片段、轨道、子合成、变量 | /hyperframes-core |
| 动画 — 原子运动规则、场景蓝图、过渡效果、运行时适配器(GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | /hyperframes-animation |
创意指导 — design.md、调色板、字体、旁白、节拍规划、音频响应式 | /hyperframes-creative |
| 媒体预处理 — TTS 配音、背景音乐、转录、背景移除、字幕 | /hyperframes-media |
| CLI 开发循环 — 初始化、代码检查、验证、检查、预览、渲染、发布、诊断 | /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 / 网络动画来源没有可转换的 Remotion 源码 — 请通过/general-video重新创建。 - 它无法生成自身没有的输入。 不支持屏幕/会话录制、摄像头捕获、AI 说话头像/唇形同步虚拟形象生成。如果素材或资源尚不存在,HyperFrames 无法凭空生成 — 请先要求用户提供(或使用正确的捕获工具)。
其他情况 — 从 URL、简短描述、主题、PR、要注释的素材或单个要动画化的元素制作视频 — 都在范围内;请在下方的路由表中处理。
视频路由
此部分仅知道顶级工作流。它不加载工作流内部的阶段、领域技能(hyperframes-* — 请参阅上方的能力地图)或技术参考。
决策表
输入类型(意图)是主要判断轴;输出时长仅作为上限,而非门控条件。 对于匹配的输入,专业化工作流可以处理长达约 3 分钟的内容 — _哪个_工作流由意图(输入类型,对于文本则是主题)决定,而非时长。时长仅在顶端有意义:真正较长的片段(3-5 分钟教程、5 分钟+深度解析)属于不同的范畴,应路由到 /general-video。在 ≤~3 分钟的区间内,第三个轴用于区分两个文本输入的工作流 — 主题:是_营销_产品,还是_解释_某个主题(请参见下方步骤 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/<所有者>/<仓库>/pull/<数字>链接、所有者/仓库#数字引用、或“这个 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/<数字>、所有者/仓库#数字、“这个 PR”) →/pr-to-video;否则,网站 URL 根据意图拆分 — 营销 / 发布 / 推广特定产品或 SaaS →/product-launch-video;一般网站 → 视频(网站导览、作品集/博客/着陆页展示、从网站自身视觉元素制作社交媒体片段、或仅仅是“把这个网站变成视频”) →/website-to-video。两者都使用无头 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 可以联网搜索该网站并抓取其品牌资源(除非用户选择退出 → 切换到 no-capture 预设模式)。不粘贴 URL 不会将其变成 faceless / no-capture 工作。对于提供的脚本,逐字复制与重构之间的选择是 PLV 内部的决定,绝不会改变路由。
- 矛盾线索 → 询问,不要猜测。 如果提供的来源是产品自身的营销材料(其着陆页、宣传文案……)
- 一个正在被营销、发布或推广的特定产品 / 公司 / SaaS / 应用 / 网站 →
- URL 类型 + 意图 — URL 不再自动默认为 PLV;首先由它的_类型_然后_意图_决定:一个 GitHub PR 链接(