四阶段把文章做成可录屏 16:9 视频网页：web-video-presentation 完整指南

四阶段把文章做成可录屏 16:9 视频网页：web-video-presentation 完整指南

【免费下载链接】garden-skillsConardLi's open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址: https://gitcode.com/GitHub_Trending/we/garden-skills

做视频必须先做 PPT、再录配音、最后录屏对轨？garden-skills仓库里的web-video-presentation给了另一条路：让 Agent 用 Vite + React + TypeScript 写出一个"伪装成视频"的 16:9 网页演示，每点一次推进口播稿的一个节拍（beat），进度 UI 默认隐藏，录屏画面里只剩内容；网页完成后可选合成口播 mp3，浏览器打开?auto=1、按一下 Space，录屏软件一镜到底收片，音视频天然同步。它沉淀的不是样式模板，而是一套方法论与协作流程：内容、对齐、开发、音频、录制四个阶段，外加三个硬性检查点。

先搞懂一件事：narrations.ts 是全项目唯一真相源

开工之前先说一个贯穿全流程的事实：每章目录里的narrations.ts同时是step 数和口播文本的唯一来源，其余所有产出都以它为准——

• 章节代码里if (step === N)出现的最大 N + 1，必须等于narrations.length。代码写了 5 个分支，narrations.ts 就只能是 5 条，多一条少一条都是 bug。
• 音频合成只认它：npm run extract-narrations扫所有章节的 narrations.ts 生成audio-segments.json，TTS 再按段逐条合成 mp3。
• outline 里的 step 数只是初始预估，实现时以 narrations.ts 为准，发现不一致再回改 outline。

于是 script / outline / 章节代码 / chapters.ts / 音频文件这五处都被同一个文件锚住，谁和它不一致，跑一遍 extract 就能立刻发现。对应的工作目录如下（Agent 在你的当前目录下创建）：

my-video/ ├── article.md # 用户给的原文，不删——开发阶段画面的信息源 ├── script.md # 平台化口播稿，决定节拍 ├── outline.md # 开发计划：章节切分 + 每步内容 + 信息池 └── presentation/ # 脚手架产出的 Vite + React + TS 项目 ├── src/chapters/<NN>-<id>/ │ ├── <Chapter>.tsx │ ├── <Chapter>.css │ └── narrations.ts # step 数 + 口播文本的唯一真相源 ├── scripts/ │ ├── extract-narrations.ts │ ├── synthesize-audio.sh # provider-agnostic runner │ └── tts-providers/ # 一个 TTS 后端一个 .sh ├── audio-segments.json └── public/audio/<id>/1.mp3 # 合成口播，从 1 编号

命名规则值得记牢：章节 id 用小写 + 连字符（如coldopen），文件夹是0N-<id>，组件 PascalCase（Coldopen.tsx），CSS 类前缀用章节缩写（.cd-、.mg-），音频子目录名与 id 相同，文件名按 step 编号且1-indexed（对齐 narrations 数组 index + 1）。

五步走通：从一叠文字到成片

整体链路是：内容 → 对齐 → 开发 → 音频 → 录制。其中三个硬检查点 ⚠️ 分别是：稿子与计划写完后的Checkpoint Plan、第 1 章做完的强制验收、音频合成前的Checkpoint Audio。Agent 每到节点必须停下来等确认，不允许从一叠文字静默狂奔到成品代码——主题影响动效设计，大纲确认防止章节节奏漂移，这两件事省掉之后返工才最贵。

第 1 步 内容：一次产出 script.md 与 outline.md

Agent 对三种输入的处理不同：你给书面文章，它一次思考产出script.md+outline.md两份文件；你直接给口播稿，它落盘成 script.md 再补一份简化版 outline；你只说"帮我做个 X 主题的视频"，它会反问要素材——这个 Skill 不替你构思内容。

文章转口播的规则（完整规则在references/SCRIPT-STYLE.md）可以浓缩成三条底线：

• 信息保留度 ≥ 60%：口播稿是"换说法"不是"摘要"，关键数字、案例、论证链要逐项对得上；允许压缩的只有套话开场、重复总结、学术铺垫，禁止压缩关键数据与反方观点。
• 去 AI 味：假共情、假深刻、自我标榜、万能模板（"底层逻辑是……"）、连续排比，这五类念出来一耳朵是机器。落盘前真的要张嘴念一遍，念到"这话我说不出口"的地方就是 AI 味。
• 保持原文语言："B 站风格"只调节奏和结构，不改语言。平台变体有差异：B 站默认短句 ≤ 20 字 + 3 秒钩子，抖音/视频号压到 ≤ 12 字、1 秒钩子，YouTube 长视频可以放宽到 ≤ 30 字。

