/gtrk-oralcut

name: gtrk-oralcut
description: 智能口播剪辑闭环——开剪前主动检查同目录独立口播音频，有则先对轨换声，再通过同合云剪掉废话/重复/长停顿，产出客户端(gtrk)+剪映+PR 三方工程。当用户想「剪口播/剪个视频/智能剪辑/去掉废话和停顿/把这条口播剪一版/出剪映草稿/生成剪辑工程/oral cut」时使用本 skill。凡涉及把口播毛片做成可二次精修的剪辑工程，优先用本 skill 驱动 gtrk CLI，不要手搓 ffmpeg。

口播剪辑（gtrk-oralcut）

> **⚠️ 用户要的是「完整包装的成片」而非只剪干净？先去 `/gtrk-talking-head`（口播链图纸）。** > 那张图纸把本命令接进全链：外录音轨对轨换声 → 多段拼接 → 本命令粗剪 → 拆分/B-roll/字卡/BGM/字幕 → 客户端出片。 > 本 skill 是**命令手册**（怎么跑 oralcut），那张是**场景图纸**（怎么串全链），配合用不冲突。

把用户的口播毛片，用 `gtrk` CLI 跑通「**检查独立口播音频 →（如有）先对轨换声 → 本地抽音频/720p → 只传抽出物（毛片永不上传）** → 云端智能口播剪辑 → 拉回三方工程文件 →（可选）**本地 ffmpeg 渲染成片**」，再把产物目录 + 三端打开方式回给用户。**CLI 是手、你是脑。**

> **本 skill 已含你需要的全部信息**（参数、取值、执行、读报告、排错），照它做即可，不用也无法去查外部文档。（源仓库另有一份更全的工具无关版 `AGENT.md`，那是给在仓库里开发的人看的，与你无关。）

前置：CLI 装没装 + 体检

先跑 `gtrk doctor`（它顺带验证 `gtrk` 命令本身在不在）：

• **`gtrk` 找不到 / command not found** → CLI 没装 → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
• 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key + 剪映目录，**交互式、需真终端**，你别替他跑）。
• 报云端连不上 / 剪映目录没配 → 照提示让用户处理。
• 全绿就往下走。

ffmpeg 依赖（本地抽音频 / 渲染必需，缺了你来装）

oralcut 现在**本地预处理**（探原片几何 + 抽 16k 单声道 mp3 / 压 720p 代理）和 **本地渲染**都靠 `ffmpeg`/`ffprobe`。看 `gtrk doctor` 里「本地渲染 (ffmpeg)」这行：

• **已就绪** → 往下走。
• **未找到** → 你来装（CLI 不自下不自分发）：**先确认确实没有**（doctor 已查过 `~/.gitruck/ffmpeg` 与系统 PATH），缺了再拉 `ffmpeg` + `ffprobe` 两个可执行文件放到 `~/.gitruck/ffmpeg/`（Windows 即 `ffmpeg.exe`/`ffprobe.exe`）。
• **国内用户优先国内加速站点**：GitHub 官方静态构建（BtbN / gyan.dev）直连慢，走 GitHub 加速代理（pass-through）或同合云自建镜像拉，下载后**核对 sha256**。
• 装好复跑 `gtrk doctor` 确认转绿。
• 用户自己装过 ffmpeg 并配了 PATH → doctor 会从系统探到直接用；**绝不去改用户的环境变量/PATH**（CLI 一律绝对路径调用）。若装在别处，用 `--ffmpeg-path <目录>` 指给它。

开剪前硬闸：主动发现独立口播音频，先对轨再 oralcut

**无论用户有没有主动提到外录音频，执行 agent 都必须在第一次 `gtrk oralcut` 之前检查毛片所在目录。** 用户给的是目录时，先列出其中的视频与音频；用户给的是单个视频时，也要查看它的同目录。识别 `wav / mp3 / m4a / flac` 等独立音频，并按文件名、同一拍摄批次与数量关系判断是否是该视频的口播外录：

• 唯一视频 + 唯一口播音频，或名称可明显配对（如 `03思考_视频_V01.mp4` ↔ `03思考_音频_V01.flac`）→ **直接视为一组，不用反问用户**。
• 多个视频/音频且配对有歧义 → 在任何上传或 oralcut 计费前，让用户确认映射关系。
• 文件名/上下文明确是 BGM、配乐、伴奏或环境声 → 不是口播外录，不走对轨。

