@gitruck/cli 1.1.5 → 1.1.7

package/skills/gtrk-music-visualizer/SKILL.md

@@ -1,94 +1,95 @@
----
-name: gtrk-music-visualizer
-description: 音乐可视化成片——把一首歌通过同合云出成一条频谱可视化视频（可选背景/封面 + 模板/配色样式）。当用户想「把这首歌做成可视化视频 / 音乐可视化 / 频谱视频 / 歌曲配画面出片 / music visualizer / 给歌配个动态封面视频」时使用本 skill。凡涉及把一段音频做成频谱可视化成片，优先用本 skill 驱动 gtrk CLI 的 `music-visualizer` 命令，不要手搓 ffmpeg。
----
-
-# 音乐可视化（gtrk-music-visualizer）
-
-把用户的一首歌，用 `gtrk` CLI 跑通「**主音频上传（+可选背景/封面各自上传）** → 云端出频谱可视化成片 → 拉回本地」，再把产物目录回给用户。**CLI 是手、你是脑。**
-
-> **本 skill 已含你需要的全部信息**（参数、取值、执行、排错），照它做即可。具体模板 id 与参数细节以云端 API 文档为准（本地不冻结模板列表）。
-
-## 前置：CLI 装没装 + 体检
-
-先跑 `gtrk doctor`：
-- **`gtrk` 找不到 / command not found** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
-- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key，交互式、需真终端，你别替他跑）。
-- 全绿就往下走。
-
-## 一条命令
-
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
-> 成片等一切产物只落产物目录（缺省 = 音频同目录）或**用户显式指定的 `--out`**；
-> **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
-> 临时文件一律放系统 temp 且**用完即删**（含中断 / 失败路径）。违者后果 = 用户系统盘被静默吃满（真机事故，非假设）。
-
-```
-gtrk music-visualizer <音频> --template <模板id> [可选样式/文件] [--json]
-```
-
-- `<音频>`：本地音频文件（mp3/wav/m4a/aac/flac/ogg/wma 等）。按其时长计费。
-- `--template <id>`：**必填**。可视化模板 id（如 `aurora`）。取值以云端 API 文档 / 服务端模板列表为准；用户没指定就问他要，或让他去文档挑一个。传错服务端会报错并列出可选集。
-
-### 可选辅助文件（各自独立上传）
-- `--background <图或视频>`：背景素材，接受图片或视频。
-- `--cover <图>`：封面图，**仅接受图片**。
-
-### 可选样式参数
-- `--track <曲名>` / `--artist <歌手>`：叠加到画面的文字。
-- `--resolution <WxH>`：输出分辨率，如 `1080x1920`（竖屏）、`1920x1080`（横屏）。缺省走服务端默认 1920x1080。
-- `--fps <30-60>`：帧率，缺省 30。
-- `--c1 <hex>`：频谱主色，十六进制如 `#ff0066`。缺省白色。
-- `--c2 <hex>`：频谱**第二色**——**给了它才是双色渐变**，不给就是 `--c1` 单色。想要炫一点的渐变频谱就配上 `--c2`。
-- `--blur <0-40>`：背景模糊强度，缺省 16。
-
-### 通用
-- `--out <dir>`：产物目录（缺省 = 音频同目录下带时间戳的子目录）。
-- `--param k=v` / `--params-json '{...}'`：透传任意云端参数（覆盖优先级最高）。
-- `--json`：机读模式，stdout 只出结果 JSON。
-- `--reupload`：强制重新上传，忽略缓存。
-
-## 常见用法
-
-- 最简：`gtrk music-visualizer ./song.mp3 --template aurora`
-- 竖屏 + 双色渐变 + 叠字：`gtrk music-visualizer ./song.mp3 --template aurora --resolution 1080x1920 --c1 #ff0066 --c2 #6600ff --track 夜曲 --artist 周杰伦`
-- 带自定义背景 + 封面：`gtrk music-visualizer ./song.mp3 --template aurora --background ./bg.jpg --cover ./cover.png`
-
-## 配色引导（你帮用户想清楚）
-
-- 用户只说「配色炫一点 / 渐变」→ 给 `--c1` + `--c2` 两个色（双色渐变）。
-- 用户说「纯色 / 简洁」→ 只给 `--c1`。
-- 拿不准具体 hex：给常见搭配建议（如霓虹粉紫 `#ff0066`→`#6600ff`、青蓝 `#00e5ff`→`#0066ff`），或让用户给个大概色系你转 hex。
-- hex 必须是 `#RRGGBB` 或 `#RGB`；写错命令会在提交前报错。
-
-## 读产物
-
-完成后产物目录里有：
-- `<音频名>-visualizer.mp4`：成片。
-- `result.json`：`ok`/`files`/`taskId`；`ok=false` 时看 `errors`，可凭 `task.json` 的 `taskId` 稍后恢复，别急着重跑（重跑会重新计费）。
-
-## 排错
-
-- **缺 `--template`**：必填，问用户要模板 id 或让他查云端 API 文档的模板列表。
-- **模板 id 报错**：服务端会列出可选集，照着改。
-- **`--cover` 报「仅接受图片」**：封面只能是图片；视频素材放 `--background`。
-- **样式参数报错**：`--fps` 30-60、`--blur` 0-40、`--resolution` 必须 `宽x高`、`--c1/--c2` 必须十六进制——按报错提示改。
-- **产物下载失败（ok=false）**：网络波动或链接过期；凭 `taskId` 恢复，不整条重跑。
-
----
-
-## 改工程：走 `gtrk patch`，不要裸手改 JSON
-
-跑完之后要**微调某个片段**（挪位置 / 改时长 / 切开 / 改音量）时，一律用 `gtrk patch`：
-
-```bash
-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 命令参考。
-> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。
+---
+name: gtrk-music-visualizer
+description: 音乐可视化成片——把一首歌通过同合云出成一条频谱可视化视频（可选背景/封面 + 模板/配色样式）。当用户想「把这首歌做成可视化视频 / 音乐可视化 / 频谱视频 / 歌曲配画面出片 / music visualizer / 给歌配个动态封面视频」时使用本 skill。凡涉及把一段音频做成频谱可视化成片，优先用本 skill 驱动 gtrk CLI 的 `music-visualizer` 命令，不要手搓 ffmpeg。
+---
+
+# 音乐可视化（gtrk-music-visualizer）
+
+把用户的一首歌，用 `gtrk` CLI 跑通「**主音频上传（+可选背景/封面各自上传）** → 云端出频谱可视化成片 → 拉回本地」，再把产物目录回给用户。**CLI 是手、你是脑。**
+
+> **本 skill 已含你需要的全部信息**（参数、取值、执行、排错），照它做即可。具体模板 id 与参数细节以云端 API 文档为准（本地不冻结模板列表）。
+
+## 前置：CLI 装没装 + 体检
+
+先跑 `gtrk doctor`：
+- **`gtrk` 找不到 / command not found** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
+- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key，交互式、需真终端，你别替他跑）。
+- 全绿就往下走。
+
+## 一条命令
+
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 成片等一切产物只落产物目录（缺省 = 音频同目录）或**用户显式指定的 `--out`**；
+> **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
+> 临时文件一律放系统 temp 且**用完即删**（含中断 / 失败路径）。违者后果 = 用户系统盘被静默吃满（真机事故，非假设）。
+> 交付物（颗粒 HTML / 工程文件 / 派单稿 / 文稿等）SHALL **直接以工程目录内的最终路径为写入路径**，MUST NOT 先写 agent 自有工作目录再拷进工程——**中转本身即违规**，不以「最后拷进去了」免责，**体积不是豁免理由**（2026-09-07 事故里漂掉的是 2.7–6.2 KB 的 HTML）。与上一条的分界：抽帧图这类**不交付**的中间物走系统 temp；**要交付的东西没有暂存态**。
+
+```
+gtrk music-visualizer <音频> --template <模板id> [可选样式/文件] [--json]
+```
+
+- `<音频>`：本地音频文件（mp3/wav/m4a/aac/flac/ogg/wma 等）。按其时长计费。
+- `--template <id>`：**必填**。可视化模板 id（如 `aurora`）。取值以云端 API 文档 / 服务端模板列表为准；用户没指定就问他要，或让他去文档挑一个。传错服务端会报错并列出可选集。
+
+### 可选辅助文件（各自独立上传）
+- `--background <图或视频>`：背景素材，接受图片或视频。
+- `--cover <图>`：封面图，**仅接受图片**。
+
+### 可选样式参数
+- `--track <曲名>` / `--artist <歌手>`：叠加到画面的文字。
+- `--resolution <WxH>`：输出分辨率，如 `1080x1920`（竖屏）、`1920x1080`（横屏）。缺省走服务端默认 1920x1080。
+- `--fps <30-60>`：帧率，缺省 30。
+- `--c1 <hex>`：频谱主色，十六进制如 `#ff0066`。缺省白色。
+- `--c2 <hex>`：频谱**第二色**——**给了它才是双色渐变**，不给就是 `--c1` 单色。想要炫一点的渐变频谱就配上 `--c2`。
+- `--blur <0-40>`：背景模糊强度，缺省 16。
+
+### 通用
+- `--out <dir>`：产物目录（缺省 = 音频同目录下带时间戳的子目录）。
+- `--param k=v` / `--params-json '{...}'`：透传任意云端参数（覆盖优先级最高）。
+- `--json`：机读模式，stdout 只出结果 JSON。
+- `--reupload`：强制重新上传，忽略缓存。
+
+## 常见用法
+
+- 最简：`gtrk music-visualizer ./song.mp3 --template aurora`
+- 竖屏 + 双色渐变 + 叠字：`gtrk music-visualizer ./song.mp3 --template aurora --resolution 1080x1920 --c1 #ff0066 --c2 #6600ff --track 夜曲 --artist 周杰伦`
+- 带自定义背景 + 封面：`gtrk music-visualizer ./song.mp3 --template aurora --background ./bg.jpg --cover ./cover.png`
+
+## 配色引导（你帮用户想清楚）
+
+- 用户只说「配色炫一点 / 渐变」→ 给 `--c1` + `--c2` 两个色（双色渐变）。
+- 用户说「纯色 / 简洁」→ 只给 `--c1`。
+- 拿不准具体 hex：给常见搭配建议（如霓虹粉紫 `#ff0066`→`#6600ff`、青蓝 `#00e5ff`→`#0066ff`），或让用户给个大概色系你转 hex。
+- hex 必须是 `#RRGGBB` 或 `#RGB`；写错命令会在提交前报错。
+
+## 读产物
+
+完成后产物目录里有：
+- `<音频名>-visualizer.mp4`：成片。
+- `result.json`：`ok`/`files`/`taskId`；`ok=false` 时看 `errors`，可凭 `task.json` 的 `taskId` 稍后恢复，别急着重跑（重跑会重新计费）。
+
+## 排错
+
+- **缺 `--template`**：必填，问用户要模板 id 或让他查云端 API 文档的模板列表。
+- **模板 id 报错**：服务端会列出可选集，照着改。
+- **`--cover` 报「仅接受图片」**：封面只能是图片；视频素材放 `--background`。
+- **样式参数报错**：`--fps` 30-60、`--blur` 0-40、`--resolution` 必须 `宽x高`、`--c1/--c2` 必须十六进制——按报错提示改。
+- **产物下载失败（ok=false）**：网络波动或链接过期；凭 `taskId` 恢复，不整条重跑。
+
+---
+
+## 改工程：走 `gtrk patch`，不要裸手改 JSON
+
+跑完之后要**微调某个片段**（挪位置 / 改时长 / 切开 / 改音量）时，一律用 `gtrk patch`：
+
+```bash
+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 命令参考。
+> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。

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,33 +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 <目录>` 指给它。
-
-## 开剪前硬闸：主动发现独立口播音频，先对轨再 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。
-
-## 把用户的话变成一次调用
+- 用户自己装过 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），你才能解析结果 + 读报告。不是可选项。
 
@@ -117,6 +117,7 @@ gtrk oralcut "<align 结果 JSON 的 output，即 *_extaudio.mp4>" [原有参数
 > 一切产物（成片 / 预览 / 代理 / 素材 / 工程文件）只落**工程目录**或**用户显式指定的输出路径**；
 > **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
 > 临时文件一律放系统 temp 且**用完即删**（含中断 / 失败路径）。违者后果 = 用户系统盘被静默吃满（真机事故，非假设）。
+> 交付物（颗粒 HTML / 工程文件 / 派单稿 / 文稿等）SHALL **直接以工程目录内的最终路径为写入路径**，MUST NOT 先写 agent 自有工作目录再拷进工程——**中转本身即违规**，不以「最后拷进去了」免责，**体积不是豁免理由**（2026-09-07 事故里漂掉的是 2.7–6.2 KB 的 HTML）。与上一条的分界：抽帧图这类**不交付**的中间物走系统 temp；**要交付的东西没有暂存态**。
 
 ```bash
 gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|concise|compact] [其它参数…] --json