Communitygithub.com

barefootford/buttercut

内部子流程(非独立入口)——共享的素材分析流水线,生成音频转录、联系表以及Sonnet撰写的摘要。由 process-library 和 reprocess-with-contact-sheets 技能端到端调用;请勿单独触发。

buttercut 是什么?

Buttercut 的 Analyze Video 技能是素材分析工作流的核心,负责为每个剪辑生成三种产物:音频转录(transcript)、联系表(contact_sheet)和 Markdown 摘要(summary)。该技能设计为子流程,供 process-library 等上层技能调用,而非直接供用户触发。工作流分六个步骤执行:防止系统休眠、执行机械化的转录和联系表生成(利用 WhisperX 和 ffmpeg)、可选的转录精炼(修正专有名词)、通过 Sonnet 模型批量生成摘要(每批10个剪辑,最多10个子代理并行)、与用户确认素材理解情况,以及最后停止防休眠机制。该技能支持 macOS 和 Windows 平台,重点关注容错性(如重试失败的剪辑)和进度透明(向用户展示非技术化的待办事项列表)。用户可在分析完成前请求粗剪,但会收到警告提示。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/barefootford/buttercut/tree/HEAD/skills/analyze-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

技能:分析视频(主线程简要)

这是主线程用于分析视频工作流步骤的操作手册。在库设置完成后、任何剪辑工作之前执行。它涵盖了每个剪辑生成的三个产物:音频 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 代理,将所有所需值内联在提示中传递。
  • 随着代理完成(通过 Library API——参见 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 写入。)

如果用户在分析完成前请求粗剪

警告:“我现在可以创建粗剪,但在分析完所有素材后我会做得更好。是否继续?”如果用户确认,则继续。否则,等待分析完成。

相关技能