@gitruck/cli 1.0.1 → 1.0.2

package/README.en.md

@@ -403,7 +403,7 @@ Standalone single-request capabilities, kept separate from the pipeline's lane c
 
 | Tool | Input | Output | Billing | Status |
 |---|---|---|---|---|
-| `image_move` | One image | Camera-move video (geometry derived from the source orientation: landscape 1920×1080 / portrait 1080×1920) | Queried live before the run | Live |
+| `image_move` | One image; optional `--motion` picks one of 26 camera moves | Camera-move video (geometry derived from the source orientation: landscape 1920×1080 / portrait 1080×1920) | Queried live before the run | Live |
 | `image_matting` | One image | Transparent-background png (`--param` can request a backing plate) | Queried live before the run | Live |
 | `image_blackborder_remove` | One local image | Image with black borders removed | Queried live before the run | Live |
 | `image_canvas_adapt` | One local image; optional target width/height and `normal` / `rectangle` / `square` | Aspect-adapted image | Queried live before the run | Live |
@@ -444,7 +444,7 @@ Standalone single-request capabilities, kept separate from the pipeline's lane c
 The seven shared video tools — black-border removal, aspect adaptation, stabilization, vaporwave, cleanup, upscaling and interpolation — accept only the server's current `video_ext`: `.mp4`, `.avi`, `.mpg`, `.mov`, `.flv`, `.mxf`, `.mpeg`, `.ogg`, `.3gp`, `.wmv`, `.h264`, `.m4v`, `.ts`; `.mkv` and `.webm` are rejected locally. Inputs must be local file paths — the CLI does not download remote videos.
 
 - `gtrk tool list [--json]` — list every tool (name/description/input/output/live price/status); `--json` emits a single-line machine-readable array (including dynamic `billingHint`/`pricing`). **Works without an API key**; prices are queried anonymously through a public endpoint, and on failure the full list is still shown with an unavailable marker.
-- `gtrk tool image_move ./photo.jpg [--json]` — image to camera move; artifacts land in `photo-image_move/`. `--param width=1080 --param height=1920` overrides the derived geometry.
+- `gtrk tool image_move ./photo.jpg [--motion zoom_in_center] [--json]` — image to camera move; artifacts land in `photo-image_move/`. `--motion` picks the camera move explicitly (26 values: 8 pans `up_to_down`/`down_to_up`/`left_to_right`/`right_to_left` plus four diagonals, 9 zoom-in anchors `zoom_in_{up,down,left,right,left_up,right_up,left_down,right_down,center}`, 9 zoom-out anchors `zoom_out_` at the same positions); when omitted the server picks one automatically. `--param width=1080 --param height=1920` overrides the derived geometry.
 - `gtrk tool image_matting ./portrait.jpg` / `gtrk tool video_matting ./clip.mp4` — image/video matting.
 - `gtrk tool image_blackborder_remove ./photo.jpg [--json]` — automatically crops black borders from one image.
 - `gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle [--json]` — image aspect conversion; omitting the canvas parameters uses the server defaults. Per the actual runtime contract the canvas mode accepts only `normal`, `rectangle` and `square`, not the `fit` from older docs.

package/README.md

@@ -88,18 +88,22 @@ gtrk transcript "D:/素材/采访视频.mp4"
 
 **每片一条龙（有先后的 SOP，对 agent 说话、每步你可介入——不是一次性并行铺完）**
 
-各车道**按次序铺、每步留检查点**：先铺 B-roll 定底层 → 你调好 → 再把 MG 叠上去 → 最后上 AI 再现。你对话推进每一步，agent 替你跑对应命令。
+各车道**按次序铺、每步留检查点**：先把 B-roll 底轨三源铺齐（影视素材 / 本地素材 / AI 情景片段）→ 你调好 → 抽帧核一遍画面构图 → 最后才把 MG（含 ov）叠上去。你对话推进每一步，agent 替你跑对应命令。
 
 | 步 | 你对 agent 说 | agent 替你做 | 你可以介入 |
 |:--:|---|---|---|
 | ① | 「帮我把这条口播**剪一版**」 | `/gtrk-oralcut` → `gtrk oralcut` → 三方工程 + transcript | — |
 | ② | 「接着**拆分镜派单**」 | `/gtrk-splitter` → `gtrk split` → `dispatch.json` 四车道 | 核对派单结果 |
