@gitruck/cli 1.3.9 → 1.3.11

package/skills/gtrk-narration/SKILL.md

@@ -24,7 +24,7 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 
 ## 二、输入契约与开工七问
 
-**输入**：本地素材语料（素材夹，或单条长片——影视/游戏实况先建索引拆条）±稿件 ± 用户自己念的口播毛片。**MUST NOT 执行任何网络下载**（版权责任归用户）。
+**输入**：本地素材语料（素材夹，或单条长片——影视/游戏实况先建索引拆条）±稿件 ± 用户自己念的口播毛片。**MUST NOT 下载二创源片 / 主体素材**（版权责任归用户）。平台授权素材（素材矩阵的 BGM / 空镜）可按其签名直链落地；这条例外不适用于源片与主体画面素材。
 
 | # | 问 | 怎么取证 | 决定什么 |
 |---|---|---|---|
@@ -41,6 +41,7 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 > **推荐面（公约 §三‴）**：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 `gtrk skills recommend --scene <id> --json`；用户拒绝后不执行推荐动作。
 >
 > 语种必须在转写前确认。非中文素材传错语种会让检查点①拿到错误稿件并产生重复 ASR 成本；不要静默使用 `zh-CN`。粤语建议填写 `zh-HK` 作为元数据，当前 `--json` 路径按字级转写；无对白素材回答「无对白 / 不转写」即可。
+> **内容离机要在这张表里说清**：转写会把长片抽出的音轨上传同合云做云端语音识别（按时长计费）；建索引会上传 512px 抽帧图做向量化（即传即弃，视频本体不上云）。问⑦时一并告知，用户不愿音频上云就答「不转写」，台词锚改用字幕文件或画面。
 >
 ## 三、时序铺排三档（本图纸的技术正本）
 
@@ -297,6 +298,6 @@ gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 
 ## 九、计费与排错
 
-- 计费大头：TTS（按字数）与可选的 long2short 引用海选（按时长）；实时价格 CLI 自动打印，**原样转述**后再动。
+- 计费大头：TTS（按字数）与可选的 long2short 引用海选（按时长）；CLI 在提交前打印实时价格（long2short 另可先 `--dry-run --json` 零计费报价），**原样转述**后再动。
 - 索引/理解/本地检索按矩阵成员口径（多为免费或豁免），以运行时打印为准。
 - 排错：低置信对照段处理见 §三 乙；`6004`/上传类症状以 `gtrk-oralcut`、拼装路以 `gtrk project` 各自口径为准；其余零件症状回各零件 skill，本图纸不搬。

package/skills/gtrk-oralcut/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: gtrk-oralcut
 description: 智能口播剪辑闭环——开剪前主动检查同目录独立口播音频，有则先对轨换声，再通过同合云剪掉废话/重复/长停顿，产出客户端(gtrk)+剪映+PR 三方工程。当用户想「剪口播/剪个视频/智能剪辑/去掉废话和停顿/把这条口播剪一版/出剪映草稿/生成剪辑工程/oral cut」时使用本 skill。凡涉及把口播毛片做成可二次精修的剪辑工程，优先用本 skill 驱动 gtrk CLI，不要手搓 ffmpeg。
+metadata:
+  in_app_agent: true
 ---
 
 # 口播剪辑（gtrk-oralcut）
@@ -16,24 +18,22 @@ description: 智能口播剪辑闭环——开剪前主动检查同目录独立
 ## 前置：CLI 装没装 + 体检
 
 先跑 `gtrk doctor`（它顺带验证 `gtrk` 命令本身在不在）：
-- **`gtrk` 找不到 / command not found** → CLI 没装 → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
+- **`gtrk` 找不到 / command not found** → CLI 没装 → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js；外部 agent 的前置；内置 agent 已具备，跳过），再重试。
 - 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key + 剪映目录，**交互式、需真终端**，你别替他跑）。
 - 报云端连不上 / 剪映目录没配 → 照提示让用户处理。
 - 全绿就往下走。
 
-### ffmpeg 依赖（本地抽音频 / 渲染必需，缺了你来装）
+### ffmpeg 依赖（本地抽音频 / 渲染必需）
 
