@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/video-shotcraft-vincentwei10/references/final-review.md

@@ -0,0 +1,116 @@
+# 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 句式是否成立（若分镜采用；sparkle 一拍取自 `sfx/light/`）；
+- A5：长样本（>5s，库里 21 个）是否都显式给了 `durationInFrames`，有没有音效拖到动作结束后还在响；
+- A6：每条 SFX 在**渲染产物**里是否真的听得见（不看预览——预览把 volume 钳到 1.0）；本身录得轻的素材（峰值 <-12dB，库里 7 个）即便给 1.0 仍可能被 BGM 盖住，是否已换素材／预归一化／给足 >1 的增益，且渲染后 max_volume 未削波；
+- A7：UI 类音效是否为真实物件质感而非合成反馈提示音（S1 判别问句）——`sfx/ui/` 中 `ui-confirm-*` `ui-*-tone` `ui-notify-*` 等合成音若出现在成片，是否有“系统在说话”的叙事理由并已写入项目说明文档（逐文件质感表见 sound-design 3.3）。
+- A8：配了 BGM 的片子是否交付了带 BGM / 无 BGM（保留 SFX）两版成片，
+  且两版出自同一时间线（无 BGM 版画面与 SFX 与带 BGM 版逐帧一致）；
+- A9：卡点/SFX 密集片是否对成片实测并补偿了输出音轨偏移与音源峰值
+  滞后（sound-design §4.6），补偿常数是否附实测记录（渲染管线四要素、
+  探针、测法、日期），源分析值与输出偏移是否分开记账（SOURCE_BEAT0
+  未被污染）；渲后回测误差表是否无系统性同向偏移（music-beat-sync §5b）。
+
+### Q — 视觉技术质量
+
+完整执行 `aesthetic-rules.md`。至少检查文字锐度、构图、圆角遮罩、3D 纹理
+清晰度、元素落位、相机抖动、转场接缝、光效廉价感、可读时长和确定性渲染。
+
+## 报告格式
+
+每条结论使用编号，并给问题附帧号或截图：
+
+```text
+P1 ✓ 产品定位和核心卖点清楚。
+F2 ✗ 第 340 帧：已确认的知识图谱功能没有出现在成片。
+V3 ✗ 第 420 帧：大面积琥珀纸张材质偏离已确认的深蓝科技方向。
+S2 ✗ 第 515 帧：用户选择 whip-pan，实际实现为 flash-cut。
+Q2 ✗ 第 615 帧：3D 推近后正文文字发糊，见关键帧 f615.png。
+```
+
+最后按严重程度列出必须修复项、建议优化项和无法验证项。不要用没有证据的
+“整体不错”代替逐项检查，也不要为了报告好看而全部标记通过。

package/skills/video-shotcraft-vincentwei10/references/guided-free-creation.md

