| name | cut-talking-head |
| description | 剪辑中文口播原素材：逐词转录、识别口误与重复、生成删词候选、在 Studio 审核后执行可靠物理剪切，并重建剪后字幕。用户说剪口播、处理口误、生成口播基础素材、继续剪口播，或确认卡回传 action=continue_cut / return_cut_review 时使用。不要用于单独安装、单独打开工作台、普通视频编辑或口播分镜成片。 |
剪口播
这是 chengfeng-videocut 的第一个业务入口。目标产物只有：
source_cut.mp4 + subtitles.srt
Skill 做语义判断与编排；产品 Runtime 是项目、Cuts、媒体剪切和 Studio 状态的唯一写入者。
0. 每次先做 Runtime 预检
把 SKILL_DIR 设为当前 SKILL.md 所在目录的绝对路径，不要假定插件安装位置：
PLUGIN_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"
ENSURE="$PLUGIN_ROOT/scripts/ensure-runtime.cjs"
VC="$PLUGIN_ROOT/scripts/videocut-cli.cjs"
node "$ENSURE" --install-if-missing --json
必须把它作为当前任务的内联步骤：
ready：继续本 Skill。missing：脚本只提示一次“正在从 GitHub Release 安装”，校验完成后自动续跑。runtime_unhealthy、安装失败或安装后 doctor 失败：报告结构化诊断并停止。- 预检阶段禁止启动服务、打开 Studio 或创建项目。
详细协议见 Runtime 与产品契约。
1. 接受真实输入
只接受用户给出的真实口播视频或现有真实项目。没有真实媒体就停止；禁止用示例、占位视频或浏览器里的其他项目顶替。
[真实视频]
|
v
[逐词转录 + 稳定 wordIds]
|
v
[Product project prepare]
若 Runtime 尚未提供原视频转录命令，可使用当前环境已经获准的 ASR 能力生成任务目录内的逐词候选；若没有可用 ASR，就明确报告 missing_transcription_adapter，不要打开 Studio，也不要伪造 transcript。
准备项目：
node "$VC" project prepare "$jobDir" \
--video "$taskLocalVideo" \
--transcript "$taskLocalTranscript" \
--json
--video 与 --transcript 必须是任务目录内的真实文件。已有规范项目时先 workflow get，不要重复创建 projectId。
2. 生成并提交删词候选
先读 语义删除规则。候选只引用稳定 wordIds：
{
"schemaVersion": 1,
"cutWordIds": ["word-12", "word-13"],
"reasons": [
{ "wordIds": ["word-12", "word-13"], "kind": "repeat", "risk": "low" }
]
}
固定原则：
- 删除只有“删除 / 未删除”两态；AI 原因不形成“建议删除”第三态。
- 口误、重复和残句默认删前保后；长句、整句和分叉重说必须高风险复核。
- 普通停顿不由 Skill 计算。相邻静音合并与
natural-pause-v2 由 Product 确定性执行。
- 不直接写
cut-selection.json、project.json 或事件日志。
启动产品服务时只允许无头启动，不加 --open：
node "$VC" start --host 127.0.0.1 --port 5190 --json
用环境提供的后台进程能力运行它。然后先读最新 revision，再提交候选：
node "$VC" workflow get "$jobDir" --json
node "$VC" cuts set "$jobDir" \
--file "$proposalFile" \
--expected-revision "$latestRevision" \
--json
3. 到人工审核时才打开 Studio
只有 transcript 与 Cuts 已落盘、工作流已经进入 cut_review_ready，才打开同一个 canonical Studio：
node "$VC" open "$jobDir" --json
使用 Codex 内置浏览器打开返回的 URL，并进入 ?view=koubo。此时停止自动推进，等待用户划词、恢复和保存。
不要：
- 把“打开工作台”当任务第一步；
- 访问旧
review.html、8898 或 8899；
- 控制 Studio DOM、直接改媒体元素；
- 创建独立音频轨或占位字幕轨。
4. 确认卡与物理剪切
用户表示审核完成后：
- 重新
workflow get，取得当前 projectId、项目 revision 与 Cuts revision。
- 调用本插件 MCP App 的
show_workflow_confirmation，传入：
projectId
stage=cut_review_ready
expectedProjectRevision
expectedCutsRevision
selectedCount（可选）
removedDuration（可选）
- 卡片只回传 action，不直接剪切。
- 收到
action=continue_cut 后再次读取最新 revision；若与卡片 revision 不同，停止并让用户核对新编辑。
- revision 一致时才执行：
node "$VC" cuts apply "$jobDir" \
--expected-revision "$latestRevision" \
--confirmed \
--json
return_cut_review 返回同一 Studio；pause_workflow 保存状态后停止。
5. 重建剪后字幕
物理剪切成功后，必须基于 source_cut.mp4 重新转录。先读 剪后字幕校对。禁止把原始字幕按删除区间机械拼成最终字幕。
字幕候选通过产品发布：
node "$VC" workflow get "$jobDir" --json
node "$VC" artifact put "$jobDir" \
--type subtitles \
--file "$subtitleProposal" \
--expected-project-revision "$latestProjectRevision" \
--expected-artifact-revision "$latestSubtitleRevisionOrNone" \
--json
只有媒体可解码、有音频流、剪后字幕已发布且时间轴有效，才能报告基础素材包完成。
恢复与失败
revision_conflict：重新读取状态，说明用户刚才的编辑，不自动覆盖。media_has_no_audio：保留原素材和上一份有效产物，停止交付。runtime_unhealthy：不要循环重装。- 页面关闭但服务仍在：读取 workflow 后从当前状态续做，不新建项目。
- 任何失败都不得把“能预览”说成“已经剪好”。
