logamee-film-forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Logamee Film Forge

This skill is the project manager for automated PPT-style videos. It is a pure-text workflow guide. It does not bundle JavaScript libraries, TTS engines, browsers, ffmpeg, or model weights. The user's agent installs and verifies those dependencies in the local environment before the dependent step runs.

It does not create a video from chat memory. It creates a chain of files, and every step reads the previous step's file output.

The workflow has two execution modes, and the mode must be chosen before any project artifact is created:

```
auto
```
: continue through the pipeline without waiting between ordinary steps. The agent still records decisions, runs machine checks, and stops for safety-critical approvals such as missing dependencies, unclear source, or an explicitly required human review.
```
semi-auto
```
: stop after every step, report the artifact just created and the checks performed, then wait for the user's feedback before starting the next step. Do not silently continue because the next step appears obvious.

The project directory is also a required user decision. Before saving source, creating

environment-check.md

, or generating any other project artifact, ask the user to confirm the exact

workdir

. Record the chosen directory and execution mode in

project-config.md

at the project root. Never invent a project directory from the current working directory, a previous project, or a similarly named demo.

该技能是自动化PPT风格视频的项目管理器，是一份纯文本工作流指南。它不捆绑JavaScript库、TTS引擎、浏览器、ffmpeg或模型权重。用户的Agent需在依赖步骤运行前，在本地环境中安装并验证这些依赖项。

它不会从聊天记忆中生成视频，而是创建一系列文件，每个步骤都会读取上一步的文件输出。

工作流有两种执行模式，必须在创建任何项目工件前选择：

```
auto
```
：在常规步骤之间无需等待，持续执行流程。Agent仍会记录决策、运行机器检查，并在遇到安全关键型审批环节时停止，例如依赖项缺失、来源不明或明确需要人工审核的情况。
```
semi-auto
```
：每完成一个步骤后停止，报告刚创建的工件和执行的检查，然后等待用户反馈后再启动下一步。即使下一步看似显而易见，也不得静默继续。

项目目录也是用户必须决定的内容。在保存源文件、创建

environment-check.md

或生成任何其他项目工件之前，请用户确认确切的

workdir

project-config.md

中。切勿从当前工作目录、先前项目或类似命名的演示中凭空生成项目目录。

Core Rules

核心规则

Do not rely on conversation memory as workflow state. If chat history and files conflict, files win.
```
project-config.md
```
is the authoritative project setup record. It must contain the user-confirmed absolute
```
workdir
```
and either
```
auto
```
or
```
semi-auto
```
mode.
At the end of every numbered step, update
```
project-config.md
```
with
```
Current Step
```
,
```
Last Completed Step
```
, and any blocker or pending user decision.
In
```
semi-auto
```
mode, do not start the next numbered step until the user gives feedback after the current step. A generated file is not permission to continue.
If a required input file is missing or stale, stop and regenerate it. Do not guess.
```
article.md
```
is the original source and is never edited.
```
content-understanding.md
```
proves that the source was understood before any slide planning begins.
```
theme-extraction.md
```
is the only theme input used by HTML generation. Never copy layout, components, typography systems, or animations from the source theme skill.
```
storyboard.md
```
is the user-facing creative master. Users review and edit this single file.
Every video must have a cover frame. The cover is written at the top of
```
storyboard.md
```
, enters the final video timeline, and stays for about 3 seconds by default.
```
slide-specs/
```
is generated from
```
storyboard.md
```
by freezing. Do not hand-edit slide specs.
```
visual-logic.md
```
is required before HTML generation. It turns each slide's meaning into visual form and semantic animation. Do not skip it.
```
deck.html
```
is a render artifact, not a text source.
Before any paid, remote, cloned, or token-heavy TTS call, create a local subtitle-and-slide preview from
```
Narration
```
and get user approval. Do not spend TTS calls on text that has not passed subtitle review.
Before storyboard approval, run a narration read-aloud pass. This is not rewriting the argument; it only adjusts sentence breaks, punctuation rhythm, long-sentence splitting, and terminology spacing so TTS can speak steadily.
Audio timing is the final clock. Use TTS durations to replace estimated slide timing.
After TTS, do not enter
```
?preview=1
```
with duration-weighted subtitle estimates. First generate a timestamp artifact from the real audio, normally
```
subtitles.json
```
for browser preview and
```
subtitles.srt
```
for final video.
Whisper or another timestamp tool provides timing only. Display subtitle text still comes from
```
slide-specs/NN.md
```
```
Narration
```
, unless the user explicitly approved a subtitle text edit.
Page changes need a small pause. Do not make slides feel like one continuous scrolling transcript.
Before recording, the browser preview is the screening room.

不要依赖对话记忆作为工作流状态。如果聊天记录与文件冲突，以文件为准。
```
project-config.md
```
是权威的项目设置记录。它必须包含用户确认的绝对
```
workdir
```
以及
```
auto
```
或
```
semi-auto
```
模式。
在每个编号步骤结束时，更新
```
project-config.md
```
中的
```
Current Step
```
、
```
Last Completed Step
```
以及任何阻塞问题或待处理的用户决策。
在
```
semi-auto
```
模式下，必须在用户对当前步骤给出反馈后，才能启动下一个编号步骤。生成文件并不意味着可以继续执行。
如果所需的输入文件缺失或过期，请停止操作并重新生成该文件，切勿猜测。
```
article.md
```
是原始源文件，绝不编辑。
```
content-understanding.md
```
用于证明在开始任何幻灯片规划之前，源内容已被正确理解。
```
theme-extraction.md
```
是HTML生成所使用的唯一主题输入。切勿从源主题技能中复制布局、组件、排版系统或动画。
```
storyboard.md
```
是面向用户的创意主文件。用户只需审阅和编辑这一个文件。
每个视频必须包含封面帧。封面位于
```
storyboard.md
```
的顶部，会进入最终视频时间线，默认停留约3秒。
```
slide-specs/
```
由
```
storyboard.md
```
冻结生成。请勿手动编辑幻灯片规格。
在生成HTML之前，必须创建
```
visual-logic.md
```
。它将每张幻灯片的含义转换为视觉形式和语义动画，切勿跳过此步骤。
```
deck.html
```
是渲染工件，而非文本源文件。
在进行任何付费、远程、克隆或消耗大量令牌的TTS调用之前，根据
```
Narration
```
创建本地字幕和幻灯片预览，并获得用户批准。切勿在字幕未通过审核的文本上消耗TTS调用。
在分镜脚本获得批准之前，进行旁白朗读检查。这并非改写论点，仅调整句子断句、标点节奏、长句拆分和术语间距，以便TTS能够平稳朗读。
音频时长是最终的时间基准。使用TTS时长替换预估的幻灯片时长。
TTS生成后，不要使用基于时长加权的字幕预估进入
```
?preview=1
```
模式。首先从真实音频生成时间戳工件，通常是用于浏览器预览的
```
subtitles.json
```
和用于最终视频的
```
subtitles.srt
```
。
Whisper或其他时间戳工具仅提供时间信息。字幕显示文本仍来自
```
slide-specs/NN.md
```
的
```
Narration
```
，除非用户明确批准了字幕文本编辑。
页面切换需要短暂停顿。不要让幻灯片看起来像连续滚动的文稿。
在录制之前，浏览器预览是审查环节。

Pipeline

流程

confirm workdir + execution mode
  ↓
project-config.md
  ↓
environment-check.md
  ↓
article.md
  ↓
content-understanding.md
  ↓
theme-extraction.md
  ↓
storyboard.md
  ↓ freeze
slide-specs/
  ↓
visual-logic.md
  ↓
deck.html
  ↓
local subtitle-and-slide preview
  ↓
audio/ + durations + precise subtitles
  ↓
?preview=1
  ↓
output.mp4

semi-auto

mode, pause for user feedback after each arrow's destination artifact is created and checked. In

auto

mode, continue ordinary arrows without waiting, while preserving the same artifacts and safety checkpoints.

确认workdir + 执行模式
  ↓
project-config.md
  ↓
environment-check.md
  ↓
article.md
  ↓
content-understanding.md
  ↓
theme-extraction.md
  ↓
storyboard.md
  ↓ 冻结
slide-specs/
  ↓
visual-logic.md
  ↓
deck.html
  ↓
本地字幕与幻灯片预览
  ↓
audio/ + 时长 + 精准字幕
  ↓
?preview=1
  ↓
output.mp4

在

semi-auto

模式下，每个箭头指向的目标工件创建并检查完成后，暂停并等待用户反馈。在

auto

模式下，常规步骤无需等待即可继续，但会保留相同的工件和安全检查点。

Working Directory Layout

工作目录布局

This skill needs a working directory, not a full application scaffold. Do not create

package.json

requirements.txt

, or project boilerplate unless the user explicitly asks for a reusable software project.

Use the directory only to store durable workflow artifacts:

workdir/
├── project-config.md
├── environment-check.md
├── article.md
├── content-understanding.md
├── theme-extraction.md
├── storyboard.md
├── slide-specs/
│   ├── cover.md
│   ├── 01.md
│   ├── 02.md
│   └── ...
├── visual-logic.md
├── deck.html
├── gsap.min.js
├── audio/
│   ├── 01.wav or 01.mp3
│   ├── 02.wav or 02.mp3
│   ├── all.wav or all.mp3
│   ├── final-mix.wav or final-mix.mp3
│   ├── durations.json
│   ├── tts-metadata.md
│   └── subtitle-alignment.md
├── subtitles.json
├── subtitles.srt
└── output.mp4

Use two-digit slide numbers:

, ... Do not add redundant prefixes inside folders.

The clean example directory should not keep render caches or debugging output. After a successful final assembly, remove transient folders and files such as

render/

, temporary browser profiles, rendered frame sequences, one-off helper scripts, raw TTS response logs, raw recognizer JSON, word timestamp caches, concat lists, and short TTS samples. Keep the durable artifacts above so another agent can inspect, resume, or explain the workflow from files alone.

该技能需要一个工作目录，而非完整的应用脚手架。除非用户明确要求创建可复用的软件项目，否则请勿创建

package.json

、

requirements.txt

或项目样板文件。

仅使用该目录存储持久化的工作流工件：

workdir/
├── project-config.md
├── environment-check.md
├── article.md
├── content-understanding.md
├── theme-extraction.md
├── storyboard.md
├── slide-specs/
│   ├── cover.md
│   ├── 01.md
│   ├── 02.md
│   └── ...
├── visual-logic.md
├── deck.html
├── gsap.min.js
├── audio/
│   ├── 01.wav 或 01.mp3
│   ├── 02.wav 或 02.mp3
│   ├── all.wav 或 all.mp3
│   ├── final-mix.wav 或 final-mix.mp3
│   ├── durations.json
│   ├── tts-metadata.md
│   └── subtitle-alignment.md
├── subtitles.json
├── subtitles.srt
└── output.mp4

使用两位数的幻灯片编号：

、

……文件夹内请勿添加冗余前缀。

示例目录应保持整洁，不要保留渲染缓存或调试输出。成功完成最终组装后，删除临时文件夹和文件，如

render/

、临时浏览器配置文件、渲染帧序列、一次性辅助脚本、原始TTS响应日志、原始识别器JSON、单词时间戳缓存、合并列表和简短TTS样本。保留上述持久化工件，以便其他Agent仅通过文件即可检查、恢复或解释工作流。

Artifact Contract

工件约定

The workflow must be able to resume from files alone.

Source artifacts:

```
project-config.md
```
: user-confirmed absolute
```
workdir
```
, execution mode, source pointer, and current workflow status.
```
article.md
```
: original source, never rewritten.
```
storyboard.md
```
: user-approved creative master.
```
environment-check.md
```
: local dependency and capability record.

Frozen artifacts:

slide-specs/cover.md

and

slide-specs/NN.md

: generated only from

storyboard.md

Each slide spec must carry the current
```
storyboard-hash
```
.

Derived artifacts:

```
content-understanding.md
```
```
theme-extraction.md
```
```
visual-logic.md
```
```
deck.html
```
```
audio/NN.wav
```
or
```
audio/NN.mp3
```
```
audio/all.wav
```
or
```
audio/all.mp3
```
```
audio/final-mix.wav
```
or
```
audio/final-mix.mp3
```
```
audio/durations.json
```
```
audio/tts-metadata.md
```
```
audio/subtitle-alignment.md
```
```
subtitles.json
```
```
subtitles.srt
```
```
output.mp4
```

Derived artifacts may be regenerated. When an upstream artifact changes, downstream artifacts are stale until rebuilt.

Staleness rules:

```
article.md
```
change invalidates every downstream artifact.
```
content-understanding.md
```
change invalidates
```
storyboard.md
```
and everything after it unless the user explicitly confirms the old storyboard still applies.
```
theme-extraction.md
```
change invalidates
```
deck.html
```
and all visual previews, but does not rewrite narration.
```
storyboard.md
```
change invalidates
```
slide-specs/
```
,
```
visual-logic.md
```
,
```
deck.html
```
, local subtitle preview, TTS audio for affected narrated slides, timing, subtitles, preview, and recording.
```
visual-logic.md
```
change invalidates
```
deck.html
```
, local subtitle-and-slide preview, preview, and recording.
```
deck.html
```
change invalidates visual review, local subtitle-and-slide preview, browser preview, and recording.

TTS profile or narration change invalidates affected slide audio,

audio/all.*

audio/durations.json

subtitles.json

subtitles.srt

?preview=1

, and

output.mp4

Never continue from a stale artifact just because the conversation says it is probably fine.

工作流必须能够仅通过文件恢复。

源工件：

