--- name: chengfeng-export description: 把剪好的口播烧成一个成片文件：账本切片段、推近、字幕、HTML 画面层，一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。 user-invocable: true ---

# 导出（成片）

**这是链条最后一段，也是整个产品里唯一一个真正画出像素的地方。**

在它之前全部是标注：账本记「播哪些词」，字幕记「屏上写什么」，画面记「盖什么层」， 预览把这三样实时拼给人看，**不落盘**。导出把它们烧成一个文件。

```text 需要 edit-list.json（必须）、subtitles.json、visuals.json + modules/ 产出 成片.mp4 ```

前提工具：机器上有 **Google Chrome**（用来把字幕和动画画成图）。桌面安装来源的 FFmpeg / FFprobe 已随 App 进入 Product 受管目录；纯 CLI 安装仍要求系统 `ffmpeg ≥ 6`。缺 Chrome 会明确报错，不要试图绕过——没有它就没有字幕层和动画层。

先读取并执行 [业务 Skill 的阶段合同](../../references/business-workflow-contract.md) 里的「结论等级」一节。**导出不进剪辑状态机**：它不改任何项目文件、不做 CAS 写入、 不推进 stage，产出是一个新文件，重跑一次就覆盖。所以它不需要确认卡。

## 0. 就绪

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

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

## 命令

```bash node "<插件根>/scripts/ensure-running.cjs" --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --dry-run --json # 先看计划，不编码 node "<插件根>/scripts/videocut-cli.cjs" export <project> --json # 出成片（默认 2 倍、源帧率） node "<插件根>/scripts/videocut-cli.cjs" export <project> --out /path/成片.mp4 --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --scale 1 --json # 只要源尺寸 node "<插件根>/scripts/videocut-cli.cjs" export <project> --keep-work --json # 留下中间片和逐帧 PNG，供排查 ```

`ensure-running` 身份不匹配、端口冲突或服务不健康时立即停止；不允许用 foreground 临时顶替后继续导出。

## 两步，别只跑第二步

```text ① --dry-run 先报计划 片长、帧数、字幕屏数、画面层数、推近段数、输出尺寸 念给用户听。数字不对就是上游不对，编码十分钟不会修好它 ② 真跑 assemble → overlay → compose → verify 四段进度 ```

`--dry-run` 里的 `warnings` 必须原样转述。它只报一类事：**某些字幕屏或画面层的词 已经被剪掉了**，所以它们不会出现在成片里。这是上游要决定的事，不是导出该替人吞掉的。

## 清晰度：源片是天花板，先看源再谈放大

导出前看一眼源分辨率（`--dry-run` 的 `source` 字段就有）：

```text 源宽 ≥2560（Retina 原生录屏） → --scale 1，输出就是原生像素，这是最好的情况 源宽 <1920（如 960×720） → 先停一下：问用户有没有同一次录制的高清导出。 录屏工具常常能把同一次录制重新导出成 3 倍分辨率， 换源比任何后期都管用（见下节）。确实没有 → --scale 2 ```

`--scale 2` 对低清源有用的原因：底片放大不会变清楚，但**字幕和动画是按输出尺寸 重画的**——观众真正在读的就是这两样；平台再压一次时，大图分到的码率也更高。

**不要为了「更清晰」去调 `--fps`。** 帧率跟着源片走；改它只会让动画的采样和录屏对不上。

## 换源：用户拿出同一次录制的高清版时

这不是导出流程的一部分——导出本身永远只读。换源是用户明确点头后的独立素材操作， 做完再回来正常导出。

**先判定是不是同一条**（前两条就足够硬）：

```bash ffprobe -v error -show_entries format=duration -of csv=p=0 <两个文件> # 时长精确到毫秒相同 ffmpeg -v error -i <文件> -map 0:a:0 -c copy -f md5 - # 音频流逐位相同 # 再抽两三帧对比画面内容，眼睛确认 ```

**音频逐位相同 = 时间线相同**：逐词稿、账本、字幕、画面层全绑词 id，一个不用动。 这正是「绑词不绑秒」在换源这件事上的兑现。

