@gitruck/cli 1.2.6 → 1.2.7

package/AGENT.md

@@ -132,6 +132,16 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
    - **不越过用户自装的 ffmpeg**：定位仍是 `--ffmpeg-path` → `~/.gitruck/ffmpeg` → 系统 PATH。
    - 字体落 `~/.gitruck/fonts`，经 `ass` 滤镜 `fontsdir` 供给——**不动用户的系统字体表**。
    - 平台未覆盖时（如 linux-arm64）会明确报错并指引手工安装，**不会错装其他架构的包**。
+
+6. **skill 新鲜度（agent 纪律 · fix-skill-install-staleness）**：随包 `/gtrk-*` skill 是
+   **装进去的那一刻的快照**，`npm i -g @gitruck/cli@latest` 升级 CLI **不会**刷新它们。
+   ⇒ **你正在读的这份 skill 有可能落后于当前 CLI 版本，而且落后时不会报任何错。**
+   需要 skill 的命令在检测到落后时会往 **stderr** 打一次提示并附修复命令；
+   见到它 **MUST** 转告用户跑 `gtrk skills install`（或 `gtrk upgrade`），
+   **MUST NOT** 当噪音忽略 —— 「照着旧口径继续干活」正是这条提示要防的事。
+   随时自查：`gtrk doctor` 里的「Skill 新鲜度」一行。判不出或一致时**零输出**，
+   所以没看到提示不等于装过（没装过 manifest 就不存在，doctor 会如实说判不出）。
+
 
 ---
 
@@ -225,7 +235,7 @@ gtrk oralcut-result 88269671080189958 --render --out "D:/回收/某条"
 
 ## 2.2 视觉拆分派单器：`gtrk split`（成片 → 分镜派单）
 
-`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 再现 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
+`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 情景动画 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
 
 编排顺序（脑=`gtrk-splitter` skill / 手=本命令）：
 

package/README.en.md

@@ -121,7 +121,7 @@ Lanes are laid **in order, with a checkpoint at every step**: first fill the B-r
         ↓                                               │
    gtrk matrix     按文稿铺 B-roll                       │
         ↓                                               │
-   AI 再现（可选）  外部平台出片 → 手动回铺               │
+   AI 情景动画（可选）  外部平台出片 → 手动回铺           │
         ↓                                               │
    客户端挑选      抽帧核构图 ← 底轨定稿前别往下走        │
         ↓                                               │
@@ -253,6 +253,17 @@ gtrk skills install --all
 gtrk skills install --copy
 ```
 
+> ⚠️ **Upgrading the CLI does not refresh the skills you already installed.**
+> `npm i -g @gitruck/cli@latest` swaps the CLI package only; the copy under each agent's directory is still
+> **the snapshot from your last install** — the agent keeps working from the stale wording, **and nothing errors out**.
+> Refresh with `gtrk upgrade` (CLI + skills) or run `gtrk skills install` on its own.
+>
+> Since **1.1.3** this is no longer silent: the skill-backed commands (`oralcut`, `long2short`, `split`,
+> `matrix`, `mg`, `subtitle`, `project`) print a one-off notice on **stderr** with the fix command when they
+> detect that the installed skills lag behind the package; when they match, or cannot be judged, output is
+> **empty**. Run `gtrk doctor` any time for the "Skill freshness" row, or set
+> `GTRK_SKILL_FRESHNESS=off` to silence the whole thing.
+
 `--agents` accepts agent IDs from both the upstream adapter and the gtrk supplement layer. Chinese agents already covered include `trae`, `trae-cn`, `codebuddy`, `qoder`, `qoder-cn`, `qwen-code`, `kimi-code-cli`, `iflow-cli`, `codearts-agent` and `lingma`, plus `workbuddy`, `qoderwork` and `comate` which upstream has not registered yet. Common shorthands — `qwen`, `kimi`, `iflow`, `codearts`, `tongyi-lingma`, `qoder-work`, `baidu-comate` — are mapped automatically. When upstream adds new agents, gtrk can use the new IDs without a release; if an existing script must hardcode a directory, `--dir <skills dir>` still gives you the compatible copy mode.
 
 **Agent input UIs are not standardized**: Claude usually surfaces skill names in `/` completion; different Codex clients enter via `$`, `/skills` or a Skills panel; TRAE relies mostly on Skills settings, explicit naming or semantic triggering. So not seeing a Claude-style `/gtrk-*` dropdown does not mean the skill is missing. If a new skill does not show up, refresh the window or start a new session.

package/README.md

@@ -120,7 +120,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
         ↓                                               │
    gtrk matrix     按文稿铺 B-roll                       │
         ↓                                               │
-   AI 再现（可选）  外部平台出片 → 手动回铺               │
+   AI 情景动画（可选）  外部平台出片 → 手动回铺           │
         ↓                                               │
    客户端挑选      抽帧核构图 ← 底轨定稿前别往下走        │
         ↓                                               │
@@ -134,7 +134,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
                      （或导出剪映草稿 / PR 工程）
 ```
 
