overlays

覆盖层

路径：${CLAUDE_SKILL_DIR} 表示包含此 SKILL.md 的文件夹，${CLAUDE_PLUGIN_ROOT} 表示它上两级的插件文件夹。

先阅读 ${CLAUDE_PLUGIN_ROOT}/PRINCIPLES.md：真实事物承载每个节拍，不要有 AI 感；先流畅，再求变化；每个元素都要与其对应的口播词同步出现；绝不遮挡人脸；遵守安全区域。

向用户提出的所有问题都要放在问题框中：调用 AskUserQuestion 工具（提供 2-4 个选项，推荐选项放在第一位）。只有在不具备该工具的 Agent 中，才用文本提出编号问题。

在已由 style-edit 渲染过的编辑文件夹中修改。输出相同的编辑内容，只更改指定的节拍：重新规划、检查，并对有改动的部分重新渲染。其他内容必须与用户批准的内容完全一致。此技能不编写渲染器代码：它会修改 visuals.json 和 images.json，其余工作由 style-edit 的脚本和 Remotion 模板完成。为某个时刻新增卡片时，优先使用用户先添加的内容（edits/<name>/assets.json：来自 assets/ 的图片，或按 style-edit 步骤 1 的方式通过 site 指定的链接），之后再搜索素材。

在 Mac 和 Linux 上使用 python3 运行脚本，在 Windows 上使用 py。路径相对于资源库（PRINCIPLES.md 中的“位置”）。S="${CLAUDE_PLUGIN_ROOT}/skills/style-edit/scripts"， VPY="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/run.py"；python3 "$VPY" 是虚拟环境中的 Python。

edits/<name>/plan.json + render.mp4 (+ render.plan.json, the plan it was made from)
visuals.json / images.json  ->  plan.py  ->  stills-at/sheet.png  ->  edit.py patch  ->  check.py render  ->  review page

references/changes.md 列出了每种修改的精确命令、示意图制作方法，以及检查失败时的处理方式。阅读步骤中指定的章节。

0. 了解风格偏好和编辑内容

python3 "${CLAUDE_PLUGIN_ROOT}/skills/taste/scripts/taste.py" show --edit edits/<name>
python3 "$S/plan.py" cards edits/<name>

cards 会为每张卡片打印一行：card:N、时间、类型、词语、方框、图层，以及它对应的 visuals.json 或 images.json 节拍。card:N 是审核页面上的 [card N ...]；静帧表中的 “card N” 对应 card:N-1。绝不要直接读取 plan.json。

• 没有 render.mp4 或 plan.json？ 这是首次处理：使用 style-edit。
• 备注涉及剪辑（词语被截断、停顿）：使用剪辑技能。**备注涉及所有视频的字幕大小、字体或颜色：**先使用风格偏好技能，再使用 style-edit。
• 备注是适用于所有视频的偏好（“徽标总是小一点”“不要全屏示意图”）：在此处进行调整，并同时用风格偏好技能保存该规则。

1. 找到对应节拍

将用户的话与卡片对应起来：时间（“在 0:15”）、词语（“Duolingo 那张”）或审核备注（[card 1 logo 'Duolingo']）。只有一个明确匹配项：继续。匹配项有两个或更多，或没有匹配项：在问题框中提问，每个候选卡片列出一个选项（包含其时间、类型和词语），并将最接近的选项设为推荐项。

只更改用户指定的节拍。过程中绝不重新挑选、移动或重新设计其他卡片。 如果用户只说“减少卡片”，却没有指出具体卡片：列出承载信息最少的卡片（例如一闪而过的徽标、同一图片的第二次出现），然后询问要删除哪些，并推荐最弱的一张。

2. 进行修改

每个节拍执行一条命令。节拍可通过 card:N、时间（0:15、15.4s，当时显示的卡片或在 1.5 秒内开始的卡片）或词语（Duolingo；第二次说到时用 Duolingo@2）定位：

python3 "$S/plan.py" beat edits/<name> card:1 'box=[40,17,20,11]'      # move or resize (x, y, w, h in % of the frame)
python3 "$S/plan.py" beat edits/<name> 0:20 brand=Notion domain=notion.so   # swap the logo
python3 "$S/plan.py" beat edits/<name> YouTube@1 --drop                # fewer cards
python3 "$S/plan.py" beat edits/<name> --add edits/<name>/visuals.fill-1.json   # new beats, in spoken order

值可以是 JSON（或纯文本）；props.label=x 会在一个节拍内设置该属性；key=null 会移除一个键。一个捕获节拍同时存在于 visuals.json 和 images.json 中：beat 会同时修改两者。每种请求的处理方式（移动、放大、移出人脸、移出字幕、展示真实页面、为截图添加动画、变得更流畅、稍后出现）：见 references/changes.md 中的 “Requests”。

新视觉素材（动画、示意图、真实页面）：阅读 style-edit 的 ${CLAUDE_PLUGIN_ROOT}/skills/style-edit/references/motion-design.md（默认的视觉效果和动态效果：优先使用制作的动画而非静态捕获，每页一张捕获画面，并在频段中放大显示），然后按照所述内容，从 style-edit 的 ${CLAUDE_PLUGIN_ROOT}/skills/style-edit/references/shapes.md 中按顺序选择格式：用户自己的素材、捕获的真实内容、用真实部件重建的 UI、真实徽标。示意图应是由文中提到的真实徽标或捕获画面构成的 flow，在说到对应内容时点亮各部分，并作为叠加层放在头部旁边或上方：说话者始终留在画面中（见 references/changes.md 中的 “A diagram”）。绝不能使用文字面板、文字卡片、素材图标或用户未要求的全屏场景。若有多个新节拍，应并行分派：在一条消息中为每个节拍各分配一个 template-filler Agent，并提供编辑文件夹、对应句子、所选格式、出现时机对应的词语、style-edit 的 references/shapes.md 完整路径，以及各自的输出文件 edits/<name>/visuals.fill-<n>.json。然后用所有文件执行一次 beat --add。只有一个新节拍时：自行编写。