**换源四步**（2026-07-29 真实走过一次；第 ③ 步当时漏了，剪辑预览当场报 「生成失败」——指纹记录不止一处，grep 旧指纹找全再动手）：

```text ① 换文件 input/source.mp4 和 uploads/source.mp4 是硬链接对 —— 删两个，拷新文件到 input/，再建硬链接回 uploads/ （macOS 用 ln；Windows 用 New-Item -ItemType HardLink） ② 更新指纹 project.json 的 source.sha256 改成新文件的 ③ 再查一处 workbench.json 的 sourceSha256 也记着源片指纹， 剪辑预览管道校验的恰恰是这本 —— 漏了它，预览拒绝生成 （这是产品的正确行为：指纹对不上宁可失败，不拿旧预览冒充） ④ 重导 --scale 1 —— 换源就是为了原生像素，别再放大 ```

保险做法：用你的搜索工具在 <项目目录> 的全部 *.json 里找旧指纹前 8 位， 列出来的每一处都要处理（缓存记录如 preview-edited/current.json 会自动重算，不用手动改）。

音频不同（重新录了一遍、剪过、时长不一样）就**不是换源**，是新项目： 逐词稿要重新转，所有标注作废。别硬套。

## 验收：三件事，缺一件就不算导出完成

```text ① 命令成功返回 产品自己数成片的尺寸、帧数、音轨，和计划逐项比。 对不上就是 readback_mismatch 报错，文件留在盘上当证据， 不算导出完成 ② 抽帧看像素 从成片里抽帧，用眼睛看。至少覆盖：一个推近段、 一个整屏动画段、一个只有字幕的段、一个层与层的边界 ③ 人耳听感 没人真的听过，一律记 human listening UNVERIFIED ```

② 不许用预览截图代替。**预览和成片是两条渲染路径，验收要看的正是它们对不对得上**—— 拿预览的图当成片的证据，等于把要验的那件事当成了前提。

**判推近要找判别性地标，整体印象会骗人**（2026-07-29 真踩过）：1.6 倍推近后的 屏幕页面看起来仍像"一整页"，缩略图上和全景几乎没差别——曾把正确的推近帧误判成 "推近丢了"，白追半小时、重导两次。正确判法是找**只有裁剪才能造成的证据**： 被裁掉一半的元素（气泡从中间断开）、消失的边缘元素（侧栏、标题栏）。 和源片同刻帧对比一眼定案。

抽帧就用 ffmpeg：

```bash ffmpeg -v error -ss 8.84 -i 成片.mp4 -frames:v 1 -y frame.png ```

## 出问题往哪查

`--keep-work` 会在项目的 `.chengfeng-videocut/export/` 下留三样东西， 它们把「哪一半错了」直接分开：

```text assembled.mkv 只有剪辑，没有任何盖的东西。它错 = 账本或切片错 overlay/*.png 只有盖的东西，透明底。它错 = 字幕样式或模块错 spans/*.mp4 合成后的分段。它错 = 推近或对齐错 ```

对照表：

```text 成片没有字幕/动画 overlay PNG 是不是全透明？模块是不是没答应 seek？ 动画停在第一帧 模块没实现 seek，或者 GSAP 时间线没 paused 画面整块白 模块少了 `:root { color-scheme: dark }` 推近的框歪了 模块的 viewBox 和层的 zoom 不是同一组数 成片比计划短 某个 span 帧数不够，看 compose 阶段的报错 层边界闪一小段原片 overlay 截图陈旧（帧标记验证失效）。产品靠页面顶部的 帧标记条自证每张截图属于哪一帧；若复发，先确认 overlay PNG 顶部有标记条、compose 有裁掉它的 crop 找不到 Chrome 装 Google Chrome，别改成别的渲染路径 ```

## 不许做什么

- 不许把「导出成功」说成「验收通过」——命令返回成功只是产品自己对得上，不是画面对 - 不许用预览截图、DOM、日志代替成片抽帧 - 不许没人听过就报 human listening PASS - 不许为了让导出跑通去改项目文件（改字幕、删层、动账本）。导出只读，不写 - 不许在导出里补做上游的活：缺字幕就去写字幕，缺画面就去做画面，别在这一段临时糊一个

