clips

Clips

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

请先阅读 ${CLAUDE_PLUGIN_ROOT}/PRINCIPLES.md：此插件中的每个视频都遵循这些规则（提问、真实感、动态、故事与构图、隐私、成本）。

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

输入一段长视频，输出几个最精彩的短片段，每个都是符合用户风格的完整竖屏剪辑。

clips/<name>/
  source.mp4          the long video (a symlink for a local file; never modify the original)
  source.mp3, cover.jpg  instead, for an audio-only podcast: its audio and the show's artwork
  words.raw.json      one transcript of the whole thing (never read it)
  candidates.json     every candidate with its features (never read it)
  shortlist.md        the top 8 that do not overlap, about 1,500 tokens: the only file you read
  shortlist.json      the same, for the page
  picks.html          the page the user picks from
edits/<name>-clip<N>/ one edit per chosen clip: source.mp4, words.raw.json (re-timed), clip.json

在 Mac 和 Linux 上使用 python3 运行脚本，在 Windows 上使用 py。 PY="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/run.py"；下面的 python3 "$PY" 会运行编辑器的 venv Python（Windows 上使用 py "$PY"）。 如果文件不存在，请先运行 setup 技能。K="${CLAUDE_SKILL_DIR}/scripts/clips.py"， C="${CLAUDE_PLUGIN_ROOT}/skills/cut/scripts"，S="${CLAUDE_PLUGIN_ROOT}/skills/style-edit/scripts。

0. 只询问一次

先读取用户的档案和品味（python3 "${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/profile.py" show、 python3 "${CLAUDE_PLUGIN_ROOT}/skills/taste/scripts/taste.py" show）。如果还没有档案：先运行 start 技能的风格采集流程，确保片段符合用户的风格。

然后调用一次问题框，推荐选项放在第一位：

问题	选项
要几个片段？	3（推荐）/ 5 / 1
每个片段要多长？	20-40 s（推荐）/ 40-60 s / 60-90 s
有几个人说话？	一人（推荐）/ 两人（播客或访谈）

跳过用户已经回答的问题。这些问题取代剪辑技能中的“先剪一段还是一次剪完”问题：片段会直接连续处理，用户再确认挑选结果和静帧表。

1. 视频

本地文件（同一磁盘上使用硬链接，否则使用符号链接，最后才使用副本）：

python3 "${CLAUDE_PLUGIN_ROOT}/skills/clips/scripts/clips.py" link "<absolute path>" clips/<name>

链接：

python3 "${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/links.py" fetch "<url>" clips/<name> --max-height 1080

它会使用 venv 中的 yt-dlp（setup 会将其安装在 venv 中，而不是 PATH 中），将下载画质限制为 1080p（1080x1920 的片段无需 4K；20 分钟的 4K 演讲会占用数 GB 空间），并打印文件路径： clips/<name>/source.mp4。退出码 3：该网站要求登录（YouTube 会提示“确认你不是机器人”）。 重新运行并添加 --cookies-from-browser chrome（或用户使用的浏览器）前，先在问题框中询问。 播客（RSS feed 或 Apple Podcasts 节目链接）：route 会将最新剧集列为 ask 选项；在问题框中询问用户要哪一集（最新的排在前面），然后运行 fetch "<option url>" clips/<option name> --direct --cover "<option image>"： 音频会保存为 source.mp3（或其原始扩展名），节目的封面图会保存为 cover.jpg。 只下载用户有权重复使用的内容：用户自己的视频，或已获许可的视频。如果链接指向他人的内容，只需提醒一次。

2. 只转录一次

python3 "$PY" "$C/transcribe.py" clips/<name>/source.mp4 clips/<name>/words.raw.json   # the file fetch printed: source.mp3 for audio

先说明耗时：在笔记本电脑上，Whisper 每 3 分钟视频需要 1-4 分钟（免费）；13 分钟的视频用 Scribe 大约需要 20 s。使用的引擎与剪辑技能相同。Scribe 还会标注笑声和其他音频事件，评分会用到这些信息。 所有片段都会重复使用这份转录稿：不会重复转录。

3. 候选片段与入围名单

python3 "$K" candidates clips/<name> --min 20 --max 40 [--speakers 2] [--style creator-teardowns/<handle>/style.json]

传入用户选择的时长。--style 是配置文件中的首位创作者；入围名单中会列出据此测得的“有效做法”。 代码会将转录文本拆分为句子，把时长范围内的每段连续完整句子都作为候选片段（不会以“Mm-hmm”开头，也不会在单词中间结束），测量每段候选片段，根据特征排名，并写入 shortlist.md。

只阅读 shortlist.md。每个条目都包含钩子、每个中间句子的开头词语、最后一句以及测得的特征。根据四个问题评判每个条目：钩子单独是否有效？陌生人能否听懂？内容是否有回报？是否包含具体的观点、数字或故事？

绝不要读取 words.raw.json 或 candidates.json。从入围名单中按优先顺序选出用户要求数量的片段。无论分数如何，都应剔除：

• 广告口播、赞助内容、开场白或结束语；
• 依赖此前语境的钩子（“正如我所说”“这就是为什么”“这个”）；
• 观点属于过时说法的片段（“录制时，它排第 40 名”），如果此后说法已变更：实时采集当前页面会与之矛盾。

4. 先展示精选页面，再提问

python3 "$K" page clips/<name> --recommend c12,c40,c7
open clips/<name>/picks.html    # Windows: start "" ..., Linux: xdg-open ...

单页展示所有入围片段，每段都附带 360 px 预览、转录文本（钩子加粗）、评分细目和测得的特征，并标出你的精选。然后在问题框中提问（多选）：先列出你的精选，每个选项标注时间和钩子，再加上“页面中的另一个片段”。等待回答。

