dsh-drawai 0.3.4 → 0.4.1

package/lib/motion/shotcraft/upstream/references/pipeline.md

@@ -0,0 +1,382 @@
+# pipeline — 八阶段制作流水线
+
+八阶段，方向性问题不进昂贵的逐镜头阶段。
+实证细节来自多支已交付宣传片的复盘（模板片见 `template/`）。
+
+## 目录
+
+- 阶段 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/`），每轮反馈修改后整片重渲。
+   阶段 7 只是把这套贯穿动作升级为对照 aesthetic-rules.md 的正式自检报告。
+
+另注顺序弹性：styleframe 可以先用 HTML 与少量安全预检素材；重要的是**逐镜头
+实现开始前最终素材必须依据已定案的分镜采集**——素材方向错误拖到逐镜头阶段后
+才暴露，代价是整套场景报废。
+
+---
+
+## 阶段 0：产品理解与执行约束
+
+在写视频代码或采集最终素材前，只读检查项目的定位、主要功能、页面状态、视觉
+tokens、启动方式和数据风险。根据项目证据和用户已有描述，生成产品简报与需求到
+执行决策表，明确用途、受众、核心卖点、必须展示功能、时长/画幅/语言、音频和
+数据口径对本片的实际影响。
+
+自主自由创作由 Agent 对缺省项作动态判断并写入设计 spec，不暂停要求用户确认。
+用户指定了 BGM 时，先按 `references/music-beat-sync.md` 分析节奏；未指定时由 Agent
+根据产品与发布场景在阶段 6 选型。公开演示数据可在确认其公开属性后使用；客户、
+个人、内部、密钥、实时或其他敏感数据一律先虚构、脱敏或冻结。
+
+**产出**：产品简报；需求到执行决策表；明确的数据与音频约束。
+
+---
+
+## 阶段 1：视觉方向与 styleframe
+
+**目标**：用最便宜的产物锁定全片色板、字体、光感与运镜气质，
+让所有方向性争论发生在写第一行 Remotion 代码之前。
+
+**具体操作**：
+
+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——**选择性适配，
+   不强行套用**。图片参考同理：它描述的是"某一类镜头"的感觉，
+   不是全片风格令。
+
+**品牌→动效参数推导**。不凭手感挑 easing/时长，先把品牌放到两根轴上，
+再从最近的预设起步：
+
+- **能量轴**：低（沉稳/premium/机构感）↔ 高（运动/startup/娱乐）——
+  决定时长、过冲、squash 幅度；
+- **调性轴**：严肃（金融/医疗/enterprise）↔ 活泼（消费/社交/儿童）——
+  决定路径曲直、次级动作多寡。产品视觉本身是证据（锐利几何形→工程感，
+  圆角+亮色→柔和活泼）；用户口述的品牌词覆盖视觉推断。
+
+| 预设（品类） | 主时长@30fps | 入场 easing | 过冲 | squash |
+|---|---|---|---|---|
+| 专业信赖（fintech/enterprise/B2B）| ~21f | bezier(0,0,0.2,1) | 1.0 不弹 | 0 |
+| 精致高端（奢侈品/时尚）| ~48f | bezier(0.4,0,0.6,1) | ≤1.02 | 0 |
+| 活力大胆（体育/游戏/startup）| ~18f | bezier(0.16,1,0.3,1) | 1.12 | 0.25 |
+| 活泼愉悦（消费/社交）| ~27f | bezier(0.34,1.56,0.64,1) | 1.08 | 0.18 |
+| 平静关怀（健康/教育）| ~42f | ease-in-out 对称 | 1.0 | ≤0.04 |
+| 亲和友好（小微/社区）| ~26f | bezier(0.25,0.46,0.45,0.94) | 1.04 | 0.08 |
+
+用法：定预设 → 按两轴微调 → tokens 写进设计 spec。自检两条：
+①用三个词描述成片动效，与品牌词对得上吗；②同一套 tokens 必须同时管
+入场/转场/hold 节奏——一个品牌一种动效嗓音，混用两套读作拼盘。
+注意预设值与库内硬判例冲突时判例赢：落地要弹的场合 y1 必须 >1，
+"专业信赖不弹"指的是无落地隐喻的淡入/推移类动作。
+
+**产出**：选定方向的 styleframe；色板/字体/光感 tokens + 动效性格 tokens；
+（有参考片时）motion breakdown 表。
+
+**常见坑**：
+
+- 用渲染视频做风格提案：太贵，改方向的心理成本也高。静态帧足够定调。
+- 参考驱动的风格 move 全局一刀切：风格化机位逐镜头决定（信息密集的
+  列表/堆叠镜头正视更可读）。
+
+---
+
+## 阶段 2：功能到镜头映射
+
+**目标**：为每个必须展示的功能选定合适的运动语法，不在此阶段提前写完整分镜。
+
+**具体操作**：
+
+1. **先列产品功能清单，逐一对应镜头**。核心功能漏拍等于返工；
+   一种动画手法（飞入/堆叠/翻页）全片只当一次主角，同质化即返工信号。
+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 段天然是品牌呼吸位。
+3. 写完整分镜表：镜头顺序、时长、功能信息、具体页面状态、镜头卡与变体、主动作、
+   素材来源、字幕、转场和 SFX。每镜只讲一个主要动效。
+4. 排时间线时**预留 hold/rest 帧预算**：品牌字标落定 hold ≥1s（30f）、
+   批量动效收尾 0.5s 静止、开场主体动作 ≥3s。节奏返工是单向的——
+   过快必返工、放慢从未被否。
+5. Agent 检查分镜与产品简报、需求决策、视觉方向和镜头映射一致后自行放行，
+   把分镜转译成帧级时间轴进实施计划：
+   `| shot | from | duration | 内容 |`（卡点片则 from/to 全用 `beatF(n)`
+   表达），并给每镜头指定源文件与验收帧号。
+
+**产出**：设计 spec（含风格 tokens + motion breakdown + 分镜表）；
+帧级时间轴。
+
+**常见坑**：
+
+- 没对功能清单，凭手感排镜头：核心功能漏拍、动画手法同质化，两种都返工。
+- 开场贪多：开场信息宁少而聚焦，一个主角、一条完整动作弧。
+- 时长预算不含呼吸位：动效排满每一帧，后期逐镜头补 hold 等于全线挪帧。
+
+---
+
+## 阶段 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` 初始化后把
+`assets/lib/` 组件 copy 进去；走模板路线则直接从 `template/` 起步）。
+
+**目标**：按帧级时间轴逐镜头落地，每镜头完成即自证质量——
+验收在这个阶段就开始，不留到最后。
+
+**具体操作**：
+
+1. **每镜头先解析再三读**（硬规则，不可跳）：用
+   `gallery/api/library.json` 校验卡名和 `style-key` → 读对应配方卡全文 →
+   按卡片“参考实现”定位并读准确的 demo TSX 全文 → copy `assets/lib/`
+   对应组件进项目。同时保存该 style 的 Gallery 参考样片路径，供实现对照和终检。
+   标为“仅供参考，需要自定义实现”的样式不默认推荐，用户明确点名后才可实现并
+   标注风险；标为“缺少预览”的样式不得声称已按动态样片复刻。
+   demo 代码是调校过的参数真相（缓动、时值配比、
+   摘罩时机、已知坑的规避写法都在里面）——允许按目标产品做适配性
+   改动，但配方卡"已知坑/命门"标注的参数不得降档，质量标准只升不降。
+   凭卡名和理解新写＝放弃全部调校积累，实测质感差一档。
+2. **PageCam 是一切"真实页面"镜头的地基**：整页纹理 + 关键帧 2.5D 相机 +
+   页面空间 overlay，children 按页面 CSS px 定位、与 layout.json 共坐标系。
+3. **静帧验收（最高频动作）**：每镜头在计划里写死 2 个验收帧号，
+   完成即跑 `npx remotion still src/index.ts <Comp> out/qa/<name>.png
+   --frame=<N>`，自己肉眼检查构图/穿帮/文字锐度后才算完成。
+   静帧产物按迭代版本归档 `out/qa/`，用户贴帧反馈时可直接对号。
+4. **每轮修改后整片渲染**：`npx remotion render src/index.ts <Comp>
+   out/promo.mp4`，再用 `ffmpeg -i out/promo.mp4 -vf "select=eq(n,…)"`
+   从成片抽关键帧回看。实际形态是"改哪个镜头就 still 哪几帧，
+   然后整片重渲"，成本可接受且杜绝接缝意外。
+5. 像素级自检备小工具：裁剪放大看文字锐度（crop）、两帧像素 diff、
+   量元素 bbox 对构图。
+6. **确定性渲染铁律**：禁 `Date.now()` / `Math.random()` / 无参 `new Date()`。
+   一切伪随机用固定种子（mulberry32/哈希函数，seed 从 index 派生），
+   保证逐帧可复现、渲染间零抖动。
+7. 对照 `references/aesthetic-rules.md` 边做边自检（不等阶段 7）：
+   落地要弹的缓动 y1 必须 >1、光效裁进圆角、3D 下文字糊先查
+   栅格化路径（CSS `zoom` 布局级放大，而非 transform scale）而不是调 DoF。
+8. 指代含糊的用户反馈（"第一个标题"）先确认对象再动手；改错立即整
+   commit revert 重来，不在错误版本上打补丁——每个改动独立 commit
+   以便干净回滚。
+9. **为交付后的动效工作台留好接口**（`references/workbench.md` §2–3）：时间表只写一份
+   （`SHOTS` 是唯一事实源，字幕表 / SFX 钉帧 / 转场点从它派生并 `export`）；镜头的语境级
+   参数（文案 / 颜色 / 字号 / 位置）做成带默认值的 props，节奏命门保持常量；
+   `src/workbench.ts` 里 import 这些表、给每个单元补 `component` / `props` / `schema`。
+   模板路线已自带（`template/src/workbench.ts`），自由创作在时间线定稿后补写，
+   交付前 `cd workbench && npm run parity` 证明拆解无损。
+
+**产出**：逐镜头 commit；`out/qa/` 静帧档案；每轮全片渲染 mp4；`src/workbench.ts` 清单。
+
+**阶段输出**：整片渲染视频（每轮迭代一版）+ 关键静帧。自主自由创作不因该输出
+暂停等待确认；用户主动反馈时再纳入下一轮。
+用户可能以"从成片截帧贴图"方式给反馈，双方基于帧评审。
+
+**常见坑**：
+
+- 首检交给用户：交付前必须自己抽帧看片，"镜头视角很差，
+  而且有小抖动"这种问题不该由用户发现。
+- 跳过 demo 代码直接写：参数是几轮真实裁决调校出来的，
+  新写的版本几乎必然回踩已知坑。
+- 产品宣传片默认不加手持 shake；相机噪声只在明确追求纪实感时用。
+- 装饰性 glint/泛光群发：批量元素入场靠运动本身。单点高质量光效可做，
+  群发即廉价。
+- 3D 推进下文字发糊：根因是纹理源分辨率/栅格化路径，先查素材链路
+  （2x 纹理 + CSS zoom + 关键元素 4x 单独截图），别先动相机和景深。
+- 飞入动画终点悬空：元素必须落进页面布局的真实槽位（嵌入、归位、
+  排进滚动流），悬浮在页面上方不落地会显得假。
+
+---
+
+## 阶段 6：声音设计
+
+**目标**：BGM 定全片能量骨架，SFX 逐拍钉在动效关键帧上，
+音色符合"产品宣传片"片种而非 UI 事件语义。
+
+**前置条件（最贵的顺序教训）**：**画面时间线锁定后才开始。**
+画面每动一次，钉帧表就要全体重对。若画面确实又改了，收尾动作固定
+包含"全表 SFX 帧号重对"，音画错位是必查项。
+
+**具体操作**（细节与判例见 `references/sound-design.md`）：
+
+1. 读 `references/sound-design.md` 与 `references/sfx-sourcing.md`，根据分镜里的
+   动作、材质、时长和音色从 Freesound 搜索 SFX。新项目不从模板或共享本地库挑音。
+   默认 CC0，允许署名时可选 CC BY；相关性与声源匹配优先，下载量/评分人数仅作辅助。
+2. 用 `assets/scripts/sfx-source.py get` 下载到工程 `public/audio/sfx/`，核对详情页许可，
+   保存 `audio-manifest.json` 与 `FREESOUND-CREDITS.md`。脚本下载的是 MP3 预览，
+   不当成原始无损音频；原音质要求按素材页支持的流程获取并重新测量。
+3. **BGM**：已指定则沿用前期节奏分析；未指定则结合产品方向选择，可使用
+   `assets/audio/bgm/` 备选。候选必须垫进成片试听，音量按实测给 SFX/配音留空间。
+   BGM 独立受 `bgm` inputProp 控制，从同一时间线交付带 BGM / 无 BGM（保留 SFX）两版。
+4. 音色按片种和实际声源判断：运镜 whoosh、落地 impact、铺垫 riser、光效 sparkle、
+   转场 transition；点击/开关/碎裂要有拟音。合成反馈提示音只在有明确叙事理由时使用。
+5. **中央 SFX 表 + 相对钉帧**：`{ from, src, volume }[]`，逐条注释动作，
+   `from` 用 `SHOTS.x.from + offset` 或 `beatF(n)`，不写裸绝对帧号；
+   按 sound-design §4.6 扣除音源峰值与输出音轨偏移。Remotion 使用工程内固定文件。
+6. 下载时的分析记录用于确定播放窗口、增益和候选峰值。>5s 动作样本显式给
+   `durationInFrames`，环境声按段落铺，impact 混响保留自然尾音。处理后重新分析并更新
+   文件哈希与修改记录；10ms 能量峰不是 LUFS/true peak，也不自动等于语义落点。
+7. 连发防机枪感：不同样本交替、音量递减、间隔贴动画加速，密集段收成 swoosh。
+   强鼓点片只给画面独有动作配 SFX，重音留给分镜中的少量峰值。
+8. 在成片语境里试听并验峰，确认拟音可听见、不削波、不盖住必要人声。
+   元数据和测量不能冒充试听结论；候选尚未试听时如实记录。
+9. 若分镜采用结尾三拍句式，用 Freesound 的 riser→impact→sparkle 贴实际动作，
+   不照抄模板音源名/帧号。下载失败不静默用旧库替代，按结果只重试失败项。
+
+**产出**：带声整片；SFX 相对钉帧表；工程内固定音频、来源许可清单、署名文件与分析记录。
+CC BY 素材的署名随交付提供，发布时进入说明或成片署名。
+
+**阶段输出**：带声整片渲染。自主自由创作继续进入终检，不暂停等待确认。
+
+**常见坑**：
+
+- 画面未锁定就精确钉音，后续变更漏掉 SFX 复核。
+- 只看下载量选到不匹配的声源，或把合成提示音当成真实 UI 拟音。
+- 长样本不设播放窗口，或照抄增益而忽略素材本身峰值。
+- 将 MP3 预览当原始无损音频、许可只留搜索标签、CC BY 署名只留在工程中。
+- 直接在渲染时间线引用远程 URL，网络变化导致成片不可复现。
+
+---
+
+## 阶段 7：验收
+
+**目标**：把贯穿全程的静帧/整片自检升级为一次正式的全片过检，
+同时验证成片是否忠实执行当前模式下确认或记录的产品简报、需求到执行决策表、视觉方向、镜头映射和分镜，
+对照终检与审美准则逐条出报告，然后终渲交付。
+
+**具体操作**：
+
+1. 全片渲染最新版，ffmpeg 抽全部关键帧（每镜头至少：入场中、
+   动作峰值、落定后三帧）。配了 BGM 的片子在此处就渲出两版——带 BGM 版
+   和无 BGM 版（保留 SFX），无 BGM 版靠阶段 6 预留的 `bgm` inputProp
+   从同一时间线渲出：写一个 `props-nobgm.json`（内容 `{"bgm":false}`）
+   然后 `npx remotion render … --props=props-nobgm.json`（跨平台可靠；
+   macOS/Linux 也可内联 `--props='{"bgm":false}'`，Windows shell 会剥掉
+   内联 JSON 的双引号，必须走文件）。不另建工程、不用 ffmpeg 后期抽轨。
+   命名区分（如 `promo.mp4` / `promo-nobgm.mp4`）。
+2. **独立终检（必做）**：派一个干净上下文的 subagent 做第三方审查。
+   不给它制作过程中的辩解、修改历史或“应该通过”的暗示，只提供：最新版成片
+   （配 BGM 的片子含两版，供 A8 校验）、
+   抽出的关键帧、创作模式、产品简报、需求到执行决策表、确认或记录的视觉方向/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，不留哑巴段落。
+5. 音画对齐终检：逐条 SFX 对帧回放，确认无错位（时间线若在阶段 6 后
+   还动过，先重对再验）。卡点片按 music-beat-sync.md §5 做渲后回测，
+   全部切点误差 ≤3f 才算过。
+6. 审查报告的修复项回到阶段 3/5/6 小循环：方案或分镜偏差回阶段 3，画面实现
+   问题回阶段 5，声音问题回阶段 6；直到 checklist 通过后终渲出片。
+   终渲重复步骤 1 的双版本渲染——配 BGM 的片子交付带 BGM / 无 BGM 两版，
+   无 BGM 版方便用户后期自配音乐或平台配乐。
+
+**产出**：独立审查报告（final-review + aesthetic-rules checklist + 帧号证据）
++ 终渲成片（带 BGM / 无 BGM 两版）。
+
+**交付物**：审查报告 + 成片两版（带 BGM + 无 BGM）。
+
+交付后先 `node workbench/scripts/open.mjs <工程目录>` 主动打开动效工作台（浏览器自动
+把成片拆成多轨，用户可视化微调后直接导出；见 `references/workbench.md`），再在最后按
+1-2-3 依次说三件事：① 发布时推荐（非强制）在简介 @ 一下
+skill 作者（三个平台账号都带链接）；② 邀请把成片放到作品展示页（用日常语言
+说，可留自己的账号）；③ 可以导出剪映工程文件（需要则读
+`references/jianying-export.md` 执行）。逐条口径与账号链接见 `SKILL.md`
+「交付收尾」。
+
+**常见坑**：
+
+- 把验收当"最后才做的事"：本阶段只是收口。若前五阶段没做静帧自检，
+  这里堆积的问题量会让 checklist 失去意义——验收贯穿全程是定式。
+- 自检报告流于"全部 ✓"：用户会读清屏幕上每个字、会自己截帧对比——
+  报告里每条结论都应附可复核的帧号/截图。
+- 制作 agent 自己出审查报告：确认偏差不可避免，独立 subagent 审查
+  不可省略。
+- 只查“好不好看”不查“是否符合当前模式的制作基准”：功能漏拍、视觉方向漂移、
+  镜头变体用错和未经确认的数据都属于终检失败。

