update-buttercut

技能：更新 ButterCut

将 ButterCut 更新到最新版本，然后用通俗易懂的视频剪辑术语概述新增内容。本项目的用户都是视频剪辑师——Claude 有时会自行修改代码，甚至让仓库停留在一个副分支上。更新程序会自行彻底重置这种状态：它会获取更新；如果有内容需要应用，就会暂存所有未提交的更改、切换到 main、快进更新并同步依赖项。你要做的是运行更新程序，并告诉用户有哪些新内容。

**ButterCut Pro：**在 Pro 版安装中（ruby lib/buttercut/library.rb edition 输出 pro；core 则是开源版 ButterCut），更新程序会使用安装程序保存的许可证登录更新服务。你无需额外运行任何操作——只有在解读失败消息时，才需要阅读此技能目录中的 @pro-update.md。

工作流程

1. 运行更新程序——只运行一条命令，不做其他操作：

ruby lib/buttercut/update.rb

切勿自行拼凑这些步骤（git stash、git checkout、git pull、git config、bundle install、pip install）：更新程序已经会处理这些操作，而且在 Pro 版中，只有它知道如何登录。libraries/ 被 gitignore 忽略，不会受到上述操作的影响。该命令会输出一个 JSON 对象：

• updated — 是否有新内容到达。before/after 是 SHA（仅开发者模式会关注）。
• changelog — 本次更新添加到 CHANGELOG.md 的内容，这些内容已写给用户阅读。步骤 2 会概述这些内容；你无需运行 git 查看。
• stashed — 暂存本地修改时使用的暂存名称，否则为 null。只有在有内容需要应用时，才会暂存修改；当前安装会保持原样。
• dependencies — bundle、whisperx（同步到仓库固定版本的虚拟环境）和 whisperx_wrapper（曾用于隐藏崩溃的旧版 macOS 包装器，发现后会重写），每项状态为 ok、repaired、failed 或 skipped。skipped 属于正常情况（Windows，或安装版本早于标准虚拟环境布局）。如果 whisperx 状态为 failed，更新仍然已完成——告知用户转录功能可能会异常，直到再次运行更新程序；稍后再运行更新程序。
• shell_ruby_ok — 仅限 macOS（其他平台为 null）。false 表示 Agent shell 无法再解析到正确的 Ruby：2026 年年中之前配置的安装缺少 ~/.zprofile 激活行，因此在登录 shell（zsh -lc——某些 Agent 客户端运行命令时采用的方式）中，macOS 的 path_helper 会将 mise shim 降到较低优先级，ruby 会回退到系统 Ruby 2.6，而它无法解析 ButterCut 的脚本。重新运行 skills/setup/simple-setup.md 中步骤 2 的 mise 激活代码块——它带有 grep 检查且可幂等运行，因此只会追加缺失的激活行——然后用通俗说法提及一次（“我还修复了一个旧版 ButterCut 安装中的小问题”），不要提 shell 或 PATH。状态为 true 时，不要提及此事。
• skills_link_ok — false 表示 Windows 检出将 .claude/skills 链接变回了纯文本文件（未启用开发者模式的检出无法创建符号链接），导致 Claude 无法再看到 ButterCut 的技能。继续操作前，按照 skills/setup/windows-setup.md 中的步骤 7 修复。
• error + message — 更新未完成。用通俗说法告诉用户消息内容，不要循环重试。
  • network — 在触碰任何内容之前，获取操作失败。开源更新来自公开的 GitHub 仓库，无需凭据，因此这意味着网络故障或无法连接 GitHub——建议稍后重试。
  • local — 更新已下载，但安装本身的状态阻止了应用更新（本地提交与 main 分叉，或合并不是快进式合并）。等待无济于事。如果设置了 stashed，用户的修改已保存在该暂存中，仓库可能已位于 main——请说明这一点。展示消息，并提出协助理清问题（视频编辑器模式下，操作 git 前先询问）。
  • unexpected — 更新程序本身出错（消息中会列出错误）。如果设置了 stashed，用户的修改已保存在该暂存中。告知用户更新未完成，然后运行 report-bug 技能。
  • license_missing / license_declined（仅限 Pro）：遵循 @pro-update.md。

更新程序还会重置每日更新检查计时器，因此 ButterCut 不会在刚完成更新后立即再次询问是否更新。

2. 告诉用户他们获得了什么——使用用户的语言。 步骤 1 中的 changelog 内容已写给用户阅读——用一两句话概述，写成发布说明的风格，先说明用户现在能做什么（“ButterCut 现在支持处理照片——将静态图像拖入素材库，然后在剪辑中使用”）。然后：

• 注意版本区分。 发布说明可能会按 ### ButterCut (free) 和 ### ButterCut Pro 分组列出更改。如何概述 Pro 部分，取决于你在本技能开头查到的版本（ruby lib/buttercut/library.rb edition）：
  • 对于 Pro 安装（pro），用户同时拥有免费版和 Pro 版——将免费版和 Pro 版的更改合并概述为他们现在可以使用的功能。
  • 对于 core 安装（core），用户只获得了免费版的更改。将这些概述为“你现在可以……”，然后以轻描淡写、可选了解的方式提醒他们 Pro 版的内容——不要说成他们已经拥有的功能，例如：“此外，ButterCut Pro 还新增了多轨道时间线和实时预览面板，详见 buttercut.io。”只用一句话，绝不强推；如果此次更新没有 ### ButterCut Pro 条目，则完全跳过。
• 如果 changelog 为空但 updated 为 true，就说他们已获得最新的后台改进——不要逐一列举。如果 updated 为 false，则表示他们使用的已经是最新版本。
• 概述中绝不要提及分支、提交、SHA、测试、版本文件、迁移或 main。
• 除非此次更新包含新增的带编号发布说明，否则不要引用版本号。只有将一批更改作为一个整体公开发布时，才会有带编号的发布说明；两次发布之间，版本文件会按设计落后于 main，因此“仍在使用 0.7.2”对用户毫无意义。
• 更新后不要运行测试套件。 大量测试输出会让人觉得出了问题，而“测试通过”回答的并不是视频编辑用户会提出的问题。
• 如果设置了 stashed，就用直白的说法提及一次（“我在更新前暂存了几处本地文件修改；如果你以后想恢复，它们都还在”）——不要自动尝试重新应用。

（在开发者模式下——存在 .buttercut_mode 时——跳过上述角色规则，以技术方式报告：版本、SHA 和运行测试套件都可以提及。）