Веб-видеопрезентация

Пошаговое преобразование статьи или текста дикторского текста в «веб-страницу, маскирующуюся под видео», пригодную для записи экрана, с возможностью добавления аудиозаписи дикторского текста. Результат = проект на Vite + React + TS + аудиозаписи, разбитые по разделам.

Сферы применения

• «У меня есть текст дикторского комментария / статья, помогите превратить это в видео» — контент, основанный на дикторском комментарии
• Хотите создать «динамическую презентацию»
• Запись экрана в горизонтальном формате 16:9 с крупным шрифтом, пробелами и анимацией на каждом экране
• Обучение / Демонстрация продукта / Keynote Хочу добиться кинематографического эффекта
• Видеоконтент для Bilibili / YouTube / Douyin

В основе этого Skill лежат методология и процесс совместной работы. Шаблоны-каркасы предоставляют токены и праймити, но каждое эстетическое решение (цветовая гамма, шрифты, характер анимации) должно быть переработано с учётом вашей темы — не копируйте шаблоны без изменений.

Обзор рабочего процесса

Phase 1   内容编写
   1.1  识别用户输入
   1.2  一次产出 script.md + outline.md
        （口播稿 + 开发计划）
   ▼
[Checkpoint Plan]      ← 必须停。一次对齐 5 件事：
                         稿子 / outline / 主题 / 素材 / 开发模式
   ▼
Phase 2   网页开发
   2.1  脚手架（按选定主题）
   2.2  第 1 章 = 主线程 + 完整版本（强制 anchor）
        ▼
        [硬节点] 用户验收第 1 章 ← 不可跳过
        ▼
   2.3  第 2~N 章（按选定模式：A 逐章 / B 顺序 / C 并行）
   ▼
[Checkpoint Audio]     ← 必须停。是否合成音频
   ▼
Phase 3   音频合成（可选）
   ▼
Phase 4   录屏 + 后期

Соглашения по рабочему каталогу (agent создаёт/редактирует файлы в текущем каталоге пользователя):

my-video/
├── article.md          # 用户给原文时必有 —— 不删！开发阶段画面信息源
├── script.md           # 必有：保持原文语言的平台化口播稿（决定节拍）
├── outline.md          # 必有：开发计划（章节切分 + 每步内容 + 信息池）
└── presentation/       # 脚手架产出的 Vite + React + TS 项目
    ├── src/chapters/-/
    │   ├── .tsx     # 视觉实现
    │   ├── .css
    │   └── narrations.ts     # ★ step 数 + 口播文本的唯一真相源
    ├── scripts/
    │   ├── extract-narrations.ts   # 扫所有 narrations.ts → audio-segments.json
    │   ├── synthesize-audio.sh     # provider-agnostic runner（循环 segments）
    │   └── tts-providers/          # 每 provider 一个 .sh（内置 2 个）
    │       ├── README.md           # 三函数契约 + 5 段现成代码片段（11labs / edge-tts / say / azure / gcloud）
    │       ├── minimax.sh          # 默认 provider，用 mmx-cli
    │       └── openai.sh           # 内置 OpenAI TTS（curl + OPENAI_API_KEY）
    ├── audio-segments.json         # extract 产出（合成前 review）
    └── public/audio//.mp3   # 可选：合成的音频

Важно:narrations.ts является единственным достоверным источником информации о количестве шагов и синтезе звука. Разделы .tsx в if (step === N) в разделе «Главы» должно равняться narrations.length. Это гарантирует, что в 5 местах (скрипт / контур / код разделов / chapters.ts / аудиофайлы) никогда не будет несоответствий.

Строгий протокол самопроверки (на протяжении всего Skill)

Каждый из следующих трёх результатов после завершения должен пройти цикл «самопроверка → исправление → повторное представление / продвижение»:

Способы выполнения (по мере снижения сложности, предпочтительно использовать более изолированные методы):

