cut

剪辑

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

先阅读 ${CLAUDE_PLUGIN_ROOT}/PRINCIPLES.md：此插件中每个视频都遵循的规则。

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

edits/<name>/  transcript.txt (read this, never words.raw.json), spans.json (what to remove, quoted),
  candidates.md (what code flagged), paper-edit.md (the cut as text), cut-check.html (the
  transcript), review.json (notes), cut.mp4 + words.json (the render and its words).

<name> 是文件名的 slug（IMG_1234.MOV -> img-1234），位于素材库中（PRINCIPLES.md「位置」）。绝不要修改、移动或复制源文件：传入它的路径。

PY="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/run.py"；python3 "$PY" 会运行工具虚拟环境。在 Windows 上，这些命令中的 python3 都用 py 替代。 还没有虚拟环境：先运行 setup 技能。S="${CLAUDE_SKILL_DIR}/scripts"。

还没有视频？

询问素材文件的路径。如果有多个文件：查看 references/takes.md。如果没有：提供示例素材（原始、竖屏，保留重拍、说错和停顿），并将其下载到用户的文件夹：

curl -L -o sample-take.mp4 https://github.com/nextwork-projects/ai-video-editor-cooked/releases/download/sample-video/sample-take.mp4

0. 询问：先剪辑，还是一次完成所有工作

在做任何其他事情之前，在问题框中提一个问题（开始时的选择适用于整个剪辑）：

你想先只剪辑，还是一次完成剪辑和风格化编辑？

• 先只剪辑（推荐）。 我会先让你确认剪辑，再添加字幕、缩放或视觉元素。这样，剪辑有变动时就不必重新生成视觉元素（可节省 token）。
• 一次完成所有工作。 我会先剪辑，然后不等确认就继续做风格化处理。渲染任何内容之前，你仍会看到剪辑页面和静帧表。

只有当用户已经回答过（“只剪辑”“一次完成剪辑和风格化处理”），或 start 或 clips 调用了此技能时，才跳过此步骤。先只剪辑：执行步骤 1-6，然后停止，直到用户批准剪辑并要求进行风格化处理。**一次完成所有工作：**执行步骤 1-5，打开剪辑页面，然后直接继续进行风格化编辑；之后如果剪辑有变动，则从计划步骤重新运行风格化编辑。

0b. 了解用户的偏好

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

遵循其中的每条规则。重新处理前，使用 taste 技能记录用户对结果的反馈（如“太慢了”）。

1. 转录

python3 "$PY" "$S/transcribe.py" <source> edits/<name>/words.raw.json [--script <their script>]

提供脚本（或可重复使用的 --keyterm Name）可提高姓名和术语的识别准确度（Scribe 的效果提升 20%）。

先说明所需时间：3 分钟的素材用 Whisper 需要 1-4 分钟，CrisperWhisper 大约需要与素材时长相同的时间。有已保存的密钥时会选择 Scribe；否则，如果已安装，则选择 CrisperWhisper；再否则使用免费的本地 Whisper（可通过 --engine whisper|crisper|scribe 覆盖），它会丢弃一些语气词和说错的部分。如果这些都没有，只需说明一次，setup 可以安装其中一种（CrisperWhisper 的权重仅可用于非商业用途）。编辑过程中绝不下载模型：如果重新检查需要尚未安装的模型（退出代码 4），则跳过，并在本轮备注中说明。

绝不要读取 words.raw.json：步骤 2 会写入 transcript.txt，文件大小只有它的 1/12。

2. 决定剪掉什么

python3 "$S/retakes.py" propose edits/<name>

代码会将所有可能要剪掉的内容（重复的句子、没说完的句子、“等等，抱歉”、填充词）写入 candidates.md。每一项只是需要查看的位置，不是剪辑决定。阅读 transcript.txt 和 candidates.md，遵循 references/retake-detection.md，并编写 spans.json （参见 references/shapes.md）。

如果有 script.md：运行 python3 "$S/script_match.py" edits/<name>，并阅读 script-match.md（参见 references/script.md）。

保留最后一次录制的内容，备用开场白除外。绝不要手动输入时间戳或片段。

只有在用户希望缩短时（或用户的偏好要求进行编辑审查时），才同时阅读 references/editorial-rules.md 并添加 redundant 剪辑（内容取舍）。

听错姓名只需运行一条命令，绝不要重写 JSON：python3 "$S/retakes.py" fix edits/<name> cloud=Claude jiv=Jev（完整词语会保存在 fixes.json 中，供字幕使用）。

3. 构建

python3 "$S/build_timeline.py" <source> edits/<name> && python3 "$PY" "$S/mirror.py" <source> edits/<name>

所有超过 --max-pause（0.15 s）的停顿（包括呼吸声）都会变为 0.10 s；只有音乐下的词间空隙 会被缩短。构建出现 ERROR 时不会写入任何内容：修复对应片段后重新运行。

