@gitruck/cli 1.1.2 → 1.1.4

package/skills/gtrk-mg/SKILL.md

@@ -169,7 +169,26 @@ gtrk mg --project "<split产物目录>" --json
 
 ★ **若你是走前置硬门 2 的「明示跳过 AI」进来的**：收口前 MUST 把那份「**AI 回铺后待复查构图**」清单复述给用户（哪几颗颗粒、对应哪几个 AI beat 区间），并说明「AI 片段回铺后这几颗可能要重产」。**MUST NOT 静默收口。**
 
-除非用户表示只铺这一版 MG、暂不出片。
+### 逃生门：两种信号都要认（范围 + 节奏）
+
+上面的「别收工、顺势收口」是**默认**，但**用户表达了范围保留或节奏保留时 SHALL 停在铺完这一步、
+SHALL NOT 自动上字幕出片**（`gtrk render` 还是计费/耗时动作，更不能替他拍板）。
+两者语义正交，认漏一个都会误冲：
+
+- **范围信号 = 走多远**（我只要这一个产物）：「只铺这一版 MG、暂不出片」「先不渲」「工程给我就行」。
+- **节奏信号 = 怎么走**（每步停等我）：**「逐步推进」**（本仓公约立法定名的正式模式名，
+  定义就是「每步停等确认」，用户会照着这么说）、「一步步来」「先 X 然后我们再说」
+  「我看看再定」「等我确认」。
+
+⚠️ **词表只是举例、不是白名单**——判据是「**用户表达了节奏/范围保留**」，换个说法照样得听懂。
+特别注意「先 X **然后**我们逐步推进」：用户明说了还要往下，**范围**逃生门逐字不成立，
+但**节奏**逃生门成立 ⇒ **停**。
+
+停下时**必须交代下一步是什么、他说一声就继续**（例：「MG 颗粒已叠铺完。按你说的逐步来我先停在这，
+下一步是上字幕 + `gtrk render` 出片，你说一声我就接着做」），别退化成事事请示。
+★ 上面那份「AI 回铺后待复查构图」清单**该复述照复述**——停下不等于不交代。
+
+**没有这两类信号时不改默认**：仍按上文顺势收口。
 
 **渲完必看质检摘要**：`gtrk render` 收口后会自动扫一遍成片（闪帧 / 段内跳切 / 黑帧 / 冻结 / 爆音 / 静音 / 音画不同步），落 `<成片名>.qc.json` 并打摘要。**「严重」条目要如实转述给用户并给出路**，别把有缺陷的片子说成出好了：
 

package/skills/gtrk-narration/SKILL.md

@@ -213,11 +213,14 @@ gtrk transcript "<长片>" --lang <开工⑦所答语种> --json   # 影视/游
 #     MUST NOT 以「粤语传错」为由重跑（la 进 ASR 缓存键，换码必 cache miss、白扣一次时长）。详见 §二 ⑦ 注
 
 # ②③ 写稿（甲档出处共生 / 乙路对照表对齐）→ 检查点①拍板（§六）
-gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --commercial-only --json   # BGM 候选附试听
-#   ⚠️ 版权判断不在零件手里，在你手里：零件缺省 copyright_scope=all（**不筛**）。
-#   is_copyright 的权威语义是 1/true=可商用、0/false=**不可商用**——反直觉，MUST NOT 把 false
-#   读成「无版权、可随便用」。带 --commercial-only 就把不可商用的挡在候选之外；不带就 MUST
-#   逐条按 copyright_label（派生位，中文标签）自己判，别默认候选都能用。
+gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
+#   ⚠️ is_copyright 的权威语义是 1/true=可商用、0/false=**不可商用**——反直觉，MUST NOT 把 false
+#   读成「无版权、可随便用」（真机上正是这一步读反，把不可商用素材铺进了 5 个工程）。
+#   ⟲ 260906 拍板 · 选材口径：矩阵成员档**缺省搜全库**，MUST NOT 默认加 --commercial-only、
+#   也 MUST NOT 以「保险起见」为由剔掉 is_copyright:false 的候选（全库正是成员身份买到的东西）。
+#   对价是**如实标注**：推荐时 MUST 逐条带上 copyright_label（派生位，中文标签），不可商用的照直说，
+#   但 MUST NOT 升级成追问或阻塞。用户**特意说明**只要可商用 / 要商用发布 / 客户商单时才加
+#   --commercial-only 收紧；「用户没说」MUST NOT 当成「用户要求收紧」。
 
 # ④ 声音基座（按开工④路由）
 gtrk tool audio_tts_clone --text-file <稿段.txt> --speaker <voice_id> --json   # TTS 路