-oralcut 现在**本地预处理**（探原片几何 + 抽 16k 单声道 mp3 / 压 720p 代理）和 **本地渲染**都靠 `ffmpeg`/`ffprobe`。看 `gtrk doctor` 里「本地渲染 (ffmpeg)」这行：
+oralcut 现在**本地预处理**（探原片几何 + 抽 16k 单声道 mp3 / 压 720p 代理）和 **本地渲染**都靠 ffmpeg / ffprobe。看 `gtrk doctor` 里「本地渲染 (ffmpeg)」这行，或直接跑 `gtrk deps status`：
 
 - **已就绪** → 往下走。
-- **未找到** → 你来装（CLI 不自下不自分发）：**先确认确实没有**（doctor 已查过 `~/.gitruck/ffmpeg` 与系统 PATH），缺了再拉 `ffmpeg` + `ffprobe` 两个可执行文件放到 `~/.gitruck/ffmpeg/`（Windows 即 `ffmpeg.exe`/`ffprobe.exe`）。
-  - **国内用户优先国内加速站点**：GitHub 官方静态构建（BtbN / gyan.dev）直连慢，走 GitHub 加速代理（pass-through）或同合云自建镜像拉，下载后**核对 sha256**。
-  - 装好复跑 `gtrk doctor` 确认转绿。
+- **未找到** → `gtrk deps install --ffmpeg`（从同合云镜像装进 `~/.gitruck/ffmpeg/`，国内直连、自带校验，已存在则跳过），装好复跑 `gtrk deps status` 确认转绿。内置 agent 的运行时由客户端备好，不会走到这一步。
 - 用户自己装过 ffmpeg 并配了 PATH → doctor 会从系统探到直接用；**绝不去改用户的环境变量/PATH**（CLI 一律绝对路径调用）。若装在别处，用 `--ffmpeg-path <目录>` 指给它。
 
 ## 开剪前硬闸：主动发现独立口播音频，先对轨再 oralcut
 
-**无论用户有没有主动提到外录音频，执行 agent 都必须在第一次 `gtrk oralcut` 之前检查毛片所在目录。** 用户给的是目录时，先列出其中的视频与音频；用户给的是单个视频时，也要查看它的同目录。识别 `wav / mp3 / m4a / flac` 等独立音频，并按文件名、同一拍摄批次与数量关系判断是否是该视频的口播外录：
+**无论用户有没有主动提到外录音频，执行 agent 都必须在第一次 `gtrk oralcut` 之前检查毛片所在目录。** 用户给的是目录时，先跑 `gtrk media probe "<该目录>" --json` 列出其中的视频与音频（类别、时长、编码、有无音轨；只看这一层、纯本地零计费）；用户给的是单个视频时，对它所在的目录跑同一条。识别 `wav / mp3 / m4a / flac` 等独立音频，并按文件名、同一拍摄批次与数量关系判断是否是该视频的口播外录：
 
 - 唯一视频 + 唯一口播音频，或名称可明显配对（如 `03思考_视频_V01.mp4` ↔ `03思考_音频_V01.flac`）→ **直接视为一组，不用反问用户**。
 - 多个视频/音频且配对有歧义 → 在任何上传或 oralcut 计费前，让用户确认映射关系。
