clip-anything

clip-anything 是做什么的？

用途

将一段长录像（单个文件、多个文件或包含整个会话的文件夹）转换为最多 N 个竖屏高光剪辑片段，使用免费的本地 clip-anything CLI 完成。该技能驱动工具运行，在真正剪辑前先展示它会剪什么，然后读取报告，让用户了解每个时刻被选中的原因。它绝不会上传、发布或发送任何录像数据到任何地方；CLI 本身不会发起任何网络调用，除了一个可选的、一次性下载 Whisper 模型的请求，且该请求会事先询问用户。

前提条件

• 路径中存在 uvx（来自 uv）或 pipx。CLI 是一个 Python 包；uvx clip-anything 无需安装即可运行。
• 路径中存在 ffmpeg 和 ffprobe。如果缺少它们，CLI 会返回退出码 3 并显示安装命令。
• 用户能指向一个录像文件：.mp4 .mkv .mov .m4v .ts .m2ts .mts .webm .avi .flv，或多个文件、或一个包含这些文件的文件夹。

指令

从用户当前目录开始工作。使用用户给出的确切路径；对路径加引号。不要移动、重命名或删除录像文件。除了在以下步骤中打印出来并建议用户运行的内容外，不要安装任何其他东西。

工作流程

（按顺序执行步骤；如果有步骤无法完成，则报告该问题，而不是跳过它。）

1. 检查工具。 运行 command -v uvx || command -v pipx 和 command -v ffmpeg && command -v ffprobe。如果 uvx 和 pipx 都缺失，打印并停止： curl -LsSf https://astral.sh/uv/install.sh | sh （macOS/Linux） 或 winget install astral-sh.uv （Windows）。 如果 ffmpeg 缺失，打印并停止：brew install ffmpeg / sudo apt install ffmpeg / winget install Gyan.FFmpeg。 如果只有 pipx 可用，则在本文档中使用 pipx run clip-anything 代替 uvx clip-anything。
2. 解析输入。 如果用户指定了文件或文件夹，则直接使用。如果用户说“我的录像”但没有提供路径，则在当前目录中查找视频文件（按上面列出的扩展名搜索，最新的优先）。只有当存在多个合理的输入或没有输入时才询问用户；否则继续并说明使用了哪个路径。接受文件夹作为输入：CLI 会将其视为一个会话。
3. 始终先执行干运行。 运行 uvx clip-anything "<input>" --dry-run --json 2>/dev/null （如果用户指定了数量，则添加 --count N）。解析标准输出的 JSON。显示一个简短的表格：排名、start 到 end（格式为 mm:ss）、duration_s、score、title（如果存在）以及来自 components 的主要组件。如果 clips 为空，则直接说明情况，并读取 warnings（below_floor 警告表示没有片段超过动作门槛），然后建议使用 --min-score 0 或更低的数值。
4. 渲染。 除非用户只要求预览，否则运行 uvx clip-anything "<input>" 并使用相同的选项，不包含 --dry-run 和 --json，以便显示进度界面。仅当用户表示需要字幕并且同意一次性模型下载时，才添加 --yes 参数；否则让 CLI 自行询问。报告输出文件夹（默认为 ./clips，或由 --out 指定）。
5. 解释选择。 读取 clips/report.json（直接读取文件，或使用 python3 -I -c 处理）。对于每个 ok 的剪辑，给出以下信息：时间跨度、得分以及支持该剪辑的信号（components：相对于基线的响度、音频起始点、运动、音频/运动一致性、静态卡片惩罚、语音奖励）。当 layout 为 facecam 时提及，当 captions 为 true 时提及。用通俗的语言列出 warnings 中的每一条信息；工具会主动说明降级情况，用户应该知道。
6. 提供可调参数，每行一个，只给出与用户看到的情况匹配的参数：
   • --count N 更多或更少的剪辑（这是最大值；安静的会话会返回更少）
   • --min-score 0.3 降低动作门槛；--min-score 0 使文件与自身比较排名
   • --min 20 --max 60 剪辑长度范围（秒）
   • --crop center 静态中心裁剪，而不是跟随动作
   • --no-captions 从不嵌入字幕；--facecam off 不合成摄像头画面
   • --vision 使用本地 Ollama 进行重排名和生成标题（实验性；仅与 127.0.0.1:11434 通信）
   • --force 覆盖上一次运行的剪辑；--no-cache 忽略缓存的分析结果 使用不同参数重新运行只需几秒钟，因为分析结果已缓存在视频旁边。
7. 声明。 当存在字幕或标题时，请说明一次：字幕是机器转录（faster-whisper，本地），标题来自本地视觉模型；两者都可能出错，发布前应检查。

示例

• “从昨晚的直播中制作 5 个短视频，文件在 ~/Videos/obs/ 里” → 步骤 1，传入文件夹，--count 5 干运行，显示表格，渲染，解释。
• “为什么它选了一个加载画面？” → 打开 report.json，显示该剪辑的 components（高 card 值表示静态卡片惩罚被触发，但响亮的起始点仍然胜出），建议使用 --min-score 0.6 或在 --config TOML 文件中设置更高的 w_card。
• “只展示它会剪什么，不要渲染” → 仅执行步骤 1 到 3。

限制

• 以转录为主的时刻（例如一个没有动作的笑话）得分较低，这是有意为之；工具对动作进行排名，语音只是一个奖励。
• 动作门槛是基于两个游戏校准的；如果遇到未见过的游戏，返回的剪辑可能少于要求的数量。应如实告知，而不是未经请求就使用 --min-score 0 强制生成剪辑。
• 1080p60 源的解析速度约为每小时 100 秒；多小时的视频文件需要等待，但不会卡死。
• 该技能不会编辑剪辑、选择缩略图或发布到任何地方。发布是由用户自行完成的步骤。

故障排除

• 退出码 2：输入错误（路径不存在、不支持的文件、文件夹中没有视频）。显示 CLI 的消息。
• 退出码 3：ffmpeg 或 ffprobe 缺失。打印步骤 1 中针对用户操作系统的安装命令。
• 退出码 1：没有渲染任何内容。读取干运行 JSON 中的 warnings；通常是 below_floor。
• 字幕以旁白 .ass 文件形式写入而不是嵌入：这是因为 ffmpeg 构建没有 libass（标准 Homebrew 公式）。使用支持 ffmpeg-full 构建并将它放在 PATH 中可以解决；其他一切仍可正常工作。
• --vision 没有效果：Ollama 未运行或没有视觉模型；运行将继续仅使用动作分析，并留下一条警告。