5. 每个选定片段

python3 "$K" trim clips/<name> c12 c40 c7          # -> edits/<name>-clip1, -clip2, -clip3

每个剪辑文件夹都会获得 source.mp4（帧级精准，留有余量且不会截到下一个词）和重新对齐时间的 words.raw.json。纯音频来源（source.mp3）没有画面：trim 会将每个片段的音频作为其 source.mp4，并配上播客自带的封面（封面模糊并调暗，以填满 1080x1920，清晰封面置于字幕上方；没有封面则使用黑色画面），且 clip.json 中会写明 audio_only。有封面时，渲染会让封面动起来：缓慢推近封面，背景相对封面漂移，每句开头轻微放大。对于这些片段，不要询问布局：overlay、reframe no、no cutout、captions on（profile.py style 会保持字幕开启）。只需说明一次：每个片段都是以节目封面为背景的音频，并配有说话者台词字幕。在处理片段前，统一确定所有片段的配乐（style-edit references/plan.md 中的 "Music"；除非用户设置了 sound.music，否则由样式决定）。

同时处理所有片段（Claude Code，或任何带有子 Agent 的 Agent）：每个片段启动一个 clip-editor Agent（ai-editor:clip-editor），在一条消息中启动全部 Agent，让它们同时运行。向每个 Agent 提供 EDIT（片段文件夹的绝对路径）、ROOT（${CLAUDE_PLUGIN_ROOT}）、PY 行，以及这些选项的答案： 画面比例、布局、配乐、转录引擎、是否 reframe（宽幅来源需设为 yes，除非平台是 YouTube）以及来源是否已烧录字幕。每个 Agent 都会将片段从剪辑处理到 style-edit，再生成静帧表，并返回简短的 JSON：status、cut_s、verify、cut_page、sheet、error。合并这些结果；绝不要打开片段的转录稿或纸上剪辑稿。然后，对每个状态为 ready 的片段运行 stills-critic Agent，同样在一条消息中启动全部 Agent，并修复它们指出的问题（该片段重新生成计划和静帧）。状态为 failed 的片段：按下文手动处理。

逐个处理（不使用子 Agent），按顺序处理每个片段：

1. 从宽幅视频转为竖屏：python3 "$PY" "$K" reframe edits/<name>-clip<N> 会裁切为 9:16，并逐镜头跟随说话者的头部画面（使用 ffmpeg 查找镜头切换）。如果配置文件的平台是 YouTube，或来源已经是竖屏，则跳过。
2. **剪辑：**使用其第 2 步中的剪辑技能（retakes.py propose）：转录稿已经准备好。 然后按该技能的说明构建、渲染、验证并生成剪辑页面。语音下的配乐按文件测量：build_timeline.py 只会在词语之间裁剪。
3. **样式：**运行 python3 "${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/profile.py" style edits/<name>-clip<N>， 然后使用其第 2 步中的 style-edit 技能。如果来源已经烧录字幕，则在该剪辑的 style.json 中设置 "captions": {"present": false}，否则字幕会叠在一起。

无论采用哪种方式，都要打开每个片段的 cut-check.html，并将所有静帧表放在一起展示，以便一次性审批；只询问一次是否渲染所有片段，然后进行渲染。审批后，对每个片段的文件夹运行 python3 "${CLAUDE_PLUGIN_ROOT}/skills/cut/scripts/judge_cut.py" score（剪辑参考 references/judge.md）。在一个 审阅页面上交付渲染结果，每个片段一个标签页（第 1 个片段使用 start，其余使用 alt，文件夹为 clips/<name>；参见 ${CLAUDE_PLUGIN_ROOT}/skills/style-edit/references/review.md），然后在后台运行 serve 和 wait。

如果脚本停止运行

消息	操作
no run of whole sentences lasts <lo>-<hi> s	在问题框中询问是否可以放宽时长范围，然后再次运行 candidates
no candidate <id>	使用 shortlist.md 中的一个 ID
links.py fetch exit 3（需要登录或出现“confirm you're not a bot”）	询问后再使用 --cookies-from-browser <browser> 重新运行
任何剪辑或 style-edit 消息	查看对应技能中的 "If a script stops" 表格

规则

1. 屏幕上的每个词、数字和名称都来自该片段本身的内容。不包含视频其他部分的内容，也不包含说话者未说过的内容。
2. 不得有 AI 痕迹：${CLAUDE_PLUGIN_ROOT}/skills/style-edit/references/ai-tells.md 适用于每个片段。
3. 播客特写画面没有多余空间：卡片或徽标不得遮住头部。画面元素越少越好；字幕和缩放效果足以承载内容。
4. 切勿在句子中途剪断片段。比要求更短或更长，也好过打断表达。

每个长视频的成本

在一段 13 分钟的双人播客和一段 12 分钟的真人出镜视频上测得（2026-10）：

• 转录：Scribe 用时 16-18 秒；Whisper 免费，但速度较慢。每个长视频处理一次。
• 候选片段和特征：4-6 秒代码，$0。
• Claude 阅读 shortlist.md（约 1,500 个 token），而不读转录文本（约 20,000 个 token）。
• 候选片段页面：8 个预览需要 30-40 秒的 ffmpeg 处理，文件大小为 7-9 MB。
• 每个片段的成本相当于一次剪辑加一次风格编辑。

自检

python3 "$K" demo

文件

• scripts/clips.py：候选片段、页面、裁剪、重新取景和离线演示（合成转录文本）。 仅使用标准库，reframe 除外（通过 venv 使用 OpenCV）。
• ${CLAUDE_PLUGIN_ROOT}/agents/clip-editor.md：对一个片段进行剪辑和风格编辑，并生成静帧表。