chengfeng-subtitle

name	chengfeng-subtitle
description	给剪好的口播做字幕：直接用已有的逐词稿加账本算出剪后时间（不必导出、不必重新转录）、用词典和作者文稿改写听错的专名、按句子分屏、在 Studio 里逐屏复核。用户说做字幕、加字幕、改字幕、重新分屏、字幕不对时使用。不要用于删词剪辑、物理剪切、分镜动画或成片渲染。
user-invocable	true

字幕

这是一件事，不是流程的一段。 用户什么时候喊它就什么时候做——刚剪完可以做， 做完又删了两句可以再做一遍。

它只有一个前提：账本已经存在。不是因为它排在剪辑后面，而是因为没有账本， 它不知道哪几句留着、各自落在成片的第几秒。

需要   edit-list.json（账本）、transcript.json（逐词稿）
产出   subtitles.json

干完就停，不指挥用户下一步。

先读取并执行 业务 Skill 的阶段合同， 判据见 字幕校对规则，专名写法见 AI 用词词典。

谁说了算什么

这是这一段的地基，其余都从这里推出来。

剪口播   说了算「留哪些话、在什么时候」    ← 时间的唯一真相
字幕     说了算「屏幕上显示什么字」        ← 显示的唯一真相

一屏字幕存的是词 id 列表 + 显示文字，不存秒数。时间每次从账本现算。 于是两本账没有第二份时间可以走偏，失效也能精确到屏：「第 7、第 12 屏的词被剪掉了」， 而不是那句谁也点不动的「字幕可能已过期」。

字幕存自己的文字是故意的。 转录回答「他说了什么」，字幕回答「给人看什么」—— 标点、去掉的口头禅、专名的正式写法，这些本来就该不一样。逼一份字符串同时干两件事， 字幕就永远加不了逗号。

0. 就绪

先执行 检查更新 的「就绪检查」——skills 是否 最新、Runtime 是否配套；插件根也在那里定位（本文命令里的 <插件根> 都代入 那个字面路径）。只有「就绪」才继续；「需新会话」或「停」按它的处置执行 （含「禁止自制替代界面」禁令），业务 Skill 不自带环境逻辑。

若就绪结果为 runtime.kind=desktop-managed，直接复用桌面 App 已安装的稳定 CLI 与 同一 launchd/windows-task 服务；不要解析 Electron 路径、另装依赖或起第二个 Runtime。

1. 入口断言

node "<插件根>/scripts/ensure-running.cjs" --json
node "<插件根>/scripts/videocut-cli.cjs" inspect "<项目目录>" --json

断言	不成立时
edit-list.json 存在且有片段	说清楚缺账本，让用户先喊剪口播。不要自己去剪。
transcript.json 存在	项目没准备好，停止。不要自己造一份。

不要断言 source_cut.mp4，也不要去转录。 字幕两样都不需要——见下一节。

2. 改字：先词典，后文稿

不需要重新转录。 原来那份逐词稿已经带着时间戳，账本知道哪几段留着—— 每个词落在成片的第几秒是算出来的，不是再听一遍听出来的：

词在源片的第几秒   转录里就有
哪几段留着         账本里就有
词在成片的第几秒   两者一算就出来

再送一遍 ASR 只是把同样的话重新听一次，花钱、花时间，而且听得更差——专名要重新改一遍。 （transcript retranscribe 是上一版设计的遗留，那时字幕打算靠转写剪后视频拿时间轴。 字幕改成锚词 id 之后这个问题就没了。做字幕不要用它。）

两件不同的工具，都要用。

# 词典：这个说话人的固定写法，不需要证据
node "<插件根>/scripts/videocut-cli.cjs" transcript dictionary "<项目目录>" --dictionary "<插件根>/references/ai-term-dictionary.md" --json

# 文稿：作者手上有稿子时才做，逐处要证据
node "<插件根>/scripts/videocut-cli.cjs" transcript align "<项目目录>" --script "<口播稿文件>" --json

词典    永远这么写            不看上下文，直接改，列出改了哪几处
文稿    上下文对得上才这么写   逐处要证据，对不上的报「不敢定」，不猜

为什么必须有词典，光靠文稿不行：口播会重录。真实项目里同一句录了四遍， 于是「连接叉」「叉是」这些上下文全都出现不止一次，align 只能报「不敢定」—— 它按规矩不猜，因为名字写错比听错更糟。三处「叉」它只敢改一处。 词典没有这个问题：在这个说话人的作品里，「叉」就是「X」。

词典只有一份，在插件级 references/ai-term-dictionary.md：它改的是转录， 而剪口播和字幕吃同一份转录。不要在这个 skill 下面再建一份。

改完要看那份清单。 词典不看上下文，所以它也会改错——比如把说话人真的说的 「Skills」（Claude Skills，复数专名）normalize 成「Skill」。看到不对就改词典， 不要在命令这边打补丁。

