chengfeng-cut

Edit spoken-word

From one video toa manually reviewed word-deletion ledger (Cuts + EDL), without touching media files. Seven steps in one line:

0  就绪     引用「检查更新」的就绪检查（本 Skill 不带环境逻辑）
1  建档     真实视频 → 云端逐词转录 → 产品建项目 → 起服务 → 读回状态
2  修字     词典把字改对（通用一本 + 用户一本）→ 出修字表
3  删词     读偏好与规则 → 五轮扫描，每轮只找一类，只记行
4  汇总     删词汇总表 + 重复句子表 → 按表自读校验
5  审核     全量提交 → 两张表呈给用户 → 打开 Studio 亲自复核
6  复盘交棒  对比提案与终版 → 归档三抽屉 → 报告四件事

Do not cut media: changing the ledger once takes tens of milliseconds; cutting once is an irreversible file. By the end of this Skill, there is no new video on disk. The Skill makes semantic judgments and orchestrates; the Product Runtime is the sole writer of the project, Cuts, and Studio state.

The user speaks at only three points: for a same-source project, choose continue or start over (only when it has been edited before), Studio review, and completion confirmation. Everything else is one-way reporting, without stopping to wait for a reply.The completion criterion for each step is its deliverable: if no table is produced, it is not complete.

First read and execute the business Skill's stage contract. Correspondence between this document's steps and the contract stages: 1=preflight+Product state readback, 5=proposal+Product CAS, review=project-level review binding. The three stages after the contract (confirmation, execution, acceptance) belong to the export Skill.

The incident origins of each rule are in the incident log—the rules are in the main text, the stories are over there.

0. Readiness

First execute the check for updates 's "readiness check"—whether the skills are latest and whether the Runtime is matched;the plugin rootis also located there (the <插件根> in commands in this document is substituted with that literal path). Continue only after obtaining "ready"; for "new session required" or "stop", follow its handling (including the "no self-made alternative interface" prohibition).

If the readiness result is runtime.kind=desktop-managed, it shares the same stable entry point and the launchd/windows-task service with the CLI installation, so continue directly; do not look for an Electron installation directory, separately install Bun / FFmpeg, or start a second Runtime.

1. Create the file: real input → transcription → create the product project

What to do: hand the user's real local video and cloud word-by-word transcript to the product, create the file atomically, start the service, and read back the state.

# 云端逐词转录（生成任务目录内的 transcript 候选）之后：
node "<插件根>/scripts/videocut-cli.cjs" project create "<项目目录>" --video "<任务目录内的视频文件>" --transcript "<任务目录内的逐词稿>" --json

node "<插件根>/scripts/ensure-running.cjs" --json          # 产品声明式确保常驻服务（5190）

node "<插件根>/scripts/videocut-cli.cjs" workflow get "<项目目录>" --json    # Product state readback
node "<插件根>/scripts/videocut-cli.cjs" cuts get "<项目目录>" --json

Rules:

• Only accept the real spoken-word video or existing real project provided by the user; if there is no real media, stop, and do not substitute examples or placeholder videos
• Transcription uses only thecloud ASRalready authorized in the current environment; do not fall back to local ASR; when no cloud ASR is available, report missing_cloud_transcription_adapter, do not open Studio, and do not forge a transcript
• --video / --transcript must be a real file inside the task directory; do not pass the aspect ratio—the product will automatically derive it from the video's actual dimensions (Runtime 0.4.4+). Add it only when the user explicitly requests a special aspect ratio. --aspect-ratio W:H
• For an existing canonical project, first inspect confirm and reuse it; do not repeatedly create projectId; when the same video has been edited before, ask the user: continue from last time, or start over (this is one of the three speaking points).project prepare is an idempotent compiler, used only when recovering from an interruption or explicitly refreshing; if interrupted, just rerun it directly.
• project create is the only entry point: it does not go through the asset library, upload session, or extra Skill; the Skill must not write first project.json
• The service must be confirmed by the script healthy=true、runtimeMode=launchd(macOS) or runtimeMode=windows-task(Windows), version compatibility, and the URL being canonical 5190 before continuing; on failure, pass through the structured error and stop; falling back to foreground, changing ports, or killing unknown processes is forbidden
• The two readbacks must point to the same projectId, saving the workflow stage and the three revisions Project / Cuts / EditList; if missing or inconsistent, stop