```
project-config.md
```
：用户确认的绝对
```
workdir
```
、执行模式、源指针和当前工作流状态。
```
article.md
```
：原始源文件，绝不改写。
```
storyboard.md
```
：用户批准的创意主文件。
```
environment-check.md
```
：本地依赖项和能力记录。

冻结工件：

slide-specs/cover.md

和

slide-specs/NN.md

：仅从

storyboard.md

生成。

每个幻灯片规格必须包含当前的
```
storyboard-hash
```
。

派生工件：

```
content-understanding.md
```
```
theme-extraction.md
```
```
visual-logic.md
```
```
deck.html
```
```
audio/NN.wav
```
或
```
audio/NN.mp3
```
```
audio/all.wav
```
或
```
audio/all.mp3
```
```
audio/final-mix.wav
```
或
```
audio/final-mix.mp3
```
```
audio/durations.json
```
```
audio/tts-metadata.md
```
```
audio/subtitle-alignment.md
```
```
subtitles.json
```
```
subtitles.srt
```
```
output.mp4
```

派生工件可以重新生成。当上游工件发生变化时，下游工件会过期，直到重新构建。

过期规则：

```
article.md
```
更改会使所有下游工件失效。
```
content-understanding.md
```
更改会使
```
storyboard.md
```
及其之后的所有工件失效，除非用户明确确认旧的分镜脚本仍然适用。
```
theme-extraction.md
```
更改会使
```
deck.html
```
和所有视觉预览失效，但不会改写旁白。
```
storyboard.md
```
更改会使
```
slide-specs/
```
、
```
visual-logic.md
```
、
```
deck.html
```
、本地字幕预览、受影响旁白幻灯片的TTS音频、时长、字幕、预览和录制失效。
```
visual-logic.md
```
更改会使
```
deck.html
```
、本地字幕与幻灯片预览、预览和录制失效。
```
deck.html
```
更改会使视觉审查、本地字幕与幻灯片预览、浏览器预览和录制失效。
TTS配置文件或旁白更改会使受影响的幻灯片音频、
```
audio/all.*
```
、
```
audio/durations.json
```
、
```
subtitles.json
```
、
```
subtitles.srt
```
、
```
?preview=1
```
和
```
output.mp4
```
失效。

切勿仅因对话中说“可能没问题”就继续使用过期工件。

Environment and Capability Requirements

环境与能力要求

The user's agent is responsible for installing missing dependencies. This skill must state what is needed, probe before dependent steps, and stop with an actionable missing-dependency report instead of guessing.

Dependency policy:

Do not embed GSAP, Playwright, ffmpeg, TTS engines, Whisper, or other runtime dependencies inside this skill.
Do not use CDN scripts in generated decks.
Install dependencies into the user's local machine, a user-level tool cache, or the working directory's local assets as appropriate.
After every installation, run the probe again. Do not continue until the probe passes.
If installation needs network access or elevated permissions, ask the user before running it.
Record installed tools, versions, and any local asset paths in
```
environment-check.md
```
.
If the user's goal is a final video, run a full-video environment check before Step 1. Phase-by-phase checks are only acceptable when the user explicitly wants to stop before audio or recording.

Required capabilities:

visual constraint checking for layout, overlap, safe areas, and animation states
frontend-quality review for typography, composition, density, and visual hierarchy

Optional theme sources:

any user-selected and successfully loaded theme/design skill
a user-provided token file or visual reference whose license permits reuse
an explicit no-theme choice, producing conservative neutral tokens

Optional theme sources are not dependencies. Never assume a named third-party skill is installed or redistributable.

Common system tools:

Node.js / npm, when a local HTTP server, Playwright tooling, or JS helpers are needed
ffmpeg, for audio concatenation, muxing, subtitles, and transcoding
Playwright or another browser automation tool, for browser preview and recording
TTS tool selected by the user at the Step 9 voice-source gate; do not install or assume one before that choice
timestamp/transcription tool, such as Whisper or another word/subtitle timestamp generator
local HTTP server, when browser audio loading or preview mode cannot work from
```
file://
```
GSAP local browser bundle, normally
```
gsap.min.js
```
, for slide animation timelines

Probe commands should be simple and replaceable:

bash

node --version
npm --version
ffmpeg -version
python3 --version

用户的Agent负责安装缺失的依赖项。该技能必须说明所需的依赖项，在依赖步骤运行前进行探测，并停止操作并提供可操作的缺失依赖项报告，切勿猜测。

依赖项策略：

不要在该技能中嵌入GSAP、Playwright、ffmpeg、TTS引擎、Whisper或其他运行时依赖项。
不要在生成的演示文稿中使用CDN脚本。
根据情况，将依赖项安装到用户的本地机器、用户级工具缓存或工作目录的本地资源中。
每次安装后，重新运行探测。直到探测通过后才能继续。
如果安装需要网络访问或提升权限，请在运行前询问用户。
将已安装的工具、版本和任何本地资源路径记录在
```
environment-check.md
```
中。
如果用户的目标是生成最终视频，请在步骤1之前运行完整的视频环境检查。只有当用户明确希望在音频或录制步骤前停止时，才允许分阶段检查。

必备能力：

针对布局、重叠、安全区域和动画状态的视觉约束检查
针对排版、构图、密度和视觉层次的前端质量审查

可选主题来源：

任何用户选择并成功加载的主题/设计技能
用户提供的许可允许复用的标记文件或视觉参考
明确选择无主题，生成保守的中性标记

可选主题来源不是依赖项。切勿假设某个第三方技能已安装或可重新分发。

常见系统工具：

Node.js / npm：当需要本地HTTP服务器、Playwright工具或JS辅助工具时使用
ffmpeg：用于音频拼接、混流、字幕处理和转码
Playwright或其他浏览器自动化工具：用于浏览器预览和录制
用户在步骤9语音源环节选择的TTS工具；在做出选择前，请勿安装或假设使用某一工具
时间戳/转录工具，如Whisper或其他单词/字幕时间戳生成器
本地HTTP服务器：当浏览器音频加载或预览模式无法通过
```
file://
```
运行时使用
GSAP本地浏览器包，通常为
```
gsap.min.js
```
：用于幻灯片动画时间线

探测命令应简单且可替换：

bash

node --version
npm --version
ffmpeg -version
python3 --version

Probe the user-selected TTS command or API adapter here.

在此探测用户选择的TTS命令或API适配器。

npx playwright --version test -f gsap.min.js


Suggested install guidance for missing tools:

- Node.js / npm: install through the user's normal package manager, such as Homebrew, Volta, nvm, or the official installer.
- ffmpeg: install through the user's package manager, such as Homebrew on macOS.
- Playwright: install with npm in the user's preferred tool location, then run the browser install step required by Playwright.
- GSAP: install or download locally through npm, then copy or reference the local `gsap.min.js` in the working directory or a known local asset path. Generated HTML must load this local file, not a CDN URL.
- TTS: install or configure only the channel selected at Step 9. A free online candidate may use `edge-tts`, while local/offline or custom API channels need their own documented probe.
- Whisper/timestamp tool: install only when precise subtitle timestamps are needed; until then, use measured slide audio duration and narration-based subtitle splitting.
- Prefer an isolated tool environment for heavy timestamp tools such as `whisper-timestamped`, WhisperX, or forced-alignment libraries. Do not install them into the user's main Python/Conda environment when they may change NumPy, SciPy, PyTorch, numba, or llvmlite versions.

Installation shape:

- Prefer user-level or tool-cache installation over embedding libraries into the skill.
- A per-workdir dependency cache such as `.deps/` is acceptable when the user wants the video folder to be self-contained, but it is still a dependency cache, not an application scaffold.
- Do not create `package.json` in the workdir root unless the user explicitly asks for a software project.
- For GSAP, a typical agent action is: install `gsap` locally, locate `node_modules/gsap/dist/gsap.min.js`, copy it to the deck's local asset path, then verify `deck.html` loads that local file.
- For Playwright, a typical agent action is: install Playwright tooling, install the browser runtime, then verify a browser can open the local preview page.
- For ffmpeg, verify both basic transcoding and subtitle support before recording with burned subtitles.

Do not install dependencies silently unless the user asks for auto setup. If a tool is missing, tell the user which tool their agent should install, why it is needed, which step is blocked, and which probe must pass afterward.

npx playwright --version test -f gsap.min.js


缺失工具的建议安装指南：

- Node.js / npm：通过用户常用的包管理器安装，如Homebrew、Volta、nvm或官方安装程序。
- ffmpeg：通过用户的包管理器安装，如macOS上的Homebrew。
- Playwright：在用户偏好的工具位置通过npm安装，然后运行Playwright要求的浏览器安装步骤。
- GSAP：通过npm本地安装或下载，然后将本地的`gsap.min.js`复制到演示文稿的本地资源路径，确保生成的HTML加载该本地文件，而非CDN URL。
- TTS：仅安装或配置步骤9中选择的渠道。免费在线候选工具可使用`edge-tts`，而本地/离线或自定义API渠道需要各自的文档化探测。
- Whisper/时间戳工具：仅在需要精准字幕时间戳时安装；在此之前，使用测量的幻灯片音频时长和基于旁白的字幕拆分。
- 对于`whisper-timestamped`、WhisperX或强制对齐库等重型时间戳工具，优先使用隔离的工具环境。当它们可能改变NumPy、SciPy、PyTorch、numba或llvmlite版本时，请勿将其安装到用户的主Python/Conda环境中。

安装形式：

- 优先选择用户级或工具缓存安装，而非将库嵌入技能中。
- 当用户希望视频文件夹自包含时，每个工作目录的依赖缓存（如`.deps/`）是可接受的，但它仍然是依赖缓存，而非应用脚手架。
- 除非用户明确要求创建软件项目，否则请勿在工作目录根目录创建`package.json`。
- 对于GSAP，Agent的典型操作是：本地安装`gsap`，找到`node_modules/gsap/dist/gsap.min.js`，将其复制到演示文稿的本地资源路径，然后验证`deck.html`加载该本地文件。
- 对于Playwright，Agent的典型操作是：安装Playwright工具，安装浏览器运行时，然后验证浏览器可以打开本地预览页面。
- 对于ffmpeg，在录制带嵌入字幕的视频之前，验证基本转码和字幕支持。

除非用户要求自动设置，否则请勿静默安装依赖项。如果工具缺失，请告知用户其Agent应安装哪个工具、为什么需要该工具、哪个步骤被阻塞以及之后必须通过哪个探测。

Environment Bootstrap

环境引导

Before Step 1, after Step 0 has created and verified

project-config.md

, create or update

environment-check.md

Never run Environment Bootstrap before the user has confirmed the project directory and execution mode.

environment-check.md

belongs inside the confirmed

workdir

; it must not be written to a guessed or legacy directory.

Output:

undefined

在步骤1之前，步骤0创建并验证

project-config.md

之后，创建或更新

environment-check.md

。

在用户确认项目目录和执行模式之前，切勿运行环境引导。

environment-check.md

必须位于已确认的

workdir

内；不得写入猜测的或遗留的目录。

输出内容：

undefined

Environment Check

环境检查

Required Capabilities

必备能力

visual constraint checking:
frontend-quality review:

视觉约束检查：
前端质量审查：

System Tools

系统工具

node:
npm:
python3:
ffmpeg:
playwright:
TTS:
timestamp tool:

node：
npm：
python3：
ffmpeg：
playwright：
TTS：
时间戳工具：

Local Browser Assets

本地浏览器资源

gsap.min.js:

gsap.min.js：

Recording Capability

录制能力

browser automation:
ffmpeg subtitle support:

浏览器自动化：
ffmpeg字幕支持：

Result

结果

Ready / Blocked

就绪 / 阻塞

Blockers

阻塞问题


Rules:

- If a required skill is missing, stop and tell the user which skill must be installed.
- If a required tool for the current phase is missing, stop before that phase.
- If the user chooses a custom/cloned TTS, its probe belongs in `environment-check.md`.
- If `gsap.min.js` is missing before HTML generation, stop and instruct the user's agent to install or fetch GSAP locally, then rerun the check.
- Do not proceed from environment bootstrap with `Result: Blocked`.


规则：

- 如果必备技能缺失，停止操作并告知用户必须安装哪个技能。
- 如果当前阶段所需的工具缺失，在进入该阶段前停止操作。
- 如果用户选择了自定义/克隆的TTS，其探测应包含在`environment-check.md`中。
- 如果在HTML生成前`gsap.min.js`缺失，停止操作并指导用户的Agent本地安装或获取GSAP，然后重新运行检查。
- 如果`Result: Blocked`，切勿继续环境引导。

Human Checkpoints

人工检查点

Ask for confirmation at these checkpoints unless the user explicitly chose

auto

mode. In

semi-auto

mode, also stop after every numbered step and wait for feedback before proceeding:

Project setup: confirm the exact project directory and choose
```
auto
```
or
```
semi-auto
```
before creating any artifact.
```
environment-check.md
```
: confirm required skills, local dependencies, browser assets, TTS, ffmpeg, and recording capability are ready, or ask permission for the user's agent to install missing pieces.
```
content-understanding.md
```
: confirm the content was understood correctly.
```
theme-extraction.md
```
: confirm the borrowed color/mood direction.
```
storyboard.md
```
: confirm static cover frame, page order, screen text, narration, and content-slide animation intent.
```
deck.html
```
: confirm visual layout and semantic animation after self-checks.
Local subtitle-and-slide preview before TTS: confirm narration text, subtitle splitting, estimated rhythm, slide changes, and whether the picture and subtitles match without calling TTS.
TTS audio preview and precise timing calibration: confirm voice, speed, pauses, exact subtitle timing, slide changes, and animation rhythm inside a previewable deck.
```
?preview=1
```
: final full-run confirmation before recording, if the previous preview was partial or has been regenerated.