@@ -107,7 +107,7 @@ gtrk oralcut "<align 结果 JSON 的 output，即 *_extaudio.mp4>" [原有参数
 | `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 底层支持任意云端参数）。
+> **因势象形举例**：「教学口播、别删太狠、句号后多顿一下」→ `--preset steady --params-json '{"punctuation_breaks":{"。":0.7}}'`；「英文短视频卡点狠、顺便渲染成 mp4」→ `--lang en-US --preset compact --render`；「上次有句话没剪进去」→ `--visual-assist`。用户**自己点名**某参数+值 → 照他原样 `--param`/`--params-json` 透传（CLI 底层支持任意云端参数）。
 >
 > **以上就是你需要的全部参数——本 skill 自足，别去别处查**（`gtrk oralcut --help` 也随时列全部 flag）。官网另有一份面向开发者的原始 HTTP API 文档，那是给人看的，你不必也无法访问。
 
@@ -121,13 +121,16 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 ```
 
 - `--json`：人读日志走 stderr，**成功时 stdout 只有一行结果 JSON**：
-  `{ ok, outDir, files:{gtrk:[],jianying:[],xml:[]}, jianyingDraftPath, rendered, report, errors, taskId, fileId }`（`rendered`=本地渲染成片路径，未开 `--render` 时为 `null`）
+  `{ ok, outDir, files:{gtrk:[],jianying:[],xml:[]}, jianyingDraftPath, rendered, report, errors, taskId, fileId, pricing }`（`rendered`=本地渲染成片路径，未开 `--render` 时为 `null`）
+- **计费**：按上传物音频时长（≈毛片时长）计。CLI 在抽音频之前查一次实时价格，往 stderr 打一行「计费提示」（单价 + 本次预估积分），`--json` 结果的 `pricing` 里也有；给用户交代时**原样转述**，别自己报数字、别引用旧价。查不到时这一行是「实时价格暂不可用，以服务端结算为准」，照实说即可。
+- **想先报价再开跑**（用户问「要花多少」、长片要先确认）：同一条命令加 `--dry-run`，只探测并报价，零抽取、零上传、零计费、不建任何目录，`--json` 时 stdout 一行 `{ok, dry_run:true, source, duration, pricing}`。
 - **命令失败**（毛片路径错 / 鉴权失败 / 参数越界 6016 等）→ **进程非 0 退出、报错打到 stderr、stdout 无 JSON**。先看退出码，非 0 就把 stderr 的报错如实回给用户、别当成功。
 - 默认会自动打开产物目录（用户能直接看到文件）；纯脚本/无头环境才加 `--no-open`。
 - 云端处理是分钟级，耐心等命令返回。
 - **毛片 > 2 小时跑不了**：CLI 在上传前就会拦下（零抽取、零上传、零扣费），不是跑到一半才失败。
   遇到超长毛片**先分段再逐段剪**，切段用流拷贝、秒级完成、不重编码：
-  `ffmpeg -ss 0 -t 2400 -i "<毛片>" -c copy "<毛片名>_seg01.mp4"`（2400s = 40 分钟/段）。
+  `gtrk media cut "<毛片>" --start 0 --end 2400 --copy -o "<毛片名>_seg01.mp4"`（2400s = 40 分钟/段；下一段 `--start 2400 --end 4800`，依此类推；`-o` 与毛片同扩展名）。
+  起点按关键帧对齐，回执的 `seconds` 是实际时长：每段会从区间起点之前最近的关键帧开始，段与段之间有几秒重叠、不丢内容。
   各段各出一份工程，逐段精修互不影响。
 
 ## 跑完读报告、给用户交代、按需调整（因势象形的另一半）
@@ -152,19 +155,28 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 ## 回给用户（三端打开方式）
 
 - **客户端**：在同合云桌面客户端（OpenCut Gitruck Edition）里「打开工程」选 `files.gtrk[0]`（…/gtrk/project.gtrk）。
-- **剪映**：已自动落到剪映草稿目录（`jianyingDraftPath`），开剪映在项目列表里找**同名工程**即可。
+- **剪映**：已自动落到剪映草稿目录（`jianyingDraftPath`），开剪映在项目列表里找与 `jianyingDraftPath` 末级目录**同名**的草稿即可。
 - **PR/FCP**：Premiere 里「文件 > 导入」`files.xml[0]`（…/xml/premiere.xml）。
   同时提醒用户：若导入时弹出「链接媒体」框（素材被移动、改名，或路径在这台机器上无效），链接前先确认目标文件；勾着「自动重新链接其他媒体」时，Premiere 会按**文件名**在所选位置查找其余缺失素材并自动链上，链错也不提示——同合云素材多以编号命名，不同工程里同名文件很常见，链完要在项目面板「媒体路径」列逐条核对，拿不准就取消该选项、逐个链接。用户反馈 PR 里素材脱机时，先问素材是否移动过、路径在这台机器上是否有效；**MUST NOT** 建议勾「自动重新链接其他媒体」一把链完。
 
-产物目录名形如 `<毛片名>-video-project-<时间戳>`，靠文件名 + 时间认出是哪一次剪辑、互不覆盖。
+产物目录名形如 `<毛片名>-video-project-<时间戳>`，靠文件名 + 时间认出是哪一次剪辑。时间戳只精确到秒，同一目录下同名毛片同一秒再起一次（如 `clip0.mp4` 与 `clip0.mov` 并行）时，后到的那份追加 `-2`。剪映草稿根是所有毛片共用的一层目录，不同目录下的同名毛片（换卡后重复的 `C0001.MP4` 之类）同秒开剪也会撞名：后到的那份草稿改叫 `…-2`，原草稿不动。最终落点以 `outDir` 与 `jianyingDraftPath` 为准，别按名字去猜。
 
-## 下一步（自动接力，别停在交工）
+## 下一步（按请求范围决定接不接力）
 
-口播工程剪好只是成片一条龙的第一站。确认 `ok=true`、`files.gtrk[0]` 与 transcript 就绪后，**别停下等用户开口**——顺势接力到视觉拆分：触发 `/gtrk-splitter`（把这条工程 + transcript 拆成 beat 级分镜派单，agent 再跑 `gtrk split` 产 `dispatch.json`），驱动后续各车道生产+铺轨。一句话交代即推进：「口播工程已就绪，我接着把它拆成分镜派单」。
+口播工程剪好，可能就是用户要的全部，也可能只是成片一条龙的第一站。确认 `ok=true`、`files.gtrk[0]` 与 transcript 就绪后，**看用户这次要多少**：
+
+- **请求覆盖下游 → 顺势接力**：用户要成片、出片、完整包装、一条龙，或点名要 B-roll、字卡、BGM、字幕中的任一项；或这个会话里先前已说过「一路做到成片」。这时不追问「要不要继续」，直接触发 `/gtrk-splitter`（把这条工程 + transcript 拆成 beat 级分镜派单，agent 再跑 `gtrk split` 产 `dispatch.json`），驱动后续各车道生产+铺轨。一句话交代即推进：「口播工程已就绪，我接着把它拆成分镜派单」。
+- **窄请求或判不清 → 停在交工**：用户只要剪辑工程、剪映 / PR 草稿、去停顿去废话、剪一版；或只说「帮我剪个视频」，看不出要不要成片。这时交付三端打开方式后停下，**一句话交代下一步，不发问**。示范：「剪辑工程已就绪（三端打开方式见上）。要往成片做的话，下一步是拆成分镜派单，再配 B-roll、字卡、BGM 和字幕，你说一声我就接着做。」
+
+⚠️ **上面的说法只是举例、不是白名单**——判据是「**用户的请求覆盖不覆盖下游**」，换个说法照样得听懂。只要把剪好的口播渲染成 mp4（`--render`）不算覆盖下游，那是本 skill 自己的产物。**判不清按窄请求处理**，也不为此在开剪前先发问：误停只多一句话，用户说「继续」就接上；误接力会跑一串工具调用、往工程里写拆分稿与候选轨，回退还要清理。
+
+### 作为图纸的一步被调用时
+
+如果你是在按某张图纸（`/gtrk-talking-head` 等）跑粗剪这一步，剪完**交回图纸**：以图纸的停点与模式为准（口播链是 §四 检查点①，必停），本节的接力规则不适用，MUST NOT 自行接力到 `/gtrk-splitter`。
 
 ### 逃生门：两种信号都要认（范围 + 节奏）
 
-**用户表达了范围保留或节奏保留，就停在这一步、别自动接力。** 两者语义正交，认漏一个都会误冲：
+**请求覆盖下游时，用户若还表达了范围保留或节奏保留，就停在这一步、别自动接力。** 两者语义正交，认漏一个都会误冲：
 
 - **范围信号 = 走多远**（我只要这一个产物）：「只要这版剪辑工程」「先不往下」「暂不出片」。
 - **节奏信号 = 怎么走**（每步停等我）：**「逐步推进」**（这是本仓公约立法定名的正式模式名，
@@ -178,7 +190,7 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 停下时**必须交代下一步是什么、他说一声就继续**，别退化成事事请示。示范：
 「口播工程已就绪。按你说的逐步来，我先停在这。下一步是拆成 beat 级分镜派单，你说一声我就接着做。」
 
-**没有这两类信号时不改默认**：仍按上文自动接力，别问「要不要继续」。
+**请求覆盖下游、又没有这两类信号时，照旧自动接力**，别问「要不要继续」。
 
 > 原则：**agent 替用户跑 CLI / 接力 skill，用户只对话**——别让用户自己去终端敲下一条 gtrk 命令。