package/skills/gtrk-oralcut/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gtrk-oralcut
-description: 智能口播剪辑闭环——把一条口播原视频(毛片)通过同合云云端剪掉废话/重复/长停顿，产出客户端(gtrk)+剪映+PR 三方工程文件并自动打开产物目录。当用户想「剪口播/剪个视频/智能剪辑/去掉废话和停顿/把这条口播剪一版/出剪映草稿/生成剪辑工程/oral cut」时使用本 skill。凡涉及把口播毛片做成可二次精修的剪辑工程，优先用本 skill 驱动 gtrk CLI，不要手搓 ffmpeg。
+description: 智能口播剪辑闭环——开剪前主动检查同目录独立口播音频，有则先对轨换声，再通过同合云剪掉废话/重复/长停顿，产出客户端(gtrk)+剪映+PR 三方工程。当用户想「剪口播/剪个视频/智能剪辑/去掉废话和停顿/把这条口播剪一版/出剪映草稿/生成剪辑工程/oral cut」时使用本 skill。凡涉及把口播毛片做成可二次精修的剪辑工程，优先用本 skill 驱动 gtrk CLI，不要手搓 ffmpeg。
 ---
 
 # 口播剪辑（gtrk-oralcut）
@@ -9,7 +9,7 @@ description: 智能口播剪辑闭环——把一条口播原视频(毛片)通
 > 那张图纸把本命令接进全链：外录音轨对轨换声 → 多段拼接 → 本命令粗剪 → 拆分/B-roll/字卡/BGM/字幕 → 客户端出片。
 > 本 skill 是**命令手册**（怎么跑 oralcut），那张是**场景图纸**（怎么串全链），配合用不冲突。
 
-把用户的口播毛片，用 `gtrk` CLI 跑通「**本地抽音频/720p → 只传抽出物（毛片永不上传）** → 云端智能口播剪辑 → 拉回三方工程文件 →（可选）**本地 ffmpeg 渲染成片**」，再把产物目录 + 三端打开方式回给用户。**CLI 是手、你是脑。**
+把用户的口播毛片，用 `gtrk` CLI 跑通「**检查独立口播音频 →（如有）先对轨换声 → 本地抽音频/720p → 只传抽出物（毛片永不上传）** → 云端智能口播剪辑 → 拉回三方工程文件 →（可选）**本地 ffmpeg 渲染成片**」，再把产物目录 + 三端打开方式回给用户。**CLI 是手、你是脑。**
 
 > **本 skill 已含你需要的全部信息**（参数、取值、执行、读报告、排错），照它做即可，不用也无法去查外部文档。（源仓库另有一份更全的工具无关版 `AGENT.md`，那是给在仓库里开发的人看的，与你无关。）
 
@@ -29,9 +29,33 @@ oralcut 现在**本地预处理**（探原片几何 + 抽 16k 单声道 mp3 /
 - **未找到** → 你来装（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 <目录>` 指给它。
-
-## 把用户的话变成一次调用
+- 用户自己装过 ffmpeg 并配了 PATH → doctor 会从系统探到直接用；**绝不去改用户的环境变量/PATH**（CLI 一律绝对路径调用）。若装在别处，用 `--ffmpeg-path <目录>` 指给它。
+
+## 开剪前硬闸：主动发现独立口播音频，先对轨再 oralcut
+
+**无论用户有没有主动提到外录音频，执行 agent 都必须在第一次 `gtrk oralcut` 之前检查毛片所在目录。** 用户给的是目录时，先列出其中的视频与音频；用户给的是单个视频时，也要查看它的同目录。识别 `wav / mp3 / m4a / flac` 等独立音频，并按文件名、同一拍摄批次与数量关系判断是否是该视频的口播外录：
+
+- 唯一视频 + 唯一口播音频，或名称可明显配对（如 `03思考_视频_V01.mp4` ↔ `03思考_音频_V01.flac`）→ **直接视为一组，不用反问用户**。
+- 多个视频/音频且配对有歧义 → 在任何上传或 oralcut 计费前，让用户确认映射关系。
+- 文件名/上下文明确是 BGM、配乐、伴奏或环境声 → 不是口播外录，不走对轨。
+
+发现可配对的独立口播音频后，固定顺序：
+
+```bash
+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），你才能解析结果 + 读报告。不是可选项。
 