outline.md的定位是开发计划，不是视觉规划：只写章节切分、每步屏幕内容（一行、3~10s 估时）、每章首段从 article.md 抽的"信息池"（数字/引用/案例，每条带来源标注），不写动画。写死动画等于把章节开发者变成翻译机；留白，让实现的人按内容现场设计动线。章节切分的经验值：每章 3~8 步、30~60 秒，全部 step 估时累加与总时长误差 < 10%。

两份文件落盘后先走自检流程（下文"质量红线"再讲），才允许进入对齐。

第 2 步 对齐：Checkpoint Plan 一次定 5 件事

Agent 停下来，给你一次性摆出 5 个决定：

1. script.md要不要改？
2. outline.md要不要改？重点看章节切分、step 数、估时、每步屏幕内容、信息池够不够细节、素材清单是否完整。
3. 选哪个主题？Agent 会动态读全部themes/*/theme.json，按bestFor命中主动推荐 2~3 套，其余一句话带过，也可以让你做新主题。
4. 真素材怎么来？a) Agent 从现有素材挑 / b) 你提供 / c) 全部 placeholder。
5. 开发模式选哪个？

模式只影响第 2 章及之后——第 1 章无论哪种模式都是主线程开发 + 你验收：

你说"主题你帮我选"，Agent 会取推荐第 1 个，但必须告诉你选了什么、为什么，留反悔机会。中途随时能切模式：第 2 章验收通过后再说"剩下的并行"照样执行。

第 3 步 开发：脚手架、第 1 章验收，然后 2~N 章

一条命令生成项目，默认主题midnight-press：

bash skills/web-video-presentation/scripts/scaffold.sh ./presentation --theme=paper-press bash skills/web-video-presentation/scripts/scaffold.sh --list-themes

产物是普通 Vite + React + TS 应用，npm run dev即跑（默认 5173 端口，被占用自动换）。自带01-example演示章，写真实内容前先删掉该文件夹，并移除src/registry/chapters.ts里的对应注册项。

为什么第 1 章必须人工验收：它是章节开发规范（单一入口references/CHAPTER-CRAFT.md）在"你的主题 + 你的题材"下的第一次落地。规范有盲区、主题 token 不够用，第 1 章一定会暴露，此刻有人类反馈就能修规范、调主题，早改成本最低；后续章节无论顺序还是并行都要参考第 1 章的代码模式，它就是这个项目的"风格锚点"。第 1 章要求完整版本一次到位（节奏 + 视觉 + 真素材齐全），没有骨架版概念。验收时 Agent 会请你对五件事：视觉气质是否符合主题预期、节奏是否合适、动画是否内容驱动（有没有无脑入场动画）、画面上有没有"口播没念但 article 能挂"的细节、反 AI 味检查（紫粉渐变 / 圆角彩色边框 / emoji 图标）。

第 2 章起，每章独立按 CHAPTER-CRAFT 开发，风格不强求章章一致——颜色字体由主题 token 兜底统一，动画节奏由各章自由发挥，这本身就是设计预期。开发时有一批隐式生效的硬规则，它们是"视频感"的来源：

• 内容写在固定 1920×1080 坐标系里，靠 transform scale 适配视口，没有响应式。
• 章节是全局 step 游标的纯函数：if (step === N) return <FullScene />，一步独占整屏，无定时器。
• 控件默认 opacity 0、悬浮才出现；舞台无 header / footer / 页码 / 品牌条，录进画面的只有内容。
• 动效优先：每章至少 1~2 处"动起来的图"（数字递增、横条生长、流程节点依次点亮、连线自绘、模拟终端交互），整章纯文字 = 验收不过。
• 多点逐个揭示：讲"第一是 X、第二是 Y"必须拆成两个 step，讲 Y 时 X 灰化保留作上下文；严禁一个 step 把 N 项全部 stagger 上来。
• 双源原则：节奏跟 script.md，画面细节 / 数据 / 引用回 article.md 抽，让画面信息密度 > 口播密度。
• 颜色与字体家族走主题 token，禁硬编码 hex；hero 文字至少 80px、舞台四边留 80px 安全区；动画时长必须 ≤ 该 step 口播时长。
• 工程红线：不用setTimeout/setInterval驱动动画（用 CSS keyframes）；可交互元素加data-no-avoid-advance一类的防误触标记；章节代码物理隔离，不跨章 import。

实现单章时只读一份文件：references/CHAPTER-CRAFT.md（原则、开工 5 问、关系→动作决策树、视觉工具箱、反 AI 味、代码硬规则、完工自检、反馈速查全在这一份里）。另外，凡是改动chapters.ts（增删 / 重排章节，或某章 narrations 长度变化），都要 bumppresentation/src/hooks/useStepper.ts里的STORAGE_KEY（如v4→v5），否则本地持久化的游标会落到不存在的 step 上。

第 4 步 音频：可选，但决定你录制的方式

Phase 2 结束后 Agent 必须停下再问一次：是否合成音频（Checkpoint Audio ⚠️）。链路是：narrations.ts → audio-segments.json → TTS 逐段合成 → Auto 模式录制。

先抽取、再合成，而且合成前让人先看一眼 json 确认文本与切分：

cd presentation npm run extract-narrations npm run synthesize-audio # 默认 minimax，增量（跳过已存在） PRESENTATION_TTS=openai npm run synthesize-audio -- --voice=nova # 换 OpenAI TTS

runner 本身是 provider-agnostic 的：不知道任何 TTS 后端，只循环 segments、跳过已存在文件（断点续合不烧重复 token）、串行打印进度。每个后端就是scripts/tts-providers/下一个.sh文件，内置两个：minimax（默认，走mmx-cli，中文口播首选）和openai（curl +OPENAI_API_KEY，多数 agent 已有 key）。要换 ElevenLabs / edge-tts / macOS say / Azure / Google Cloud，目录 README 里有 5 段可粘贴片段，存成<name>.sh再设PRESENTATION_TTS=<name>即可；完全自研的 TTS 只需实现三函数契约：

合成完用 ffprobe 校验时长，重点盯 ≥ 15s 的条目（说明该 step 口播太密或没拆够，让用户决定改稿重合还是拆 step）：

for f in public/audio/*/*.mp3; do d=$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$f") echo "$f ${d}s" done

