@gitruck/cli 1.2.6 → 1.2.8

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/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## 未发布
 
+### 加：视频译制配音 `video_translate_dub`（link-video-translate-dub-cli）
+
+`gtrk tool video_translate_dub <视频或音频> --language <源语种> --translate-language <目标语种> --speaker <clone 或音色代号>`：
+把原片里的话翻译成目标语种，用所选音色或克隆原片说话人的声音逐句重新配音，画面保持原样（不做口型同步）。
+单条最长 120 分钟，超了上传前直接拒；按分钟计费，运行前实时查价。
+可选 `--ref <参考音频或视频>`（仅 `clone` 有意义，克隆别人的声音须先取得本人同意）、`--ref-lang`、`--no-keep-bgm`、`--fit-policy`、
+`--speed-band <最小,最大>`、`--subtitle-mode`、`--subtitle-type`、`--project-formats <逗号分隔>`；各参数的合法取值以服务端为准，CLI 不内置枚举。
+
+产物：`<输入名>-dub.mp4`（音频输入为 `-dub.mp3`）、`dub.wav`、`bgm.wav` 与 `base.mp4`（有则落）、字幕 `.srt`、逐句对齐记录 `transcript.json`、
+工程文件按格式分目录（`gtrk/`、`jianying/` …），`result-output.json` 为配音对齐报告。
+提交时自动带上原片与产物目录的本机路径，各格式工程里的素材都指向本机文件，打开即用。要剪映草稿加 `--project-formats gtrk,jianying`：草稿两件套齐全后自动放进剪映草稿目录（新增 `--jianying-draft-dir`，缺省读 `gtrk init` 配置或自动探测，与 `gtrk oralcut` 一致）；CapCut 草稿留在产物目录。服务端尚未升级时工程里仍是占位名、剪映草稿缺 meta，终端会各打一行提示。
+字幕、逐句记录、工程文件等附带产物偶尔缺项时只打一行 WARN，任务照常判成功。
+
+### 加：工具族通用「附加输入文件」
+
+工具可声明除主输入之外的本地文件参数（首个使用者是上面的 `--ref`）：任何上传之前先本地校验文件存在与扩展名，
+主输入之后上传，`--reupload` 同样生效，`task.json` 记录 `extraInputs`；没声明的工具行为与面包屑不变。
+产物文件名带子目录时自动建父目录。
+
+### 改：共享参数说明与超时长报错
+
+`--language` / `--translate-language` / `--speaker` / `--subtitle-type` 的说明改为不绑定单一工具的表述，参数名不变。
+视频类工具输入超时长的报错改为「输入时长超过 N 分钟上限，请先裁剪或分段后再提交」。
+
 ### 文档：`gtrk-tools` 图纸写明 `audio_tts_clone` 可选出字幕（link-add-tts-subtitle-output-cli 3.2）
 
 输入列补 `--subtitle-format <fmt>`（可选、缺省不出、不额外计费、取值以服务端为准），产物列补另产 `tts-<音色代号>.srt`（服务端降级时不留空文件）；

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.
@@ -666,6 +677,7 @@ Standalone single-request capabilities, kept separate from the pipeline's lane c
 | `audio_tts_clone` | **No file**: one of `--text`/`--text-file` (≤ 5000 characters) plus a required `--speaker`; optional language/format/speed/segmentation/subtitles/**sentence pause** (`--fragment-interval <sec>`, **in-house voices only**; cloud voices **return an error** rather than silently ignoring it — the valid range is enforced server-side and stated in that error) | Voice-over audio wav/mp3 (plus optional subtitles); billed by character count — the unit and unit price come from what `gtrk tool list` shows live | Queried live before the run | Live |
 | `video_ai_subtitle` | One video or audio file; `--language <code>` required; optional `--translate-language`, `--need-render`, `--need-pure`, `--subtitle-type`, `--subtitle-color`. By default only locally extracted audio is uploaded (the raw file never leaves your machine) | `.ass` subtitles + optional burned-in / subtitle-stripped `.mp4` + `result-output.json` (summary + word-level timeline) | Queried live before the run | Live |
 | `subtitle_translate` | One **subtitle file** `.ass` / `.srt`; **both** `--language <code>` and `--translate-language <code>` are required; optional `--output-format`, `--line-mode`, `--bilingual`, `--subtitle-type`, `--subtitle-color`, `--canvas <WxH>`. No speech recognition | Translated subtitles `.ass` or `.srt` + `result-output.json` (entry counts + degradation flags) | Queried live before the run | Live |
+| `video_translate_dub` | One video or audio file (**≤ 120 minutes**, uploaded whole); **all three of** `--language <source>`, `--translate-language <target>`, `--speaker <clone or voice code>` are required; optional `--ref <reference audio or video>` (only with `clone`; cloning someone else's voice requires that person's consent), `--ref-lang`, `--no-keep-bgm`, `--fit-policy`, `--speed-band <min,max>`, `--subtitle-mode`, `--subtitle-type`, `--project-formats <comma-separated>` (default: `.gtrk` only; add `jianying` to get a Jianying draft placed straight into your Jianying drafts folder), `--jianying-draft-dir`; valid values are decided server-side. Only the audio is replaced — the picture stays as it is (no lip sync); long sources take 15+ minutes | Dubbed video `<input-name>-dub.mp4` (`.mp3` for audio input) + `dub.wav` / `bgm.wav` + `.srt` subtitles + `transcript.json` + project files in per-format subfolders (`gtrk/`, `jianying/` …) + `result-output.json` (dub alignment report; includes `errors` when a side artifact is missing, without failing the run) | Queried live before the run | Live |
 | `video_long2short_pro` | One long video (uploaded whole); `--language <code>` required; optional `--output-language`, `--main-topic`, `--output-size`, `--no-jump-cut`, `--duration-pref`, `--max-clip-sec`, `--split-screen`, `--split-orientation`, `--speed-factor`, `--no-camera-move`, `--no-subtitle`, `--subtitle-translate-language` | Finished clips `clip{i}.mp4` + the human-readable report `clips.md` (including polish-degradation details) + `result-output.json` | Queried live before the run | Live |
 | `audio_separation` | One audio file; optional `--mode fast\|turbo` | Vocal and accompaniment audio (one or two items, depending on what is returned) | Queried live before the run | Live |
 | `audio_speaker_split` | One audio file; optional `--only-struct` | Per-speaker `.wav` stems + a `spoken_list` timeline (`result-output.json`) | Queried live before the run | Live |

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。
 
 **不建栏目？直接用默认"厨房"。** 零配置 = 内置默认栏目，端到端照常跑通，行为与配置化之前逐字节一致——栏目层是可选资产，不是必经关卡。
 
@@ -686,6 +695,7 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 | `audio_tts_clone` | **无文件**：`--text`/`--text-file` 二选一（≤5000 字）+ `--speaker` 必填；可选语言/格式/语速/切分法/字幕/**句间停顿**（`--fragment-interval <秒>`，**仅自训音色**；云引擎音色传了会**报错**而非静默忽略，合法区间由服务端校验并在报错里给出） | 配音音频 wav/mp3（+ 可选字幕）；按文本字符数计费，计量单位与单价以 `gtrk tool list` 实时显示为准 | 运行前实时查询 | 已上线 |
 | `video_ai_subtitle` | 单条视频或音频；`--language <码>` 必填；可选 `--translate-language`、`--need-render`、`--need-pure`、`--subtitle-type`、`--subtitle-color`。默认只传本地抽出的音频（毛片不上传） | `.ass` 字幕 + 可选烧录/去字幕 `.mp4` + `result-output.json`（摘要 + 字级时间轴） | 运行前实时查询 | 已上线 |
 | `subtitle_translate` | 单个**字幕文件** `.ass` / `.srt`；`--language <码>` 与 `--translate-language <码>` **双必填**；可选 `--output-format`、`--line-mode`、`--bilingual`、`--subtitle-type`、`--subtitle-color`、`--canvas <WxH>`。不含语音识别 | 译文字幕 `.ass` 或 `.srt` + `result-output.json`（条数统计 + 降级标记） | 运行前实时查询 | 已上线 |
+| `video_translate_dub` | 单条视频或音频（**≤120 分钟**，整片上传）；`--language <源语种>`、`--translate-language <目标语种>`、`--speaker <clone 或音色代号>` **三项必填**；可选 `--ref <参考音频或视频>`（仅 `clone`；克隆别人的声音须先取得本人同意）、`--ref-lang`、`--no-keep-bgm`、`--fit-policy`、`--speed-band <最小,最大>`、`--subtitle-mode`、`--subtitle-type`、`--project-formats <逗号分隔>`（缺省只出 `.gtrk`；要剪映草稿写 `gtrk,jianying`，草稿自动放进剪映草稿目录）、`--jianying-draft-dir`；取值以服务端为准。只换音轨、画面保持原样（不做口型同步），长片耗时十几分钟起 | 配音成片 `<输入名>-dub.mp4`（音频输入为 `.mp3`）+ `dub.wav` / `bgm.wav` + 字幕 `.srt` + `transcript.json` + 工程文件按格式分目录（`gtrk/`、`jianying/` …）+ `result-output.json`（配音对齐报告；附带产物缺项时含 `errors`，不判失败） | 运行前实时查询 | 已上线 |
 | `video_long2short_pro` | 单条长视频（整片上传）；`--language <码>` 必填；可选 `--output-language`、`--main-topic`、`--output-size`、`--no-jump-cut`、`--duration-pref`、`--max-clip-sec`、`--split-screen`、`--split-orientation`、`--speed-factor`、`--no-camera-move`、`--no-subtitle`、`--subtitle-translate-language` | 逐条成片 `clip{i}.mp4` + 人读报告 `clips.md`（含润色降级明细） + `result-output.json` | 运行前实时查询 | 已上线 |
 | `audio_separation` | 单条音频；可选 `--mode fast\|turbo` | 人声与伴奏音频（按实际返回可为一项或两项） | 运行前实时查询 | 已上线 |
 | `audio_speaker_split` | 单条音频；可选 `--only-struct` | 各说话人 `.wav` 分轨 + `spoken_list` 时间线（`result-output.json`） | 运行前实时查询 | 已上线 |
@@ -764,7 +774,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` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
 - **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。