-**记两件事就够**：① **底下的先铺、盖在上面的最后叠**——B-roll 与 AI 再现同属底轨画面（并列的两条腿），动态图（MG 主颗粒 + OV 透明叠层）是唯一的叠加层，底轨没定稿就叠等于白做；② 出片永远在客户端或你自己的剪辑软件里完成，CLI 只负责把料铺进工程。
+**记两件事就够**：① **底下的先铺、盖在上面的最后叠**——B-roll 与 AI 情景动画同属底轨画面（并列的两条腿），动态图（MG 主颗粒 + OV 透明叠层）是唯一的叠加层，底轨没定稿就叠等于白做；② 出片永远在客户端或你自己的剪辑软件里完成，CLI 只负责把料铺进工程。
 
 > 三条链各自的完整走法（含每步产物、常见问题）见使用教程的子页：**口播链**（短视频口播 / 人文社科杂谈）· **配音链**（电影解说 / 美食解说）· **长剪短**（播客 / 圆桌 / 脱口秀 / 访谈 / 直播回放）。
 
@@ -149,7 +149,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
 
 > **次序有理由**：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版是「因势象形避主体」、**依赖底轨的最终画面构图**，所以三源（影视 / 本地 / AI）必须全落齐、构图核过，才轮到 MG。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
 >
-> ⚠️ **旧版文档曾写「④ 铺 MG → ⑤ 最后上 AI 再现」，理由是「越往后叠得越上层」——那是把「工序次序」误当成了「图层次序」，已于 2026-08-17 纠正。** 若你装的是旧版 skill，`gtrk upgrade` 刷新后才是新序。
+> ⚠️ **旧版文档曾写「④ 铺 MG → ⑤ 最后上 AI 情景动画」，理由是「越往后叠得越上层」——那是把「工序次序」误当成了「图层次序」，已于 2026-08-17 纠正。** 若你装的是旧版 skill，`gtrk upgrade` 刷新后才是新序。
 >
 > **AI 出片是异步的**：外部平台抽卡可能数天，严格串行会把 ④⑤ 无限期卡住。故进 ⑤ 的门是「**AI 片段已回铺 ∨ 你明示先跳过**」；走跳过时 agent 会把与 AI 区间相邻/重叠的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述给你。
 >
@@ -190,10 +190,10 @@ CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再
 | **B-roll 候选挑选** | `gtrk matrix` 铺 N 条候选轨，用轨道**小眼睛**逐条切换对比、选定、删多余——审美取舍只能人在客户端做 |
 | **MG / 颗粒精修** | 客户端里 html-particle **活颗粒透明预览** + Transform/Blending/Effects 参数逐帧微调 |
 | **口播精剪** | 磁性主轨 ripple、手动微调切点 / 停顿 / 分屏 |
-| **AI 再现回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ③——它属底轨阶段，MG 要等它落位后才铺） |
+| **AI 情景动画回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ③——它属底轨阶段，MG 要等它落位后才铺） |
 | **最终出片** | 多车道合成（overlay / MG / particle 云渲叠起来）+ 剪映草稿导出，都在客户端出片链 |
 
-> **`gtrk render` 现在会合成叠加层了（1.1.10 起）。** 它按契约 z 序（`track_index` 升序）把**全部可见**的叠加层叠进成片——overlay 视频轨（B-roll 候选 / AI 再现回铺）与 MG 颗粒都在内；在客户端关了「小眼睛」（`hidden`）的轨不进片。
+> **`gtrk render` 现在会合成叠加层了（1.1.10 起）。** 它按契约 z 序（`track_index` 升序）把**全部可见**的叠加层叠进成片——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 MG 颗粒都在内；在客户端关了「小眼睛」（`hidden`）的轨不进片。
 >
 > **颗粒那一段有计费**：CLI 没有 HTML 渲染引擎，颗粒要送同合云烤成透明 MOV 再本地叠。计量 = **唯一颗粒数 × 未命中缓存数**（按分钟），未命中时会先出预估并要你确认（`--yes` 跳过；`--json` 下必须显式 `--yes`）。**第二次渲染全命中缓存 ⇒ 零计费**；缓存与客户端导出剪映时那份**同键同落点**（`<工程目录>/.tonghe-cache/particles/`），所以客户端烤过的颗粒 CLI 直接命中、反之亦然。不想花钱用 `--no-particles` 出无颗粒版（overlay 视频轨照常合成，那部分零计费、纯本地）。
 >