发现可配对的独立口播音频后，固定顺序：

gtrk audio align "<毛片>" "<外录>" --json
gtrk oralcut "<align 结果 JSON 的 output，即 *_extaudio.mp4>" [原有参数…] --json

• **MUST 先 align、再 oralcut。MUST NOT 先剪机内声，事后再把外录硬塞进工程或另剪一版补救。** align 产物已经把外录换进视频，后续 oralcut 的每个画面切点会天然同步作用到外录声。
• align 高置信自动完成时，后续输入必须切换为结果 JSON 的 `output`，不要继续拿原毛片跑 oralcut。
• align 低置信时会产 `*_align.gtrk`：停下让用户在客户端拖齐并保存，再跑 `gtrk audio align --resume "<对齐工程>" --json`；拿到换轨产物后才允许继续 oralcut。
• align 失败时如实停下排错；除非用户明确同意，**不得静默回退到机内声开剪**。
• 换轨产物是后续工程依赖素材，必须提醒用户留存；原毛片保留不动，作为内录保底。
• **文稿路径要在换轨前记住**：若原毛片靠同名 `.txt` 自动探稿，换轨后的 `_extaudio.mp4` 通常匹配不到原同名文稿，后续必须显式传 `--script "<原文稿路径>"`。

没有发现独立口播音频，才直接对原毛片执行 oralcut。

把用户的话变成一次调用

> **每次调用都必须带 `--json`**（成功时 stdout 只出一行结果 JSON、人读日志转 stderr），你才能解析结果 + 读报告。不是可选项。

从用户消息里取这几样，缺关键的就问：

1. **毛片路径**（必需）：口播原视频的本地路径。没有就问。 2. **文稿**：用户给了逐字稿/文字稿**文件** → `--script <txt文件路径>`（接的是 .txt 文件路径，不是稿子正文）；没给则不传（CLI 会探毛片同名 `.txt`，有就自动按有稿剪、更准；无则云端无稿智能重建）。 3. **节奏**：用户说「快/紧凑/卡点狠」→ `--preset compact`；「稳/别删太多停顿」→ `--preset steady`；没特别说就不传（CLI 默认 `concise` 精练）。 4. **只要某端**：只要客户端 → `--formats gtrk`；只要剪映 → `--formats jianying`；只要 PR → `--formats xml`（全部格式见下表、逗号可多选）；默认三端全给（`gtrk,jianying,xml`）。

完整参数规格 —— 按用户需求因势象形、自由组合

**你手上有云端全部参数（下表）。按用户的具体诉求自由决定用哪些、怎么配——需要就调、没提就跑默认（默认已是给多数人调好的）。** 只有一条要求：**名字 / 取值 / 范围照下表用**（别记错拼错）；万一传越界，云端会报 `6016` 并附具体原因，照着改即可——乱传不会产出错误成片，只会明确报错。