Machine checks do not replace these checkpoints. They only catch mechanical issues.

除非用户明确选择

auto

模式，否则在这些检查点需要请求确认。在

semi-auto

模式下，每个编号步骤完成后也需停止并等待反馈，然后再继续：

项目设置：在创建任何工件之前，确认确切的项目目录并选择
```
auto
```
或
```
semi-auto
```
模式。
```
environment-check.md
```
：确认必备技能、本地依赖项、浏览器资源、TTS、ffmpeg和录制能力已就绪，或请求用户允许其Agent安装缺失的组件。
```
content-understanding.md
```
：确认内容已被正确理解。
```
theme-extraction.md
```
：确认借用的颜色/风格方向。
```
storyboard.md
```
：确认静态封面帧、页面顺序、屏幕文本、旁白和内容幻灯片动画意图。
```
deck.html
```
：在自检后确认视觉布局和语义动画。
TTS前的本地字幕与幻灯片预览：确认旁白文本、字幕拆分、预估节奏、幻灯片切换以及画面与字幕是否匹配，无需调用TTS。
TTS音频预览和精准时长校准：确认语音、语速、停顿、精准字幕时长、幻灯片切换和预览演示文稿内的动画节奏。
```
?preview=1
```
：如果之前的预览是部分的或已重新生成，在录制前进行最终的完整运行确认。

机器检查无法替代这些检查点，它们仅能捕捉机械问题。

Interactive Decision Points

交互式决策点

This skill is interactive by default. The first interaction is mandatory: ask the user to choose the execution mode and confirm the project directory before creating or modifying any project artifact. Do not silently default to auto mode or infer a directory from context.

Execution modes:

```
auto
```
: continue through ordinary pipeline steps without waiting for a message after each step. Keep the artifact chain and machine verification; stop only at explicit human checkpoints, safety blockers, or decisions that cannot be inferred.
```
semi-auto
```
: after every numbered step, stop and report: the step completed, files created or changed, verification result, and the next step. Wait for explicit user feedback before proceeding. A message such as "继续" or an equivalent approval is required; do not treat silence as approval.

The mode applies to the whole project unless the user explicitly changes it. If the user changes mode, record the change in

project-config.md

before continuing.

Ask the user at these points unless the answer is already explicit in the current request or stored in

project-config.md

Project setup: exact project directory (
```
workdir
```
) and execution mode (
```
auto
```
or
```
semi-auto
```
).
Dependency installation: when probes fail, whether the user's agent may install the missing local dependencies, and where to install them.
Theme source: whether to use a user-selected theme skill/template style, or continue with no external theme.
Narration perspective: first-person author voice, objective explanatory voice, or third-person report voice.
Storyboard approval: whether
```
storyboard.md
```
is approved for freezing.
Brand mark: whether every page needs a fixed footer-like identifier. This is optional and defaults to empty if the user does not provide exact text. If the brand has a public URL, ask whether the URL should be shown with the mark.
TTS source: at the start of Step 9, require the user to choose a voice channel through an interactive menu. Do not infer or preselect a provider from installed tools.
Visual review: whether the self-checked
```
deck.html
```
is approved.
Local subtitle-and-slide review: whether the subtitles generated from
```
Narration
```
and the estimated slide timing are acceptable before TTS is called.
Audio preview review: whether the generated voice, real pacing, precisely recalibrated subtitles, slide switching, and animation rhythm are acceptable in
```
deck.html?preview=1
```
.
Preview review: whether
```
?preview=1
```
is approved for recording after any timing/subtitle regeneration.
Recording choice: if both ffmpeg-burned subtitles and HTML subtitles are available, ask which path to use unless the project already chose one.

Rules:

If the user has not selected a theme, stop at Step 3 and ask whether they want to specify one. Do not assume "no external theme".

If the user declines a theme, still create

theme-extraction.md

and record

Source Theme: None selected by user

Before writing
```
storyboard.md
```
, confirm narration perspective unless it is already explicit. If the source article contains first-person experience, do not rewrite it into "the author says" without asking.
Before writing
```
storyboard.md
```
, ask for an optional topic title, which becomes the main cover title. If the user leaves it empty, derive a topic title from
```
article.md
```
and
```
content-understanding.md
```
instead of asking again. Separately ask whether every page should carry a fixed brand mark or footer-like identifier. Do not use the topic title as the brand mark unless the user explicitly says so. If the user does not provide a brand mark, record
```
Brand Mark: None provided
```
.
If the user chooses auto mode, still write decisions into files. Auto mode removes repeated confirmation, not durable state.
If a decision is made in chat, copy it into the relevant artifact before continuing.
If an artifact and chat memory conflict, ask the user which one is current.

该技能默认是交互式的。第一次交互是强制性的：在创建或修改任何项目工件之前，询问用户选择执行模式并确认项目目录。切勿静默默认使用auto模式或从上下文推断目录。

执行模式：

```
auto
```
：常规流程步骤无需等待每条消息即可继续。保留工件链和机器验证；仅在明确的人工检查点、安全阻塞或无法推断的决策时停止。
```
semi-auto
```
：每个编号步骤完成后，停止并报告：步骤已完成、创建或更改的文件、验证结果以及下一步。等待用户明确反馈后再继续。需要类似“继续”的消息或等效批准；切勿将沉默视为批准。

除非用户明确更改，否则模式适用于整个项目。如果用户更改模式，在继续前将更改记录在

project-config.md

中。

除非当前请求或

project-config.md

中已明确给出答案，否则在以下点询问用户：

项目设置：确切的项目目录(
```
workdir
```
)和执行模式(
```
auto
```
或
```
semi-auto
```
)。
依赖项安装：当探测失败时，用户的Agent是否可以安装缺失的本地依赖项，以及安装位置。
主题来源：是否使用用户选择的主题技能/模板风格，或不使用外部主题继续。
旁白视角：第一人称作者视角、客观解释视角或第三人称报告视角。
分镜脚本批准：
```
storyboard.md
```
是否批准冻结。
品牌标识：是否每个页面都需要固定的页脚式标识。这是可选的，如果用户未提供确切文本，默认为空。如果品牌有公开URL，询问是否应与标识一起显示该URL。
TTS来源：在步骤9开始时，要求用户通过交互式菜单选择语音渠道。切勿从已安装工具中推断或预选提供商。
视觉审查：自检后的
```
deck.html
```
是否批准。
本地字幕与幻灯片审查：从
```
Narration
```
生成的字幕和预估幻灯片时长在调用TTS前是否可接受。
音频预览审查：生成的语音、真实节奏、精准重新校准的字幕、幻灯片切换和动画节奏在
```
deck.html?preview=1
```
中是否可接受。
预览审查：在任何时长/字幕重新生成后，
```
?preview=1
```
是否批准用于录制。
录制选择：如果同时支持ffmpeg嵌入字幕和HTML字幕，询问使用哪种方式，除非项目已做出选择。

规则：

如果用户未选择主题，在步骤3停止并询问是否要指定主题。切勿假设“不使用外部主题”。

如果用户拒绝主题，仍需创建

theme-extraction.md

并记录

Source Theme: None selected by user

。

在编写
```
storyboard.md
```
之前，确认旁白视角，除非已明确说明。如果源文章包含第一人称体验，未经询问请勿将其改写为“作者说”。
在编写
```
storyboard.md
```
之前，询问可选的主题标题，该标题将成为封面的主标题。如果用户留空，从
```
article.md
```
和
```
content-understanding.md
```
中推导主题标题，而非再次询问。另外询问是否每个页面都应显示固定的品牌标识或页脚式标识。除非用户明确说明，否则请勿将主题标题用作品牌标识。如果用户未提供品牌标识，记录
```
Brand Mark: None provided
```
。
如果用户选择auto模式，仍需将决策写入文件。Auto模式仅移除重复确认，而非持久化状态。
如果在聊天中做出决策，在继续前将其复制到相关工件中。
如果工件与聊天记忆冲突，询问用户哪个是当前有效的。

Step 0: Project Setup and Confirm Scope

步骤0：项目设置与范围确认

This is the mandatory workflow entry point. Do not create

environment-check.md

article.md

, or any other project artifact before this step is complete.

Ask the user two questions first:

Which exact directory should be the project
```
workdir
```
?
Which execution mode should this project use:
```
auto
```
or
```
semi-auto
```
?

The user must explicitly confirm both values. Do not infer the directory from the current working directory, the source article location, a previous demo, or a directory mentioned only as an example.

After confirmation:

Verify that the chosen directory exists or create only the confirmed empty project directory and its required
```
slide-specs/
```
and
```
audio/
```
subdirectories.
Write
```
project-config.md
```
at the project root before any other project artifact:

undefined

这是强制性的工作流入口点。在完成此步骤之前，切勿创建

environment-check.md

、

article.md

或任何其他项目工件。

首先询问用户两个问题：

项目的
```
workdir
```
应是哪个确切目录？
该项目应使用哪种执行模式：
```
auto
```
还是
```
semi-auto
```
？

用户必须明确确认这两个值。切勿从当前工作目录、源文章位置、先前演示或仅作为示例提及的目录中推断目录。

确认后：

验证所选目录是否存在，或仅创建已确认的空项目目录及其所需的
```
slide-specs/
```
和
```
audio/
```
子目录。
在创建任何其他项目工件之前，在项目根目录写入
```
project-config.md
```
：

undefined

Project Config

项目配置

Project Directory

项目目录

Workdir: /absolute/path/confirmed/by/user

Workdir: /用户确认的绝对路径

Execution Mode

执行模式

Mode: auto | semi-auto
Rule: auto continues ordinary steps; semi-auto waits for user feedback after every numbered step.

Mode: auto | semi-auto
规则：auto模式继续常规步骤；semi-auto模式在每个编号步骤后等待用户反馈。

Source

源文件

Input:

输入：

Status

状态

Current Step: 0 - Project Setup
Last Completed Step: none


3. In `semi-auto` mode, stop and wait for the user's feedback after writing `project-config.md`.
4. In `auto` mode, continue to the environment bootstrap only after the file exists and the path is verified.

Then confirm the remaining scope:

- source input: pasted text, URL content, or file path
- theme skill/theme/template style, or explicit no-theme choice
- narration perspective: first-person author voice, objective explanatory voice, or third-person report voice
- optional topic title: the main title shown prominently on the cover. If the user leaves it empty, derive it from the source content.
- optional brand mark: whether each page should show a fixed footer-like identifier, the exact text if yes, and whether to include a URL such as `www.example.com`. Leave it empty when the user does not provide one.
- TTS preference: record `Not selected yet` unless the user already made an explicit choice. The binding voice-source gate runs at the start of Step 9, after narration and local subtitle review are approved.
- recording path: prefer ffmpeg-burned subtitles; fall back to HTML subtitles when libass is unavailable

Also confirm that environment probes have passed for the current phase:

- selected TTS command or API adapter only when the user already chose one; otherwise defer this probe to Step 9
- `ffmpeg`
- ffmpeg subtitle support / libass when burning SRT
- Whisper or chosen timestamp tool
- Playwright/browser recording support

If a required tool is missing, stop at that step and report the exact missing dependency and the install guidance from Environment Bootstrap.

当前步骤：0 - 项目设置
上一个完成步骤：无


3. 在`semi-auto`模式下，写入`project-config.md`后停止并等待用户反馈。
4. 在`auto`模式下，仅在文件存在且路径验证通过后，继续进行环境引导。

然后确认剩余范围：

- 源输入：粘贴的文本、URL内容或文件路径
- 主题技能/主题/模板风格，或明确选择无主题
- 旁白视角：第一人称作者视角、客观解释视角或第三人称报告视角
- 可选主题标题：封面显著显示的主标题。如果用户留空，从源内容中推导。
- 可选品牌标识：每个页面是否应显示固定的页脚式标识，如果是，确切文本是什么，以及是否包含URL（如`www.example.com`）。用户未提供时留空。
- TTS偏好：除非用户已明确选择，否则记录`Not selected yet`。绑定的语音源环节在步骤9开始时运行，即旁白和本地字幕审查获得批准后。
- 录制路径：优先选择ffmpeg嵌入字幕；当libass不可用时，回退到HTML字幕

同时确认当前阶段的环境探测已通过：

- 仅当用户已选择时，探测所选的TTS命令或API适配器；否则将此探测推迟到步骤9
- `ffmpeg`
- 嵌入SRT字幕时的ffmpeg字幕支持/libass
- Whisper或所选的时间戳工具
- Playwright/浏览器录制支持

如果所需工具缺失，在该步骤停止并报告确切的缺失依赖项以及环境引导中的安装指南。

Step 1: Save Source

步骤1：保存源文件

Input: user source.

Output:

article.md

Save the source exactly enough to preserve meaning. Do not rewrite it. If the source is incomplete, ask the user before continuing.

输入：用户源文件。

输出：

article.md

。

保存源文件时，需保留足够的信息以确保含义不变。请勿改写。如果源文件不完整，在继续前询问用户。

Step 2: Content Understanding

步骤2：内容理解

Input:

article.md

Output:

content-understanding.md

Do not create storyboard or HTML before this file exists. It must include:

undefined

输入：

article.md

。

输出：

content-understanding.md

。

在该文件存在之前，切勿创建分镜脚本或HTML。它必须包含：

undefined

Content Understanding

内容理解

One-Sentence Judgment

一句话判断

Core Argument

核心论点

Audience

受众

Deep Structure

