视频拆解分析：从用户喜欢的视频到命名技术和制作配方
这是 video-breakdown 0.4.1 版本。
用户有一个喜欢的视频，但无法说出其中使用了什么技术。你需要逐镜头地告诉他们每个转场、镜头运动、文字样式和声音的正确名称，实现该效果的 EditAtlas 技术，以及使用他们自己的素材制作类似效果的具体步骤。
全程需要遵循三个原则：
- 数字是提示，帧图像是证据。
analyze.py测量像素并采样。它可能会把冲击变焦误认为是拼接，把光圈转场误认为是渐隐为黑色，把老电影的闪烁误认为是切出。你命名的每个元素都必须来自你用 Read 工具打开的帧图像。请说明哪些是你仅通过测量得出的。 - 你无法听到声音。 音频数据只表示哪里发生了突发情况、音量大小、亮度高低和节奏快慢。它不能说明声音是什么。切勿为未经识别的瞬态声音写下“嗖的一声”；应写明“在 4.9 秒处出现一个短暂明亮的音效，与变焦音相近”。
- 切勿自行创造。 只能基于用户提供的文件开展工作。报告中出现的每个技术 slug 和声音 ID 都必须来自本次会话中 EditAtlas 的搜索或获取调用。如果没有匹配项，请如实说明。
脚本位于 scripts/ 目录下（需要 Python 3.9+、numpy、Pillow、以及包含 ffprobe 的 FFmpeg，且这些工具需在 PATH 中）。请在技能文件夹路径下运行它们，并在你自己的工作目录（work/）中执行；切勿写入用户的文件夹。
python SKILL/scripts/analyze.py VIDEO --out work/bd # 生成 breakdown.json + 帧图像图集
python SKILL/scripts/frames.py VIDEO --at 6.8 --span 0.6 --step 0.04 --out work/look # 获取拼接过渡的每一帧
python SKILL/scripts/frames.py VIDEO --at 7.9 --crop 0,60,100,40 --out work/look # 获取底部 40% 区域，用于阅读文本
python SKILL/scripts/text_look.py VIDEO --at 3.6 --crop 12,24,76,11 --text "Caringbah" --fonts sans-heavy --out work/text/title
python SKILL/scripts/report.py work/bd/breakdown.json work/bd/notes.json --out result/breakdown.md --check-api
当输入缺失时
- 只有链接，没有文件（TikTok、Reels、YouTube）：请用户下载视频并提供文件路径。此技能不会从平台获取视频。屏幕录制视频也可以。
- 完全没有视频：请用户提供。不要描述此类视频“通常”会有什么。
- 视频过长（超过 5 分钟）：
analyze.py默认只读取前 300 秒。请询问用户哪个部分是重点，或使用--max-seconds参数。
拆解分析旨在学习视频的编辑方法。配方应使用用户自己的素材；请勿建议复用参考视频的素材片段、音乐或角色。
1. 测量
运行 analyze.py。它会打印摘要并写入 breakdown.json 文件，包含以下内容：
| 部分 | 内容 |
|---|---|
format | 尺寸、形状（9:16、16:9）、帧率、时长 |
pacing | 镜头数量、每分钟拼接数、镜头中位数/最短/最长时长、前3秒内的拼接数、规律性 |
joins | 每次镜头切换：时间、长度、类型（cut、cross-dissolve、dip to black、white flash、bright flash、带有方向的 wipe、带有轮廓和方向的 shape wipe（一个扁平图形在画面上放大）、带有方向的 push or slide、zoom transition、blur transition、snap zoom or punch-in、jump cut、gradual (other)） |
shots | 每个镜头：测量的镜头术语（推进、快速变焦、摇晃、稳定、速度变化）、画面风格（黑暗、温暖、黑白、黑边、暗角），以及对于静止镜头的时机：元素进入画面所需时间、停留时间、离开方式 |
overlays | events：画面中某个区域发生变化而其余部分保持静止的时刻（文字、贴纸、图形出现或消失）；persistent：跨越镜头切换持续存在的区域（标志、边框、字幕栏） |
audio | 响度、类语音占比、节拍候选以及剪辑是否落在节拍上、瞬态（突发声音）及其最近的画面事件、渐强（进入高潮） |
每个数字的含义及其可能的错误：请参阅 references/reading-the-numbers.md。在每次会话进行第一次拆解前请先阅读该文档。
2. 观察
按以下顺序，使用 Read 工具打开：
overview.png：整个视频的 24 帧或更多（短视频每 0.15 秒一帧，长视频一秒一帧或更少）。首先了解故事和风格，以及每段文字出现的位置。shots_NN.png：每个镜头的第一帧、中间帧和最后一帧。检查每个镜头是否真实：冲击变焦、闪光或闪烁可能会将一个镜头分割成两个；源素材内部的溶解可能会看起来像拼接。joins_NN.png：每个非单纯切出的拼接过渡的六帧画面。根据这些帧命名转场类型。events.png：每个叠加事件前后的画面。这是字幕、贴纸和图形出现的地方。
然后在你不确定的地方使用 frames.py：--step 0.04（在 25 fps 下为一帧）跨越一个拼接过渡观察其形状，--crop 来阅读小文字或观察文字如何进入（弹出、弹跳、滑入、打字机效果），--times 来并排查看几个时刻。观察两到三次是正常的；一个效果较多的短视频可能需要更多次。
对照图像检查格式。一个 9:16 的视频，如果其镜头看起来像是从更宽的视频（电影、播客、游戏：面部和物体边缘被裁剪，每个画面中构图位置不同）中裁剪出来的，则属于重新构图：请说明这一点，并搜索 reframe to vertical。宽幅视频带有黑边则是信箱格式或立柱格式。
对于每个元素，在查找名称之前，先用通俗的语言写下你所看到的：“旧画面被压缩成一条水平线，而新画面在其后显示”，而不是“一个挤压”。
画面中的文字
文字是观众最先模仿的内容，也是重新制作时最容易出错的地方：使用了错误的字体类型，原作是渐变而复制版用了纯色，文字本应在人物后面却放到了前面。对于每段非纯字幕的文字，请找出以下五件事：
- 图层。 是否有物体或人物遮住了部分文字（头发遮住了单词底部，一只手挡住前方）？那么文字是在主体之后：
compositing-text-behind-object。查看它们重叠区域的裁剪图。检查每个标题，而不仅仅是第一个：同一个视频可能有多处文字位于主体后面。 - 入场动画。
frames.py --at <出现时间> --span 0.6 --step 0.04 --crop ...：观察文字是否带着运动模糊滑入（从哪一侧）、从上方掉落、弹出（缩放）、淡入、逐个打字出现、是逐字还是整体出现，以及文字落地后是否再次移动。当镜头运动时，叠加事件可能会漏掉文字出现的时间点；使用概览图找到这些时间点。 - 颜色。 在文字完全出现并静止后，裁剪出文字区域，运行
text_look.py。裁剪一行文字，并在四周留一点背景空白。它会输出填充色（纯色，或带有方向和十六进制色标点的渐变）、轮廓或偏移阴影、文字周围的光晕或暗色光圈，以及文字的倾斜角度。打开look.png：“taken as text” 必须仅显示文字，无其他内容。如果它取到了人脸或遗漏了部分渐变，请使用--text-clusters参数并指定属于文字的簇编号重新运行（其下方的面板会显示每个簇）。每个单词都可以有自己的颜色：请分别测量每个标题。 - 字体。 先描述字母形状：无衬线、衬线或手写体；对于手写体，是均匀笔触（刷子、记号笔、随意风格）还是粗下笔细上笔（正式、书法风格）；字重；直立或倾斜；大写或小写；宽或窄。
text_look.py会输出笔画粗细和对比度，这有助于区分书法手写体（对比度 2.2 或更高）和刷子手写体。然后添加参数--text "<显示的文字>" --fonts <分组>（--list-fonts可查看所有分组）以选择一两个匹配的字体分组，并通过肉眼比较字母：大写字母、a、g、t 的形状、连笔。匹配度数字对于无衬线和衬线字体有参考意义，但对手写体参考意义较弱。列出一两个免费的相似字体，并说明它们是相似字体，而非创作者使用的原始字体。 - 位置和大小： 文字所在位置、其高度占画面比例、以及停留时长。
设计好的动态效果
对于标志、标题、图表和图形动画视频，时机是让它们看起来完成度高的关键，也是重新制作时最容易出错的地方。阅读每个镜头的 timing（进入动画用时 0.7 秒，快速，然后稳定；在镜头时长的 71% 内保持静止；离开动画用时 0.8 秒，缓慢，然后加速）和 format.loops，在帧图像中验证这些数据，并将数字记录在元素的 seen 或 note 字段以及配方中。在纯色背景上，一个图形放大或出现可能被报告为拼接（jump cut、snap zoom、zoom transition）：如果背景保持不变，那么它就是该元素的入场动画。详细内容请参阅 references/reading-the-numbers.md 中的“设计的动态”部分。
3. 使用 EditAtlas 命名
对于每个元素，通过其结果而非猜测的名称进行搜索：
- 使用通俗的描述（“圆形闭合为黑色，然后打开”、“单词逐个弹入”、“向主体突然快速变焦”）调用
search_techniques。使用category参数限制范围（transition, captions, motion, vfx, color）。每个分析器标签对应的有效搜索词，请参考references/reading-the-numbers.md。 - 对最佳的一两个结果调用
get_technique，并保留描述与你观察到的情况相匹配的那个。精确复制其slug和name。将匹配程度标记为exact（完全匹配）、close（思路一致，细节有差异）或partial（部分匹配）。 - 音效：通过搜索时刻所需的声音效果（例如，文字出现用 pop，进入高潮前用 riser，推送效果用 whoosh）来调用
search_sfx。参考视频中的真实声音是未知的；你是在为相同的时刻推荐 EditAtlas 的音效，因此请说明。 - 调用
get_workflow并传入视频类型（short_vertical、product_ad、food_review等）以获取 EditAtlas 推荐的节奏和结构；将其与你测量的数据进行对比。
如果没有 MCP 工具，也可以通过 REST API 进行相同的搜索：https://edit.trysometh.ing/api/v1/techniques?q=... 和 /api/v1/sfx?q=...。
单纯的切出、说话片段或素材本身无需技术名称：使用 gap 说明即可。当 EditAtlas 中没有任何内容匹配一个真实存在的效果时，请在 gap 中写下你的搜索词；这能告知 EditAtlas 缺少了什么。
4. 编写笔记和报告
在 breakdown.json 旁边编写 notes.json 文件（格式和示例请参考 references/notes-format.md）：内容包括每个镜头的画面内容、每个元素及其时间点、通俗描述、证据和 EditAtlas 技术或音效、对测量错误的修正、制作配方，以及你未检查的项目。将 lang 设置为用户的母语（vi 或 en）。
运行 report.py ... --check-api。如果笔记跳过了某个镜头、某个元素没有给出技术名称或原因、或者遗漏了未检查的项目，该脚本会拒绝运行。使用 --check-api 参数可以确认每个 slug 和声音 ID 在 EditAtlas 上存在且名称匹配。请修正其列出的问题并重新运行。
交付
首先，进行版本检查。 如果 EditAtlas MCP 已连接，调用不带名称的 get_skill。如果它列出 video-breakdown 的版本高于 0.4.1，则你回复的第一行需要说明存在新版本以及如何更新（在 Claude Code 中：/plugin，然后选择 Marketplaces，再选 editatlas-skills，最后 Update marketplace；在其他环境中，使用名称 video-breakdown 调用 get_skill 会给出具体步骤）。如果没有 MCP 工具，则跳过此步骤。
用用户的母语向他们提供：
- 两到三句话：这是什么类型的编辑，以及它成功的关键点是什么（节奏、标志性效果）。
- 按时间顺序排列的元素及其名称和链接：报告中的表格，或其主要行。
- 制作配方：使用他们自己素材的逐步操作指南，技术按顺序列出。主动提出帮助他们进行编辑，这将从调用
get_workflow开始；对于音效，则涉及sound-design技能（调用get_skill）。 - 哪些是测量得到的，哪些是你实际观察的，哪些是未知的：创作者使用的实际字体（你提供的是免费相似字体）、精确的缓动曲线（
timing提供了持续时间和大致形状，而非具体曲线）、每个声音的实际内容、素材是拍摄的还是生成的。 - 报告文件（
result/breakdown.md）。
交付后，询问技术名称和配方是否正确，并在有 send_feedback 工具可用时将用户反馈发送出去。
参考资料
references/reading-the-numbers.md：每个测量指标、其已知错误，以及每个标签的搜索词。在每次会话进行第一次拆解前请先阅读。references/notes-format.md：notes.json 的字段以及一个完整示例。在编写笔记前请先阅读。