chengfeng-finish-talking-head

Voiceover final cut

This is chengfeng-videocut 's second business entry point. It consumes the already-reviewed basic material package and produces:

source_cut.mp4 + subtitles.srt
               |
               v
      storyboard / animation / timeline
               |
               v
        final.mp4 + verification.json

First read and execute the stage contracts of the two business Skills. This Skill only continues on an existing Product projectId and does not create projects, import materials, establish upload sessions or material libraries; any continuation keeps a fixed stage:preflight -> Product state readback -> proposal -> Product CAS -> project-level review binding -> user confirmation -> Product execution -> outcome verification。

0. preflight: perform a Runtime precheck first every time

PLUGIN_ROOT="$(codex plugin list --json | node -e 'let s=""; process.stdin.on("data", c => s += c); process.stdin.on("end", () => { const rows = JSON.parse(s).installed || []; const hit = rows.filter(x => x.enabled && x.name === "chengfeng-videocut" && x.source && x.source.path); if (hit.length !== 1) process.exit(1); process.stdout.write(hit[0].source.path); });')"
test -n "$PLUGIN_ROOT" && test -f "$PLUGIN_ROOT/.codex-plugin/plugin.json" || { echo "chengfeng-videocut enabled plugin root unavailable" >&2; exit 1; }
ENSURE="$PLUGIN_ROOT/scripts/ensure-runtime.cjs"
RUNNING="$PLUGIN_ROOT/scripts/ensure-running.cjs"
STUDIO="$PLUGIN_ROOT/scripts/ensure-studio.cjs"
VC="$PLUGIN_ROOT/scripts/videocut-cli.cjs"

node "$ENSURE" --install-if-missing --json

PLUGIN_ROOT comes only from the source.pathof the enabled Plugin lines above. Do not rely on SKILL_DIRthat is not guaranteed to exist, hard-coded development machine paths, or guessing the install location by directory search.

The precheck is an internal step of this Skill, not a third Skill. When missing, prompt once and install;runtime_unhealthy、runtime_capability_missing or when installation fails, stop, do not overwrite the existing installation, and do not fall back to the old editing chain;stopping means stopping; it is forbidden to continue the process with a self-made review page, player or any substitute interface(output is untrustworthy whenever the product is unavailable). Neither the precheck nor the headless generation stage may open Studio. For the detailed protocol see Runtime and product contract。

After the Runtime precheck succeeds and before the first workflow get , immediately have the Product declaratively ensure the resident service:

node "$RUNNING" --json

Continue only after the script confirms that the service healthy=true、runtimeMode=launchd, the version is compatible, the PID is valid and the URL is the canonical 5190 entry point. On failure, pass through the Product's structured error and stop; falling back to foreground, changing ports or killing unknown processes is forbidden.

1. Product state readback: check the basic material package

node "$VC" workflow get "$jobDir" --json

The following must all exist and pass the product check:

• source_cut.mp4: the real post-cut video, including an audio stream;
• subtitles.srt: canonical subtitles rebuilt based on the post-cut video;
• workflow get.data.artifact.state=current；
• workflow get.data.artifact.editListRevision is exactly the same as the current editListRevision ;
• the same projectId and current project revision.

When only the file path exists but Runtime does not return the above artifact state, fail-closed based on artifact_state_unavailable . Do not assume that source_cut.mp4 corresponds to the current timeline merely because it exists, and do not let an old final cut enter the storyboard chain.

Whichever is missing, go back to that segment,do not vaguely point back to cut voiceover—what is missing differs, so the Skill to run differs:

What is missing	Switch to
source_cut.mp4 does not exist (not yet physically cut)	$chengfeng-videocut:chengfeng-export-talking-head
source_cut.mp4 exists,subtitles.srt does not	$chengfeng-videocut:chengfeng-subtitle-talking-head
there is not even a deletion-word ledger	$chengfeng-videocut:chengfeng-cut-talking-head

In all cases, resume this Skill with the same projectId . Do not add a new business state machine or a second project.

2. Read the project configuration and prepare the proposal

The aspect ratio, animation style and additional requirements must come from the current project state; do not read mutable global defaults shared by all projects. When the user has not yet chosen, ask only for the necessary information that would materially change the final cut.

{
  "aspectRatio": "4:3",
  "animationStyle": "xiaohei",
  "requirements": "保留真实产品操作画面"
}

After the user confirms the configuration, execute start-finalwith the latest revision. Re-read the revision at every step; do not reuse old values consecutively.

3. proposal → Product CAS: storyboard candidate

First read storyboard rules. Segment by subtitle semantics, bind candidate segments to a stable wordIds, then publish through product validation:

node "$VC" artifact put "$jobDir" \
  --type visual-plan \
  --file "$visualPlanProposal" \
  --expected-project-revision "$latestProjectRevision" \
  --expected-artifact-revision "$latestArtifactRevisionOrNone" \
  --json

On first entry into storyboard, and on first entry into the animation / timeline review views described below, the same sequence must be repeated before opening; do not rely on the ensure from the beginning of the flow:

node "$RUNNING" --json
node "$VC" open "$jobDir" --json
node "$STUDIO" --url "$productUrl" --view "$reviewView" --json