| 用户想要 | CLI 怎么传 | 取值 · 默认 | 说明 | |---|---|---|---| | 有稿对齐（更准） | `--script <txt>`（或毛片同名 `.txt` 自动） | 10–50000 字 · 缺省无稿重建 | 有稿逐字对齐质量最佳；无稿智能重建终稿 | | 换语种 | `--lang <码>` | `zh-CN`/`en-US`/`ja-JP`… · 默认 `zh-CN` | 不传即 CLI 默认发 `zh-CN`；主推中文，余语种尽力而为 | | 产哪些工程格式 | `--formats <逗号列表>` | `xml`/`fcpxml`/`otio`/`jianying`/`capcut`/`gtrk` · CLI 缺省 `gtrk,jianying,xml` | 可多选 | | 顺带出成片视频 | `--render` | 开关 · 缺省不渲 | **本地** ffmpeg 按 gtrk EDL 渲染 mp4（毛片仍不上传、云端不渲染）；需 ffmpeg 就绪 | | 成片画质 | `--crf <n>`（配 `--render`） | 整数 14–28 · `18` | 本地渲染用；越小越清晰 / 越大体积越小 | | 成片编码 | `--codec <c>`（配 `--render`） | `h264` · `h264` | 本地渲染用；当前仅 h264 | | 指定 ffmpeg 位置 | `--ffmpeg-path <目录>` | 路径 · 缺省 `~/.gitruck/ffmpeg`→系统 | 用户 ffmpeg 装在非标准位置时指给它 | | 节奏松紧 | `--preset <名>` | `steady`/`concise`/`compact` · 默认 `concise` | 不传即 CLI 默认发 `concise`（精练）；见下方预设表，铺底后可逐项覆盖 | | **剪不准 / 剪掉真内容 / 有话没剪进去** | `--visual-assist` | 开关 · 关 | 开则**本地改传 720p 代理**（非上传原片）+ **视觉找补兜底**：画面说话检测保护疑似漏识别段不被误剪并重识别捞回（需说话人面部基本可见）；上传体量比纯音频大、处理耗时增加，但不额外计费、绝不凭空生成 | | 别随说话人节奏自适应 | `--no-adaptive-rhythm` | 一元 flag：传即关闭 · 自适应默认开 | 是否定 flag（不接受 `=值` 赋值）；关了改用固定标点停顿表 | | 剪映草稿目录（非标准位置） | `--jianying-draft-dir <目录>`（或 `auto`） | 路径 · 读 init 配置 / 自动探测 | 出剪映可直开草稿需要它 | | 工程落盘到别处 | `--out <目录>`（或 `-o`） | 路径 · 缺省 `<毛片同目录>/<毛片名>-video-project-<时间戳>` | 想把产物放指定位置时用 |

**更细的节奏散参数**（无一等 flag，用 `--param 键=值` 或嵌套 `--params-json`）：

| 参数 | 传法 | 取值 · 默认 | 说明 | |---|---|---|---| | `punctuation_breaks` | `--params-json '{"punctuation_breaks":{"。":0.6,"，":0.3}}'` | 每标点 0–5 秒 · 见预设表 | 逐标点停顿；键只能是 `，、；：。！？—……` 和 `paragraph`（段落） | | `intra_gap_max` | `--param intra_gap_max=0.4` | 0–5 · `0.35` | 句内停顿超此值算气口、触发收紧 | | `intra_gap_target` | `--param intra_gap_target=0.05` | 0–5 且 <max · `0.10` | 气口收到的目标秒数 | | `pad_in` / `pad_out` | `--param pad_out=0.15` | 0–5 · `0.05` / `0.08` | 保留片段头 / 尾呼吸留白 | | `render.audio_crossfade_ms` | `--params-json '{"render":{"audio_crossfade_ms":12}}'` | 0–50 · `8` | 切点淡化毫秒，`0`=硬切；**需配 `--render`**（属成片音频淡化，不开 --render 云端忽略此字段） |

**节奏预设表 · 完整值**（选最贴内容类型的，再逐项覆盖散参数；「默认」列 = 不选预设时的基线，也即各标点的默认停顿）：

| 参数（秒） | `steady` 稳健 | `concise` 精练 | `compact` 紧凑 | 默认 | |---|---|---|---|---| | 适用 | 讲述 / 教学 | 自媒体中长视频 | 短视频 / 广告 | 通用 | | `、` / `，` / `；` | 0.18 / 0.25 / 0.36 | 0.12 / 0.18 / 0.26 | 0.06 / 0.08 / 0.12 | 0.15 / 0.20 / 0.30 | | `：` / `—` | 0.45 / 0.55 | 0.32 / 0.40 | 0.15 / 0.18 | 0.35 / 0.45 | | `。` `！` / `？` | 0.55 / 0.60 | 0.40 / 0.45 | 0.18 / 0.20 | 0.45 / 0.50 | | `……` / `paragraph`（段落） | 0.75 / 1.20 | 0.55 / 0.90 | 0.25 / 0.40 | 0.60 / 1.00 | | `intra_gap_max` / `intra_gap_target` | 0.45 / 0.15 | 0.35 / 0.10 | 0.25 / 0.05 | 0.35 / 0.10 | | `pad_in` / `pad_out` | 0.05 / 0.10 | 0.05 / 0.08 | 0.03 / 0.05 | 0.05