@@ -137,7 +161,26 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 
 ## 下一步（自动接力，别停在交工）
 
-口播工程剪好只是成片一条龙的第一站。确认 `ok=true`、`files.gtrk[0]` 与 transcript 就绪后，**别停下等用户开口**——顺势接力到视觉拆分：触发 `/gtrk-splitter`（把这条工程 + transcript 拆成 beat 级分镜派单，agent 再跑 `gtrk split` 产 `dispatch.json`），驱动后续各车道生产+铺轨。一句话交代即推进：「口播工程已就绪，我接着把它拆成分镜派单」，除非用户表示只要这版剪辑工程、暂不往下。
+口播工程剪好只是成片一条龙的第一站。确认 `ok=true`、`files.gtrk[0]` 与 transcript 就绪后，**别停下等用户开口**——顺势接力到视觉拆分：触发 `/gtrk-splitter`（把这条工程 + transcript 拆成 beat 级分镜派单，agent 再跑 `gtrk split` 产 `dispatch.json`），驱动后续各车道生产+铺轨。一句话交代即推进：「口播工程已就绪，我接着把它拆成分镜派单」。
+
+### 逃生门：两种信号都要认（范围 + 节奏）
+
+**用户表达了范围保留或节奏保留，就停在这一步、别自动接力。** 两者语义正交，认漏一个都会误冲：
+
+- **范围信号 = 走多远**（我只要这一个产物）：「只要这版剪辑工程」「先不往下」「暂不出片」。
+- **节奏信号 = 怎么走**（每步停等我）：**「逐步推进」**（这是本仓公约立法定名的正式模式名，
+  定义就是「每步停等确认」，用户会照着这么说）、「一步步来」「先 X 然后我们再说」
+  「我看看再定」「等我确认」。
+
+⚠️ **上面的词只是举例、不是白名单**——判据是「**用户表达了节奏/范围保留**」，换个说法照样得听懂。
+典型误判：「先智能剪口播 **然后我们逐步推进**」——用户说了「然后」，明确表示还要往下，
+**范围**逃生门逐字不成立；但**节奏**逃生门成立 ⇒ **SHALL 停**。（2026-09-04 真机事故就栽在这里：
+当时只写了范围侧，agent 一口气连跑了三个 skill。）
+
+停下时**必须交代下一步是什么、他说一声就继续**，别退化成事事请示。示范：
+「口播工程已就绪。按你说的逐步来，我先停在这。下一步是拆成 beat 级分镜派单，你说一声我就接着做。」
+
+**没有这两类信号时不改默认**：仍按上文自动接力，别问「要不要继续」。
 
 > 原则：**agent 替用户跑 CLI / 接力 skill，用户只对话**——别让用户自己去终端敲下一条 gtrk 命令。
 

package/skills/gtrk-splitter/SKILL.md

@@ -160,6 +160,25 @@ dispatch 落地后**不要收工**——但下游各车道是**有先后的 SOP
 
 > 每车道有专属**驱动 skill**（懂 SOP 位置 + 管用户检查点）：拆分派单后**直接交棒 ③ `/gtrk-matrix`**（B-roll 底轨的影视/本地素材腿），AI 车道非空时它再交棒同阶段的 `/gtrk-ai-drama`；三源落齐 + ④ 抽帧检查过后，才交棒 ⑤ `/gtrk-mg`。你（agent）触发 `/gtrk-matrix` 起步即可。**agent 替用户跑 CLI，用户只对话。**
 
+#### 逃生门：两种信号都要认（范围 + 节奏）
+
+上面的「别停在派单、直接交棒 `/gtrk-matrix`」是**默认**，但**用户表达了范围保留或节奏保留时
+SHALL 停在派单这一步、SHALL NOT 自动交棒**。两者语义正交，认漏一个都会误冲：
+
+- **范围信号 = 走多远**（我只要这一个产物）：「只要这份拆分稿」「派单出来我先看看」「先不铺轨」。
+- **节奏信号 = 怎么走**（每步停等我）：**「逐步推进」**（本仓公约立法定名的正式模式名，
+  定义就是「每步停等确认」，用户会照着这么说）、「一步步来」「先 X 然后我们再说」
+  「我看看再定」「等我确认」。
+
+⚠️ **词表只是举例、不是白名单**——判据是「**用户表达了节奏/范围保留**」，换个说法照样得听懂。
+特别注意「先 X **然后**我们逐步推进」：用户明说了还要往下，**范围**逃生门逐字不成立，
+但**节奏**逃生门成立 ⇒ **停**。
+
+停下时**必须交代下一步是什么、他说一声就继续**（例：「派单出来了：MG N 槽 / B-roll M 段 / AI K 段。
+按你说的逐步来我先停在这，下一步是铺 B-roll 底轨，你说一声我就接着做」），别退化成事事请示。
+
+**没有这两类信号时不改默认**：仍按上文有序推进、每步替用户跑命令。
+
 ---
 
 ## 拆分方法论（沿《实在界漫游指南》视觉语法精华）