合成后运行时零额外配置，脚手架的App.tsx已接好：

Auto 模式的推进规则就一句话：每段音频播完 + 200ms 缓冲 → 自动推进，没有"等动画跑完"的兜底——视觉动画比口播长会被当场切。音频缺失或 narration 是空串时，退化到字数估时max(1500ms, 字数 × 250ms)，保证整片预览也能跑通。

第 5 步 录制：一镜到底

合成了音频的话，录制路径简单到可以背下来 ✅：

1. 浏览器全屏，URL 改成http://localhost:5173/?auto=1；
2. 看到 "Press SPACE to start" 蒙层 = Auto 就绪；
3. 打开屏幕录制（macOS 用 Cmd+Shift+5 或 QuickTime，跨平台用 OBS，捕获 1920×1080 / 60fps）；
4. 按一次 Space → 整片自动播完 → 停止录制；
5. 裁掉头尾，即成片。

全程不点鼠标，音视频天然同步，不需要后期对轨。跳过了音频合成则走备用路径：全屏打开 Manual 模式，刷新一次清空历史游标，开录后按口播节奏点击推进，后期用 DaVinci Resolve / iMovie / CapCut / 剪映 配音调时间线。Agent 的义务是在 Checkpoint Audio 后主动告诉你该走哪条路。

质量红线：三关自检 + 四条工程铁律

全流程有三道自检闸门：script.md完成、outline.md完成、单章实现完成，每个都必须走"自检 → 修复 → 再汇报"。执行方式按能力降级：最优是开独立 reviewer agent（Agent Teams），传"产出文件路径 + 对应清单 + 关键上下文"，让它逐项给出 pass/fail 结论、证据与改写建议；没有 Teams 就用 subagent 走同样流程；都没有就自己严格逐项核查——不允许目测一遍放行。铁律：拿到结论后先按 fail 项把产出改完，再汇报"做完了 + 自检结论 + 改了什么"，直接拿原始结论汇报但不修复算违规。

工程层面还有四条，破了就是返工：

• narrations.ts 长度 = 代码中if (step === N)最大 N + 1，唯一真相源不许旁路；
• 动chapters.ts后 bumpSTORAGE_KEY；
• 动画时长 ≤ 该 step 口播时长，Auto 模式不会等你；
• 颜色 / 字体家族走 token，章节 CSS 不硬编码——换主题后某章看起来坏了，bug 在章节不在主题。

主题系统：23 套内置，换肤只覆盖一个文件

整片从头到尾只跑一个主题，禁止章节间翻转明暗（录屏里像很硬的剪辑）。主题 = 一组 CSS 设计 token + 一份theme.json元数据，每套约 25~35 个 token。章节对 token 的消费分两层：颜色 + 字体家族必须走 token（换主题不破的底线）；字号 / 间距 / 动画时长 / 缓动 / 边框宽度可硬编码自由发挥，动画气质参考theme.json的mood（字段本身不写 ms 数值）。hero 数字、分割线、卡片、舞台装饰通过 primitive class（.hero-num/.rule/.card/.stage-frame）自动接入，章节直接用 class 即可。

