@gitruck/cli 0.2.17 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitruck/cli",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
   "license": "MIT",
   "author": "Gitruck (同合云)",
@@ -48,7 +48,7 @@
     "build": "bun build ./src/index.ts --target=node --outfile dist/index.js",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm test && bun run build",
-    "test": "esbuild src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts src/lib/material-integrity.ts src/lib/solid-png.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --test \"test/*.test.mjs\"",
+    "test": "esbuild src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts src/lib/material-integrity.ts src/lib/solid-png.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --test \"test/*.test.mjs\"",
     "openspec:gate": "node openspec/gate.mjs"
   },
   "devDependencies": {

package/skills/gtrk-long2short/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: gtrk-long2short
+description: 长剪短闭环——把一条长视频（课程/直播/播客/访谈毛片）通过同合云选段跳剪成多条高光短片工程，一次产出逐 clip 的 gtrk+剪映+PR 三方工程（可选智能分屏）。当用户想「长剪短 / 长视频切高光 / 直播切片 / 课程切短视频 / 播客出短片 / 两小时的课切成几条精华」时使用本 skill。凡涉及把长视频拆成多条可精修的短片工程，优先用本 skill 驱动 gtrk CLI 的 `long2short` 命令，不要手搓 ffmpeg、不要人工挑时间码。
+---
+
+# 长剪短（gtrk-long2short）
+
+把用户的一条长视频，用 `gtrk` CLI 跑通「**本地抽音频/720p 代理（毛片永不上传）** → 云端语义选段+跳剪（可选分屏）→ 逐 clip 拉回 gtrk/剪映/PR 三方工程」，再把产物目录回给用户。**CLI 是手、你是脑。**
+
+> 与智能剪口播（gtrk-oralcut）同一心智模型；差异是**一次任务出 N 条短片**，各自一份工程组落 `clip{i}/` 子目录。
+
+## 前置：CLI 装没装 + 体检
+
+先跑 `gtrk doctor`：
+- **`gtrk` 找不到** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
+- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（交互式、需真终端，你别替他跑）。
+- 全绿就往下走。
+
+## 一条命令
+
+```bash
+gtrk long2short "D:/毛片/课程.mp4" --language zh-CN --json
+```
+
+对谈/多人同框想要分屏：
+
+```bash
+gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-orientation tb --json
+```
+
+## 参数表
+
+| 参数 | 说明 |
+|---|---|
+| `--language <code>` | **必填**，源语种（如 zh-CN；取值以服务端支持列表为准，传错服务端会报枚举） |
+| `--split-screen` | 开启智能分屏：本地改传 **720p 代理**（否则只抽音频）；云端检测多人同框段并烤 720p 分屏素材 |
+| `--split-orientation <o>` | 分屏方向 `auto|lr|tb`（缺省 auto=按内容可复现随机） |
+| `--main-topic <text>` | 主题引导，影响选段偏好 |
+| `--duration-pref <p>` / `--max-clip-sec <n>` | 成片时长偏好 / 单条上限秒。**成片条数由内容语义决定，不能指定条数** |
+| `--no-jump-cut` | 关闭跳剪（默认开：片内去水词冗余，只删不重排） |
+| `--output-size <s>` | 画布 `9:16|16:9|1:1` 或 `WxH`（缺省 9:16 竖版） |
+| `-f, --formats <list>` | 三方格式，缺省 `gtrk,jianying,xml`（云端逐 clip 直产；gtrk 恒有） |
+| `--jianying-draft-dir <dir>` | 剪映草稿根（或 `auto`）；各 clip 草稿落 `<草稿根>/<产物根名>_clip{i}` |
+| `-o/--out`、`--no-open`、`--json`、`--reupload`、`--param/--params-json` | 与 oralcut 同口径 |
+
+## 计费与跑前须知（每次都转述给用户）
+
+- 运行时 CLI 自动查询实时价格并在跑前打印——**把计费提示原样转述**；按**上传物音频时长**计费（≈原片时长），**长片先向用户确认再跑**。
+- 云端处理时长随片长涨（ASR+选段），CLI 轮询墙钟 60 分钟；超时不丢——产物根 `task.json` 里有 `task_id` 可恢复。
+
+## 产物（跑完把这些讲给用户）
+
+- 产物根 `<毛片名>-long2short/`：`report.json`（选段报告）+ `result.json` + 逐 clip 子目录 `clip0/ clip1/ …`（各含 `gtrk/` 客户端工程、`jianying/` 草稿、`xml/` PR 工程）。
+- 开了 `--split-screen` 时：**分屏素材落在毛片旁的 `split_screen/` 子目录**（工程素材路径指向那里，别移动/删除，移动了工程会缺素材）——这点要提前告知用户。
+- 剪映草稿已拷入草稿根（给了 `--jianying-draft-dir` 时），剪映里直接可见 `<产物根名>_clip{i}`。
+
+## 排错
+
+- **部分 clip 失败 / 个别分屏素材 404**：单点失败不连坐，`result.json` 的 `errors` 有明细；把失败项如实告诉用户，其余产物照常可用。
+- **轮询超时/进程中断**：凭产物根 `task.json` 的 `task_id` 查询云端状态；任务在云端照常跑完，稍后可重取。
+- **clips 为空**：说明内容里没有可成片的高光段（纯语义选段），把 `report.json` 摘要给用户看原因。

package/skills/gtrk-matrix/SKILL.md

@@ -111,7 +111,10 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 - **在同合云桌面客户端（opencut / OpenCut Gitruck Edition）里打开这个工程**，B-roll 候选轨已经铺好。
 - **用轨道头的「小眼睛」开关逐条切换对比**：看哪条候选最贴这段口播的情绪/画面，留下满意的、关掉不要的。
 - 候选默认是 preview 代理（轻量预览）；**下载原片属挑选后的动作**（客户端挑选 UI），确认要哪条再拉原片。
-- **候选轨下方还垫了一条纯黑底轨**（`lay.blackTrack`），按 beat 包络整条铺满，作用是 B-roll 期间遮住底下的口播画面（含候选轨上的留空处）——删多余候选轨时**别误删它**；换片请拖到**候选轨的颗粒**上、**别拖到黑底条上**（含拖拽保护的客户端会直接拒绝并提示；尚未升级到该版本的客户端会被误拖打出黑底破洞、该处漏口播）。不想要黑底就加 `--no-black-bed` 重跑，会自动剥净。
+- **候选轨下方还垫了一条纯黑底轨**（`lay.blackTrack`），按 beat 包络整条铺满，作用是 B-roll 期间遮住底下的口播画面（含候选轨上的留空处）——删多余候选轨时**别误删它**；换片请拖到**候选轨的颗粒**上、**别拖到黑底条上**。不想要黑底就加 `--no-black-bed` 重跑，会自动剥净。
+  - **拖到黑底条上会被客户端直接拒绝并给出提示**（0.2.10 起，2026-07-31 发版强更；`fix-broll-drop-target-type-gate` 把落点命中面接通了黑底保护）。若用户客户端仍是 0.2.10 之前的旧版（强更未拉到），旧行为是**静默新建一条 video 轨**插入、落点在黑底条下半区时预览完全看不见——遇到用户说「拖了没反应」，先让他重启客户端吃到强更，再查轨道数。
+  - 所以用户说「拖了没变化 / 画面没换」时，**先按这条排查**：看轨道数是不是比刚才多了一条；**按一次 `Ctrl+Z` 就整条撤销**（插入 + 建轨一起回、不留空轨），再让他拖到候选轨的颗粒上。
+  - **MUST NOT 跟用户说「客户端会拒绝并提示」**——那是发版后才成立的行为，现在承诺就是骗他。
 - 觉得填充有问题（太杂/太空/漏段）先别急着往下——**回来告诉我**，我按下面「常见情况」调参重铺。
 
 **用户明确说「B-roll 就这样、可以了」之后**，才交棒 ④。别自作主张替他拍板往下冲。

package/skills/gtrk-mg/SKILL.md

@@ -85,6 +85,13 @@ gtrk mg lint "<产物目录>/mg/<composition_id>.html" --dispatch "<产物目录
   - `x-engine-api-override`：颗粒运行时覆写了 `tl.seek`（老颗粒常见的 `rr-seek-shim`）或把 `__timelines[…]` 换成了包装对象。它会推翻引擎显式传的 `seek(t, true)`，且引擎改走 `time()`/`progress()` 就完全失效。**既有垫片属过渡态**：2026-07-26 引擎侧结论已核实（引擎本就不抑制回调），垫片已无保护作用、也无害，**可择期清理**（删后须重跑 lint 并重渲复验），不清也不拦；新颗粒别再加。
   - `x-raf-interval`：颗粒里有 `requestAnimationFrame(` / `setInterval(`。这类自有时钟**不被 seek 驱动**，逐帧渲染时等于冻结（契约明令：所有视觉变化必须挂在 tl 上）。静态正则分不清用途，报了要**人眼确认它是不是在驱动画面**；若是 → 回步骤 2 让生产 skill 改挂 tl。
   - 另：引擎不抑制回调 = 逐帧 scrub 时 `onComplete`/`onStart`/`onRepeat` 会**反复触发**。颗粒里**别写「只跑一次」的回调**（累加计数 / `push` 数组 / 一次性 DOM 插入），要写成每次从补间状态**重算**的幂等形式。
+- **成本项 `c-filter-*` 三项恒非致命、当期全部不拦铺轨**（正本条款 = `contracts/gsap-emit-v1.md`「渲染成本：真卷积滤镜」一节）：这组查的是**每帧成本**、不是正确性——命中的颗粒**画面是对的，只是渲得慢**。
+  - `c-filter-animated`：**时间线补间直接驱动了真卷积滤镜**（`filter:blur()/drop-shadow()`，或补间驱动 SVG `feGaussianBlur` 的 `stdDeviation`）。滤镜值一变，上一帧的卷积结果当场失效、缓存彻底失灵，是这组里**最贵**的形态。**处置**：回步骤 2 让生产 skill 改用 `opacity` / `transform`（`scale`/位移）表达同一叙事动作；确需滤镜就做成**静态两态切换**。**不拦铺轨**。
+  - `c-filter-static-fullbleed`：**整幅静态真卷积滤镜**（该声明自身就是 `position:absolute;inset:0` 一类铺满形态）。每帧对整幅做一次卷积。**首选改法是缩小被滤镜覆盖的几何面积**（面积一项同时压掉卷积与整幅逐帧合成两笔成本）；次选把静态滤镜结果预烘成图，且**必须是 RGBA PNG**（透明叠加颗粒的 alpha 是成片合成的必需通道，烘成 JPEG 或无 alpha 格式会在成片里塌成不透明色块），但预烘只消得掉卷积、消不掉整幅逐帧合成，**收益有上限**。去不去滤镜属审美取值，**判断权在作者**，本项只给信息与改法。**不拦铺轨**。
+  - `c-filter-indeterminate`：补间的 `filter` 值不是字符串字面量（变量 / 模板串 / 函数返回），lint **对该处没作判定**——既不是「判过且通过」，也不是命中。**人眼确认它到底会不会驱动 blur / drop-shadow**；会就按 `c-filter-animated` 的改法处理。**不拦铺轨**。
+  - **`box-shadow` 整族不在射程内**（含 `box-shadow: 0 0 0 Npx` 这类零卷积脉冲写法，也含带模糊半径的写法）——看到 `box-shadow` 没被报**不是漏报**，是既定射程边界。
+  - ⚠️ **没报 ≠ 这颗便宜**：这三项是**形态提示**，真判据永远是**真渲染出片计时**。收益也别外推——现网既有栏目语料（21 颗）去掉滤镜只省 **0~3.1%**（2026-07-30 真机实测，仅对该语料成立），这组规则的价值在**滤镜重的新语料进管线前先把门立好**。
+- **id 前缀读法**（三个命名空间，别按前缀反推错阻断行为）：**数字前缀 `1-`~`8-`** = 契约铁律项，致命性**按项声明**（`4-*` / `5-*` / `7-*` / `8-*` 就都不致命）；**`x-`** = 哨兵项，**恒不拦**；**`c-`** = 成本项，致命性按项声明，**当前三项均不拦**。
 - **不过（非 0 退出、逐条报因）→ 把报错原样丢回栏目 MG 生产 skill 修，重产重 lint，别硬铺**。铺一颗不合规颗粒会污染工程。
 - 只想批量干校验不写回：`gtrk mg --project <dir> --lint-only`（有 beat 没过就 `ok:false` + **非 0 退出**，工程一个字节都不动）。
 

package/skills/gtrk-tools/SKILL.md

@@ -7,7 +7,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 
 飞书使用教程统一入口：[gtrk CLI 使用教程](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk)。
 
-`gtrk tool <name> [input]` 是 gtrk 的**单点能力**族：一个工具 = 单发单收（给一个输入、出一份产物），没有 SOP 次序、没有用户检查点链——与成片管线的车道命令（`oralcut` / `split` / `matrix` / `mg`）是两回事。本 skill 是这个族的**统一调用向导**：认清有哪些工具、按纪律驱动 `gtrk tool` 命令、把产物和计费如实回给用户。
+`gtrk tool <name> [输入...]` 是 gtrk 的**单点能力**族：一个工具 = 单发单收（给一份输入、出一份产物；多文件图片工具的「一份输入」是一组图片路径，顺序即拼装顺序），没有 SOP 次序、没有用户检查点链——与成片管线的车道命令（`oralcut` / `split` / `matrix` / `mg`）是两回事。本 skill 是这个族的**统一调用向导**：认清有哪些工具、按纪律驱动 `gtrk tool` 命令、把产物和计费如实回给用户。
 
 > **本 skill 已含你需要的全部信息**（工具清单、调用纪律、恢复语义、排错话术）。工具清单以 `gtrk tool list --json` 为**唯一真相**——本文件与它漂移时以命令输出为准并回来修本文件。参数细节以 `gtrk tool --help` 为准。
 
@@ -31,6 +31,9 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `video_segment` | 「机械分镜 / 按画面变动切分镜区间 / 场景切分」 | 单条本地视频；可选 `--detector content\|adaptive`、`--threshold` | 分镜区间结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
 | `video_ai_segment` | 「智能分镜 / 语义切镜头 / 按类目景别拆镜头」 | 单条本地视频；可选 `--segment-mode scene\|shot_type\|narrative\|subject` | 语义分镜结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
 | `video_motion_cut` | 「运镜高光 / 提取运镜片段 / 找高光镜头」 | 单条本地视频 | 运镜/高光片段结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
+| `video_speaker_detect` | 「谁在说话 / 说话人检测 / 检测画面里谁在何时开口」 | 单条本地视频；可选 `--language`、`--max-faces-per-frame`、`--detect-body`、`--track-sample-fps`。**重 GPU、按分钟计费较高，长片先想清楚** | 可见说话人结构 `result-output.json`（时间字段时基以服务端输出为准） | 运行前实时查询 | 已上线 |
+| `video_split_screen` | 「分屏 / reaction 同框 / 对比视频 / 多画面合成」 | **2~16 段视频**（多 positional，顺序有语义）；精确档 `--clips-json`：条目 `{input:0 起序号, begin_time_ms, end_time_ms, crop 归一化}`（**毫秒时基**、`input` 指第几个输入文件、同文件可多窗口）；可选 `--layout-mode/--layout-id/--seed/--output-ratio/--quality/--fit-mode/--audio-mode/--gap-ratio/--background-color`。**成片时长对齐最短段** | 一条分屏成片视频 | 运行前实时查询 | 已上线 |
+| `video_face_track` | 「人脸追踪 / 人物出场时间段 / 视频里有哪几个人」 | 单条本地视频；可选 `--sample-fps`、`--max-faces`、`--min-face-ratio`、`--enable-body-match`、`--similarity-threshold`；`time_ranges` 经 `--params-json` 传（**单位毫秒**，如 `{"begin_time":0,"end_time":30000}`）。**重 GPU、按分钟计费较高** | 人物 ID/时间段/轨迹结构 `result-output.json`（时基以服务端输出为准） | 运行前实时查询 | 已上线 |
 | `video_ai_subtitle` | 「智能字幕 / 给视频加字幕 / 视频翻译字幕 / 烧录字幕 / 去原字幕」 | 单条视频或音频；**`--language <码>` 必填**；可选 `--translate-language`、`--need-render`（烧录）、`--need-pure`（去原字幕）、`--subtitle-type`、`--subtitle-color` | `.ass` 字幕文件 + 可选烧录/去字幕 `.mp4` + `result-output.json`（LLM 摘要 + 字级时间轴） | 运行前实时查询 | 已上线 |
 | `audio_separation` | 「分离人声和伴奏 / 提取人声 / 提取伴奏」 | 单条音频 | 人声与伴奏音频（按实际返回可为一项或两项） | 运行前实时查询 | 已上线 |
 | `audio_speaker_split` | 「按说话人分轨 / 把不同人的声音分开 / 谁在什么时候说话」 | 单条音频；可选 `--only-struct` 只出结构 | 各说话人 `.wav` 分轨 + `spoken_list` 时间线（`result-output.json`） | 运行前实时查询 | 已上线 |
@@ -40,7 +43,9 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `piano_audio_to_midi` | 「钢琴扒谱 / 钢琴音频转 MIDI / 提取 MIDI」 | 单条音频 | MIDI 文件 `.mid` | 运行前实时查询 | 已上线 |
 | `piano_audio_enhance` | 「钢琴录音修复 / 增强钢琴音质」 | 单条音频 | 高质量 WAV + 配套 MIDI（双产物） | 运行前实时查询 | 已上线 |
 | `image_to_square` | 「长图转方图 / 把长图变方的」 | 单张图片；可选 `--max-line`（≤20000） | 方形图片 | 运行前实时查询 | 已上线 |
-| `image_to_live` | 「图片变 LivePhoto / 静图微动 / 让照片动起来」 | 单张图片 | 微动视频 `.mp4`（产物是视频） | 运行前实时查询 | 已上线 |
+| `image_to_live` | 「图片变 LivePhoto / 静图微动 / 让照片动起来」 | 单张图片 | 微动视频 `.mp4`（产物是视频） | 运行前实时查询 | 未开放（上游生成能力暂未开放，恢复后重新上架） |
+| `image_classic_template` | 「做封面 / 智能拼图 / 标题配图出封面图」 | **多张图片**（可传多个路径，文件顺序即拼装顺序）；**`--main-title <标题>` 必填**；可选 `--sub-title`、`--template-mode`、`--aspect`、`--quality`、`--output-pic-count`（服务端钳制 ≤20）、`--output-text-count`（≤20）、`--title-layout` | 封面/拼图成品（text/pic/render 三组、各组可空可多张） | 运行前实时查询 | 已上线 |
+| `image_vertical_stitch` | 「拼长图 / 多图竖拼 / 截图接成一张长图」 | **多张图片**（可传多个路径，顺序=自上而下拼接顺序） | 一张垂直拼接长图 | 运行前实时查询 | 已上线 |
 | `mad` | 「一键剪 MAD / 素材文件夹自动出卡点成片 / 自动选技法 / 给这堆素材出个 AE 工程」 | 一个素材文件夹（3~10 条视频）+ 可选 `--bgm 歌.mp3` | AE 母合成工程 `.jsx`（仅支持 AE） | 仅 `--bgm` 触发实时查价 | 已上线 |
 
 > 清单随 CLI 版本增补。**动手前先跑 `gtrk tool list --json` 拿最新清单**，别凭记忆——新工具、状态变化都在那里。
@@ -69,7 +74,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 5. **瞬时网络错误退避后只重试 1 次**：若 `gtrk tool list --json` 或工具命令因 `fetch failed`、`ECONNRESET`、`ETIMEDOUT`、`ENOTFOUND`、`socket hang up`、网络不可达或 HTTP `502/503/504` 失败，先等 **2 秒**，再原样执行同一命令 **1 次且仅 1 次**（总尝试次数最多 2 次）。第二次仍失败就停止，如实说明网络波动并给出最后错误，绝不循环重试。参数/文件校验错误、缺 Key、HTTP 4xx、云端业务错误码、明确的任务失败/取消均**不重试**。重试前先检查日志及输出目录：一旦已出现 `taskId` 或 `task.json`，说明任务可能已经提交，禁止重跑整条以免重复计费，转入下一条恢复语义。
 6. **产物落地与恢复**：产物落在 `outDir`（缺省 = 输入同目录下 `<输入名>-<工具名>/`，可 `--out <dir>` 覆盖）。提交成功即写 `task.json`（含 `taskId`）、完成即写 `result.json`。**分析型工具**（`video_segment` / `video_ai_segment` / `video_motion_cut`）产的是**结构化数据不是下载文件**：结果落 `result-output.json`（分镜/运镜结构），`result.json` 的 `resultFile` 字段指向它、`files` 为空且 `ok=true` 属正常，别当成「没出产物」。**若 `ok=false`**（任务完成但产物下载失败，如链接过期；或既无文件也无结构）：`result.json` 的 `errors` 有明细、`task.json` 保留——凭其中的 `taskId` 可稍后人工恢复取回，别急着重跑整条（重跑会重新计费）。
 7. **透传高级参数**：命令没为某个云端参数开 flag 时，用 `--param k=v`（可重复）或 `--params-json '<对象>'` 直接透传（如 `image_move` 想指定输出几何 `--param width=1080 --param height=1920`）。
-8. **单发单收、批量靠循环**：一次一个输入；用户要批处理就你逐个循环调，不是一条命令喂多文件。
+8. **单发单收、批量靠循环**：一次一份输入；用户要批处理就你逐个循环调。例外是多文件图片工具（`image_classic_template` / `image_vertical_stitch`）——它们的一份输入天然是一组图片（一次任务一次计费），传参顺序即拼装顺序，别把它当批处理。
 
 图片比例转换常用形态：`gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --json`。`--canvas-type` 只接受实际运行时契约 `normal`、`rectangle`、`square`；不要传旧文档中的 `fit`。省略画布参数时不替服务端写死默认值。