技能:分析视频(主线程简要)
这是主线程用于分析视频工作流步骤的操作手册。在库设置完成后、任何剪辑工作之前执行。它涵盖了每个剪辑生成的三个产物:音频 transcript、contact_sheet 和 Markdown summary。粗剪代理通过运行 script_extractor.rb 读取转录 JSON 中的对话——无需单独的脚本产物。
SKILL.md 是主线程的分派简要。子代理的工作提示位于 agent_prompt.md 中——在启动 Task 代理时内联其内容。不要传递 SKILL.md。
术语
- 面向用户: 称为“素材分析”或“分析素材”。
- 内部/文件名: “转录”(library.yaml 字段
transcript等)。
前置条件
- 库设置已完成(
library.yaml存在,schema 为最新——如果未进行,请从 AGENTS.md 运行迁移)。 - 直接读取
libraries/settings.yaml获取whisper_model。对于库字段,通过ruby lib/buttercut/library.rb <name> summary读取快照并从 JSON 中提取所需值——不要内联解析 library.yaml。
此时,创建一个对用户可见的待办事项列表,包含高层次、非技术性的步骤,以便他们能够了解处理库的整体计划。仅当他们选择加入时才包含提神步骤。例如:
- [ ] 保持计算机唤醒
- [ ] 创建转录(0/30)
- [ ] 分析素材(0/30)
- [ ] 让计算机再次休眠
- [ ] 一起审查素材
这些公开待办事项映射到下面的步骤:“保持计算机唤醒”是步骤1,“让计算机再次休眠”是步骤6;“创建转录”涵盖步骤2中的机械化运行以及步骤3中的可选精炼(从步骤2的 [transcript …] 进度行推进其计数;当精炼开启时,在步骤3期间保持其为进行中);“分析素材”跟踪步骤4中的摘要(在剪辑被摘要时推进其计数,而不是在联系表之后);“一起审查素材”是步骤5。
在公开聊天中,请引用这些非技术性步骤。将技术工作(WhisperX、联系表生成、Sonnet 摘要)放在幕后。
步骤1 — 处理期间防止休眠
在开始分析之前,询问用户(通过 AskUserQuestion):“处理可能需要一段时间——希望我保持你的计算机唤醒直到完成吗?”选项:“是(推荐)”和“否”。
如果是,在后台启动平台的保持唤醒辅助程序并存储 PID——你将在步骤6分析完成后终止它。(备份由调用技能——process-library——在此技能返回后处理。)
macOS:
caffeinate -i -w $$ &
KEEPAWAKE_PID=$!
Windows(Git Bash):
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!
两者都在素材处理时防止空闲休眠(显示器可能关闭,这没问题)。
步骤2 — 处理素材(转录,然后联系表)
(如果你直接到达此技能而非通过 process-library,首先告诉用户:“发现 [N] 个视频([总大小])。开始素材分析...”)
这是两个机械化命令,你依次运行——先转录,后联系表。切勿同时运行:WhisperX 是 RAM 密集型,避免重叠正是我们的目的。不要使用子代理手动处理;每个命令每次执行方式相同,大约每次2个剪辑,每完成一个剪辑即将其记录到 library.yaml 中。两者都是幂等的——它们只处理缺少该产物的剪辑——因此重新运行仅完成剩余部分。它们将在类似迷你 Sidekiq 的任务服务中运行。你将运行命令,然后监控将返回的日志文件以查看进度。
步骤2a — 转录。 如果使用 Claude Code,使用 run_in_background: true 运行 Bash 工具。否则使用正确的工具/参数在后台运行。
ruby lib/buttercut/process_footage.rb transcripts <library-name>
启动后立即在日志文件上设置 Monitor 或等效机制,以接收每个完成或失败剪辑的通知:
tail -f tmp/logs/processing/<library-name>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"
ruby lib/buttercut/library.rb <name> pending transcript # JSON 列表;完成数 = N − 其长度
随着剪辑完成,更新“创建转录 5/20”,即 number_of_clips_complete/total_number_of_clips,以便用户看到进度。当后台任务完成时,如果有任何剪辑失败,它将返回非零退出码。失败时,重新运行一次。如果再次失败,进行调查,然后要么创建一个修复程序以便优雅处理,要么将问题告知用户并可能将剪辑从库中移除。
等待2a完成后再开始2b。
步骤2b — 联系表。 转录完成后,生成联系表(快速的 ffmpeg 传递——前台即可):
ruby lib/buttercut/process_footage.rb contact-sheets <library-name>
联系表保持在幕后——不要将其作为公开计数呈现。一旦2a完成并且任何精炼(步骤3)也完成后,将“创建转录”标记为完成。
调优(可选):两个步骤都从 libraries/settings.yaml 读取 parallel_jobs(默认为2);如需单次覆盖,使用 --jobs N。每个步骤在 tmp/logs/processing/<library>/ 下写入带时间戳的日志,供事后审查。
重新处理。 每个步骤跳过已具有其产物的剪辑。要重做某个——比如听错名字的转录——使用 --force --clips NAME.mov 重新运行该步骤。--force 单独使用时将重建每个剪辑。
步骤3 — 精炼转录(判断——仅在 transcript_refinement: true 时)
精炼是转录中唯一需要判断的部分——根据库上下文修正听错专有名词——因此它保留为模型步骤,在机械化传递之后运行。如果库的 transcript_refinement 为 false,则完全跳过此步骤。
当其为 true 时,将精炼子代理(2-4个并行,滚动式)分派到步骤2a刚刚写入的转录上。将 skills/transcribe-audio/refine_instructions.md 内联为每个子代理的提示,并内联传递:
transcript_path— 剪辑转录 JSON 在libraries/<library>/transcripts/下的绝对路径user_context和footage_summary— 来自ruby lib/buttercut/library.rb <name> summary的当前值(空字符串也可以;精炼仍然能捕获无效令牌和自我见证修复)
子代理就地编辑转录 JSON 并返回一个简短的更正列表。它们不接触 library.yaml——步骤2a已经设置了 transcript 字段。精炼完成后,将公开的“创建转录”待办事项标记为完成。
步骤4 — 摘要(Sonnet 子代理,分批,滚动式)
在 Sonnet 模型上分派 analyze-video 子代理。Sonnet 读取联系表时视觉细节明显比 Haiku 更多(捕捉服装、建筑、镜头构图)——这值得,因为摘要会影响后续每个剪辑决策。
每个子代理处理10个剪辑,最多10个子代理并行,采用滚动分派。 每个子代理顺序处理其10个剪辑;分批处理分摊了每个代理约5-10秒的分派开销。对于93个剪辑的库,总共约10个子代理而不是93个。一旦某个代理返回,立即启动下一个子代理——不要等待整批10个完成,否则会因批次中最慢的代理而损失约30%的挂钟时间。
对于每个子代理,内联传递10个剪辑记录的列表。每个剪辑记录需要:
video_filename— 视频的基本文件名(用于摘要标题和回复行)duration— 来自 library.yaml 的时长字符串(例如00:01:19);代理将其渲染到摘要标题中contact_sheet_path—_full.jpg的绝对路径(来自步骤2)transcript_path— 音频转录 JSON 的绝对路径(来自步骤2);子代理通过script_extractor.rb按需提取对话summary_output_path— 代理应写入摘要 markdown 的绝对路径。不要手动构建此文件名;向库询问规范路径:ruby lib/buttercut/library.rb <name> field_path summary <clip>(处理summaries/summary_<clip>.md约定,无论是否带文件扩展名)
每当子代理返回其批处理时,为该批次中的每个剪辑更新 library.yaml 中的 summary:
ruby lib/buttercut/library.rb <name> complete summary <filename> [<filename>...]
contact_sheet 字段已在步骤2中填充,因此子代理返回仅贡献摘要。
如果子代理内联返回摘要而不是写入磁盘(有时 Sonnet 会幻觉“Write 工具被阻塞”并将 markdown 转储到其回复中),不要盲目重试——只需从代理响应中提取每个摘要,并使用主线程中的 Write 将其写入匹配的 summary_output_path。然后正常运行 complete summary 命令。比重分派更快,并且内容已经存在。
(为长剪辑生成的按片段联系表与 _full 表并存于磁盘上,可通过约定发现——它们不在 library.yaml 中列出。)
在摘要完成之前不要继续。在剪辑被摘要时推进“分析素材”计数;完成后标记为完成。
图片。 图片完全跳过步骤2-3(无需转录音频,无需生成联系表)——summary 是它们唯一需要的产物,它们与视频一起出现在 ruby lib/buttercut/library.rb <name> pending summary 中。图片本身就是要查看的内容,因此直接对其进行摘要:从主线程或 Sonnet 子代理读取图片文件(它很小),并写一个3-4句的描述——主体、场景、构图、任何图片上的文字——写入来自 ruby lib/buttercut/library.rb <name> field_path summary <image-filename> 的规范路径。注意图片剪辑键包括扩展名(title-card.png → summaries/summary_title-card_png.md),field_path 会为你处理。然后以同样的方式记录:ruby lib/buttercut/library.rb <name> complete summary <image-filename>。
步骤5 — 与用户确认素材理解
(这是“一起审查素材”待办事项。)一旦所有摘要都已写入,与用户讨论素材实际显示的内容——确认角色名称、地点、叙事主线、任何偏离主题的剪辑以及用户对该库的创作意图。使用普通对话;仅在提供离散选择时使用 AskUserQuestion。随着你了解到的信息,更新:
footage_summary和user_context通过ruby lib/buttercut/library.rb <name> update_metadata footage_summary "..."(以及同样的user_context)- 当某个摘要标签错误或遗漏关键细节时,更新相应的
summary_*.md文件(例如,“一个穿着棕褐色夹克的男人” → 用户的名字)
这是进行此彻底审查的唯一地点。后续的每次粗剪计划运行将继承所得上下文,而不是重新审问库。
步骤6 — 停止保持唤醒辅助程序
如果你在步骤1中启动了它,现在终止它(两个平台):
kill $KEEPAWAKE_PID 2>/dev/null
并行子代理模式(参考)
用于步骤3和4。
主代理职责:
- 一次性读取
library.yaml和settings.yaml以收集子代理所需的所有值。 - 启动 Task 代理,将所有所需值内联在提示中传递。
- 随着代理完成(通过
LibraryAPI——参见 AGENTS.md),顺序更新 library.yaml。 - 处理错误和重试。
子代理职责:
- 仅使用主代理内联传递的输入,处理分配的一个或多个剪辑。
- 就地精炼转录 JSON(精炼)或读取预生成的联系表,通过
script_extractor.rb从转录中提取对话,并通过一次 Write 调用写入摘要 markdown(analyze-video)。(WhisperX 不再是子代理——process_footage.rb transcripts在步骤2a中运行它。) - 返回一个包含文件路径的简短结构化响应。
每个技能的 agent_prompt.md 记录其自身的 IO 合约——包括子代理是否读取或写入 library.yaml。(剧透:它从不写入 library.yaml。只有主代理通过 Library API 写入。)
如果用户在分析完成前请求粗剪
警告:“我现在可以创建粗剪,但在分析完所有素材后我会做得更好。是否继续?”如果用户确认,则继续。否则,等待分析完成。