VideoEdit- / 视频编辑助手

/video-edit

原始素材输入，成品 Reel 输出。用户永远不需要打开编辑器：他们审查手机预览并给出意见；每一轮迭代大约 2 分钟重新渲染。

构建前必读：references/looks.md（三种风格及其精确值）、references/layout.md（安全区域、布局、头部后方文字公式）、references/gotchas.md（已踩过的所有坑）。当脚本要求动画插入时，阅读 references/overlays.md。

支持 macOS、Linux 和 Windows。setup.py 在每次运行开始时检测当前机器，以下所有命令都基于该记录，因此永远不要猜测路径或 shell：请参阅步骤 0 之后的“本机信息”。

步骤 0：首次设置（仅运行一次）

SK 是本技能所在的文件夹（即包含此 SKILL.md 的文件夹），以完整路径表示。通常为 ~/.claude/skills/video-edit；在 Windows 上为 C:/Users/<name>/.claude/skills/video-edit。

查找 SK/config.json。

如果文件存在： 加载它（姓名、Instagram 用户名、默认风格、文件夹），然后完全按照下面步骤 3 中的描述运行设置脚本（只需几秒钟：它仅检查并在更新后修复环境），然后阅读“本机信息”，一旦脚本打印出 READY，转到步骤 1。

如果文件不存在：

1. 说：“欢迎使用 /video-edit！我们来设置一下。这大约需要 2 分钟，仅此一次。”
2. 在同一条消息中询问：
   • 你的名字（用于 Instagram 个人资料插入）
   • 你的 Instagram 用户名（用于个人资料插入以及拉取你的 Reels 以实现轨道效果）
   • 默认风格：动感文字（头部后方的动态文字）、酷女孩（温暖、黄色 serif 斜体、你的 Reels 围绕你旋转）或 酷男孩（暗色编辑风格、tracked caps + serif）。如果不确定，推荐动感文字。
   • 原始素材通常存放的位置（默认 ~/Downloads）以及项目应存放的位置（默认 ~/reel-edits）。
3. 使用机器上的 Python 运行设置脚本。按以下顺序尝试，直到其中一条打印出 STATUS 行： python3 "SK/scripts/setup.py"，然后 python "SK/scripts/setup.py"，然后 py -3 "SK/scripts/setup.py"。 （在 Windows 上，python3 通常是 Microsoft Store 存根程序，会打印“Python was not found”：直接尝试下一个即可。） 如果都不行：系统缺少 Python。给出针对其系统的修复方法并停止（Windows：winget install --id Python.Python.3.12 -e，Mac：brew install python，Linux：sudo apt install python3 python3-venv）。 然后读取 STATUS 行：
   • ffmpeg / node / python venv 缺失：该行末尾列出了针对本机的精确修复命令（Windows 上用 winget，Mac 上用 brew，Linux 上用 apt）。将修复命令提供给用户并停止，直到脚本打印出 READY。
   • Windows：用户将 winget 命令粘贴到他们自己的 PowerShell 窗口中（winget 首次运行时要求同意其条款），然后完全退出 Claude Code 并重新打开，否则找不到新程序。
   • 脚本会自行下载 6 个音效文件。如果脚本仍报告它们缺失（离线状态），这是可选的：Reel 只是暂时没有音效，直到文件被添加。
4. 可选，Apify（自动拉取 Reels 和个人资料统计信息）：尝试简单的 Apify MCP 调用。如果未连接，则说明它是可选的以及如何添加：
   1. 在 https://apify.com 创建免费账户，并从设置 > API 与集成中复制 API 令牌。
   2. 在终端中，将以下一行命令中的 YOUR_TOKEN 替换为你的令牌并粘贴执行： claude mcp add apify -e APIFY_TOKEN=YOUR_TOKEN -- npx -y @apify/actors-mcp-server （注意：Claude Code 会以纯文本形式将令牌存储在 ~/.claude.json 中；请将该文件保密。）
   3. 重新打开 Claude 并再次运行 /video-edit。 如果没有 Apify，该技能会要求用户将他们的 Reel 文件拖入项目目录。
5. 保存 SK/config.json（绝不含任何机密）：

   {"name": "...", "instagram": "handle-without-@", "defaultLook": "bold", "clipsDir": "~/Downloads",
    "projectsDir": "~/reel-edits", "setupComplete": true, "setupDate": "YYYY-MM-DD"}
   