-| ③ | 「**先铺 B-roll**」 | `/gtrk-matrix` → `gtrk matrix` → 候选轨铺入 | **opencut 里挑选/调整 B-roll**（小眼睛切换对比） |
-| ④ | 「B-roll 定了，**铺 MG**」 | `/gtrk-mg` → `gtrk mg` → MG 颗粒叠在 B-roll 之上 | 精修颗粒（opencut 手调） |
-| ⑤ | 「**上 AI 再现**」 | `/gtrk-ai-drama`（skill，无命令）→ 四段描述稿（中英分块） | 外部平台出片、片段手动回铺 |
+| ③ | 「**铺 B-roll 底轨**」（两条腿同一阶段） | `/gtrk-matrix` → `gtrk matrix` → 影视/本地素材候选轨铺入；`/gtrk-ai-drama`（skill，无命令）→ 四段描述稿（中英分块） | **opencut 里挑选/调整 B-roll**（小眼睛切换对比）；AI 片段去外部平台出片、**手动回铺** |
+| ④ | 「B-roll 齐了，**抽帧看看构图**」 | 对**三源合并后的最终底轨**抽帧（agent 纪律，无专属命令） | **确认构图**（主体位置 / 安全区 / 朝向 / 明暗） |
+| ⑤ | 「构图没问题，**铺 MG**」 | `/gtrk-mg` → `gtrk mg` → MG（含 ov）叠在已定稿的底轨之上 | 精修颗粒（opencut 手调） |
 | ⑥ | 「**出成片**」 | 客户端出片链（多车道合成 + 颗粒云渲 / 导剪映）；`gtrk render` 只出**主轨快照预览** | 客户端里精修定稿 |
 
-> 次序有理由：**MG 叠在 B-roll 之上**，要先把底层 B-roll 定下来、你满意了再铺 MG；AI 再现最后上。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
+> **次序有理由**：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版是「因势象形避主体」、**依赖底轨的最终画面构图**，所以三源（影视 / 本地 / AI）必须全落齐、构图核过，才轮到 MG。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
+>
+> ⚠️ **旧版文档曾写「④ 铺 MG → ⑤ 最后上 AI 再现」，理由是「越往后叠得越上层」——那是把「工序次序」误当成了「图层次序」，已于 2026-08-17 纠正。** 若你装的是旧版 skill，`gtrk upgrade` 刷新后才是新序。
+>
+> **AI 出片是异步的**：外部平台抽卡可能数天，严格串行会把 ④⑤ 无限期卡住。故进 ⑤ 的门是「**AI 片段已回铺 ∨ 你明示先跳过**」；走跳过时 agent 会把与 AI 区间相邻/重叠的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述给你。
 >
 > ③④⑤⑥ 都要**回到客户端**挑选 / 精修 / 回铺 / 出片——CLI 把料铺进 `.gtrk`，客户端把 `.gtrk` 出成片。详见下文「**CLI × 客户端**」小节。
 
@@ -137,7 +141,7 @@ CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再
 | **B-roll 候选挑选** | `gtrk matrix` 铺 N 条候选轨，用轨道**小眼睛**逐条切换对比、选定、删多余——审美取舍只能人在客户端做 |
 | **MG / 颗粒精修** | 客户端里 html-particle **活颗粒透明预览** + Transform/Blending/Effects 参数逐帧微调 |
 | **口播精剪** | 磁性主轨 ripple、手动微调切点 / 停顿 / 分屏 |
