切割
路径：${CLAUDE_SKILL_DIR} 指包含此 SKILL.md 的文件夹，${CLAUDE_SKILL_DIR}/../.. 指编辑器文件夹（此仓库的 .claude/ 目录，比当前文件夹高两层）。
首先阅读 ${CLAUDE_SKILL_DIR}/../../PRINCIPLES.md：每个视频都遵循的规则。
每个问题都放入问题框：AskUserQuestion 工具（提供 2-4 个选项，推荐作为首个工具）。仅在未配备该工具的代理中，才以编号文本形式提问。
edits/<name>/ transcript.txt（读取此文件，切勿读取 words.raw.json），spans.json（待移除的内容，带引号），
candidates.md（代码标记的内容），paper-edit.md（以文本形式呈现的剪辑），cut-check.html（转录文本），
review.json（备注），cut.mp4 + words.json（输出视频及其对应的文字数据）。
<name> 是文件名的 slug 形式（IMG_1234.MOV -> img-1234），存放在库中（PRINCIPLES.md "Where"）。切勿修改、移动或复制源文件：直接传递其路径。
PY="${CLAUDE_SKILL_DIR}/../../lib/ai_editor/run.py"；python3 "$PY" 用于运行工具虚拟环境。在 Windows 上，凡是在这些命令中使用 python3 的地方，请改用 py。
如果尚未创建虚拟环境：请先运行 setup 技能。S="${CLAUDE_SKILL_DIR}/scripts"。
尚未提供视频？
询问用户素材的路径。多个文件：参考 references/takes.md。没有文件：当设置了 AI_EDITOR_SAMPLE_URL 时，提供该示例素材并下载到用户的文件夹（curl -L -o sample-take.mp4 "$AI_EDITOR_SAMPLE_URL"）；否则请用户录制一段（任何手机拍摄的 30-60 秒说话视频均可）。
0. 询问：先只做剪辑，还是全部一次性完成
在执行任何其他操作之前，先在问题框中提出一个问题（如果是完整编辑，则由 start 决定）：
您是希望先只做剪辑，还是剪辑和风格化编辑一次性完成？
- 先只做剪辑（推荐）。 在您批准剪辑后，我再添加字幕、缩放或视觉效果，这样如果剪辑更改就不会重建视觉效果（占用更少的 token）。
- 一次性完成。 我完成剪辑后直接进行风格化处理，无需等待。在开始渲染之前，您仍然会看到剪辑页面和缩略图表格。
仅当用户已经回答（如“直接剪掉”、“一次性完成剪辑和风格化”）或由 start 或 clips 技能调用此技能时，跳过此问题。先只做剪辑： 执行步骤 1-6，然后停止，直到用户批准剪辑 并 主动要求风格化。一次性完成： 执行步骤 1-5，打开剪辑页面，然后直接继续执行 style-edit；后续若剪辑变更，则从其计划步骤重新运行 style-edit。
0b. 读取用户的偏好
python3 "${CLAUDE_SKILL_DIR}/../../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% 准确率）。
告知用户所需时间：Whisper 处理 3 分钟素材需 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 秒）的停顿（包括呼吸）都会被缩短到 0.10 秒；只有在背景音乐下，才只修剪单词之间的间隙。如果构建出现 ERROR，则不写入任何输出：修复相应的 range 后重新运行。
mirror.py 会在书本、衬衫或标志上的文字出现镜像反转（前置摄像头拍摄的情况）时输出 mirrored：此时向用户提问一次，保持原样拍摄（推荐）（大多数创作者会发布原始画面）/ 翻转以使文字可读；如果选择翻转，则在下面的每次 render.py 命令中添加 --flip。
在一条消息中，同时启动背景编码（run_in_background）和 paper 检查；然后步骤 4 仅编码已更改的部分：
python3 "$S/render.py" <source> edits/<name> --segments-only
cut-judge 代理会对 paper-edit.md 进行评分（检查是否遗漏了失误、连接处是否不佳、是否丢失了良好的台词），并修复 spans.json。对于超过 5 分钟的素材，优先运行阅读器，再运行评判器：参考 references/judge.md。切勿自行读取 paper-edit.md。
paper-edit.md中出现CLIPPED：表示裁剪停顿导致吞词。提高--pad。如果问题依旧：某个标签范围不准确。- 语音中的连接点应移动到静音帧。如果发现
still in speech：在步骤 5 中监听。
4-5. 渲染与验证
前台操作（render.py 会等待后台编码完成）：
R="${CLAUDE_SKILL_DIR}/../../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_cut 会将剪辑后的转录与保留的单词进行比对（退出码 1 会中断整个链条）：
- MISSING：保留的单词未出现在渲染结果中。提高
--pad（或缩小范围），重新构建，重新渲染。 - SURVIVED：针对真正的重复或口吃添加一个 range，但绝不能剪掉保留的台词。
- HEARD DIFFERENTLY（如 "jev -> jeff"）以及填充词备注属于转录器差异：无需重新构建。
- DOUBLED：连续重复两次的单词。自然重复（如“非常，非常”）：保留。如果是口吃：添加其 range。
- N 个语音内连接：监听。如果音频被裁剪：运行
splice_check.py edits/<name> --fix，然后重新渲染。
执行一个修复周期（使用相同的链条），然后向用户展示剩余问题。
6. 用户审批
链条已打开审查页面（参考 ../style-edit/references/review.md）。在后台执行 serve 和 wait。告知用户剪辑节省的秒数。备注格式："keep "：缩小或删除该 range；"cut "：添加一个 range；停顿问题：调整 --max-pause。然后执行步骤 4-5，对每条备注进行 resolve（使用 --reply：说明更改了什么），最后执行 round --video edits/<name>/cut.mp4（切勿再次执行 start），然后询问是否学到知识。
审批通过后，执行一次 Bash 调用：python3 "$S/trend.py" log edits/<name>（tally：记录趋势），这是钩子检查。然后如果存在 hooks.json（参考 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" 运行，或运行 setup 技能的步骤 3 |
no ElevenLabs key（退出码 2）/ HTTP 4xx、unreachable（退出码 3） | 移除 --engine scribe，或使用 setup 技能重新保存密钥 |
构建报错 ERROR 提示引号问题 | 修复该 range 的引号或添加 occurrence，然后重新构建 |
cannot derive a silence threshold / marked no silence | 语音和背景音量相差小于 10 dB：运行 ffmpeg -i <source> -af volumedetect -vn -f null -，传递 --noise 约为均值以上 10 dB |
渲染报错 ERROR ... | 告知用户；重新运行渲染一次 |
规则
- 每个剪除都必须引用转录文本。没有引用，就不能剪除。
- 脚本（script）用于在多次拍摄之间进行取舍，并保留脚本中重复出现的每句台词。不能因为偏离脚本而剪掉内容。
- 切勿在剪除点使用流复制（
-c copy）：它会导致最多 2 秒的偏差。 - 未经验证和审批的渲染结果绝不交给用户。
自检
test_build_timeline.py、test_retakes.py、test_media.py（针对 ffmpeg）；demo 用于 transcribe.py、trend.py、splice_check.py、script_match.py、mirror.py。