@gitruck/cli 1.3.3 → 1.3.5

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

@@ -18,11 +18,11 @@ description: 音乐可视化成片——把一首歌通过同合云出成一条
 
 ## 一条命令
 
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
-> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
 > 成片等一切产物只落产物目录（缺省 = 音频同目录）或**用户显式指定的 `--out`**；
 > **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
-> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
+> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
 
 ```
 gtrk music-visualizer <音频> --template <模板id> [可选样式/文件] [--json]

package/skills/gtrk-narration/SKILL.md

@@ -37,17 +37,17 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 | ⑦ | **源片语种 / 方言** | **问用户**：听一段 / 看片内有无内嵌字幕 / 看素材出处 | `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）；素材通篇无对白答「无对白 / 不转写」即闭合，MUST NOT 因缺这个答案阻塞开工 |
 
 > ②③④⑤⑦ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。
-> **推荐面（公约 §三‴）**：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 `gtrk skills recommend --scene <id> --json`；用户拒绝后不执行推荐动作。
+> **推荐面（公约 §三‴）**：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 `gtrk skills recommend --scene <id> --json`；用户拒绝后不执行推荐动作。
 >
-> 语种必须在转写前确认。非中文素材传错语种会让检查点①拿到错误稿件并产生重复 ASR 成本；不要静默使用 `zh-CN`。粤语建议填写 `zh-HK` 作为元数据，当前 `--json` 路径按字级转写；无对白素材回答「无对白 / 不转写」即可。
+> 语种必须在转写前确认。非中文素材传错语种会让检查点①拿到错误稿件并产生重复 ASR 成本；不要静默使用 `zh-CN`。粤语建议填写 `zh-HK` 作为元数据，当前 `--json` 路径按字级转写；无对白素材回答「无对白 / 不转写」即可。
 >
 ## 三、时序铺排三档（本图纸的技术正本）
 
 每段叙述配什么画面，按下面三档路由，**高档优先**：
 
-> **⚠️ 甲档的适用范围**：
+> **⚠️ 甲档的适用范围**：
 > **整份手写 plan（免索引直排）降级为「引用段与硬出处段专用」**，叙述段缺省不再走它。
-> 手写 plan 缺少检索结果携带的质量信号，因此：
+> 手写 plan 缺少检索结果携带的质量信号，因此：
 >
 > | 信号 | 断在哪 | 后果 |
 > |---|---|---|
@@ -103,36 +103,36 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 > 两条独立，回执分别以 `has_cuts` / `fps` 报，`cut_snap` 三态再把「按你的标注主动不吸」
 > 与「素材没索引想吸也无从吸」分开。
 
-> **直写 plan 操作注记**：整份 plan 可以手写——甚至**不依赖本地索引**
+> **直写 plan 操作注记**：整份 plan 可以手写——甚至**不依赖本地索引**
 > （4K 长片索引很慢，甲档直排等不起也不必等）。逐 beat 一条 query、逐出处窗一条 result，
 > `segments:[{start,end,best,score}]`（源片秒）。三条铁则：① `best` 是**窗内代表帧时刻**
 > （秒），落窗外会被校验拒；lay 取段大致**以 best 为中心**——想 start 锚定就把 best 设为
-> 「窗起点 + 意图时长/2」；② 预算三量齐足——`per_shot_sec` 按「beat 时长 / 窗数」给、**窗宽 ≥ 份额**，长出处区间拆成多个子窗；③ 引用段窗与配音时轴**逐秒对齐**（窗起点 = 引用音频对应的
+> 「窗起点 + 意图时长/2」；② 预算三量齐足——`per_shot_sec` 按「beat 时长 / 窗数」给、**窗宽 ≥ 份额**，长出处区间拆成多个子窗；③ 引用段窗与配音时轴**逐秒对齐**（窗起点 = 引用音频对应的
 > 源时刻），铺后按 `clip_st 与 track_st 的差恒等` 复核零漂移；④ **口播基座下 beat 预算按
 > dispatch 的成片轴包络算**——`transcript.json` 的 st/ed 是源时码，且 beat 连续化会把句间
