@gitruck/cli 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitruck/cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
   "license": "MIT",
   "author": "Gitruck (同合云)",

package/skills/gtrk-matrix/SKILL.md

@@ -25,6 +25,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 ## 配方库 v1（起手式，可变奏可自创）
 
 > 配方前置都一样：能跑 `gtrk` CLI；本地素材类配方先 `gtrk matrix index --dirs <素材夹>` 建索引。每条命令都带 `--json`。
+> ⚠️ **路径里有英文半角逗号**（`Bears, Salmon and Adventure` 这种）时 `--dirs` / `--materials` MUST **重复传**（`--dirs "A" --dirs "B"`，累加不覆盖），别塞进一串里 —— 缺省按半角逗号分隔。整串在盘上存在时会自动不拆，中文全角「，」从不参与拆分。
 
 ### 配方 A · 纯匹配铺轨（默认主路）
 
@@ -427,6 +428,8 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 | 只想先看清单不铺轨 | `--lay 0`（只产 plan）；之后铺 = `matrix lay`（不重新检索、不重新烧配额） |
 | **报「候选轨已被你编辑过」拒铺** | 保护不是故障：工程零改动，plan 照常产出。① opencut 处置那条轨后重跑；② 用户明确点头 → `--force-relay`（raw 登记删除不可恢复，先说后果） |
 | **`matrix lay` 报「plan 校验未通过」** | 你把不可编辑面改坏了（报错逐条指名字段）：按 §plan 编辑口径改回来重跑；`local_path 路径无效` 多半是可移动盘没挂载或真把路径改了 |
+| **describe 明明跑过、这轮又扣费** | 多半是**服务端判据升级**：`describes` 缓存键并入判据版本（`DESCRIBE_CRITERIA_VERSION`），旧口径条目在新版本下不算命中，会重跑重计费。`--json` 的 `cached_stale_criteria` 就是这一栏的张数（是 `called` 的子集，不是额外开销）。旧产物不删、仍可读。**属预期，不是缺陷** |
+| **`matrix index` 报 `0/0`（一个素材都没枚举到）** | 先看两件事：① `--dirs` 的路径里有没有**英文半角逗号**——有就改成重复传（见文首前置）；② 素材夹里有没有**断链**（失效软链接）。两条都不是再查路径本身对不对 |
 | 报「本地索引不存在」 | 先 `gtrk matrix index --dirs <...>`；已建过则查 `--dirs` 与建索引目录是否一致、可移动盘是否挂载 |
 | 换电脑用不了索引 | 索引跨机不可移植（本机缓存），新机重跑 `matrix index` 即可 |
 | 预览看不了 / 想「重签」 | 别为此重跑铺轨：`preview_url`/`cover_url` 不带签名不过期；带签名 24h 过期的是原片 `url`——工程内走客户端「确认原片」重签；**脱离工程要原片落本地走 `gtrk matrix fetch <clip_id...>`（免费重签+下载，见「精剪补素材」节）** |

package/skills/gtrk-narration/SKILL.md

@@ -207,6 +207,9 @@ QC 反算重铺）；② 段带 `cuts`，端点残片收缩生效；③ 段带 `
 # ① 索引前置（第一步就起，不是可选项——它是质量信号的载体，见 §三 代价表）
 #    4K 长片索引慢，未提速期**与写稿/TTS/检查点①并行跑**，别串行干等
 gtrk matrix index --dirs "<这一部片的绝对路径>" &     # 后台起，写稿同时跑（索引侧同口径：也钉单片）
+#   ⚠️ **后台起就看不见失败**：全域零枚举现在是**硬失败**（退出码 1），而 `&` 把它吞了 ——
+#     回头 MUST 看那一行的 `materials.total` 与 `per_dir`，别等到检索阶段才发现索引是空的。
+#     报 0/0 先看两件事：路径里有没有**英文半角逗号**（有就把 --dirs 重复传，别塞一串）、素材夹里有没有断链。
 gtrk transcript "<长片>" --lang <开工⑦所答语种> --json   # 影视/游戏类：台词与时码双锚（可选）
 #   ↑ 语种取开工⑦所答，MUST NOT 拿缺省顶上去 —— 但「传错就白花钱」只在**非中文**这一档成立；
 #     粤语 SHOULD 如实填 zh-HK（元数据诚实 + 备链路切换），当前链路下对粤语无差别：
@@ -242,6 +245,9 @@ gtrk matrix lay --project "<工程>" --mark-weight 0.3 --highlight-weight 0.2 --
 # BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
 # 不得用 download_url 原曲（人声与配音打架，260827 美食批踩坑）
 gtrk mg --project "<工程>" --json
+# --beat-align 的高潮点取自 split.beats 的 narrative / container_stage（升华段 → 容器转折 → 回扣段）；
+# 拆分稿没带这两个字段 ⇒ 落 0.75×全片兜底档，**CLI 会明示那是猜的**。不接受就用 --climax <轨秒> 指定。
+# 两侧都够长时零平铺（恰好 1 个 clip）；不够长才按小节线平铺补齐、接缝吸附 downbeat。
 gtrk audio lay --project "<工程>" --file "<bgm>" --volume 0.1 --beat-align --json
 gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 ```