2. Text correction: fix the characters and produce a correction table

What it does: before any word-deletion judgmentbefore, use the dictionary to correct characters misheard in transcription—if the characters are wrong, all later judgments will be wrong; a misheard character is not an extra word, and word deletion cannot fix it.

node "<插件根>/scripts/videocut-cli.cjs" transcript dictionary "<项目目录>" --dictionary "<插件根>/references/ai-term-dictionary.md" --json

Use your file tool to check whether $HOME/.chengfeng-videocut/dictionary.md exists; if it exists, run through it again (transitional approach: the CLI currently accepts only a single file, so run it twice; it can only supplement, not undo the previous pass—the full multi-dictionary CLI release such as user-priority merging):

node "<插件根>/scripts/videocut-cli.cjs" transcript dictionary "<项目目录>" --dictionary "$HOME/.chengfeng-videocut/dictionary.md" --json

Output: correction table—merge the applied lists returned by the two calls into one small table (original word → changed to → context), and report it to the user.After changes, this table must be reviewed—the dictionary will also make mistakes when it does not look at context; if something is wrong, change the dictionary, not patch it elsewhere.

Only when the dictionary cannot solve it and the author has a manuscript on hand, add one context alignment pass:

node "<插件根>/scripts/videocut-cli.cjs" transcript align "<项目目录>" --script "<口播稿文件>" --json   # 只报不改
node "<插件根>/scripts/videocut-cli.cjs" transcript correct "<项目目录>" --file "<修正文件>" --json

Rules:

• Change only the text, not the time, word count, or wordId—the product compares timestamps word by word, and changing them causes direct rejection
• Change only the wording, not the meaning—when something was truly said wrong and then repeated, that is a false start and restatement, handled by word deletion
• If the dictionary does not have it and the manuscript cannot confirm it,guessing is forbidden: report it and leave it for a human to add to the dictionary. Inserting a made-up name is worse than leaving a misheard name
• Keep spoken Chinese as in the original: saying “叉” or “大模型” is what he said
• The dictionary isa gate that every transcription must pass through(the same audio transcribed twice gives different results; see the incident log)

Segment the transcript by punctuation: in the transcription, every word carries punctuation; in the transcript, one comma is one segment, and one sentence is one line; subtitles consume the same punctuation, so both sides have consistent sentence breaks. Old projects before 2026-07-28 have no punctuation; just run node "<插件根>/scripts/videocut-cli.cjs" transcript regroup "<项目目录>" --json to re-segment paragraphs (word-by-word verification of id/time/text unchanged, safe for edited projects); if you really need punctuation, retranscribe—punctuation simply does not exist in old transcriptions.

3. Word deletion: five rounds of scanning, each round looking for only one type

What it does: read the materials, then read the playback order completely five times, each pass carrying only one criterion. Reading with one criterion at a time gives far higher judgment quality than carrying six at once; each round produces a small, checkable output.

First read the materials:

node "<插件根>/scripts/videocut-cli.cjs" transcript playback "<项目目录>" --json

Then use your file-reading tool to read $HOME/.chengfeng-videocut/cut-preferences.md(user preference, what he has said counts; if the file does not exist, this is a new user, so skip).

The criteria are in semantic deletion rules(principles + precedents). Teaching material priority:user preference > user precedents > general precedents。

第 1 轮  重复          句间重复、句内重复（最客观：两遍相同）
第 2 轮  残句与改口     说一半断掉、换个说法重说
第 3 轮  口误重说       说错的数字、专名、词，后面重说对的
第 4 轮  英文卡壳       词头 / 字母 / 音节重复
第 5 轮  口头禅与语气词  最主观，按用户偏好的密度与容忍度来

