1仕組みと動作原理

成果物は「Webページに偽装した録画可能な動画」：Vite + React + TSプロジェクトと章ごとに分割された音声で構成され、HTML検証通過後にデフォルトでナレーション音声を直接合成します。

skills/web-video-presentation/SKILL.md

把一篇文章或口播稿，一步步做成可录屏的"伪装成网页的视频"，HTML 验证完成后默认直接合成口播音频。产出物 = Vite + React + TS 项目 + 按章节切分的音频。

ここでの処理内容：「動画制作」を「Webページ制作＋音声＋画面録画」に置き換えることで、動画編集ソフトを使わずフロントエンドのツールチェーン（章コンポーネント、トークンテーマ）を活用できるようにします。

narrations.tsをステップ数および音声合成の唯一の信頼できる情報源（Single Source of Truth）とし、章コード内の最大ステップ値 + 1がnarrations.lengthと完全に一致することを必須とします。

skills/web-video-presentation/SKILL.md

> **关键**：`narrations.ts` 是 step 数和音频合成的**唯一真相源**。

ここでの処理内容：原稿 / outline / 章コード / chapters.ts / 音声ファイルの5箇所における乖離を防止し、旧版で発生していた「Webページのステップ数と音声ファイル数の不一致」問題を根本から解決します。

3つの成果物（script.md / outline.md / 単一章の実装）を対象とする厳格な自己点検プロトコルを適用し、不合格項目を修正してから報告することを義務付けます。

skills/web-video-presentation/SKILL.md

下面三个产出，每一个**完成后必须走自检 → 修复 → 再汇报 / 推进**：

ここでの処理内容：自己点検を品質ゲートとして機能させ、能力に応じた縮退運用（Agent Teams → subAgent → 自己点検）を定義します。「未修正のまま未加工の結論を報告する行為は規約違反」という鉄則を設けています。

outlineにはアニメーションの詳細を意図的に記載しません。アニメーションを固定化すると章実装エージェントが機械的翻訳に陥るため、余白を残すことで本物の動画らしい表現を生み出します。

skills/web-video-presentation/SKILL.md

> **outline 不写动画的理由**：写死动画 = chapter agent 退化为翻译机；

ここでの処理内容：「具体化すべき部分と余白にすべき部分」を設計方針として定義します。outlineはテンポ/内容/情報プール（章分割、ステップ数、推定時間、各ステップの画面表示内容、章レベルの情報プール）のみを管理し、アニメーションはCHAPTER-CRAFT.mdの内容駆動型決定木に基づき章実装時に動的に決定します。

Checkpoint Planを必須ゲートとし、原稿・outline・素材・開発モードの4点を一括で整合確認します。テーマのデフォルトはd2-editorial-gridです。

skills/web-video-presentation/SKILL.md

## Checkpoint Plan —— 4 件事一次对齐（**硬节点**）

ここでの処理内容：人間の介入を価値の高い少数のチェックポイント（他には第1章検収と途中のモード切り替え）に絞り込み、章ごとの度重なる質疑応答を排除します。

第1章はメインスレッドでの実装とユーザー検収を必須とします。選択したテーマ/題材におけるCHAPTER-CRAFT指針の初回適用例となり、後続章のコードスタイルの基準となります。

skills/web-video-presentation/SKILL.md

**第 1 章无论哪种模式都必须主线程做完 + 用户验收**（强制 anchor）。

ここでの処理内容：「骨組みだけのドラフト」という妥協を排除します。指針の不備やテーマトークンの不足は第1章でしか顕在化しないため、手戻りコストが最も低い初期段階でユーザーが検収可能な完成サンプルを作成します。

Phase 3では音声合成の要否を確認せずデフォルトで実行します。全HTMLの完了および検証通過後、直ちに音声合成へ移行し、4つの例外時（不要の指示、認証情報不足、ローカルTTSへの変更など）のみ停止します。

skills/web-video-presentation/SKILL.md

**默认不要停下来问是否合成音频**。Phase 2 全部 HTML 已完成且验证通过后， agent 直接进入本阶段。