@@ -248,6 +248,15 @@ gtrk skills install --all
 gtrk skills install --copy
 ```
 
+> ⚠️ **升级 CLI 不会自动刷新已装的 skill。** `npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，
+> 各 Agent 目录下那份 skill 仍是**上次装进去的快照** —— agent 会照着旧口径干活，**而且不报错**。
+> 刷新走 `gtrk upgrade`（升 CLI + 刷 skill）或单独跑 `gtrk skills install`。
+>
+> 自 **1.1.3** 起这件事有信号了：需要 skill 的命令（`oralcut` / `long2short` / `split` / `matrix` /
+> `mg` / `subtitle` / `project`）在检测到本机 skill 落后时，会往 **stderr** 提示一次并给出修复命令；
+> 一致或判不出时**零输出**。随时自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」；
+> 嫌吵用环境变量 `GTRK_SKILL_FRESHNESS=off` 整块关掉。
+
 `--agents` 接受上游适配器和 gtrk 补充层的 Agent ID。国产 Agent 已覆盖 `trae`、`trae-cn`、`codebuddy`、`qoder`、`qoder-cn`、`qwen-code`、`kimi-code-cli`、`iflow-cli`、`codearts-agent`、`lingma`，并额外补充上游尚未登记的 `workbuddy`、`qoderwork`、`comate`。常见简写 `qwen`、`kimi`、`iflow`、`codearts`、`tongyi-lingma`、`qoder-work`、`baidu-comate` 也会自动映射。以后上游新增 Agent，gtrk 无须发版也能直接使用新 ID；已有脚本若必须写死一个目录，仍可用 `--dir <skills目录>` 走兼容复制模式。
 
 不同 Agent 的**输入 UI 不统一**：Claude 常把 skill 名放进 `/` 补全；Codex 的不同客户端可从 `$`、`/skills` 或 Skills 面板进入；TRAE 以 Skills 设置、显式点名或语义触发为主。因此没看到 Claude 风格的 `/gtrk-*` 下拉，不代表 skill 没安装。新 skill 没出现时，刷新窗口或新开会话。
@@ -287,7 +296,7 @@ gtrk skills install --copy
 > **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑤ 步（B-roll 三源全齐、构图核过才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
 > 上面 18 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，四者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
 
-**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 再现什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
+**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
 ---
 
@@ -305,7 +314,7 @@ gtrk skills install --copy
 - 栏目配置 `~/.gitruck/columns/<id>.json`（词表 vocab + B-roll 检索偏好 + style 引用清单）
 
 **【成片层 · 每片跑】= 做菜（流程形状不变）**
-剪口播 → 拆文稿 → 派单（B-roll 检索 / 动效 / 再现）→ 装配 → 渲染。每一步显式消费当前栏目配置：拆文稿按你的词表校验（`--column <id>` 或 config `defaultColumn`），B-roll 检索按你栏目的检索偏好（`broll.column_tag_ids` 栏目标签 / `material_class_policy` / facets），各车道走你自己的生产 skill。
+剪口播 → 拆文稿 → 派单（B-roll 检索 / 动效 / 情景动画）→ 装配 → 渲染。每一步显式消费当前栏目配置：拆文稿按你的词表校验（`--column <id>` 或 config `defaultColumn`），B-roll 检索按你栏目的检索偏好（`broll.column_tag_ids` 栏目标签 / `material_class_policy` / facets），各车道走你自己的生产 skill。
 
 **不建栏目？直接用默认"厨房"。** 零配置 = 内置默认栏目，端到端照常跑通，行为与配置化之前逐字节一致——栏目层是可选资产，不是必经关卡。
 
@@ -764,7 +773,7 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 把 `.gtrk` 当 EDL 用本地 ffmpeg 出成片。**素材一律取本地原片**（`materials[].path`），云端不产成片。
 
-**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 再现回铺）与 `beat_track` 的 MG 颗粒。
+**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。
 
 - **可见性只读 `hidden` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
 - **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。