package/skills/gtrk-tools/SKILL.md

@@ -19,13 +19,13 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `image_matting` | 「给图片抠像 / 抠出主体 / 去背景 / 出透明 png」 | 单张图片 | 透明背景 png | 运行前实时查询 | 已上线 |
 | `image_blackborder_remove` | 「图片去黑边 / 裁掉四周黑边 / 保留有效画面」 | 单张本地图片 | 去黑边图片 | 运行前实时查询 | 已上线 |
 | `image_canvas_adapt` | 「图片比例转换 / 调整画布尺寸 / 转成矩形或方形裁剪」 | 单张本地图片；模式只支持 `normal` / `rectangle` / `square` | 比例适配图片 | 运行前实时查询 | 已上线 |
-| `image_purify` | 「清理我有权处理的图片水印 / 去掉 Logo 或叠加元素 / 图片净化」 | 单张本地图片（仅处理你有权处理的素材） | 净化图片 | 运行前实时查询 | 已上线 |
+| `image_purify` | 「清理我有权处理的图片水印 / 去掉 Logo 或叠加元素 / 图片净化 / 按我圈的框去掉台标」 | 单张本地图片（仅处理你有权处理的素材）；可选按框直接去除 | 净化图片 | 运行前实时查询 | 已上线 |
 | `video_matting` | 「视频抠像 / 视频去背景 / 出透明背景视频」 | 单条视频（≤10 分钟） | 透明背景 webm | 运行前实时查询 | 已上线 |
 | `video_blackborder_remove` | 「视频去黑边 / 裁掉视频四周黑边 / 保留有效画面」 | 单条本地视频 | 去黑边视频 | 运行前实时查询 | 已上线 |
 | `video_canvas_adapt` | 「视频比例转换 / 横竖屏适配 / 截取片段并转换画布」 | 单条本地视频；模式只支持 `normal` / `rectangle` / `square` | 比例适配视频 | 运行前实时查询 | 已上线 |
 | `video_stabilizer` | 「视频防抖 / 稳定手持画面 / 去抖」 | 单条本地视频；方式 `fast` / `exp` / `turbo` | 防抖视频 | 运行前实时查询 | 已上线 |
 | `video_vaporwave` | 「给视频加蒸汽波滤镜 / 复古滤镜 / 使用某个滤镜预设」 | 单条本地视频；滤镜名需精确 | 蒸汽波滤镜视频 | 运行前实时查询 | 已上线 |
-| `video_purify` | 「清理我有权处理的视频水印 / 去字幕 / 只净化指定区域」 | 单条本地视频（仅处理你有权处理的素材）；可选范围、方式和归一化 ROI | 一条净化视频 | 运行前实时查询 | 已上线 |
+| `video_purify` | 「清理我有权处理的视频水印 / 去字幕 / 只净化指定区域 / 只抹我圈的这块 / 只抹片头几秒的角标」 | 单条本地视频（仅处理你有权处理的素材）；可选范围、方式、归一化 ROI 和带时间段的区域框 | 一条净化视频 | 运行前实时查询 | 已上线 |
 | `video_upscale` | 「视频超分 / 低清视频放大 / 动漫视频变清晰」 | 单条本地视频（≤1 分钟）；倍数 `2` / `3` / `4`，类型 `Reality` / `Anime` | 一条超分视频 | 运行前实时查询 | 已上线 |
 | `video_interpolate` | 「视频补帧 / 提高帧率 / 让画面更流畅」 | 单条本地视频；倍数 `2` / `3` / `4`，不附加 1 分钟限制 | 一条插帧视频 | 运行前实时查询 | 已上线 |
 | `video_segment` | 「机械分镜 / 按画面变动切分镜区间 / 场景切分」 | 单条本地视频；可选 `--detector content\|adaptive`、`--threshold` | 分镜区间结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