深层结构

Cause / contrast / progression / reversal / hierarchy / system / conflict / misconception correction / narrative.

因果/对比/递进/反转/层级/系统/冲突/纠正误解/叙事。

Viewer Path

受众路径

What the viewer misunderstands or lacks at the beginning, and what they should understand by the end.

受众最初误解或缺乏的内容，以及他们最终应理解的内容。

Visual Opportunities

视觉机会

What should become visual structure, and what should stay in narration.

哪些内容应转化为视觉结构，哪些内容应保留在旁白中。

Rhythm

节奏

Which moments need impact, which need restraint.

哪些时刻需要突出，哪些时刻需要克制。

Risks

风险

Where the video could become text piles, generic cards, wrong metaphors, or decorative motion.


Human checkpoint required.

视频可能出现文本堆砌、通用卡片、错误隐喻或装饰性动画的地方。


需要人工检查点。

Step 3: Theme Extraction

步骤3：主题提取

Input: user-selected theme skill/theme.

Output:

theme-extraction.md

Before creating this file, check whether the user has chosen a theme skill or template style.

If yes, extract only tokens and broad mood from that source.
If no, ask: "Do you want to specify a theme skill or template style for this video?"
If the user declines, create a neutral
```
theme-extraction.md
```
with
```
Source Theme: None selected by user
```
and conservative tokens.
Do not pick a theme silently.

Borrow skin, not bones. Extract only normalized tokens and broad mood:

undefined

输入：用户选择的主题技能/主题。

输出：

theme-extraction.md

。

在创建该文件之前，检查用户是否已选择主题技能或模板风格。

如果是，仅从该来源提取标记和大致风格。
如果否，询问：“您是否要为此视频指定主题技能或模板风格？”
如果用户拒绝，创建中性的
```
theme-extraction.md
```
，记录
```
Source Theme: None selected by user
```
和保守标记。
切勿静默选择主题。

仅借用外观，而非核心。仅提取标准化标记和大致风格：

undefined

Theme Extraction

主题提取

Source Theme

源主题

Tokens

标记

bg:
text:
muted:
accent:
accent-2:
rule:
panel:
subtitle-bg:
subtitle-text:
chrome-text:

bg:
text:
muted:
accent:
accent-2:
rule:
panel:
subtitle-bg:
subtitle-text:
chrome-text:

Mood

风格

Light/dark/paper/cinematic/high-contrast, graphic language, and motion temperament.

明亮/深色/纸质/电影感/高对比度，图形语言和动画风格。

Explicitly Ignored

明确忽略的内容

source layout
source components
source card style
source type scale
source animation
source HTML/CSS templates


After this file is created, HTML generation must not return to the original theme skill for layout or animation ideas.

Human checkpoint recommended.

源布局
源组件
源卡片样式
源排版比例
源动画
源HTML/CSS模板


该文件创建后，HTML生成不得再回到原始主题技能中获取布局或动画思路。

建议设置人工检查点。

Step 4: Storyboard

步骤4：分镜脚本

Inputs:

article.md

content-understanding.md

theme-extraction.md

Output:

storyboard.md

This is the only file the user reviews for page-by-page content. Keep each slide compact:

undefined

输入：

article.md

、

content-understanding.md

、

theme-extraction.md

。

输出：

storyboard.md

。

这是用户唯一需要逐页审阅内容的文件。保持每张幻灯片简洁：

undefined

Storyboard

分镜脚本

Decisions

决策

Narration Perspective:
Subtitle Source: Narration
Topic Title:
Brand Mark:

旁白视角：
字幕来源：Narration
主题标题：
品牌标识：

Cover Frame - Title

封面帧 - 标题

Duration

时长

About 3 seconds.

约3秒。

Purpose

目的

Opening cover frame for the final video.

最终视频的开场封面帧。

Visual

视觉

The first visual impression of the video.

视频的第一视觉印象。

Screen Text

屏幕文本

Only cover title, subtitle, author/series marks, or short context.

仅显示封面标题、副标题、作者/系列标识或简短上下文。

Slide 01 - Title

幻灯片01 - 标题

Goal

目标

The one thing the viewer should understand.

受众应理解的核心内容。

Visual

视觉

The screen structure, focus, and relationship. Include the content relation here instead of a separate field.

屏幕结构、焦点和关系。在此处包含内容关系，而非单独字段。

Screen Text

屏幕文本

Only words that appear on screen: keywords, numbers, labels, short claims. Do not repeat subtitles. Do not include remark text that explains, labels, or restates what a provided asset or the visual already shows. If a provided image (QR code, promotion graphic, screenshot) carries the meaning, do not typeset a caption, hint, or footnote beside it; the asset is the message.

仅显示出现在屏幕上的文字：关键词、数字、标签、简短声明。请勿重复字幕。请勿包含解释、标注或重申已有资源或视觉内容的备注文本。如果提供的图像（二维码、推广图、截图）已传达含义，请勿在其旁边排版说明、提示或脚注；资源本身就是信息。

Narration

旁白

The spoken script for this slide. This is also the subtitle source by default. Write it in the confirmed narration perspective, and make sure it connects naturally with the previous and next slide.

该幻灯片的口述脚本。默认情况下，这也是字幕来源。以确认的旁白视角编写，并确保与上一张和下一张幻灯片自然衔接。

Animation

动画

Two to four sentences describing the understanding sequence. Say what appears first, what changes, and where the final focus lands. Do not write seconds, easing, CSS classes, directions, pixel values, or GSAP parameters.

用2-4句话描述理解顺序。说明先出现什么、什么发生变化以及最终焦点落在哪里。请勿写入秒数、缓动效果、CSS类、方向、像素值或GSAP参数。

Notes

备注

Optional. Use only for off-screen content, risks, or special constraints.


Animation in storyboard is a cognitive script, not implementation code. The HTML stage must follow the intent strictly, while choosing the GSAP implementation details according to layout and final timing.

Cover rules:

- The cover frame is required.
- It is not counted as a content slide.
- It enters the final video timeline before Slide 01.
- Default duration is about 3 seconds.
- The cover must show the topic title clearly. If the user did not provide one, derive it from `article.md` and `content-understanding.md`.
- Do not add narration or subtitle to the cover unless the user explicitly asks for a spoken opening.
- The cover is a static frame. It must have no entrance animation, path drawing, fade-in, text reveal, highlight animation, or delayed element appearance.
- The cover must be complete and readable at `0s`. This first frame is also the file thumbnail / preview cover on macOS Finder and Quick Look.
- Do not include a cover `Animation` field in `storyboard.md` or `slide-specs/cover.md`. Animation begins from Slide 01.

Brand mark rules:

- If the user wants a fixed page brand mark, record the exact text in `storyboard.md` Decisions.
- If the user does not provide one, record `Brand Mark: None provided` and do not render a footer mark.
- Do not treat the topic title as a brand mark automatically. The topic title belongs prominently on the cover; the repeated footer mark is a separate optional choice.
- The mark is global chrome, like a footer or running label. It should not be repeated inside every slide's `Screen Text`.
- If the user provides a brand URL, keep it with the brand mark as chrome text, usually on a second line.
- Default placement is lower-left, paired with the page number in the opposite corner. Move it only if it conflicts with subtitles or key visuals.
- Use text first. Do not require an image logo unless the user provides one.
- HTML generation must reserve enough footer/subtitle space so the brand mark, page number, subtitles, and meaningful visual elements do not overlap.

Narration and subtitle rules:

- `Narration` is the single text source for both TTS and subtitles.
- Do not maintain a separate `Subtitle` field in `storyboard.md`.
- Viewers normally expect subtitles to match what is spoken.
- Before user approval, perform a TTS narration adaptation pass on every `Narration` block:
  - preserve meaning, claims, examples, and order
  - do not add new arguments, promotional language, or emotional performance
  - split overlong sentences into speakable units
  - keep connective words when they make the spoken logic clearer
  - avoid dense chains of commas that cause rushed TTS delivery
  - keep English technical terms such as `Function Calling`, `MCP`, `Skill`, `Agent`, and `Multi-Agent` in readable groups instead of burying them inside a long sentence
  - prefer stable Chinese punctuation over special pause symbols unless the chosen TTS explicitly supports them
  - read all slide narrations in order and check that the voice sounds like one continuous talk, not separate captions
- During subtitle generation, split lines and timing from `Narration`; do not paraphrase, compress, add claims, or change wording.
- If the user explicitly asks for subtitle editing, edit `subtitles.srt` after TTS/timing generation and record that exception.
- Before freezing, read all `Narration` blocks in order and check continuity. The narration should sound like one continuous script, not eight isolated captions.

Human checkpoint required.

可选。仅用于屏幕外内容、风险或特殊约束。


分镜脚本中的动画是认知脚本，而非实现代码。HTML阶段必须严格遵循意图，同时根据布局和最终时长选择GSAP实现细节。

封面规则：

- 必须包含封面帧。
- 封面帧不算作内容幻灯片。
- 它会进入最终视频时间线，位于幻灯片01之前。
- 默认时长约为3秒。
- 封面必须清晰显示主题标题。如果用户未提供，从`article.md`和`content-understanding.md`中推导。
- 除非用户明确要求口述开场，否则请勿为封面添加旁白或字幕。
- 封面是静态帧。不得有入场动画、路径绘制、淡入、文本揭示、高亮动画或延迟元素出现。
- 封面必须在`0s`时完整且可读。第一帧也是macOS Finder和Quick Look中的文件缩略图/预览封面。
- 请勿在`storyboard.md`或`slide-specs/cover.md`中包含封面`Animation`字段。动画从幻灯片01开始。

品牌标识规则：

- 如果用户需要固定的页面品牌标识，在`storyboard.md`的Decisions中记录确切文本。
- 如果用户未提供，记录`Brand Mark: None provided`，并且不渲染页脚标识。
- 切勿自动将主题标题用作品牌标识。主题标题应显著显示在封面上；重复的页脚标识是单独的可选选择。
- 标识是全局界面元素，如页脚或运行标签。请勿在每张幻灯片的`Screen Text`中重复。
- 如果用户提供品牌URL，将其与品牌标识一起作为界面文本，通常显示在第二行。
- 默认位置为左下角，与对角的页码配对。仅当与字幕或关键视觉元素冲突时才移动。
- 优先使用文本。除非用户提供，否则不需要图像标志。
- HTML生成必须预留足够的页脚/字幕空间，确保品牌标识、页码、字幕和有意义的视觉元素不会重叠。

旁白和字幕规则：

- `Narration`是TTS和字幕的唯一文本来源。
- 请勿在`storyboard.md`中维护单独的`Subtitle`字段。
- 观众通常期望字幕与口述内容匹配。
- 在获得用户批准前，对每个`Narration`块执行TTS旁白适配检查：
  - 保留含义、主张、示例和顺序
  - 请勿添加新论点、宣传语或情绪化表达
  - 将过长的句子拆分为可朗读的单元
  - 保留连接词，使口述逻辑更清晰
  - 避免密集的逗号链导致TTS仓促朗读
  - 将`Function Calling`、`MCP`、`Skill`、`Agent`和`Multi-Agent`等英文技术术语保持为可读的组，而非埋在长句中
  - 优先使用稳定的中文标点，而非特殊停顿符号，除非所选的TTS明确支持
  - 按顺序朗读所有幻灯片的旁白，检查语音是否像连贯的讲话，而非单独的字幕
- 在生成字幕时，从`Narration`拆分换行和时长；请勿释义、压缩、添加主张或更改措辞。
- 如果用户明确要求编辑字幕，在TTS/时长生成后编辑`subtitles.srt`并记录该例外情况。
- 在冻结前，按顺序朗读所有`Narration`块并检查连贯性。旁白应听起来像连贯的脚本，而非八个孤立的字幕。

需要人工检查点。

Step 5: Freeze Storyboard

步骤5：冻结分镜脚本

Input: confirmed

storyboard.md

Output:

slide-specs/cover.md

and

slide-specs/NN.md

Freeze mechanically:

split

<!-- cover --> ... <!-- /cover -->

into

slide-specs/cover.md

split every

<!-- slide: NN --> ... <!-- /slide -->

block into

slide-specs/NN.md

do not rewrite, polish, or add content during freeze
add source metadata to each slice:

<!-- source: storyboard.md -->
<!-- storyboard-hash: HASH -->
<!-- cover -->

or:

<!-- source: storyboard.md -->
<!-- storyboard-hash: HASH -->
<!-- slide: 01 -->

Before visual logic, HTML, TTS, preview, or recording, verify every slide spec has the current storyboard hash. If hashes differ, stop and re-freeze from

storyboard.md

输入：已确认的

storyboard.md

。

输出：

slide-specs/cover.md

和

slide-specs/NN.md

。

机械冻结：

将

<!-- cover --> ... <!-- /cover -->

拆分到

slide-specs/cover.md

中

将每个

<!-- slide: NN --> ... <!-- /slide -->

块拆分到

slide-specs/NN.md

中

冻结过程中请勿改写、润色或添加内容
为每个片段添加源元数据：

<!-- source: storyboard.md -->
<!-- storyboard-hash: HASH -->
<!-- cover -->

或：

<!-- source: storyboard.md -->
<!-- storyboard-hash: HASH -->
<!-- slide: 01 -->

在进行视觉逻辑、HTML、TTS、预览或录制之前，验证每个幻灯片规格是否包含当前的分镜脚本哈希。如果哈希不同，停止操作并从

storyboard.md

重新冻结。

Step 6: Visual Logic

步骤6：视觉逻辑

Inputs:

slide-specs/

theme-extraction.md

references/FORM-MAP.md