Each round has a fixed action: look up precedents by the current round’s type → when one is found, record one line (wordIds + type + risk) → Do not decide other types. In subsequent rounds, skip words that are already marked, and leave conflicts to be resolved in the summary.

Rules:

• Judge using only the playback order of transcript playback , and do not assemble it yourself from transcript.json assemble— "said twice" depends on being adjacent in playback; assembling it yourself will read skipped numbers as missing content and wrongly reject it (see the incident log)
• Deletion has only two states: "deleted / not deleted"; the AI reason does not form a third state of "suggested deletion"
• For slips of the tongue, repetitions, and incomplete sentences, by default delete the earlier and keep the later; long sentences, whole sentences, and branched restatements must undergo high-risk review
• Ordinary pauses are not calculated by the Skill: adjacent silence merging and natural-pause-v2 are deterministically executed by the product

4. Summary: two tables; only act once the tables are out

What to do: merge the rows from the five rounds into two tables—this is the output of this step and also what is shown to the user.

Deleted words summary table(word-by-word deletion decisions):

| # | 时间   | 类型   | 删除              | 剩下读作          | 风险 | 依据      |
|---|-------|--------|------------------|------------------|-----|----------|
| 1 | 00:12 | 重复   | 这个功能呢         | 这个功能它其实      | 低  | 判例 R2   |
| 2 | 02:31 | 改口   | 比如我就让他跟踪    | 比如我让grok跟踪    | 高  | 判例 R5   |

Repeated sentences table(sentences said multiple times; the word-by-word table cannot show "how many times it was recorded and which pass to keep," and this is exactly what the user most wants to verify):

| 句子（开头）      | 说了几遍 | 保了哪遍        | 删了哪几遍   | 风险            |
|-----------------|--------|---------------|------------|-----------------|
| 因为今天有什么…   | 3      | 第 3 遍 00:08  | 第 1、2 遍  | 低——三遍基本一致  |
| 多数Agent能搜…   | 2      | 第 2 遍 04:40  | 第 1 遍     | 高——两遍说法有出入，重点听 |

Thenself-read: according to the tables, read through the full text after deletion once in playback order, and undo rows that do not read smoothly. This is the definition of review: the AI looks again itself, not asks the user; if unsure = do not list (two states).

5. Review: only open Studio at the manual review stage

What to do: submit all candidates, present the two tables to the user, then open the product review page for the user to review personally.

node "<插件根>/scripts/videocut-cli.cjs" cuts get "<项目目录>" --json              # 取 Cuts 自己的 revision
node "<插件根>/scripts/videocut-cli.cjs" cuts set "<项目目录>" --file "<提案文件>" --expected-revision "<Cuts当前revision>" --json

Candidates reference only stable wordIds：

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

Submission rules:

• Candidates arethe complete conclusion of this round's judgment, not an increment——cuts set is replacement semantics; submitting an increment will silently drop the previous round's semantic deletions (see the incident log); when submitting candidates, it is forbidden to read or manually merge initialization.baselineCutWordIds(the product automatically merges in the pause baseline)
• reasons and write it to disk as is; the product will trim the parts that mention undeleted words
• Do not directly write cut-selection.json、project.json or the event log
• cuts get.data.revision is the revision of Cuts,workflow get.data.revision is the project's, mixing them is forbidden
• After successful submission, you must check noLongerCut(the number of words no longer deleted this time): if it is nonzero and not an intentional retraction = an increment was submitted, go back and supplement the full set and resubmit; if you read "unknown" you must also see
• then immediately again workflow get + cuts get, confirming cut_review_ready and the three revisions; if inconsistent, stop immediately, and never directly write JSON or automatically overwrite
• After submission, leave <提案文件> in the task directory—it is needed for the step 6 retrospective (reasons will be trimmed by the product after user edits, so later reverse-checking from the ledger is unreliable)

Thenpresent the tables first, then open the page: send the two tables to the user so they can take the tables into Studio for review.

node "<插件根>/scripts/ensure-running.cjs" --json                    # 打开前再次幂等 ensure
node "<插件根>/scripts/videocut-cli.cjs" open "<项目目录>" --json          # 取产品返回的项目 URL