-> 停顿带并入下一 beat，窗预算不足会产生空洞；
-> ⑤ **beat 粒度以关键句为主，采用约七三的对齐与游离比例**。先认清机制：
+> 停顿带并入下一 beat，窗预算不足会产生空洞；
+> ⑤ **beat 粒度以关键句为主，采用约七三的对齐与游离比例**。先认清机制：
 > `matrix lay` 在 beat 内按候选分数贪心铺满、**槽序与句序无关**——一个 beat 跨多句时，
 > 只有「领衔句」能拿到为它挑的画面，其余句是跟随。由此定编排法（**顺序不可颠倒**）：
 > **①关键词卡点先行**：先挑出有明确视觉指涉的句子（实体/动作/可拍之物），逐句独立成 beat、
 > 一 beat 一窗，保证「稿说什么就给什么」。**划分判据是「素材里有没有」，不是「句子抽不抽象」**
-> ——素材里有对应画面的句子 MUST 卡点
+> ——素材里有对应画面的句子 MUST 卡点
 > （哪怕它夹在抽象段里，如「昨天的老汤兑进今天的新汤」有汤锅镜头就必须给汤锅）；素材里
 > 确实没有的才允许降为跟随（「卖过三十年汽车」片里无车、「多线程游戏」无从拍）。判据的
 > 落地取证=渲后 `gtrk qc --alignment`：**卡点句 mismatch MUST 收敛到 0，且每一条 mismatch
-> 都要先问「是我窗选错了，还是素材真没有」；②**其余填坑**：抽象句、数字句、修辞句、情绪句
+> 都要先问「是我窗选错了，还是素材真没有」；②**其余填坑**：抽象句、数字句、修辞句、情绪句
 > （日期/克数/"比太阳起得早"/"多线程游戏"）**没有对应画面可给**，合并进相邻关键句的
 > 长镜头当跟随，或用主题相近的群像长镜头覆盖；③**七三开收口**：约 70% 时长逐句对齐、
 > 30% 游离创造自然感——**游离不是妥协是设计**。
-> ⚠️ **不要追求 100% 逐句硬切**：对齐质检的靶子是「关键句零 mismatch」，其余句允许跟随；一个 beat 也不要跨太多关键句，以免集体错位。
-> ⑥ **盲选窗跨源镜头切点**——`direct_slots` 的直排槽同样会过窗口精修，`provenance` 段的端点会自动吸到切点。
+> ⚠️ **不要追求 100% 逐句硬切**：对齐质检的靶子是「关键句零 mismatch」，其余句允许跟随；一个 beat 也不要跨太多关键句，以免集体错位。
+> ⑥ **盲选窗跨源镜头切点**——`direct_slots` 的直排槽同样会过窗口精修，`provenance` 段的端点会自动吸到切点。
 > 仍会剩下两种情形，都要如实报账而不是靠重铺硬碰：
 > · **素材未索引**（无 `cuts`）⇒ 收缩无数据可用。先索引再铺是正解，等不起就照实说明。
 > · **`quote` 引用段** ⇒ 它按设计**不吸**（吸走就是画音错开）。若那一口确实横跨切换，
 >   那是内容本身如此，正确处置是改稿或改引用区间，不是让铺轨替你挪。
 > 渲后 QC 的 flash/intra_cut 证据仍可反算源切点（clip_st + into_clip_sec）供人工复核。
 
-### 甲′ · 出处窗内检索（叙述段缺省路）
+### 甲′ · 出处窗内检索（叙述段缺省路）
 
 **出处准与检索对齐可以兼得**，不必二选一：把出处区间当**检索域**而不是当**答案**。
 