ここでの処理内容：「音声合成を実行するか」の都度確認を廃止しデフォルト実行とします。音声はAutoモードによるワンカット画面録画（マスター音軌＋タイムラインによるHTML制御）の前提条件となるためです。

デフォルトのTTS設定はVolcengine/Doubao向けに固定されています：engine=volcengine、seed-tts-2.0、voice_type zh_male_liufei_uranus_bigtts、speed 1.2、speech_rate 20。

skills/web-video-presentation/SKILL.md

engine=volcengine resource_id=seed-tts-2.0 voice_type=zh_male_liufei_uranus_bigtts voice_name=刘飞 2.0 speed=1.2 speech_rate=20

ここでの処理内容：即時利用可能な中国語男性音声（Liu Fei 2.0）をデフォルトとして提供し、差分処理、既存ファイルのスキップ、音量正規化を統合したパイプラインを構築します。

Phase 4の画面録画はデフォルトでCDP自動録画を採用し、本ワークフローでのscreencliの使用は明確に禁止します（AIエージェントが起動しトークンを消費するため）。

skills/web-video-presentation/SKILL.md

默认不要用 screencli 做本流程：它会启动 AI agent、消耗 tokens

ここでの処理内容：より制御しやすい代替手段（CDP/Playwright自動録画、?auto=1&record=1の手動録画、音声スキップの手動クリック）を提供し、字幕焼き込みおよび2xマスター作成の2つの後処理ブランチを備えます。

視覚表現には10項目のワンフレーズ原則をインデックスとして定めています（16:9固定ステージ、グローバルステップカウンター、ステップごとの全画面占有、ナレーションの拍＝ステップ、内容駆動型アニメーション、段階的開示、デュアルソース原則など）。

skills/web-video-presentation/SKILL.md

| 10 | 双源原则 | script 定节拍，**article 定画面密度**（落到信息池） |

ここでの処理内容：膨大なドキュメントを1ページの索引に集約し（詳細はCHAPTER-CRAFT.md Part 0）、16:9の仕様を「コンテンツ解像度1920×1080 + transform scale、レスポンシブ非対応」と定義します。

2コア機能

01記事/ナレーション原稿/コミックコマ → クリック駆動型16:9 Webプレゼンテーション（Vite + React + TSプロジェクト + ステップ分割音声）の生成

02ワンクリックでのスキャフォールディング（テーマ選択および内蔵01-exampleデモの削除手順を含む）と実依存パッケージの自動インストール

03章開発メインガイド（CHAPTER-CRAFT.md）：10の原則 / 着工前5つの確認事項 / 関係性→アクション決定木 / 視覚ツールボックス / 反AI感アンチパターン / コード規約 / 完了時セルフチェック

04Comic Panels Mode：manifest.json + panel_*.png → 16:9 モーションコミック（各コマの1〜Nステップ分割、カメラズーム、部分拡大、セリフ字幕、トランジション）

05自動音声合成パイプライン：extract-narrations → synthesize-audio（デフォルトVolcengine/Doubao、既存スキップの差分処理）→ normalize-audio → build-master-audio（マスター音軌＋タイムライン）

06CDP自動画面録画（puppeteer-coreでローカルChromeを操作し、Page.startScreencastでフレームを取得してffmpegで合成）および字幕焼き込み

0710種の内蔵テーマ（d2-editorial-grid デフォルト、bauhaus-bold、blueprint、chalk-garden、midnight-press、monochrome-print、newsroom、paper-press、sunset-zine、terminal-green、warm-keynote）とカスタムテーマ作成手順

08リッチな視覚ツールボックス参照（frontend-slides / slide-deck-generator / marp-slidesから抽出されたReactコンポーネント、SVGダイアグラム、ダッシュボードプリミティブと明確な依存関係境界）

3外部依存関係