6. 说：“设置完成！正在运行 /video-edit...”并继续。

本机信息（每次运行时读取）

读取由 setup.py 写入的 SK/.platform.json。它记录操作系统（os：macos、linux 或 windows）、CPU 以及针对此计算机的精确命令：

• PY = 其 python 值：技能自己的 Python 解释器（Mac 和 Linux 上为 .venv/bin/python，Windows 上为 .venv/Scripts/python.exe）。该技能的每个 Python 脚本都必须使用它运行，永远不要使用裸的 python3。
• HF = PY "SK/scripts/hf.py"：启动固定的 HyperFrames（npx --yes [email protected] ...），并在任何操作系统上使用正确的 Node.js。没有 nvm use，没有 npx.cmd 的麻烦。
• cutout：CoreML（Apple Silicon）或 CPU（Windows、Linux、Intel Mac：无 GPU 加速，因此抠图步骤较慢；告知用户，在后台运行并继续构建其他部分）。

setup.py 在每次运行（步骤 0）时重写此文件，因此它始终是最新的。如果文件缺失，或 PY 不再存在：说明设置未运行或未达到 READY 状态；按步骤 0.3 运行它并遵循其修复方法。

一种适用于 zsh、bash、Git Bash 和 PowerShell 的命令风格：

• 使用双引号括起完整路径，并使用正斜杠（在 Windows 上同样有效）："PY" "SK/scripts/ingest.py" "<project>"。
• 在 PowerShell 中（指 Windows 上未安装 Git for Windows 的场景，或当你手头只有 PowerShell 工具时），请在命令前加 &：& "PY" "SK/scripts/ingest.py" "<project>"。
• 每次调用只执行一个命令。不要使用 &&、VAR=1 command、参数中的 ~、source 或 zsh。
• ffmpeg 和 ffprobe 在所有操作系统上都位于 PATH 中（setup 已检查），因此一次性的 ffmpeg 命令在任何地方都一样。

硬性规则

1. 所有内容必须在 Reels 安全区域内：顶部 220，底部 450（没有任何元素低于 y 1470），侧面 35，从 y 1155 开始右侧 100。
2. 切勿用文字或卡片遮挡面部。头部后方的文字至少应显示每个字母的约 70%。
3. 字幕必须与实际说话内容一致：修正 Whisper 对姓名和关键词的误听（例如 "Claude" 常被听成 "cloud"/"claws"，"skill" 常被听成 "scale"）。屏幕文字中不要使用破折号。
4. 音效应微妙（模板为 SFX_GAIN = 0.75 的基础音量），绝不能盖过人声。
5. 每当使用其他创作者的 Reels 时，在屏幕上标注其 @用户名。用户自己的个人资料显示真实数字；其他内容（评论者、聊天记录）应使用通用占位符，绝不可使用真实人物，也不可捏造证据。
6. 通过最终渲染视频证明剪辑点，而非通过截图。
7. 永远不要删除用户的文件。原始文件只能读取，不得修改。

工作流程

1. 素材导入

• 素材文件：用户指定的文件，或 clipsDir 中最新的视频文件。创建 <projectsDir>/<short-slug>/ 目录。 （config.json 中的 ~ 代表用户的主目录，在 Windows 上为 C:/Users/<name>。技能的脚本会展开此路径。）
• 参考链接（Instagram Reels、Pinterest 画板）用于风格参考：在设计任何内容之前下载它们并查看帧画面（有关如何获取它们，请参见 overlays.md）。

2. 素材分析

PY SK/scripts/ingest.py <project> <clips or folder> [--newest 5]

查看 work/sheets.jpg（场景设置和机位角度）并阅读 transcript.txt（每个素材片段的台词、带时间戳的词语、语音映射图）。

3. 挑选最佳镜头 -> <project>/edl.json