-| **AI 再现回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ⑤） |
+| **AI 再现回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ③——它属底轨阶段，MG 要等它落位后才铺） |
 | **最终出片** | 多车道合成（overlay / MG / particle 云渲叠起来）+ 剪映草稿导出，都在客户端出片链 |
 
 > **`gtrk render` ≠ 最终成片。** `gtrk render` 是本地 ffmpeg 出**主轨（口播粗剪）的快照预览**——只合主视频轨 + 音轨，**不合成 overlay（B-roll 候选）/ MG 颗粒 / AI 再现**。要出**真正的多车道成片**（各车道叠起来、颗粒云渲、导剪映草稿），走**客户端出片链**。一句话：**CLI 管「把料铺进工程」，客户端管「把工程出成片」。**
@@ -202,9 +206,10 @@ gtrk skills install --copy
 |:--:|---|---|---|
 | ① | `/gtrk-oralcut` | `gtrk oralcut` | 智能剪口播 → 客户端/剪映/PR 三方工程 + transcript |
 | ② | `/gtrk-splitter` | `gtrk split` | 拆分派单 → `dispatch.json`（A_ROLL/MG/AI_DRAMA/FILM_BROLL 四车道） |
-| ③ | `/gtrk-matrix` | `gtrk matrix` | **先铺 B-roll** 候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
-| ④ | `/gtrk-mg` | `gtrk mg` | **再铺 MG 颗粒**（叠在调好的 B-roll 之上） |
-| ⑤ | `/gtrk-ai-drama` | （无命令，纯创作） | **最后上 AI 再现**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
+| ③ | `/gtrk-matrix` | `gtrk matrix` | **B-roll 底轨·影视/本地素材腿**：铺候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
+| ③ | `/gtrk-ai-drama` | （无命令，纯创作） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
+| ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent 纪律硬门，供 ⑤ 的排版避让决策使用 |
+| ⑤ | `/gtrk-mg` | `gtrk mg` | **MG（含 ov）最后叠上**（叠在已定稿、构图已核的底轨之上） |
 | — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
 | — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4 |
 | 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |
@@ -212,7 +217,7 @@ gtrk skills install --copy
 | 🎵 | `/gtrk-music-visualizer` | `gtrk music-visualizer` | 一首歌 → 频谱可视化成片（模板 + 可选背景/封面 + 配色样式），**不在成片 SOP 序列内**、独立引流用 |
 | 🖼️ | `/gtrk-cover` | （无命令，纯创作） | 封面工作台两阶段：设计诊断 + 三尺寸中英双版文生图 Prompt → 用户外部平台抽图 → H5 排字工作台（拖拽/滚轮微调、一键导出多尺寸 PNG）。栏目封面审美经栏目配置 `style.skills`（`produces:"cover"`）注入；**不在成片 SOP 序列内**（投放配套的「第 0 阶段」） |
 
