chengfeng-videocut 本地口播剪辑 Agent：Codex 插件安装路径与能力边界

chengfeng-videocut 是一套面向中文口播创作者的本地剪辑工具，由开发者成峰（GitHub 账号 Agentchengfeng）维护，代码以 Apache-2.0 协议开源。它的工作方式是让 AI 助手读转录文本、标出该删掉的片段，再由装在本机的工作台程序执行实际的剪切与导出。素材、转录结果和工程文件都留在本地，不经过云端服务。

先说版本情况。这个项目在 2026 年 1 月前后随着一批中文介绍被更多人知道，当时流传的安装方法是把仓库克隆进 Claude Code 的技能目录。仓库此后改了名字、重组了结构，现在公开的安装入口是 Codex 插件，早期教程里的那几条命令已经对不上。下面的内容按官方仓库当前的说明整理。

项目由哪几部分组成

Codex 插件提供剪口播、字幕、画面、导出四项能力，本地 Runtime 执行剪辑与导出

插件提供方法，本地 Runtime 执行剪辑

三块东西分开发布、分开编号，这是理解整个项目的前提：

插件（Plugin）：给 AI 助手提供方法和确认工具，本身不执行工程操作。当前版本 0.10.11，仍是预发行状态，仓库为 chengfeng-videocut-skills。
Runtime 与 Studio：执行工程操作的本机程序，附带一个跑在浏览器里的审核工作台，公开下载版本是 v0.4.11，仓库为 chengfeng-videocut。
六个独立 Skill 包：安装与接入、剪口播、字幕、导出、维护与排障、镜头设计，各自维护，标签都停在 v0.1.0-beta.1 的源码预览阶段。

官方文档反复强调这三者的验收是分开的：装上插件不等于工作台可用，工作台能启动也不等于整条剪辑链路跑得通。这种写法在开源项目里不算常见，也大致说明了它现在的成熟度。

七个入口分别产出什么

插件目前注册了七个可调用的能力，官方把每一个的产出物都写死了：

剪口播：输出复核过的删词账本，不生成任何媒体文件
字幕：输出 subtitles.json，时间轴按账本重算，当前版本不再单独发 SRT
画面：输出 visuals.json 与 HTML 模块
导出：把剪辑、推近、字幕、画面层一次烧成 mp4 成片
上报 Bug：先生成脱敏草稿，用户确认同一份正文后才调用 GitHub CLI 提交
检查更新：解析官方快照并给出来源证明，用户确认后才改动已有安装
工作台操作：0.10.11 新增，用于定位词句、覆盖或移除画面、拆分裁剪已有片段

剪口播不直接改原片，而是先交出一份可以逐条核对的删词清单，人工确认之后才进入执行环节——这道人工闸门是整套流程里最关键的设计。

最后一项有个前置条件需要留意：工作台操作要求 Runtime 0.5.9 及以上，而当前公开下载的 Runtime 仍是 0.4.11，缺少它要求的 workbench 接口。插件在能力不满足时只报告并停止，不会自动降级或升级。换句话说，这项新能力眼下装了也用不上。

安装：现在走 Codex 插件

前提是三样东西：Node.js 18 以上（准备 Runtime 的安装引导要求 20 以上）、Git，以及一个已登录、支持 codex plugin 命令的 Codex CLI。按 Release 给出的完整提交取得源码并核对 HEAD 之后，在该目录执行：

node bin/install.cjs install --dry-run
node bin/install.cjs install
node bin/install.cjs doctor

安装器只调用宿主支持的插件命令，并回读来源、克隆提交和安装状态；碰到同名或来源不明的已有安装会拒绝覆盖，官方也明确写了不要靠删除安装目录绕过这道检查。版本身份同样锁死：installer-manifest.json 里 marketplaceRef 和 pluginRef 固定在同一个提交上，安装时不跟随 main 或 stable 漂移。

已知问题写在 README 里：npm 10.9.2 按完整提交做 Git 打包时可能报 GitFetcher requires an Arborist constructor。这是引导阶段就失败了，插件一个字节都没有装上，此时不应该改用未锁定的 main 或 stable 分支重试。