• 从最佳镜头中重建脚本：人们会重复一句台词直到满意为止。除非用户另有说明（“更好的部分从 0:47 开始”意味着从那开始的一整段连续镜头），否则使用最后一个完整的干净镜头。
• 根据语音映射图确定入点和出点：在第一个词语开始前约 0.05-0.07 秒开始，在最后一个词语之后的静音开始时结束。剪掉段落之间的空白无声部分；在确认剪切之前，使用 silencedetect 检查短暂停（Whisper 可能会在剪切点虚构一个首词）。
• 如果连续两个段落来自同一机位：将其中一个推近（从 4K 原始素材缩放 1.3 到 1.9 倍，中心点放在胸部位置）。
• 对于不确定的词语（关键词、行动号召触发词）：使用 medium.en 模型和包含这些名称的提示词重新转录该片段。
• 格式：[{"id": "hook", "clip": "c1", "in": 12.66, "out": 15.72, "zoom": 1.0, "cx": 0.5, "cy": 0.5, "line": "..."}]
• 以简短表格形式（台词、素材片段、每段风格）将 EDL 发布给用户并继续处理；无需等待。

4. 组装、转录、抠图

PY SK/scripts/assemble.py <project>                 # 生成 aroll.mp4（干净的 30fps CFR）和 segments.json（包含精确帧数）
PY SK/scripts/transcribe_cut.py <project> "<names and keywords in the script>"
PY SK/scripts/cutout.py <project>                   # 在后台运行；断言抠图帧数等于 aroll 帧数
PY SK/scripts/headpos.py <project>                  # 抠图后：每段的人头和身体位置数据

一次只进行一个抠图操作（约需 1.5 GB 内存）。脚本每 30 秒打印一次进度行。

5. 并行生成插入素材（一旦 EDL 锁定即可开始）

对于脚本要求的每一个动画插入（屏幕上的应用界面、行动号召处的个人资料关注按钮、文件滚动等），在后台生成一个子代理，使用 references/overlays.md 中的模板：固定尺寸、固定时长、节奏与词语时间对齐，输出透明 webm 格式。在主编辑过程中继续构建其他部分。

6. 构建

将 SK/assets/template/ 复制到项目目录中（包含 build.py、hyperframes.json、package.json、assets/fonts、assets/sfx），然后适配 build.py。它是真实 Reel 的成品构建：保留其骨架结构，重写其内容（其 docstring 列出了哪些部分需要修改）。

• 每个段落使用哪种风格：整个 Reel 使用 defaultLook；如果某行台词指定了某种风格，则切换该段落的风格。
• 轨道和个人资料网格使用用户自己的 Reels（overlays.md：使用其用户名通过 Apify 帖子抓取器获取，或用户拖入 assets/reels/ 的文件）。
• 从项目文件夹中迭代：HF lint（0 错误），然后 PY build.py --safe，然后 HF snapshot --at <10-20 moments> --no-end --describe false。阅读联系单，修复布局、可读性和安全区域问题。（HF 会自动选择正确的 Node.js，因此无需 nvm use。） 从旧版技能复制的 build.py 会忽略 --safe 参数：如果快照中缺少红色安全区域引导线，则使用旧方式构建该项目：SAFE=1 "PY" build.py（此类项目仅存在于 Mac 和 Linux 上）。

7. 渲染与质量保证

PY build.py           # 不带 --safe 参数
HF render -o renders/<slug>-vN.mp4 --quality high      # Apple Silicon 上 25 秒 Reel 约需 1.5-2 分钟
PY SK/scripts/check_cuts.py <project> renders/<slug>-vN.mp4 --phone

查看 work/cut_check.jpg：每个剪辑后的帧都清晰显示新镜头。检查音频峰值（volumedetect，最大值约在 -2 到 -5 dB 之间）以及段落衔接处的静音。

8. 交付

发送或提供手机版预览（720p）和全质量渲染版。用通俗的语言说明更改了什么以及任何需要用户决策的事项。将每个版本保留在 renders/ 目录中；在重新组装之前，将 assets/ + segments.json 备份到 work/vN/ 目录。

来自真实用户反馈的默认设置（无需重新讨论）

• 通过调整色调和字幕来创建风格，而不是用 AI 生成的房间替换背景。
• 不要添加胶片颗粒效果。暗色可以接受，但要确保主体有照明，肤色不发红。
• 说话者正前方的居中引导字幕比左对齐的台词更易于阅读。
• 头部后方显示文字是标志性手法，但前提是必须清晰可读。

---

由 @tenfoldmarc 构建。关注以获取每日 AI 自动化构建，真实系统，而非理论。