@gitruck/cli 0.2.10 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitruck/cli",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "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": "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/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.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/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/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.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\""
   },
   "devDependencies": {
     "@xmldom/xmldom": "^0.9.6",

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

@@ -0,0 +1,71 @@
+---
+name: gtrk-music-visualizer
+description: 音乐可视化成片——把一首歌通过同合云出成一条频谱可视化视频（可选背景/封面 + 模板/配色样式）。当用户想「把这首歌做成可视化视频 / 音乐可视化 / 频谱视频 / 歌曲配画面出片 / music visualizer / 给歌配个动态封面视频」时使用本 skill。凡涉及把一段音频做成频谱可视化成片，优先用本 skill 驱动 gtrk CLI 的 `music-visualizer` 命令，不要手搓 ffmpeg。
+---
+
+# 音乐可视化（gtrk-music-visualizer）
+
+把用户的一首歌，用 `gtrk` CLI 跑通「**主音频上传（+可选背景/封面各自上传）** → 云端出频谱可视化成片 → 拉回本地」，再把产物目录回给用户。**CLI 是手、你是脑。**
+
+> **本 skill 已含你需要的全部信息**（参数、取值、执行、排错），照它做即可。具体模板 id 与参数细节以云端 API 文档为准（本地不冻结模板列表）。
+
+## 前置：CLI 装没装 + 体检
+
+先跑 `gtrk doctor`：
+- **`gtrk` 找不到 / command not found** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
+- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key，交互式、需真终端，你别替他跑）。
+- 全绿就往下走。
+
+## 一条命令
+
+```
+gtrk music-visualizer <音频> --template <模板id> [可选样式/文件] [--json]
+```
+
+- `<音频>`：本地音频文件（mp3/wav/m4a/aac/flac/ogg/wma 等）。按其时长计费。
+- `--template <id>`：**必填**。可视化模板 id（如 `aurora`）。取值以云端 API 文档 / 服务端模板列表为准；用户没指定就问他要，或让他去文档挑一个。传错服务端会报错并列出可选集。
+
+### 可选辅助文件（各自独立上传）
+- `--background <图或视频>`：背景素材，接受图片或视频。
+- `--cover <图>`：封面图，**仅接受图片**。
+
+### 可选样式参数
+- `--track <曲名>` / `--artist <歌手>`：叠加到画面的文字。
+- `--resolution <WxH>`：输出分辨率，如 `1080x1920`（竖屏）、`1920x1080`（横屏）。缺省走服务端默认 1920x1080。
+- `--fps <30-60>`：帧率，缺省 30。
+- `--c1 <hex>`：频谱主色，十六进制如 `#ff0066`。缺省白色。
+- `--c2 <hex>`：频谱**第二色**——**给了它才是双色渐变**，不给就是 `--c1` 单色。想要炫一点的渐变频谱就配上 `--c2`。
+- `--blur <0-40>`：背景模糊强度，缺省 16。
+
+### 通用
+- `--out <dir>`：产物目录（缺省 = 音频同目录下带时间戳的子目录）。
+- `--param k=v` / `--params-json '{...}'`：透传任意云端参数（覆盖优先级最高）。
+- `--json`：机读模式，stdout 只出结果 JSON。
+- `--reupload`：强制重新上传，忽略缓存。
+
+## 常见用法
+
+- 最简：`gtrk music-visualizer ./song.mp3 --template aurora`
+- 竖屏 + 双色渐变 + 叠字：`gtrk music-visualizer ./song.mp3 --template aurora --resolution 1080x1920 --c1 #ff0066 --c2 #6600ff --track 夜曲 --artist 周杰伦`
+- 带自定义背景 + 封面：`gtrk music-visualizer ./song.mp3 --template aurora --background ./bg.jpg --cover ./cover.png`
+
+## 配色引导（你帮用户想清楚）
+
+- 用户只说「配色炫一点 / 渐变」→ 给 `--c1` + `--c2` 两个色（双色渐变）。
+- 用户说「纯色 / 简洁」→ 只给 `--c1`。
+- 拿不准具体 hex：给常见搭配建议（如霓虹粉紫 `#ff0066`→`#6600ff`、青蓝 `#00e5ff`→`#0066ff`），或让用户给个大概色系你转 hex。
+- hex 必须是 `#RRGGBB` 或 `#RGB`；写错命令会在提交前报错。
+
+## 读产物
+
+完成后产物目录里有：
+- `<音频名>-visualizer.mp4`：成片。
+- `result.json`：`ok`/`files`/`taskId`；`ok=false` 时看 `errors`，可凭 `task.json` 的 `taskId` 稍后恢复，别急着重跑（重跑会重新计费）。
+
+## 排错
+
+- **缺 `--template`**：必填，问用户要模板 id 或让他查云端 API 文档的模板列表。
+- **模板 id 报错**：服务端会列出可选集，照着改。
+- **`--cover` 报「仅接受图片」**：封面只能是图片；视频素材放 `--background`。
+- **样式参数报错**：`--fps` 30-60、`--blur` 0-40、`--resolution` 必须 `宽x高`、`--c1/--c2` 必须十六进制——按报错提示改。
+- **产物下载失败（ok=false）**：网络波动或链接过期；凭 `taskId` 恢复，不整条重跑。

package/skills/gtrk-style-maker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gtrk-style-maker
-description: "能生产 skill 的 meta skill——通过启发式访谈引导视频创作者想清楚**他自己的**视觉语法，并把它落成**他自己的可执行 skill 家族**（黑盒、留本地）+ 栏目内共享词表 + 栏目配置登记。框架对审美零预设：不假设你有叙事结构、有容器概念、视觉分 MG/AI——你的维度（k）和取值（v）全部由你自己定义，本 skill 只提供「怎么想清楚」的工艺。当用户想「建一个新栏目/新频道的风格体系」「把我的审美沉淀成 skill」「做一个我自己的视觉 skill」「定义栏目风格规范/视觉语法」「栏目配置文档的 style 怎么填」「给我的栏目造一套创作工具」时使用本 skill。产出的 skill 落 ~/.claude/skills 即装即用，登记进 gtrk 栏目配置（style.skills）。"
+description: "能生产 skill 的 meta skill——通过启发式访谈引导视频创作者想清楚**他自己的**视觉语法，并把它落成**他自己的可执行 skill 家族**（黑盒、留本地）+ 栏目内共享词表 + 栏目配置登记。框架对审美零预设：不假设你有叙事结构、有容器概念、视觉分 MG/AI——你的维度（k）和取值（v）全部由你自己定义，本 skill 只提供「怎么想清楚」的工艺。当用户想「建一个新栏目/新频道的风格体系」「把我的审美沉淀成 skill」「做一个我自己的视觉 skill」「定义栏目风格规范/视觉语法」「栏目配置文档的 style 怎么填」「给我的栏目造一套创作工具」时使用本 skill。产出的 skill 通过通用 skills 适配器安装到当前或多个 Agent，登记进 gtrk 栏目配置（style.skills）。"
 ---
 
 # gtrk-style-maker · 造你自己的视觉 skill
@@ -75,7 +75,7 @@ description: "能生产 skill 的 meta skill——通过启发式访谈引导视
 1. **起 skill 目录**（用户作坊目录为正本，如 `D:\<他的工作区>\skills\<skill-name>\`）：SKILL.md（frontmatter `name`+`description`，description 即触发器，写清「当用户想…时使用」）+ **README.md 必产**（含「正本→安装」单向流声明）+ 按需 references/ assets/。exemplar 一旦在 SKILL.md 里被引用就必须真实存在——「计划中的案例」不能以文件路径形式出现。skill 正文结构**由访谈产出的维度决定**，不套模板。
 2. **契约绑定**：产物命中管线 handoff 类型的，查 `contracts/handoff-contracts.json`（本 CLI 包内）；映射到契约的（如 HTML 动画颗粒 → gsap-emit v1），在 skill 中引用「契约名+版本」并把契约合规项加进其自检清单；映射为 null 或管线外产物，无此要求。
 3. **共享词表**（条件产出，见第⑤招）。
-4. **安装**：整目录拷到 `~/.claude/skills/<skill-name>/`（即装即用）。skill README 写明**「正本→安装」单向流**：源码正本在作坊，安装位是产物，改动先改正本再重装。
+4. **安装**：以作坊里的 skill 目录为源，运行 `npx -y skills add "<skill正本目录>" -g -y`，让通用适配器自动探测 Agent，并以统一正本 + symlink/junction 安装；用户明确指定宿主时追加 `-a <agent-id>`（可重复），明确要求独立副本时追加 `--copy`。不要在本 skill 里维护 Claude/Codex/TRAE 等路径表。skill README 写明**「正本→安装」单向流**：源码正本在作坊，安装位是产物，改动先改正本再重装。
 5. **登记**：把 `{id, ref: <正本路径>, produces: <handoff 类型或自造串>}` **追加**进本地栏目配置 `style.skills`（词表进 `style.shared`）。配置文件位置以 gtrk 的 paths 口径为准（当前 `~/.gitruck/columns/<栏目id>.json`）；文件不存在则创建最小骨架 `{meta:{id},style:{skills:[…]}}`。**追加，绝不清空既有条目**。产物是管线外的（封面等），登记时加 `routing:"none"`。
 
 ## 交付前自检（你自己的 Quality Bar）

package/skills/gtrk-style-maker/references/craft-output-spec.md

@@ -17,7 +17,7 @@
 
 ## 2. 「正本→安装」单向流（写进产出 skill 的 README）
 
-> 本 skill 源码正本在 `<用户作坊路径>`；`~/.claude/skills/<name>/` 是安装产物。改动**永远先改正本**，再重新拷贝安装。云端（claude.ai capability）上传是可选的第三级分发，同样以作坊正本打包。
+> 本 skill 源码正本在 `<用户作坊路径>`；Agent 的 skills 目录是安装产物。改动**永远先改正本**，再运行 `npx -y skills add "<用户作坊路径>/<name>" -g -y` 重新安装。通用适配器负责 Agent 探测、目录映射，以及统一正本到各宿主的 symlink/junction；需要独立副本时才加 `--copy`。云端上传是可选的第三级分发，同样以作坊正本打包。
 > ——副本漂移是有血泪教训的（同一枚举曾在 6 处定义、口径打架），单向流是唯一解法。
 
 ## 3. 共享词表（条件产出）
@@ -43,4 +43,4 @@
 ## 6. 收尾提醒（给用户）
 
 - skill 留本地即完整可用；上传 claude.ai（打包 .skill zip）是**可选**分发，供网页/移动端触发。
-- 后续迭代：改作坊正本 → 重拷 `~/.claude/skills/` → （可选）重新打包上传。
+- 后续迭代：改作坊正本 → 重跑 `npx -y skills add "<正本目录>" -g -y` → （可选）重新打包上传。

package/skills/gtrk-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gtrk-tools
-description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtrk tool` 家族。当用户想“让图动起来 / 抠像去背景 / 图片或视频去黑边 / 图片或视频比例转换 / 视频防抖 / 添加蒸汽波滤镜 / 清理有权处理的图片或视频中的水印、字幕或叠加元素 / 视频超分变清晰 / 视频补帧变流畅 / 分离人声和伴奏 / 提取伴奏 / 给音频或视频降噪 / 去掉音频静音停顿 / 一键剪 MAD / 用某个 gtrk 单点工具 / gtrk 工具族里有什么”时使用本 Skill。凡涉及这些能力，优先驱动 CLI，不让用户自己去终端敲，也不手搓 ffmpeg。
+description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtrk tool` 家族。当用户想“让图动起来 / 抠像去背景 / 图片或视频去黑边 / 图片或视频比例转换 / 视频防抖 / 添加蒸汽波滤镜 / 清理有权处理的图片或视频中的水印、字幕或叠加元素 / 视频超分变清晰 / 视频补帧变流畅 / 分离人声和伴奏 / 提取伴奏 / 按说话人分轨 / 音频变调变速 / 钢琴扒谱转 MIDI 或修复钢琴录音 / 给音频或视频降噪 / 去掉音频静音停顿 / 长图转方图 / 图片变 LivePhoto 微动 / 视频机械分镜或智能分镜切镜头 / 提取运镜高光片段 / 给视频加字幕或翻译字幕或烧录字幕 / 一键剪 MAD / 用某个 gtrk 单点工具 / gtrk 工具族里有什么”时使用本 Skill。凡涉及这些能力，优先驱动 CLI，不让用户自己去终端敲，也不手搓 ffmpeg。
 ---
 
 # gtrk 工具族（gtrk-tools）
@@ -28,9 +28,19 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `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`（非下载文件） | 运行前实时查询 | 已上线 |
+| `video_ai_segment` | 「智能分镜 / 语义切镜头 / 按类目景别拆镜头」 | 单条本地视频；可选 `--segment-mode scene\|shot_type\|narrative\|subject` | 语义分镜结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
+| `video_motion_cut` | 「运镜高光 / 提取运镜片段 / 找高光镜头」 | 单条本地视频 | 运镜/高光片段结构 `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`） | 运行前实时查询 | 已上线 |
+| `audio_stretch` | 「变调 / 变速 / 升降 key / 加快放慢音频」 | 单条音频；可选 `--semitones`、`--speed`（>0） | 变调变速音频 | 运行前实时查询 | 已上线 |
 | `audio_noise_reduce` | 「音频降噪 / 视频声音降噪 / 去底噪」 | 单条音频或视频 | 降噪后的音频 | 运行前实时查询 | 已上线 |
 | `audio_silence_remove` | 「去静音 / 删掉过长停顿 / 压缩音频空白」 | 单条音频 | 去静音音频 | 运行前实时查询 | 已上线 |
+| `piano_audio_to_midi` | 「钢琴扒谱 / 钢琴音频转 MIDI / 提取 MIDI」 | 单条音频 | MIDI 文件 `.mid` | 运行前实时查询 | 已上线 |
+| `piano_audio_enhance` | 「钢琴录音修复 / 增强钢琴音质」 | 单条音频 | 高质量 WAV + 配套 MIDI（双产物） | 运行前实时查询 | 已上线 |
+| `image_to_square` | 「长图转方图 / 把长图变方的」 | 单张图片；可选 `--max-line`（≤20000） | 方形图片 | 运行前实时查询 | 已上线 |
+| `image_to_live` | 「图片变 LivePhoto / 静图微动 / 让照片动起来」 | 单张图片 | 微动视频 `.mp4`（产物是视频） | 运行前实时查询 | 已上线 |
 | `mad` | 「一键剪 MAD / 素材文件夹自动出卡点成片 / 自动选技法 / 给这堆素材出个 AE 工程」 | 一个素材文件夹（3~10 条视频）+ 可选 `--bgm 歌.mp3` | AE 母合成工程 `.jsx`（仅支持 AE） | 仅 `--bgm` 触发实时查价 | 已上线 |
 
 > 清单随 CLI 版本增补。**动手前先跑 `gtrk tool list --json` 拿最新清单**，别凭记忆——新工具、状态变化都在那里。
@@ -51,9 +61,10 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 2. **执行前转述实时计费提示**：先读本次 `gtrk tool list --json` 的 `billingHint`/`pricing`，再把实时结果如实告诉用户；不得引用本文件或记忆中的旧价格。若显示价格暂不可用，就说明最终以服务端结算为准。
 3. **一律带 `--json`**：`gtrk tool <name> <输入> --json`。stdout 只会有一行结果 JSON（`{ ok, outDir, files, taskId, fileId, … }`），人读日志在 stderr。按 `ok` 判成败、从 `files` 拿产物路径、把 `outDir` 回给用户。
 4. **缺 API Key 先引导配置**：cloud 型工具没配 Key 会报错让先跑 `gtrk init`。遇到就引导用户 `gtrk init`（或设 `GITRUCK_API_KEY`），别反复重试。
-5. **产物落地与恢复**：产物落在 `outDir`（缺省 = 输入同目录下 `<输入名>-<工具名>/`，可 `--out <dir>` 覆盖）。提交成功即写 `task.json`（含 `taskId`）、完成即写 `result.json`。**若 `ok=false`**（任务完成但产物下载失败，如链接过期）：`result.json` 的 `errors` 有明细、`task.json` 保留——凭其中的 `taskId` 可稍后人工恢复取回，别急着重跑整条（重跑会重新计费）。
-6. **透传高级参数**：命令没为某个云端参数开 flag 时，用 `--param k=v`（可重复）或 `--params-json '<对象>'` 直接透传（如 `image_move` 想指定输出几何 `--param width=1080 --param height=1920`）。
-7. **单发单收、批量靠循环**：一次一个输入；用户要批处理就你逐个循环调，不是一条命令喂多文件。
+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. **单发单收、批量靠循环**：一次一个输入；用户要批处理就你逐个循环调，不是一条命令喂多文件。
 
 图片比例转换常用形态：`gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --json`。`--canvas-type` 只接受实际运行时契约 `normal`、`rectangle`、`square`；不要传旧文档中的 `fit`。省略画布参数时不替服务端写死默认值。