--- name: chengfeng-export description: 把剪好的口播烧成一个成片文件：账本切片段、推近、字幕、HTML 画面层，一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。 user-invocable: true ---

# 导出（成片）

**这是链条最后一段，也是整个产品里唯一一个真正画出像素的地方。**

在它之前全部是标注：账本记「播哪些词」，字幕记「屏上写什么」，画面记「盖什么层」， 预览把这三样实时拼给人看，**不落盘**。导出把它们烧成一个文件。

```text 需要 edit-list.json（必须）、subtitles.json、visuals.json + modules/ 产出 成片.mp4 ```

前提工具：机器上有 **Google Chrome**（用来把字幕和动画画成图）。桌面安装来源的 FFmpeg / FFprobe 已随 App 进入 Product 受管目录；纯 CLI 安装仍要求系统 `ffmpeg ≥ 6`。缺 Chrome 会明确报错，不要试图绕过——没有它就没有字幕层和动画层。

先读取并执行 [业务 Skill 的阶段合同](../../references/business-workflow-contract.md) 里的「结论等级」一节。**导出不进剪辑状态机**：它不改任何项目文件、不做 CAS 写入、 不推进 stage，产出是一个新文件，重跑一次就覆盖。所以它不需要确认卡。

## 0. 就绪

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

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

## 命令

```bash node "<插件根>/scripts/ensure-running.cjs" --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --dry-run --json # 先看计划，不编码 node "<插件根>/scripts/videocut-cli.cjs" export <project> --json # 出成片（默认 2 倍、源帧率） node "<插件根>/scripts/videocut-cli.cjs" export <project> --out /path/成片.mp4 --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --scale 1 --json # 只要源尺寸 node "<插件根>/scripts/videocut-cli.cjs" export <project> --keep-work --json # 留下中间片和逐帧 PNG，供排查 ```

`ensure-running` 身份不匹配、端口冲突或服务不健康时立即停止；不允许用 foreground 临时顶替后继续导出。

## 两步，别只跑第二步

```text ① --dry-run 先报计划 片长、帧数、字幕屏数、画面层数、推近段数、输出尺寸 念给用户听。数字不对就是上游不对，编码十分钟不会修好它 ② 真跑 assemble → overlay → compose → verify 四段进度 ```

`--dry-run` 里的 `warnings` 必须原样转述。它只报一类事：**某些字幕屏或画面层的词 已经被剪掉了**，所以它们不会出现在成片里。这是上游要决定的事，不是导出该替人吞掉的。

## 清晰度：源片是天花板，先看源再谈放大

导出前看一眼源分辨率（`--dry-run` 的 `source` 字段就有）：

```text 源宽 ≥2560（Retina 原生录屏） → --scale 1，输出就是原生像素，这是最好的情况 源宽 <1920（如 960×720） → 先停一下：问用户有没有同一次录制的高清导出。 录屏工具常常能把同一次录制重新导出成 3 倍分辨率， 换源比任何后期都管用（见下节）。确实没有 → --scale 2 ```

`--scale 2` 对低清源有用的原因：底片放大不会变清楚，但**字幕和动画是按输出尺寸 重画的**——观众真正在读的就是这两样；平台再压一次时，大图分到的码率也更高。

**不要为了「更清晰」去调 `--fps`。** 帧率跟着源片走；改它只会让动画的采样和录屏对不上。

## 换源：用户拿出同一次录制的高清版时

这不是导出流程的一部分——导出本身永远只读。换源是用户明确点头后的独立素材操作， 做完再回来正常导出。

**先判定是不是同一条**（前两条就足够硬）：

```bash ffprobe -v error -show_entries format=duration -of csv=p=0 <两个文件> # 时长精确到毫秒相同 ffmpeg -v error -i <文件> -map 0:a:0 -c copy -f md5 - # 音频流逐位相同 # 再抽两三帧对比画面内容，眼睛确认 ```

**音频逐位相同 = 时间线相同**：逐词稿、账本、字幕、画面层全绑词 id，一个不用动。 这正是「绑词不绑秒」在换源这件事上的兑现。