references/TOOLKIT.md

, visual constraint checking, and frontend-quality review.

Output:

visual-logic.md

Do not build

deck.html

until

visual-logic.md

exists.

For the cover, write only the static visual logic. The cover is not animated:

undefined

输入：

slide-specs/

、

theme-extraction.md

、

references/FORM-MAP.md

、

references/TOOLKIT.md

、视觉约束检查和前端质量审查。

输出：

visual-logic.md

。

在

visual-logic.md

存在之前，切勿构建

deck.html

。

对于封面，仅编写静态视觉逻辑。封面没有动画：

undefined

Cover - Title

封面 - 标题

Content Relation

内容关系

The opening identity and topic signal.

开场标识和主题信号。

Visual Form

视觉形式

The complete static frame that appears at

0s

在

0s

时出现的完整静态帧。

Screen Text Density

屏幕文本密度

What must appear on the cover, and what should be kept out.

必须出现在封面上的内容，以及应排除的内容。

Avoid

避免

What the cover must not become.


For every content slide, write:

```md

封面不得出现的情况。


对于每个内容幻灯片，编写：

```md

Slide 01 - Title

幻灯片01 - 标题

Content Relation

内容关系

The real relationship being explained: chaos-to-order, progression, hierarchy, contrast, cause/effect, misconception correction, system, conflict, conclusion, etc.

正在解释的真实关系：混乱到有序、递进、层级、对比、因果、纠正误解、系统、冲突、结论等。

Semantic Noun

语义名词

The structural kind: process, system, hierarchy, contrast, timeline, state, evidence, correction, or another precise relation.

结构类型：流程、系统、层级、对比、时间线、状态、证据、纠正或其他精确关系。

Semantic Verb

语义动词

The visible action: gather, transform, scan, monitor, branch, converge, stack, replace, circulate, reveal, or another precise verb.

可见动作：聚集、转换、扫描、监控、分支、汇聚、堆叠、替换、循环、揭示或其他精确动词。

FORM-MAP Match

FORM-MAP匹配

The matching rows or animation words from

references/FORM-MAP.md

, for example: chaos-to-order, progression, hierarchy, contrast, route/journey, timeline, misconception correction.

来自

references/FORM-MAP.md

的匹配行或动画词汇，例如：混乱到有序、递进、层级、对比、路线/旅程、时间线、纠正误解。

Visual Form

视觉形式

The structure that expresses the relationship. Do not say "cards" unless cards are truly the semantic form.

Derive the form from the semantic noun and verb. Do not start with a card grid and pour labels into it. If one slide contains several items with different verbs, design different internal structures for those items instead of repeating one box and changing only its icon, border, or color.

If the form uses connected nodes, plan the connection as visible segments between nodes. Do not plan a full background line that passes behind cards and becomes partially hidden.

表达关系的结构。除非卡片确实是语义形式，否则请勿说“卡片”。

从语义名词和动词推导形式。切勿从卡片网格开始，然后将标签填入其中。如果一张幻灯片包含多个具有不同动词的项目，为这些项目设计不同的内部结构，而非重复使用一个框并仅更改其图标、边框或颜色。

如果形式使用连接节点，规划节点之间的可见线段作为连接。切勿规划穿过卡片后方并部分隐藏的完整背景线条。

Screen Text Density

屏幕文本密度

What must stay on screen, and what should be left to narration/subtitles. The screen must be understandable on its own at the main-idea level, but it should not carry every detail when narration already carries those details.

必须保留在屏幕上的内容，以及应留给旁白/字幕的内容。屏幕本身应能在核心思想层面被理解，但当旁白已包含这些细节时，屏幕无需承载所有细节。

Animation Logic

动画逻辑

How motion changes understanding. It must say what appears first, what changes, what resolves, and where the final focus lands.

动作如何加深理解。必须说明先出现什么、什么发生变化、什么得到解决以及最终焦点落在哪里。

Animation States

动画状态

State A:
State B:
State C:

Each state must be separately readable, screenshot-safe, and free of text overlap. The final settled state is the most important state: no node, line, label, subtitle, page number, or decorative mark may cover another readable element. GSAP may only connect these states; it must not compensate for a broken layout.

状态A：
状态B：
状态C：

每个状态必须单独可读、适合截图，且无文本重叠。最终稳定状态是最重要的状态：任何节点、线条、标签、字幕、页码或装饰性标识不得覆盖其他可读元素。GSAP仅能连接这些状态；不得弥补布局缺陷。

Avoid

避免

What this slide must not become: text alignment, stacked keywords, decorative fade-in, generic cards, etc.

该幻灯片不得出现的情况：文本对齐、堆叠关键词、装饰性淡入、通用卡片等。

Timing Note

时长备注

Optional. Use only when this slide needs to break the default 4-6 second opening animation rule.


Rules:

- `visual-logic.md` must use `FORM-MAP.md` deliberately, but not mechanically.
- Start from the slide's `Goal`, `Narration`, and `Animation`, not from the amount of text.
- Write `Semantic Noun` and `Semantic Verb` before `Visual Form`. If either field is vague, the slide is not ready for layout.
- If the chosen form is only "place keywords on screen and fade them in", reject it and choose a stronger semantic form.
- Treat a border as containment, not expression. `Box + label`, even with an icon and accent color, fails when the geometry does not show the action or relation.
- Use repeated cards only for genuinely equivalent objects or an intentional comparison task. Different verbs require different internal visual grammars.
- Before HTML generation, apply a conceptual text-removal test to every proposed visual: without labels, the major direction, transformation, containment, hierarchy, or state should remain inferable.
- Animation must deepen understanding, not only introduce elements.
- Do not implement a deck with one universal entrance recipe such as `opacity + y + scale + stagger`. Shared timing utilities are acceptable, but each slide timeline must express its own relation: paths grow, systems assemble, layers stack, gaps close, categories expand, loops complete, or evidence maps to conclusions. A slide whose only motion is fading or sliding independent objects into place fails semantic animation review.
- Before HTML generation, write a one-line motion verb for every slide and verify that adjacent slides do not accidentally use the same motion grammar unless their content relation is genuinely the same.
- Always bind the slide to a `FORM-MAP.md` relation before choosing layout.
- Always define `Animation States`; do not build HTML from `Animation Logic` alone.
- Every animation state must be screenshot-safe before motion is added.
- Treat `0%` as a real designed frame, not merely an implementation starting value. Text-bearing elements must be either fully readable or fully hidden at the initial state. Never scale a text container to a small nonzero height/width that exposes compressed boxes, clipped glyphs, or half-readable labels.
- For node-link visuals, every relationship line must be readable as a connector in the final still frame. Lines should occupy gaps between nodes, not sit underneath nodes as partially hidden background strokes.
- Plan screen text as a two-layer reading system: screen text carries the visual skeleton; narration/subtitles carry detail, examples, and nuance.
- If a slide feels crowded, remove secondary screen text before shrinking fonts or squeezing layout. The viewer should still understand the visual claim without hearing every detail.
- Treat estimated narration duration as the temporary clock for slide length and subtitle preview before TTS exists.
- The default deck animation should establish the slide early, usually within 4-6 seconds, and then hold a clean final state while narration explains it.
- Semantic synchronization, where a visual change is tied to an exact spoken phrase, is optional and should only be used when the user explicitly wants it or when a slide genuinely depends on that precision.
- Do not create a stretched animation just because narration is long. A 10-second narration can still have a 4-second opening animation if the final still frame remains useful.
- Human checkpoint recommended before rebuilding `deck.html`, especially for first versions.

可选。仅当该幻灯片需要打破默认的4-6秒开场动画规则时使用。


规则：

- `visual-logic.md`必须有意使用`FORM-MAP.md`，而非机械使用。
- 从幻灯片的`Goal`、`Narration`和`Animation`开始，而非文本量。
- 在`Visual Form`之前编写`Semantic Noun`和`Semantic Verb`。如果任一字段模糊，幻灯片尚未准备好进行布局。
- 如果所选形式仅为“在屏幕上放置关键词并淡入”，拒绝该形式并选择更具语义的形式。
- 将边框视为容器，而非表达元素。`Box + label`即使带有图标和强调色，当几何形状无法显示动作或关系时也是失败的。
- 仅当对象真正等效或有意进行比较时，才使用重复卡片。不同的动词需要不同的内部视觉语法。
- 在HTML生成之前，对每个提议的视觉应用概念性文本移除测试：隐藏标签后，仍应能推断出主要方向、转换、包含、层级或状态。
- 动画必须加深理解，而非仅引入元素。
- 切勿使用单一通用入场方案（如`opacity + y + scale + stagger`）实现演示文稿。共享时长工具是可接受的，但每个幻灯片时间线必须表达自身的关系：路径延伸、系统组装、层堆叠、间隙闭合、类别扩展、循环完成或证据映射到结论。仅通过淡入或滑动独立对象进入的幻灯片无法通过语义动画审查。
- 在HTML生成之前，为每个幻灯片编写一个单行动作动词，并验证相邻幻灯片是否意外使用相同的动词语法，除非它们的内容关系确实相同。
- 在选择布局之前，始终将幻灯片绑定到`FORM-MAP.md`中的关系。
- 始终定义`Animation States`；切勿仅从`Animation Logic`构建HTML。
- 添加动画之前，每个动画状态必须适合截图。
- 将`0%`视为真实设计帧，而非仅作为实现起始值。承载文本的元素在初始状态下必须完全可读或完全隐藏。切勿将文本容器缩放到非零的小高度/宽度，导致显示压缩框、裁剪字形或半可读标签。
- 对于节点链接视觉，每个关系线在最终静止帧中必须作为连接器可读。线条应位于节点之间的间隙，而非位于节点下方作为部分隐藏的背景笔触。
- 将屏幕文本规划为两层阅读系统：屏幕文本承载视觉框架；旁白/字幕承载细节、示例和细微差别。
- 如果幻灯片显得拥挤，在缩小字体或挤压布局之前移除次要屏幕文本。即使未听到所有细节，观众仍应能理解视觉主张。
- 在TTS生成之前，将预估的旁白时长作为幻灯片长度和字幕预览的临时基准。
- 默认演示文稿动画应尽早建立幻灯片，通常在4-6秒内，然后在旁白解释时保持清晰的最终状态。
- 语义同步（视觉变化与确切口述短语绑定）是可选的，仅当用户明确要求或幻灯片确实依赖该精度时才使用。
- 切勿仅因旁白较长就拉长动画。10秒的旁白仍可使用4秒的开场动画，只要最终静止帧仍然有用。
- 在重新构建`deck.html`之前建议设置人工检查点，尤其是第一版。

Step 7: Build and Self-Check HTML

步骤7：构建并自检HTML

Inputs:

slide-specs/

visual-logic.md

theme-extraction.md

references/TOOLKIT.md

, visual constraint checking, and frontend-quality review.

Output: self-checked

deck.html

Use estimated slide timing only for the first visual version:

Chinese narration preview: normally 4.5-5.5 visible characters/second for a clear teaching voice. Use 5 characters/second as the default unless the project records a different speaking style.
English: about 2.5 words/second
give every slide a small pause before advancing
use a normal opening animation window, usually 4-6 seconds, slightly slower for dense concept slides
keep the final state readable for the remaining narration
use the slide's
```
Narration
```
only as context for whether the final visual structure supports the explanation; do not mechanically bind every spoken phrase to a separate animation event

Subtitle preview timing:

split Chinese subtitles by natural punctuation such as
```
。
```
,
```
；
```
,
```
：
```
, and only then by length if one line becomes too long
do not give every subtitle segment the same duration
estimate each segment from its own visible character count, using the project speaking-rate constant
add a small punctuation pause after sentence-like segments
clamp each segment so very short fragments do not flash and very long fragments do not block the next beat
use this only before TTS exists; after TTS, replace preview estimates with actual audio/subtitle timestamps

Interaction rules:

manual mode: Space advances, Backspace goes back
ArrowRight advances and ArrowLeft goes back as keyboard alternatives.
Do not render visible previous/next arrow controls in presentation or video decks unless the user explicitly asks for clickable navigation. These controls compete with the composition and are normally absent from the final recording.
no click-to-advance
each slide owns one GSAP Timeline
page animations autoplay when a slide enters
avoid nested
```
setTimeout
```
as animation sequencing
```
open deck.html
```
should work for non-audio review; audio preview may require a local HTTP server

Technology default:

HTML/CSS/SVG for structure and visuals
GSAP as the only animation timeline
Rough Notation only when a slide needs correction marks, circles, highlights, or hand-drawn emphasis
no CDN dependencies
do not introduce Mermaid, ECharts, CountUp, Typed, Canvas libraries, or other tools unless the content truly requires them and there is a clear reason

Run the visual constraint checks before showing the visual version to the user.

For every slide, inspect the final timeline state, not only the first frame. Capture every settled slide at the target recording resolution and review both a contact sheet and flagged full-resolution frames. DOM overflow checks are only mechanical evidence; they do not prove that a layout is good.

A final frame fails composition review when any of the following is true, even when nothing technically overlaps or overflows:

the visual weight is stranded at one edge while another region is empty for no semantic reason
a large negative-space region does not express distance, absence, delay, conflict, hierarchy, or another deliberate relation
related elements are separated without a visible connector, grouping, or directional reading path
the title, supporting structure, and conclusion compete instead of establishing a clear reading order
the visual is technically inside the viewport but looks sparse, squeezed, unfinished, or like components were placed without composition

For every large empty region, answer: "What does this space mean?" If there is no precise answer, recompose the slide. Use a vision model on the settled contact sheet to find suspicious pages, then inspect every flagged page at full resolution because contact-sheet thumbnails can produce false positives.