@@ -135,6 +135,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 - 视频防抖：`gtrk tool video_stabilizer ./clip.mp4 --stabilizer-method turbo --json`。支持 `fast`、`exp`、`turbo`；未传时由服务端使用 `turbo`，`exp` 只按实验方式转述，不承诺观感。
 - 蒸汽波滤镜：`gtrk tool video_vaporwave ./clip.mp4 --vaporwave-filter "灼熱苦夏" --json`。滤镜名原样精确传递，不翻译、不猜别名；未传时 CLI 明确使用 `愈漸升溫`。
 - 视频净化：`gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method ffmpeg --purify-roi 0,0.78,1,0.2 --json`。ROI 是 `x,y,w,h` 归一化坐标，只能和 `custom` 同用；`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用这个上限。只处理用户有权修改的素材，不宣称能还原被遮挡的原始内容。
+- 按框直接去除：`gtrk tool video_purify ./clip.mp4 --purify-scope region --purify-region 0.8,0.02,0.18,0.08,0,5 --json`（图片把工具换成 `image_purify`、框只写 `x,y,w,h`）。`--purify-region` 可重复，最多 16 个框，视频框后可带 `start,end` 秒。`custom` 只去除框内识别到的文字；`region` 不做识别、**框内全部内容都会被处理（包括画面主体）**——用户要去的是图形台标、半透明图案或只在某段时间出现的角标时选 `region`，并提醒框越小越贴边效果越好。
 - 视频超分：`gtrk tool video_upscale ./clip.mp4 --upscale-times 3 --upscale-type Anime --json`。输入最多 60 秒，放大后任一边超过 4000 px 会由服务端拒绝；这是实验性增强，不能承诺主观画质一定提升。
 - 视频插帧：`gtrk tool video_interpolate ./clip.mp4 --interpolate-multiplier 3 --json`。支持 `2`、`3`、`4`，不套用旧总览里的 1 分钟限制；原视频任一边超过 4000 px 时由服务端拒绝。
 

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

@@ -244,6 +244,10 @@ gtrk transcript "<原片>" --lang <zh-CN 普通话 | zh-HK 粤语 | en-US | ja-J
 #   ↑ **MUST NOT 以「粤语语种传错」为由重跑转写**：la 进 ASR 缓存键（asr_result_cache.py:71-75），
 #     换码必然 cache miss，白扣一次时长换回逐字段相同的请求与同一份结果。
 # 原创场景改跑：gtrk matrix index --dirs "<素材夹>" && gtrk matrix describe --materials ...
+#   ↑ **这个 `&&` 现在真的会拦住**：全域零枚举（一个素材都没枚举到）是**硬失败**（退出码 1），
+#     `describe` 不会执行 —— 这是改对了：以前 index 报 0/0 也 exit 0，`describe` 会对着空清单空跑一趟。
+#     报 0/0 先看两件事：路径里有没有**英文半角逗号**（有就把 --dirs 重复传 `--dirs "A" --dirs "B"`，累加不覆盖）、
+#     素材夹里有没有断链。⚠️ 「个别素材处理失败」不算硬失败（那是既有 failed 计数口径，退出码仍 0）。
 #   ↑ 原创（自拍素材集）这一档**整夹即该片素材域，传夹正确**，不受 ⑦ 那条「钉单片」铁则约束——
 #     那条治的是二创：一个夹里躺着几条互不相干的片，才会互相抢候选
 
@@ -307,6 +311,9 @@ gtrk mg --project "<工程目录>" --json
 # BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
 # 不得用 download_url 原曲（人声与配音打架，260827 美食批踩坑）；"pure" 取 download_url。
 # 文件名 bgm-<曲名>[-伴奏].<扩展名>：跨片避让按**标题归一化键**记账（剥 bgm- 前缀与伴奏/instrumental/off-vocal 后缀），乱命名=下一轮 --exclude-recent 失准
+# --beat-align 的高潮点取自 split.beats 的 narrative / container_stage（升华段 → 容器转折 → 回扣段）；
+# 拆分稿没带这两个字段 ⇒ 落 0.75×全片兜底档，**CLI 会明示那是猜的**。不接受就用 --climax <轨秒> 指定。
+# 两侧都够长时零平铺（恰好 1 个 clip）；不够长才按小节线平铺补齐、接缝吸附 downbeat。
 gtrk audio lay --project "<工程目录>" --file "<bgm>" --volume 0.1 --beat-align --json
 
 # ⑪ 字幕（样式/颜色 = 检查点①拍板值；用户没选用 default/雅黑；零计费——拆行走云端 subtitle_line_split 0 积分留痕，离线可加 --offline 用本地拆窗、重跑幂等替换）

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

@@ -240,6 +240,9 @@ gtrk mg lint "<工程目录>/mg/<composition_id>.html" --dispatch "<工程目录
 gtrk mg --project "<工程目录>" --json
 
 # ⑪ BGM（-20dB = 线性 0.10）
+# --beat-align 的高潮点取自 split.beats 的 narrative / container_stage（升华段 → 容器转折 → 回扣段）；
+# 拆分稿没带这两个字段 ⇒ 落 0.75×全片兜底档，**CLI 会明示那是猜的**。不接受就用 --climax <轨秒> 指定。
+# 两侧都够长时零平铺（恰好 1 个 clip）；不够长才按小节线平铺补齐、接缝吸附 downbeat。
 gtrk audio lay --project "<工程目录>" --file "<bgm>" --volume 0.1 --beat-align --json
 
 # ⑫ 字幕

package/skills/gtrk-voiceover/SKILL.md

@@ -52,6 +52,9 @@ gtrk matrix lay --project "<工程>" --mark-weight 0.3 --gap-fill fast --json
 
 # ⑤⑥⑦ 字卡 → BGM → 字幕
 gtrk mg --project "<工程>" --json
+# --beat-align 的高潮点取自 split.beats 的 narrative / container_stage（升华段 → 容器转折 → 回扣段）；
+# 拆分稿没带这两个字段 ⇒ 落 0.75×全片兜底档，**CLI 会明示那是猜的**。不接受就用 --climax <轨秒> 指定。
+# 两侧都够长时零平铺（恰好 1 个 clip）；不够长才按小节线平铺补齐、接缝吸附 downbeat。
 gtrk audio lay --project "<工程>" --file "<bgm>" --volume 0.1 --beat-align --json
 gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 ```