**换源四步**（2026-07-29 真实走过一次；第 ③ 步当时漏了，剪辑预览当场报 「生成失败」——指纹记录不止一处，grep 旧指纹找全再动手）：

```text ① 换文件 input/source.mp4 和 uploads/source.mp4 是硬链接对 —— 删两个，拷新文件到 input/，再建硬链接回 uploads/ （macOS 用 ln；Windows 用 New-Item -ItemType HardLink） ② 更新指纹 project.json 的 source.sha256 改成新文件的 ③ 再查一处 workbench.json 的 sourceSha256 也记着源片指纹， 剪辑预览管道校验的恰恰是这本 —— 漏了它，预览拒绝生成 （这是产品的正确行为：指纹对不上宁可失败，不拿旧预览冒充） ④ 重导 --scale 1 —— 换源就是为了原生像素，别再放大 ```

保险做法：用你的搜索工具在 <项目目录> 的全部 *.json 里找旧指纹前 8 位， 列出来的每一处都要处理（缓存记录如 preview-edited/current.json 会自动重算，不用手动改）。

音频不同（重新录了一遍、剪过、时长不一样）就**不是换源**，是新项目： 逐词稿要重新转，所有标注作废。别硬套。

## 验收：三件事，缺一件就不算导出完成

```text ① 命令成功返回 产品自己数成片的尺寸、帧数、音轨，和计划逐项比。 对不上就是 readback_mismatch 报错，文件留在盘上当证据， 不算导出完成 ② 抽帧看像素 从成片里抽帧，用眼睛看。至少覆盖：一个推近段、 一个整屏动画段、一个只有字幕的段、一个层与层的边界 ③ 人耳听感 没人真的听过，一律记 human listening UNVERIFIED ```

② 不许用预览截图代替。**预览和成片是两条渲染路径，验收要看的正是它们对不对得上**—— 拿预览的图当成片的证据，等于把要验的那件事当成了前提。

**判推近要找判别性地标，整体印象会骗人**（2026-07-29 真踩过）：1.6 倍推近后的 屏幕页面看起来仍像"一整页"，缩略图上和全景几乎没差别——曾把正确的推近帧误判成 "推近丢了"，白追半小时、重导两次。正确判法是找**只有裁剪才能造成的证据**： 被裁掉一半的元素（气泡从中间断开）、消失的边缘元素（侧栏、标题栏）。 和源片同刻帧对比一眼定案。

抽帧就用 ffmpeg：

```bash ffmpeg -v error -ss 8.84 -i 成片.mp4 -frames:v 1 -y frame.png ```

## 出问题往哪查

`--keep-work` 会在项目的 `.chengfeng-videocut/export/` 下留三样东西， 它们把「哪一半错了」直接分开：

```text assembled.mkv 只有剪辑，没有任何盖的东西。它错 = 账本或切片错 overlay/*.png 只有盖的东西，透明底。它错 = 字幕样式或模块错 spans/*.mp4 合成后的分段。它错 = 推近或对齐错 ```

对照表：

```text 成片没有字幕/动画 overlay PNG 是不是全透明？模块是不是没答应 seek？ 动画停在第一帧 模块没实现 seek，或者 GSAP 时间线没 paused 画面整块白 模块少了 `:root { color-scheme: dark }` 推近的框歪了 模块的 viewBox 和层的 zoom 不是同一组数 成片比计划短 某个 span 帧数不够，看 compose 阶段的报错 层边界闪一小段原片 overlay 截图陈旧（帧标记验证失效）。产品靠页面顶部的 帧标记条自证每张截图属于哪一帧；若复发，先确认 overlay PNG 顶部有标记条、compose 有裁掉它的 crop 找不到 Chrome 装 Google Chrome，别改成别的渲染路径 ```

## 不许做什么

- 不许把「导出成功」说成「验收通过」——命令返回成功只是产品自己对得上，不是画面对 - 不许用预览截图、DOM、日志代替成片抽帧 - 不许没人听过就报 human listening PASS - 不许为了让导出跑通去改项目文件（改字幕、删层、动账本）。导出只读，不写 - 不许在导出里补做上游的活：缺字幕就去写字幕，缺画面就去做画面，别在这一段临时糊一个