1. Agent Teams (оптимальный вариант) : запустить отдельный агент-рецензент, предоставить ему «путь к выходным файлам + соответствующий чек-лист + ключевой контекст», чтобы он проверил каждый пункт и строго сообщил выводы (какие пункты прошли / какие не прошли + доказательства + рекомендации по исправлению).
2. subAgent (второй по эффективности вариант): если нет возможности использовать Teams, но можно запустить subagent, то используйте subagent и следуйте тому же процессу.
3. Самопроверка (в крайнем случае) : если ни один из текущих агентов не обладает вышеуказанными возможностями, необходимо самостоятельно провести тщательную провер ку каждого пункта — недопустимо просто просматривать документ и сразу давать добро.

Железное правило: после получения выводов сначала исправьте результаты по пунктам, отмеченным как «не прошли», а затем сообщите пользователю «работа выполнена

• результаты самопроверки + что было исправлено». Прямой отчет с исходными выводами без исправлений = нарушение.

Руководство по чтению документов на разных этапах

На разных этапах читайте разные документы. Во время длительных сессий агенты легко забывают о принципах, особенно о «главе о реализации» в Фазе 2.4, которая повторяется N раз — каждый раз необходимо возвращаться к основным ограничениям.

При написании глав читайте только один документ CHAPTER-CRAFT.md. Десять принципов / самомотивация перед началом работы / дерево решений / противодействие «ИИ-стилю» и шаблонам / самопроверка по завершении — всё это объединено в этом единственном документе.EXAMPLES/ Не обязательно читать — сначала свободно разрабатывайте дизайн, руководствуясь содержанием, а если застрянете, только тогда обращайтесь к документу (изучайте «форму» по анкорам, не копируйте дословно).

Фаза 1 — Написание контента (однократное создание)

1.1 Определение пользовательского ввода

1.2 Результат за один раз: script.md + outline.md

Оба результата создаются в ходе одного мыслительного процесса:

1. Генерация файла script.md: в соответствии с references/SCRIPT-STYLE.md правилам преобразует статью в дикторский текст для платформы, сохраняя язык оригинала. Сохраняйте файл `article.md` — он служит источником деталей для заполнения информационного пула в `outline.md` и визуализации разделов (принцип двойного источника).
2. Создание outline.md: в соответствии с references/OUTLINE-FORMAT.md правилам разбивайте на главы + разбивайте на шаги + извлекайте информацию из первого абзаца каждой главы.

Границы outline (ключевой момент):

Причины, по которым в конспекте не указываются анимации: жестко заданная анимация = деградация агента главы до уровня переводчика; Оставление свободного пространства позволяет агенту главы при начале работы каждого шага CHAPTER-CRAFT.md «дерево решений, управляемое контентом», — только так достигается подлинное ощущение видео. Подробнее см. CHAPTER-CRAFT.md Части 0, принцип 7.

После завершения этапа необходимо сначала выполнить самопроверку, а затем перейти к плану контрольных точек: в соответствии с описанным выше «строгим протоколом самопроверки» поочерёдно выполнить script.md / outline.md (в приоритетном порядке: Agent Teams → subAgent → самопроверка), и только после устранения неисправностей в соответствии с выводами переходить к Checkpoint Plan.

Checkpoint Plan — одновременное согласование 5 элементов (жесткий узел)

script.md + outline.md После завершения написания необходимо остановиться. На этом узле пользователь одновременно подтверждает 5 пунктов.

Подготовительная работа, которую агент должен выполнить в этот момент