Review the complete deck at

0%

25%

50%

75%

, and

100%

of every content-slide timeline. Build contact sheets for all five states, not only the settled state. The

0%

sheet catches compressed or partially visible text; middle-state sheets catch collisions and elements pushed through each other; the

100%

sheet catches composition and safe-area failures.

When one slide reveals a systemic defect, scan every slide for the same defect before returning to the user. Examples: if one

scaleY

entrance compresses text, inspect every text-bearing scaled container; if one final frame wastes vertical space and crowds the footer, inspect every slide for top/bottom weight imbalance. Do not stop after patching the reported page.

Treat generic

box + label

construction as a systemic defect. When it appears on one slide, scan the whole deck for repeated containers whose only semantic difference is text, icon, border color, or accent strip. Repair every affected slide before review.

Run two semantic-expression checks on every settled slide:

Text-removal check: temporarily hide labels and inspect the remaining geometry. It should still communicate the major action or relation. Exact terminology may disappear; semantic structure must not.
First-viewer paraphrase check: show the settled frame without explanation and ask what it expresses. Passing means the viewer can restate the transformation, system, hierarchy, contrast, or state. If the response only repeats labels, the slide is still a styled transcript.

For repeated chapter, phase, or section chrome, require an explicit navigation grammar such as index node + name + guide track + page count. Bare corner text is unfinished chrome.

Use frontend-quality review only to improve composition quality: typography hierarchy, spatial structure, visual focus, information density, and avoidance of generic AI card layouts.

Limits:

The review layer must not override
```
theme-extraction.md
```
tokens.
The review layer must not copy an external template or layout system.
The review layer must not change slide text, narration, subtitle meaning, or storyboard intent.
The review layer must not introduce extra frameworks, libraries, CDN dependencies, or decorative motion.
Constraint checks take precedence over aesthetic suggestions when the two conflict.

Human checkpoint required after self-check.

输入：

slide-specs/

、

visual-logic.md

、

theme-extraction.md

、

references/TOOLKIT.md

、视觉约束检查和前端质量审查。

输出：经过自检的

deck.html

。

仅在第一个视觉版本中使用预估的幻灯片时长：

中文旁白预览：清晰的教学语音通常为4.5-5.5可见字符/秒。默认使用5字符/秒，除非项目记录了不同的讲话风格。
英文：约2.5单词/秒
每张幻灯片切换前添加短暂停顿
使用正常的开场动画窗口，通常为4-6秒，密集概念幻灯片可稍慢
最终状态在旁白解释期间保持可读
仅将幻灯片的
```
Narration
```
作为上下文，判断最终视觉结构是否支持解释；切勿机械地将每个口述短语绑定到单独的动画事件

字幕预览时长：

中文字幕先按自然标点（如
```
。
```
、
```
；
```
、
```
：
```
）拆分，仅当一行过长时再按长度拆分
请勿给每个字幕片段相同的时长
使用项目讲话速率常量，根据每个片段的可见字符数预估时长
在类似句子的片段后添加短暂的标点停顿
限制每个片段的时长，避免极短片段闪烁和极长片段阻碍下一个节拍
仅在TTS生成前使用此方法；TTS生成后，用实际音频/字幕时间戳替换预览预估

交互规则：

手动模式：空格键前进，退格键后退
右键箭头前进，左键箭头后退作为键盘替代方案。
除非用户明确要求可点击导航，否则请勿在演示文稿或视频演示中渲染可见的上一页/下一页箭头控件。这些控件会干扰构图，通常不会出现在最终录制中。
不支持点击前进
每张幻灯片拥有一个GSAP Timeline
幻灯片进入时自动播放页面动画
避免使用嵌套
```
setTimeout
```
进行动画排序
```
open deck.html
```
应可用于非音频审查；音频预览可能需要本地HTTP服务器

技术默认：

使用HTML/CSS/SVG构建结构和视觉效果
使用GSAP作为唯一的动画时间线
仅当幻灯片需要纠正标记、圆圈、高亮或手绘强调时使用Rough Notation
无CDN依赖
除非内容确实需要且有明确理由，否则请勿引入Mermaid、ECharts、CountUp、Typed、Canvas库或其他工具

在向用户展示视觉版本之前，运行视觉约束检查。

对于每张幻灯片，检查最终时间线状态，而非仅第一帧。在目标录制分辨率下捕获每个稳定的幻灯片，审阅联系表和标记的全分辨率帧。DOM溢出检查仅为机械证据，不能证明布局良好。

当出现以下任一情况时，最终帧未通过构图审查，即使技术上没有重叠或溢出：

视觉重心停留在一侧边缘，而另一侧区域无语义原因地空白
大的负空间区域未表达距离、缺失、延迟、冲突、层级或其他有意的关系
相关元素之间没有可见的连接器、分组或定向阅读路径，却被分隔开
标题、支撑结构和结论相互竞争，而非建立清晰的阅读顺序
视觉元素技术上在视口内，但看起来稀疏、拥挤、未完成或组件放置无构图

对于每个大的空白区域，回答：“这个空间的含义是什么？”如果没有确切答案，重新构图幻灯片。在稳定的联系表上使用视觉模型查找可疑页面，然后以全分辨率检查每个标记的页面，因为联系表缩略图可能产生误报。

在每个内容幻灯片时间线的

0%

、

25%

、

50%

、

75%

和

100%

处审阅完整演示文稿。为所有五个状态构建联系表，而非仅稳定状态。

0%

表捕获压缩或部分可见的文本；中间状态表捕获碰撞和相互穿过的元素；

100%

表捕获构图和安全区域失败。

当一张幻灯片暴露出系统性缺陷时，在返回给用户之前扫描所有幻灯片是否存在相同缺陷。例如：如果一个

scaleY

入场压缩了文本，检查所有承载文本的缩放容器；如果一个最终帧浪费垂直空间并拥挤页脚，检查所有幻灯片的上下重量不平衡。修复完报告页面后请勿停止。

将通用的

box + label

构造视为系统性缺陷。当它出现在一张幻灯片上时，扫描整个演示文稿是否存在仅文本、图标、边框颜色或强调条不同的重复容器。在审阅前修复所有受影响的幻灯片。

对每个稳定的幻灯片运行两个语义表达检查：

文本移除检查：临时隐藏标签并检查剩余几何形状。它仍应传达主要动作或关系。确切术语可能消失；语义结构不得消失。
首次观看者释义检查：在不解释的情况下展示稳定帧，询问它表达了什么。通过意味着观看者可以重述转换、系统、层级、对比或状态。如果响应仅重复标签，幻灯片仍然是样式化的文稿。

对于重复的章节、阶段或部分界面元素，需要明确的导航语法，如索引节点+名称+引导轨迹+页码。仅角落文本是未完成的界面元素。

仅使用前端质量审查来提高构图质量：排版层级、空间结构、视觉焦点、信息密度以及避免通用AI卡片布局。

限制：

审查层不得覆盖
```
theme-extraction.md
```
中的标记。
审查层不得复制外部模板或布局系统。
审查层不得更改幻灯片文本、旁白、字幕含义或分镜脚本意图。
审查层不得引入额外框架、库、CDN依赖或装饰性动画。
当约束检查与美学建议冲突时，约束检查优先。

自检后需要人工检查点。

Step 8: Local Subtitle-and-Slide Preview

步骤8：本地字幕与幻灯片预览

Inputs: approved

deck.html

and

slide-specs/NN.md

Narration

fields.

Output: approved local subtitle-and-slide preview, normally through

deck.html?subtitlePreview=1

This step is mandatory before any remote, cloned, paid, or token-heavy TTS call. It does not use TTS or external services.

Local subtitle-and-slide review rules:

Generate subtitle text from each slide's
```
Narration
```
.
Split by natural punctuation first; split overly long Chinese segments again by comma, enumeration punctuation, or dash.
Estimate timing from visible character count and the project speaking-rate constant.
Use the estimated timing to drive both subtitle changes and slide changes.
Add a short pause between slides, normally about 0.35-0.6 seconds, so the video does not feel like one uninterrupted text crawl.
Show the result in
```
deck.html
```
through a non-audio preview mode such as
```
?subtitlePreview=1
```
.
Ask the user to approve wording, segmentation, rough rhythm, slide switching, and whether the visual structure matches the subtitle.
If the user edits narration after this review, update
```
storyboard.md
```
, re-freeze affected slide specs, rebuild
```
deck.html
```
, and run local subtitle review again before TTS.

Do not call remote TTS, cloned TTS, or token-heavy TTS while subtitle text is still under review.

Human checkpoint required.

输入：已批准的

deck.html

和

slide-specs/NN.md

的

Narration

字段。

输出：已批准的本地字幕与幻灯片预览，通常通过

deck.html?subtitlePreview=1

实现。

在进行任何远程、克隆、付费或消耗大量令牌的TTS调用之前，此步骤是强制性的。它不使用TTS或外部服务。

本地字幕与幻灯片审查规则：

从每张幻灯片的
```
Narration
```
生成字幕文本。
先按自然标点拆分；过长的中文片段再按逗号、枚举标点或破折号拆分。
根据可见字符数和项目讲话速率常量预估时长。
使用预估时长驱动字幕变化和幻灯片切换。
在幻灯片之间添加短暂停顿，通常约0.35-0.6秒，使视频不会像不间断的文本滚动。
通过非音频预览模式（如
```
?subtitlePreview=1
```
）在
```
deck.html
```
中显示结果。
请用户批准措辞、分段、大致节奏、幻灯片切换以及视觉结构是否与字幕匹配。
如果用户在此审查后编辑旁白，更新
```
storyboard.md
```
，重新冻结受影响的幻灯片规格，重新构建
```
deck.html
```
，并在TTS之前再次运行本地字幕审查。

在字幕文本仍在审查时，请勿调用远程TTS、克隆TTS或消耗大量令牌的TTS。

需要人工检查点。

Step 9: TTS

步骤9：TTS

Inputs: approved

deck.html

, approved local subtitle-and-slide preview, and

slide-specs/NN.md

Narration

fields.

Output:

audio/NN.wav

audio/NN.mp3

, duration record,

audio/all.wav

audio/all.mp3

, and

audio/tts-metadata.md

Start Step 9 with a mandatory voice-source gate. If the runtime provides an interactive choice tool, use it; otherwise present the same four choices as a plain selection list. Do not begin synthesis, install a TTS package, or silently choose a provider until the user selects one:

Use my own voice-cloning API — the user owns or controls a cloning service.
Use a cloned voice already configured in this environment — discover and list only providers/presets that can be probed successfully.
Use a free online voice channel — discover available no-cost candidates, state network/privacy/usage-limit constraints, then ask the user to select a voice.
Use a free local/offline voice channel — discover installed offline candidates or explain the required installation, model size, quality, and hardware trade-offs before asking permission to install anything.

Record the chosen channel in

project-config.md

and

audio/tts-metadata.md

. The choice is binding for the batch unless the user explicitly changes it. A failed provider must stop with a clear error; never silently fall back to another voice channel because that changes identity, licensing, privacy, and output quality.

After the user selects a branch, read and follow

references/tts-source-selection.md

for provider discovery, candidate comparison, API contract fields, credential handling, probing, metadata, and failure behavior.

For a user-owned API, collect the non-secret API contract and ask only for the environment-variable name that holds its credential. Never ask the user to paste an API key, bearer token, password, cookie, or signed URL into chat or project files. Probe the selected adapter with a short harmless sentence before batch generation.

For configured, free-online, or local/offline channels, discover and probe candidates first, then ask the user to choose the concrete provider and voice. State network, privacy, limits, installation, hardware, and licensing trade-offs that apply.

edge-tts

may be offered as a candidate; it is never a silent default. Do not install runtimes or download model weights without approval.

输入：已批准的

deck.html

、已批准的本地字幕与幻灯片预览以及

slide-specs/NN.md

的

Narration

字段。

输出：

audio/NN.wav

或

audio/NN.mp3

、时长记录、

audio/all.wav

或

audio/all.mp3

以及

audio/tts-metadata.md

。

步骤9从强制性的语音源环节开始。如果运行时提供交互式选择工具，请使用它；否则将以下四个选项作为纯选择列表呈现。在用户选择之前，切勿开始合成、安装TTS包或静默选择提供商：

使用我自己的语音克隆API — 用户拥有或控制克隆服务。
使用此环境中已配置的克隆语音 — 仅发现并列出可成功探测的提供商/预设。
使用免费在线语音渠道 — 发现可用的免费候选工具，说明网络/隐私/使用限制，然后请用户选择语音。
使用免费本地/离线语音渠道 — 发现已安装的离线候选工具，或解释所需的安装、模型大小、质量和硬件权衡，然后请求安装许可。

将所选渠道记录在

project-config.md

和

audio/tts-metadata.md

中。该选择对批次具有约束力，除非用户明确更改。如果提供商失败，必须停止并给出明确错误；切勿静默回退到其他语音渠道，因为这会改变身份、许可、隐私和输出质量。

用户选择分支后，阅读并遵循

references/tts-source-selection.md

中的提供商发现、候选比较、API合同字段、凭证处理、探测、元数据和失败行为。

对于用户拥有的API，收集非机密的API合同，仅询问存储凭证的环境变量名称。切勿要求用户将API密钥、承载令牌、密码、Cookie或签名URL粘贴到聊天或项目文件中。在批量生成之前，用简短无害的句子探测所选适配器。

对于已配置、免费在线或本地/离线渠道，先发现并探测候选工具，然后请用户选择具体的提供商和语音。说明适用的网络、隐私、限制、安装、硬件和许可权衡。

