cut-talking-head

Cut spoken-word

This is the first business entry point of chengfeng-videocut . The only target output is:

source_cut.mp4 + subtitles.srt

The Skill performs semantic judgment and orchestration; the product Runtime is the sole writer of projects, Cuts, media cuts, and Studio state.

0. Always do a Runtime pre-check first

Set SKILL_DIR to the absolute path of the directory where the current SKILL.md is located; do not assume the plugin installation location:

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 与产品契约](../../references/runtime-and-product-contract.md)。

## 1. 接受真实输入

只接受用户给出的真实口播视频或现有真实项目。没有真实媒体就停止；禁止用示例、占位视频或浏览器里的其他项目顶替。

```text
[真实视频]
    |
    v
[逐词转录 + 稳定 wordIds]
    |
    v
[Product project prepare]

If the Runtime does not yet provide a raw-video transcription command, you may use the ASR capability already permitted in the current environment to generate word-by-word candidates within the task directory; if no ASR is available, explicitly report missing_transcription_adapter, do not open Studio, and do not fabricate a transcript.

Prepare the project:

node "$VC" project prepare "$jobDir" \
  --video "$taskLocalVideo" \
  --transcript "$taskLocalTranscript" \
  --json

--video and --transcript must be real files within the task directory. If a canonical project already exists, first workflow get, and do not repeatedly create projectId。

2. Generate and submit word-deletion candidates

First read semantic deletion rules. Candidates reference only stable wordIds：

{
  "schemaVersion": 1,
  "cutWordIds": ["word-12", "word-13"],
  "reasons": [
    { "wordIds": ["word-12", "word-13"], "kind": "repeat", "risk": "low" }
  ]
}

Fixed principles:

• Deletion has only two states: "deleted / not deleted"; an AI reason does not form a third state of "suggested deletion".
• Slips of the tongue, repetitions, and incomplete sentences are deleted before and kept after by default; long sentences, whole sentences, and branching restatements must be reviewed as high risk.
• Ordinary pauses are not calculated by the Skill. Merging adjacent silences and natural-pause-v2 are performed deterministically by the Product.
• Do not directly write cut-selection.json、project.json or the event log.

When starting the product service, only headless startup is allowed; do not add --open：

node "$VC" start --host 127.0.0.1 --port 5190 --json

Run it with the background process capability provided by the environment. Then first read the latest revision, and then submit the candidates:

node "$VC" workflow get "$jobDir" --json
node "$VC" cuts set "$jobDir" \
  --file "$proposalFile" \
  --expected-revision "$latestRevision" \
  --json

3. Only open Studio at the manual review stage

Only when the transcript and Cuts have been written to disk and the workflow has entered cut_review_ready, open the same canonical Studio:

node "$VC" open "$jobDir" --json

Use Codex's built-in browser to open the returned URL and enter ?view=koubo. At this point, stop automatic progression and wait for the user to select words, restore, and save.

Do not:

• treat "open the workbench" as the first step of the task;
• visit old review.html, 8898, or 8899;
• control the Studio DOM or directly modify media elements;
• create independent audio tracks or placeholder subtitle tracks.

4. Confirmation card and physical cutting

After the user indicates that review is complete:

1. again workflow get, obtain the current projectId, project revision, and Cuts revision.
2. Call this plugin's MCP App show_workflow_confirmation, passing in:

projectId
stage=cut_review_ready
expectedProjectRevision
expectedCutsRevision
selectedCount（可选）
removedDuration（可选）

1. The card only returns the action and does not cut directly.
2. After receiving action=continue_cut , read the latest revision again; if it differs from the card's revision, stop and have the user verify the new edits.
3. Only execute when the revisions match:

node "$VC" cuts apply "$jobDir" \
  --expected-revision "$latestRevision" \
  --confirmed \
  --json

return_cut_review return to the same Studio;pause_workflow save the state and then stop.

5. Rebuild post-cut subtitles

After a successful physical cut, you must re-transcribe based on source_cut.mp4 . First read post-cut subtitle proofreadingDo not mechanically stitch the original subtitles into the final subtitles according to the deletion intervals.

Subtitle candidates passed product release:

node "$VC" workflow get "$jobDir" --json
node "$VC" artifact put "$jobDir" \
  --type subtitles \
  --file "$subtitleProposal" \
  --expected-project-revision "$latestProjectRevision" \
  --expected-artifact-revision "$latestSubtitleRevisionOrNone" \
  --json

Only when the media is decodable, has an audio stream, the trimmed subtitles have been published, and the timeline is valid can the base asset package be reported as complete.

Recovery and failure

• revision_conflict: reread the state, explain the user's just-made edit, do not automatically overwrite.
• media_has_no_audio: keep the original assets and the last valid output, stop delivery.
• runtime_unhealthy: do not repeatedly reinstall.
• Page closed but service still running: after reading the workflow, continue from the current state; do not create a new project.
• No failure may cause "can preview" to be described as "already edited".