-> **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ④ 步（B-roll 定了才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
+> **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑤ 步（B-roll 三源全齐、构图核过才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
 > 上面 10 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装）——`/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 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
@@ -403,7 +408,7 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 
 | 工具 | 输入 | 产物 | 计费 | 状态 |
 |---|---|---|---|---|
-| `image_move` | 单张图片 | 运镜视频（几何按原图朝向推导：横 1920×1080 / 竖 1080×1920） | 运行前实时查询 | 已上线 |
+| `image_move` | 单张图片；可选 `--motion` 指定 26 种运镜之一 | 运镜视频（几何按原图朝向推导：横 1920×1080 / 竖 1080×1920） | 运行前实时查询 | 已上线 |
 | `image_matting` | 单张图片 | 透明背景 png（可 `--param` 请求背景底板） | 运行前实时查询 | 已上线 |
 | `image_blackborder_remove` | 单张本地图片 | 去黑边图片 | 运行前实时查询 | 已上线 |
 | `image_canvas_adapt` | 单张本地图片；可选目标宽高与 `normal` / `rectangle` / `square` | 比例适配图片 | 运行前实时查询 | 已上线 |
@@ -444,7 +449,7 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 去黑边、比例转换、防抖、蒸汽波、净化、超分、插帧七个公共视频工具只接受服务端当前 `video_ext`：`.mp4`、`.avi`、`.mpg`、`.mov`、`.flv`、`.mxf`、`.mpeg`、`.ogg`、`.3gp`、`.wmv`、`.h264`、`.m4v`、`.ts`；`.mkv` 与 `.webm` 会在本地拒绝。输入必须是本地文件路径，CLI 不负责下载远端视频。
 
 - `gtrk tool list [--json]` — 列全部工具（名称/说明/输入/产物/实时价格/状态）；`--json` 出单行机读数组（含动态 `billingHint`/`pricing`）。**无 API Key 也能跑**；价格通过公开接口匿名查询，失败仍列完整清单并标记暂不可用。
-- `gtrk tool image_move ./photo.jpg [--json]` — 图转运镜；产物落 `photo-image_move/`。`--param width=1080 --param height=1920` 覆盖推导几何。
+- `gtrk tool image_move ./photo.jpg [--motion zoom_in_center] [--json]` — 图转运镜；产物落 `photo-image_move/`。`--motion` 显式指定运镜方式（26 值：平移 8 `up_to_down`/`down_to_up`/`left_to_right`/`right_to_left` 及四对角线、放大锚点 9 `zoom_in_{up,down,left,right,left_up,right_up,left_down,right_down,center}`、缩小锚点 9 `zoom_out_` 同九方位），未传由云端自动选择；`--param width=1080 --param height=1920` 覆盖推导几何。
 - `gtrk tool image_matting ./portrait.jpg` / `gtrk tool video_matting ./clip.mp4` — 图片/视频抠像。
 - `gtrk tool image_blackborder_remove ./photo.jpg [--json]` — 自动裁去单张图片四周黑边。
 - `gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle [--json]` — 图片比例转换；省略画布参数时沿用服务端默认。画布模式按实际运行时契约只接受 `normal`、`rectangle`、`square`，不接受旧文档中的 `fit`。

package/dist/index.js

@@ -4604,6 +4604,67 @@ function noticeOnce(deps = {}) {
   return true;
 }
 
+// src/lib/first-run-tutorial.ts
+var TUTORIAL_URL = "https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk";
+var QUICK_START_URL = "https://cloud.ai-mcn.tv/zh-CN/docs/quick-start";
+var FIRST_RUN_USAGE_LINES = [
+  '① 命令行直接剪：gtrk oralcut "<毛片.mp4>" --script "<文字稿.txt>"（无稿就别加 --script）',
+  "② 刷新你常用的 AI Agent，在它的 Skills 入口选择或点名 gtrk-oralcut；不同客户端也都可以直接描述剪辑需求触发。"
+];
+var FIRST_RUN_TUTORIAL_LINES = [
+  "\uD83D\uDC4B 第一次用 gtrk？三步跑通第一条口播：",
+  "   1) gtrk install   —— 装依赖与运行时资产",
+  "   2) gtrk init      —— 填 API Key、认剪映草稿目录（跑完会自动体检）",
+  `   3) ${FIRST_RUN_USAGE_LINES[0]}`,
+  `   使用教程 ${TUTORIAL_URL}`,
+  `   快速开始 ${QUICK_START_URL}`
+];
+function traceFailedLine2() {
+  return `   首跑留痕未能写入 ${configPath()}：不影响本次执行，下次运行会再提示一次`;
+}
+var printedInThisProcess2 = false;
+function looksOnboarded(cfg) {
+  return typeof cfg.apiKey === "string" && cfg.apiKey.trim().length > 0;
+}
+function firstRunTutorialOnce(deps = {}) {
+  const write = deps.write ?? ((chunk) => void process.stderr.write(chunk));
+  let cfg;
+  try {
+    cfg = (deps.readConfig ?? readUserConfig)();
+  } catch {
+    cfg = {};
+  }
+  const stamp = () => {
+    try {
+      (deps.writeConfig ?? writeUserConfig)({
+        firstRunNoticeAt: (deps.now ?? (() => new Date))().toISOString()
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (typeof cfg.firstRunNoticeAt === "string" && cfg.firstRunNoticeAt.length > 0)
+    return false;
+  if (looksOnboarded(cfg)) {
+    stamp();
+    return false;
+  }
+  if (printedInThisProcess2)
+    return false;
+  const [head, ...rest] = FIRST_RUN_TUTORIAL_LINES;
+  write(`\x1B[36m${head}\x1B[0m
+\x1B[2m${rest.join(`
+`)}\x1B[0m
+`);
+  printedInThisProcess2 = true;
+  if (!stamp()) {
+    write(`\x1B[2m${traceFailedLine2()}\x1B[0m
+`);
+  }
+  return true;
+}
+
 // src/lib/jianying.ts
 import { join as join4, resolve as resolve2 } from "node:path";
 import { existsSync as existsSync4 } from "node:fs";
@@ -6201,8 +6262,8 @@ async function afterConfigDoctor() {
   const healthy = await runDoctor();
   if (healthy) {
     log.step("装好了！两种用法任选：");
-    log.info('① 命令行直接剪：gtrk oralcut "<毛片.mp4>" --script "<文字稿.txt>"（无稿就别加 --script）');
-    log.info("② 刷新你常用的 AI Agent，在它的 Skills 入口选择或点名 gtrk-oralcut；不同客户端也都可以直接描述剪辑需求触发。");
+    for (const line2 of FIRST_RUN_USAGE_LINES)
+      log.info(line2);
     log.info("想有自己栏目的风格体系？在 agent 里跑 /gtrk-style-maker 建一次「你的厨房」（skill 家族 + 栏目配置）；不建就直接用默认，照常开剪。");
   } else {
     log.warn("上面体检有项没通，按提示处理好再开剪（多半是 API Key 或剪映目录）。");
@@ -7234,9 +7295,10 @@ function layBrollTracks(opts) {
       }
     }
   }
+  const hasSelfProducedContentInPlace = createdTracks.length > 0 || rebasedBandTracks.length > 0 || transitionKeptIndices.length > 0;
   let blackTrack = null;
   let blackTrackObj = null;
-  if (blackBedOn && (createdTracks.length > 0 || rebasedBandTracks.length > 0)) {
+  if (blackBedOn && hasSelfProducedContentInPlace) {
     if (!isLayoutableCanvas([canvas[0], canvas[1]])) {
       warnings.push(`画布尺寸非法（${canvas[0]}x${canvas[1]}），跳过铺纯黑底轨（候选轨照常铺）。`);
     } else {
@@ -7269,6 +7331,9 @@ function layBrollTracks(opts) {
       }
     }
   }
+  if (blackBedOn && hasSelfProducedContentInPlace && blackTrack === null) {
+    warnings.push(`异常：本轮有 B-roll 内容轨在场、也没有 --no-black-bed，却没能铺出纯黑底垫轨 —— ` + `这些 B-roll 段落底下会直接露出口播 A-roll。请回报此告警（含本轮命令行）以便定位。`);
+  }
   let blackBedHoles = [];
   let blackBedHoleSec = 0;
   if (blackTrack !== null) {
@@ -9164,6 +9229,34 @@ function probeImageDims(inputAbs, ffmpegPath) {
   } catch {}
   return;
 }
+var IMAGE_MOVE_MOTIONS = new Set([
+  "up_to_down",
+  "down_to_up",
+  "left_to_right",
+  "right_to_left",
+  "right_up_to_left_down",
+  "left_up_to_right_down",
+  "right_down_to_left_up",
+  "left_down_to_right_up",
+  "zoom_in_up",
+  "zoom_in_down",
+  "zoom_in_left",
+  "zoom_in_right",
+  "zoom_in_left_up",
+  "zoom_in_right_up",
+  "zoom_in_left_down",
+  "zoom_in_right_down",
+  "zoom_in_center",
+  "zoom_out_up",
+  "zoom_out_down",
+  "zoom_out_left",
+  "zoom_out_right",
+  "zoom_out_left_up",
+  "zoom_out_right_up",
+  "zoom_out_left_down",
+  "zoom_out_right_down",
+  "zoom_out_center"
+]);
 var imageMove = {
   name: "image_move",
   title: "图转运镜",
@@ -9174,8 +9267,21 @@ var imageMove = {
   outputHint: "运镜视频",
   enabled: true,
   taskType: "image_move",
+  options: [
+    {
+      flag: "--motion <value>",
+      desc: "运镜方式（未传则云端自动选择；显式指定后同图同参重跑结果一致）。" + "平移 8：up_to_down/down_to_up/left_to_right/right_to_left 及四条对角线；" + "放大锚点 9：zoom_in_{up,down,left,right,left_up,right_up,left_down,right_down,center}；" + "缩小锚点 9：zoom_out_ 同九方位"
+    }
+  ],
   buildPayload(fileId, ctx) {
     const p = { file_id: fileId };
+    if (ctx.opts.motion != null) {
+      const value = String(ctx.opts.motion);
+      if (!IMAGE_MOVE_MOTIONS.has(value)) {
+        throw new Error(`--motion 不支持「${value}」。合法值：平移 8（up_to_down/down_to_up/left_to_right/right_to_left/` + "right_up_to_left_down/left_up_to_right_down/right_down_to_left_up/left_down_to_right_up）、" + "放大锚点 9（zoom_in_{up,down,left,right,left_up,right_up,left_down,right_down,center}）、" + "缩小锚点 9（zoom_out_ 同九方位）");
+      }
+      p.motion = value;
+    }
     const explicit = ctx.extraParams.width != null || ctx.extraParams.height != null;
     if (!explicit && ctx.inputAbs) {
       const dims = probeImageDims(ctx.inputAbs, ctx.ffmpegPath);
@@ -11247,7 +11353,23 @@ async function runOralCutResult(taskId, opts) {
 
 // src/commands/upgrade.ts
 import { spawnSync as spawnSync5 } from "node:child_process";
-var CLIENT_UPGRADE = "irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex";
+
+// src/lib/desktop-client-hint.ts
+var CLIENT_UPGRADE_CMD = "irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex";
+var CLIENT_PLATFORMS = ["win32"];
+function hasDesktopClient(platform = process.platform) {
+  return CLIENT_PLATFORMS.includes(platform);
+}
+function desktopClientUpgradeHint(prefix, platform = process.platform) {
+  return hasDesktopClient(platform) ? `${prefix}：${CLIENT_UPGRADE_CMD}` : null;
+}
+
+// src/commands/upgrade.ts
+function noteClientUpgrade(prefix) {
+  const hint = desktopClientUpgradeHint(prefix);
+  if (hint)
+    log.info(hint);
+}
 function run(cmd) {
   const r = spawnSync5(cmd, { stdio: "inherit", shell: true });
   return r.status ?? 1;
@@ -11259,12 +11381,12 @@ function registerUpgrade(program2) {
     const latest = await latestVersion();
     if (!latest) {
       log.warn("查不到最新版本（网络问题？）。手动升级：npm i -g @gitruck/cli@latest");
-      log.info(`客户端（桌面端）升级：${CLIENT_UPGRADE}`);
+      noteClientUpgrade("客户端（桌面端）升级");
       return;
     }
     if (cmpSemver(latest, cur) <= 0) {
       log.ok(`已是最新版 v${cur}。`);
-      log.info(`客户端（桌面端）如需升级：${CLIENT_UPGRADE}`);
+      noteClientUpgrade("客户端（桌面端）如需升级");
       return;
     }
     log.info(`发现新版本 v${latest}（当前 v${cur}）。`);
@@ -11283,7 +11405,7 @@ function registerUpgrade(program2) {
       log.warn("skill 没刷成，手动跑一次：gtrk skills install");
     }
     log.ok(`已升级到 v${latest}。配置原样保留，直接接着用即可（gtrk doctor 可自检）。`);
-    log.info(`客户端（桌面端）如需一起升级：${CLIENT_UPGRADE}`);
+    noteClientUpgrade("客户端（桌面端）如需一起升级");
   });
 }
 
@@ -18622,6 +18744,9 @@ migrateLegacyHome();
 var { version } = JSON.parse(readFileSync8(join35(packageRoot(), "package.json"), "utf8"));
 var program2 = new Command;
 program2.name("gtrk").description("同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通").version(version);
+program2.hook("preAction", () => {
+  firstRunTutorialOnce();
+});
 registerInstall(program2);
 registerInit(program2);
 registerOralCut(program2);

package/package.json

@@ -1,66 +1,66 @@
-{
-  "name": "@gitruck/cli",
-  "version": "1.0.1",
-  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
-  "license": "MIT",
-  "author": "Gitruck (同合云)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Gitruck/cli.git"
-  },
-  "homepage": "https://github.com/Gitruck/cli#readme",
-  "bugs": {
-    "url": "https://github.com/Gitruck/cli/issues"
-  },
-  "type": "module",
-  "bin": {
-    "gtrk": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "assets",
-    "skills",
-    "contracts",
-    "AGENT.md",
-    "README.md",
-    "README.en.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20.6"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "gitruck",
-    "同合云",
-    "video",
-    "oral-cut",
-    "口播剪辑",
-    "cli",
-    "jianying",
-    "剪映",
-    "agent"
-  ],
-  "scripts": {
-    "gtrk": "bun run src/index.ts",
-    "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/compliance-notice.ts 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/jianying.ts src/lib/clip-brief.ts src/lib/media.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/embed-client.ts src/lib/describe.ts src/lib/local-index.ts src/lib/local-search.ts src/lib/image-move.ts src/lib/cloud-render-guard.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 src/lib/runtime-assets.ts --bundle --platform=node --format=esm --external:bun:sqlite --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 --external:bun:sqlite --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 --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\"",
-    "openspec:gate": "node openspec/gate.mjs"
-  },
-  "devDependencies": {
-    "@xmldom/xmldom": "^0.9.6",
-    "bun-types": "^1.1.0",
-    "commander": "^12.1.0",
-    "esbuild": "^0.28.1",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "hash-wasm": "^4.12.0",
-    "jszip": "^3.10.1"
-  }
-}
+{
+  "name": "@gitruck/cli",
+  "version": "1.0.2",
+  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
+  "license": "MIT",
+  "author": "Gitruck (同合云)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gitruck/cli.git"
+  },
+  "homepage": "https://github.com/Gitruck/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Gitruck/cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "gtrk": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "skills",
+    "contracts",
+    "AGENT.md",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "gitruck",
+    "同合云",
+    "video",
+    "oral-cut",
+    "口播剪辑",
+    "cli",
+    "jianying",
+    "剪映",
+    "agent"
+  ],
+  "scripts": {
+    "gtrk": "bun run src/index.ts",
+    "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/compliance-notice.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts 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/jianying.ts src/lib/clip-brief.ts src/lib/media.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/embed-client.ts src/lib/describe.ts src/lib/local-index.ts src/lib/local-search.ts src/lib/image-move.ts src/lib/cloud-render-guard.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 src/lib/runtime-assets.ts --bundle --platform=node --format=esm --external:bun:sqlite --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 --external:bun:sqlite --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 --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\"",
+    "openspec:gate": "node openspec/gate.mjs"
+  },
+  "devDependencies": {
+    "@xmldom/xmldom": "^0.9.6",
+    "bun-types": "^1.1.0",
+    "commander": "^12.1.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "hash-wasm": "^4.12.0",
+    "jszip": "^3.10.1"
+  }
+}