--- name: chengfeng-export description: 把剪好的口播烧成一个成片文件：账本切片段、推近、字幕、HTML 画面层，一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。 user-invocable: true ---

# 导出（成片）

**这是链条最后一段，也是整个产品里唯一一个真正画出像素的地方。**

在它之前全部是标注：账本记「播哪些词」，字幕记「屏上写什么」，画面记「盖什么层」， 预览把这三样实时拼给人看，**不落盘**。导出把它们烧成一个文件。

```text 需要 edit-list.json（必须）、subtitles.json、visuals.json + modules/ 产出 成片.mp4 ```

前提工具：机器上有 **Google Chrome**（用来把字幕和动画画成图）。桌面安装来源的 FFmpeg / FFprobe 已随 App 进入 Product 受管目录；纯 CLI 安装仍要求系统 `ffmpeg ≥ 6`。缺 Chrome 会明确报错，不要试图绕过——没有它就没有字幕层和动画层。

先读取并执行 [业务 Skill 的阶段合同](../../references/business-workflow-contract.md) 里的「结论等级」一节。**导出不进剪辑状态机**：它不改任何项目文件、不做 CAS 写入、 不推进 stage，产出是一个新文件，重跑一次就覆盖。所以它不需要确认卡。

## 0. 就绪

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

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

## 命令

```bash node "<插件根>/scripts/ensure-running.cjs" --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --dry-run --json # 先看计划，不编码 node "<插件根>/scripts/videocut-cli.cjs" export <project> --json # 出成片（默认 2 倍、源帧率） node "<插件根>/scripts/videocut-cli.cjs" export <project> --out /path/成片.mp4 --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --scale 1 --json # 只要源尺寸 node "<插件根>/scripts/videocut-cli.cjs" export <project> --keep-work --json # 留下中间片和逐帧 PNG，供排查 ```

`ensure-running` 身份不匹配、端口冲突或服务不健康时立即停止；不允许用 foreground 临时顶替后继续导出。

## 两步，别只跑第二步

```text ① --dry-run 先报计划 片长、帧数、字幕屏数、画面层数、推近段数、输出尺寸 念给用户听。数字不对就是上游不对，编码十分钟不会修好它 ② 真跑 assemble → overlay → compose → verify 四段进度 ```

`--dry-run` 里的 `warnings` 必须原样转述。它只报一类事：**某些字幕屏或画面层的词 已经被剪掉了**，所以它们不会出现在成片里。这是上游要决定的事，不是导出该替人吞掉的。

## 清晰度：源片是天花板，先看源再谈放大

导出前看一眼源分辨率（`--dry-run` 的 `source` 字段就有）：

```text 源宽 ≥2560（Retina 原生录屏） → --scale 1，输出就是原生像素，这是最好的情况 源宽 <1920（如 960×720） → 先停一下：问用户有没有同一次录制的高清导出。 录屏工具常常能把同一次录制重新导出成 3 倍分辨率， 换源比任何后期都管用（见下节）。确实没有 → --scale 2 ```

`--scale 2` 对低清源有用的原因：底片放大不会变清楚，但**字幕和动画是按输出尺寸 重画的**——观众真正在读的就是这两样；平台再压一次时，大图分到的码率也更高。

**不要为了「更清晰」去调 `--fps`。** 帧率跟着源片走；改它只会让动画的采样和录屏对不上。

## 换源：用户拿出同一次录制的高清版时

这不是导出流程的一部分——导出本身永远只读。换源是用户明确点头后的独立素材操作， 做完再回来正常导出。

**先判定是不是同一条**（前两条就足够硬）：

```bash ffprobe -v error -show_entries format=duration -of csv=p=0 <两个文件> # 时长精确到毫秒相同 ffmpeg -v error -i <文件> -map 0:a:0 -c copy -f md5 - # 音频流逐位相同 # 再抽两三帧对比画面内容，眼睛确认 ```

**音频逐位相同 = 时间线相同**：逐词稿、账本、字幕、画面层全绑词 id，一个不用动。 这正是「绑词不绑秒」在换源这件事上的兑现。

**换源四步**（2026-07-29 真实走过一次；第 ③ 步当时漏了，剪辑预览当场报 「生成失败」——指纹记录不止一处，grep 旧指纹找全再动手）：