1. прочитать все themes/*/theme.json взять nameZh / descriptionZh / bestFor / mood — не следует жестко кодировать список
2. В соответствии с script.md типа содержания / ключевых слов / тона, самостоятельно выбрать из темы 2–3 набора наиболее подходящих рекомендаций (по bestFor поля)
3. Просмотрите outline.md раздел «Список материалов» в конце

подготовить шаблон (каркас, агент заполняет в зависимости от ситуации)

内容计划写完，产出文件：
  📄 article.md     {若用户给原文则保留}
  📄 script.md      {X} 字 / ~{T} 分钟
  📄 outline.md     {N} 章 / {M} 步 + 每章信息池 + 末尾素材清单

章节速览：
  1.      <章节标题>     步 ~s
  2. ...

接下来一次对齐 5 件事：

  1. 稿子 (script.md) 要不要改？
     可以直接编辑文件，或口头告诉我修改方向。

  2. 开发计划 (outline.md) 要不要改？重点看：
     - 章节切分 / step 数 / 估时是否合理（合理判断：每章 30~60s）
     - 每步屏幕内容是否清晰
     - 每章首段「信息池」是否有足够的 article 细节供画面挂
     - 末尾素材清单是否完整

  3. 选哪个主题？我的推荐：
     ★ <推荐 1：nameZh (id)> — 因为 ；
     ★ <推荐 2 / 推荐 3>
     其它可选：<剩余主题，nameZh + 一句话>
     也可以让我帮你做新主题（详见 references/THEMES.md）。

  4. 真素材怎么准备？粗看本视频要的图：<列粗略清单>
     a) 我从 <现有素材路径> 帮你挑   b) 你自己提供   c) 全部 placeholder

  5. 开发模式选哪个？

     **第 1 章无论哪种模式都必须主线程做完 + 用户验收**（强制 anchor）。
     差异在第 2 章及之后：

     A) 默认 · 逐章确认（推荐）
        每章做完都暂停验收 → 风险可控 / 节奏最稳
     B) 第 1 章后顺序开发（不并行）
        第 2~N 章主线程顺序做完后统一验收 → 速度中 / 适合 agent 不支持并行
     C) 第 1 章后并行开发（subagent）
        第 2~N 章用 subagent 并行 → 最快 / 用户控并行数（一次几章）
        ⚠️ 风格各章会有差异（这是预期，主题禁区兜底）

После получения обратной связи:

• Если необходимо изменить черновик / набросок: редактируйте файл напрямую, после завершения редактирования отправьте уведомление (или устно опишите изменения агенту)
• Тема должна быть четко сформулирована, прежде чем переходить к Фазе 2. Если пользователь говорит: «Выбери тему за меня» → возьмите первый из ваших рекомендаций, сообщите пользователю, что вы выбрали и почему, дайте возможность передумать
• Формат выбран → переход к Фазе 2

Фаза 2 — Разработка веб-сайта

2.1 Создание каркаса

bash /scripts/scaffold.sh \
  ./presentation \
  --theme=<用户选的主题 id>

bash /scripts/scaffold.sh --list-themes

Пользовательская тема → сначала нажмите references/THEMES.md процедуре «Создать новую тему» themes//, а затем --theme=。

добавьте в скелет 01-example демо-версию. Перед написанием реального содержания первой главы удалите:

rm -rf presentation/src/chapters/01-example

и замените presentation/src/registry/chapters.ts из него EXAMPLE_CHAPTER .

2.2 Глава 1 — Основной поток + обязательная приемка

Суть: Глава 1 = полная версия с первого раза (ритм + визуал + полный набор реальных материалов). Нет понятия «каркасной версии» — в первой главе нужно создать макет, который пользователь сможет сразу принять.

Почему в 1-й главе обязательно должен быть главный поток:

• потому что CHAPTER-CRAFT.md первая реализация данного руководства в рамках текущей темы и текущего жанра
• Если в руководстве есть пробелы или не хватает токенов цветовой схемы и шрифтов, это обязательно проявится в 1-й главе — в этом случае, благодаря обратной связи от пользователей, можно исправить руководство и настроить тему; чем раньше внести изменения, тем ниже затраты
• Последующие главы (независимо от порядка / параллельного выполнения) должны ориентироваться на шаблоны кода первой главы, поэтому первая глава = «стилистический ориентир» для данного проекта (не требуется согласованность между главами, но каждая глава сама по себе должна быть полностью убедительной)

После завершения 1-й главы необходимо остановиться и дождаться оценки пользователями:

第 1 章  做完了，dev server 在 localhost:5173 运行。

验收重点：
  □ 视觉气质对不对？符合  的预期吗？
  □ 节奏对不对？某些步太快 / 太慢 / 信息太薄？
  □ 内容驱动动画是否到位？还是有几步是无脑入场动画？
  □ 双源原则：屏幕画面有没有"口播没念但 article 能挂"的细节？
  □ 反 AI 味检查：紫粉渐变 / 圆角彩色边框 / 假插画 / emoji 是否有？

问题告诉我，我针对性改。OK 了告诉我"继续"，我按选定模式做第 2 章及之后。

2.3 Главы 2–N — в соответствии с выбранным шаблоном

Общие правила для всех шаблонов: каждая глава разрабатывается независимо CHAPTER-CRAFT.md разрабатывается независимо . Не требуется полного стилистического соответствия между главами — темы цвета / шрифтовые токены обеспечивают базовое визуальное единство, а анимация / ритм / визуальная презентация могут свободно варьироваться в пределах каждой главы в соответствии с дизайнерским замыслом.

Режим A · По умолчанию · Пошаговое подтверждение

Завершение 2-й главы → приостановка для приёмки → ОК → 3-я глава → приостановка → ... → N-я глава. Каждая глава проходит отдельную приёмку, проблемы исправляются в любой момент, риск минимален, темп наиболее стабилен. Если пользователь не указал конкретный режим, по умолчанию используется этот.

Режим B · Последовательная разработка после 1-й главы

Глава 2 → Глава 3 → ... → Глава N. Основной поток выполняется последовательно, в конце проводится единая приёмка. Средняя скорость, подходит для сред, где агент не поддерживает параллельные задачи.

Режим C · Параллельная разработка после 1-й главы (subagent)

С помощью subagent параллельно выполняются главы со 2 по N, максимальное количество параллельных задач контролируется пользователем («4 главы за раз» / «2 главы за раз»). Самый быстрый вариант, но стиль выполнения разных глав может различаться — это ожидаемо, поскольку:

1. каждый subagent не видит результатов работы других subagent и не может механически синхронизироваться
2. код глав физически разделён (по одной папке на главу / собственный префикс CSS), что исключает взаимное нарушение целостности
3. Тематические токены обеспечивают визуальную унифицированность (цвета / шрифты / цифры на главной странице / карточки / разделительные линии, характер / декоративные элементы), стиль не будет сбиваться
4. Несогласованность стиля = ощущение «живого» видео, снятого вручную (разнообразие голосов / точек зрения)

Промпт для параллельных суб-агентов должен содержать:

• Параграф с планом текущей главы (включая информационный пул)
• references/CHAPTER-CRAFT.md (единственный обязательный к прочтению — требования к визуальной демонстрации + постепенное раскрытие информации + принцип двух источников + отсутствие «AI-привкуса» + красные линии кода + самопроверка по завершении — всё в одном документе)
• Текущая тема theme.json descriptionZh / mood / bestFor(достаточно ориентироваться на стиль , анимация / продолжительность / размер шрифта / эмодзи определяются chapter agent по своему усмотрению)
• Глава 1: код служит справочным материалом по «стилю кода» (а не «объектом визуального плагиата»)
• Жесткое правило: для каждой главы используется отдельный префикс CSS (.cd- / .mg- / .pm- / ...); не изменять chapters.ts; запускать после завершения npx tsc --noEmit

Важно: независимо от выбранного режима, пользователь может в любой момент переключиться на другой режим. После завершения Главы 2 пользователь может выбрать «остальное — параллельно» или «остальное — по главам» — оба варианта подходят.

2.4 Реализация отдельной главы (обязательно пройти каждую главу)

Подробные инструкции см. references/CHAPTER-CRAFT.md —— Единый обязательный вход, охватывающий: требования к визуальной презентации / постепенное раскрытие информации / выбор содержания / принцип двух источников / основные эстетические требования к видеопрезентации / отсутствие «AI-привкуса» / красные линии в коде / самопроверка по завершении.

Ключевые моменты (подробно описано в CHAPTER-CRAFT.md):

• В каждой главе должна быть визуальная демонстрация с использованием CSS / SVG / Canvas / JS; запрещены главы, состоящие исключительно из текста
• Поэтапное раскрытие информации: в перечнях и списках 1 пункт = 1 шаг; запрещено показывать всё сразу
• Принцип двух источников: ритм должен соответствовать тексту дикторского текста (последовательность не должна нарушаться), детали следует брать из исходной статьи (информационный пул + абзацы статьи данного раздела)
• Самопроверка по завершении: проверять по пунктам, если не соответствует требованиям — возвращаться и исправлять — действовать в соответствии с «строгим протоколом самопроверки», описанным выше (в приоритетном порядке: Agent Teams → subAgent → самопроверка), после исправлений сообщать пользователю о сдаче данной главы

2.5 После крупных изменений обновите STORAGE_KEY

Изменения chapters.ts(добавление / удаление / перестановка разделов или narrations.ts изменение объёма) следует обновить presentation/src/hooks/useStepper.ts значения STORAGE_KEY(например v4 → v5), чтобы избежать ситуации, когда постоянный курсор попадает на несуществующий шаг.

Checkpoint Audio —— Синтезировать ли аудио (жесткий узел)

По завершении Фазы 2 необходимо остановиться и спросить пользователя:

网页做完，{N} 章 {M} 步，dev server 在 localhost:5173 跑着。

要不要合成音频做"自动播放录屏"？
  ✓ 合成 → 扫所有章节的 narrations.ts 出 audio-segments.json，
           调 TTS provider 合成每步一个 mp3 到 public/audio/。
           合成完后用 ?auto=1 模式可以一镜到底录屏（音视频天然同步）。
           内置两个 provider：
             • minimax (mmx-cli)    —— 默认，中文音色稳
             • openai  (OPENAI_API_KEY) —— curl-based，多数已有 key
           其它后端 (ElevenLabs / edge-tts 免费 / macOS say 离线 /
           Azure / Google) 见 scripts/tts-providers/README.md 的现成片段。
  ✗ 不合成 → 跳过 Phase 3，直接 Phase 4 用手动录屏 + 后期配音。

Синтезировать → Фаза 3. Не синтезировать → сразу Фаза 4.

Фаза 3 —— Синтез аудио (опционально)

Подробный процесс см. references/AUDIO.md. Краткая версия:

cd presentation
npm run extract-narrations   # 扫所有 narrations.ts → audio-segments.json
# 让用户扫一眼 audio-segments.json 确认文本对
npm run synthesize-audio                       # 默认 minimax provider，增量
# 或用内置 openai (要 OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# 或自定义：写一个 scripts/tts-providers/.sh，见该目录的 README.md

после завершения синтеза сообщите пользователю: место вывода / общее количество фрагментов / какие фрагменты имеют аномальную продолжительность (слишком длинные = этот шаг нужно разделить ; слишком короткие = текст слишком скудный) — дайте возможность в последний раз скорректировать ритм. Затем перейдите к Фазе 4.

Этап 4 — запись экрана + постпродакшн

Подробнее см. references/RECORDING.md. Два варианта:

Агент после завершения Фазы 3 / Checkpoint Audio самостоятельно подсказывает пользователю подходящий путь для записи экрана.

Десять принципов (краткий список)

Полный текст см. в references/CHAPTER-CRAFT.md Часть 0 — обращайтесь туда при написании разделов, ниже приведён лишь указатель.

Краткий справочник по типичным отзывам пользователей

Упрощенная таблица см. references/CHAPTER-CRAFT.md Часть 8 «Краткий справочник по типичным отзывам». Ключевой момент : сначала определите, на каком уровне лежит проблема (ритм / визуальная часть / контент / код), затем внесите изменения в минимальный фрагмент, не переделывайте всю главу заново .

Связанные ресурсы

Делайте пометки «Когда читать», чтобы не читать всё за один раз: