口播剪辑（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），你才能解析结果 + 读报告。不是可选项。
从用户消息里取这几样，缺关键的就问：
- 毛片路径（必需）：口播原视频的本地路径。没有就问。
- 文稿：用户给了逐字稿/文字稿文件 →
--script <txt文件路径>（接的是 .txt 文件路径，不是稿子正文）；没给则不传（CLI 会探毛片同名 .txt，有就自动按有稿剪、更准；无则云端无稿智能重建）。
- 节奏：用户说「快/紧凑/卡点狠」→
--preset compact；「稳/别删太多停顿」→ --preset steady；没特别说就不传（CLI 默认 concise 精练）。
- 只要某端：只要客户端 →
--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 / 0.08 |
因势象形举例：「教学口播、别删太狠、句号后多顿一下」→ --preset steady --params-json '{"punctuation_breaks":{"。":0.7}}'；「英文短视频卡点狠、顺便出成片」→ --lang en-US --preset compact --render；「上次有句话没剪进去」→ --visual-assist。用户自己点名某参数+值 → 照他原样 --param/--params-json 透传（CLI 底层支持任意云端参数）。
以上就是你需要的全部参数——本 skill 自足，别去别处查（gtrk oralcut --help 也随时列全部 flag）。官网另有一份面向开发者的原始 HTTP API 文档，那是给人看的，你不必也无法访问。
执行（每次都带 --json）
产物落点纪律（MUST · 全文见随包 AGENT.md 同名一节）：交付物只写入工程目录或用户显式指定的输出路径；引用媒体用原路径，不复制到 agent 工作目录；临时文件放系统 temp，用完即删。
交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|concise|compact] [其它参数…] --json
--json：人读日志走 stderr，成功时 stdout 只有一行结果 JSON：
{ ok, outDir, files:{gtrk:[],jianying:[],xml:[]}, jianyingDraftPath, rendered, report, errors, taskId, fileId }（rendered=本地渲染成片路径，未开 --render 时为 null）- 命令失败（毛片路径错 / 鉴权失败 / 参数越界 6016 等）→ 进程非 0 退出、报错打到 stderr、stdout 无 JSON。先看退出码，非 0 就把 stderr 的报错如实回给用户、别当成功。
- 默认会自动打开产物目录（用户能直接看到文件）；纯脚本/无头环境才加
--no-open。
- 云端处理是分钟级，耐心等命令返回。
- 毛片 > 2 小时跑不了：CLI 在上传前就会拦下（零抽取、零上传、零扣费），不是跑到一半才失败。
遇到超长毛片先分段再逐段剪，切段用流拷贝、秒级完成、不重编码：
ffmpeg -ss 0 -t 2400 -i "<毛片>" -c copy "<毛片名>_seg01.mp4"（2400s = 40 分钟/段）。
各段各出一份工程，逐段精修互不影响。
跑完读报告、给用户交代、按需调整（因势象形的另一半）
--json 的 stdout 那行带 report（云端返回的原始剪辑报告对象，字段按需读、个别可能缺，读前判空）——读它，别只回一句"剪好了"：
duration_before → duration_after：剪了多少（如 114.7s → 68.6s）。script_source + final_script：终稿来源与内容（script_source=user 用户给稿 / rebuilt 智能重建）。无稿重建（rebuilt）时务必把 final_script 回给用户核对——那是机器猜出来的终稿，可能跟本意有出入。dropped[]：剔掉了哪些段（元素 {start,end,asr_text,reason}，reason：retake 重读 / misread 口误·弃读·终稿外内容）——可挑几条告诉用户「去掉了这些重录 / 口误或非终稿内容」。coverage（0–1）：终稿覆盖率。低于 0.6（附 low_coverage）= 文稿与实拍严重不符 → 提醒用户核对文稿、或考虑无稿重跑。uncovered_script[]：文稿里有、实拍没找到的段（漏读） → 如实告诉用户「『xx』这段没在录像里找到」；疑似是漏识别而非真漏读时，建议加 --visual-assist 重跑。review_points[]：建议人工复核处（{time,note}，识别置信度偏低）。insufficient_breaks[]：源素材留白不足、停顿没达到设定值的位置（{time,want,got}）——想让停顿更足可调 --preset/散参数，但受原素材限制。rhythm_preset（实际采用的预设名、无预设为 null）/ adaptive_rhythm（自适应是否生效；生效时另有 pause_profile 说话人停顿画像，调参参照）/ analysis_degraded（是否降级到纯机械规则）。- 开了
--visual-assist：suspect_omissions / stt_recovered（找回了哪些字）/ visual_assist_degraded。
ok：true = 全部格式成功、errors 为空；只要有一个格式失败 ok 即 false 且 errors 非空（其余格式仍可用）→ 如实说哪个格式没出来、为什么，别谎报三端都好。
据此因势象形调整（同一毛片可反复剪对比）：覆盖率低 / 漏读多 → 开 --visual-assist 或核对文稿重跑；节奏不满意 → 调 --preset / 散参数重跑；某格式失败 → 补 --jianying-draft-dir / --reupload 重跑。
跑完确认 files.gtrk[0] 在；要剪映确认 jianyingDraftPath 非空。
回给用户（三端打开方式）
- 客户端：在同合云桌面客户端（OpenCut Gitruck Edition）里「打开工程」选
files.gtrk[0]（…/gtrk/project.gtrk）。
- 剪映：已自动落到剪映草稿目录（
jianyingDraftPath），开剪映在项目列表里找同名工程即可。
- PR/FCP：Premiere 里「文件 > 导入」
files.xml[0]（…/xml/premiere.xml）。
同时提醒用户：若导入时弹出「链接媒体」框（素材被移动、改名，或路径在这台机器上无效），链接前先确认目标文件；勾着「自动重新链接其他媒体」时，Premiere 会按文件名在所选位置查找其余缺失素材并自动链上，链错也不提示——同合云素材多以编号命名，不同工程里同名文件很常见，链完要在项目面板「媒体路径」列逐条核对，拿不准就取消该选项、逐个链接。用户反馈 PR 里素材脱机时，先问素材是否移动过、路径在这台机器上是否有效；MUST NOT 建议勾「自动重新链接其他媒体」一把链完。
产物目录名形如 <毛片名>-video-project-<时间戳>，靠文件名 + 时间认出是哪一次剪辑、互不覆盖。
下一步（自动接力，别停在交工）
口播工程剪好只是成片一条龙的第一站。确认 ok=true、files.gtrk[0] 与 transcript 就绪后，别停下等用户开口——顺势接力到视觉拆分：触发 /gtrk-splitter（把这条工程 + transcript 拆成 beat 级分镜派单，agent 再跑 gtrk split 产 dispatch.json），驱动后续各车道生产+铺轨。一句话交代即推进：「口播工程已就绪，我接着把它拆成分镜派单」。
逃生门：两种信号都要认（范围 + 节奏）
用户表达了范围保留或节奏保留，就停在这一步、别自动接力。 两者语义正交，认漏一个都会误冲：
- 范围信号 = 走多远（我只要这一个产物）：「只要这版剪辑工程」「先不往下」「暂不出片」。
- 节奏信号 = 怎么走（每步停等我）：「逐步推进」（这是本仓公约立法定名的正式模式名，
定义就是「每步停等确认」，用户会照着这么说）、「一步步来」「先 X 然后我们再说」
「我看看再定」「等我确认」。
⚠️ 上面的词只是举例、不是白名单——判据是「用户表达了节奏/范围保留」，换个说法照样得听懂。
典型误判：「先智能剪口播 然后我们逐步推进」——用户说了「然后」，明确表示还要往下，
范围逃生门逐字不成立；但节奏逃生门成立 ⇒ SHALL 停。不要因用户说「然后」就忽略明确的逐步推进要求。
停下时必须交代下一步是什么、他说一声就继续，别退化成事事请示。示范：
「口播工程已就绪。按你说的逐步来，我先停在这。下一步是拆成 beat 级分镜派单，你说一声我就接着做。」
没有这两类信号时不改默认：仍按上文自动接力，别问「要不要继续」。
原则：agent 替用户跑 CLI / 接力 skill，用户只对话——别让用户自己去终端敲下一条 gtrk 命令。
改工程：走 gtrk patch，不要裸手改 JSON
跑完之后要微调某个片段（挪位置 / 改时长 / 切开 / 改音量）时，一律用 gtrk patch：
gtrk patch move --project <dir> --clip <clip_id> --to 5.0
gtrk patch trim --project <dir> --clip <clip_id> --out -1s
MUST NOT 直接编辑 .gtrk 的 JSON。 片段时码是两套并存的（clip_st+clip_ed 与
clip_st+duration）：改一份不改另一份，客户端优先读 clip_ed、后端又不强校验它 ⇒
gtrk patch 替你做恒等式同步 + 帧对齐 + 写前全档校验。
参数手册在 AGENT.md 的「元素级编辑：gtrk patch」一节与 README 命令参考。
本节只指路不搬手册 —— 搬过来就会长出会漂移的副本。