node "<插件根>/scripts/ensure-studio.cjs" --url "<产品项目URL>" --view koubo --json                                  # 能力门禁：确认 5190 注册了 koubo 视图

Rules:

• Only when the gate returns ok=true may you use Codex's built-in browser to open studio.url, then stop automatic progression and wait for the user to select words, restore, and save
• Before opening, strictly compare productUrl 's #project/<projectId> with the readback's projectId , and bind stage=cut_review_ready with the three revisions—the gate ok=true only proves product-side capability, and cannot replace project-level binding; any inconsistency requires a readback again
• studio_capability_missing: stop and explain the version incompatibility, may suggest $chengfeng-report-bug; forbidden to assume the new interface exists just because the URL contains ?view=koubo and forbidden to fall back to the old task panel
• do not treat "open the workbench" as the first step of the task; do not access the old review.html, 8898/8899; do not control the Studio DOM, do not directly modify media elements; do not create independent audio tracks or placeholder subtitle tracks

6. Retrospective handoff: do not discard assignments corrected by the user

After the user completes review, first read back:

node "<插件根>/scripts/videocut-cli.cjs" workflow get "<项目目录>" --json
node "<插件根>/scripts/videocut-cli.cjs" cuts get "<项目目录>" --json

Retrospective(transitional approach, to be replaced after the product's cuts diff command is released): take the <提案文件> retained in step 5 and compare it with the read-back final version cutWordIds ——

• restored by the user(present in the proposal, absent in the final version) = the AI deleted it incorrectly. Compare against the reason you wrote in the proposal and ask: which category of error is it?
• additionally deleted by the user(present in the final version, absent in the proposal, and also not in initialization.baselineCutWordIds pause baseline) = the AI missed it. Ask: which type does this belong to, and why was it not identified? (the baseline is used here only to remove pause words, and merging it into the submission is still forbidden)

Archive into three drawers:

• taste differences → ~/.chengfeng-videocut/cut-preferences.md append (Agent-maintained markdown, only append to and rewrite its own section; create the file if it does not exist)
• proper noun errors → ~/.chengfeng-videocut/dictionary.md append (two-column table, check for duplicates before appending)
• rule gaps → record an entry in the "cases pending upgrade" section of the preferences file; when the same type appears for the third time, report to the user, and suggest upgrading it into general cases (only modify the skills repository after human review)
• even zero differences must be recorded: add one line "fully adopted" to the project record in the preferences file

Report four things: how many words were deleted, how many seconds were reduced; current stage (should be cut_review_ready); the three revisions of project / Cuts / EDL; retrospective summary (N proposal items, X adopted, Y restored, Z additionally deleted, one sentence on the main disagreement). Then tell the user to run export next.

Do not pop up a confirmation card, do not perform cutting——the confirmation card for physical cutting belongs to the export Skill, and that card must freeze the revision at the moment the user presses confirm.

return_cut_review: first node "<插件根>/scripts/ensure-running.cjs" --jsonagain, then return to the same Studio to continue review; do not trigger a retrospective, the retrospective is done only once at the final handoff.

Report grading: Product structured revision is API/readback PASS; only real browser frame review is visual frame PASS; if no one has actually listened to the audio, it is always human listening UNVERIFIED, and playback, DOM, screenshots, or media probing must not be used as substitutes.

Recovery and failure

• revision_conflict: reread the state, explain the user's just-now edit, do not automatically overwrite
• runtime_unhealthy: do not repeatedly reinstall
• service_identity_mismatch / service_port_conflict: stop, do not fall back to foreground, do not change ports, do not kill unknown processes
• Page closed but service still running: after reading the workflow, continue from the current state, do not create a new project
• No failure may describe "the ledger has been written" as "already cut"——up to this point no media file has been produced

Note: this Skill acceptslocal real videoandcloud word-by-word transcriptGo directly to the product; this is a requirement of contract preflight; both genuinely existing is the prerequisite for all judgment.