Kind	Dependency / Endpoint
cli	npm / Vite 脚手架与依赖安装（npm create vite、npm install、npm install --save-dev tsx puppeteer-core、npx tsc --noEmit）
api	火山/豆包语音合成（默认引擎；鉴权仅从环境变量读，curl 调 unidirectional 接口）
api	MiniMax CLI（可选 TTS 路径，走 mmx auth login --api-key；key 在平台获取）
cli	MeloTTS 本地路径（可选：调 ../../.venv-tts/bin/melotts 生成 wav 再用 ffmpeg 转 mp3）
package	puppeteer-core + 本机 Chrome（CDP 录屏与字幕烧录；headless 启动参数不含任何反自动化绕过）
network	Google Fonts（主题 CSS 引用，浏览器端/录屏期拉取）与本地 dev server 端口

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: bash scripts/scaffold.sh <target> [--theme=…] (npm create vite + npm install)
scripts/ 或 SKILL.md: 外部言語パッケージ依存関係の動的インストール宣言
网络端点: 外部ネットワークアクセスの宣言: https://openspeech.bytedance.com/api/v3/tts/unidirectional (デフォルトのVolcengine/Doubao TTS、POST)
本地工作目录: ファイルの読み書きおよび成果物の出力: 生成される presentation/ プロジェクト（Vite + React + TS フルソースコード、package.json、vite.config.ts、tsc）

監査ノート： オレンジ判定（要確認）に該当する2つの要素はいずれもスキル自身のディレクトリ内で確認できます：① **認証情報ファイルの読み取り**——templates/scripts/synthesize-audio.shは環境変数がない場合、ローカルの認証情報ファイル $HOME/.config/doubao-tts/env を読み込み、DOUBAO_TTS_API_KEY / VOLCENGINE_TTS_API_KEY を認証ヘッダーとして openspeech.bytedance.com（Volcengine/Doubao TTS）へcurl送信します。また選択肢としてMiniMax CLIの mmx auth login --api-key も含まれます。② **ユーザー素材/テキストの外部送信およびアカウント利用枠の消費**——ステップ分割されたナレーションテキストが外部TTSへ逐次送信されて合成されます。またスキャフォールディング時にnpmレジストリから依存関係（vite/react/tsx/puppeteer-core）がインストールされます。いずれも「宣言された自己用途のための認証情報読み取り＋ユーザーコンテンツの外部サービス/バックエンドへの送信」というオレンジ判定の要件に該当しますが、縮退代替手段（ローカルMeloTTSの利用、音声合成をスキップしてHTMLのみを出力する設定）が用意されています。なお、セキュリティ設定の無効化（TLS無効化、--no-verify等）、自動化検出回避（CDP起動引数は--autoplay-policy/--hide-scrollbars/--window-sizeのみで、AutomationControlledやremote-allow-origins=*、キーストローク偽装等はなし）、サンドボックス解除、任意コード実行などの脆弱性は見当たりません。

5二重目の独立検証