```text ① 换文件 input/source.mp4 和 uploads/source.mp4 是硬链接对 —— 删两个，拷新文件到 input/，再建硬链接回 uploads/ （macOS 用 ln；Windows 用 New-Item -ItemType HardLink） ② 更新指纹 project.json 的 source.sha256 改成新文件的 ③ 再查一处 workbench.json 的 sourceSha256 也记着源片指纹， 剪辑预览管道校验的恰恰是这本 —— 漏了它，预览拒绝生成 （这是产品的正确行为：指纹对不上宁可失败，不拿旧预览冒充） ④ 重导 --scale 1 —— 换源就是为了原生像素，别再放大 ```

保险做法：用你的搜索工具在 <项目目录> 的全部 *.json 里找旧指纹前 8 位， 列出来的每一处都要处理（缓存记录如 preview-edited/current.json 会自动重算，不用手动改）。

音频不同（重新录了一遍、剪过、时长不一样）就**不是换源**，是新项目： 逐词稿要重新转，所有标注作废。别硬套。

## 验收：三件事，缺一件就不算导出完成

```text ① 命令成功返回 产品自己数成片的尺寸、帧数、音轨，和计划逐项比。 对不上就是 readback_mismatch 报错，文件留在盘上当证据， 不算导出完成 ② 抽帧看像素 从成片里抽帧，用眼睛看。至少覆盖：一个推近段、 一个整屏动画段、一个只有字幕的段、一个层与层的边界 ③ 人耳听感 没人真的听过，一律记 human listening UNVERIFIED ```

② 不许用预览截图代替。**预览和成片是两条渲染路径，验收要看的正是它们对不对得上**—— 拿预览的图当成片的证据，等于把要验的那件事当成了前提。

**判推近要找判别性地标，整体印象会骗人**（2026-07-29 真踩过）：1.6 倍推近后的 屏幕页面看起来仍像"一整页"，缩略图上和全景几乎没差别——曾把正确的推近帧误判成 "推近丢了"，白追半小时、重导两次。正确判法是找**只有裁剪才能造成的证据**： 被裁掉一半的元素（气泡从中间断开）、消失的边缘元素（侧栏、标题栏）。 和源片同刻帧对比一眼定案。

抽帧就用 ffmpeg：

```bash ffmpeg -v error -ss 8.84 -i 成片.mp4 -frames:v 1 -y frame.png ```

## 出问题往哪查

`--keep-work` 会在项目的 `.chengfeng-videocut/export/` 下留三样东西， 它们把「哪一半错了」直接分开：

```text assembled.mkv 只有剪辑，没有任何盖的东西。它错 = 账本或切片错 overlay/*.png 只有盖的东西，透明底。它错 = 字幕样式或模块错 spans/*.mp4 合成后的分段。它错 = 推近或对齐错 ```

对照表：

```text 成片没有字幕/动画 overlay PNG 是不是全透明？模块是不是没答应 seek？ 动画停在第一帧 模块没实现 seek，或者 GSAP 时间线没 paused 画面整块白 模块少了 `:root { color-scheme: dark }` 推近的框歪了 模块的 viewBox 和层的 zoom 不是同一组数 成片比计划短 某个 span 帧数不够，看 compose 阶段的报错 层边界闪一小段原片 overlay 截图陈旧（帧标记验证失效）。产品靠页面顶部的 帧标记条自证每张截图属于哪一帧；若复发，先确认 overlay PNG 顶部有标记条、compose 有裁掉它的 crop 找不到 Chrome 装 Google Chrome，别改成别的渲染路径 ```

## 不许做什么

- 不许把「导出成功」说成「验收通过」——命令返回成功只是产品自己对得上，不是画面对 - 不许用预览截图、DOM、日志代替成片抽帧 - 不许没人听过就报 human listening PASS - 不许为了让导出跑通去改项目文件（改字幕、删层、动账本）。导出只读，不写 - 不许在导出里补做上游的活：缺字幕就去写字幕，缺画面就去做画面，别在这一段临时糊一个