transcript align 只报不改。要应用它的提案，把 corrections 转成 [{wordId, text}] 再跑：

node "<插件根>/scripts/videocut-cli.cjs" transcript correct "<项目目录>" --file "<修正文件>" --json

改完转录，引用了这些词的字幕屏会在同一步里跟着改写，回报 subtitles.updated。 改不动的（那一行被人重写过）进 needsAttention，报出来让人看，不猜。

词典里没有、文稿里也没有任何一个写法能确认正确时，不许猜。 报出来让用户补词典—— 补进词典下一条视频就自动对了，猜对一次下次还要再猜。

3. 分屏

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

四条规则，按顺序：

① 这里删掉过话    删掉的两边在时间轴上挨着，意思上毫无关系。
                 删掉的是「静音」不算 —— 把句子中间的停顿剪掉，不能把句子劈开。
② 任何标点        火山给的，句号和逗号都算 —— **和剪口播分段是同一个粒度**，
                 两边断在同一处。标点比任何时间证据都强：说话人可以两句连着
                 说不喘气，也可以在一句中间停顿。
③ 段落边界 + 停顿  **只在这个词没有标点时才用**。它是「没标点时靠段落猜句子结束了」，
                 有标点就该由②和逗号那条管 —— 它们会考虑屏够不够长，③ 不会。
                 （在带标点的边界上也触发③，真实项目从 40 屏变 43 屏，切出更多碎屏）
④ 观众听到长停顿   句子内部要断，得有更长的静音才够格。

剪口播和字幕吃同一份标点，粒度也一样：一个逗号一段 / 一屏。

碎片（一两个字）会被并掉，但不跨句号并 —— 「你看」开启新的一句， 不是上一句的尾巴，往前并会得到「…调用Grok CLI你看」，两句糊在一起。

说话人说得快的短句会留下来（真实项目上「每天早上」「执行任务」各 0.6 秒）。 那是他真的这么说的，不报警。 一个逗号一屏必然产生这种屏， 为它报警等于对正常说话报警——报多了就没人看警告了。

剩下比一屏长的，均摊拆成几屏，一屏一行。切出一两个字的碎片，说明②那个边界 其实不是句号，把碎片并回上一屏。

命令回报四件事，都要看：

stale              被剪辑改动的屏 —— 精确到第几屏、丢了哪几个字
tooFast            字太多、时间不够读
transcriptMoved    转录已经不是当初那一份了

已经有字幕时 —— 这里要停下来问

不加 --replace 它会直接拒绝。这是这个 skill 里唯一要征求用户同意的地方， 因为 --replace 冲掉的是人花时间做的分屏和措辞，产品自己恢复不了。

用户想改几个字     不要 build。让他在 Studio 里直接改，或者告诉你改哪几屏。
用户要推倒重来     确认过了再加 --replace。

4. 复核：在 Studio 里逐屏看

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

打开后切到左栏的**「字幕」标签页**。一行一屏：左边序号和时间，右边就是字，点进去直接改。

• 回车 = 从光标处另起一屏
• 行首退格 = 并入上一屏
• 右栏「参数 → 字幕」四个预设选一个，全片一个样式
• 画面上能直接看到字幕，位置和字号跟画面成比例——预览和成片是同一套数

复核时至少让用户确认：专名对不对、有没有吞字、断句读起来顺不顺、一屏停留够不够读完。

5. 到 subtitles.json 为止

这一段做完了。 不做物理剪切、不做分镜、不做动画、不渲染成片，也不催用户下一步。

报告必须分开写：Product 结构化 readback 为 API/readback PASS；真实同项目浏览器帧 审核才是 visual frame PASS；没有人实际看过字幕跟画面对不对时一律为 human listening UNVERIFIED，不得用 DOM、截图或文件探测替代。

边界：烧进画面不是这一段的事

产出方式定的是烧进画面，而画面是导出那一段画的。字幕的产出就是 subtitles.json —— 里面的尺寸全是画面的百分比，导出按输出分辨率换算成像素即可，两边同一套数。

今天导出的 mp4 里没有字幕，那一步还没做。报告里要写清楚这个后果， 不要说「字幕做好了」就完事——用户会以为成片里有。

恢复与失败

• subtitles_exist：已经有字幕了。先问，别直接 --replace。
• revision_conflict：另一处也在写。重新读取，不自动覆盖。
• 词典报「第 N 行读不懂」：那是一行格式坏掉的表格行。规则只认表格行（| 正确写法 | 常见误识别 |）， 散文和列表都会被安静忽略。
• transcript correct 报「must not change any word id, time or gap flag」： 改字的提案里混进了改时间的东西。改字就只改字。
• runtime_unhealthy：不要循环重装。
• 任何失败都不得把「转写完成」说成「字幕做好了」。ASR 出来的是原料，不是产物。