3.1 project-level review binding: storyboard review

Only when the corresponding state enters *_review_ready, the capability gate returns ok=true, do you open studio.url. Before opening, you must strictly compare the Product URL's #project/<projectId> with the workflow readback projectId , and bind the current workflow stage, Project / EditList revision, and this stage's artifact revision to the review; a capability gate PASS only proves the product surface exists and cannot replace project-level binding. storyboard uses reviewView=storyboard, animation and timeline use reviewView=preview. After the user saves the review result, first run node "$RUNNING" --jsonagain, then call show_workflow_confirmation. When the card returns action=continue_finish_storyboard or action=return_finish_storyboard , always first execute:

node "$RUNNING" --json

continue_finish_storyboard Re-read the Product and verify the bound revision item by item, then execute confirm-storyboard；return_finish_storyboard Return to the same project's storyboard review page without advancing the state.

4. proposal → Product CAS → project-level review binding: animation candidates and review

First read animation rules; when an HTML module is needed, then read animation module contract。

The motion style is selected from style registry , then read that style's own SKILL.md and references. Currently there is only xiaohei(Xiaohei comic-style SVG motion). Styles not in the registry must not be invented out of thin air; when the user has not specified, explain the available options and let the user choose.

• Animation must be bound to a specific spoken line and cue.
• Real product operations, screenshots, and result pages should preferentially use real assets.
• When there is no animation, submit empty modules and a clear reason; do not create placeholder modules.
• HTML must support restoring to a deterministic state after seeking to any time.

After publishing animation-manifest , wait for animation_review_ready, then enter the preview view through the same capability gate for review. After the user saves, first ensure-running; when the card returns action=continue_finish_animation or action=return_finish_animation , always first execute:

node "$RUNNING" --json

continue_finish_animation Re-read the Product and verify the URL/hash projectId, stage, Project / EditList / artifact revisions, then execute confirm-animation；return_finish_animation Return to the same project's animation review page without advancing the state.

5. proposal → Product CAS → project-level review binding: timeline candidates and review

First read timeline and export. The final timeline only consumes post-cut time, real subtitles, and reviewed modules:

node "$VC" artifact put "$jobDir" \
  --type timeline \
  --file "$timelineProposal" \
  --expected-project-revision "$latestProjectRevision" \
  --expected-artifact-revision "$latestArtifactRevisionOrNone" \
  --json

After the state enters timeline_review_ready , enter the preview view through the same capability gate for review. After the user saves, first ensure-running; when the card returns action=continue_finish_timeline or action=return_finish_timeline , always first execute:

node "$RUNNING" --json

continue_finish_timeline Re-read the Product and verify the URL/hash projectId, stage, Project / EditList / artifact revisions, then execute confirm-timeline；return_finish_timeline Return to the same project's timeline review page without advancing the state.

6. user confirmation → Product execution → outcome verification: product export and acceptance

The final export must be completed by the Runtime itself; the Skill does not carry a renderer, nor does it pass the old Skill script path:

node "$VC" workflow get "$jobDir" --json
node "$VC" render run "$jobDir" \
  --expected-revision "$latestRevision" \
  --confirmed \
  --json

If the current Runtime returns missing_renderer, explicitly report that this is a Runtime version gap and stop. It is forbidden to sneak the old export_final_video.cjs, an independent preview service, or direct FFmpeg export back into the Skill.

Report completion only when all of the following conditions are met:

• renders/final.mp4 exists, and both the video stream and the audio stream can be decoded;
• the resolution matches the project aspect ratio;
• the duration is within tolerance of the timeline;
• keyframes have no black bars, occlusion, incorrect assets, or ghost subtitles;
• renders/verification.json of passed=true。

The report must clearly state the evidence level: a match of Product's stage / revision / verification.json is API/readback PASS; only when the Codex built-in browser opens the same #project/<projectId> and the bound revision to observe the actual picture is it visual frame PASS; when no one has actually compared the listening experience, always write human listening UNVERIFIED. Autoplay, mute, screenshots, DOM, or stream decoding cannot replace human listening.

Confirmation and recovery rules

candidate saved
      |
      v
*_review_ready ----> 打开同一个 Studio ----> 用户保存
      |                                      |
      |                         MCP App 回传 action + revision
      |                                      |
      +<-------- revision mismatch ----------+
      |             停止并核对
      v
confirmed transition

• The card does not directly execute any destructive action.
• studio_capability_missing When , it is forbidden to open any old Studio without a capability manifest, and silent fallback is also forbidden; it may be suggested to $chengfeng-report-videocut-bug generate a sanitized Issue draft.
• service_identity_mismatch or service_port_conflict , stop; foreground startup, changing ports, or killing unknown processes is forbidden.
• return_finish_* must first execute node "$RUNNING" --json, then return to the corresponding review view;pause_workflow after saving, stop.
• revision_conflict must re-read the state; silent overwriting is not allowed.
• "Being able to play a preview" does not equal "the final video has been exported".
• This time, a one-time confirmation receipt is not implemented; confirmation is still bound to explicit actions and Product revisions.