package/skills/gtrk-travel-recap/SKILL.md

@@ -188,7 +188,7 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
    - 用户有本地音乐 → 询问是否 `gtrk tool audio_separation` 伴奏分离后取伴奏（缺省建议分离——TTS 配音不与歌曲人声打架）；
    - 用户未提供 → **搜同和素材矩阵**：`gtrk matrix material "<按稿件情绪+地理文化写的检索词>" --scope audio --top-k 5 --diversity --json`
      （检索词口径见公约 §三′：**内容驱动、禁通用词、至少含一个只有这一片才成立的词**；候选
-     MUST 给用户挑不许默认 top1；跨片避让由 `audio lay` 记账 + 检索缺省 `--exclude-recent` 自动完成）（按成片时长挑可加 `--min-duration <秒>`）。身份路由（矩阵成员搜全库 / 非成员搜公开库）与计费口径由零件持有；**版权判断不在零件手里，在你手里**——零件缺省 `copyright_scope=all`，**不筛**。挑 BGM MUST 按**可商用**口径判：出参 `is_copyright` 的权威语义是 `1/true` = **可商用**、`0/false` = **不可商用**（反直觉：`is_copyright:false` MUST NOT 读成「无版权、可随便用」，它恰恰是不可用的那一档；概念素材固定 `is_copyright=0` 即此意）。派生位 `copyright_label` 直接给了中文标签，照它转述即可。省事路是检索时就带 `--commercial-only`，把不可商用的挡在候选之外；出参 `results[]` 直接用，`upsell` 是独立顶层字段（非成员且没搜够时才有，原样转述给用户即可，**不要**把它当候选）。
+     MUST 给用户挑不许默认 top1；跨片避让由 `audio lay` 记账 + 检索缺省 `--exclude-recent` 自动完成）（按成片时长挑可加 `--min-duration <秒>`）。身份路由（矩阵成员搜全库 / 非成员搜公开库）与计费口径由零件持有；**版权状态要你如实转述**——出参 `is_copyright` 的权威语义是 `1/true` = **可商用**、`0/false` = **不可商用**（反直觉：`is_copyright:false` MUST NOT 读成「无版权、可随便用」，它恰恰是不可用的那一档；概念素材固定 `is_copyright=0` 即此意）。**⟲ 260906 拍板 · 选材口径**：零件缺省 `copyright_scope=all`，矩阵成员档就是**搜全库**——你 MUST NOT 默认加 `--commercial-only`，也 MUST NOT 以「保险起见」为由剔掉 `is_copyright:false` 的候选（全库正是成员身份买到的东西）。对价是**如实标注**：推荐时 MUST 逐条带上派生位 `copyright_label` 给的中文标签，不可商用的照直说，但 MUST NOT 升级成追问或阻塞。用户**特意说明**只要可商用 / 要商用发布 / 客户商单时，才加 `--commercial-only` 把不可商用的挡在候选之外；「用户没说」MUST NOT 当成「用户要求收紧」。出参 `results[]` 直接用，`upsell` 是独立顶层字段（非成员且没搜够时才有，原样转述给用户即可，**不要**把它当候选）。
      推荐 3-5 首、**每首附试听链接**（结果的 `download_url`）；`audio_type:"pure"` 纯音乐直接用，`"song"` 直接取 `accompaniment_url` 现成伴奏（零处理成本，两档都有）；注意曲长 vs 成片时长（`duration` 字段）：`audio lay` **缺省循环叠满至工程末尾、尾段裁齐**（多 clip 首尾相接，命令会打 INFO 报段数），短曲只是**接缝多一些**、不会铺一半就静音（想少几道接缝，挑曲时加 `--min-duration <秒>`）；要单次铺请显式传 `--no-loop`；
    - **试听链接义务（MUST）**：音色与 BGM 的推荐没有试听链接=未完成推荐。
    - **BGM 落地一步（MUST，别留悬空 · ⟲ 2026-09-02 补）**：检索出参只给**签名 URL**，而 §五 ⑩ 的 `gtrk audio lay --file` **只收本地路径**（传 URL 必炸）——拍板之后、上轨之前，agent MUST 把选中曲**落成本地文件**。口径照解说链正本 `gtrk-narration` §五 原文对齐：`audio_type:"song"` **MUST 取 `accompaniment_url` 伴奏版上轨**、**MUST NOT 用 `download_url` 原曲**（人声与配音打架，260827 美食批踩坑）；`"pure"` 取 `download_url`。文件名按 **`bgm-<曲名>[-伴奏].<扩展名>`** 约定——跨片避让记账按**标题归一化键**匹配（剥 `bgm-` 前缀与 伴奏 / instrumental / off-vocal 后缀），命名不合规会让下一轮 `--exclude-recent` 避让失准。这一步不违反 §一 的下载禁令：那条禁令的射程只到二创源片 / 主体素材，平台授权素材的签名直链不在其内。

