Merge origin/main into fix/promo-text-and-gallery-restructure

main gained the guided-creation workflow (PR #1) and the Japanese README (PR #2) while this branch reworked the gallery, so both sides touched app.js, styles.css, translations.js, sync-from-cards.py and SKILL.md. Resolutions - sync-from-cards.py: keep main's per-style STYLE_STATUS pass inside the card loop and this branch's stats recompute after it - app.js / styles.css / translations.js: keep main's implementationStatus feature, but re-home the badge. It used to live inside .current-style, which this branch removed; putting it in the card body made the card 29px taller than its row-mates whenever a reference-only style was selected, so it now overlays the demo's top-left where it costs no height and clears both the fullscreen button and the chip row. Drop main's durationText and the play/pause labels: the duration row and per-card pause button are gone - SKILL.md / pipeline.md / demos/README.md: take main's rewritten workflow text wholesale; this branch had only touched counts there - library.json is generated, so it was rebuilt from the 104 on-disk cards. main still carried 106 because it lacks this branch's retire commit (1149027), which dropped hires-rasterize-3d-text and scene-locked-title Also bring README_JA.md in line with the other two: 106/162 to 104/161 and the emoji heading swapped for the logo lockup. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-14 20:16:35 +08:00 · 2026-07-26 17:38:46 +08:00
parent 8996eaa3d9 0c84c4b0b0
commit df91782153
23 changed files with 838 additions and 197 deletions
@@ -2,6 +2,7 @@ node_modules/
 out/qa/
 .DS_Store
 .synapse/
+__pycache__/
 CLAUDE.md
 AGENT.md
 PRODUCT.md
@@ -14,7 +14,7 @@

 **An agent skill for crafting cinematic product videos: 104 shot recipe cards · 161 styles · 161 motion previews · a production-ready template**

-[English](README.md) | [中文](README_CN.md)
+[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md)

 </div>

@@ -14,7 +14,7 @@

 **让 agent 帮你制作电影感产品视频的 skill：104 张镜头配方卡 · 161 个样式 · 161 条动态样片 · 已验收成片模板**

-[English](README.md) | [中文](README_CN.md)
+[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md)

 </div>

@@ -0,0 +1,178 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./assets/brand/logo-mark-reverse.svg">
+  <source media="(prefers-color-scheme: light)" srcset="./assets/brand/logo-mark.svg">
+  <img alt="video-shotcraft logo" src="./assets/brand/logo-mark.svg" width="112" height="112">
+</picture>
+
+<h1>video-shotcraft</h1>
+
+[![GitHub stars](https://img.shields.io/github/stars/Vincentwei1021/video-shotcraft)](https://github.com/Vincentwei1021/video-shotcraft/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/Vincentwei1021/video-shotcraft)](https://github.com/Vincentwei1021/video-shotcraft/network/members)
+[![Gallery](https://img.shields.io/badge/Gallery-live%20previews-d3923c)](https://vincentwei1021.github.io/video-shotcraft/)
+
+**映画のような製品動画を制作するためのエージェントスキル：104 種類のショットレシピカード · 161 種類のスタイル · 161 本のモーションプレビュー · 実制作に対応したテンプレート**
+
+[English](README.md) | [中文](README_CN.md) | [日本語](README_JA.md)
+
+</div>
+
+**video-shotcraft** は、Claude Code や Codex をモーションデザインスタジオに
+変える AI エージェントスキルです。製品を指定するだけで、ストーリーボード、アニメーション、
+サウンドデザインを行い、[Remotion](https://www.remotion.dev/) を使って映画のようなプロモーション、
+マーケティング、ローンチ、デモ動画を制作します。実際のページキャプチャ、2.5D カメラワーク、
+ビートに同期したカット、映画品質の SFX も含まれます。
+
+## 🎬 ショーケース
+
+以下の 38 秒間の Gallery 紹介動画も、このスキルで制作されました。
+ストーリーボード、ショットの実装、サウンドデザインのすべてを、エージェントが
+ツールキットの手法に沿って行っています。
+
+https://github.com/user-attachments/assets/cba2df8a-4b2e-4247-bace-d0b1dea9c2bd
+
+▶️ [YouTube で HD 版を見る](https://youtu.be/gcVvRM_P3SM)
+
+> すべてのショットカードとモーションプレビューをオンラインで閲覧：**[Gallery](https://vincentwei1021.github.io/video-shotcraft/)**
+> — 検索、絞り込み、バリエーションの切り替え、選択したショットカード名のコピーが可能です。
+
+## 🚀 クイックスタート
+
+**最も簡単な方法は、リポジトリのリンクをエージェントに渡すことです。**
+Claude Code、Codex、または同様のエージェントで、次のように伝えます。
+
+```text
+Install this skill for me: https://github.com/Vincentwei1021/video-shotcraft
+```
+
+エージェントがリポジトリをクローンし、スキルディレクトリにリンクします。または、
+[skills](https://skills.sh/) CLI を使うか、手動でインストールします。
+
+```bash
+npx skills add Vincentwei1021/video-shotcraft
+```
+
+```bash
+git clone https://github.com/Vincentwei1021/video-shotcraft.git
+cd video-shotcraft
+ln -s "$(pwd)" ~/.claude/skills/video-shotcraft   # Claude Code
+# or
+ln -s "$(pwd)" ~/.codex/skills/video-shotcraft    # Codex
+```
+
+インストール後は、次のように依頼できます。
+
+```text
+Use video-shotcraft to create a promo for my desktop product.
+Use the deck-deal-flyin and row-embed shot cards to present this feature.
+Design a product close-up inspired by spotlight-hero-card.
+```
+
+ショットカードを指定しない場合、スキルは最初に内蔵の動画テンプレートを
+紹介し、それを使うか確認します。作業を始める前に
+[Gallery](https://vincentwei1021.github.io/video-shotcraft/) でショットを選ぶこともできます。
+
+## 📼 動画テンプレート：Ink Press
+
+スキルには、検証済みの完全なプロモーションテンプレート **Ink Press** が付属します。
+長さ 36.2 秒、1920×1080、30fps、紙・インク・アンバー調の 10 ショットで構成され、2.5D の
+実ページカメラワーク、タイトルカード、トランジション、細部まで調整された映画品質の
+SFX が含まれます。
+
+https://github.com/user-attachments/assets/4cf5af51-98f3-4af2-8ab2-7267f470513d
+
+▶️ [YouTube で HD 版を見る](https://youtu.be/iShab28B_ak)
+
+使用するには、エージェントに次のように伝えるだけです。
+
+```text
+Use video-shotcraft to make a promo for my product with the Ink Press template.
+```
+
+エージェントが製品のスクリーンショット、コピー、ブランド要素に差し替えて
+同じ品質を再現します。完成した動画を得るための、最も速く確実な方法です。
+
+> 今後、さらに多くのテンプレートが追加される予定です。
+
+## 📦 収録内容
+
+| 内容 | 説明 |
+| --- | --- |
+| 104 種類のショットレシピカード | 目的、エネルギー、推奨時間、パラメータ、実装上の注意点、既知の落とし穴 |
+| 161 本のモーションプレビュー | 161 種類のスタイルを網羅し、オンライン Gallery で検索と絞り込みが可能 |
+| Remotion 実装 | 各カードの実際のイージングとタイミングパラメータを含む、調整済みの TSX デモ |
+| 完全な動画テンプレート | 検証済みの 36.2 秒、1920×1080、30fps、10 ショットの製品プロモーション |
+| コンポーネントとアセット | 2.5D ページカメラ、キャプション、フラッシュカット、数字ロール、SFX、キャプチャスクリプト |
+| 制作手法 | キャプチャ、ビジュアルディレクション、ストーリーボード、サウンドデザイン、ビート同期、最終 QA |
+
+このツールキットは主に Web およびデスクトップ製品のプロモーションを対象としていますが、
+各ショットカードは機能デモ、ブランド映像、ローンチ動画、
+その他のモーション制作にも利用できます。
+
+## 🗂 リポジトリ構成
+
+```text
+video-shotcraft/
+├── SKILL.md                 # Agent entry point and core production rules
+├── references/
+│   ├── pipeline.md          # End-to-end production workflow
+│   ├── shots/               # 104 shot recipe cards
+│   ├── sequences/           # Reusable full-video structures and sequence patterns
+│   ├── aesthetic-rules.md   # Visual QA criteria
+│   ├── music-beat-sync.md   # BGM analysis and beat-sync methodology
+│   └── sound-design.md      # Sound-design guidance and examples
+├── demos/                   # Remotion reference implementations for shot cards
+├── gallery/                 # Static motion-preview Gallery
+├── template/                # Runnable complete video template
+└── assets/
+    ├── lib/                 # Reusable Remotion components
+    ├── scripts/             # Page-asset capture scripts
+    └── audio/               # SFX and attribution details
+```
+
+完全なワークフローと実装要件については、[SKILL.md](SKILL.md)、
+[制作パイプライン](references/pipeline.md)、および
+[ビジュアル QA 基準](references/aesthetic-rules.md)を参照してください。
+
+## 🔊 音声とアセットに関する注意事項
+
+`assets/audio/` にある音声ファイルは、それぞれのライセンス条件に従って使用できます。
+出典とライセンスの詳細については、[ATTRIBUTION.md](assets/audio/ATTRIBUTION.md)を参照してください。
+
+テンプレートに含まれる製品スクリーンショットはデモ用アセットです。公開前に
+対象製品のスクリーンショットへ差し替え、製品、顧客、または個人に関するデータを
+匿名化する必要があるか確認してください。
+
+## 🙏 謝辞
+
+このライブラリの多くのショットレシピは、優れた公式製品動画のモーション表現を
+研究してまとめたものです。対象には **ClickUp、Perplexity、Slack、Notion、
+Figma、Framer、Bear、Raycast、Pitch、Miro、Superhuman、Loom** のプロモーションが
+含まれます。カードには、ゼロから再実装したモーション技法
+（タイミング、イージング、振り付け）を記載しています。これらの動画の映像、アートワーク、
+ブランドアセットはリポジトリに含まれません。すべての商標は各所有者に帰属し、
+各社は本プロジェクトと提携しておらず、また本プロジェクトを推奨していません。
+
+特に以下のプロジェクトとコミュニティに感謝します。
+
+- **[Remotion](https://www.remotion.dev/)** — すべてのデモとテンプレートを支える
+  React ベースの動画フレームワークです。Remotion には独自の
+  [ライセンス](https://github.com/remotion-dev/remotion/blob/main/LICENSE.md)
+  がある点に注意してください（個人と小規模チームは無料、企業は有料ライセンスが必要な場合があります）。
+- **[Mixkit](https://mixkit.co/)** — 無料の商用ライセンスで収録されている
+  SFX と音楽アセットの提供元です。
+- 複数のカードに影響を与えた、ゲームフィールとアニメーションのコミュニティが公開する原則
+  （Vlambeer のスクリーンシェイクに関する講演、古典的なアニメーションのタイミングなど）。
+- **Claude Code** — このライブラリ自体も、スキルが教えるものと同じワークフローを使い、
+  AI コーディングエージェントによって構築、反復改善、QA されました。
+
+## ⭐ Star 履歴
+
+<a href="https://www.star-history.com/?repos=Vincentwei1021%2Fvideo-shotcraft&type=date&legend=top-left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/video-shotcraft&type=date&theme=dark&legend=top-left&sealed_token=DQ8_yn0k8in6tP80CRd9Ghuk1fcdEW7poFh9ticGB3wMNO-E_i6g51sUiQWCAQYP0u0bjRweuIfGoRS8FnrIz86oFp1lcl5zu2vrEJrQOoNvwdUSwmm8XNPkAiln1o-EBAX0uU8k6ReIlSRufGLqpoxsWshMSZ9mmok6ox5XXIUO77b7zOgp2yRIH6yR" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Vincentwei1021/video-shotcraft&type=date&legend=top-left&sealed_token=DQ8_yn0k8in6tP80CRd9Ghuk1fcdEW7poFh9ticGB3wMNO-E_i6g51sUiQWCAQYP0u0bjRweuIfGoRS8FnrIz86oFp1lcl5zu2vrEJrQOoNvwdUSwmm8XNPkAiln1o-EBAX0uU8k6ReIlSRufGLqpoxsWshMSZ9mmok6ox5XXIUO77b7zOgp2yRIH6yR" />
+    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Vincentwei1021/video-shotcraft&type=date&legend=top-left&sealed_token=DQ8_yn0k8in6tP80CRd9Ghuk1fcdEW7poFh9ticGB3wMNO-E_i6g51sUiQWCAQYP0u0bjRweuIfGoRS8FnrIz86oFp1lcl5zu2vrEJrQOoNvwdUSwmm8XNPkAiln1o-EBAX0uU8k6ReIlSRufGLqpoxsWshMSZ9mmok6ox5XXIUO77b7zOgp2yRIH6yR" />
+  </picture>
+</a>
@@ -1,6 +1,6 @@
 ---
 name: video-shotcraft
-description: 用镜头配方卡 + 已验收模板 + 代码/音频资产制作电影感产品视频（Remotion + 真实页面截图 + 2.5D 运镜 + 节奏卡点 + 声音设计）。当用户要求"用 video-shotcraft 做视频/宣传片"、点名 Ink Press 模板或要求复刻模板片效果，或要用镜头卡做单个动效镜头时使用。
+description: 用镜头配方卡 + 已验收模板 + 代码/音频资产制作电影感产品视频（Remotion + 真实页面截图 + 2.5D 运镜 + 节奏卡点 + 声音设计）。当用户要求"用 video-shotcraft 做视频/宣传片"、把前端项目/网页做成产品视频、点名 Ink Press 模板或要求复刻模板片效果，或要用镜头卡做单个动效镜头时使用。
 ---

 # video-shotcraft：电影感产品视频制作
@@ -10,63 +10,84 @@ description: 用镜头配方卡 + 已验收模板 + 代码/音频资产制作电
 当前 focus 是 web/桌面产品宣传片，但镜头卡本身是通用动效词汇——
 也可以单独抽卡做任意视频里的单个镜头。

-## 调用时先介绍模板并确认路线
+## 调用时先判断模式

-每次调用此 skill，**在开始任何素材采集、分镜或实现前**，先向用户说明：
+完整宣传片有三种互不合并的模式。在开始素材采集、分镜或实现前，先判断用户
+是否已经明确选择；已经选择时直接执行，不重复询问，也不要改成另一种模式。

- 当前可直接使用 `template/` 中一支**已验收的 36.2 秒产品宣传片模板
-  Ink Press（墨压）**：1920×1080、30fps、纸墨琥珀风格，含 10 个完整镜头、
-  2.5D 真实页面运镜、字卡、转场和已配好的电影感 SFX；替换目标产品的截图、
-  文案和品牌信息即可适配。
- 采用模板是最快、质量最有保障的路径；若用户要全新视觉语言，则走自由创作流程。
+1. **直接使用模板**：保持 Ink Press 原有替换流程。读 `template/TEMPLATE.md`，
+   按既有镜头结构替换目标产品的截图、文案和品牌信息。
+2. **自主自由创作**：读 `references/pipeline.md`。Agent 根据用户已有要求和项目
+   内容，自主决定视觉方向、镜头映射、分镜、素材和音频，连续推进到成片；不在
+   产品简报、styleframe、镜头映射或分镜阶段暂停等待用户确认。
+3. **共同创作**：读 `references/guided-free-creation.md`。Agent 先提出有依据的
+   判断和方案，由用户依次确认产品简报、需求决策、视觉方向、镜头映射和最终
+   分镜；分镜放行后再进入 `references/pipeline.md` 的最终素材采集与制作阶段。

-然后明确询问：**“要使用这支现成模板来制作这支视频吗？”**
+用户提供了项目路径、网址、录屏或页面截图但尚未选模式时，先做一次**最小、
+只读的产品检查**：了解产品定位、主要功能、页面视觉、可展示状态和素材风险；
+不修改业务项目、不采集敏感数据、不写视频代码。检查后给出三种模式，并说明：
+
+- Ink Press 是否适合该产品、适合与不适合的具体依据；
+- 自主自由创作与共同创作各自是否适合、预计会保留哪些产品视觉线索；
+- Agent 推荐哪一种模式及其依据和取舍。
+
+然后明确询问：**“根据上面的产品检查，我推荐使用 ×× 模式。要按这个模式继续吗？”**
 同时告知用户：可前往 https://vincentwei1021.github.io/video-shotcraft/
 浏览动态样片，并挑选希望在视频中使用的动效镜头。

- 用户确认使用：先完整阅读 `template/TEMPLATE.md`，再按模板路线执行。
- 用户明确不使用：按 `references/pipeline.md` 的阶段 0 继续，走自由创作或单镜头路线。
- 用户尚未决定：停在此处等待选择；不要默认套用模板，也不要开始制作。
+用户尚未提供可检查的项目或页面时，简要介绍三种模式再询问；不要仅因 Ink Press
+是现成模板就默认推荐它。

-**例外一：用户已点名 Ink Press 模板时，视为模板路线已选定。**
-例如"用 Ink Press 模板给我的产品做宣传片"。此时不要再询问，
-直接完整阅读 `template/TEMPLATE.md` 按模板路线执行。
+- 用户选择模板：完整阅读 `template/TEMPLATE.md`，按原模板流程执行。
+- 用户选择自主自由创作：完整阅读 `references/pipeline.md`，Agent 自主推进，不逐阶段等待确认。
+- 用户选择共同创作：完整阅读 `references/guided-free-creation.md`，按其中的确认节点协作。
+- 用户尚未决定：停在此处等待选择；不要默认替用户选择，也不要开始制作。

-**例外二：用户已明确指定要使用或参考某些镜头卡时，视为路线已经选定。**
+**例外一：用户已点名 Ink Press 模板时，视为模板模式已选定。**
+例如“用 Ink Press 模板给我的产品做宣传片”。此时不要再询问，直接完整阅读
+`template/TEMPLATE.md` 按模板路线执行。
+
+**例外二：用户已明确指定要使用或参考某些镜头卡时，镜头约束已经选定。**
 例如“用 `deck-deal-flyin` 和 `row-embed` 做这支视频”或“参考
 `spotlight-hero-card` 的效果”。此时不要介绍模板、也不要询问是否使用模板；
-直接确认指定的镜头卡，完整阅读每张卡及其 `demos/<类别>/<卡名>/` 实现源码后执行。
+按 Gallery 名称解析规则确认指定镜头，完整阅读每张卡，并按卡片的“参考实现”
+定位准确 demo 源码。单镜头可在目标素材明确后执行；完整宣传片若尚未说明采用
+自主自由创作还是共同创作，只询问这两种模式，指定镜头作为后续制作约束，不自动
+等同于共同创作。

-## 三种用法
+## 四种用法

 1. **完整宣传片（模板路线）**：想要和模板片高度相似的效果 →
-   读 `template/TEMPLATE.md`，按"换产品复现指南"替换素材逐镜头适配。
-   最快且质量有底。
-2. **完整宣传片（自由创作）**：新风格 → 按 `references/pipeline.md`
-   六阶段走（阶段 0 开工三问起步）。
-3. **单镜头/单动效**：从 `references/shots/<类别>/` 选卡（或让用户在
-   `gallery/` 画廊里挑），读卡全文 + `demos/<类别>/<卡名>/` 实现源码，
+   读 `template/TEMPLATE.md`，按“换产品复现指南”替换素材逐镜头适配。
+2. **完整宣传片（自主自由创作）**：要新风格并授权 Agent 自主决定 → 读
+   `references/pipeline.md`，从产品理解连续推进到终检，中途不逐阶段等待确认。
+3. **完整宣传片（共同创作）**：要参与关键决策 → 读
+   `references/guided-free-creation.md`，确认产品简报、需求决策、视觉方向、
+   镜头映射和最终分镜；放行后从流水线的最终素材采集继续。
+4. **单镜头/单动效**：从 `references/shots/` 选卡（或让用户在
+   `gallery/` 画廊里挑），读卡全文并按“参考实现”定位准确 demo 源码，
   适配到目标素材。

-## 镜头卡按功能类别归档
+## 自主自由创作与共同创作的边界

-`references/shots/` 与 `demos/` 均按功能分十个类别目录，找镜头先定类别再进目录：
+**自主自由创作**把创意和工程决策交给 Agent。Agent 从项目内容动态推导产品重点、
+视觉方向、镜头映射、分镜、素材处理与音频方案，记录关键判断后直接执行；除非缺少
+无法安全推断的必要输入，否则不提问、不逐阶段暂停，也不要求用户确认中间产物。
+用户已有的明确要求始终是约束，不能被 Agent 的默认选择覆盖。

-| 目录 | 类别 | 管什么 |
-|------|------|--------|
-| `opening/` | 开场与品牌 | 片头定场、品牌字标/主视觉登场 |
-| `typography/` | 文字与字卡 | 大标题/标语/章节字卡的入场与节奏 |
-| `ui-entrance/` | 界面登场与陈列 | UI/卡片墙/列表的显形、涌入、体量感陈列 |
-| `camera/` | 运镜与空间 | 2.5D/3D 相机语言：推拉摇移、俯仰、贴面飞掠 |
-| `data/` | 数据与指标 | 图表、数字揭晓、KPI/里程碑叙事 |
-| `interaction/` | 交互与功能演示 | 操作链路、AI 响应、输入/切换等功能镜头 |
-| `transition/` | 转场 | 两镜衔接的全部手法（技法卡集中在此） |
-| `rhythm/` | 节奏与蒙太奇 | 卡点、切法、段落呼吸形状、速度控制 |
-| `effects/` | 光效与强调 | 光扫/霓虹/命中反馈等强调性包装层 |
-| `outro/` | 收尾 | 片尾收束、全家福、UI→品牌变形 |
+**共同创作**才使用逐阶段确认。默认读 `references/guided-free-creation.md`，每轮只问
+1–3 个最能减少返工的问题，并在产品简报、需求决策、视觉方向、镜头映射和最终分镜
+处暂停等待用户确认。用户确认业务与创意方向；Agent 自主完成采集方式、实现参数、
+SFX 钉帧、Remotion 工程、渲染和技术 QA。

-同一张卡只归一类；跨界卡按"最常被用来做什么"归档（如 speed-ramp-freeze
-在 rhythm/）。分镜选卡时按叙事槽位逐类别扫 frontmatter 即可。
+共同创作中，用户明确说“你全权决定”或“跳过确认直接做”时，切换为自主自由创作
+并记录这一选择；不要一边声称自主推进，一边继续要求逐阶段确认。
+
+功能到镜头的映射只是“选用哪些运动语法”，不是完整分镜。共同创作确认映射后，
+Agent 必须继续给出镜头顺序、时长、具体画面、页面状态、素材来源、字幕、转场和
+SFX；只有完整分镜确认后才进入最终素材采集。用户从 Gallery 复制镜头名时，只需
+提供卡名或“卡名 · 样式名”，Agent 负责读取本地配方卡和 demo 源码。

 ## 核心理念

@@ -74,8 +95,9 @@ description: 用镜头配方卡 + 已验收模板 + 代码/音频资产制作电
   明确性是硬门槛。** 表现产品真实页面时第一步就起本地 dev server，
   用无头浏览器截全页 2x 纹理 + 元素级抠图 + layout.json 坐标表。
   非复刻场景（抽象开场/品牌段/独立展示组件）允许手搓 UI，但达不到
-   出版级质感或观众看不懂它表达什么，就回截图路线。页面数据默认
-   可用现成数据；是否脱敏在素材确认时问用户。
+   出版级质感或观众看不懂它表达什么，就回截图路线。页面数据按风险处理：
+   公开演示数据只有在产品简报明确确认后才可保留；客户、个人、内部、密钥、
+   实时或其他敏感数据必须用虚构或脱敏内容，且在采集前冻结。

 2. **整支视频的视觉语言必须从产品自身生长，不能另造一套不相干的
   “宣传片皮肤”。** 做 styleframe 前，先从产品/网站的设计系统、源码或
@@ -85,7 +107,8 @@ description: 用镜头配方卡 + 已验收模板 + 代码/音频资产制作电
   转场、粒子、光效和其他动效配色都必须复用或克制扩展这套 tokens，
   同时匹配产品的调性、品味和质感。走模板或镜头卡路线时，只继承其
   镜头结构、运动语法、节奏和已调参数；字体、排版、配色与材质必须按
-   目标产品重新蒙皮。若因叙事需要偏离产品视觉，先说明理由并让用户确认。
+   目标产品重新蒙皮。若因叙事需要偏离产品视觉，共同创作先说明理由并让用户
+   确认；自主自由创作把理由与取舍写入设计 spec 后继续。

 3. **电影感来自运镜、光影、节奏与声音的配合，不来自炫技动画。**
   被反复认可的是：单主角完整动作弧（聚光→推近→悬浮→归位）、
@@ -104,45 +127,53 @@ description: 用镜头配方卡 + 已验收模板 + 代码/音频资产制作电
   BPM/相位 + 带通找鼓点重音），时间线用拍号 `beatF(n)` 写，渲后从
   成片抽音轨回测切点误差 ≤3f。方法论见 `references/music-beat-sync.md`。

-6. **用镜头卡动效必须先读它的 demo 实现代码。** 配方卡给的是语义和
-   参数表，`demos/<类别>/<卡名>/` 里的源码才是调校过的参数真相（缓动、时值
+6. **用镜头卡动效必须先解析 Gallery 索引并读准确的 demo 实现代码。**
+   先用 `gallery/api/library.json` 校验卡名与 `style-key`，再按卡片文档的
+   “参考实现”定位具体 TSX。配方卡给的是语义和参数表，准确的 demo 源码
+   才是调校过的参数真相（缓动、时值
   配比、摘罩时机、已知坑的规避写法）。允许适配性改动，但卡上
   "已知坑/命门"标注的参数不得降档——质量标准只升不降。凭卡名和
   理解新写＝放弃全部调校积累。

-7. **廉价确认物前置：素材→styleframe→分镜逐级确认，方向问题不进
-   逐镜头阶段。** 一个纯 HTML/CSS 对比页 + 一张截图就能锁定全片
-   色板/字体/光感；分镜表与设计 spec 同文档一次确认。确认物越廉价、
-   越早，返工越便宜。
+7. **共同创作把廉价确认物前置，自主自由创作把同样的判断留作执行记录。**
+   产品简报→需求到执行决策表→文字方向→styleframe→镜头映射→分镜的顺序不变；
+   共同创作逐级交给用户确认，自主自由创作由 Agent 自主选定并连续推进。两种模式
+   都不应在方向未定时进入逐镜头实现。

-8. **验收贯穿全程 + 交付前独立审查。** 阶段 4 起每个镜头用
+8. **验收贯穿全程 + 交付前独立审查。** 阶段 5 起每个镜头用
   `npx remotion still` 出静帧自检、每轮修改后整片渲染 + ffmpeg
-   抽帧回看；交付前必须派一个干净上下文的 subagent 做独立视觉审查
-   （只给成片/关键帧/审美准则/分镜表，逐条出带帧号证据的报告）——
-   制作者对自己的产出有确认偏差，首检永远不能交给用户。
+   抽帧回看；交付前必须派一个干净上下文的 subagent 做独立终检。审查输入
+   包含成片、关键帧、产品简报、需求到执行决策表、当前模式确认或记录的视觉方向/styleframe、功能到镜头映射、
+   Gallery 卡名/变体、准确 demo TSX、Gallery 参考样片/抽帧、最终分镜、选中的镜头卡和
+   审美准则；按 `references/final-review.md`
+   同时检查方案一致性、功能完整性、镜头还原度、视觉/音频技术质量和数据安全，
+   逐条出带帧号证据的报告。制作者对自己的产出有确认偏差，首检永远不能交给用户。

 9. **确定性渲染**：禁 `Date.now()`/`Math.random()`，一切伪随机固定
   种子（mulberry32/哈希，seed 从 index 派生），逐帧可复现。

 ## 工作流

-按 `references/pipeline.md` 六阶段执行（阶段 0 开工三问：音乐选好了吗 /
-用模板还是自由创作 / 数据合规口径）。阶段 3（分镜）时扫
-`references/shots/` 各类别目录的卡片 frontmatter 按能量曲线选镜头；阶段 4–6 持续
-对照 `references/aesthetic-rules.md` 自检；阶段 5 读
+自主自由创作按 `references/pipeline.md` 从阶段 0 连续执行，不逐阶段等待用户确认。
+共同创作先按 `references/guided-free-creation.md` 完成阶段 0–3 的产品理解、视觉方向、
+镜头映射和分镜确认，再从流水线阶段 4 的最终素材采集继续，不得重复提问或重新设计。
+阶段 2–3 扫 `references/shots/` 各卡 frontmatter 按能量曲线选镜头；阶段 5–7 持续
+对照 `references/aesthetic-rules.md` 自检；阶段 6 读
 `references/sound-design.md`；卡点片全程贴 `references/music-beat-sync.md`。

 ## 何时读哪个文件

 | 时机 | 读 |
 |------|----|
-| 项目启动 | pipeline.md（阶段 0 三问） |
+| 项目启动且模式未定 | 最小只读检查，然后提供三种完整宣传片模式并推荐 |
+| 自主自由创作 | pipeline.md（Agent 自主完成阶段 0–7，不逐阶段等待确认） |
+| 共同创作 | guided-free-creation.md（确认阶段 0–3），再从 pipeline.md 阶段 4 继续 |
 | 用户已选 BGM | music-beat-sync.md（先分析再分镜） |
 | 走模板路线 | template/TEMPLATE.md 全文 |
-| 分镜设计 | sequences/ 桥段模板（全片骨架先填空）；shots/ 各类别目录 frontmatter；选中的卡读全文 |
-| 逐镜头实现 | 该镜头卡全文 + demos/<类别>/<卡名>/ 实现源码全文 + assets/lib/ 对应组件 |
+| 分镜设计 | sequences/ 桥段模板（全片骨架先填空）；shots/ 全部 frontmatter；选中的卡读全文 |
+| 逐镜头实现 | 该镜头卡全文 + 按“参考实现”定位的准确 demo 源码全文 + assets/lib/ 对应组件 |
 | 声音设计 | sound-design.md + assets/audio/ |
-| 验收 | aesthetic-rules.md 全文过 checklist（独立 subagent 执行） |
+| 验收 | final-review.md + aesthetic-rules.md 全文过 checklist（独立 subagent 执行） |

 ## 资产使用方式

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Video Shotcraft"
+  short_description: "用真实页面与镜头卡制作可验收的电影感产品宣传片工作流"
+  default_prompt: "使用 $video-shotcraft，把我的前端项目制作成产品宣传片。"
@@ -1,8 +1,8 @@
 # demos/ — 镜头卡参考实现源码

-每个 `demos/<类别>/<卡名>/` 目录对应 `references/shots/<类别>/<卡名>.md` 的"参考实现"
-（十个功能类别目录说明见 SKILL.md）。
-这些是调校过的 Remotion 组件——**用卡先读这里的源码**（SKILL.md 理念 5）。
+多数镜头卡会在“参考实现”中指向本目录；必须先读卡片，再按其明确路径定位准确的
+demo 文件，不能只凭卡名假设目录结构。这里的组件是调校过的 Remotion 实现——
+**用卡先读准确源码**（SKILL.md 理念 5）。

 使用方式：copy 需要的 .tsx 进你的 Remotion 项目（30fps / 1920×1080），
 注册成 Composition 即可跑。两类共享依赖：
@@ -84,6 +84,11 @@ const cardDescription = (card) => state.language === 'zh'
  ? card.summary || card.intention
  : translations.cardsEn[card.name] || card.name.split('-').join(' ');

+function implementationStatusLabel(style) {
+  if (style.implementationStatus === 'reference-only') return text('referenceOnly');
+  if (style.implementationStatus === 'missing-preview') return text('missingPreview');
+  return '';
+}


 function resolveTheme(choice = state.theme) {
@@ -129,12 +134,13 @@ function applyLanguage() {

 function mediaMarkup(style, cardIndex) {
  const title = escapeHtml(styleName(style));
+  const status = implementationStatusLabel(style);
  if (!style.media) {
    return `
      <div class="preview preview-missing">
        <span class="missing-glyph" aria-hidden="true"></span>
-        <p>${escapeHtml(text('noSample'))}</p>
-        <small>${escapeHtml(text('noSampleHint'))}</small>
+        <p>${escapeHtml(status || text('noSample'))}</p>
+        <small>${escapeHtml(status ? text('noSample') : text('noSampleHint'))}</small>
      </div>`;
  }

@@ -174,6 +180,7 @@ function cardMarkup(card, cardIndex) {
  const style = card.styles[selectedIndex];
  const encodedSource = card.source.split('/').map(encodeURIComponent).join('/');
  const sourceUrl = card.sourceUrl || `/source/${encodedSource}`;
+  const status = implementationStatusLabel(style);
  const title = cardName(card);
  const subtitle = state.language === 'zh' ? card.name : '';

@@ -187,6 +194,7 @@ function cardMarkup(card, cardIndex) {
    <article class="shot-card${isSelected ? ' is-selected' : ''}" id="${escapeHtml(card.name)}">
      <div class="card-media">
        ${mediaMarkup(style, cardIndex)}
+        ${status && style.media ? `<p class="implementation-status implementation-status--${escapeHtml(style.implementationStatus)}">${escapeHtml(status)}</p>` : ''}
        ${multiStyle ? styleSelectorMarkup(card, selectedIndex) : ''}
      </div>
      <div class="card-body">
@@ -47,3 +47,6 @@ logo 单瓣（多元素落位拼装）。观众看到的不是"logo 出现了"
 demos/ui-to-brand-morph/
 （IconFlipBloomLogo.tsx / InputMorphsIntoLogo.tsx）
 原片出处：A perplexity-promo 88–91.5s / B slack-promo 40–41s
+
+实现状态：`icon-flip-bloom` 有样片；`input-morph-assemble` 有参考实现但缺少
+Gallery 动态预览，不得声称已按样片对照还原。
@@ -47,3 +47,7 @@ name: wall-reveal-moves
 ## 参考实现
 demos/wall-reveal-moves/
 （BentoLightUp.tsx）
+
+实现状态：`bento-light-up` 可按上述源码适配；`grid-wave-flip` 与
+`wireframe-draw-on` 仅供参考，需要自定义实现。二者不默认推荐，只有用户明确
+点名后才可基于本卡参数和 Gallery 样片制作，并在设计 spec 与终检中记录风险。
@@ -632,6 +632,33 @@ kbd { padding: 0.2rem 0.34rem; border: 1px solid var(--line); border-radius: 5px
  border-color: var(--accent);
 }

+.implementation-status {
+  /* was a grid cell inside .current-style, which this branch removed; now a
+     standalone badge over the demo's bottom-left, where it costs no card
+     height: appearing in the body flow made the card 29px taller than its
+     row-mates whenever a reference-only style was selected. */
+  position: absolute;
+  left: 0.5rem;
+  top: 0.5rem;
+  z-index: 2;
+  /* clears the fullscreen button (top-right) and the chip row (bottom) */
+  max-width: calc(100% - 4rem);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  width: fit-content;
+  padding: 0.16rem 0.4rem;
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  color: var(--muted);
+  background: var(--surface-soft);
+  font-size: 0.7rem;
+  font-style: normal;
+  line-height: 1.25;
+}
+.implementation-status--reference-only { border-color: var(--danger); color: var(--danger); }
+.implementation-status--missing-preview { border-style: dashed; }
+
 .summary {
  display: -webkit-box;
  margin: 0.65rem 0 0;
@@ -13,6 +13,14 @@ SHOTS = ROOT / 'references' / 'shots'
 SOURCE = ROOT / 'gallery' / 'source'
 LIB = ROOT / 'gallery' / 'api' / 'library.json'

+# These variants have a recipe/sample but no reusable demo source. Keep them visible for
+# reference, but do not let the workflow recommend them by default.
+STYLE_STATUS = {
+    ('wall-reveal-moves', 'grid-wave-flip'): 'reference-only',
+    ('wall-reveal-moves', 'wireframe-draw-on'): 'reference-only',
+    ('ui-to-brand-morph', 'input-morph-assemble'): 'missing-preview',
+}
+

 def parse_card(path):
    text = path.read_text(encoding='utf-8')
@@ -81,6 +89,12 @@ def main():
        card['source'] = f"references/shots/{card['category']}/{card['name']}.md"
        if len(card.get('styles', [])) == 1:
            card['styles'][0]['description'] = card['summary']
+        for style in card.get('styles', []):
+            status = STYLE_STATUS.get((card['name'], style['key']))
+            if status:
+                style['implementationStatus'] = status
+            else:
+                style.pop('implementationStatus', None)
    lib['categories'] = CATEGORIES

    # stats are the single source of truth every page and llms.txt reads;
@@ -90,15 +104,10 @@ def main():
    lib['stats']['styleCount'] = len(styles)
    lib['stats']['previewCount'] = sum(1 for style in styles if style.get('media'))
    lib['stats']['mediaCount'] = lib['stats']['previewCount']
-
    LIB.write_text(json.dumps(lib, ensure_ascii=False) + '\n', encoding='utf-8')
    print(f"synced {len(lib['cards'])} cards ({lib['stats']['styleCount']} styles, "
          f"{lib['stats']['previewCount']} previews); missing card files: {missing or 'none'}")

-    # 3. regenerate SEO artifacts (prerendered card list, sitemap.xml, llms.txt)
-    import runpy
-    runpy.run_path(str(Path(__file__).parent / 'build-seo.py'))
-

 if __name__ == '__main__':
    main()
@@ -44,6 +44,8 @@ window.GALLERY_I18N = {
      noSample: '暂未匹配到样片',
      noSampleHint: '加入同名 demo.mp4 后自动出现',
      fullscreen: '全屏播放',
+      referenceOnly: '仅供参考，需要自定义实现',
+      missingPreview: '缺少动态预览',
      scanning: '正在扫描',
      synced: '已自动同步',
      failed: '扫描失败',
@@ -103,6 +105,8 @@ window.GALLERY_I18N = {
      noSample: 'No sample matched',
      noSampleHint: 'Add a matching demo.mp4 to load it automatically',
      fullscreen: 'Play fullscreen',
+      referenceOnly: 'Reference only: custom implementation required',
+      missingPreview: 'Dynamic preview unavailable',
      scanning: 'Scanning',
      synced: 'Auto-synced',
      failed: 'Scan failed',
@@ -4,10 +4,18 @@

 **使用方式**：
 - 每条 = 规则（一句可执行的话）+ 判例（用户原话 / 返工经过）+ 自检问题，三要素缺一不可。
- pipeline.md 阶段 6 验收时**逐条过一遍**，输出自检报告，格式：`编号 ✓` 或 `编号 ✗(位置)`（位置 = 镜头名/帧号）。
+- pipeline.md 阶段 7 验收时**逐条过一遍**，输出自检报告，格式：`编号 ✓` 或 `编号 ✗(位置)`（位置 = 镜头名/帧号）。
 - 准则可以有意识违反（风格需要时），但每次违反必须写进该项目的说明文档（写明违反了哪条、为什么）。
 - 编号体系：R(节奏) / Q(质感·运镜·构图) / S(声音) / C(文案) / P(流程)，编号一经发布不重排，新增条目只追加。

+## 目录
+
+- 节奏（R）
+- 质感、运镜与构图（Q）
+- 声音（S）
+- 文案（C）
+- 流程（P）
+
 ---

 ## 节奏（R）
@@ -31,10 +39,10 @@

 ## 质感·运镜·构图（Q）

-### Q1. 复刻既有页面必须真实截图；手搓 UI 限非复刻场景且质量/表达达标；数据一律虚构，绝不出现客户真名
-规则：凡是表现产品既有页面的镜头，第一步就用无头浏览器截真实页面（整页纹理 + 元素级抠图 + 坐标 json），不手搓仿真贴图复刻；非复刻场景（抽象开场/品牌段/页面上不存在的独立展示组件）允许手搓 UI，但质量（出版级质感，对照 Q10 标准）与表达明确性（观众一眼看懂它是什么）是硬门槛，达不到回截图路线。截图前先给页面注入虚构数据集，客户/项目真名一律替换——"页面结构真实、数据内容虚构"是合规底线，对手搓素材同样生效。
+### Q1. 复刻既有页面必须真实截图；手搓 UI 限非复刻场景且质量/表达达标；数据按风险口径处理
+规则：凡是表现产品既有页面的镜头，第一步就用无头浏览器截真实页面（整页纹理 + 元素级抠图 + 坐标 json），不手搓仿真贴图复刻；非复刻场景（抽象开场/品牌段/页面上不存在的独立展示组件）允许手搓 UI，但质量（出版级质感，对照 Q10 标准）与表达明确性（观众一眼看懂它是什么）是硬门槛，达不到回截图路线。公开演示数据只有在产品简报明确确认后可保留；客户、个人、内部、密钥、实时或其他敏感内容必须先虚构、脱敏或冻结。对手搓素材同样适用该口径。
 判例：用户："我希望的是用真实的页面，然后加入动画"、"不要用真实数据，造一份fake的，不要提到客户名字"。改用真实 dashboard 页面重建，此前一下午手搓纹理复刻版整体作废。修订（2026-07-13 用户裁决）："不一定都要来自真实页面截图，可以手搓UI组件，只是要保证质量和表达的明确性"——判例约束收窄为"不用手搓复刻既有页面"。
-自检：每块 UI 素材：它在复刻既有页面吗？是则必须来自截图；手搓件的质感和表达能过 Q10 级审视吗？源数据里有没有任何真实客户/项目名？
+自检：每块 UI 素材：它在复刻既有页面吗？是则必须来自截图；手搓件的质感和表达能过 Q10 级审视吗？源数据是否符合已确认的数据口径，且不含未授权的客户、个人、内部或密钥信息？

 ### Q2. 3D 透视下 UI 纹理按原生尺寸 rasterize 后缩小使用；文字发糊先查纹理分辨率链路
 规则：3D 场景里的 UI 纹理按显示尺寸的 2–4 倍原生栅格化、在 3D 里向下采样（放大走布局级 CSS zoom 而非 transform scale）；文字模糊先查栅格化路径，别先动相机/DoF。
@@ -0,0 +1,107 @@
+# final-review — 成片独立终检
+
+独立审查 Agent 使用本清单验证“成片是否符合当前创作模式的制作基准”，并结合
+`aesthetic-rules.md` 检查视觉技术质量。审查 Agent 必须处于干净上下文，不参与
+制作；不要给它制作过程中的理由、辩解、修改历史或预期结论。
+
+## 审查输入
+
+- 最新成片 MP4 和每镜头关键帧；
+- 创作模式：直接使用模板、自主自由创作或共同创作；
+- 产品视频简报与必须展示的功能；
+- 需求到执行决策表；
+- 共同创作中用户确认、自主自由创作中 Agent 记录的视觉方向、品牌 tokens、
+  styleframe（或跳过理由）和禁用风格；模板模式则提供原模板结构与实际替换记录；
+- 功能到镜头映射；
+- 用户指定或 Agent 在设计 spec 中记录的 Gallery 卡名与具体变体；
+- `gallery/api/library.json` 中对应卡片与 `style-key` 记录；
+- 卡片文档定位到的准确 demo TSX 源码；
+- 对应 Gallery 参考样片，或从参考样片抽出的关键帧/contact sheet；
+- 最终分镜、字幕、页面状态和 SFX 计划；
+- 选中的 `references/shots/*.md`；
+- `aesthetic-rules.md`；
+- 数据合规口径。
+
+缺少某项输入时标记“无法验证”，不要自行猜测制作基准。索引、卡片文档、
+demo 源码与 Gallery 参考样片互相冲突时，明确报告冲突来源，不自行挑一个当真相。
+
+## 检查项
+
+### P — 产品目标
+
+- P1：产品定位、目标用户和核心卖点是否清楚；
+- P2：成片是否把注意力放在当前模式确认或记录的功能优先级上；
+- P3：是否出现项目不存在、未经确认或容易误导的功能宣称。
+- P4：需求到执行决策表中的执行选择，是否能在分镜、文案、页面状态、音频和素材中
+  找到对应落地；不得用固定的“受众/用途→风格”刻板映射替代项目依据。
+
+### F — 功能完整性
+
+- F1：每个“必须展示的功能”是否至少有一个清楚可辨的镜头；
+- F2：每镜头是否提供新信息，是否存在重复功能或重复 tagline；
+- F3：页面状态是否能让观众理解功能，而不只是装饰性运动。
+
+### V — 视觉方向
+
+- V1：字体、色板、材质、圆角、光感和信息密度是否符合确认或记录的视觉方向；
+- V2：动效速度、过冲、停留和能量曲线是否符合确认或记录的动效性格；
+- V3：是否偏离制作基准，漂移到 Ink Press、赛博霓虹或其他无关风格；
+- V4：禁用的颜色、效果或品牌特征是否被使用。
+
+### S — 镜头卡与 Gallery 变体
+
+- S1：功能映射中的镜头卡是否实际出现在对应镜头；
+- S2：用户点名 `卡名 · 样式名` 时，`style-key`、准确 demo TSX 和 Gallery
+  参考样片是否指向同一变体，成片是否使用该变体；
+- S3：对照准确 demo TSX 与 Gallery 参考样片，是否保留配方卡/demo 的动作
+  语法、关键时值、缓动关系和遮罩时机；
+- S4：是否违反卡片标注的“已知坑/命门”；
+- S5：适配后的产品截图、坐标和品牌 token 是否自然。
+- S6：标为“仅供参考，需要自定义实现”的样式是否得到用户明确点名，并在报告中标注
+  其实现风险；标为“缺少预览”的样式是否避免声称与动态样片一致。
+
+不要求和 Gallery 样片像素级一致。检查的是运动语法和关键参数是否忠实，同时
+允许为目标产品调整截图、坐标、文案、品牌视觉和必要构图。
+
+### B — 分镜一致性
+
+- B1：镜头顺序、时长和功能信息是否符合确认或记录的最终分镜；
+- B2：主动作、页面状态、素材来源、字幕、转场和 SFX 是否一致；
+- B3：品牌字标 hold 是否至少 1 秒，批量动效收尾是否至少静止 0.5 秒；
+- B4：是否在最终分镜放行后，无依据地删除、替换或增加关键镜头。
+
+### D — 数据与素材安全
+
+- D1：是否遵守真实数据、虚构数据或脱敏口径；
+- D2：是否暴露客户、个人、密钥、内部地址或其他敏感信息；
+- D3：表现真实产品页面时是否使用真实截图，而非低质量手搓复刻；
+- D4：截图状态、字体、图片和动态数据是否完整加载。
+- D5：公开演示数据是否有可复核的公开属性；客户、个人、内部、密钥、实时
+  或其他敏感数据是否已虚构、脱敏或冻结。
+
+### A — 音频与节奏
+
+- A1：BGM 是否符合确认或记录的音频方向，音量是否给 SFX 和可选配音留出空间；
+- A2：SFX 是否钉在真实动作关键帧，是否出现明显错位；
+- A3：强节奏音乐的切点误差是否不超过 3 帧；
+- A4：结尾能量峰值和 riser→impact→sparkle 句式是否成立（若分镜采用）。
+
+### Q — 视觉技术质量
+
+完整执行 `aesthetic-rules.md`。至少检查文字锐度、构图、圆角遮罩、3D 纹理
+清晰度、元素落位、相机抖动、转场接缝、光效廉价感、可读时长和确定性渲染。
+
+## 报告格式
+
+每条结论使用编号，并给问题附帧号或截图：
+
+```text
+P1 ✓ 产品定位和核心卖点清楚。
+F2 ✗ 第 340 帧：已确认的知识图谱功能没有出现在成片。
+V3 ✗ 第 420 帧：大面积琥珀纸张材质偏离已确认的深蓝科技方向。
+S2 ✗ 第 515 帧：用户选择 whip-pan，实际实现为 flash-cut。
+Q2 ✗ 第 615 帧：3D 推近后正文文字发糊，见关键帧 f615.png。
+```
+
+最后按严重程度列出必须修复项、建议优化项和无法验证项。不要用没有证据的
+“整体不错”代替逐项检查，也不要为了报告好看而全部标记通过。
@@ -0,0 +1,197 @@
+# guided-free-creation — 共同创作引导流程
+
+共同创作模式用于用户希望参与产品短片的关键业务与创意决策。它把产品简报、
+需求决策、视觉方向、镜头映射和最终分镜交给用户确认，把视频工程细节交给
+Agent 执行。自主自由创作不读本文件，也不使用这里的逐阶段确认节点。
+
+## 目录
+
+- 产品简报与安全素材预检
+- 需求到执行决策表
+- 视觉方向与 styleframe
+- 功能到镜头映射
+- Gallery 镜头名称解析
+- 分镜确认与制作放行
+
+## 1. 产品简报
+
+先只读检查项目，不写视频代码、不修改业务项目、不采集或导出敏感内容。检查技术栈、
+入口、启动命令、页面路由、主要组件、交互状态、API、页面文案、CSS 视觉 token、
+外部依赖和数据风险，并判断哪些功能能通过真实页面状态清楚表达。
+
+输出一张由 Agent 先填写的产品简报表。每一行都必须先给出判断或推荐，
+再写明依据；不要把所有字段原样丢给用户填写。
+
+```text
+当前阶段：产品理解
+
+| 项目 | Agent 的判断或推荐 | 依据 |
+|---|---|---|
+| 项目定位 |  |  |
+| 目标用户 |  |  |
+| 视频用途 |  |  |
+| 核心卖点 |  |  |
+| 必须展示的功能 |  |  |
+| 可用页面/状态 |  |  |
+| 首屏主张 |  |  |
+| 期望时长/画幅/语言 |  |  |
+| 音乐/配音 |  |  |
+| 数据合规口径 |  |  |
+| 视觉线索 |  |  |
+
+需要确认：
+1. 只列出无法从项目或用户已有描述中确定的事项。
+2. 对可以推荐但仍需用户拍板的事项，先写“推荐方案＋依据”，再在此处提问。
+```
+
+填写规则：
+
+- 能从 README、源码、路由、页面状态、文案或 computed styles 确定的，直接填写
+  判断和证据，不再询问；
+- 无法完全确定但可以根据项目合理推荐的，填写动态推荐、推荐依据和需要用户
+  拍板的选项；
+- 完全无法判断的，明确写“无法从当前材料判断”，只把它放到下方问题中；
+- 每轮只追问 1–3 个最影响视频结果的问题；不显示“置信度”字段；
+- 推荐必须来自当前上传项目或页面，不得使用固定答案。
+
+用户确认简报后，先按数据口径进行一次**临时安全素材预检**：只采集制作
+styleframe 所需的少量页面截图或 token，不做完整切片、全量导出或最终素材入库。
+公开演示数据只有在简报明确确认后可保留；客户、个人、内部、密钥、实时或其他
+敏感数据必须先替换、脱敏或冻结。已经明确提供的信息不要重复询问。
+
+## 2. 需求到执行决策表
+
+把已确认的用户需求、项目证据和 Agent 的执行选择写成同一张可追溯表。它不是
+固定的“受众→风格”规则表：每行都必须写明当前项目与用户材料带来的依据，
+并允许 Agent 提出与常见套路不同的推荐。
+
+```text
+当前阶段：从需求到制作决策
+
+| 已确认需求 | 项目/用户依据 | 受影响的执行范围 | Agent 推荐 | 需要确认项 |
+|---|---|---|---|---|
+| 视频用途 |  | 叙事结构、信息量、CTA |  |  |
+| 目标受众及其情境 |  | 场景、语言、节奏、功能优先级 |  |  |
+| 核心卖点与必须展示功能 |  | 页面状态、镜头、文案 |  |  |
+| 时长/画幅/语言 |  | 镜头数、字幕密度、构图 |  |  |
+| 音乐/配音 |  | 节奏、停顿、SFX 留白 |  |  |
+| 数据合规口径 |  | 采集、mock、打码、终检 |  |  |
+| 视觉方向 |  | tokens、材质、转场语气 |  |  |
+```
+
+表只记录对当前视频会产生实际影响的项。无法确定的项保留在“需要确认项”，
+每轮合计只问 1–3 个；已经确认的项不得再次提问。后续的视觉方向、镜头映射、
+分镜、素材采集、声音设计与终检都必须能追溯回此表，并在设计 spec 中保存。
+
+## 3. 视觉方向
+
+从页面、源码或 computed styles 提取字体、色板、圆角、信息密度、光感和动效
+性格。视觉方向分两轮确认：
+
+1. 先给出最多 3 个根据当前项目生成的文字方向。每个方向说明：名称、一句话
+   视觉主张、3–5 个关键词、字体/色彩/材质、镜头运动性格、适合原因和取舍。
+   只有产品确实适合纸张、编辑部或叙事质感时，才把 Ink Press 列为候选；不能
+   因为仓库里有它就固定加入。
+2. 用户选出 1–2 个入围方向，或明确授权 Agent 自选。对入围方向制作一个纯
+   HTML/CSS 的实际 styleframe 对比页：每个方向展示 2–3 张 1920×1080 的
+   静态关键画面（例如品牌开场、核心功能、品牌收尾），使用当前产品的真实
+   页面素材或已提取的视觉 token，不写 Remotion 代码、不渲染完整视频。
+3. 用 Playwright/Puppeteer 截出 styleframe 对比图，展示并列方向的字体、色板、
+   材质、构图、光感和信息密度。用户确认最终方向后，才能进入功能到镜头映射。
+
+Styleframe 用来确认静态视觉语言，不能单独证明缓动、运镜速度或节奏；这些仍需
+结合动效 tokens、Gallery 参考样片判断。若动效差异无法靠文字和样片判断，再做
+短的运动测试。用户已经提供严格品牌规范、明确参考片、直接选定 Ink Press，或
+明确授权 Agent 自选并跳过视觉确认时，可以记录理由后跳过 styleframe 对比。
+
+## 4. 功能到镜头映射
+
+先列产品功能，再扫描 `references/shots/` 各卡 frontmatter 的用途、能量、建议
+时长和限制。给每个必须展示的功能推荐首选和备选镜头：
+
+| 功能 | 首选镜头 | 备选镜头 | 画面要表达什么 | 需要的页面状态 |
+|---|---|---|---|---|
+
+用户可以接受、替换、删除或授权 Agent 自选。确定映射后，必须完整读取选中卡片，
+并按其“参考实现”定位准确 demo 源码；没有合适镜头时可以新写，但要说明新写范围
+和验证风险。Gallery 标为“仅供参考，需要自定义实现”的样式不默认推荐；用户明确
+点名后才允许自定义实现，并把风险写进设计 spec。
+
+这张映射表不是完整分镜，不得在用户确认映射后直接开始制作。它只确定“哪个
+产品功能使用哪一种镜头语法”，之后还必须进入第 5 节，展开镜头顺序、时长、
+页面状态、具体动作、素材、字幕、转场和声音。
+
+## 5. Gallery 镜头名称解析
+
+Gallery（https://vincentwei1021.github.io/video-shotcraft/）只是用户浏览和挑选
+动态样片的界面，镜头定义和实现源码已经包含在本仓库。用户不需要描述动画，
+只需复制并提供镜头名。
+
+收到镜头名后按以下顺序处理：
+
+1. 读取 `gallery/api/library.json`，用其中的 `cards[].name` 校验 `card-name`，
+   用该卡的 `styles[].key` 校验 `style-key`；不要用模糊猜测代替索引校验；
+2. 用索引中的 `source` 定位并完整读取 `references/shots/*.md`；
+3. 按卡片“参考实现”的明确路径，把具体样式解析到准确的 demo TSX；若文档只写
+   demo 目录，读取目录文件并根据导出名、注释和样式语义确定对应文件；
+4. 将索引中的 `styles[].media.url` 解析为本地 `gallery/media/` 参考样片，并在
+   设计 spec 记录：卡名、style-key、卡片文档、准确 demo TSX、参考样片；
+5. 如卡片需要通用组件，再读取并复制 `assets/lib/` 的对应文件；
+6. 保留 demo 中已经调校的缓动、时值配比、遮罩时机和“已知坑/命门”参数；
+7. 只替换目标产品的截图、布局坐标、文案、品牌 token 和必要的构图参数。
+
+Gallery 可能复制出两种形式：
+
+```text
+spotlight-hero-card
+shot-transitions · whip-pan
+```
+
+- 只有卡名：使用卡片默认变体；如果同一卡的多个变体表达差异明显，Agent 先按
+  前后镜头和产品气质推荐一个具体变体，并说明原因，必要时让用户确认。
+- `卡名 · 样式名`：优先使用用户点名的具体变体，读取对应实现，不擅自换式。
+- 名称不存在：报告无法匹配，并给出仓库中最接近的真实卡名；不要凭名字臆造。
+- 索引标为“仅供参考，需要自定义实现”：不主动推荐；用户明确点名后，明确说明
+  该样式没有可复用的完整实现，按配方参数和参考样片制作，并把实现风险写进设计 spec。
+- 索引标为“缺少预览”：可读取准确源码并用于制作，但不得声称已对照动态样片。
+
+严禁只根据卡名含义重新写一套近似动画。卡片文件提供语义，demo 源码才是参数
+真相。用户选中多个镜头后，把它们与产品功能映射，再继续生成完整分镜。
+
+## 6. 分镜确认
+
+把确认的功能和镜头组合成分镜，并至少包含：
+
+```text
+| # | 时间/帧 | 功能信息 | 镜头卡 | 主动作 | 素材来源 | 字幕/SFX |
+```
+
+检查每镜只讲一个主要动效，品牌字标 hold 至少 1 秒，批量动效收尾至少静止
+0.5 秒，避免重复 tagline 或让同一种动效反复当主角。用户确认分镜与最终设计 spec
+后，二者共同构成**制作放行**：不重新打开此前已确认的业务或创意问题，只补实现
+必要的未决项。此时再做最终全量素材采集（整页 2x 截图、元素切片、layout.json），
+把批准分镜转成帧级时间轴，再进入 `pipeline.md` 阶段 4 的最终素材采集、阶段 5
+逐镜头实现、阶段 6 声音设计和阶段 7 终检。
+
+将用户确认后的产品简报、需求到执行决策表、视觉方向/tokens、styleframe 或跳过理由、
+功能到镜头映射、Gallery 卡名与具体变体、最终分镜和数据合规口径保存为稳定的设计 spec
+（或在终检交接时完整提供），作为 `final-review.md` 的审查基准。不要让独立
+审查 Agent 依赖零散聊天记录猜测用户确认过什么。
+
+## 默认与跳过规则
+
+用户授权 Agent 全权决定时，仍须根据产品内容动态推导：从视觉 token 生成方向，
+从核心功能与页面状态选择镜头，从发布渠道、功能数量和阅读密度推荐时长/画幅/
+语言，从品牌能量与节奏推荐音乐。只有项目和用户描述都没有相关线索时，才使用
+30–38 秒、1920×1080 作为兜底。数据口径按项目风险决定：公开演示数据可沿用，
+客户、个人或内部数据改用虚构/脱敏内容。首次整片渲染前仍需提交分镜备案，除非
+用户明确要求不看中间产物。
+
+## 每轮回复格式
+
+```text
+当前阶段：
+已确认：
+本轮需要确认：
+确认后交付：
+```
@@ -5,11 +5,20 @@
 70s、18 镜、131.97 BPM 的强鼓点宣传片按此法制作，渲后回测全部切点
 误差 ≤2.2f（感知阈值约 3f）。

+## 目录
+
+- 何时启用
+- 节拍网格测定
+- 鼓点与重音定位
+- 用拍号编排时间线
+- 渲后回测
+- 工具备忘
+
 ## 0. 何时启用

-阶段 0 就问用户：**是否已选好音乐？**
+阶段 0 先检查用户是否已指定音乐。
 - 已选好 → 走本文档：先分析节奏，再让分镜的每个切点/动效锚到拍号
- 未选 → BGM 选型放到阶段 5（见 pipeline.md），此时动效时间线按
+- 未选 → BGM 选型放到阶段 6（见 pipeline.md），此时动效时间线按
  内容节奏排，不强行卡点

 ## 1. 节拍网格测定（不要相信 beat_track 的 tempo 标量）
@@ -1,98 +1,77 @@
-# pipeline — 六阶段制作流水线
+# pipeline — 八阶段制作流水线

-六阶段，每阶段有廉价确认物，方向性问题不进昂贵的逐镜头阶段。
+八阶段，方向性问题不进昂贵的逐镜头阶段。
 实证细节来自多支已交付宣传片的复盘（模板片见 `template/`）。

-两处相对"理想化六阶段"的修正（实战复盘已吸收）：
+## 目录

-1. **分镜与设计是同一份文档、同一次确认。** 分镜表长在设计 spec 里
-   （`| # | 时间 | 镜头 | 关键动效 |` 四列），用户一次确认同时放行风格细节
-   与镜头结构——不设独立的分镜确认环节。
+- 阶段 0：产品理解与执行约束
+- 阶段 1：视觉方向与 styleframe
+- 阶段 2：功能到镜头映射
+- 阶段 3：分镜与制作放行
+- 阶段 4：最终素材采集
+- 阶段 5：逐镜头实现
+- 阶段 6：声音设计
+- 阶段 7：独立终检与交付
+
+本文件是**自主自由创作**的完整流水线：阶段 0–3 的判断由 Agent 根据项目内容
+自主完成并记录，不逐阶段等待用户确认，然后连续进入阶段 4–7。用户已给出的
+用途、受众、功能、画幅、音频或数据要求都是硬约束。
+
+直接使用 Ink Press 模板不进入本流水线，按 `template/TEMPLATE.md` 的原有替换
+流程执行；模板文档引用阶段 4 时只借用其中的素材采集方法。
+
+**共同创作从 `guided-free-creation.md` 进入本文件时，不要从头重跑。** 该流程
+已经完成并确认阶段 0–3；直接从阶段 4 最终素材采集继续，不重新询问或重新设计。
+
+两处执行原则（实战复盘已吸收）：
+
+1. **最终设计 spec 与分镜共同构成制作放行。** 分镜表长在设计 spec 里
+   （`| # | 时间 | 镜头 | 关键动效 |` 四列）；确认放行不重新打开已确认的
+   业务或创意问题，只补实现必要的未决项。
 2. **验收贯穿全程，不是最后一个阶段。** 每个镜头任务以 `npx remotion still`
   静帧肉眼验收收尾（产物按版本归档 `out/qa/`），每轮反馈修改后整片重渲。
-   阶段 6 只是把这套贯穿动作升级为对照 aesthetic-rules.md 的正式自检报告。
+   阶段 7 只是把这套贯穿动作升级为对照 aesthetic-rules.md 的正式自检报告。

-另注顺序弹性：素材采集与风格定调谁先谁后不重要（styleframe 可以先用
-手绘 HTML），重要的是**逐镜头实现开始前素材必须已定案且经用户确认**——
-素材方向错误拖到逐镜头阶段后才暴露，代价是整套场景报废。
+另注顺序弹性：styleframe 可以先用 HTML 与少量安全预检素材；重要的是**逐镜头
+实现开始前最终素材必须依据已定案的分镜采集**——素材方向错误拖到逐镜头阶段后
+才暴露，代价是整套场景报废。

 ---

-## 阶段 0：开工三问
+## 阶段 0：产品理解与执行约束

-写第一行代码、截第一张图之前，先问清三件事：
+在写视频代码或采集最终素材前，只读检查项目的定位、主要功能、页面状态、视觉
+tokens、启动方式和数据风险。根据项目证据和用户已有描述，生成产品简报与需求到
+执行决策表，明确用途、受众、核心卖点、必须展示功能、时长/画幅/语言、音频和
+数据口径对本片的实际影响。

-1. **音乐选好了吗？** 用户已有指定 BGM → 先走
-   `references/music-beat-sync.md` 做节奏分析，分镜的每个切点/动效
-   都要锚到拍号（强节奏曲=所有转场动效必须卡点）；未选 → BGM 选型
-   留到阶段 5，时间线按内容节奏排。
-2. **用模板还是自由创作？** `template/` 是一支已验收成片的完整工程；
-   目标是"和模板片极度相似的效果"→ 按 `template/TEMPLATE.md` 的
-   换产品复现指南走（快、质量有底）；目标是新风格 → 走下面的完整流程，
-   模板只当参考。
-3. **数据合规口径？** 页面数据默认用现成真实数据即可；如涉及敏感/客户
-   信息，截图发用户确认时一并确认是否需要脱敏替换（脱敏是用户选项，
-   不是默认动作）。
+自主自由创作由 Agent 对缺省项作动态判断并写入设计 spec，不暂停要求用户确认。
+用户指定了 BGM 时，先按 `references/music-beat-sync.md` 分析节奏；未指定时由 Agent
+根据产品与发布场景在阶段 6 选型。公开演示数据可在确认其公开属性后使用；客户、
+个人、内部、密钥、实时或其他敏感数据一律先虚构、脱敏或冻结。
+
+**产出**：产品简报；需求到执行决策表；明确的数据与音频约束。

 ---

-## 阶段 1：素材采集
-
-**目标**：拿到全部镜头所需的真实页面素材——全页纹理、元素切片、坐标表，
-为 2.5D 运镜和页面空间动画打地基。
-
-**具体操作**：
-
-1. 起产品本地 dev server（桌面端产品则用窗口截图工具，同样出三件套）。
-2. 复制 `assets/scripts/capture-template.mjs` 进项目，改 BASE_URL 与选择器，
-   跑一次产出三件套：
-   - **全页 2x 截图**：viewport 1920×1080、`deviceScaleFactor: 2`
-     （纹理 2x 物理像素，消费端按 CSS 尺寸显示，天然留一档放大余量）；
-     `page.screenshot({ fullPage: true })`；截图前 `document.fonts.ready`
-     + 600ms settle（实时同步页额外再等 1.5–2s）。
-   - **per-element cutout**：语义选择器（article/header/nav/aside）逐元素
-     `element.screenshot()`；悬浮件（搜索框/按钮/统计行）加
-     `omitBackground: true` 出透明底，供独立成层；需要"卡片飞入
-     空板"的镜头，把所有卡设 `visibility:hidden` 后再截一张空 backplate。
-   - **layout.json**：每个元素在整页坐标系（`getBoundingClientRect()`
-     + scroll 偏移）下的 `{x,y,w,h}` bbox + 每页 `pageH`（scrollHeight）。
-     场景代码直接 import 它决定飞行目标位、遮罩位置、入场区域。
-3. 管线要支持**按页/按元素增量重采**（单独的小脚本只覆写一张纹理 +
-   layout 单键替换）。活的协作文档/实时数据页每次截图都不一样——
-   先冻结再采，且一开始就留好增量口子。
-
-**产出**：`public/textures/` 全页图 + 元素切片 + 空 backplate；
-`layout.json`；可重跑的 capture 脚本（进项目 repo）。
-
-**用户确认物**：关键页截图直接发给用户看，确认素材状态对不对、
-数据是否需要脱敏（见阶段 0 第 3 问）。
-
-**常见坑**：
-
- 手搓 HTML **复刻既有页面**贴图：一眼假，整体报废。复刻默认走真实
-  截图；手搓 UI 只用于非复刻场景（抽象开场/品牌段/独立展示组件），
-  且质量与表达明确性达标。
- 活数据源不锁定：协作文档/实时数据页先冻结再采。
- 只截整页不记坐标：没有 layout.json，后续所有页面空间动画都要人肉量像素。
-
---
-
-## 阶段 2：风格定调
+## 阶段 1：视觉方向与 styleframe

 **目标**：用最便宜的产物锁定全片色板、字体、光感与运镜气质，
 让所有方向性争论发生在写第一行 Remotion 代码之前。

 **具体操作**：

-1. 先给 2–3 个文字风格方向，用户挑出想看的。
-   每个方向附一组**动效性格 tokens**（推导法见下方"品牌→动效参数"表）——
-   风格定调锁的不只是色板字体，还有全片的缓动/时长/过冲口味。
-2. 对入围方向**不渲染视频、不写 Remotion 代码**，写一个纯 HTML/CSS
-   静态对比页：每方向 2–3 张 1920×1080 的 `.frame`（CSS
-   `transform:scale()` 缩到 ~820px 并排），暗底画廊排版，配方向名/标签/描述。
-3. Playwright/Puppeteer 全页截图导出一张 **styleframe 对比图**发给用户。
-   成本 = 一个 HTML 文件 + 一张截图，却能锁定全片 tokens。
-4. 若用户给了参考片：下载后 ffmpeg 抽帧（`select=eq(n,…)` 抽 ~100 帧、
+1. 根据当前项目生成最多 3 个文字方向。每个方向附一组**动效性格 tokens**
+   （推导法见下方“品牌→动效参数”表），但不要把 Ink Press 作为固定选项。
+2. Agent 依据产品视觉、用途和受众自主选择最合适的方向，并把选择与取舍写入
+   设计 spec；不暂停等待用户选择。
+3. 对选定方向**不渲染视频、不写 Remotion 代码**，写一个纯 HTML/CSS
+   styleframe 页，包含 2–3 张 1920×1080 静态关键画面。
+4. 用 Playwright/Puppeteer 截图验证字体、色板、材质、构图、光感与信息密度；
+   缓动和运镜速度仍以 tokens、Gallery 样片或短运动测试判断。若已有严格品牌规范
+   或明确参考片，可记录理由后跳过 styleframe。
+5. 若用户给了参考片：下载后 ffmpeg 抽帧（`select=eq(n,…)` 抽 ~100 帧、
   `tile=4x5` 拼 contact sheet），逐个动画/转场/特效做 motion breakdown，
   写成"手法｜参考片实现｜取舍"三列表进设计 spec——**选择性适配，
   不强行套用**。图片参考同理：它描述的是"某一类镜头"的感觉，
@@ -122,11 +101,9 @@
 注意预设值与库内硬判例冲突时判例赢：落地要弹的场合 y1 必须 >1，
 "专业信赖不弹"指的是无落地隐喻的淡入/推移类动作。

-**产出**：styleframe 对比图；色板/字体/光感 tokens + 动效性格 tokens；
+**产出**：选定方向的 styleframe；色板/字体/光感 tokens + 动效性格 tokens；
 （有参考片时）motion breakdown 表。

-**用户确认物**：styleframe 对比图，用户看图选定方向。
-
 **常见坑**：

 - 用渲染视频做风格提案：太贵，改方向的心理成本也高。静态帧足够定调。
@@ -135,37 +112,48 @@

 ---

-## 阶段 3：分镜设计
+## 阶段 2：功能到镜头映射

-**目标**：把产品功能清单翻译成一条有能量曲线的镜头序列，
-每镜头绑定一个独特功能、只讲一个动效。
+**目标**：为每个必须展示的功能选定合适的运动语法，不在此阶段提前写完整分镜。

 **具体操作**：

 1. **先列产品功能清单，逐一对应镜头**。核心功能漏拍等于返工；
   一种动画手法（飞入/堆叠/翻页）全片只当一次主角，同质化即返工信号。
-2. 先查 `references/sequences/` 有无适用的桥段模板（全片结构骨架，
-   如 promo-energy-arc），有则按其填空流程分配段位与帧预算；
-   再按功能类别扫 `references/shots/<类别>/` 卡片的 frontmatter（一句话/适用/时长/能量；类别目录说明见 SKILL.md）
-   逐槽位选配方：低能量品牌开场 → 中高能量功能段交替 →
-   字卡呼吸位间隔 → 结尾推到全片能量峰值（"产品发布会"规格）。
-3. **已有指定 BGM 时**：先出音乐结构表（满能量起点/breakdown 拍号，
+2. 扫描 `references/shots/` 全部卡片的 frontmatter，根据用途、能量、建议时长、
+   限制和所需页面状态，为每项功能选择首选与备选卡；Agent 自主定案并记录依据。
+3. 完整读取选中卡片，并按“参考实现”定位准确 demo 源码。没有合适卡片时可新写，
+   但必须在设计 spec 中说明范围与验证风险。
+
+**产出**：功能到镜头映射表；选中卡名、变体、demo 源码和参考样片定位。
+
+---
+
+## 阶段 3：分镜与制作放行
+
+**目标**：把已定案的功能与镜头映射排成有能量曲线的完整镜头序列，并转成帧级
+实施计划。自主自由创作由 Agent 自行放行，不暂停等待确认。
+
+**具体操作**：
+
+1. 先查 `references/sequences/` 有无适用的桥段模板；有则按其填空流程分配段位
+   与帧预算，再把映射好的镜头排成低能量开场→功能段与呼吸位交替→高能量收尾。
+2. **已有指定 BGM 时**：先出音乐结构表（满能量起点/breakdown 拍号，
   见 music-beat-sync.md §2），镜头边界全部锚到拍号，最强 hit 分给
   全片 2–3 个大 slam；breakdown 段天然是品牌呼吸位。
-4. 写分镜表进设计 spec：`| # | 时间 | 镜头 | 关键动效 |` 四列，每镜 2–4s，
-   字卡文案原文直接入表。**分镜与设计同文档、同一次确认**。
-5. 排时间线时**预留 hold/rest 帧预算**：品牌字标落定 hold ≥1s（30f）、
+3. 写完整分镜表：镜头顺序、时长、功能信息、具体页面状态、镜头卡与变体、主动作、
+   素材来源、字幕、转场和 SFX。每镜只讲一个主要动效。
+4. 排时间线时**预留 hold/rest 帧预算**：品牌字标落定 hold ≥1s（30f）、
   批量动效收尾 0.5s 静止、开场主体动作 ≥3s。节奏返工是单向的——
   过快必返工、放慢从未被否。
-6. 用户确认后，把分镜表转译成帧级时间轴进实施计划：
+5. Agent 检查分镜与产品简报、需求决策、视觉方向和镜头映射一致后自行放行，
+   把分镜转译成帧级时间轴进实施计划：
   `| shot | from | duration | 内容 |`（卡点片则 from/to 全用 `beatF(n)`
   表达），并给每镜头指定源文件与验收帧号。

 **产出**：设计 spec（含风格 tokens + motion breakdown + 分镜表）；
 帧级时间轴。

-**用户确认物**：设计 spec / 分镜表（一次确认放行）。
-
 **常见坑**：

 - 没对功能清单，凭手感排镜头：核心功能漏拍、动画手法同质化，两种都返工。
@@ -174,7 +162,41 @@

 ---

-## 阶段 4：逐镜头实现
+## 阶段 4：最终素材采集
+
+**前置条件**：最终设计 spec 与分镜已经放行。共同创作以用户确认作为放行；自主
+自由创作以 Agent 完成一致性检查并记录为放行。此前为 styleframe 采过的少量安全
+截图只能作为方向验证，不得直接替代最终素材。
+
+**目标**：严格按最终分镜拿到全部镜头所需的真实页面素材，包括全页纹理、元素
+切片和坐标表，为 2.5D 运镜与页面空间动画打地基。
+
+**具体操作**：
+
+1. 起产品本地 dev server（桌面端产品则用窗口截图工具，同样出三件套）。
+2. 复制 `assets/scripts/capture-template.mjs` 进项目，改 BASE_URL 与选择器，
+   跑一次产出三件套：
+   - **全页 2x 截图**：viewport 1920×1080、`deviceScaleFactor: 2`；截图前
+     `document.fonts.ready` + 600ms settle，实时同步页额外再等 1.5–2s。
+   - **per-element cutout**：按语义选择器逐元素截图；悬浮件用透明底，需要
+     “卡片飞入空板”的镜头则额外截空 backplate。
+   - **layout.json**：记录每个元素在整页坐标系下的 `{x,y,w,h}` bbox 与每页
+     `pageH`，供飞行目标位、遮罩位置和入场区域直接使用。
+3. 支持按页/按元素增量重采。活数据源先按阶段 0 的数据口径冻结、虚构或脱敏，
+   再进行最终采集。
+
+**产出**：`public/textures/` 全页图、元素切片与空 backplate；`layout.json`；
+可重跑的 capture 脚本。
+
+**常见坑**：
+
+- 在分镜放行前做全量采集：页面状态和素材范围尚未确定，会造成重复采集。
+- 手搓 HTML 复刻既有页面：复刻默认走真实截图；手搓 UI 只用于非复刻场景。
+- 活数据源不锁定，或只截整页不记录 layout 坐标。
+
+---
+
+## 阶段 5：逐镜头实现

 **前置条件**：需已有可跑的 Remotion 项目（30fps、1920×1080，`src/index.ts`
 注册 Composition；新项目可 `npx create-video@latest` 初始化后把
@@ -185,9 +207,13 @@

 **具体操作**：

-1. **每镜头三读**（硬规则，不可跳）：读对应配方卡全文 → 读
-   `demos/<类别>/<卡名>/` 对应式的 demo 实现源码全文 → copy `assets/lib/`
-   对应组件进项目。demo 代码是调校过的参数真相（缓动、时值配比、
+1. **每镜头先解析再三读**（硬规则，不可跳）：用
+   `gallery/api/library.json` 校验卡名和 `style-key` → 读对应配方卡全文 →
+   按卡片“参考实现”定位并读准确的 demo TSX 全文 → copy `assets/lib/`
+   对应组件进项目。同时保存该 style 的 Gallery 参考样片路径，供实现对照和终检。
+   标为“仅供参考，需要自定义实现”的样式不默认推荐，用户明确点名后才可实现并
+   标注风险；标为“缺少预览”的样式不得声称已按动态样片复刻。
+   demo 代码是调校过的参数真相（缓动、时值配比、
   摘罩时机、已知坑的规避写法都在里面）——允许按目标产品做适配性
   改动，但配方卡"已知坑/命门"标注的参数不得降档，质量标准只升不降。
   凭卡名和理解新写＝放弃全部调校积累，实测质感差一档。
@@ -196,8 +222,6 @@
 3. **静帧验收（最高频动作）**：每镜头在计划里写死 2 个验收帧号，
   完成即跑 `npx remotion still src/index.ts <Comp> out/qa/<name>.png
   --frame=<N>`，自己肉眼检查构图/穿帮/文字锐度后才算完成。
-   含字幕/文字的镜头加查有效字高（字幕 ≥56px、辅助文字 ≥32px，
-   按渲染帧实际像素量，3D 镜头计入 scale 与透视压缩，见审美准则 Q11）。
   静帧产物按迭代版本归档 `out/qa/`，用户贴帧反馈时可直接对号。
 4. **每轮修改后整片渲染**：`npx remotion render src/index.ts <Comp>
   out/promo.mp4`，再用 `ffmpeg -i out/promo.mp4 -vf "select=eq(n,…)"`
@@ -208,7 +232,7 @@
 6. **确定性渲染铁律**：禁 `Date.now()` / `Math.random()` / 无参 `new Date()`。
   一切伪随机用固定种子（mulberry32/哈希函数，seed 从 index 派生），
   保证逐帧可复现、渲染间零抖动。
-7. 对照 `references/aesthetic-rules.md` 边做边自检（不等阶段 6）：
+7. 对照 `references/aesthetic-rules.md` 边做边自检（不等阶段 7）：
   落地要弹的缓动 y1 必须 >1、光效裁进圆角、3D 下文字糊先查
   栅格化路径（CSS `zoom` 布局级放大，而非 transform scale）而不是调 DoF。
 8. 指代含糊的用户反馈（"第一个标题"）先确认对象再动手；改错立即整
@@ -217,7 +241,8 @@

 **产出**：逐镜头 commit；`out/qa/` 静帧档案；每轮全片渲染 mp4。

-**用户确认物**：整片渲染视频（每轮迭代一版）+ 关键静帧。
+**阶段输出**：整片渲染视频（每轮迭代一版）+ 关键静帧。自主自由创作不因该输出
+暂停等待确认；用户主动反馈时再纳入下一轮。
 用户可能以"从成片截帧贴图"方式给反馈，双方基于帧评审。

 **常见坑**：
@@ -236,7 +261,7 @@

 ---

-## 阶段 5：声音设计
+## 阶段 6：声音设计

 **目标**：BGM 定全片能量骨架，SFX 逐拍钉在动效关键帧上，
 音色符合"产品宣传片"片种而非 UI 事件语义。
@@ -274,7 +299,7 @@
 **产出**：带声整片；SFX 钉帧表（相对帧表达式+音源+音量+注释）；
 音频文件入 repo 并记录来源授权。

-**用户确认物**：带声整片渲染。
+**阶段输出**：带声整片渲染。自主自由创作继续进入终检，不暂停等待确认。

 **常见坑**：

@@ -284,32 +309,41 @@

 ---

-## 阶段 6：验收
+## 阶段 7：验收

 **目标**：把贯穿全程的静帧/整片自检升级为一次正式的全片过检，
-对照审美准则逐条出报告，然后终渲交付。
+同时验证成片是否忠实执行当前模式下确认或记录的产品简报、需求到执行决策表、视觉方向、镜头映射和分镜，
+对照终检与审美准则逐条出报告，然后终渲交付。

 **具体操作**：

 1. 全片渲染最新版，ffmpeg 抽全部关键帧（每镜头至少：入场中、
   动作峰值、落定后三帧）。
-2. **独立视觉审查（必做）**：派一个干净上下文的 subagent 做第三方
-   审查——它没有参与制作、不知道"应该长什么样"，只拿到成片 mp4、
-   抽出的关键帧、`references/aesthetic-rules.md` 和分镜表。它的任务：
-   逐镜头看帧+看片，持 checklist 逐条给出
-   "R1 ✓ / Q2 ✗（第 340 帧文字发糊，见截图）"式结论，输出带帧号
-   证据的审查报告。制作 agent 对自己的产出有确认偏差，独立审查
-   替代的是用户当人肉 QA 的那几轮往返。
-3. 内容级自查：每个镜头问"给了什么新信息"，重复镜头/重复 tagline 删；
+2. **独立终检（必做）**：派一个干净上下文的 subagent 做第三方审查。
+   不给它制作过程中的辩解、修改历史或“应该通过”的暗示，只提供：最新版成片、
+   抽出的关键帧、创作模式、产品简报、需求到执行决策表、确认或记录的视觉方向/tokens、styleframe 或跳过理由、
+   功能到镜头映射、
+   Gallery 卡名与具体变体、`library.json` 中对应记录、卡片文档定位到的准确
+   demo TSX、Gallery 参考样片或从中抽出的关键帧、最终分镜、选中的镜头卡、
+   `references/final-review.md` 和 `references/aesthetic-rules.md`。
+3. 审查 Agent 按 `final-review.md` 检查产品目标、功能完整性、视觉方向一致性、
+   镜头卡/变体还原度、分镜一致性、数据安全、音画同步和视觉技术质量。逐镜头
+   看帧+看片，给出 "F2 ✗（第 340 帧缺少已确认的知识图谱功能）" 或
+   "Q2 ✗（第 615 帧文字发糊）" 式结论，每条问题附可复核帧号/截图。
+   镜头卡适配不要求和 Gallery 样片像素级相同，但必须保留动作语法、关键时值、
+   已知坑/命门参数和用户点名的具体变体。
+4. 内容级自查：每个镜头问"给了什么新信息"，重复镜头/重复 tagline 删；
   文案按最终画面重写一遍，纯动画段落也要有解说 caption，不留哑巴段落。
-4. 音画对齐终检：逐条 SFX 对帧回放，确认无错位（时间线若在阶段 5 后
+5. 音画对齐终检：逐条 SFX 对帧回放，确认无错位（时间线若在阶段 6 后
   还动过，先重对再验）。卡点片按 music-beat-sync.md §4 做渲后回测，
   全部切点误差 ≤3f 才算过。
-5. 审查报告的修复项回到阶段 4/5 小循环，直到 checklist 通过；终渲出片。
+6. 审查报告的修复项回到阶段 3/5/6 小循环：方案或分镜偏差回阶段 3，画面实现
+   问题回阶段 5，声音问题回阶段 6；直到 checklist 通过后终渲出片。

-**产出**：独立审查报告（aesthetic-rules checklist + 帧号证据）+ 终渲成片。
+**产出**：独立审查报告（final-review + aesthetic-rules checklist + 帧号证据）
+ 终渲成片。

-**用户确认物**：审查报告 + 成片。
+**交付物**：审查报告 + 成片。

 **常见坑**：

@@ -319,3 +353,5 @@
  报告里每条结论都应附可复核的帧号/截图。
 - 制作 agent 自己出审查报告：确认偏差不可避免，独立 subagent 审查
  不可省略。
+- 只查“好不好看”不查“是否符合当前模式的制作基准”：功能漏拍、视觉方向漂移、
+  镜头变体用错和未经确认的数据都属于终检失败。
@@ -47,3 +47,6 @@ logo 单瓣（多元素落位拼装）。观众看到的不是"logo 出现了"
 demos/ui-to-brand-morph/
 （IconFlipBloomLogo.tsx / InputMorphsIntoLogo.tsx）
 原片出处：A perplexity-promo 88–91.5s / B slack-promo 40–41s
+
+实现状态：`icon-flip-bloom` 有样片；`input-morph-assemble` 有参考实现但缺少
+Gallery 动态预览，不得声称已按样片对照还原。
@@ -47,3 +47,7 @@ name: wall-reveal-moves
 ## 参考实现
 demos/wall-reveal-moves/
 （BentoLightUp.tsx）
+
+实现状态：`bento-light-up` 可按上述源码适配；`grid-wave-flip` 与
+`wireframe-draw-on` 仅供参考，需要自定义实现。二者不默认推荐，只有用户明确
+点名后才可基于本卡参数和 Gallery 样片制作，并在设计 spec 与终检中记录风险。
@@ -4,6 +4,13 @@

 模板片的声音全部集中在一个文件里管理（`template/src/aifl/Main.tsx`：`SFX[]` 钉帧表），场景组件不含任何音频代码——声音是时间线级资产，不是镜头级资产。

+## 目录
+
+- 方法
+- BGM 选型
+- SFX 词汇表
+- 对齐技巧
+
 ---

 ## 1. 方法
@@ -56,7 +56,8 @@

 ## 四、换产品复现指南（保质量的最短路径）

-1. **采集素材**（详细流程见 ../references/pipeline.md 阶段 1）：
+1. **采集素材**（具体采集方法见 ../references/pipeline.md 阶段 4；模板路线只借用
+   采集方法，不执行自由创作的阶段 0–3）：
   复制 `../assets/scripts/capture-template.mjs` 进目标产品项目，改 BASE_URL
   与选择器，产出三件套——整页 2x 截图、元素透明底切片、layout.json。
   素材命名对齐本模板（projects-full/detail-full/…），可直接覆盖 public/。