@@ -173,7 +173,7 @@ QC 反算重铺）；② 段带 `cuts`，端点残片收缩生效；③ 段带 `
 - **切取用流拷贝**（`ffmpeg -c copy`，零重编码）；想让 AI 帮你海选可引用的高光，可先跑一遍 `gtrk long2short` 拿选段清单当候选（可选辅助，明示计费）。
 - **装配**：逐段 TTS + 引用段原声按稿序拼成总音频 → 合成 transcript（各段句级时码换算到拼接轴）→ `gtrk project init --audio <总音频> --transcript <合成转写>` 建工程（自备配音兜底路）；引用段画面 = 该源区间直排上轨。无引用段时装配退化为单条 TTS + `--tts-task` 主路（与旅拍同款）。
   **产物文件名别硬拼（fix-tool-outdir-collision）**：多段 TTS 落**同一个 `--out`** 时，第二段起的产物会带 taskId 后 6 位后缀（`tts-narrator-a1b2c3.wav`），基名只有第一份是干净的。拼接清单 MUST 按每次回执的 `files` 取路径，MUST NOT 按 `tts-<speaker>.wav` 猜——猜出来的名字会一路指向第一段，拼出来的总音频会把某一段重复多遍而不报错。
-  **主轨无缝铁则**：合成 transcript 里引用段 utterance 的 st/ed **MUST 写物理拼接位**（拼接轴上的真实起止），MUST NOT 加字幕 pad；已有 pad 的工程按「改时刻→重导视图→重落拆分→重铺→字幕重出」修复。
+  **主轨无缝铁则**：合成 transcript 里引用段 utterance 的 st/ed **MUST 写物理拼接位**（拼接轴上的真实起止），MUST NOT 加字幕 pad；已有 pad 的工程按「改时刻→重导视图→重落拆分→重铺→字幕重出」修复。
 - **克制丑话**：引用段是佐料——时长占比失衡会让片子变成搬运，平台判定风险归用户（§八 一并告知）。
 
 ## 五、快速成片编排
@@ -193,8 +193,8 @@ gtrk transcript "<长片>" --lang <开工⑦所答语种> --json   # 影视/游
 
 # ②③ 写稿（甲档出处共生 / 乙路对照表对齐）→ 检查点①拍板（§六）
 gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
-#   ⚠️ is_copyright 的权威语义是 1/true=可商用、0/false=**不可商用**，MUST NOT 把 false
-#   读成「无版权、可随便用」。矩阵成员档**缺省搜全库**，MUST NOT 默认加 --commercial-only、
+#   ⚠️ is_copyright 的权威语义是 1/true=可商用、0/false=**不可商用**，MUST NOT 把 false
+#   读成「无版权、可随便用」。矩阵成员档**缺省搜全库**，MUST NOT 默认加 --commercial-only、
 #   也 MUST NOT 以「保险起见」为由剔掉 is_copyright:false 的候选（全库正是成员身份买到的东西）。
 #   对价是**如实标注**：推荐时 MUST 逐条带上 copyright_label（派生位，中文标签），不可商用的照直说，
 #   但 MUST NOT 升级成追问或阻塞。用户**特意说明**只要可商用 / 要商用发布 / 客户商单时才加
@@ -217,7 +217,7 @@ gtrk matrix lay --project "<工程>" --mark-weight 0.3 --highlight-weight 0.2 --
 
 # ⑧⑨⑩ 字卡（MG 临场泛化，公约 §三）→ BGM（0.10 垫底、短了自动循环铺满）→ 字幕直出
 # BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
-# 不得用 download_url 原曲（人声与配音会打架）
+# 不得用 download_url 原曲（人声与配音会打架）
 gtrk mg --project "<工程>" --json
 # --beat-align 的高潮点取自 split.beats 的 narrative / container_stage（升华段 → 容器转折 → 回扣段）；
 # 拆分稿没带这两个字段 ⇒ 落 0.75×全片兜底档，**CLI 会明示那是猜的**。不接受就用 --climax <轨秒> 指定。
@@ -229,21 +229,21 @@ gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 > **停顿太长时**：自训音色加 `--fragment-interval 0.2`（合成时就对）；云引擎音色**不支持**该参数（传了会报错，不会静默忽略），改在合成后跑 `gtrk audio tighten --project <工程>` 收紧句间停顿（纯本地零计费；只压跨句界的停顿，句内换气与原声引用段不动）。
 
 配方口径（`--mark-weight 0.3`、BGM 0.10、`--gap-fill fast`、句界吸附缺省）与旅拍图纸 §五 同源，本图纸引用不复制。
-`--highlight-weight 0.2`：看点维度与 mark 正交——mark 判「好不好看」、highlight 判
+`--highlight-weight 0.2`：看点维度与 mark 正交——mark 判「好不好看」、highlight 判
 「有没有看点」（信息量/戏剧性/情绪强度/稀缺性）。看点准则按垂类走 L1 rubric（美食/旅拍图纸各持一份
 **画面投影版**）。两权之和 0.5，语义仍占一半——**MUST NOT 加到语义压不住的程度**，那会变成
 「专挑好看的，不管说的是什么」。
 ⚠️ 三个权重（mark/highlight）与 blurry 降权**全都依赖 `matrix describe --plan` 跑过**；
 没跑就是全部候选中性、排序与不开权重逐字节一致。
-质检按公约「三级收敛」执行：**L1 恒开**；**L2 落轨前**可用 `gtrk matrix lay --arrange-qc` 检查卡点句画音对齐；**L3 渲后终检**随本来就要交付的本地渲附带，不为质检单独逼渲。跑过的质检结论随交付分层呈现。
+质检按公约「三级收敛」执行：**L1 恒开**；**L2 落轨前**可用 `gtrk matrix lay --arrange-qc` 检查卡点句画音对齐；**L3 渲后终检**随本来就要交付的本地渲附带，不为质检单独逼渲。跑过的质检结论随交付分层呈现。
 
 ## 六、检查点①（拍板停一次；铺画面前另有一次用量确认）
 
-> 本地素材的编排缺省走云端并按编排量计费。`matrix lay` 跑前必须报告预估用量，取得同意后才能带 `--yes`；无 TTY 且未确认时整轮中止，工程不改动，plan 可重跑。
+> 本地素材的编排缺省走云端并按编排量计费。`matrix lay` 跑前必须报告预估用量，取得同意后才能带 `--yes`；无 TTY 且未确认时整轮中止，工程不改动，plan 可重跑。
 
 稿件（含引用窗口标注）+ **出处对照表**（乙路时；低置信段标出）+ 画幅 + 音色（附试听）+ BGM（附试听）+ 字幕样式（不挑走默认）——一屏给齐一次拍板。**未经确认 MUST NOT 发起 TTS/长剪短等计费动作。**
 
-## 六′、稿句↔镜头对照表（铺轨前必给）
+## 六′、稿句↔镜头对照表（铺轨前必给）
 
 候选选定、**铺轨动作发起之前**，把「哪句配哪个镜头、为什么是它」摊开给用户过目。
 出处对照表回答「这段稿从哪来」，本表回答「这段稿给什么画面」——两张表不互替。
@@ -261,7 +261,7 @@ gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 用户在这里改判的成本最低：他说「u0012 我记得片尾还有个更好的标牌镜头」，此时换窗重检索
 只花几秒；等铺完渲完再改，就是整轮返工。
 
-## 六″、验收判据
+## 六″、验收判据
 
 含 B-roll 覆盖的成片，验收 MUST 同时满足两条：
 
@@ -269,7 +269,7 @@ gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 2. **`gtrk qc --alignment` 的卡点句 mismatch = 0**。
 
 > ⚠️ **判据是 lead_mismatch 归零，不是全句对齐率冲 100。**
-> 全句率趋近 100% 往往意味着逐句硬切，可能让片子变碎。
+> 全句率趋近 100% 往往意味着逐句硬切，可能让片子变碎。
 > 全句 rate 只作参考量看趋势，**MUST NOT 当达标线**。
 >
 > 每一条 lead mismatch 都先问「**是我窗选错了，还是素材真没有**」：前者换窗重铺，

package/skills/gtrk-oralcut/SKILL.md

@@ -113,8 +113,8 @@ gtrk oralcut "<align 结果 JSON 的 output，即 *_extaudio.mp4>" [原有参数
 
 ## 执行（每次都带 `--json`）
 
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：交付物只写入工程目录或用户显式指定的输出路径；引用媒体用原路径，不复制到 agent 工作目录；临时文件放系统 temp，用完即删。
-> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：交付物只写入工程目录或用户显式指定的输出路径；引用媒体用原路径，不复制到 agent 工作目录；临时文件放系统 temp，用完即删。
+> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
 
 ```bash
 gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|concise|compact] [其它参数…] --json