edge-tts

可作为候选工具提供，但绝非静默默认。未经批准，请勿安装运行时或下载模型权重。

Shared Generation Rules

共享生成规则

Record the selected method before generating audio.
Probe it before using it for the batch. If it is missing, misconfigured, or unclear, stop with an actionable report.
Use the selected channel for all narration unless the user explicitly changes the choice.
If the provider exposes emotion, sampling, speed, seed, or reference-mode controls, choose and record a conservative consistency profile before batch generation. Do not rely on "same voice" alone as proof that all pages will sound consistent.
For voice cloning, prefer a mode that follows the reference voice directly when text-description emotion control causes unstable tone. Avoid blank emotion-text modes that infer exaggerated emotion from each slide.
Keep emotion control weak and stable by default: natural, clear explanation; steady speed; clear pauses; no exaggerated performance.
Do not bind audio pauses to subtitle chunks. Subtitle boundaries exist for reading and may split one spoken sentence into several entries; they must never insert silence into speech.
When a voice sounds flat as one long page but mechanical as sentence-by-sentence synthesis, group narration into 2–4 semantic paragraphs. Synthesize each paragraph continuously with one stable profile, normalize paragraph loudness, and insert only a short deterministic breath between semantic paragraphs. Keep ordinary full stops inside each paragraph under the model's natural prosody.
Record the approved paragraph grouping, inter-paragraph breath duration, loudness target, provider-specific controls, and prompt in TTS metadata before batch generation.

For free online providers, a command may look like this after the user explicitly selects the provider and voice:

bash

edge-tts --voice SELECTED_VOICE --text "..." --write-media audio/01.mp3

Use one audio file per narrated slide. The cover is excluded unless it has narration. Concatenate in slide order to

audio/all.wav

audio/all.mp3

with ffmpeg. Use the same extension consistently inside

audio/durations.json

deck.html

, and

tts-metadata.md

The TTS metadata must include the actual generation profile, not only the provider name:

provider and command/API
voice/preset/reference audio
emotion mode and emotion text, if any
speed, temperature, top-p/top-k, seed, or equivalent sampling controls when the tool exposes them
output file for every slide
measured duration for every slide
any regenerated slide and why it was regenerated

After generation, check page-to-page voice consistency. At minimum, listen to the first slide, the second slide, and any slide whose text may push emotion strongly. If one page has a different tone, do not accept the batch just because the files exist. Regenerate the bad page with the same conservative profile, then rebuild duration records and

audio/all.*

Treat cloned-voice approval as five separate gates: speaker identity, breath support, prosodic contour, pause structure, and noise floor. Passing one does not imply the others pass. A familiar timbre can still be flat, mechanically segmented, breathless, or noisy.

Also check speaking-rate consistency. Do not judge only by total duration. Compare each slide's approximate characters-per-second and listen for local rush/drag inside the slide. If one slide has a clearly different pacing curve, first inspect its

Narration

for long chains, dense terminology, or awkward punctuation; fix the narration in

storyboard.md

, re-freeze affected slide specs, and only then regenerate TTS.

Run a noise-floor gate before building final timing:

listen to the beginning, middle, and end of a representative page; a denoiser that sounds clean only at the beginning fails
distinguish stable model hiss from intended breaths and deterministic semantic pauses
after the user approves timbre and prosody, prefer post-processing the approved WAV over resynthesizing it; resynthesis may change identity, contour, and timing
denoise into a separate directory, never overwrite approved raw audio
require every processed file to preserve exact duration and sample count before reusing subtitle or slide timing
choose the most natural acceptable denoise, not the numerically quietest one; metallic speech, watery artifacts, pumping, missing sibilants, or weakened consonants are failures
when using FFmpeg
```
afftdn
```
, do not assume
```
track_noise=1
```
is safer: adaptive tracking can make the beginning clean and let noise return later
for steady clone-model hiss, compare a fixed FFT profile with non-local means; an established conservative NLM starting point is
```
highpass=f=65,anlmdn=s=0.0025:p=0.002:r=0.006:m=11
```
, then verify by ear

Read

references/cloned-voice-video-production.md

when using a cloned voice, semantic-paragraph synthesis, denoising, or Playwright recording.

After audio is generated, do not stop at a file list. Update the timing records and prepare the deck for the next sync step:

write measured duration for every narrated slide into
```
audio/durations.json
```
concatenate narrated slide audio into
```
audio/all.wav
```
or
```
audio/all.mp3
```
keep the cover duration in the deck timeline, normally about 3 seconds
make sure
```
deck.html
```
references the actual per-slide audio files
do not ask the user to approve
```
?preview=1
```
yet; exact subtitle sync has not been generated

The user checkpoint at this step is voice quality, not full video approval. If needed, give the user a short audio sample or a partial audio preview. Full video preview happens after Step 10 creates precise subtitle timing.

The cover frame has no narration by default. Do not generate TTS for

cover.md

unless the user explicitly adds cover narration. Its default 3-second duration is handled in the deck timeline.

If narration changes after this step, return to Step 8, regenerate affected slide audio, rebuild

audio/all.*

, rebuild timestamps, update preview, and recheck sync.

在生成音频之前记录所选方法。
在批量使用之前进行探测。如果缺失、配置错误或不明确，停止操作并提供可操作的报告。
除非用户明确更改选择，否则使用所选渠道生成所有旁白。
如果提供商公开情感、采样、语速、种子或参考模式控制，在批量生成之前选择并记录保守的一致性配置文件。切勿仅依赖“相同语音”作为所有页面声音一致的证明。
对于语音克隆，当文本描述情感控制导致语调不稳定时，优先选择直接跟随参考语音的模式。避免空白情感文本模式，因为它会从每张幻灯片推断夸张的情感。
默认保持情感控制弱且稳定：自然、清晰的解释；稳定的语速；清晰的停顿；无夸张表达。
切勿将音频停顿绑定到字幕块。字幕边界是为阅读而设的，可能将一个口述句子拆分为多个条目；切勿在语音中插入沉默。
当语音作为长页面听起来平淡，但逐句合成又机械时，将旁白分组为2–4个语义段落。用一个稳定的配置文件连续合成每个段落，标准化段落音量，并在语义段落之间插入短暂的确定性停顿。保持每个段落内的普通句号遵循模型的自然韵律。
在批量生成之前，将批准的段落分组、段落间停顿时长、音量目标、提供商特定控制和提示记录在TTS元数据中。

对于免费在线提供商，用户明确选择提供商和语音后的命令可能如下：

bash

edge-tts --voice SELECTED_VOICE --text "..." --write-media audio/01.mp3

每个有旁白的幻灯片使用一个音频文件。封面除非有旁白，否则不包含在内。使用ffmpeg按幻灯片顺序合并为

audio/all.wav

或

audio/all.mp3

。在

audio/durations.json

、

deck.html

和

tts-metadata.md

中一致使用相同的扩展名。

TTS元数据必须包含实际生成配置文件，而非仅提供商名称：

提供商和命令/API
语音/预设/参考音频
情感模式和情感文本（如有）
提供商工具公开的语速、温度、top-p/top-k、种子或等效采样控制
每张幻灯片的输出文件
每张幻灯片的测量时长
任何重新生成的幻灯片及其原因

生成后，检查页面间的语音一致性。至少收听第一张幻灯片、第二张幻灯片以及任何文本可能强烈推动情感的幻灯片。如果某一页语调不同，切勿仅因文件存在就接受批次。使用相同的保守配置文件重新生成有问题的页面，然后重建时长记录和

audio/all.*

。

将克隆语音批准视为五个独立环节：说话人身份、呼吸支持、韵律轮廓、停顿结构和本底噪声。通过一个环节并不意味着其他环节也通过。熟悉的音色仍可能平淡、机械分段、气喘或有噪声。

还要检查讲话速率一致性。切勿仅通过总时长判断。比较每张幻灯片的近似字符/秒，并收听幻灯片内的局部急促/拖沓。如果某张幻灯片的节奏曲线明显不同，首先检查其

Narration

是否有长链、密集术语或尴尬标点；在

storyboard.md

中修复旁白，重新冻结受影响的幻灯片规格，然后重新生成TTS。

在构建最终时长之前运行本底噪声环节：

收听代表性页面的开头、中间和结尾；仅开头干净的降噪器是失败的
区分稳定的模型嘶嘶声与有意的呼吸和确定性语义停顿
用户批准音色和韵律后，优先对批准的WAV进行后处理，而非重新合成；重新合成可能改变身份、轮廓和时长
将降噪后的文件保存到单独目录，切勿覆盖批准的原始音频
要求每个处理后的文件保留确切的时长和样本数，然后再重用字幕或幻灯片时长
选择最自然的可接受降噪，而非数值上最安静的；金属感语音、水样 artifacts、泵浦效应、缺失的咝音或弱化的辅音都是失败的
使用FFmpeg
```
afftdn
```
时，切勿假设
```
track_noise=1
```
更安全：自适应跟踪可能开头干净，之后又出现噪声
对于稳定的克隆模型嘶嘶声，比较固定FFT配置与非局部均值；保守的NLM起始点为
```
highpass=f=65,anlmdn=s=0.0025:p=0.002:r=0.006:m=11
```
，然后通过听觉验证

使用克隆语音、语义段落合成、降噪或Playwright录制时，阅读

references/cloned-voice-video-production.md

。

音频生成后，不要停留在文件列表。更新时长记录并为下一步同步准备演示文稿：

将每个有旁白的幻灯片的测量时长写入
```
audio/durations.json
```
将有旁白的幻灯片音频合并为
```
audio/all.wav
```
或
```
audio/all.mp3
```
在演示文稿时间线中保留封面时长，通常约3秒
确保
```
deck.html
```
引用实际的每张幻灯片音频文件
请勿要求用户批准
```
?preview=1
```
；尚未生成精确的字幕同步

此步骤的用户检查点是语音质量，而非完整视频批准。如有需要，向用户提供简短的音频样本或部分音频预览。完整视频预览在步骤10创建精确字幕时长后进行。

封面帧默认无旁白。除非用户明确添加封面旁白，否则请勿为

cover.md

生成TTS。其默认3秒时长在演示文稿时间线中处理。

如果此步骤后旁白更改，返回步骤8，重新生成受影响的幻灯片音频，重新构建

audio/all.*

，重新构建时间戳，更新预览并重新检查同步。

Step 10: Timing and Subtitle Sync

步骤10：时长与字幕同步

Inputs:

audio/

slide-specs/

deck.html

Outputs: updated

deck.html

subtitles.json

subtitles.srt

, and alignment metadata such as

audio/subtitle-alignment.md

Use audio as the clock:

replace estimated
```
slideDelays
```
with actual audio durations
keep each slide's GSAP timeline consistent with the approved visual rhythm
use early-established animation by default; only synchronize visual events to exact subtitle rhythm when the user approved that direction
generate timestamps with Whisper or another timestamp tool
use slide spec
```
Narration
```
text as the display subtitle source; use TTS audio timing as the time source
after TTS, recalculate subtitle segment durations from the real audio timing of each slide
when using Whisper, treat recognized text as untrusted for display; use it only to locate time boundaries, because technical terms and names are often misrecognized
subtitle chunking after TTS must follow spoken timing boundaries, not only written punctuation or text length. If one spoken segment contains two written fragments, merge those fragments into one subtitle entry; if one written sentence is spoken in two clear segments, split it at the natural pause.
when word-level timestamps are available, use them to capture local speech pace, but still apply a display layer: do not show isolated open-list fragments such as
```
Prompt、
```
or entries shorter than about 0.8 seconds. Merge them with a neighboring subtitle while preserving the original narration text order.
create
```
subtitles.json
```
with per-slide relative timestamps so browser preview can sync each slide's own audio file
create
```
subtitles.srt
```
for final video or subtitle burning
```
deck.html?preview=1
```
must read
```
subtitles.json
```
when it exists; only pre-TTS subtitle preview may use estimated duration splitting
preserve a short inter-slide pause unless the user explicitly asks for hard cuts

Subtitle and narration are not separate sources by default:

```
Narration
```
is both the TTS source and the subtitle text source
generated subtitles may split lines and timestamps, but should not rewrite words
if subtitles are manually edited as an exception, rebuild subtitles and preview
if narration changes, rebuild TTS, subtitles, preview, and recording

Machine checks:

audio files count equals the number of slide specs with
```
Narration
```
; cover is excluded unless it has narration
total slide timing matches
```
audio/all.*
```
duration plus cover and inter-slide pauses within tolerance
no subtitle entry has zero or negative duration
every narrated slide has at least one subtitle entry in
```
subtitles.json
```
subtitles cover the video without large gaps or overrun

输入：

audio/

、

slide-specs/

、

deck.html

。

输出：更新后的

deck.html

、

subtitles.json

、

subtitles.srt

以及对齐元数据（如

audio/subtitle-alignment.md

）。

使用音频作为时间基准：