--- name: chengfeng-export description: 把剪好的口播烧成一个成片文件：账本切片段、推近、字幕、HTML 画面层，一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。 user-invocable: true ---

# 导出（成片）

**这是链条最后一段，也是整个产品里唯一一个真正画出像素的地方。**

在它之前全部是标注：账本记「播哪些词」，字幕记「屏上写什么」，画面记「盖什么层」， 预览把这三样实时拼给人看，**不落盘**。导出把它们烧成一个文件。

```text 需要 edit-list.json（必须）、subtitles.json、visuals.json + modules/ 产出 成片.mp4 ```

前提工具：机器上有 **Google Chrome**（用来把字幕和动画画成图）。桌面安装来源的 FFmpeg / FFprobe 已随 App 进入 Product 受管目录；纯 CLI 安装仍要求系统 `ffmpeg ≥ 6`。缺 Chrome 会明确报错，不要试图绕过——没有它就没有字幕层和动画层。

先读取并执行 [业务 Skill 的阶段合同](../../references/business-workflow-contract.md) 里的「结论等级」一节。**导出不进剪辑状态机**：它不改任何项目文件、不做 CAS 写入、 不推进 stage，产出是一个新文件，重跑一次就覆盖。所以它不需要确认卡。

## 0. 就绪

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

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

## 命令

```bash node "<插件根>/scripts/ensure-running.cjs" --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --dry-run --json # 先看计划，不编码 node "<插件根>/scripts/videocut-cli.cjs" export <project> --json # 出成片（默认 2 倍、源帧率） node "<插件根>/scripts/videocut-cli.cjs" export <project> --out /path/成片.mp4 --json node "<插件根>/scripts/videocut-cli.cjs" export <project> --scale 1 --json # 只要源尺寸 node "<插件根>/scripts/videocut-cli.cjs" export <project> --keep-work --json # 留下中间片和逐帧 PNG，供排查 ```

`ensure-running` 身份不匹配、端口冲突或服务不健康时立即停止；不允许用 foreground 临时顶替后继续导出。

## 两步，别只跑第二步

```text ① --dry-run 先报计划 片长、帧数、字幕屏数、画面层数、推近段数、输出尺寸 念给用户听。数字不对就是上游不对，编码十分钟不会修好它 ② 真跑 assemble → overlay → compose → verify 四段进度 ```

`--dry-run` 里的 `warnings` 必须原样转述。它只报一类事：**某些字幕屏或画面层的词 已经被剪掉了**，所以它们不会出现在成片里。这是上游要决定的事，不是导出该替人吞掉的。

## 清晰度：源片是天花板，先看源再谈放大

导出前看一眼源分辨率（`--dry-run` 的 `source` 字段就有）：

```text 源宽 ≥2560（Retina 原生录屏） → --scale 1，输出就是原生像素，这是最好的情况 源宽 <1920（如 960×720） → 先停一下：问用户有没有同一次录制的高清导出。 录屏工具常常能把同一次录制重新导出成 3 倍分辨率， 换源比任何后期都管用（见下节）。确实没有 → --scale 2 ```

`--scale 2` 对低清源有用的原因：底片放大不会变清楚，但**字幕和动画是按输出尺寸 重画的**——观众真正在读的就是这两样；平台再压一次时，大图分到的码率也更高。

**不要为了「更清晰」去调 `--fps`。** 帧率跟着源片走；改它只会让动画的采样和录屏对不上。

## 换源：用户拿出同一次录制的高清版时

这不是导出流程的一部分——导出本身永远只读。换源是用户明确点头后的独立素材操作， 做完再回来正常导出。

**先判定是不是同一条**（前两条就足够硬）：

```bash ffprobe -v error -show_entries format=duration -of csv=p=0 <两个文件> # 时长精确到毫秒相同 ffmpeg -v error -i <文件> -map 0:a:0 -c copy -f md5 - # 音频流逐位相同 # 再抽两三帧对比画面内容，眼睛确认 ```

**音频逐位相同 = 时间线相同**：逐词稿、账本、字幕、画面层全绑词 id，一个不用动。 这正是「绑词不绑秒」在换源这件事上的兑现。