@@ -0,0 +1,199 @@
+# 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/`
+   若无 mp4，先跑 `gallery/fetch-media.sh` 从 release 拉取，或直接用在线
+   Gallery 对应链接），并在设计 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
+当前阶段：
+已确认：
+本轮需要确认：
+确认后交付：
+```

package/skills/video-shotcraft-vincentwei10/references/jianying-export.md

@@ -0,0 +1,183 @@
+# 剪映工程导出：成片 → 可编辑的剪映草稿
+
+把 Remotion 时间线导出为剪映（CapCut 国内版）工程文件，用户可在剪映里
+继续改字幕内容/字号/颜色、对每个镜头变速/重排/调色、调整或替换 SFX 与
+BGM。镜头内部动效（逐帧程序渲染）超出剪映的素材+关键帧模型，只能烘焙。
+
+**触发时机**：任何模式下成片交付后，作为「交付收尾」三件事的第 3 条告知
+用户一次——成片可以导出剪映工程文件（在剪映里改字幕、变速、换音频）。
+用户要求时执行本文档流程；用户明确点名"导出剪映工程"时直接执行，不再确认。
+
+**平台前提**：Mac 版剪映专业版 11.2 实测通过（`jianying-export/mac_draft.py`）；
+Windows 版按上游支持路径实现但未真机验证（`windows_draft.py`），首次使用
+先做冒烟测试（见 §6）。剪映打开明文草稿后会升级加密保存——**单向转换**，
+要改就改导出脚本重装（幂等覆盖），不要试图读回剪映改过的草稿。
+
+## 1. 分层原则：什么可编辑、什么烘焙
+
+| 层 | 剪映里的形态 | 可编辑度 |
+|---|---|---|
+| 镜头内动效（运镜/粒子/3D/逐元素编排） | 烘焙进底片 | 仅整段变速/调色 |
+| 镜头边界 | 底片按镜头切段（同一文件不同 source_timerange） | 变速/重排/删减 |
+| 屏幕空间字幕/解说 | 剪映原生文本轨 | 内容/字号/颜色全开 |
+| SFX / BGM | 剪映音频轨（带音量） | 全开 |
+| 用户点名的独立元素（logo/计数等） | 可选：画中画图层 | 位置/大小/透明度 |
+
+品牌动效时刻（标题贴位、logo lockup 等定制编排的文字）默认烘焙——拆成
+剪映文本会丢掉调校过的入场动画；用户明确要求可编辑时才拆，并说明代价。
+
+## 2. plate 底片渲染
+
+给 Remotion 项目加一个 `plate` inputProp，渲一版**无字幕、无 SFX、无 BGM**
+的干净底片。字幕组件用 `getInputProps()` 网关（不必层层传 prop）：
+
+```tsx
+// 字幕组件顶部
+import { getInputProps } from 'remotion';
+const { plate } = getInputProps() as { plate?: boolean };
+if (plate) return null;
+```
+
+```tsx
+// Root 里音频统一 gating
+{bgm && !plate && <Audio src={staticFile('audio/bgm.mp3')} volume={0.72} />}
+{!plate && SFX.map(...)}
+```
+
+```bash
+npx remotion render src/index.ts <CompId> out/plate.mp4 \
+  --props='{"bgm":false,"plate":true}'
+```
+
+渲后抽帧对比原片同帧（ffmpeg -ss）：确认字幕已剥离、其余视觉逐帧一致。
+
+## 3. 时间线数据提取
+
+从 Remotion 工程的常量表（`theme.ts` 的 SHOTS / Main.tsx 的 CAPTIONS、
+SFX 表）提取三张表，**拍号网格在 Python 里精确复算**，不要抄注释里的
+约数帧号：
+
+```python
+FPS = 30
+BEAT0, BEAT_T = 0.0538, 0.47609        # 与 theme.ts 完全一致
+def beatF(n): return round((BEAT0 + n * BEAT_T) * FPS)
+def f2us(f): return round(f * 1_000_000 / FPS)   # 帧 → 微秒
+```
+
+- **镜头表** `(名称, from帧, to帧)`：抄 SHOTS 定义（含钉真实瞬态的非整拍
+  边界）。
+- **字幕表** `(中文, 英文, from帧, to帧)`：抄各镜头字幕组件的实参；
+  **相邻镜头同文案合并为一段**（原片的跨镜头延续）。
+- **SFX 表** `(文件, 目标拍, 峰值秒, 音量)`：抄 Root 的钉帧表。剪映按
+  摆放位置播放，**不要带上 Remotion 侧的输出音轨偏移补偿**（那补的是
+  Remotion 渲染输出链路的编码偏移，见 sound-design §4.6，与剪映播放
+  无关）：`start_f = beatF(拍) - round(峰值秒 * FPS)`。
+  长样本的显式截断时长（如 impact 留混响尾）照抄。
+
+**微秒边界铁律**：相邻段的 Timerange 必须"起点/终点各自取整再相减"
+（`Timerange(f2us(f0), f2us(f1) - f2us(f0))`）。起点和时长分别取整会产生
+1µs 级缝隙/重叠，pyJianYingDraft 直接报 SegmentOverlap。
+
+## 4. 建轨（pyJianYingDraft 0.3.x）
+
+环境：`python3.11 -m venv .venv && pip install pyJianYingDraft`，
+封面抽帧需要 ffmpeg。建轨骨架（synapse-promo-v2 验收版蒸馏）：
+
+```python
+import pyJianYingDraft as draft
+
+folder = draft.DraftFolder(STAGING)          # 先建到暂存目录，装库是独立步骤
+script = folder.create_draft(NAME, 1920, 1080, fps=FPS, allow_replace=True)
+script.append_track(draft.TrackSpec(draft.TrackType.video, name="底片"))
+script.append_track(draft.TrackSpec(draft.TrackType.audio, name="BGM"))
+script.append_track(draft.TrackSpec(draft.TrackType.text, name="字幕EN"))
+script.append_track(draft.TrackSpec(draft.TrackType.text, name="字幕ZH"))
+
+# 底片切段：source=target 同区间 → 每段可在剪映单独变速/重排
+plate = draft.VideoMaterial(PLATE)
+for _name, f0, f1 in SHOTS:
+    rng = draft.Timerange(f2us(f0), f2us(f1) - f2us(f0))
+    script.add_segment(draft.VideoSegment(plate, rng, source_timerange=rng),
+                       "底片")
+
+# SFX：Remotion 重叠音频自动混音，剪映同轨段不可重叠 → 贪心分道
+sfx_segs = []
+for file, beat, peak_sec, volume in SFX:
+    mat = draft.AudioMaterial(os.path.join(SFX_DIR, file))
+    start_f = max(0, beatF(beat) - round(peak_sec * FPS))
+    dur_us = min(f2us(截断帧数), mat.duration, f2us(TOTAL_F - start_f))
+    sfx_segs.append((f2us(start_f), dur_us, mat, volume))
+lanes, placed = [], []
+for start, dur, mat, volume in sorted(sfx_segs):
+    lane = next((i for i, end in enumerate(lanes) if end <= start), len(lanes))
+    if lane == len(lanes): lanes.append(0)
+    lanes[lane] = start + dur
+    placed.append((lane, start, dur, mat, volume))
+for i in range(len(lanes)):
+    script.append_track(draft.TrackSpec(draft.TrackType.audio, name=f"SFX{i+1}"))
+for lane, start, dur, mat, volume in placed:
+    script.add_segment(draft.AudioSegment(mat, draft.Timerange(start, dur),
+                                          volume=volume), f"SFX{lane+1}")
+
+# BGM 一段（音量照抄 Root）
+bgm = draft.AudioMaterial(BGM)
+script.add_segment(draft.AudioSegment(
+    bgm, draft.Timerange(0, min(bgm.duration, f2us(TOTAL_F))), volume=0.72),
+    "BGM")
+
+# 双语字幕拆两轨：一个文本段只能一种字号，中文大英文小必须分开
+for zh, en, f0, f1 in CAPTIONS:
+    rng = draft.Timerange(f2us(f0), f2us(f1) - f2us(f0))
+    script.add_segment(draft.TextSegment(zh, rng, **ZH_STYLE), "字幕ZH")
+    script.add_segment(draft.TextSegment(en, rng, **EN_STYLE), "字幕EN")
+script.save()
+```
+
+**字幕样式换算**（Mac 11.2 实测标定）：
+
+- 剪映 `TextStyle(size=…)` 单位 ≈ **画布高度百分比**：size 15 渲出
+  ≈150px @1080p。CSS 像素字号 ÷ 10.8 ≈ 剪映 size（64px → 6.0）。
+- `ClipSettings(transform_y=t)` 按半高归一，`屏幕y = 540 × (1 − t)`：
+  底部字幕区 t ≈ −0.70（y≈915）/ −0.825（y≈985）。
+- scrim 底用 `TextBackground(color="#FFFFFF", alpha=0.82, round_radius=0.35)`；
+  颜色是 0–1 浮点三元组（#2C2C2C → (0.173,)*3）。
+- 字体不指定则用剪映默认；导出后提醒用户可在剪映里换字体微调——字号/
+  位置是近似值，用户反馈后调参重装收敛。
+
+## 5. 装进剪映草稿库
+
+```python
+import mac_draft                      # Mac；Windows 用 windows_draft
+info = mac_draft.macify(draft_dir, DRAFT_NAME)   # Mac 三坑适配+媒体打包
+bak = mac_draft.install(draft_dir, DRAFT_NAME, info)
+```
+
+Mac 版三个坑（mac_draft.py 已全部处理，改模块前必读其 docstring）：
+入口文件名 `draft_info.json`；meta 的 `draft_materials(type 0)` 必须登记
+全部媒体（否则弹"媒体丢失"）；沙盒应用只能访问 `~/Movies`，媒体必须打包
+进草稿 `Resources/`（否则"暂无访问权限"）。
+
+Mac 版 platform 需要本机设备指纹（device_id 等），模块自动从草稿库里仍为
+明文的老草稿抄取。**全新机器往往没有明文老草稿，此时 macify 会明确报错
+中止**（无指纹草稿能否被剪映加载未经实测）——按报错提示传 `donor_draft`
+或实验性传 `allow_missing_fingerprint=True`，并把实测结果反馈回模块注释。
+
+Windows 版：`windows_draft.install(draft_dir, DRAFT_NAME)`，无注册表，
+列表不刷新就重启剪映。
+
+**安装前必须让用户完全退出剪映**（Cmd+Q；osascript quit 会被剪映忽略，
+不要强杀）。安装脚本已内置运行检测。卸载：`mac_draft.uninstall(名称)`。
+
+## 6. 验收
+
+1. 脚本自检：读装好的 `draft_info.json` 核对轨道数/段数/时长，媒体登记
+   逐条 `os.path.exists` 且路径都在草稿目录内。
+2. 用户端三查：整片播放连贯、SFX 卡拍；双击字幕改文字/字号/颜色；
+   任选一段底片变速。
+3. 新机器/新剪映版本首次使用：先跑 `jianying-export/smoke_test.py`
+   （最小三轨草稿注入），确认打开无"内容已损坏"、无"媒体丢失"再做正片。
+4. 交付时说明：剪映保存后草稿被加密（单向）；想改字幕方案/镜头切分，
+   回导出脚本改参数重装。
+5. **隐私**：Mac 版草稿的 platform 字段含本机设备标识（device_id/
+   hard_disk_id/mac_address）。自包含草稿目录**不要直接分发给他人**——
+   对外只交付渲出的成片；确要给别人可编辑工程，在对方机器上重新导出。