如果 mirror.py 检测到书本、衬衫或标牌上的文字是反的（使用前置摄像头拍摄），会显示 mirrored：询问一次， 按拍摄原样保留（推荐）（大多数创作者都会这样发布）/ 翻转，使文字正向显示；如果选择翻转，在下面每个 render.py 调用中都添加 --flip。

在一条消息中，在后台启动片段编码（run_in_background），同时进行纸面检查；第 4 步只会编码有变化的内容：

python3 "$S/render.py" <source> edits/<name> --segments-only

cut-judge Agent 会评估 paper-edit.md（是否保留了口误、是否有不自然的拼接、是否删掉了好的台词），并修复 spans.json。超过 5 min 的素材先由读稿器处理，再由评审处理：references/judge.md。不要自己阅读 paper-edit.md。

• paper-edit.md 中出现 CLIPPED：剪掉停顿时误删了一个词。调高 --pad。仍然存在：标签有误。
• 语音中的拼接点应移到安静的画面。任何 still in speech：在第 5 步听一下。

4-5. 渲染并验证

前台运行（render.py 会等待后台编码完成）：

R="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/review.py"
python3 "$S/build_timeline.py" <source> edits/<name> && \
python3 "$S/render.py" <source> edits/<name> && \
python3 "$PY" "$S/verify_cut.py" edits/<name> --engine <same engine as step 1> && \
python3 "$S/preview_cut.py" edits/<name> --no-open && \
python3 "$R" edits/<name> start --video edits/<name>/cut.mp4 --stage cut --transcript edits/<name>/words.json

验证通过：剪辑页面已就绪。Verify 会将剪辑的转录与保留的词进行比较（退出码为 1 时会停止后续流程）：

• MISSING：渲染结果中缺少一个保留的词。调高 --pad（或缩小片段范围），重新构建并重新渲染。
• SURVIVED：对于确实重复或口误的内容，添加一个片段；绝不能添加会删掉保留台词的片段。
• HEARD DIFFERENTLY（“jev -> jeff”）和填充词备注属于转录差异：无需重新构建。
• DOUBLED：连续说了两次的词。自然重复（“very, very”）：保留。口误：添加对应片段。
• N join(s) in speech：听一下。如果有截断：运行 splice_check.py edits/<name> --fix，然后重新渲染。

进行一轮修复（使用同一流程），然后向用户说明剩余问题。

6. 用户批准

流程会打开审核页面（../style-edit/references/review.md）。在后台运行 serve 和 wait。说明剪掉了多少秒。备注：“keep ”：缩小或删除对应片段；“cut ”：添加一个片段；停顿不合适：调整 --max-pause。然后执行第 4-5 步，逐条用 resolve 处理备注（--reply：说明做了什么更改），最后运行 round --video edits/<name>/cut.mp4（绝不能再次运行 start），然后询问是否有学习相关问题。

用户批准后，使用一次 Bash 调用：python3 "$S/trend.py" log edits/<name>（tally：趋势），并检查 hook。然后，如果存在 hooks.json，再生成 hook 变体（references/retake-detection.md）；由 start 调用，在询问用户是否批准 style-edit 的静帧时一并询问，不要提前询问。

只有用户批准后，剪辑才算完成；cut.mp4、words.json 会交给 style-edit。如果用户说“先只要剪辑”，告知他们之后可以再申请样式。绝不要自行启动 style-edit。由 start 调用：页面打开时，在后台启动 visual-prep；对它的每个 motion_briefs 同时在后台启动一个 clip-builder；只需说明一次 motion_note。

如果脚本停止

消息	处理方式
no such file / ffmpeg could not read audio	询问正确路径；绝不要复制或转换源文件
faster-whisper missing / CrisperWhisper missing	使用 python3 "$PY" 运行，或执行设置技能的第 3 步
no ElevenLabs key（退出码 2）/ HTTP 4xx、unreachable（退出码 3）	移除 --engine scribe，或使用设置技能重新保存密钥
构建引用句子时出现 ERROR	修复对应片段的引用内容，或添加 occurrence，然后重新构建
cannot derive a silence threshold / marked no silence	语音与背景音的音量差不到 10 dB：运行 ffmpeg -i <source> -af volumedetect -vn -f null -，传入比平均值高约 10 dB 的 --noise
渲染时出现 ERROR ...	告知用户；重新运行一次 render

规则

1. 每次剪辑都必须引用转录内容。没有引用就不剪。
2. 脚本负责在多个拍摄片段之间解决冲突，并保留它判定为重复说出的台词的每个片段。不得因为内容偏离脚本而剪掉任何内容。
3. 剪辑时绝不要使用流复制（-c copy）：剪辑点最多会偏移 2 s。
4. 绝不要交付未经验证和批准的渲染结果。

Self-check

test_build_timeline.py, test_retakes.py, test_media.py (ffmpeg); demo on transcribe.py, trend.py, splice_check.py, script_match.py, mirror.py.