@@ -154,6 +154,7 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 - **客户端**：在同合云桌面客户端（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-<时间戳>`，靠文件名 + 时间认出是哪一次剪辑、互不覆盖。
 
@@ -172,7 +173,7 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 
 ⚠️ **上面的词只是举例、不是白名单**——判据是「**用户表达了节奏/范围保留**」，换个说法照样得听懂。
 典型误判：「先智能剪口播 **然后我们逐步推进**」——用户说了「然后」，明确表示还要往下，
-**范围**逃生门逐字不成立；但**节奏**逃生门成立 ⇒ **SHALL 停**。不要因用户说「然后」就忽略明确的逐步推进要求。
+**范围**逃生门逐字不成立；但**节奏**逃生门成立 ⇒ **SHALL 停**。不要因用户说「然后」就忽略明确的逐步推进要求。
 
 停下时**必须交代下一步是什么、他说一声就继续**，别退化成事事请示。示范：
 「口播工程已就绪。按你说的逐步来，我先停在这。下一步是拆成 beat 级分镜派单，你说一声我就接着做。」
@@ -194,7 +195,7 @@ 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` 替你做恒等式同步 + 帧对齐 + 写前全档校验。
+`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。
 
 > 参数手册在 `AGENT.md` 的「元素级编辑：`gtrk patch`」一节与 README 命令参考。
 > 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。