项目分享|videocut-skills：Claude Code专属视频剪辑Agent，一键搞定口播优化

1. 口播剪辑的真实痛点为什么我宁愿把时间花在写脚本上录一条三分钟的口播前期写稿可能只花二十分钟后期剪辑却能拖掉一个半小时。这不是夸张是我自己做知识类短视频前三个月的常态。素材导进时间线先要一帧一帧听哪里卡壳了哪里「嗯」「啊」「那个」冒出来哪里停顿超过一秒显得尴尬。手动剪完一遍导出再看又发现漏了两处口误只能回去重剪。字幕更磨人自动识别出来的文本错字连篇专业名词全给你识别成谐音改字幕的时间比剪视频还长。这个场景几乎每个口播创作者都经历过。问题不在于剪辑软件不好用而在于「逐帧人工判断」这件事本身就不该由人来做。人耳对静音和语气词的敏感度有限听久了会疲劳漏检是必然的。而 AI 语音识别在逐字级的时间戳精度上早就超过了人耳的判断能力。videocut-skills 这个项目就是冲着这个痛点来的。它是 Ceeon 团队开发的一套 Claude Code 专属视频剪辑 Agent以 Claude Code Skills 的形式存在把口误识别、静音检测、语气词处理、字幕生成这几件事串成了一条自动化流水线。你不需要打开任何剪辑软件不需要拖时间轴只需要在 Claude Code 的对话框里输入命令Agent 会先转录、再生成一份「审查稿」告诉你打算删哪些片段你确认之后它调用 FFmpeg 执行剪辑最后把字幕烧录进去。适合谁用三类人最直接受益一是日更或隔日更的口播博主批量处理素材的需求最强二是做在线课程录制的老师一节课四五十分钟静音和口误密集三是刚入门、还没学会 Premiere 或 Final Cut 的新手用命令行的方式反而比学软件更快出片。如果你已经在用 Claude Code 写代码或做其他自动化任务那这套 Skills 的接入成本几乎为零。我实测下来一条八分钟的口播素材从导入到出成片包括人工确认审查稿的时间大概在十二到十五分钟。同样的素材纯手动剪我至少要花五十分钟以上。效率差距主要来自「识别」和「执行」两个环节的自动化人只需要做「确认」这一个动作。下面我会从环境准备开始把 TaoToken 的接入配置、videocut-skills 的安装、一次完整口播成片的验证流程以及我踩过的几个报错全部拆开讲清楚。你跟着做应该能在一个小时内跑通第一条片子。2. 前置准备用 TaoToken 给 Claude Code 接上稳定的大模型通道videocut-skills 本身是跑在 Claude Code 里的 Skills它的「大脑」是 Claude 模型。Claude Code 默认走官方通道但在国内网络环境下直连经常遇到超时、断流、请求失败的问题。我一开始也是硬扛结果转录到一半 Agent 卡住不动审查稿生成不出来排查半天发现是模型请求超时了。后来我改用 TaoToken 作为 Claude Code 的模型接入层。TaoToken 是一个大模型 API 聚合服务提供兼容 Anthropic 协议的接口Claude Code 只需要改两个环境变量就能接上。它的作用是让模型请求走一条稳定的通道避免因为网络抖动导致 Agent 执行中断。对于 videocut-skills 这种需要多轮对话、多次模型调用的场景通道稳定性直接决定了整个流程能不能跑完。你需要先拿到一个 API Key。访问 TaoToken 的 API Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite注册后创建一个新的 Key复制出来备用。这个 Key 就是 Claude Code 调用模型时的凭证。接下来配置 Claude Code 的接入地址。TaoToken 的 API 端点是 https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。Claude Code 读取的是环境变量macOS 和 Linux 下在终端里执行export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken API KeyWindows 下用 PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEY你的TaoToken API Key如果你希望每次打开终端都自动生效可以把这两行写进~/.bashrc或~/.zshrc。Windows 则通过「系统属性 → 环境变量」添加。配置完成后先验证一下通道是否通。在终端里跑一个最简单的请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的TaoToken API Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复ok}] }如果返回的 JSON 里有正常的文本内容说明通道没问题。如果返回 401检查 Key 是否复制完整如果返回连接超时检查 Base URL 是否写成了带路径的形式正确写法就是https://taotoken.net/api不要在后面加/v1。这里有个细节要注意Claude Code 在启动时会读取环境变量如果你是在 Claude Code 已经打开的情况下才设置的变量需要重启 Claude Code 才能生效。我第一次配置完没重启Agent 一直报模型不可用折腾了十分钟才发现是这个原因。通道通了之后Claude Code 的所有模型请求都会走 TaoToken。你可以在 Claude Code 里输入/status查看当前使用的模型和端点确认 Base URL 显示的是 taotoken.net。这一步确认完就可以进入 videocut-skills 的安装了。3. 可复制配置videocut-skills 安装与 Claude Code 接入参数videocut-skills 的安装分两步先把项目克隆到 Claude Code 的 skills 目录然后在 Claude Code 里触发自动安装命令让它下载依赖和模型。先确认你的本地环境满足最低要求Python 3.8 以上磁盘剩余空间至少 8GB模型约 5GB加上依赖和临时文件网络通畅。FFmpeg 不需要提前装安装脚本会自动处理。克隆项目。macOS 和 Linux 下git clone https://github.com/Ceeon/videocut-skills.git ~/.claude/skills/videocutWindows 下git clone https://github.com/Ceeon/videocut-skills.git %USERPROFILE%\.claude\skills\videocut克隆完成后打开 Claude Code在对话框里输入/videocut:安装Agent 会自动执行安装脚本依次安装 FFmpeg、FunASR、Whisper 等依赖并下载 Whisper large-v3 和 FunASR 的模型文件。整个过程大约 5 到 10 分钟取决于你的网络速度。安装过程中终端会输出进度看到「安装成功」的提示就说明完成了。这里有一个关键配置需要你手动确认videocut-skills 在调用模型做审查稿生成和决策时走的是 Claude Code 当前的模型通道。也就是说你前面配置的 TaoToken 环境变量会直接作用于 videocut-skills 的模型调用。如果你在 Claude Code 里切换了模型videocut-skills 也会跟着切换。为了确保配置一致建议在 Claude Code 的 settings 文件里显式声明模型和端点。Claude Code 的配置文件通常位于~/.claude/settings.json你可以加入以下内容{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken API Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(ffmpeg:*), Bash(python:*), Bash(whisper:*) ] } }这个 JSON 片段做了三件事固定了 Base URL 和 Key指定了模型 ID并且给 FFmpeg、Python、Whisper 相关的命令开了执行权限。videocut-skills 在剪辑和字幕烧录阶段会频繁调用 FFmpeg如果权限没开Agent 会卡在「等待授权」的状态。如果你用的是 Claude Code 的 coding-plan 模式配置方式略有不同。coding-plan 模式下Claude Code 会读取项目级的.claude/settings.json你需要在 videocut 的 skills 目录下也放一份同样的配置或者直接在全局 settings 里配置。我建议用全局配置避免每个项目都要重复设置。配置写完后重启 Claude Code输入/videocut:剪口播测试一下 Skills 是否被正确加载。如果 Claude Code 能识别出这个命令并开始询问视频文件路径说明安装和配置都成功了。还有一个容易忽略的点videocut-skills 的模型调用量不小。一次八分钟的口播视频转录加审查稿生成加剪辑决策大概会消耗 3 到 5 万 token。如果你用的是按量计费的 Key建议先充一点额度避免跑到一半因为余额不足中断。TaoToken 的控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里可以查看用量和余额。4. 验证请求一次完整口播成片的实操流程配置就绪后我们跑一条完整的口播视频从素材导入到成片导出把每个环节的输入输出都过一遍。准备一条口播素材格式 MP4时长控制在十分钟以内方便快速验证。把文件放在一个你记得住的路径比如~/videos/raw/test01.mp4。第一步在 Claude Code 里触发剪口播命令/videocut:剪口播 ~/videos/raw/test01.mp4Agent 收到命令后会先调用 Whisper 做语音转录生成带时间戳的文本。转录完成后它会调用 FunASR 做语音分析识别三类问题片段口误说错后重说的部分、语气词「嗯」「啊」「那个」「就是」等、静音能量低于阈值且持续超过 1 秒的片段。识别完成后Agent 会生成一份审查稿格式类似审查稿 - test01.mp4 总时长08:23 识别到问题片段14 处 [1] 00:00:12 - 00:00:14 语气词「嗯」 [2] 00:01:05 - 00:01:08 静音 3.2 秒 [3] 00:02:18 - 00:02:21 口误「这个这个」 [4] 00:03:40 - 00:03:42 语气词「那个」 ... [14] 00:07:55 - 00:07:58 静音 2.8 秒 确认删除以上片段回复「确认」执行剪辑或指出需要保留的片段。这一步是整个流程里唯一需要人工介入的地方。你要做的是快速扫一遍审查稿看看有没有误判。比如某个专业术语被当成了口误或者某段有意的停顿被当成了静音。如果有直接回复「保留第 3 条和第 7 条」Agent 会重新生成审查稿。确认无误后回复「确认」。Agent 调用 FFmpeg 执行剪辑删除所有标记片段输出一个中间文件test01_cut.mp4。剪辑完成后Agent 会自动做一次循环审查重新检测剪辑后的视频是否还有遗漏的问题片段。如果没有进入字幕环节。第二步生成并烧录字幕/videocut:字幕 ~/videos/raw/test01_cut.mp4Agent 用 Whisper large-v3 转录文本然后通过词典纠正功能修正专业名词和常见错字。纠正后的文本生成 SRT 字幕文件再调用 FFmpeg 把字幕烧录到视频里。你可以指定字幕样式/videocut:字幕 ~/videos/raw/test01_cut.mp4 字幕颜色白色字体大小24底部居中烧录完成后输出最终文件test01_final.mp4。整个流程从触发剪口播到出成片我实测大约十二分钟其中人工确认审查稿花了不到两分钟。第三步验证成片。打开test01_final.mp4重点检查三件事语气词和静音是否被干净删除剪辑点是否自然有没有突兀的跳切字幕是否与语音对齐。如果发现某个剪辑点不自然可以反馈给 Agent/videocut:自更新 第 5 个剪辑点前后各保留 0.3 秒缓冲避免跳切太生硬Agent 会记录这条偏好下次处理同类视频时自动应用。这就是自更新模块的作用用得越多剪辑风格越贴合你的习惯。如果你要批量处理多条视频可以把多个文件路径一起传给 Agent/videocut:剪口播 ~/videos/raw/ep01.mp4 ~/videos/raw/ep02.mp4 ~/videos/raw/ep03.mp4Agent 会依次处理每条都生成独立的审查稿你逐条确认即可。批量模式下建议先把所有审查稿过一遍再统一确认避免来回切换。5. 常见报错排查401、local proxy failed 与 reading choices 的解法这一节把我踩过的坑和社区里高频出现的报错整理出来你遇到问题时可以直接对照。报错一401 UnauthorizedError: 401 Unauthorized - invalid x-api-key这个报错说明 Claude Code 调用模型时 Key 无效。排查顺序先确认ANTHROPIC_API_KEY环境变量是否设置正确在终端里执行echo $ANTHROPIC_API_KEY看输出是否和你复制的 Key 一致。如果环境变量没问题检查 Key 是否在 TaoToken 控制台里被禁用或删除。还有一种情况是 Key 复制时带了空格或换行重新复制一次确保首尾没有空白字符。报错二local proxy failedError: local proxy failed - connection refused这个报错通常出现在 Claude Code 启动时说明它尝试连接的本地代理端口没有服务在监听。如果你之前配置过本地代理工具检查代理是否还在运行。如果你没有用代理检查ANTHROPIC_BASE_URL是否被错误地设置成了http://localhost:xxxx之类的地址。正确值应该是https://taotoken.net/api。另外某些终端会继承系统的 HTTP_PROXY 环境变量执行unset HTTP_PROXY HTTPS_PROXY清除后再试。报错三reading choices 相关错误Error: reading choices - unexpected end of JSON input这个报错说明模型返回的响应体不完整通常是网络中断导致的。videocut-skills 在生成审查稿时会要求模型返回结构化的 JSON如果响应被截断解析就会失败。解决办法检查网络稳定性如果用的是不稳定的通道换到 TaoToken 的稳定端点重试。另外把max_tokens设置得太小也会导致响应被截断Claude Code 默认的 max_tokens 通常够用但如果你手动改过建议调回默认值。报错四OAuth 相关错误Error: OAuth token expired - please re-authenticate如果你之前用 Claude Code 的官方登录方式做过 OAuth 认证切换到 TaoToken 后可能会残留旧的认证信息。解决办法删除~/.claude/目录下的认证缓存文件通常是auth.json或credentials.json然后重新用环境变量方式配置。Claude Code 会优先读取环境变量里的 Key不再走 OAuth 流程。报错五FFmpeg 权限被拒绝Error: Bash(ffmpeg:*) permission denied这个报错说明 Claude Code 没有获得执行 FFmpeg 的权限。回到第 3 节的 settings.json 配置确认permissions.allow里包含了Bash(ffmpeg:*)。如果你用的是 Claude Code 的交互模式Agent 会在第一次调用 FFmpeg 时弹出授权请求选择「始终允许」即可。如果之前误点了「拒绝」需要在 settings 里手动加上。报错六模型 ID 不匹配Error: model not found - claude-sonnet-4-20250514这个报错说明你配置的模型 ID 在当前通道下不可用。检查 TaoToken 的模型列表确认你使用的模型 ID 拼写正确。Claude Code 的模型 ID 格式通常是claude-sonnet-4-20250514或claude-opus-4-20250514注意日期后缀不能省略。如果你不确定用哪个可以在 TaoToken 的模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里测试一下模型是否可用。排查完这些报错基本能覆盖 90% 的接入问题。如果遇到其他错误先看 Claude Code 的日志输出日志里会包含具体的请求 URL 和响应状态码根据状态码定位问题会快很多。6. 从能跑到好用videocut-skills 的调优与长期使用建议跑通第一条片子之后你会发现 videocut-skills 的默认配置已经能处理大部分场景但要想让它真正贴合你的口播风格还需要做一些调优。第一件事是调整静音检测阈值。默认阈值是 1 秒但不同创作者的语速和停顿习惯差异很大。语速快、停顿短的博主可以把阈值调到 0.8 秒避免把正常的换气停顿误删。语速慢、停顿多的可以调到 1.5 秒确保长停顿被清理干净。调整方式是在自更新命令里说明/videocut:自更新 静音检测阈值调整为 0.8 秒第二件事是维护一个个人词典。Whisper 在转录专业术语、人名、品牌名时经常出错比如把「Transformer」识别成「传斯福默」。你可以在 videocut-skills 的配置目录里放一个dict.txt每行一个「错误写法正确写法」的映射Agent 在生成字幕时会自动替换。这个词典越用越准处理同类内容的效率会明显提升。第三件事是合理使用批量模式。批量处理虽然省事但审查稿的确认环节不能省。我的做法是批量跑完转录和识别把所有审查稿导出到一个文本文件里集中花十分钟过一遍标记出需要保留的片段再统一回复确认。这样比逐条处理快又不会因为跳过确认导致误删。关于成本videocut-skills 的模型调用量主要花在转录和审查稿生成上。一条十分钟的视频大约消耗 3 到 5 万 token按 TaoToken 的计费标准单条成本在可接受范围内。如果你要处理大量素材建议关注 TaoToken 的 coding-plan 方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite长期编码和 Agent 类任务用 plan 模式更划算。最后说一个我自己的使用习惯每次处理完一条视频花三十秒回顾一下审查稿里有没有误判有的话立刻用自更新命令反馈。坚持一两周之后Agent 的剪辑决策会明显更贴合你的预期误判率大幅下降。这个反馈循环是 videocut-skills 相比传统剪辑工具最大的优势——它不是一次性的工具而是一个会随着使用逐渐进化的助手。如果你还没开始用建议先拿一条三分钟以内的短素材试手跑通全流程后再处理长视频。接入文档在 TaoToken 的文档页面https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite可以找到更详细的协议说明和参数配置。