3. 获取，然后重新规划

node "$S/capture.mjs" edits/<name>          # only when a beat needs a new capture, logo or post; keeps files already fetched
python3 "$S/plan.py" edits/<name>/style.json edits/<name>/captions.json [--aspect ...] [--layout ...]

使用与该编辑的上一次规划相同的标志（第二种形状使用相同的 --out，之后的每条命令都使用 --plan plan-16x9.json）。plan.py 是确定性的：未修改的节拍会保持不变。覆盖 plan.json 前，它会将渲染计划保存为 render.plan.json。阅读有关你所修改节拍的每一条警告。如果配置文件启用了 behind，且有后置卡片被移动或添加，则运行 python3 "$VPY" "$S/matte.py" edits/<name>（它只会剪切新帧；如果卡片时长超过几秒，先查看其 --estimate）。

python3 "$S/check.py" plan edits/<name>

修复你所修改节拍上的所有 FAIL，然后重新规划。

4. 仅截取这些时刻的静帧

python3 "$S/edit.py" stills edits/<name> --at 15.4 --at 12.9-15.3

一个时间点对应一张静帧；一个时间范围对应五张（进入、到位、中间、后段、退出），用于评估动态卡片的帧。为每张修改过的卡片提供其时间范围（来自 plan.py cards），以及它前后各一个时刻。会写入 stills-at/ 和 stills-at/sheet.png，每个缩略图都会标注时间和当时显示的卡片。检查缩略图表；也交给 stills-critic Agent，并将它盲评的 reads_as 与该节拍应展示的内容进行对比。继续之前先修复问题：卡片挡住人脸、被字幕或应用按钮遮挡、文字在手机上太小、页面部分错误、呈现出 AI 风格、说话者未出现在画面中（用户未要求的全屏场景）。

• 修复（移动、调整大小、替换、删除）：继续执行步骤 5。
• 新视觉素材（动画、示意图、新页面）：展示缩略图表，并在问题框中询问： 渲染（推荐） / 修改内容。得到回答前不要渲染。

5. 补丁渲染

python3 "$S/edit.py" patch edits/<name>

它会比较 plan.json 和 render.plan.json，只重新渲染发生变化的片段（出口和声音尾音各延长 0.5 秒），在笔记本电脑上完成，然后将其拼接进 render.mp4；音频会按采样点剪切。它会输出片段范围和帧数。若视频大部分内容都发生了变化，则改为完整渲染；如果更改不是局部的（尺寸、视觉效果、动态风格、字幕样式），则会停止：此时按 style-edit 的步骤 6 询问渲染位置，并按其步骤 7 进行渲染。--range 13-15.5 可手动重新渲染某个片段（适用于没有 render.plan.json 的旧版渲染）。

6. 检查渲染结果

python3 "$VPY" "$S/check.py" render edits/<name>

如果 FAIL 出现在你负责的时刻，就回到第 2 或第 3 步；最多修复两轮，然后移交尚未解决的问题。如果 FAIL 与你负责的内容相距甚远，说明它之前就已存在：请说明这一点，不要在这里追查。每种 FAIL 的含义见 style-edit references/plan.md“检查中的 FAIL 和 WARN”。

7. 在审阅页面上移交

R="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/review.py"
python3 "$R" edits/<name> resolve <note> fixed --reply "moved the Duolingo logo above the caption" --new-t 15.4
python3 "$R" edits/<name> round --stage edit --video edits/<name>/render.mp4 --plan edits/<name>/plan.json

如果页面尚不存在，请使用相同的标志运行 start。然后在后台运行 serve 和 wait（见 style-edit references/review.md）。用一行告诉用户改了什么，以及内容在哪里。关于卡片的新备注交由此处处理；关于剪辑的备注交给剪辑技能。

如果脚本停止运行

消息	操作
no beat matches ...	运行 plan.py cards，并通过 card:N 选择卡片
no render.plan.json ... (edit.py patch)	使用 --range A-B 指定更改卡片附近的范围，或完整渲染
the change is not local (<key> changed)	完整渲染：style-edit 的第 6 和第 7 步
the plan is WxH, N frames; render.mp4 is ...	剪辑或画面尺寸已更改：完整渲染
warning: '<word>' ... never said	节拍的 word/nth 必须与 captions.json 中的拼写一致
capture.mjs failed <kind> '<word>'	换一个 URL，或改用徽标
check.py plan found a FAIL (stills)	修复你负责的节拍中的 FAIL，然后再次运行 plan
... missing (run matte.py)	运行 matte.py，然后再次运行 stills 或 patch

文件

• references/changes.md：每项请求对应的节拍更改、示意图配方和检查失败项。
• style-edit 的 scripts/：plan.py cards|beat（查找并更改一个节拍）、edit.py stills --at （时刻截图）、edit.py patch（重新渲染更改内容）、capture.mjs、matte.py、check.py。
• ${CLAUDE_PLUGIN_ROOT}/agents/template-filler.md（haiku，每个新节拍一个）、stills-critic.md（sonnet）、 render-watcher.md（运行时间较长的完整渲染）。