package/lib/motion/shotcraft/upstream/references/publish-upload-post.md

@@ -0,0 +1,111 @@
+# 发布到社交平台：成片 → TikTok / Instagram / YouTube / LinkedIn / X …
+
+把交付的 MP4 一次发到 TikTok、Instagram（Reels 或 Stories）、YouTube（含 Shorts）、
+LinkedIn、Facebook、X、Threads、Pinterest、Bluesky，可立即发布或定时发布。
+脚本 `publish/upload_post.py`，通过 [Upload-Post](https://upload-post.com) API 完成，
+只用 Python 标准库（无需 venv / pip）。
+
+**触发时机**：只在用户**主动要求**把成片发到社交平台时执行（例如"帮我发到
+TikTok 和 YouTube"）。它不是交付收尾 1-2-3 之外的第 4 条推荐，不要主动推销。
+发布是公开且难以撤回的操作，**必须先让用户确认文案和平台清单**，再真正发布。
+
+> **说明**：Upload-Post 是第三方托管服务。免费版每月 10 次上传，覆盖上面除
+> TikTok 以外的全部平台（TikTok 需付费版）。只有用户配置了自己的 API key 时
+> 本流程才会联网。
+
+## 1. 一次性准备（用户操作）
+
+1. 在 https://upload-post.com 注册，创建一个 profile，把要发的社交账号连到这个 profile。
+2. 在后台创建 API key。
+3. 设置环境变量（或写进用户自己的 shell 配置）：
+
+```bash
+export UPLOAD_POST_API_KEY=...
+export UPLOAD_POST_USER=<profile 名>
+```
+
+缺这两个变量时，告诉用户以上三步，停下等待，不要尝试发布。
+
+## 2. 选文件与准备文案
+
+- **文件**：用交付的成片。配了 BGM 的片子有两版（带 BGM / 无 BGM），默认发
+  **带 BGM 版**；用户另有要求按用户的来。
+- **画幅**：TikTok、Reels、Shorts 要竖屏 9:16。成片是横屏 16:9 时如实告诉用户
+  （这些平台会加黑边或裁切），建议改发 YouTube / LinkedIn / X / Facebook，或另渲
+  一版竖屏。
+- **文案 `--title`**：在 TikTok / Instagram / X / Threads 上就是正文，按社交文案写
+  （钩子一句 + 2–4 个话题标签），不要写成 YouTube 标题。含 YouTube 时 ≤100 字符。
+  交付收尾第 1 条里用户若同意 @ 作者，把那句放进文案。
+- **长描述 `--description`**：YouTube / LinkedIn / Facebook / Pinterest 用。
+- **AI 声明 `--ai-generated`**：询问用户是否标注 AI 生成内容。成片由 Agent 以代码
+  渲染，一般不属于"逼真的合成影像"，默认不标；用了 AI 生成画面或 AI 配音时建议标。
+
+把「文案 + 描述 + 平台清单 + 定时（如有）+ 各平台隐私设置」整理给用户，
+**得到明确确认后**再进入下一步。
+
+## 3. 先 dry-run（不发布）
+
+```bash
+python3 publish/upload_post.py --video out/promo.mp4 --title "<文案>" \
+  --description "<长描述>" --platforms tiktok,instagram,youtube --dry-run --json-out
+```
+
+检查输出：`authOk` 为 `true`；`missingPlatforms` 非空说明这些平台没连到 profile，
+会被跳过，告诉用户去后台连接，或从清单里去掉。
+
+## 4. 发布
+
+去掉 `--dry-run` 重跑。脚本等待各平台结果（默认最多 10 分钟），逐平台输出链接或错误。
+
+- **每条发布命令只跑一次。** 无论超时、断网、报错还是 `status: "unknown"`，都**不要
+  重跑发布命令**，重跑会生成新的 request_id，同一视频会被发两次。只能查询：
+  `python3 publish/upload_post.py --status <requestId> --json-out`
+- 脚本如何区分：只有 **400 / 401 / 403 / 422**（服务端受理前明确拒绝）才判失败，此时
+  没有任何东西被发出去，修正参数后可以再发。5xx、网关错误、超时、断网、2xx 却无有效
+  JSON 都属于"不确定"，视频可能已被受理。脚本会自动用同一个 request_id 查询：查到就
+  照常继续；仍无法确认则输出 `status: "unknown"`（退出码 2）、`requestId` 和
+  `statusCommand`，并带 `doNotRerun: true`。
+- 脚本在**发送之前**就把 `request_id` 和对应的 `--status` 命令打到 stderr。进程中途
+  被中断时，用这条命令查询，不要重跑发布。
+- 定时发布（`--schedule 2026-10-01T09:00:00 --timezone Asia/Shanghai`）立即返回
+  `jobId` + `requestId` 和 `statusCommand`。定时任务按 **`jobId`** 查询：
+  `python3 publish/upload_post.py --status <jobId> --json-out`（输出里的 `statusCommand`
+  就是这条命令）。
+
+## 5. 向用户汇报
+
+每个平台一行：链接、或原因。
+
+| 平台结果 | 含义 |
+|---|---|
+| `completed` + `url` | 已发布。私密发布没有公开链接：YouTube 仍给出本人可看的链接，其他平台给 `postId` + `note` |
+| `skipped` | profile 没连这个平台，没有发 |
+| `failed` / `retryable` | `error` 是平台给的原因（如账号授权过期，去后台重新连接）；`retryable` 会由服务端自动重试 |
+| TikTok `inbox: true` | TikTok 把视频放进了草稿箱，需要用户在 TikTok App 里点发布 |
+| 整体 `status: "unknown"` | 无法确认是否已受理。原样告诉用户 `requestId`，稍后用 `statusCommand` 查询；**不要重跑发布命令** |
+
+## 6. 参数速查
+
+| 参数 | 说明 |
+|---|---|
+| `--video` / `--title` | 成片路径 / 各平台共用文案 |
+| `--description` / `--description-file` | 长描述 |
+| `--platforms` | `tiktok,instagram,youtube,linkedin,facebook,x,threads,pinterest,bluesky`（别名 `twitter` `reels` `shorts`） |
+| `--user` | profile 名，默认 `$UPLOAD_POST_USER` |
+| `--schedule` + `--timezone` | 定时发布（≤365 天），IANA 时区，默认 UTC |
+| `--first-comment` | 发布后自动发第一条评论 |
+| `--ai-generated` | AI 生成内容声明（TikTok / Instagram / YouTube / X） |
+| `--thumbnail` | 自定义封面（YouTube、LinkedIn） |
+| `--youtube-privacy` | `private`（默认）/ `unlisted` / `public` |
+| `--tags` | YouTube 标签，逗号分隔 |
+| `--tiktok-privacy` / `--tiktok-draft` | TikTok 隐私（默认沿用账号设置）/ 只存草稿 |
+| `--instagram-story` | 发 Stories 而非 Reels |
+| `--facebook-page-id` / `--linkedin-page-id` | 指定 Facebook 主页 / 以 LinkedIn 公司页发布 |
+| `--pinterest-board` | Pinterest 必填 |
+| `--status ID` | 查询之前的发布：即时发布用 request_id，定时发布用 job_id |
+| `--dry-run` / `--json-out` | 只校验不发布 / 输出一行 JSON |
+
+错误类型（`errorType`）：`auth`（key 缺失或错误）、`validation`（参数错误，或所选平台都没连接）、
+`forbidden`（套餐不支持，如免费版发 TikTok）、`quota`（频率或套餐上限）、`http`（网络 / 服务端）。
+
+离线单测：`python3 -m unittest publish/test_upload_post.py -v`

package/lib/motion/shotcraft/upstream/references/sequences/promo-energy-arc.md

@@ -0,0 +1,50 @@
+---
+name: promo-energy-arc
+一句话: 全片能量骨架——低开品牌 → 单主角立传 → 字卡呼吸间隔的功能爬升段 → 发布会峰值收场
+适用: 30–60s 多功能 web 产品宣传片的默认全片结构（分镜阶段先填骨架再挑卡）
+段数: 4 段位 + 2–4 张呼吸字卡
+---
+
+## 意图
+
+把散落在 R1–R3/Q5/Q8/P4 的节奏规则合成一条可直接填空的全片曲线。
+模板片成片（1085f）与两次独立复现（各 900f）三次成表均收敛到同一
+骨架——它是默认项，不是令：逐项目可有意识偏离，偏离写进项目 spec。
+
+## 段位表
+
+| 段位 | 时长占比 | 能量 | 职责 | 候选配方卡 |
+|------|----------|------|------|------------|
+| ① 品牌开场 | 8–12%（30s 片）；开场+立传合计可达 20%（模板片） | 低 | 字标压印 + hold ≥1s（R1），交棒产品页面 | brand-ink-open |
+| ② 单主角立传 | 12–15% | 中（质感最高、节奏最慢） | 一个主角、一条完整动作弧 ≥3s（Q5/R3），立出产品原子单位 | spotlight-hero-card（+aesthetic-rules.md Q2 高清 rasterize 技法） |
+| ③ 功能爬升段 | 55–65% | 中高⇄低交替 | 每镜绑一个独特功能、一种手法只当一次主角（P4）；镜与镜之间按需插呼吸字卡 | deck-deal-flyin / type-and-filter / list-stack-press / row-embed / document-typewriter-reveal |
+| ④ 发布会收场 | 13–16% | 峰值（全片最高） | 已展示功能各出代表元素合影围住字标（Q8），sign-off hold ≥1s（R1） | outro-group-photo-launch |
+
+呼吸字卡（paper-title-card）规则：每 1–2 个功能镜头后插一张，单张
+50–55f（≈1.8s），全片 2–4 张；重要功能出场前用作引导字卡（C2）。
+模板片 10 镜里字卡占 4 席，两次复现各 2 席——密度按功能镜头数取。
+
+## 填空流程（替代 ad-hoc 推导）
+
+1. 列产品功能清单（P4），数出功能镜头数 N。
+2. 按段位表分配总帧数：先扣 ①②④ 与字卡的预算，剩余给 ③ 均分。
+   每镜预算内**先划走 hold/rest 帧**（R1 落定 ≥30f、批量收尾 15f，R3）
+   再排动效——不是排完动效再找空隙。
+3. ③ 段能量交替：高能量镜（发牌/堆叠）与稳节奏镜（交互/读字段）
+   间隔排列，信息密度最高的镜头（文档/报告类）放在峰值收场之前——
+   模板片与两次复现均把文档/报告类镜头排在倒数第 2–3 位。
+4. 逐槽位扫 shots/ frontmatter 挑卡，选中的卡读全文。
+5. 镜头排定后逐接缝选转场式（shot-transitions 技法卡三式选型），
+   写进分镜表"关键动效"列——转场帧从相邻镜头预算划走。
+
+## 已知坑
+
+- 骨架当风格令全局硬套：段位占比是模板片单例实证（标注：单例判例），
+  15s 短片或单功能产品应大胆合并段位，但 ①hold/④峰值两端不可省。
+- ③ 段只堆高能量镜：连续高能量读作嘈杂，交替与字卡就是节奏本身。
+- 呼吸字卡写成第二遍 tagline：字卡与 outro 文案重复即删（P4 判例：
+  outro tagline 去重）。
+
+## 参考实现
+
+template/src/aifl/Main.tsx AIFL_SHOTS 段位表（sum=1085f）。

package/lib/motion/shotcraft/upstream/references/sfx-sourcing.md

@@ -0,0 +1,95 @@
+# Freesound 音效选材
+
+新制作与换音直接从 [Freesound](https://freesound.org) 获取 SFX，不再使用共享本地音效库。
+用户指定的音源仍优先。BGM 沿用独立选曲流程，见 [sound-design.md](sound-design.md) §2。
+本模块负责选材、下载与来源记录；钉帧、混音、输出偏移补偿继续按 sound-design 执行。
+
+## 1. 把画面写成声音需求
+
+每个 cue 记录：对应镜头/动作、声源或材质、目标时长、攻击/尾音、音色和许可要求。
+例如纸卡滑入：`paper slide`，0.2–0.8s，干燥、单次、无长尾、CC0。
+以声源匹配为先，再比较时长、录音描述与热度；不要只搜索抽象情绪或宽泛的 `click`。
+
+- 单击/滑动不要选混有多个动作的长段录音，除非能明确裁出所需动作。
+- 下载量与评分人数用于辅助排序，不能替代匹配度；大量评分的 4.4 分通常比 6 人评出的
+  4.9 分更有参考性。推荐时引用实际数据，缺失值保留未知，不能编造。
+- 上传者描述提供声源、设备、处理方式线索；优先清晰且匹配的实际声源。
+  名牌设备不保证质量，口技或内置麦克风也不自动意味着不可用，按项目质感判断。
+- UI 动作的拟音与合成提示音分开判断，遵守 aesthetic-rules S1/S4。
+
+## 2. 搜索
+
+脚本独立实现，Python 3.9+ 标准库，无需 Freesound API key；下载/分析需 ffmpeg、ffprobe。
+从 skill 根目录执行；路径含空格时加引号。安装在其他位置时用脚本绝对路径。
+
+```bash
+python3 assets/scripts/sfx-source.py search "paper slide" --max-duration 1 --limit 5 --output /path/to/video/audio-search.json
+python3 assets/scripts/sfx-source.py search "short cinematic impact" --license by --max-duration 3 --pages 2
+```
+
+输出 JSON 含 ID、标题、作者、素材页、预览地址、描述、时长、下载量、评分和人数。
+保留搜索相关性顺序，并在本地再次过滤许可与时长。`--pages` 最多 3 页，先缩窄关键词，
+不以抓取更多页面代替选材。搜索输出只用于比较，不作为下载时的许可凭据。
+
+许可默认 `cc0`；`by` 允许 CC0 和 CC BY。商用产品片不接受 BY-NC、Sampling+ 或未知许可。
+用户愿意接受署名时可用 `--license by`，无需对每条声音重复询问。
+
+## 3. 下载到当前视频工程
+
+把 ID 换成本次搜索返回的候选；`get` 也支持已知 ID，不依赖全局缓存。
+
+```bash
+python3 assets/scripts/sfx-source.py get fs:12345 fs:67890 --out-dir /path/to/video/public/audio/sfx
+```
+
+需要 CC BY 时在 `get` 上同样传 `--license by`。下载前重新读取各素材的详情页、
+核对实际许可 URL 与版本，再有界并发下载。不会修改网络代理，也不会自动切换其他音源。
+
+产物：
+
+- `fs-<id>.mp3`：Freesound 的高质量 **有损 MP3 预览**，不是上传者的原始 WAV。
+- `audio-manifest.json`：来源、作者、素材页、许可 URL/版本、预览标记、下载时间、
+  SHA-256、修改记录与实际音频分析。
+- `FREESOUND-CREDITS.md`：可随工程交付的来源与署名清单；CC BY 条目需进入发布页说明
+  或成片署名，不能仅留在工程文件中。剪辑、变速、归一化等改动需补写 `changes`。
+
+重复下载会核对文件哈希，不覆盖自行修改或来源不明的同名文件。每个输出目录同一时间
+只运行一个 `get`。部分下载失败时成功项仍保留清单，命令退出非零；根据逐条结果只重试失败 ID。
+无匹配候选时调整查询；网站超时/限流/页面结构变化时停止该来源的自动调用，说明具体问题。
+可给出素材页供人工下载，再按同样字段记录来源；不能用 HTML 错误页冒充音频。
+
+原音质或无损处理有明确要求时，从素材页走 Freesound 支持的登录/下载流程取得原文件；
+不能把预览转 WAV 后标成“原始无损素材”。记录真实文件种类、地址、哈希并重新分析。
+
+## 4. 分析、试听与接入
+
+`get` 自动用 ffprobe 与 ffmpeg 解码验收，记录实际格式/采样率/声道、时长、sample peak、
+整体 RMS、10ms RMS 能量峰和相对峰值 -40dB 的活动区间。这些不是 LUFS、true peak 或精确动作起点。
+多个动作的录音需要选择正确的峰值，不能直接将全文件最大峰用于所有 cue。
+
+单独分析处理后的文件：
+
+```bash
+python3 assets/scripts/sfx-source.py analyze /path/to/video/public/audio/sfx/fs-12345.mp3 --output /path/to/video/audio-analysis.json
+```
+
+处理后更新 manifest 的文件名、SHA-256、`analysis` 和 `changes`；原文件与处理后文件的
+峰值时间分开记录。浏览器试听或把候选垫入片段检查音色、底噪、尾音与音乐的关系。
+工具只有元数据/测量能力时，明确写“未试听”，不要将下载数、波形或 ffmpeg 分析描述成听感。
+自主创作可基于证据选定并继续；用户要求听候选时给素材页或支持的本地音频预览。
+
+随后将固定文件接入中央 SFX 表，`from` 从 `SHOTS`/`beatF` 派生，并根据
+sound-design §4.6 补偿音源峰值与输出偏移。下载文件必须随工程保存，不能只引用远程 URL。
+工作台显示工程音频；新增下载后重新运行 `node workbench/scripts/open.mjs <工程目录>` 更新索引。
+
+## 5. 模板与交付
+
+`template/public/audio/` 的历史文件保留供原样运行与验证，不作为新项目的选材池。
+用模板为新产品制作时，沿用 SFX 的动作语义和钉帧结构，从 Freesound 选音后重新测量、对齐；
+用户明确要求复现原声音时保留该要求，并按模板授权记录核实音源。
+共享 SFX 目录移除前的完整记录可从 Git 历史查询，BGM 授权仍在 `assets/audio/ATTRIBUTION.md`。
+
+交付音频文件、manifest、署名清单和 SFX 时间表。终检见 [final-review.md](final-review.md) A10。
+
+选材方法参考 [vibe-motion/sound](https://github.com/vibe-motion/sound)（查阅版本 `01f81d6`）；
+本仓库的 CLI 为独立实现，未引入其脚本或个人 Clash 配置。