内置 23 套主题各有独立设计 DNA：深色 8 套（midnight-press、dark-botanical、chalk-garden、blueprint、terminal-green、neon-cyber、bold-signal、creative-voltage），浅色 15 套（paper-press、newsroom、monochrome-print、vintage-editorial、sunset-zine、pastel-dream、warm-keynote、electric-studio、bauhaus-bold、swiss-ikb、dune、indigo-porcelain、forest-ink、kraft-paper、split-canvas）。必填 token 包括：表面色 4 个（--shell/--surface/--surface-2/--surface-3）、文字 4 个（--text/--text-2/--text-mute/--text-faint）、Accent 3 个（--accent是唯一饱和色，另两个是它的透明度衍生）、字型家族 4 个（--font-display-cn/--font-display-en/--font-body/--font-mono），另有--r-card、--rule-w/--rule-style、--stage-pad-x/y、阴影等可选性格 token。

脚手架会把所选主题的tokens.css拷进项目、主题 id 写入.theme标记文件，之后切换主题 = 一次文件覆盖：cp skills/web-video-presentation/themes/newsroom/tokens.css presentation/src/styles/tokens.css，刷新 dev server 即完成，章节代码一行没动。

创作新主题：复制最接近的主题做起点 → 按契约改tokens.css（调色板 → 字体 → 性格旋钮 → 阴影 → 装饰层，不碰字号 / 间距 / 时长尺度）→ 改theme.json（id必须等于目录名，字段含name/nameZh/descriptionZh/mood/bestFor/preview）→ 用 demo 章节测试一遍。几条不显而易见的规则：深色主题里--shell比--surface更深更饱和，浅色主题里略灰；--text与--surface对比度至少 4.5:1；--text-faint在 13px 大写小字下仍要可读；挑一个设计签名重重发力（虚线分割 / 粗黑边 / 扫描线 / 纸纹 / glass slab），别同时叠三个。

常见坑与最佳实践

• 录制时动画被切一半：Auto 严格按音频结束推进，说明该 step 动画长于口播。三选一：写更长口播 / 拆 step / 调动画速度，不要重做整章。
• 游标落到不存在的 step：动过chapters.ts或 narrations 长度却没 bumpSTORAGE_KEY。
• mmx CLI not found in PATH/mmx is not authenticated：runner 启动时会自己报这两类错，装mmx-cli、重新登录即可。
• 中文口播不像真人：OpenAI 六种音色都偏英语，中文角色换默认 minimax。
• 整段合成被截断：单段撞 API 长度上限（mmx 约 5000 字符 / OpenAI 约 4096），回 narrations.ts 拆成两条——那个 step 本就该拆两个。
• 音频 404 但 Auto 还能跑：缺 mp3 时退化为字数估时，这是兜底不是成功，别误以为已合成。
• 换主题后某章"坏了"：该章硬编码了颜色 / 字体 / 尺寸，bug 在章节里，不在主题里。
• 用户反馈"哪里不对劲"：先定位是哪一层（节奏 / 视觉 / 内容 / 代码），再改最小切片；并行模式下各章风格略有漂移是预期，token 兜底视觉统一。

参考文件索引

全部位于skills/web-video-presentation/：

• SKILL.md——完整工作流、三个硬检查点、自检协议、各阶段读取指南
• README.md——概述、核心思想、23 套主题画廊
• references/CHAPTER-CRAFT.md——章节开发单一入口（原则 / 开工 5 问 / 决策树 / 视觉工具箱 / 反 AI 味 / 代码硬规则 / 完工自检 / 反馈速查）
• references/SCRIPT-STYLE.md——文章 → 口播稿规则、去 AI 味五类、平台变体
• references/OUTLINE-FORMAT.md——outline 字段规范、命名约定、章节切分经验、信息池
• references/THEMES.md——完整 token 契约、主题清单、创作新主题流程
• references/AUDIO.md——音频合成流程、内置 provider 用法、换 provider 路径、故障排查表
• references/RECORDING.md——录屏工具与后期
• references/EXAMPLES/——章节结构示意（看形，不照搬）
• templates/scripts/tts-providers/README.md——provider 三函数契约 + 5 段现成代码片段
• scripts/scaffold.sh——一键脚手架
• themes/——23 套内置主题（每套含theme.json+tokens.css）

【免费下载链接】garden-skillsConardLi's open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址: https://gitcode.com/GitHub_Trending/we/garden-skills