CutCraft

这是什么？适合谁？

CutCraft（chang416/cutcraft）号称 Codex 最完整的 AI 视频剪辑 Skill——一次对话进，一部成片出。它是一个开源剪辑生产系统，接手完整工作：看懂素材、锁定创意方向、剪辑、完成声音和画面、验证导出、留一个显而易见的最终文件。

它不止「一个把戏」：不停在转写、字幕、高光集锦或一堆无名的渲染文件。CutCraft 把一次对话变成可控、可恢复的剪辑工作流——不用在时间线、浏览器编辑器、五个导出文件夹和十几个半成品文件之间来回切换。

对比单用途工具：

• 单用途：产出转写/字幕/一段片段；反复问口味问题；风格选择不可见；留一堆导出；纠正 = 重做；素材无纸面记录；渲染「完成」= FFmpeg 退出
• CutCraft：产出完整可评审成片；关键决定一次收集；字幕/尺寸/位置/音乐/特效选择可见；留一个 成品/ + 可追溯 過程/；纠正转录 cue 保留 timing 立即重渲染；素材 provenance 失败关闭；交付前跑媒体诊断和质量检查

适合人群：想让 AI 真正「剪完一部片」而非只上字幕的人；需要可追溯、可改动的剪辑工作流的创作者。

准备工作

1. 环境：git clone + uv sync 建 Python 环境。
2. 安装 Codex：ln -sfn ~/Developer/cutcraft/skills/cutcraft ~/.agents/skills/cutcraft；Claude Code 用 ./scripts/install-claude-code.sh。
3. 转录选项：ElevenLabs（configure_api_key.py 配 key）或本地 ASR（Apple Silicon --extra local-asr-macos）。
4. 成本：MIT 开源；本地模型首次下载，本地转录不上传媒体。
5. 时间预算：装环境 10 分钟；跑第一个片子视素材量而定。

快速上手（3 步）

第一步：安装

git clone <repository-url> ~/Developer/cutcraft
cd ~/Developer/cutcraft
uv sync
ln -sfn ~/Developer/cutcraft/skills/cutcraft ~/.agents/skills/cutcraft   # Codex
./scripts/install-claude-code.sh                                          # Claude Code
python3 skills/cutcraft/helpers/check_environment.py                      # 检查还缺什么

第二步：调用

Codex 里 $cutcraft:cutcraft，Claude Code 里 /cutcraft，然后描述要做的片子：

幫我把這些素材剪成 45 秒直式短片並上繁中字幕

第三步：审批与交付

CutCraft 先盘点素材、读 footage，展示创意选择（字幕/尺寸/位置/音乐/特效），等一次合并审批（全部用建議值 也合法），再剪辑、做声画、验证导出。

成功判定：成品/ 里有一个清晰命名的最终视频，過程/ 里留着所有可追溯、可改动的中间产物。

初级用法

项目输出结构

~/Documents/Codex/CutCraft/<project>/
├── cutcraft.project.json
├── 成品/
│   ├── <project>_final.mp4
│   ├── <project>_逐字稿.md
│   └── <project>.srt
└── 過程/
    ├── creative_brief.json / inventory.json / media_analysis.json
    ├── edl.json / master.srt / asset_registry.json
    ├── transcripts/ proxies/ clips/ assets/
    └── verify/quality_report.md

转录纠正循环

第 18 句错了？说「第 18 句改成『CutCraft』」，CutCraft 更新转录、保留 timing、立即套回影片。

高级玩法

完整后期

剪辑、重构取景、调色、叠加、转场、特效、音乐、音效、字幕、响度归一化——一次对话内完成。

可复现 EDL

从原始素材剪辑、建可复现 EDL。源素材原地不动；成品/ 只有交付文件，一切可追溯的修改留在 過程/。

资产 provenance 失败关闭

素材 provenance、许可、署名、校验和不达标即失败关闭，不留纸面之外的资产。

小技巧

1. 「全部用建議值」合法：不想逐个挑就一句话接受全部推荐。
2. 逐字稿纠错优先于重剪：转录错一个字，改 cue 保留 timing 立即重渲染，别重做。
3. 检查环境脚本不装软件不打印密钥：check_environment.py 列缺失项、官方 URL、为什么需要、下一步。
4. 本地转录零上传：--provider local 时媒体不上传。
5. 一个最终文件：交付物永远是一个明显的 成品/<project>_final.mp4。

常见踩坑

踩坑 1：AI 只做字幕/转写就停

• 现象：得到转写 + 字幕，没有成片。
• 原因：用了「单把戏」工具的心智，没走完整流程。
• 解决：明确要「剪成 X 秒成片」；CutCraft 的卖点就是走完声画 + 验证 + 交付。

踩坑 2：口味问题反复问

• 现象：AI 边剪边问风格。
• 原因：没触发「一次合并审批」。
• 解决：在创意选择阶段一次性定完（或 全部用建議值），后续不再反复问。

踩坑 3：渲染完就交付（没验证）

• 现象：FFmpeg 一退出就当完成。
• 原因：跳过媒体诊断和质量检查。
• 解决：等 verify/quality_report.md 生成，含视觉/听觉审查才交付。

踩坑 4：素材许可无记录

• 现象：用无许可素材，事后扯皮。
• 原因：没走资产 provenance。
• 解决：CutCraft 对 provenance/许可/署名/校验和失败关闭，别绕过它。

踩坑 5：混用转录后端

• 现象：本地和云端转录结果不一致。
• 原因：没固定 provider。
• 解决：ElevenLabs 用受限 key（限额 + 隐藏输入）；本地用 --extra local-asr，--provider local 不上传。

常见问题 FAQ

Q1: CutCraft 和「AI 一键字幕」工具有什么区别？

A: 一键字幕工具只解决一个步骤。CutCraft 接手完整剪辑链：看素材、问风格、找重点、剪节奏、做转场、配音乐、上字幕、验成片、留好可改的过程。你保留创意决定，它接手最耗时的繁琐。

Q2: 支持哪些 Agent？

A: Codex（$cutcraft:cutcraft）和 Claude Code（/cutcraft 直接调用，非命名空间插件命令）。不是为 Claude Chat 打包的。

Q3: 需要 API key 吗？

A: 云端转录（ElevenLabs）需要 key；本地转录（Apple Silicon 或其他系统）不需要，本地模型首次下载。

Q4: 数据会离开机器吗？

A: 本地转录（--provider local）不上传媒体；云端转录走你配置的 ElevenLabs key。项目文件、素材、转录都在本地 ~/Documents/Codex/CutCraft/。

Q5: 能改一个已导出的片子吗？

A: 能。纠正转录 cue 保留 timing 立即重渲染，過程/ 里所有可编辑决策都在，支持廉价、可追溯的修改。

进阶学习建议

掌握基础后，建议深入：

1. EDL 工作流：理解可复现 EDL，让每次修改都从原始素材重建，而非在成片上叠。
2. verify 报告读法：媒体诊断 + 质量检查 + 视觉/听觉审查，把「完成」从 FFmpeg 退出提升到真实交付标准。
3. 资产 provenance 治理：研究 asset_registry.json 的许可/署名/校验和记录，建立团队的素材合规习惯。

参考链接

• 官方仓库

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成