**换源四步**（2026-07-29 真实走过一次；第 ③ 步当时漏了，剪辑预览当场报 「生成失败」——指纹记录不止一处，grep 旧指纹找全再动手）：

```text ① 换文件 input/source.mp4 和 uploads/source.mp4 是硬链接对 —— 删两个，拷新文件到 input/，再建硬链接回 uploads/ （macOS 用 ln；Windows 用 New-Item -ItemType HardLink） ② 更新指纹 project.json 的 source.sha256 改成新文件的 ③ 再查一处 workbench.json 的 sourceSha256 也记着源片指纹， 剪辑预览管道校验的恰恰是这本 —— 漏了它，预览拒绝生成 （这是产品的正确行为：指纹对不上宁可失败，不拿旧预览冒充） ④ 重导 --scale 1 —— 换源就是为了原生像素，别再放大 ```

保险做法：用你的搜索工具在 <项目目录> 的全部 *.json 里找旧指纹前 8 位， 列出来的每一处都要处理（缓存记录如 preview-edited/current.json 会自动重算，不用手动改）。

音频不同（重新录了一遍、剪过、时长不一样）就**不是换源**，是新项目： 逐词稿要重新转，所有标注作废。别硬套。

## 验收：三件事，缺一件就不算导出完成

```text ① 命令成功返回 产品自己数成片的尺寸、帧数、音轨，和计划逐项比。 对不上就是 readback_mismatch 报错，文件留在盘上当证据， 不算导出完成 ② 抽帧看像素 从成片里抽帧，用眼睛看。至少覆盖：一个推近段、 一个整屏动画段、一个只有字幕的段、一个层与层的边界 ③ 人耳听感 没人真的听过，一律记 human listening UNVERIFIED ```

② 不许用预览截图代替。**预览和成片是两条渲染路径，验收要看的正是它们对不对得上**—— 拿预览的图当成片的证据，等于把要验的那件事当成了前提。

**判推近要找判别性地标，整体印象会骗人**（2026-07-29 真踩过）：1.6 倍推近后的 屏幕页面看起来仍像"一整页"，缩略图上和全景几乎没差别——曾把正确的推近帧误判成 "推近丢了"，白追半小时、重导两次。正确判法是找**只有裁剪才能造成的证据**： 被裁掉一半的元素（气泡从中间断开）、消失的边缘元素（侧栏、标题栏）。 和源片同刻帧对比一眼定案。

抽帧就用 ffmpeg：

```bash ffmpeg -v error -ss 8.84 -i 成片.mp4 -frames:v 1 -y frame.png ```

## 出问题往哪查

`--keep-work` 会在项目的 `.chengfeng-videocut/export/` 下留三样东西， 它们把「哪一半错了」直接分开：

```text assembled.mkv 只有剪辑，没有任何盖的东西。它错 = 账本或切片错 overlay/*.png 只有盖的东西，透明底。它错 = 字幕样式或模块错 spans/*.mp4 合成后的分段。它错 = 推近或对齐错 ```

对照表：

```text 成片没有字幕/动画 overlay PNG 是不是全透明？模块是不是没答应 seek？ 动画停在第一帧 模块没实现 seek，或者 GSAP 时间线没 paused 画面整块白 模块少了 `:root { color-scheme: dark }` 推近的框歪了 模块的 viewBox 和层的 zoom 不是同一组数 成片比计划短 某个 span 帧数不够，看 compose 阶段的报错 层边界闪一小段原片 overlay 截图陈旧（帧标记验证失效）。产品靠页面顶部的 帧标记条自证每张截图属于哪一帧；若复发，先确认 overlay PNG 顶部有标记条、compose 有裁掉它的 crop 找不到 Chrome 装 Google Chrome，别改成别的渲染路径 ```

## 不许做什么

- 不许把「导出成功」说成「验收通过」——命令返回成功只是产品自己对得上，不是画面对 - 不许用预览截图、DOM、日志代替成片抽帧 - 不许没人听过就报 human listening PASS - 不许为了让导出跑通去改项目文件（改字幕、删层、动账本）。导出只读，不写 - 不许在导出里补做上游的活：缺字幕就去写字幕，缺画面就去做画面，别在这一段临时糊一个