1实现原理 · 为什么它能做到
把 HyperFrames 定为中文旁白视频的唯一生产面（不止教学视频），并明令不走旧的 web-video-presentation 路线，除非用户明确要点击驱动的网页演示。
skills/hyperframes-teaching-video/SKILL.md
Use HyperFrames as the primary production surface for Chinese narrated videos, not only teaching videos. … Do not use the old Web Video Engineer / `web-video-presentation` implementation path unless the user explicitly asks for a click-driven webpage presentation.
这里在做什么：为「同名目录遗留的旧路线」划清界限，同时要求继承旧路线的耐用品：narration-first、大字幕、16:9 检查、显式渲染验证。
默认视觉与语气：Apple Keynote / macOS 风、口语化，且禁止公式化开场（如 AI 时代，别再…）与对观众露出的内部标签（s03、文件夹名）。
skills/hyperframes-teaching-video/SKILL.md
Use Apple Keynote / macOS style unless the user gives a stronger reference … Avoid starting with formulaic lines like "AI 时代，别再...".
这里在做什么：把「不像 AI 生成」的措辞层规则前置，并规定中文优先（英文只留给代码标识、API 名、UI 名）。
先写旁白再动画，且写稿唯一参考是 references/CODE-GARDEN-VOICEOVER.md；开写前先在 DESIGN.md 写一句定位句。
skills/hyperframes-teaching-video/SKILL.md
For narration drafting or rewriting, read `references/CODE-GARDEN-VOICEOVER.md` first. … Before writing the script, write a one-sentence **positioning statement** in `DESIGN.md`
这里在做什么：防止 workflow/case-study/showcase 的请求漂移成通用「怎么用这个工具」教程——定位句强制先声明体裁（教程/解释/案例拆解/产品展示/流程拆解/踩坑复盘/发布资产）。
单一 sync manifest 作真相源：旁白、字幕、场景起点都从它派生，而不是手维护三份数组。
skills/hyperframes-teaching-video/SKILL.md
Keep one sync manifest as the source of truth for narration, subtitles, and scene starts.
这里在做什么：用 assets/sync-script.json（{ "scene": "#scene-3", "text": "..." } 形状）生成 narration.txt、sync-map.js 与 HTML 时长，从机制上避免「网页 step 与音频文件数对不上」。
TTS 有具体默认值：Doubao/Volcano seed-tts-2.0 + zh_male_liufei_uranus_bigtts + speech_rate=20；Edge TTS 作备选并给男女音色与 +20% 语速建议。
skills/hyperframes-teaching-video/SKILL.md
In `/Users/d2/project/web vidio` projects, default to Doubao / Volcano `seed-tts-2.0`, voice `zh_male_liufei_uranus_bigtts`, and `speech_rate=20` unless the user says otherwise. … Recommended Edge TTS defaults for Chinese: voice `zh-CN-YunxiNeural` for a male presenter voice, or `zh-CN-XiaoxiaoNeural` for a female presenter voice; rate `+20%` unless the user requests a slower or faster delivery.
这里在做什么：把作者本机的生产约定写死（含一个本机绝对路径 /Users/d2/project/web vidio），并给出「豆包凭证不可用且 Edge TTS 可接受」时的降级条件与前置检查（command -v edge-tts）。
时长必须来自实测音频：有音频文件时禁止用字数、Edge TTS 词边界元数据或旁白文本估算，并要求 ffprobe 复核后回填时长与 cue 时机。
skills/hyperframes-teaching-video/SKILL.md
Do not estimate timing from character count, Edge TTS word-boundary metadata, or narration text alone when audio files exist.
这里在做什么：把「字幕与画面入场跟口播同步」变成可测量约束；换 TTS 提供方时必须重生成旁白、sync map、字幕、场景时机与 MP4，禁止旧 sync map 配新音频。
字幕规格具体到像素与行数：约 66-72px 中文、强对比或阴影、默认居中底部纯文字（无「旁白」标签、无大底板）、可见字幕保持单行。
skills/hyperframes-teaching-video/SKILL.md
Keep visible subtitles to one line. … Use roughly 66-72px Chinese text for burned-in HyperFrames subtitles, strong contrast or shadow, and enough bottom margin to avoid covering the scene focus.
这里在做什么：把「1080p 录屏里读得清」当硬指标；若 cue 会换行就拆成相邻更短 cue 并重生成 TTS/时机，而不是接受渲染出两行。
HyperFrames 实现契约照抄生态约定：根元素带 data-duration、audio 用真实 <audio> 元素、在 window.__timelines 注册暂停的 GSAP 时间线、确定性动画、默认柔和交叉淡化转场。
skills/hyperframes-teaching-video/SKILL.md
Register a paused GSAP timeline in `window.__timelines` and build deterministic animation.
这里在做什么：明确禁止全屏擦除、白闪、扫光条、硬 visibility 切换与易空白的转场（除非用户明确要高能效果），并要求元素逐个随口播出现而不是一次铺满。
验证只看真实产物：npm run check（或 hyperframes lint/inspect）、渲染 MP4 后 ffprobe 查真实时长、ffmpeg 抽接触表逐项目视。
skills/hyperframes-teaching-video/SKILL.md
ffprobe -v error -show_entries format=duration,size -of json renders/final.mp4
这里在做什么：把「说做完」绑定在真实 MP4 上，并给出七项目视清单（无空帧/无掉落转场、当前旁白点视觉最强、元素随口播入场、字幕不挡关键内容、中文标签、时长符合节奏、字幕单行无多余标签）。
发布草稿有安全阀：可以用真实浏览器准备草稿并核对字段，但在用户确认平台/账号/标题文案/标签/MP4/封面之前不点最终发布。
skills/hyperframes-teaching-video/SKILL.md
When using a live browser to upload to social platforms, prepare drafts and verify fields, but do not click the final publish/submit button until the user confirms
这里在做什么：把「自动化发布」限制在草稿阶段，最终提交留人工确认；这是本 skill 唯一的对外动作红线。
2核心能力
01中文旁白视频的通用生产（教学、解释、产品演示、流程拆解、案例研究、展示片、社交短片）而不是只做教学
02基于真实音频时长的同步旁白 + 大字幕（单行、66-72px、默认居中底部纯文字）
03TTS 双路线：Doubao/Volcano（seed-tts-2.0，刘飞 2.0，speech_rate 20）与 Edge TTS（zh-CN-YunxiNeural / zh-CN-XiaoxiaoNeural，+20%）
04TTS 前置检查与拒绝静默降级：先 command -v edge-tts 或 import edge_tts，缺依赖就报阻断而不是偷偷换提供方/换慢速默认值
05HyperFrames HTML 合成实现：data-duration、真实 <audio>、window.__timelines 暂停 GSAP 时间线、元素逐个入场、柔和交叉淡化转场
06真实 MP4 验证与抽帧复核（hyperframes lint/inspect、ffprobe 真实时长、ffmpeg 接触表 + 七项目视清单）
07封面/缩略图与发布草稿资产（9:16 海报、平台文案与标签、草稿状态与核对项）
08常见返修处方（太短→加解释重写旁白、无焦点→错峰入场+压暗旧元素、转场空白→改交叉淡化、字幕太小/换行→改字号或拆 cue）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | HyperFrames CLI（lint / inspect；渲染经项目 npm run render 或 npx hyperframes） |
| cli | ffprobe / ffmpeg（真实时长核对、抽接触表） |
| api | Doubao / Volcano 语音合成（seed-tts-2.0，需凭证；本 skill 未自带客户端，走项目 TTS 脚本） |
| cli | Edge TTS（免豆包 key，但需网络与 edge-tts CLI/Python 包） |
| network | 社交平台网页（用真实浏览器准备发布草稿，需用户确认后才提交） |
| reference | 口播写作参考（随包分发）：references/CODE-GARDEN-VOICEOVER.md |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: （本 skill 目录内无脚本、无模板、无可执行代码）
- 网络端点: 声明外部网络访问: 语音合成：Doubao / Volcano TTS（凭证由项目 TTS 脚本持有）或 Edge TTS（必须联网，免豆包 key）
- 本地工作目录: 文件读写与工件输出: 项目内：DESIGN.md（含定位句与所选 TTS 提供方/音色/语速）、assets/sync-script.json 与由其生成的 narrati
审计说明： 。本 skill 自身目录只有 SKILL.md、references/CODE-GARDEN-VOICEOVER.md 与 agents/openai.yaml（无脚本、无端点、无凭证读取代码），触发橙档的是 SKILL.md 自身声明的生产路径：① **语音合成后端**——默认点名 Doubao / Volcano seed-tts-2.0（需账号凭证）并给出 Edge TTS 作为免 key 备选（仍需联网），旁白文本因此送外部服务；② **发布草稿**——指示用真实浏览器在社交平台准备草稿并核对字段（账号相关动作，虽明令提交前必须用户确认）；③ **素材检索**——要求需要当前/外部影像时去搜索并把素材存本地而非热链。三者的外部对象都可预期且都给了人工确认或降级路径（Edge TTS 免 key、草稿不点提交），未见安全降级（无 TLS 关闭、无 --no-verify）、反自动化绕过（无 AutomationControlled/真实键击替身）、沙箱关闭或任意代码执行面。
5第二遍独立确认
- [ok] 本 skill 是否夹带脚本/凭证读取（档位下限依据） — find 目录只返回 SKILL.md、references/CODE-GARDEN-VOICEOVER.md、agents/openai.yaml；grep 无 process.env / fetch / curl 调用点。所有外部能力都以「指示」形式出现，由项目侧脚本或宿主 CLI 执行。
- [ok] TTS 外部依赖与凭证是否真实存在（橙档依据） — SKILL.md 原文给出 Doubao/Volcano seed-tts-2.0 + zh_male_liufei_uranus_bigtts + speech_rate=20 的项目默认，并写 'Edge TTS does not require the Doubao API key, but it still needs network access and the `edge-tts` CLI or Python package installed.' 即既确认凭证类后端存在，也确认有免 key 备选。
- [ok] 社交平台动作是否越界（是否会自动发布） — 原文 'When using a live browser to upload to social platforms, prepare drafts and verify fields, but do not click the final publish/submit button until the user confirms the exact platform, account, title/copy/tags, MP4, and cover.' 明确把最终提交留给人工确认，属安全阀而非绕过。
- [discrepancy] 文档里写死的本机路径对其他使用者意味着什么 — ［判定：私有前提，非缺陷］SKILL.md 写 'In `/Users/d2/project/web vidio` projects, default to Doubao / Volcano `seed-tts-2.0` …'——该默认值绑定作者本机目录；在别处使用需替换为本地路径/项目约定，否则「默认音色语速」这一段不适用（不是安全风险，但是可见的可移植性问题）。
- [ok] 字幕/时长是否真以实测音频为准（避免估算冒充） — SKILL.md 明写 'Do not estimate timing from character count, Edge TTS word-boundary metadata, or narration text alone when audio files exist.' 并要求对每段或最终音频跑 ffprobe、由真实时长重生成 sync-map.js；缺依赖时要求报阻断而不是静默换提供方或换慢速默认值。
- [ok] 仓库级验证/提交指示是否真在文档中（工程侧影响） — SKILL.md 末尾 'If the target is inside a git repository, inspect the diff, run verification, and commit the task-related changes unless there is no change, no repository, or a real blocker.'——即 skill 会指示 agent 做 git 提交；已在 file_writes 与 risks 中标注，供使用者知情。
6结论
适合： 适合用 HyperFrames 生产中文旁白视频的个人或小团队：教学视频、解释器、产品/能力展示、工作流与案例拆解、社交短片，且已有（或愿意搭）Doubao/Volcano 或 Edge TTS 的配音路径与 npm run check/render 脚本。也适合需要「按实测音频对齐字幕与画面入场」的严格节奏控制场景。
不适合： 不适合：① 要用点击驱动网页演示路线的场景（应走同仓库的 web-video-presentation）；② 完全不能把旁白文本交给外部 TTS 且无本地 TTS 的环境；③ 不做人眼复核的纯自动化流水线（验收含目视清单）；④ 不想让 agent 触碰 git 提交的仓库（需先改掉文档末尾的提交指示或明确禁用）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload hyperframes-teaching-video.tar.gz
sha256:
Option B · Copy Guide for Agent4d726d1ecfb6c878…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit f2c70b812b.