用实际音频时长替换预估的
```
slideDelays
```
保持每张幻灯片的GSAP时间线与批准的视觉节奏一致
默认使用早期建立的动画；仅当用户批准该方向时，才将视觉事件与确切的字幕节奏同步
使用Whisper或其他时间戳工具生成时间戳
使用幻灯片规格的
```
Narration
```
文本作为显示字幕来源；使用TTS音频时长作为时间来源
TTS生成后，根据每张幻灯片的真实音频时长重新计算字幕片段时长
使用Whisper时，将识别的文本视为不可信的显示文本；仅用它定位时间边界，因为技术术语和名称经常被错误识别
TTS后的字幕分段必须遵循口述时长边界，而非仅书面标点或文本长度。如果一个口述片段包含两个书面片段，将这些片段合并为一个字幕条目；如果一个书面句子被分成两个清晰的口述片段，在自然停顿处拆分。
当单词级时间戳可用时，用它们捕捉局部讲话节奏，但仍需应用显示层：请勿显示孤立的开放式列表片段（如
```
Prompt、
```
）或短于约0.8秒的条目。将它们与相邻字幕合并，同时保留原始旁白文本顺序。
创建带有每张幻灯片相对时间戳的
```
subtitles.json
```
，以便浏览器预览可以同步每张幻灯片自己的音频文件
创建
```
subtitles.srt
```
用于最终视频或字幕嵌入
```
deck.html?preview=1
```
存在时必须读取
```
subtitles.json
```
；仅TTS前的字幕预览可使用预估时长拆分
除非用户明确要求硬切，否则保留短暂的幻灯片间停顿

默认情况下，字幕和旁白不是单独的来源：

```
Narration
```
既是TTS来源也是字幕文本来源
生成的字幕可拆分换行和时间戳，但不得改写单词
如果作为例外手动编辑字幕，重新构建字幕和预览
如果旁白更改，重新构建TTS、字幕、预览和录制

机器检查：

音频文件数量等于带有
```
Narration
```
的幻灯片规格数量；封面除非有旁白，否则不包含在内
总幻灯片时长与
```
audio/all.*
```
时长加上封面和幻灯片间停顿在公差范围内匹配
没有字幕条目时长为零或负数
每个有旁白的幻灯片在
```
subtitles.json
```
中至少有一个字幕条目
字幕覆盖整个视频，无大间隙或溢出

Step 11: Browser Preview

步骤11：浏览器预览

Inputs:

deck.html

audio/NN.*

audio/durations.json

subtitles.json

subtitles.srt

Output:

?preview=1

review session.

In preview mode:

embed or sequence the generated audio files from
```
audio/
```
start after user gesture
use
```
audio.currentTime
```
/
```
timeupdate
```
to drive slide changes and subtitle display
do not rely on guessed timers for audio sync
start a local HTTP server when browser audio loading requires it

Human checkpoint required. Ask the user to approve the preview before recording. Do not record before this is approved, unless the user explicitly chose auto mode.

输入：

deck.html

、

audio/NN.*

、

audio/durations.json

、

subtitles.json

、

subtitles.srt

。

输出：

?preview=1

审查会话。

在预览模式下：

嵌入或序列播放
```
audio/
```
中的生成音频文件
用户触发后开始
使用
```
audio.currentTime
```
/
```
timeupdate
```
驱动幻灯片切换和字幕显示
切勿依赖猜测的计时器进行音频同步
当浏览器音频加载需要时，启动本地HTTP服务器

需要人工检查点。请用户在录制前批准预览。除非用户明确选择auto模式，否则录制前必须获得批准。

Step 12: Background Render and Assemble

步骤12：后台渲染与组装

Inputs: approved

deck.html

audio/NN.*

audio/durations.json

subtitles.json

subtitles.srt

Output:

output.mp4

This step must be background and non-interruptive. Do not use visible desktop screen recording, QuickTime-style recording, manual browser capture, or any path that steals focus from the user's current work.

Preferred path:

Start a local HTTP server for the workdir.
Launch Headless Chrome / Playwright / another headless browser in the background.
Render the approved deck through a recording/export mode that has no visible controls, no preview overlay, and no manual interaction.
Create a final audio track such as
```
audio/final-mix.wav
```
that includes the cover silence and the same short inter-slide pauses used by the visual timeline.
Use ffmpeg to assemble the rendered visual stream and final audio track into
```
output.mp4
```
.

The assembled MP4 should open on the complete static cover frame. Because macOS Finder / Quick Look often uses the first video frame as the thumbnail, the first encoded frame must already be the final cover state. Do not solve this with export-time cover-animation patches; the cover itself should have no animation.

Do not assume a browser recording starts at visual timeline zero. Playwright/WebM recording begins when the context starts and may include page load, navigation, button setup, and shutdown tail frames. Before muxing:

hide preview controls from HTML parsing time in a render-only mode; hiding them after load can still contaminate the first encoded frame
call the playback function programmatically and return immediately instead of awaiting the full-run Promise inside
```
page.evaluate
```
mute the browser's preview audio in render mode while preserving
```
audio.currentTime
```
as the visual/subtitle clock; add the approved final mix during ffmpeg assembly
run a short startup probe that proves
```
previewRunning
```
, slide ID, growing audio time, visible subtitle, and no page error
inspect the raw recording around load, cover, Slide 01, and shutdown; measure startup lead and tail instead of guessing
if raw recording lead makes exact trim fragile, construct the first cover interval from the approved full-cover still and splice the recording at the measured Slide 01 transition
make the final encoded duration follow the final audio clock, then verify video/audio stream duration delta

Use a practical video frame rate for animation.

24fps

is the normal floor for final output;

30fps

is acceptable when motion is dense or the machine can render it comfortably. Do not use very low rates such as

12fps

for final delivery unless the user explicitly accepts a choppy preview render.

If the local ffmpeg build supports

subtitles

/ libass, the agent may render clean visuals and burn

subtitles.srt

during assembly. If subtitle burning is unavailable, render HTML subtitles inside the headless browser frame. In both cases, the final

output.mp4

must contain visible subtitles.

Before rendering, confirm the recording path if the project has not already selected one. If the user does not care, choose the background path that works with the current local tools. Never fall back to foreground screen recording unless the user explicitly asks for that.

Use the available ffmpeg path. On Apple Silicon Homebrew, ffmpeg may live under

/opt/homebrew

; on Intel, under

/usr/local

. Do not hardcode one path without probing.

Timing rules:

```
audio/all.*
```
usually contains only continuous narration and is not enough for final assembly when the video has a cover frame or page pauses.
Build a final mixed audio file that matches the visual timeline exactly: cover silence, optional cover narration if approved, inter-slide pauses, and every slide audio in order.
The visual timeline, subtitle timeline, and final mixed audio duration should match within normal encoding tolerance.

After assembly, verify more than metadata:

run
```
ffprobe
```
for codecs, resolution, frame rate, stream durations, pixel format, and sample rate
run black-frame detection and final loudness/peak measurement
extract and visually review at least six real frames:
```
0s
```
cover, cover-to-Slide-01 transition, early narrated frame with subtitle, middle, late final slide, and final second
confirm subtitles are actually in pixels, not merely present in a JSON/SRT artifact
require the audio/video stream duration delta to be small enough that no visible end drift can accumulate
verify the first encoded frame is the complete cover and contains no play button, browser control, subtitle bar, or loading residue

After a successful assembly, clean the workdir before delivery. Delete render-only caches such as

render/frames/

, temporary browser profiles, temporary silence files created during assembly, check screenshots, raw recognizer outputs, raw TTS response logs, concat lists, and one-off helper scripts. Do not delete

article.md

content-understanding.md

theme-extraction.md

storyboard.md

slide-specs/

visual-logic.md

deck.html

gsap.min.js

, approved audio files, duration records, subtitle files, alignment notes,

audio/final-mix.*

, or

output.mp4

unless the user explicitly asks.

输入：已批准的

deck.html

、

audio/NN.*

、

audio/durations.json

、

subtitles.json

、

subtitles.srt

。

输出：

output.mp4

。

此步骤必须在后台进行且不中断。请勿使用可见的桌面屏幕录制、QuickTime风格录制、手动浏览器捕获或任何占用用户当前工作焦点的方式。

首选路径：

为工作目录启动本地HTTP服务器。
在后台启动Headless Chrome / Playwright / 其他无头浏览器。
通过无可见控件、无预览覆盖层、无需手动交互的录制/导出模式渲染已批准的演示文稿。
创建最终音频轨道（如
```
audio/final-mix.wav
```
），包含封面静音和视觉时间线使用的相同短暂幻灯片间停顿。
使用ffmpeg将渲染的视频流和最终音频轨道组装为
```
output.mp4
```
。

组装后的MP4应从完整的静态封面帧开始播放。由于macOS Finder / Quick Look通常使用第一帧作为缩略图，第一个编码帧必须已是最终封面状态。请勿用导出时的封面动画补丁解决此问题；封面本身不应有动画。

切勿假设浏览器录制从视觉时间线零点开始。Playwright/WebM录制从上下文启动时开始，可能包含页面加载、导航、按钮设置和关闭尾部帧。混流前：

在仅渲染模式下，从HTML解析时隐藏预览控件；加载后隐藏仍可能污染第一个编码帧
以编程方式调用播放函数并立即返回，而非在
```
page.evaluate
```
内等待完整运行的Promise
在渲染模式下静音浏览器预览音频，同时保留
```
audio.currentTime
```
作为视觉/字幕时钟；在ffmpeg组装期间添加批准的最终混音
运行简短的启动探测，证明
```
previewRunning
```
、幻灯片ID、增长的音频时间、可见字幕和无页面错误
检查加载、封面、幻灯片01和关闭周围的原始录制；测量启动前导和尾部，而非猜测
如果原始录制前导使精确修剪脆弱，从批准的完整封面静止帧构建第一个封面间隔，并在测量的幻灯片01过渡处拼接录制
使最终编码时长遵循最终音频时钟，然后验证视频/音频流时长差

为动画使用实用的视频帧率。

24fps

是最终输出的正常下限；当动画密集或机器可以舒适渲染时，

30fps

是可接受的。除非用户明确接受卡顿的预览渲染，否则最终交付不要使用极低帧率（如

12fps

）。

如果本地ffmpeg构建支持

subtitles

/ libass，Agent可渲染清晰的视觉效果并在组装期间嵌入

subtitles.srt

。如果无法嵌入字幕，在无头浏览器帧内渲染HTML字幕。无论哪种情况，最终的

output.mp4

必须包含可见字幕。

渲染前，如果项目尚未选择录制路径，请确认。如果用户不在意，选择适应当前本地工具的后台路径。除非用户明确要求，否则切勿回退到前台屏幕录制。

使用可用的ffmpeg路径。在Apple Silicon Homebrew上，ffmpeg可能位于

/opt/homebrew

；在Intel上，位于

/usr/local

。未经探测，切勿硬编码路径。

时长规则：

```
audio/all.*
```
通常仅包含连续旁白，当视频有封面帧或页面停顿时，不足以用于最终组装。
构建与视觉时间线完全匹配的最终混合音频文件：封面静音、批准的可选封面旁白、幻灯片间停顿以及按顺序的每张幻灯片音频。
视觉时间线、字幕时间线和最终混合音频时长应在正常编码公差范围内匹配。

组装后，不仅验证元数据：

运行
```
ffprobe
```
检查编解码器、分辨率、帧率、流时长、像素格式和采样率
运行黑帧检测和最终响度/峰值测量
提取并视觉审查至少六个真实帧：
```
0s
```
封面、封面到幻灯片01的过渡、带字幕的早期旁白帧、中间帧、后期最终幻灯片帧和最后一秒
确认字幕确实在像素中，而非仅存在于JSON/SRT工件中
要求音频/视频流时长差足够小，不会累积可见的末尾漂移
验证第一个编码帧是完整封面，无播放按钮、浏览器控件、字幕栏或加载残留

成功组装后，在交付前清理工作目录。删除仅渲染缓存，如

render/frames/

、临时浏览器配置文件、组装期间创建的临时静音文件、检查截图、原始识别器输出、原始TTS响应日志、合并列表和一次性辅助脚本。除非用户明确要求，否则请勿删除

article.md

、

content-understanding.md

、

theme-extraction.md

、

storyboard.md

、

slide-specs/

、

visual-logic.md

、

deck.html

、

gsap.min.js

、批准的音频文件、时长记录、字幕文件、对齐说明、

audio/final-mix.*

或

output.mp4

。

Step 13: Deliver

步骤13：交付

Output the

output.mp4

path and note any skipped verification.

输出

output.mp4

路径，并注明任何跳过的验证。

Change Rules

变更规则

User content changes go into
```
storyboard.md
```
, then re-freeze.
Do not patch
```
slide-specs/
```
by hand unless the user explicitly asks for emergency surgery.
If
```
storyboard.md
```
hash differs from slide specs, stop before rendering or TTS.
If
```
visual-logic.md
```
is missing or stale after slide/storyboard changes, regenerate it before rebuilding
```
deck.html
```
.
If
```
deck.html
```
text differs from slide specs, fix
```
deck.html
```
; do not treat it as a source.
If theme changes, regenerate
```
theme-extraction.md
```
, rebuild
```
deck.html
```
, and preview again.
If narration changes, rebuild TTS, timing, subtitles, preview, and recording.
If only subtitle text changes, rebuild subtitles and preview; check whether it still matches the audio.

用户内容更改写入
```
storyboard.md
```
，然后重新冻结。
除非用户明确要求紧急修改，否则请勿手动修改
```
slide-specs/
```
。
如果
```
storyboard.md
```
哈希与幻灯片规格不同，在渲染或TTS前停止。
如果幻灯片/分镜脚本更改后
```
visual-logic.md
```
缺失或过期，在重新构建
```
deck.html
```
前重新生成。
如果
```
deck.html
```
文本与幻灯片规格不同，修复
```
deck.html
```
；切勿将其视为源文件。
如果主题更改，重新生成
```
theme-extraction.md
```
，重新构建
```
deck.html
```
并再次预览。
如果旁白更改，重新构建TTS、时长、字幕、预览和录制。
如果仅字幕文本更改，重新构建字幕和预览；检查是否仍与音频匹配。",