package/skills/gtrk-vlog-docu/SKILL.md

@@ -188,7 +188,7 @@ HKRR 四维（缺哪补哪）：
 3. **旁白稿 + 标题**：正文全文贴给用户（不是给路径），标注每段旁白挂在哪个位置；标题候选列出；
 4. **画幅**：横屏 B 站/西瓜=1920x1080，竖屏抖音=1080x1920。**素材几何与画幅不一致时明确提示**；
 5. **TTS 音色**：拉 catalog（`GET {apiBase}/task/tts/voices`，免鉴权）挑 2–4 个候选，**每个附试听链接**（`audition_url`）。⚠️ 纪实类的旁白与现场同期声会交替出现，**音色应贴近用户本人音色或明显区分**（避免观众困惑「这是谁在说」）——如用户本人出镜说话，优先建议同性别接近音色；
-6. **BGM 处置（双来源）**：用户自带 → 询问是否 `audio_separation` 取伴奏；未提供 → `gtrk matrix material "<按内容情绪写的检索词>" --scope audio --top-k 5 --diversity --json`，推荐 3–5 首**每首附试听链接**（`download_url`），`audio_type:"song"` 取 `accompaniment_url`。⚠️ 纪实类 BGM 要给同期声让路，音量口径同旅拍（-20dB）；
+6. **BGM 处置（双来源）**：用户自带 → 询问是否 `audio_separation` 取伴奏；未提供 → `gtrk matrix material "<按内容情绪写的检索词>" --scope audio --top-k 5 --diversity --json`，推荐 3–5 首**每首附试听链接**（`download_url`），`audio_type:"song"` 取 `accompaniment_url`。⚠️ **版权状态如实转述**：`is_copyright` 的语义是 `1/true`=**可商用**、`0/false`=**不可商用**（反直觉，MUST NOT 把 `false` 读成「无版权、可随便用」）；矩阵成员档**缺省搜全库**，MUST NOT 默认加 `--commercial-only`、也 MUST NOT 擅自剔掉 `false` 的候选，但推荐时 MUST 逐条带上派生位 `copyright_label` 的中文标签（不追问不阻塞）——用户特意说明只要可商用 / 要商用发布时才加 `--commercial-only` 收紧。⚠️ 纪实类 BGM 要给同期声让路，音量口径同旅拍（-20dB）；
 7. **字幕样式**：7 样式 × 11 色；用户没选用 default+雅黑（不追问不阻塞）。
 
 **试听链接义务（MUST）**：音色与 BGM 的推荐没有试听链接=未完成推荐。

package/skills/gtrk-voiceover/SKILL.md

@@ -33,6 +33,10 @@ description: 通用配音视频创作图纸（配音链快速成片预设）—
 ```bash
 # ①② 写稿（三段式通用框架层 + 文风铁律自校验）→ 检查点①拍板
 gtrk matrix material "<情绪 调性 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
+#   ⚠️ is_copyright：1/true=可商用、0/false=**不可商用**（反直觉，MUST NOT 读成「无版权、可随便用」）。
+#   ⟲ 260906 拍板：矩阵成员档**缺省搜全库**，MUST NOT 默认加 --commercial-only、也 MUST NOT 擅自剔掉
+#   false 的候选；对价是推荐时 MUST 逐条带上派生位 copyright_label 的中文标签（不追问不阻塞）。
+#   用户**特意说明**只要可商用 / 要商用发布 / 客户商单时，才加 --commercial-only 收紧。
 
 # ③ 配音 → 建工程
 gtrk tool audio_tts_clone --text-file <稿.txt> --speaker <voice_id> --json