插件装好之后，Runtime 要另外准备。macOS arm64 在缺少 Bun 时会从固定的官方资产下载，校验 SHA-256 后存进产品私有目录，不动全局 Bun 和 shell 配置。其他平台的自动依赖准备、桌面安装包、媒体依赖与常驻服务，官方说明里写的是不在本次验证范围，这一点对 Windows 用户尤其关键。

只想装其中某一个独立 Skill 的话，走的是另一个仓库的命令：

npx -y github:Agentchengfeng/chengfeng-videocut-install#v0.1.0-beta.1 plan --host codex
npx -y github:Agentchengfeng/chengfeng-videocut-install#v0.1.0-beta.1 install --host codex
npx -y github:Agentchengfeng/chengfeng-videocut-install#v0.1.0-beta.1 doctor --host codex

文件默认落在用户目录下的 .agents/skills/，Codex 模式会额外建一个 .codex/skills/ 入口；省掉 --host codex 则只装中性的 Agent 目录。首次试用应给三条命令都加上 --target-root 指向一个空目录，不要拿真实的用户安装目录做第一次测试。

还有一件事需要点明：仓库简介至今写着「用 Claude Code Skills 做的视频剪辑 Agent」，但现行安装文档只给了 Codex 入口和中性的 .agents 目录，没有对应的 Claude Code 安装说明。早期教程里 git clone 到 ~/.claude/skills/videocut 再执行 /videocut:安装 的做法，对应的是已经改名的旧仓库，现在照抄不会成功。想了解 AI 助手侧的技能安装机制，可以先看 find-skills 让 AI 助手自己发现和安装技能这篇。

一次剪辑大致怎么走

本地口播剪辑的五个环节

素材导入后先在本机完成转录，Agent 据此生成删词账本，人工在 Studio 里对照视频、逐字稿、字幕和时间线确认保留哪些、删掉哪些。确认后的剪切提交会校验选择与工程修订，避免多个写入者互相覆盖。最后由导出环节把剪辑、字幕和画面层一次烧成成片，编码执行归 Runtime，插件只负责编排。

Studio 本身有门禁：只在人工审核状态下、并通过顶层视图能力检查后才会打开。Runtime 提供的托管时间线操作包括移动、裁剪、拆分和删除四种，产品形态上更接近一个有 CLI 接口的审核工作台，而不是完整的非线性编辑器。

数据去向与许可条款

Studio 与 CLI 的核心流程在本机运行，服务默认绑定 127.0.0.1。官方说明写明：项目文件、媒体、转录和剪切结果不会因为使用本产品而自动上传，产品也不包含分析遥测或使用行为上报。会联网的部分是安装器和版本更新（访问 GitHub），以及用户主动选用的 Google Fonts、自己在项目 HTML 里加的远程图片和第三方插件。第三方渲染器或 AI 服务是否联网，由它们各自的配置决定。

许可稍微复杂一点。项目自有代码与 HyperFrames 派生代码按 Apache-2.0 发布，Studio 和部分运行时能力改自 HyperFrames 0.7.54，上游版权已保留。但分发的便携包还捆绑了 GSAP 3.15.0 与 MotionPathPlugin，这两项单独受 GSAP Standard License 约束，不适用 Apache-2.0。商业用途上线前需要把这条单独核对一遍。

几点判断

中文介绍里常被引用的 FunASR、Whisper large-v3 和约 5GB 模型权重，对应的是年初那一版的安装流程，当前官方仓库的公开文档里没有再列出这些模型名称。想确认转录引擎到底用什么，以实际安装后 doctor 的输出和对应 Release 说明为准，不要照着旧文章的描述规划硬盘和网络。

适用边界也比较清楚。只是想把口播里的静音和明显口误删掉，成熟商业剪辑软件加自动转写已经能覆盖大半需求，上手成本低得多。这套方案的价值集中在两点：删词判断交给 Agent 去做，以及素材和转录全程不出本机。对素材保密有硬性要求、又习惯命令行的创作者更适合投入时间，而项目整体仍在预发行阶段，短期内更适合做试验性使用，不宜直接放进有交付节点的生产流程。

同类的自托管路线可以一起比较，YumCut 开源 AI 短视频生成器走的是生成方向，成本账和部署条件都更重；想看 Agent 驱动的完整视频链路怎么分工，Codex 视频制作全流程：4 个插件与 Skill 从脚本到成片里的拆解更系统。传统路线的参照仍然是剪映这类图形界面工具。