Skill ffmpeg-skill 让编码智能体安全调用本地FFmpeg剪辑视频

写代码的智能体现在普遍能读能写，却常常卡在一个看似简单的问题上：让它们帮你剪一段视频、转个格式、截一张动图，结果往往是一串拼错的 ffmpeg 命令，要么根本跑不起来，要么在不知情的情况下把源文件覆盖掉。视频文件一旦被错误处理，损失几乎不可逆，这让很多团队不敢把媒体处理交给智能体。

ffmpeg-skill 给 Claude Code、Codex 这类编码智能体补上了 42 个本地视频处理工具。它不靠把命令当字符串丢给 shell，而是用带类型约束的脚本把每个操作变成智能体能够读懂、也能够被程序校验的能力，从根本上避免了“猜参数、拼命令”的脆弱做法。

对日常需要在仓库里顺手产出演示素材、短视频或封面的开发者来说，这种既能干活又不会闯祸的封装，比直接让智能体拼命令行要可靠得多。它把视频处理从一项高风险操作，变成了一项可以放心委托的常规任务。

项目基本信息

一、项目介绍

在实际研发里，视频处理之所以难交给智能体，核心矛盾在于 ffmpeg 的强大与危险并存：参数组合成千上万，一个 -ss 放错位置就可能从截断变成全量重编码，而智能体没有“眼见为实”的能力，只能照着训练记忆拼命令。ffmpeg-skill 的解法不是更强地提示模型，而是把能力收口到受控的工具集里。

值得一提的是，它把“先测量、再决策、后校验”的工程闭环直接做进了工具设计。很多同类方案只提供命令模板，而 ffmpeg-skill 强制每个任务从 probe.py 的真实探测数据出发，这让智能体的行为从“猜”变成了“算”，稳定性提升明显。

从定位上看，它更适合作为编码智能体的“媒体手脚”，而不是一个独立的剪辑软件。开发者在写代码的过程中顺手产出素材，工作流是连续的；如果目标是专业影视剪辑，那它显然不是替代品。

落地建议：先在个人项目里用 doctor 跑通环境，再把最重复的转码、抽帧动作交给它，逐步建立信任，再扩展到更细的视频处理流程。

和直接让智能体调用 ffmpeg 命令行相比，它的优势是确定性：每一步的输入输出都被契约约束，失败的代价是“这一项没做成”，而不是“源文件被覆盖”。这种可预期性，正是把 AI 接进生产流程的前提。

需要留意的边界是，它强依赖本机 ffmpeg 的质量与版本。某些特殊编码格式若本机 ffmpeg 不支持，工具也无能为力；另外它擅长单文件处理，超大规模的批量流水线仍建议配合脚本编排。

二、核心优势

• 真实文件优先：每个任务都从 probe.py 实测视频的时长、帧率、分辨率开始，智能体基于真实测量结果决策，而不是凭空猜测参数，从源头减少出错。
• 结构化工具而非 shell 字符串：每个操作都是带类型参数的脚本，全程不经由 shell 执行，既避免了命令注入，也消除了参数拼接时常见的引号与转义错误。
• 可读契约：contract 命令把每个工具能接收什么、会写出什么、依赖哪段 ffmpeg 语法完整列出来，智能体先读契约再行动，行为变得可预测、可审计。
• 执行后校验：结果会被重新探测并与目标规格比对，当画面发生变化时自动发现偏差并修正，形成“执行—校验—修正”的闭环，而不是一跑了之。

三、适用场景

• 在代码仓库里顺手生成项目演示视频、GIF 封面或短视频片段，无需切换专业剪辑软件。
• 批量转码、加水印、抽帧、生成缩略图等重复的媒体处理任务，交给智能体按计划完成。
• 需要本地、离线、不依赖任何云 API 密钥的隐私敏感场景，比如内部素材处理。

四、安装教程

本项目支持跨平台运行（Windows / macOS / Linux）。基础安装命令如下：

注意：需要本机已安装 ffmpeg。首次使用建议先跑 doctor 自检环境是否就绪。

常见报错与处理：

• 命令找不到（command not found）：多为未安装对应运行时（Node / Python / uv / Homebrew），请先确认环境就绪。
• 网络超时或 403：可切换为国内镜像源，或检查代理设置后重试。
• 权限错误（EACCES）：避免用 sudo 全局安装，建议使用版本管理器或用户级前缀。

五、使用示例

以下为真实可运行的使用方式（输入与预期输出）：

输入：
  npx ffmpeg-skill contract --json | head -40

输出（节选）：
  {
    "tools": [
      {"name": "trim", "inputs": ["src","start","end"],
       "writes": "out.mp4", "ffmpeg": "-ss {start} -to {end}"},
      {"name": "resize", ...}
    ]
  }
智能体据此知道 trim 需要源文件、起止时间，并会写出 out.mp4，无需猜测语法；后续调用也都遵循这份契约。

六、常见问题

问：没有 ffmpeg 能跑吗？

答：不能。ffmpeg-skill 是 ffmpeg 的结构化封装，本机必须预先装好 ffmpeg，可用 doctor 命令检查是否就绪，缺依赖时它会给出明确提示。

问：会把我原来的视频覆盖掉吗？

答：默认每个工具都会写出新文件，且执行后有校验环节，按契约生成独立输出，不会直接覆盖源文件，可以放心让智能体操作。

七、总结

ffmpeg-skill 把视频处理从“赌一把的命令行”变成智能体能安全调用的结构化能力，本地优先、契约可读、结果可校验。对需要反复处理媒体素材的编码工作流，它既提升了可靠性，也降低了让智能体碰命令行带来的风险，是编码智能体能力版图里一块务实而关键的补丁。