[ok] TTS 凭证读取与外发是否真实（橙档关键证据） — synthesize-audio.sh 原文：'# 2. DOUBAO_TTS_API_KEY or VOLCENGINE_TTS_API_KEY for default Volcengine/Doubao TTS'；'DEFAULT_VOLCENGINE_ENV_FILE="$HOME/.config/doubao-tts/env"'；缺失时 source 该文件；取到后作为鉴权头 curl 到 https://openspeech.bytedance.com/api/v3/tts/unidirectional。调用点与降级说明（AUDIO.md 的「缺少 API Key 时不要假装合成成功」）一致。
[ok] 是否存在反自动化绕过或安全降级（红档排除） — record-cdp-screencast.mjs 的 puppeteer.launch 只有 headless: true 与 args=[--autoplay-policy=no-user-gesture-required, --hide-scrollbars, --window-size=…]，无 AutomationControlled、无 remote-allow-origins=*、无 webdriver 伪装；全目录 grep --no-verify / --sandbox / dangerouslyDisableSandbox 零命中。CDP 只连本机回环页面（默认 http://127.0.0.1:5175/?auto=1&record=1&autostart=1）。
[discrepancy] 「默认不停下问」会不会导致未经同意的付费合成 — ［判定：设计取舍，非缺陷］SKILL.md 明写 '**默认不要停下来问是否合成音频**。Phase 2 全部 HTML 已完成且验证通过后，agent 直接进入本阶段。'，并列出四种收口例外（用户说不要/鉴权缺失/换本地 TTS）。即：默认路径会消耗 TTS 账号额度且不再二次确认——属有意的流程设计（音频是一镜到底前提），但使用者应在开始前知情并配好额度与凭证。
[ok] 脚手架是否真的安装 puppeteer-core（录屏能力来源） — scripts/scaffold.sh 内含 `npm install >/dev/null 2>&1` 与 `npm install --save-dev tsx puppeteer-core >/dev/null 2>&1`，随后跑 `npx tsc --noEmit` 自检；即录屏/字幕脚本的依赖由脚手架负责安装，而非假定全局存在。
[unlocatable] 并行章节开发（模式 C）带来的风格与质量分散 — 文档声称主题 token 兜底、章节 CSS 物理隔离、风格不一致等于「人手写视频的呼吸感」；但 pin 仓库内没有多章并行产出的成品或验收记录可用于验证该主张，本次只读侦查不运行生成，故仅作「文档声明」记录，不当作已核事实。
[ok] 「?auto=1 一镜到底」的机制描述是否与代码一致 — AUDIO.md 与 build-master-audio.mjs 的描述一致：分段合成后拼成 master.mp3 + timeline.json，运行时 Auto 模式优先播 master 音轨并按 timeline 驱动 HTML 节点；RECORDING.md 的 CDP 路径以 --audio=<normalized master> 复用同一条母版，避免分段交接造成尾字截断。

6結論

「Web動画」を再現性のあるエンジニアリングパイプラインとして確立：スキャフォールディング、章開発ガイド、音声合成、CDP録画、字幕焼き込みまで付属スクリプトで完結

厳格な単一信頼源（SSOT）原則：narrations.tsがステップ数と音声を一元管理し、5つの関連成果物における不整合を排除

抑制的かつ明確な人間介入ポイント：Checkpoint Planでの4項目一括整合確認＋第1章の必須検収＋開発モードの柔軟な切り替え

反AI感と視覚的基準を検収項目に明記：紫ピンクのグラデーション、角丸カラーボーダー、無機質なイラスト、絵文字をチェック対象とし、テキストのみの章を禁止して各章にリッチなHTMLメインビジュアルを義務付け

実践的で即利用可能な音声デフォルト値（Volcengine/Doubao Liu Fei 2.0、speech_rate 20）を提供し、ローカルMeloTTSやMiniMaxの代替案および「APIキー欠落時のフェイルセーフ」処理を完備

録画環境において制御可能で低コストな選択肢を提供（screencliの使用を明確に排除）し、依存関係はグローバル前提ではなくスキャフォールディング時にインストール

最適な用途： 記事やナレーション原稿（またはコマ割り済みコミック画像）を所持し、「動画のように見える」16:9の解説プレゼンテーション（動的スライド、技術チュートリアル/トークデモの録画、モーションコミックHTML版など）を作成したい方に最適です。Node/npm、ローカルChrome、ffmpegの導入環境が必要で、デフォルトのVolcengine/Doubao TTS利用（またはローカルMeloTTSへの切り替え）に同意できる環境を前提とします。原稿執筆から完成動画出力までの一貫したパイプラインを提供します。

不向きな用途： 以下には適しません：① Webプレゼンテーションではなく、動画編集ソフトによる本格的な映像編集を求めるプロジェクト（本スキルが出力するのは録画可能なWebページ＋音声です）；② 原稿を外部TTSに送信できず、ローカルTTS環境の構築も望まない環境；③ 人手による微調整を行わずに全章の視覚的統一を厳密に求めるケース（並列モードではスタイルに差異が生じます）；④ ドキュメント作成の手間をかけず即座に出力だけを求めるユーザー（Checkpoint、第1章検収、各章のセルフチェックが必須プロセスです）；⑤ macOS以外でChromeパスの変更を希望しない環境（--chromeでの上書き設定が必要）。

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload web-video-presentation.tar.gz

sha256: 6c6b9cedf0142114…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit f2c70b812b.