@gitruck/cli 1.3.6 → 1.3.8

package/docs/reference.md

@@ -23,7 +23,7 @@
 | ![在 Agent 中调用 gtrk 示例 1](../assets/agent-example-1.png) | ![在 Agent 中调用 gtrk 示例 2](../assets/agent-example-2.png) |
 | ![在 Agent 中调用 gtrk 示例 3](../assets/agent-example-3.png) | ![在 Agent 中调用 gtrk 示例 4](../assets/agent-example-4.png) |
 
-`gtrk install` 会把 19 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-composite`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`·`gtrk-cover`·`gtrk-travel-recap`·`gtrk-live-slicing`·`gtrk-talking-head`·`gtrk-narration`·`gtrk-voiceover`·`gtrk-food-recap`·`gtrk-vlog-docu`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
+`gtrk install` 会把 20 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-composite`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`·`gtrk-cover`·`gtrk-travel-recap`·`gtrk-live-slicing`·`gtrk-talking-head`·`gtrk-narration`·`gtrk-voiceover`·`gtrk-food-recap`·`gtrk-vlog-docu`·`gtrk-ref-reading`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
 
 默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
 
@@ -72,6 +72,7 @@ gtrk skills install --copy
 | ⑤ | `/gtrk-mg` | `gtrk mg` | **MG（含 ov）最后叠上**（叠在已定稿、构图已核的底轨之上） |
 | ⑥ | `/gtrk-composite` | `gtrk composite` | **合成层**（字幕之后、出片之前）：把选定时间窗做成合成颗粒——一段时间内的整个画面由一颗代码颗粒接管（逐句换画面、对照并排、并列卡片、字幕排版），讲者与 B-roll 作为槽位画进去；入口三选一（整片铺满 / AI 判定 / 指定区间），候选显示在客户端大纲 CP 行；纯本地零计费。出片时由 `gtrk composite bake` 在本机烘焙成视频（首次需 `gtrk deps install --browser`） |
 | — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
+| 🔍 | `/gtrk-ref-reading` | `gtrk transcript` + `gtrk media` | **参考片精读**：别人的一条视频 → 字级转写 + 带台词标签的网格 + 关键动效逐帧 → 按「系统」记每个设计事件对着哪句话，落成 `ANALYSIS.md` / `TIMELINE.md` / `PROGRESS.md`；读完可交 `/gtrk-style-maker` 建栏目。看片命令纯本地零计费（只有转写一步计费），**不在成片 SOP 序列内** |
 | ③′ | 「**屏录画中画**」 | `gtrk pip lay` | 把口播粗剪的切点镜像到同步录的屏录 / 第二机位，铺屏录满幅轨 + 人像画中画副本轨（圆 / 圆角方 / 爱心 / 菱形 / 星形蒙版，可圆角）；纯本地零计费；低置信时产对齐工程让客户端拖齐后 `--resume` |
 | — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4（含 overlay 与 MG 颗粒；颗粒未命中缓存时云渲计费，`--no-particles` 可跳过） |
 | ✂️ | `/gtrk-long2short` | `gtrk long2short` | 长剪短·粗剪：长视频语义选段+跳剪 → 逐 clip 出客户端/剪映/PR 三方工程（毛片不上传），**不在成片 SOP 序列内**、随时可独立用 |
@@ -88,7 +89,7 @@ gtrk skills install --copy
 | 🧭 | `/gtrk-vlog-docu` | 编排 `gtrk transcript` → `tool audio_tts_clone` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **Vlog 纪实图纸**：一批现场素材 → 素材理解、选档写稿、一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端可出片工程；「现场同期声 × 后期旁白」双声道交替，区别于纯口播链与纯配音链 |
 
 > **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑤ 步（B-roll 三源全齐、构图核过才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
-> 上面 19 个 `/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 里。
+> 上面 20 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，`/gtrk-ref-reading` 管参考片精读，五者都不属成片 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 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
@@ -183,6 +184,36 @@ GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4   # 环境变量，临时关一次（
 
 当前状态随时可查：`gtrk doctor` 的「崩溃自动上报」一行会写明开 / 关，以及关是被谁关的。关闭后崩溃的呈现与退出码**与开启时完全一致**——它只影响发不发那条报告。
 
+### 使用统计与关闭方式
+
+gtrk 会发送匿名的使用统计，帮我们知道哪些命令有人用、失败率多少、新版本多久铺开。**默认开启，首次配置时会告知一次**（紧跟崩溃报告那一行）。
+
+**每条命令发送的内容只有这些**：命令名（注册名，如 `matrix.search`，不含任何参数）、成功或失败、失败时的错误码或分类（如 `ENOENT`，不含错误消息原文）、耗时所在的区间、调用方类型（终端，或 agent 名称，如 `claude-code`）、CLI 版本、系统与架构、Node 主版本、是否配置了 API Key（只记是 / 否）。
+
+**明确不发送**：命令参数与选项值、文件名与路径、素材与工程内容、你的文稿、API Key、错误消息原文、设备标识、主机名、账号信息。统计服务会接触到你的 IP 地址，只用来判断国家或地区，不保存 IP 本身。
+
+**不拖慢命令**：命令结束时只往本机 `~/.gitruck/usage-queue.jsonl` 追加一行，由一个后台进程去发，命令照常立即退出。发不出去的留在本机（最多 200 条、7 天），下次再发。
+
+**这些情况不发**：从源码运行、跑单元测试、设置了 `CI` 环境变量。
+
+四种关法（任选其一，都是即时生效）：
+
+```bash
+gtrk init --no-usage-stats          # 写进配置，永久关（同时删掉本机还没发出去的）
+```
+
+```bash
+GITRUCK_USAGE_STATS=0 gtrk patch move …   # 环境变量，临时关一次（优先级高于配置）
+```
+
+```bash
+DO_NOT_TRACK=1 gtrk …   # 业界通用的「不追踪」约定，同样生效
+```
+
+或直接在 `~/.gitruck/config.json` 里写 `"usageAnalytics": false`。
+
+当前状态随时可查：`gtrk doctor` 的「使用统计」一行会写明开 / 关、关是被谁关的，以及当前环境发不发。关闭后命令的输出与退出码**与开启时完全一致**。
+
 ---
 
 ## 命令参考
@@ -205,6 +236,8 @@ GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4   # 环境变量，临时关一次（
 | `--platforms <list>` | 逗号分隔 `youtube,vimeo,tiktok,bilibili`，仅配合 `--online`；不指定时查询已登记的四个平台。实际结果仍取决于服务与来源可访问性 |
 | `--online-session <name>` | 外部检索批次名，仅配合 `--online` 且不可为空；同批次续跑，换名称发起新搜索，可能产生新任务与费用 |
 
+派单消费时若这一轮**零可铺候选**而工程里已有带候选的 `split/broll-plan.json`（例如上一轮云端或本地 plan），既有 plan 不会被覆盖：本轮 plan（含逐条报错与待核候选）另存为 `split/broll-plan.online-attempt.json`，`--json` 结果带 `plan_kept`，`planPath` 仍指既有 plan。退出码照旧非 0。
+
 ### `gtrk transcript <本地视频|配音音频>`
 
 把本地视频或配音音频转为一个多层级的 Markdown 文字稿。只接受本地文件路径：视频在本机抽取、音频在本机转码为 16 kHz 单声道音频，只上传音频衍生物，原文件不会上传，也不支持 URL 或平台视频下载。
@@ -224,6 +257,31 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 
 > `--json` 时另在源文件旁产一份句级时码 `<名>-transcript.json`（`utterances[]{id,text,st,ed}` + `material_id` + `text_hash` + `duration`，与 `gtrk split` 的 transcript 结构逐字段对齐），可直接被 `gtrk project init --transcript` 兜底路消费。**TTS 合成的配音勿走本零件重跑 ASR**——`gtrk project init --tts-task` 直取服务端句级时码，零 ASR 零额外计费。
 
+### `gtrk media <子命令>` — 本地看片（参考片精读取证）
+
+按时码或台词看任意本地视频：带台词标签的抽帧网格、逐帧看动效、视觉变化候选。**纯本地、零计费、不联网、不要 API Key**；只读本地文件，不下载链接。由 `/gtrk-ref-reading` 驱动，也可用来复核自家成片。
+
+| 子命令 | 做什么 |
+|---|---|
+| `probe <视频>` | 时长、显示尺寸（计入像素宽高比与旋转）、帧率与 VFR、有无音轨 |
+| `lines <转写稿>` | 逐句 `u<id> 起–止 文本`；`--find <台词>` 列出每处出现与字级起止 |
+| `frames <视频>` | 按 `--at` / `--every` / `--frames` / `--every-frame` 取单帧；带 `--transcript` 或 `--label` 时帧下方加标签 |
+| `tile <视频>` | 一张带标签的网格（≤60 格） |
+| `tiles <视频>` | 分页网格（`--cols × --rows`，缺省 3×3）；`--ranges <json>` 一次看多段；`--every-frame` 每段连续解码、保留每一原始帧 |
+| `boundaries <视频>` | 视觉变化候选（`--rate` 缺省 12、`--threshold` 缺省 0.1、`--min-gap` 合并近邻）；带 `--transcript` 时标注对着哪句话。**是机械证据，不是镜头判定** |
+| `cut <视频>` | 截一段证据片（`.mp4/.mov/.mkv`） |
+
+```bash
+gtrk media tiles "参考片.mp4" --frames 48 --cols 6 --rows 4 --cell 320 --transcript "精读/transcript.json" -o "精读/evidence/overview"
+gtrk media tiles "参考片.mp4" --around "买不动" --occurrence 1 --every-frame --cols 6 --rows 4 --transcript "精读/transcript.json" -o "精读/evidence/motion/stamp"
+gtrk media boundaries "参考片.mp4" --rate 4 --threshold 0.12 --transcript "精读/transcript.json" -o "精读/evidence/boundaries.json"
+```
+
+- **区间**：`--start/--end`（秒或 `[hh:]mm:ss.mmm`），或 `--around <台词> [--occurrence n] [--padding s]` 按台词定位（须配 `--transcript`；台词多处出现时必须指定第几处，`lines --find` 可先列出）。
+- **转写稿**：`gtrk transcript --json` 的产物（v1，含字级时码）原生可用，也认 `hypit.transcript@1`。转写稿须是这条视频的——时长 / 文件名对不上会在 stderr 告警。
+- **标签**（画面下方，不遮原片字幕与图形）：源片秒 · 时码（逐帧加帧号）· 句号 / 正在读的字与字级起止 / 所在整句（当前字高亮）。无字时写「此刻无字在读」「句间空隙」，不推断静音。标签用 libass 画，ffmpeg 缺 `ass` 滤镜时报错并指向 `gtrk deps install --ffmpeg`。
+- **落点**：`-o` 必填，不落当前目录或源片旁；已存在不覆盖，`--force` 只覆盖本命令族的旧产物。`frames` / `tiles` 的产物目录含 `index.json`，逐格记录文件、时间、字与句号。逐帧单次上限 1800 帧。
+
 ### `gtrk oralcut <毛片>`
 
 | 参数 | 作用 | 缺省 |
@@ -396,7 +454,7 @@ gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt -
 >
 > **素材落盘自检**：写回工程之后只读检查 `materials[].path` 是否落盘。相对路径以 `.gtrk` 文件所在目录（`<产物目录>/gtrk/`）为基准解析。`--json` 出 `integrity:{ checked, counts, dangling:[…], danglingReferenced, danglingOrphan, external:[…], noPathIds:[…] }`；`dangling` 是登记存在但文件缺失的素材，并标出是否被时间线引用，绝对路径缺失另计 `external`，http(s) 素材只计数且不发网络请求。检查只告知，不改 `ok`、退出码、素材条目或文件；修复悬空引用请在客户端重新确认原片或删除对应 clip。未写回的运行（`--lay 0` / 拒铺 / 工程缺失）不出 `integrity` 字段。
 >
-> **片段底板（缺省）**：每个候选片段自带纯黑底（gtrk 契约 `background_fill`，窄画幅 / 缩小时不露下层口播），每条候选轨在已落成的 beat 包络内把自己的空档补成纯黑片——`--lay 2` 时只留任一条可见也不露口播；音频驱动工程（无口播）不补。`--json` 出 `lay.bed`（`fill`）与 `lay.bed_fill`（补了几段、几秒）。没有任何 B-roll 的纯黑时段记作空洞：`lay.blackBedHoleSec` / `lay.blackBedHoles` 恒出，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时给非致命告警，可调 `--score-floor` 或在客户端补片。补片素材落在 `assets/builtin/solid-000000-<W>x<H>.png` 并幂等复用。
+> **片段底板（缺省）**：每个候选片段自带纯黑底（gtrk 契约 `background_fill`，窄画幅 / 缩小时不露下层口播），每条候选轨在已落成的 beat 包络内把自己的空档补成纯黑片——`--lay 2` 时只留任一条可见也不露口播；音频驱动工程（无口播）不补。`--json` 出 `lay.bed`（`fill`）与 `lay.bed_fill`（补了几段、几秒）。没有任何 B-roll 的纯黑时段记作空洞：`lay.blackBedHoleSec` / `lay.blackBedHoles` 恒出，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时给非致命告警，可调 `--score-floor` 或在客户端补片。补片素材落在 `assets/builtin/solid-000000-<W>x<H>.png` 并幂等复用。短于 1.2s 的空档（片段之间 1–2 帧的缝、锚定镜头前的空档）先在源窗余量内并进相邻片段（不越检索段界、段内切点与黑段），并不掉的才补黑，并在 `lay.flash_gaps.kept` 与告警里逐段点名。
 >
 > **纯黑底垫轨（`--black-bed`，旧形态）**：在候选轨之下、口播主轨之上铺满已落成的 beat 包络，候选片段不带底板；空洞口径与数值同上。老工程里已有的黑底轨在下次缺省重铺时被换成片段底板。
 
@@ -448,22 +506,23 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 | `--yes` | render 模式：跳过计费预估确认 | 关 |
 | `--json` | 机读：人读日志转 stderr，stdout 只输出结果 JSON | 关 |
 
-- **铺轨**（`gtrk mg --project <dir>`）：读 `dispatch.mg` → 逐 beat 从 `<project>/mg/<composition_id>.html` 取源颗粒 → lint → 铺进 `beat_track`，把 `struct_meta.mg` 原子写回 `.gtrk`（幂等登记自产轨 `lay_tracks`，重铺先剥旧自产物再 append、用户手加轨零连带）。「透明叠加 / 满屏底层」由颗粒 HTML 根 `background` 反推的 `opaque` 决定。缺 HTML / lint 失败的 beat 计入 `skipped`、不拦其余。
+- **铺轨**（`gtrk mg --project <dir>`）：读 `dispatch.mg` → 逐 beat 从 `<project>/mg/<composition_id>.html` 取源颗粒 → lint → 铺进 `beat_track`，把 `struct_meta.mg` 原子写回 `.gtrk`（幂等登记自产轨 `lay_tracks`，重铺先剥旧自产物再 append、用户手加轨零连带）。「透明叠加 / 满屏底层」由颗粒 HTML 根 `background` 反推的 `opaque` 决定。lint 按工程 `video_size` 比对颗粒画幅比例，跨比例的颗粒（如竖屏工程里声明 1920×1080 的颗粒）判 `1-canvas-match` 致命、不铺。缺 HTML / lint 失败的 beat 计入 `skipped`、不拦其余。
   - **剥离面 ≠ 「本次铺什么」，也 ≠ 「登记轨全集」**：`--only <beat>` **只剥命中的那几颗**（真增量合并）——轨上其余已铺颗粒的 clip / 素材 / 登记条目**原样保留**，连同用户在 opencut 对它们的手调（保留的是既有 clip 原件，非照登记重建，故透明度 `opaque` 不会丢）；这些保留条目**不重新 lint、不重新复制源 HTML**（工程自包含，`<project>/mg/` 下源文件删了也不影响）。全量重铺仍是「剥净再整轨重建」，**唯一例外**是本次派单里有、却因缺 HTML / lint 未过 / 重投影后零存活而**没铺成**的那几颗——它们上一轮的 clip 保留在轨上（不因为新的做坏了就把旧的也毁掉）；反之**派单里已不存在**的已铺条目仍照剥（计划变更 ≠ 做坏了）。要连其余已铺颗粒一起剥掉重来：`--replace-all` 显式授权。
   - **素材表不囤积**：素材按「自产身份 × 零引用」剥离（自产 = `mg-`/`rrv-` 前缀，或位于 CLI 独占的 `assets/mg/` 且文件名在自产登记里），不依赖客户端可改写的 `html_material` 前缀。`mg-` 素材数与轨上颗粒数保持一致；重复或孤儿条目会清掉。非自产素材、仍被存活 clip 引用的自产素材，以及盘上 `assets/mg/` 的 HTML 副本都不动。
   - **「一条都没定位到」不是清空指令**：`--only` 打空、`dispatch.mg` 为空/缺失、或本次条目全被 skip，**而轨上已有已铺颗粒**时，同样拒绝写回（那是派单或选择器出问题的信号）。确要清空加 `--replace-all`。首次铺轨（轨上本就没有已铺条目）不受此限，照常走完报 `laid=0`。
   - **槽位窗口现场重投影**：铺轨与 lint 之前先用「`transcript` × 当刻 `.gtrk`」重算每条队列条目的 `[track_st, track_ed]`，之后 lint 的坑位包络（铁律⑦）与落轨 clip 时长一律以重算值为准（`--only` 同守；aux 派生颗粒按**自己的** span 重投影，不与主 beat 窗口混同）。`dispatch.mg` 里的时码只是**投影时刻快照**，仅在重投影不可行时兜底——**改完口播轨直接铺即可，不必先重跑 `gtrk split`**。`--json` 恒出 `reprojection:{mode,degraded,reason?,drifted,max_offset,shrunk,dropped}`（`--lint-only` 也有）。重投影后**零存活**的条目 skip 并计入 `skipped`（不复制 HTML、不按快照铺回去）；重投影不可行（transcript 缺失 / 工程定位不到 / 主轨查不到口播素材）→ 降级用快照 + 告警 + `--json` 标注，退出码不变；工程**非 v1** 的既有行为不变（铺轨路径版本门非 0 退出、`--lint-only` 照旧出报告）。铺轨成功会把本次时码来源（`timecode_source` / `reprojected_at`）纯追加登记进 `struct_meta.mg`。
-- **lint**（`gtrk mg lint <颗粒.html> [--dispatch <path>]`）：纯本地静态校验颗粒 HTML 的铁律机器可判定子集（`<template>` 包裹、`data-composition-id` + 1920×1080、`gsap.timeline({ paused: true })`、`window.__timelines` 注册、无 `Math.random` / `Date.now`、自包含无相对外链、根 `background` 与 `opaque` 自洽…）；给 `--dispatch` 时校验 `composition_id` 命中派单。任一致命项非 0 退出并逐条报因。
+- **lint**（`gtrk mg lint <颗粒.html> [--dispatch <path>]`）：纯本地静态校验颗粒 HTML 的铁律机器可判定子集（`<template>` 包裹、`data-composition-id` + 根 `data-width` / `data-height`（正整数）、`gsap.timeline({ paused: true })`、`window.__timelines` 注册、无 `Math.random` / `Date.now`、自包含无相对外链、根 `background` 与 `opaque` 自洽…）；给 `--dispatch` 时校验 `composition_id` 命中派单，并按工程 `.gtrk` 的 `video_size` 比对颗粒声明的画幅比例（`1-canvas-match`：跨比例致命，同比例不同尺寸放行，比例差 7% 以内视为同比例——DCI 4K 这类 17:9 工程里的 16:9 颗粒放行、接受 6.7% 横向拉伸；`--project` 同样）；裸 lint 不知道目标工程，只核正整数。任一致命项非 0 退出并逐条报因。
   - **期望 id 一致性**（`1-cid-expect`，**致命**）：HTML 内 `data-composition-id` 必须等于期望 id（铺轨=该条派单的 `composition_id`；`mg lint`=文件名，仅当它命中派单或形如 `…-B<数字>[-aux<n>]` 时比对，`./tmp.html` 这类改过名的副本不比对）。防的是「复制 `<id>.html` 改名时漏改内部 id」——落轨会写出以文件名命名的 clip/material，而文件注册的是另一个 `__timelines` 键、还与同名颗粒抢同一个样式作用域。
   - **铁律⑦ tl 总长估长**（`7-fill-slot` / `7-no-estimate` / `7-infinite-repeat`，**恒非致命、不拦铺轨**）：已知坑位包络时（铺轨逐颗；`mg lint --dispatch` 命中派单条目）对 GSAP 时间线做**静态下界估算**——逐调用降级，能解析的计入（`duration×(repeat+1) + repeatDelay×repeat`，`yoyo` 不加时长），表达式 position / 非字面量 duration 那条**跳过不计**（忽略若干调用仍是合法下界）。估长 < 包络 → 告警；一条都算不出 → 显式提示「无法静态估长，铁律⑦未校验，须真引擎 seek 验收」（**不静默**，「算不出」与「算过且通过」在输出上可区分）；含 `repeat:-1` → 告警「无限循环令总长 Infinity、铁律⑦不可静态验证，请改按坑位算死的有限 repeat」。真判据永远是渲染引擎逐帧，本项只做提醒层。
   - **铁律⑧重复图元合并**（`8-primitive-merge`，**恒非致命、不拦铺轨**）：识别「循环体内创建，或由循环调用具名工厂创建；落到同一父节点；且没有逐元素动画驱动」的可合并 `line` / `rect` / `path` / `polyline` / `polygon` 批次。同一父节点的纯数字循环 trip count 累加后 **≥ 8** 才报数；边界含 `.length` / 具名常量而算不出时仍报「条数未知」，不做常量折叠；逐元素 `gsap.set` / tween 或被 tween 首实参使用的元素数组会被排除。本项只提示「这里有一批可**无损**合并的重复图元，合并后画面逐像素不变」，**不是风险判定**：命中不代表该颗粒会复现缺陷，未命中也不代表安全，真判据仍是真渲染出片抽帧。
   - **回调与 seek 语义**（`x-callback-driven` / `x-engine-api-override` / `x-raf-interval`，**恒非致命、不拦铺轨**）：对齐契约同名一节。引擎定帧 MUST 使用 `seek(t,false)` / `time(t)` / `progress(p)`；颗粒可用时间线回调驱动画面，但不得覆写 `tl.seek` 或替换 `window.__timelines[…]`。三项 lint 只作提醒，不要求作者添加垫片。
 - **status**（`gtrk mg status --project <dir>`）：汇总 MG 流水线——`dispatch.mg` beat 总数 / 已产源 HTML 数 / 已铺进 `.gtrk` 数，并逐 beat 标注（缺 HTML / 已产未铺 / 已铺）。
-- **render**（`gtrk mg render <颗粒.html> --duration <sec> [--out <dir>] [--yes]`）：**脱离工程**把单颗颗粒云渲成剪映可读的 qtrle 透明 alpha MOV（精剪补给口——粗剪导剪映后缺一颗动态图，不回客户端就能补）。链路 = lint 前置（包络 = `--duration`，任一致命项本地拦截、零提交零计费）→ **计费预估确认**（实时查价；CLI 无本地 HTML 渲染引擎，独立颗粒唯一路 = 云渲计费任务，`--yes` 跳过确认）→ 内联提交云端 → `<composition_id>.mov` 落盘 + `task.json`/`result.json` 面包屑（崩溃可凭 task_id 恢复）。**射程**：首发只出 qtrle（`--format webm` 明确拒绝，剪映不吃 VP8-alpha）、只收 1920×1080 颗粒（契约未开竖屏/异形口）、`--duration` 必填。产物不进 `.gtrk`、不写剪映草稿目录；qtrle 无损体积偏大，适合秒级颗粒。注意与 `gtrk render`（整片成片渲染）同词不同物。
-- **fetch**（`gtrk mg fetch <检索词|块名> [--top 3] [--all]` / `gtrk mg fetch --pick <块名> --slot <beat> --project <dir>` / `--pick <块名> --as <composition_id> --duration <sec> [--out <dir>]`）：**registry 中性颗粒源**——没建栏目也能出 MG。候选态**离线**（快照随包、钉死来源 commit）按检索词列 2–3 件（含 compat 标记与海报链接）；取块态按三源顺序取块（我方镜像优先、jsdelivr、GitHub raw，每源 5 s，**逐源 sha256 强校验**，三源皆败零落盘）→ 机械改写八条（`<template>` 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉子层 / GSAP 源换契约 CDN / 字体换运行时镜像可证的 CJK 字体 / 时长贴坑位 / 信箱缩放不拉伸）→ `gtrk mg lint` 致命项不过不落盘 → 落 `<project>/mg/<composition_id>.html`。**骨架不是成品**：返回的 `editable`（文案 / 数值数组 / 色值）MUST 按 beat 与栏目改写后再铺。契约当前只收 1920×1080 颗粒，其它画布拒绝；`excluded` 件拒取，`review` 件（canvas / 铁律 8 高危形态）可取但须真渲验收。`GITRUCK_MG_REGISTRY_BASE` 可整体覆盖取块前缀。
+- **render**（`gtrk mg render <颗粒.html> --duration <sec> [--out <dir>] [--yes]`）：**脱离工程**把单颗颗粒云渲成剪映可读的 qtrle 透明 alpha MOV（精剪补给口——粗剪导剪映后缺一颗动态图，不回客户端就能补）。链路 = lint 前置（包络 = `--duration`，任一致命项本地拦截、零提交零计费）→ **计费预估确认**（实时查价；CLI 无本地 HTML 渲染引擎，独立颗粒唯一路 = 云渲计费任务，`--yes` 跳过确认）→ 内联提交云端 → `<composition_id>.mov` 落盘 + `task.json`/`result.json` 面包屑（崩溃可凭 task_id 恢复）。**射程**：首发只出 qtrle（`--format webm` 明确拒绝，剪映不吃 VP8-alpha）、颗粒几何须为正整数、`--duration` 必填；MOV 按颗粒声明的 `data-width` / `data-height` 原尺寸出（竖屏 1080×1920 颗粒出 1080×1920 MOV）。产物不进 `.gtrk`、不写剪映草稿目录；qtrle 无损体积偏大，适合秒级颗粒。注意与 `gtrk render`（整片成片渲染）同词不同物。
+- **fetch**（`gtrk mg fetch <检索词|块名> [--top 3] [--all]` / `gtrk mg fetch --pick <块名> --slot <beat> --project <dir>` / `--pick <块名> --as <composition_id> --duration <sec> [--out <dir>]`）：**registry 中性颗粒源**——没建栏目也能出 MG。候选态**离线**（快照随包、钉死来源 commit）按检索词列 2–3 件（含 compat 标记与海报链接）；取块态按三源顺序取块（我方镜像优先、jsdelivr、GitHub raw，每源 5 s，**逐源 sha256 强校验**，三源皆败零落盘）→ 机械改写八条（`<template>` 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉子层 / GSAP 源换契约 CDN / 字体换运行时镜像可证的 CJK 字体 / 时长贴坑位 / 信箱缩放不拉伸）→ `gtrk mg lint` 致命项不过不落盘 → 落 `<project>/mg/<composition_id>.html`。**骨架不是成品**：返回的 `editable`（文案 / 数值数组 / 色值）MUST 按 beat 与栏目改写后再铺。registry 中性块只有 1920×1080 一种几何（尺寸写死在块里），`--canvas` 给其它画幅拒绝；派单模式下工程 `.gtrk` 的 `video_size` 比例不是 16:9（容差 7%：4K 横屏与 DCI 17:9 照取）在下载前拒、不落盘，竖屏 / 方形工程走 `--source text`（找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示）；`excluded` 件拒取，`review` 件（canvas / 铁律 8 高危形态）可取但须真渲验收。`GITRUCK_MG_REGISTRY_BASE` 可整体覆盖取块前缀。
 - **fetch --source text**（`gtrk mg fetch --source text <检索词> [--top 3] [--offline]` / `--pick <模板 id> --slot <beat> --project <dir>` / `--pick <模板 id> --as <composition_id> [--out <dir>]`）：**同合云自家的文字特效模板库**——与中性块是两条路。模板是我方 clean-room 重写的**成品**（配色与排版已做过），**不做机械改写、MUST NOT 直接改 HTML**。每颗内嵌产生它的 IR 与双哈希，颗粒因此自带出身证明（三态 `ir` / `detached` / `html`）；手改一个字节就掉成 `detached`，云端改写会拒绝它（`gtrk mg lint` 报非致命的 `x-ir-detached`）。目录走**远端择新、随包兜底**：优先取镜像上的 `catalog.json` 按 `version` 择新并缓存 24h，三源皆不可达时回落随包那份并**明示**（候选态因此永远离线可用）。取块仍逐源 sha256 强校验，三源皆败零落盘。`GITRUCK_TEXT_TEMPLATE_BASE` 可整体覆盖取块与目录前缀。
-  **落点与时长由命令钉定**：派单模式的 `composition_id` 取自 `dispatch.mg` 那条（`<工程slug>-<beatId>`，不是 `--slot` 收的 beat id），颗粒内嵌 IR 的 `id` 与 `canvas.duration` 被钉到「期望 id」与「坑位包络 + 0.3s 余量」（铁律⑦，贴模板末尾的层跟着钉），再走 `mg compile` 同一条本地编译链重编——产物仍是 `ir` 态，`1-cid-expect` 天然对得上。独立模式 `--as` 同样改写颗粒内部 id，`--duration` 钉时长；`--slot` 与 `--duration` 互斥。两者都没改时原字节落盘。
-- **compile**（`gtrk mg compile <ir.json> [--out <dir>]`）：把 IR 交给云端**确定性编译**成颗粒（**0 积分**）。改字、换色、改字号描边阴影、改时长都走它——改 IR 再编，比手改 HTML 干净，且颗粒保持 `ir` 态（云端还能继续调）。**本地没有编译器**是有意的：第二份编译器意味着第二套产物字节，而三态身份判的就是字节。
+  **落点与时长由命令钉定**：派单模式的 `composition_id` 取自 `dispatch.mg` 那条（`<工程slug>-<beatId>`，不是 `--slot` 收的 beat id），颗粒内嵌 IR 的 `id` 与 `canvas.duration` 被钉到「期望 id」与「坑位包络 + 0.3s 余量」（铁律⑦，贴模板末尾的层跟着钉），再走 `mg compile` 同一条本地编译链重编——产物仍是 `ir` 态，`1-cid-expect` 天然对得上。独立模式 `--as` 同样改写颗粒内部 id，`--duration` 钉时长；`--slot` 与 `--duration` 互斥。两者都没改、且目标画幅就是模板的 1920×1080 时原字节落盘。
+  **画幅**：按目标画幅编（IR 住在 1920 参考系，画幅是编译入参）。派单模式缺省取工程 `.gtrk` 的 `video_size`（显式 `--canvas` 与它不符当场拒；找不到 `.gtrk` 时按 1920×1080 编并提示补 `--canvas`），独立模式取 `--canvas`、不给即 1920×1080；`--json` 带 `canvas` 与 `canvas_from`（`flag` / `project` / `reference`）。
+- **compile**（`gtrk mg compile <ir.json | 颗粒.html> [--canvas <WxH>] [--out <dir>] [--remote]`）：把 IR **确定性编译**成颗粒（**0 积分**）。改字、换色、改字号描边阴影、改时长都走它——改 IR 再编，比手改 HTML 干净，且颗粒保持 `ir` 态（云端还能继续调）。缺省在本地编（零请求、断网可用，与服务端编译器逐字节等价）；`--remote` 改走服务端，留给排查与对拍。给颗粒 HTML = 按它内嵌的 IR 重置回模板。`--canvas` 是目标画幅：不给时重置沿用那颗自己的画幅、`.ir.json` 按 1920×1080；`--remote` 把同一画幅交给服务端，产物画幅与请求不符（旧服务端不认画幅）时不落盘。
 - **edit**（`gtrk mg edit <颗粒.html> --say "<一句话>" [--n 1|3] [--pick <k>] [--yes]`）：自然语言改写文字模板颗粒，经云端模型链出候选。`--n` 只收 1 或 3，**它就是计费单位数**（2 积分/候选，首次与改写同价、无免费次数）。`detached` / 无内嵌 IR 的颗粒**本地就拒**，不提交云任务、不花钱。候选带 `scope`：`L1` = 在模板可调范围内、`L2` = 越界即新生成（**不是失败**）；服务端说做不到时给一句 `refusal`，命令如实转述并以非 0 退出码区分于网络错误。不给 `--pick` 就只落候选不动原文件；给了才替换并留 `<cid>.bak.html`。
 
 `--json` 输出：`{ ok, mode:"lay"|"lint"|"status", … }`（各模式带对应字段，如铺轨的 `laid` / `skipped`、status 的逐 beat 状态）。铺轨模式另带 **`track_total`**（轨上现存已铺数）、**`kept`** / **`kept_ids`**（其中**上轮遗留**、本次没重铺的颗数与 `composition_id` 清单）与 **`removed`**（本次被剥的旧自产颗粒数）——`laid`（本次）、`track_total`（轨上共）与 `kept`（上轮遗留）**要一起读**，恒有 `track_total = laid + kept`；只看 `laid` 会让「铺 1 颗、剥 20 颗」跟「补铺 1 颗」长得一模一样，只看前两个又会漏掉「轨上那几颗不是这一轮的版本」这条代价（`kept_ids` 与 `skipped` 会重叠：这轮没铺成、上一轮那条还在轨上）。非全绿时另带机读 **`reason`**：`skipped`（部分没铺上）/ `empty_queue`（**拒写回**，工程未被改动，另带 `refused:true` 与 `blocked[]`）/ `no_project`（工程缺失未铺轨）。真写回过的运行另带 **`integrity`**（素材落盘自检，与 `gtrk matrix` 同名同形，口径见上节）。
@@ -490,12 +549,12 @@ gtrk composite bake --input <快照.gtrk> --base <工程 gtrk 目录> [--progres
 gtrk composite bake --abi
 ```
 
-- `plan`：候选窗口写进 `.gtrk` 的 `struct_meta.composite`（只动这一个键、原子写回；与 `gtrk split` 写 `struct_meta.split` 同一套做法），客户端大纲 CP 行据此画提案块；另出审稿稿 `composite/plan.md`。重跑保留已做的、不再提用户不要的。
+- `plan`：候选窗口写进 `.gtrk` 的 `struct_meta.composite`（只动这一个键、原子写回；与 `gtrk split` 写 `struct_meta.split` 同一套做法），客户端大纲 CP 行据此画提案块；另出审稿稿 `composite/plan.md`。重跑保留已做的、不再提用户不要的。「建议画面」用到的文字信号（列举 / 对照 / 数字 / 分点）识别中文与英文；其他语种只看 B-roll 密度，审稿稿里写明未识别。
 - `review`：采纳 / 不要 / 调起止 / 补窗口，写回同一个键；后续步骤只处理已采纳的窗口。
 - `scaffold`：为已采纳窗口落场景骨架 `composite/scenes/cp-wNN.html` 与上下文 `cp-wNN.context.md`；已有场景不覆盖。
 - `shots`：给选片用——带源时间码的联系表、镜头切点、黑边实测（`data-crop` 取值）；不替你选、不改工程。
-- `build`：场景 → 自包含颗粒 `gtrk/assets/composite/<id>.html`。解析规则与 infra `composite-particle-profile` 逐字节一致（帧格窗口、轨身份、锚点、字幕输入、`inputs_hash`）；风格取 `composite/theme.css`。
-- `lint`：静态校验 + 本机 Chrome / Edge 逐帧排版机检（下层画面的前景描边压上层画面、前景线条穿过画面、画面越出舞台）与**帧纯度**机检（同一帧号按「先渲前一帧」「先渲远处一帧」两种顺序各渲一次，元素与槽位几何必须一致——不一致的场景在烘焙段首、预览跳转后会画错），可出静帧。退出码 0 通过 / 1 有问题 / 3 排版未机检（找不到浏览器，可设 `GTRK_CHROME`）。
+- `build`：场景 → 自包含颗粒 `gtrk/assets/composite/<id>.html`。解析规则与 infra `composite-particle-profile` 逐字节一致（帧格窗口、轨身份、锚点、字幕输入、`inputs_hash`）；风格取 `composite/theme.css`。锚点关键词照句子原文写：匹配时关键词与句子都忽略空格、标点与大小写，英文按整词（`"cold brew"` 直接写，`tea` 不命中 `teas`）。
+- `lint`：静态校验 + 本机 Chrome / Edge 逐帧排版机检（下层画面的前景描边压上层画面、前景线条穿过画面、画面越出舞台、容器里的元素写了 `left` / `top` 偏移却没定位——`unpositioned-offset`，容器内要写 `position:absolute` 或加 `.abs`）与**帧纯度**机检（同一帧号按「先渲前一帧」「先渲远处一帧」两种顺序各渲一次，元素与槽位几何必须一致——不一致的场景在烘焙段首、预览跳转后会画错），可出静帧。退出码 0 通过 / 1 有问题 / 3 排版未机检（找不到浏览器，可设 `GTRK_CHROME`）。
 - `lay`：按自产身份幂等铺进 beat 轨最上层、补登记素材、窗口记为已做；过期颗粒拒铺；用户在客户端改过的同 id 颗粒不覆盖。
 - `bake`：把已铺的合成颗粒在本机**烘焙成不透明视频**，产物落 `gtrk/assets/composite-bake/<键>.mp4`；输入（槽位画面、字幕、锚点）按**当前时间线**现算。纯本地、零计费。
   - **浏览器**：优先钉定版本的 chrome-headless-shell（确定性出帧、最快）；没有时退回本机 Chrome / Edge（截图模式，更慢、并发降一档）。**不会静默下载**：`gtrk deps install --browser` 或本命令 `--install-browser` 显式授权才装（约 110 MB）。`GTRK_CHROME` 可指定浏览器。
@@ -503,7 +562,7 @@ gtrk composite bake --abi
   - **缓存**：键含颗粒、现算输入、素材文件指纹（大小 + 修改时间）、帧率、浏览器版本与编码参数；命中直接复用。改并发不换键。
   - **帧率**：缺省 = 工程帧率；`--fps` 指定（例如导出 30fps）。帧数 = `ceil(窗口 × fps)`，盖满整个窗口。
   - **退出码**：0 全部成功（含命中缓存）/ 1 有颗失败（其余照常，逐颗给原因）/ 2 参数或环境错误 / 130 被取消。
-  - **机读**：`--progress jsonl` 逐行输出 `type` 为 `start` / `browser` / `prep` / `progress` / `composite` / `cancelled` / `done` 的事件，相邻两行不超过 1 秒；此模式下**关闭 stdin 即取消**（其它模式不认 stdin）。`--abi` 只输出 `{abi, version, browser, overrides}`，不读工程：`browser.pinned` 是钉定的渲染组件装没装；`overrides` 是本版能烤出的槽位用户覆盖（`fit` / `framing` / `crop` 裁切 / `box` 画中画窗口大小与位置 / `slip_ms` 引用片段前后挪取帧），客户端据此判断工程里的调整能否烤出。`--input <快照> --base <目录>`：以快照为时间线来源（客户端交未保存状态用），相对素材路径与产物落点按 `--base` 解析，快照不回写。
+  - **机读**：`--progress jsonl` 逐行输出 `type` 为 `start` / `browser` / `prep` / `progress` / `composite` / `cancelled` / `done` 的事件，相邻两行不超过 1 秒；此模式下**关闭 stdin 即取消**（其它模式不认 stdin）。`--abi` 只输出 `{abi, version, browser, overrides, stage}`，不读工程：`browser.pinned` 是钉定的渲染组件装没装；`overrides` 是本版能烤出的槽位用户覆盖（`fit` / `framing` / `crop` 裁切 / `box` 画中画窗口大小与位置 / `slip_ms` 引用片段前后挪取帧），客户端据此判断工程里的调整能否烤出；`stage: "canvas"` 表示能烤任意舞台尺寸（合成舞台随工程画布，竖屏、方形同口径；缺这个字段的老版本只认 1920×1080）。`--input <快照> --base <目录>`：以快照为时间线来源（客户端交未保存状态用），相对素材路径与产物落点按 `--base` 解析，快照不回写。
 - `gtrk render` / `gtrk project export` 会先烘焙工程里的合成颗粒：烘焙成功的那段以烘焙视频出画（剪映 / Pr 里是该层位上的一段视频），**时段整段落在合成窗口内的 MG / OV 不再预渲、不计费**；烘焙失败（素材丢失、找不到浏览器等）的那颗按粗剪出画并点名原因，不拦导出。
 
 ### `gtrk project init` / `gtrk audio lay` / `gtrk audio tighten` — 音频驱动工程零件（配音先行）
@@ -586,7 +645,7 @@ gtrk project background --gtrk <工程文件> --clear
 | 工具 | 输入 | 产物 | 计费 | 状态 |
 |---|---|---|---|---|
 | `image_move` | 单张图片；可选 `--motion` 指定 26 种运镜之一 | 运镜视频（几何按原图朝向推导：横 1920×1080 / 竖 1080×1920） | 运行前实时查询 | 已上线 |
-| `image_matting` | 单张图片 | 透明背景 png（可 `--param` 请求背景底板） | 运行前实时查询 | 已上线 |
+| `image_matting` | 单张图片（带 EXIF 方向的手机照片先按显示方向摆正再上传，原图不动） | 透明背景 png（可 `--param` 请求背景底板） | 运行前实时查询 | 已上线 |
 | `image_blackborder_remove` | 单张本地图片 | 去黑边图片 | 运行前实时查询 | 已上线 |
 | `image_canvas_adapt` | 单张本地图片；可选目标宽高与 `normal` / `rectangle` / `square` | 比例适配图片 | 运行前实时查询 | 已上线 |
 | `image_purify` | 单张本地图片；可选 `full_screen` / `region` 与区域框（仅处理你有权处理的素材） | 清理水印、Logo 或叠加元素后的净化图片 | 运行前实时查询 | 已上线 |
@@ -738,7 +797,7 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
   - 分发的 ffmpeg 为 GPLv3 构建，对应源码与二进制同处提供（见分发点 `SOURCE.md`）；**下载不附加任何使用限制**。
 - `gtrk upgrade [--check]` — 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装。
 - `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills 目录>]` — 单独安装/刷新 Agent Skills；缺省由通用适配器与 gtrk 补充层自动检测。
-- `gtrk skills recommend [--scene <id>] [--json]` — 第三方 skill 推荐目录：不带 `--scene` 列十个场景（hook / mg-explainer / kinetic-text / data-viz / map / ai-drama / collage / caption / principles / technique），带场景按 tier 给条目（用途 / 安装命令 / 许可与依赖 / 登记命令）。**只推荐不打包**：目录随包分发、带快照日期、不联网不留痕；star 与许可以仓库页为准，装不装是你的选择。GPL / AGPL / 非商用 / 无许可证 / 只能经 MCP-SaaS 运行的不入目录。目录也收同合云一方的 MG 排版技法族（`--scene technique`，条目 `origin: first-party`）：技法不当车道生产者，由 agent 在 MG 步按槽位取用。
+- `gtrk skills recommend [--scene <id>] [--json]` — 第三方 skill 推荐目录：不带 `--scene` 列十个场景（hook / mg-explainer / kinetic-text / data-viz / map / ai-drama / collage / caption / principles / technique），带场景按 tier 给条目（用途 / 安装命令 / 许可与依赖 / 登记命令）。**只推荐不打包**：目录随包分发、带快照日期，命令本身不联网不留痕（使用统计除外，见「使用统计与关闭方式」）；star 与许可以仓库页为准，装不装是你的选择。GPL / AGPL / 非商用 / 无许可证 / 只能经 MCP-SaaS 运行的不入目录。目录也收同合云一方的 MG 排版技法族（`--scene technique`，条目 `origin: first-party`）：技法不当车道生产者，由 agent 在 MG 步按槽位取用。
 - `gtrk skills add <owner/repo> [--skill <name>]... [--produces MG|AI_DRAMA|FILM_BROLL|script|none] [--column <id>] [--agents ...] [--all] [--copy]` — 透传通用 `skills` 适配器安装第三方 skill，成功后把 `{id, ref: "<owner/repo>#<skill>", produces, status: "third-party"}`（一方条目 `status: "first-party"`）**追加**进栏目配置 `style.skills`（同 ref 幂等、失败不登记；`--produces` 缺省取目录值，目录外仓登记为 `routing:"none"`），之后 `gtrk mg` / `/gtrk-ai-drama` 按 `produces` 即可解析到它。
 
 ### 视频高光发现（内部验收）

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.3.6",
+	"version": "1.3.8",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",
@@ -57,7 +57,7 @@
 		"build": "bun build ./src/index.ts --target=node --minify --outfile dist/index.js",
 		"typecheck": "tsc --noEmit",
 		"prepublishOnly": "npm run typecheck && npm test && bun run build",
-		"test": "node scripts/workspace-pollution-gate.mjs --snapshot && esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/log.ts src/lib/read-json.ts src/lib/sidecar-write.ts src/lib/user-config.ts src/lib/enum-catalog.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.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/project-background.ts src/lib/client-only-state.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/clip-speed.ts src/lib/clip-keyframes.ts src/lib/column-config.ts src/lib/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.ts src/lib/matrix.ts src/lib/online-broll-client.ts src/lib/online-search-journal.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/highlight-input.ts src/lib/local-index.ts src/lib/character-input.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/project-health.ts src/lib/contact-sheet.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/composite-particle.ts src/lib/composite-lay.ts src/lib/composite-lint.ts src/lib/composite-browser.ts src/lib/composite-plan.ts src/lib/composite-shots.ts src/lib/composite-resolve.ts src/lib/composite-profile.ts src/lib/composite-scene.ts src/lib/composite-bake-plan.ts src/lib/composite-bake.ts src/lib/composite-export.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-batch.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/cut-snap.ts src/lib/mg-coverage.ts src/lib/ai-drama-lay.ts src/lib/ai-drama-pack.ts src/lib/desk-locate.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/patch-cmd.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 --external:bun:sqlite --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/commands/doctor.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/doctor-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 --external:bun:sqlite --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.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 --external:bun:sqlite --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && esbuild src/commands/composite.ts --bundle --platform=node --format=esm --external:bun:sqlite --external:commander --outfile=.test-build/composite-cmd.mjs && esbuild src/commands/purify.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/purify-cmd.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\" && node scripts/workspace-pollution-gate.mjs --verify",
+		"test": "node scripts/workspace-pollution-gate.mjs --snapshot && esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/usage-analytics.ts src/lib/log.ts src/lib/read-json.ts src/lib/sidecar-write.ts src/lib/user-config.ts src/lib/enum-catalog.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.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/project-background.ts src/lib/client-only-state.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/clip-speed.ts src/lib/clip-keyframes.ts src/lib/column-config.ts src/lib/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.ts src/lib/matrix.ts src/lib/online-broll-client.ts src/lib/online-search-journal.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/highlight-input.ts src/lib/local-index.ts src/lib/character-input.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/project-health.ts src/lib/contact-sheet.ts src/lib/media-transcript.ts src/lib/media-grid.ts src/lib/media-ffmpeg.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/composite-particle.ts src/lib/composite-lay.ts src/lib/composite-lint.ts src/lib/composite-browser.ts src/lib/composite-plan.ts src/lib/composite-shots.ts src/lib/composite-resolve.ts src/lib/composite-profile.ts src/lib/composite-scene.ts src/lib/composite-bake-plan.ts src/lib/composite-bake.ts src/lib/composite-export.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-batch.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/cut-snap.ts src/lib/mg-coverage.ts src/lib/ai-drama-lay.ts src/lib/ai-drama-pack.ts src/lib/desk-locate.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/patch-cmd.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 --external:bun:sqlite --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/commands/media.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/media-cmd.mjs && esbuild src/commands/doctor.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/doctor-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 --external:bun:sqlite --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.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 --external:bun:sqlite --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && esbuild src/commands/composite.ts --bundle --platform=node --format=esm --external:bun:sqlite --external:commander --outfile=.test-build/composite-cmd.mjs && esbuild src/commands/purify.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/purify-cmd.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\" && node scripts/workspace-pollution-gate.mjs --verify",
 		"test:linux": "node scripts/test-linux.mjs",
 		"openspec:gate": "node openspec/gate.mjs",
 		"mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs",

package/skills/gtrk-ai-drama/SKILL.md

@@ -3,9 +3,9 @@ name: gtrk-ai-drama
 description: AI 情景动画分镜稿生成器——把成片 SOP 第③步（B-roll 底轨阶段）分到 AI_DRAMA 车道的 beat，逐个产**四段朴素描述（故事背景 / 角色 / 分镜 / 原文文稿）+ 独立视觉基调段 + 时长预算**，中英双版；Markdown 外壳默认严格兼容 gitruck-ai-drama-desk 解析器，可直接导入工作台，也可拿去任意外部 AI 漫剧管线（可灵 / 即梦 / Vidu / Veo / Runway / LTX / 本地开源，或 LibTV / OiiOii / TapNow 这类成片 agent 平台）上手用。创作与出片仍在 skill / 外部工作台；工作台导出的 return-v1 包用 `gtrk ai-drama lay` 确定性回填独立 AI 轨。当用户想「上 AI 情景动画 / 做 AI 分镜 / AI 动画描述 / 把这段做成 AI 视频 / 给这段配 AI 情景动画 / 弗洛伊德这段怎么做视频」时使用本 skill。通用拆镜 craft（蒙太奇段分层 / 四段描述结构 / 中英双语 / 时长预算）由本 skill 自持；栏目视觉 DNA（Style Lock）从栏目配置 style.skills 里 produces==AI_DRAMA 的条目解析注入，绝不硬编某栏目风格。凡把口播派单里 AI_DRAMA 段落转成可出片的描述稿，优先用本 skill，别手搓。
 ---
 
-# AI 情景动画分镜稿生成器（gtrk-ai-drama）
-
-用户要求间隔取关键镜头、剩余由实况补齐时，先读 [稀疏关键场景与角色参考](references/sparse-key-scenes.md)。其短 beat 窗口、时基、逐镜参考和留空规则优先于下文针对连续 AI 段落的时长预算；不转入通篇 AI 图纸。
+# AI 情景动画分镜稿生成器（gtrk-ai-drama）
+
+用户要求间隔取关键镜头、剩余由实况补齐时，先读 [稀疏关键场景与角色参考](references/sparse-key-scenes.md)。其短 beat 窗口、时基、逐镜参考和留空规则优先于下文针对连续 AI 段落的时长预算；不转入通篇 AI 图纸。
 
 把口播派单里分到 **`AI_DRAMA` 车道**的 beat，逐个拆成分镜、为每个 beat 产 **四段朴素描述 + 独立视觉基调 + 时长预算**（中英双版），落到 `<project>/ai-drama/<beat_id>.md`，再交棒 AI Drama Desk 或任意外部平台出片；标准工作台导出包由 CLI 自动回填时间线。
 
@@ -24,7 +24,7 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 
 **你与 `matrix` 同属第 ③ 步，MUST 在 MG 之前落位。** 理由：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版决策是「因势象形避主体」、**依赖底轨的最终画面构图**；若你的片段在 MG 之后才回铺，底轨构图就变了，先产的 MG 是对着「还没有 AI 画面的底轨」做的避让，你的片段落位后必然被避让错位、甚至被 MG 盖住画面主体。
 
-> ⚠️ **工序顺序**：AI 情景片段必须先落位；它属于底轨 B-roll，不是最后叠加的图层。之后再做全局构图检查与 MG。
+> ⚠️ **工序顺序**：AI 情景片段必须先落位；它属于底轨 B-roll，不是最后叠加的图层。之后再做全局构图检查与 MG。
 
 **异步等待的口子（你造成的那个）**：你产完描述后，用户要去外部平台出片、抽卡可能数天。严格串行会把 ④⑤ 无限期卡住，故约定：进 ⑤ 的硬门是「**AI 片段已回铺 ∨ 用户明示先跳过**」。走「明示跳过」时，下游 `/gtrk-mg` MUST 把与你的 beat 相邻/重叠区间的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述——**你在交代进度时也要把这个代价说清**，让用户知道跳过意味着将来可能返工那几颗。
 
@@ -37,11 +37,11 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 3. **中英双版地位平等，不是主辅。** ①视觉基调、②故事背景、③角色、④分镜四段每一段都给完整的中文版 + 英文版（不是把中文翻一句了事）。中文喂可灵 / 即梦 / Vidu / 通义，英文喂 Veo / Runway / LTX / Luma，用户按目标平台选。**唯独 ⑤ 原文文稿是中文口播原文、不翻译**（它是源真相 + 手动拼接的对位锚，翻译反而失真）。
 4. **内容可移植，Markdown 外壳不可自由改写。** 默认产物 MUST 通过 `gitruck-ai-drama-desk` 的 Markdown 解析契约：标题必须含 `（beat BXX）`；两大块必须叫 `## 一、中文稿…` / `## 二、English Storyboard…`；角色必须用 `#### 角色名（备注）` 标题；中文镜头必须用 `#### 分镜 01 · …`，英文镜头必须用 `#### Shot 01 · …`；元信息必须含 `区间总时长：track_st … → track_ed … ≈ … 秒`。`镜头`、粗体行、项目符号角色、`## 中文` / `## English`、`工程时间位` 都不是等价写法。**人读友好不能牺牲机读契约。**
 
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
-> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
 > 分镜稿只落**工程目录**（`<project>/ai-drama/<beat_id>.md`）或**用户显式指定处**；
 > **MUST NOT** 把用户媒体（毛片 / 成片 / 预览 / 外部平台出的片段）或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
-> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
+> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
 
 ## 业务分离：栏目 Style Lock 从哪来（关键）
 
@@ -114,7 +114,7 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 
 **Step 4 · 写四段描述（中英分块）**：先出**中文稿**（② 故事背景末句锁调 → ③ 角色结构化 + 禁变项 + 质感落点，复现理论家 pin 复用同段文字 → ④ 分镜每镜前缀复述基调 + 建议秒数 + 对应原文句 + 蒙太奇级意图 → ⑤ 原文文稿中文逐句不翻译），再整块出 **English Storyboard**（① Style Lock + ②③④ 英文原生化，不含 ⑤）。中英**分两大块、不逐段交错**（craft C）。
 
-**Step 5 · 校验后落盘**：先把每个 beat 的候选稿写到系统 temp，运行随 skill 分发的 `scripts/validate-storyboard.mjs <候选稿.md>`；退出码为 0 才写到 `<project>/ai-drama/<beat_id>.md`。失败就按输出逐项修正，MUST NOT 把未通过稿件落进工程。校验器不可用时，至少逐项执行下面「解析器硬契约」与交付前自检。用户直投单段时同样先校验，再落到用户指定的工程路径。临时稿无论成功失败都删掉。
+**Step 5 · 校验后落盘**：先把每个 beat 的候选稿写到系统 temp，运行随 skill 分发的 `scripts/validate-storyboard.mjs <候选稿.md>`；退出码为 0 才写到 `<project>/ai-drama/<beat_id>.md`。失败就按输出逐项修正，MUST NOT 把未通过稿件落进工程。校验器不可用时，至少逐项执行下面「解析器硬契约」与交付前自检。用户直投单段时同样先校验，再落到用户指定的工程路径。临时稿无论成功失败都删掉。
 
 ## 输出契约（落盘 Markdown 结构 · 中英分块）
 
@@ -250,7 +250,7 @@ face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how
 
    命令自己解析 id → 导出包目录，走两条**确定性**路径：① 工作台服务可达就问它；② 服务没起就读 `~/.gitruck/ai-drama-desk.json` 的落脚点。两条都不通会报错并给出路。
 
-   > ⚠️ **拿到 id 之后 MUST NOT 去磁盘上找导出包**（`find` / `ls -R` / 通配一律禁止）。解析不出来就如实报，请用户启动工作台或直接给路径。
+   > ⚠️ **拿到 id 之后 MUST NOT 去磁盘上找导出包**（`find` / `ls -R` / 通配一律禁止）。解析不出来就如实报，请用户启动工作台或直接给路径。
    > 零命中时命令会列出「已查过哪些数据根」：源码部署与打包部署的数据根不同，项目找不到多半是**它在另一个部署里**，不是丢了。
 
    已经手上就有目录路径（或用的是非标准平台）时，仍可用 `--package "<exports/aidrama>"`，两者可混用、按路径去重。
@@ -258,7 +258,7 @@ face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how
    命令会先按当刻口播工程重投影 beat 窗口，再把所有镜头复制到 `<gtrk目录>/assets/ai-drama/<slug>/`，共用一条新的 `video_track`；每个 beat 从起点顺排，最后一镜吸收到 beat 终点。既有 A-roll、BGM 与 B-roll 轨零改动。若已铺 AI 轨被用户手调过，缺省拒绝覆盖；只有用户明确同意丢弃手调时才加 `--replace-all`。
 3. **非标准平台才手动回铺**：外部平台没有 return-v1 清单时，才由用户把片段拖回 opencut 的 **AI_DRAMA 车道**，对齐该 beat 的 `track_st→track_ed`。AI 出片仍是外部异步、用户驱动；未拿到完整片段前要停下等用户，别替他假装出片 / 回轨完成。
 4. **回铺齐 ≠ 收口，还有两步**：你的片段回铺齐只意味着 **③ B-roll 底轨阶段**完成。接着 MUST 走 **④ 全局抽帧检查画面构图**（对三源合并后的最终底轨抽帧，看主体位置 / 安全区 / 画面朝向 / 明暗，**停下等用户确认**）→ 过了才交棒 **⑤ `/gtrk-mg`** 把 MG（含 ov）叠上 → 最后才 `gtrk render` 收口。
-   ⚠️ **MUST NOT 从你这里直接跳到 `render`**；先完成全局构图检查与 MG，再进入字幕和渲染。
+   ⚠️ **MUST NOT 从你这里直接跳到 `render`**；先完成全局构图检查与 MG，再进入字幕和渲染。
 
 > 原则：**agent 替用户跑 CLI / 接力 skill，用户只对话**。但 AI_DRAMA 车道天然有「用户去外部平台出片 + 手动拼回」的手工环节——那部分是外部的手，无法替跑；除此之外的解析、生成、落盘、交代，全由你（脑）一次做完，别让用户自己去拼描述。
 

package/skills/gtrk-ai-drama/references/sparse-key-scenes.md

@@ -1,38 +1,38 @@
-# 稀疏关键场景与角色参考
-
-用户要求“隔一段挑关键场景、其余自己补实况”时使用。它不是通篇 AI 成片图纸，不套用零缝、片头铺满或自动封缝规则。
-
-## 选镜与时基
-
-先通读正文及上下文，再按叙事转折选场景。间隔是密度目标，不是机械切秒。每镜登记原句、源音频起点、母带起点、预计画面时长、人物、年龄阶段、场景与关键道具。母带含 OP/ED 时显式登记正文范围与 offset；用对应音频片段核对，不能把正文从零开始的 ASR 时码直接当母带时码。
-
-一处独立关键场景对应一个短 beat 窗口，窗口只覆盖这条片段的计划时长；不要把直到下一处场景的整个间隔当窗口让末镜吃满。CLI beat 使用 B 开头数字编号；其他展示编号应显式映射，不私改接口。其余时间留给实况，禁止自动 seal、循环或拉伸填满。用户指定只做正文时，OP/ED 不派视觉生成。
-
-## 原作资产与逐镜判断
-
-- 从叙事语义识别人物，不能靠“他、父亲、刀”等关键词自动加入主角。角色随时间改变时分别绑定年龄、发型、服装参考。
-- 实际查看参考图。只带本镜需要的角色；物证或空镜不要夹带多人图作为角色参考。原作 CG 可以锁角色/画风，但画中事件不等于当前镜头事件。
-- 参考路径逐镜登记，禁止按镜号取模轮换 CG。用户指定宿主 Image2 时使用该能力，不擅自换成本地生图或云模型。
-- 图片提示词描述一个明确瞬间；I2V 提示词描述该瞬间里有剧情含义的小动作，以及须保持稳定的脸、手、道具与空间。实际时长、尺寸、帧率以模型配置及成品探测为准，不硬编码样片参数到全部项目。
-
-## 分阶段审阅
-
-已生成、已选中、已审阅、已回轨是不同状态。逐镜看实际输出，记录人物与年龄、场景关系、道具比例、手部接触和微动可行性。审阅记录绑定具体文件与内容哈希；替换图片、分镜或人物设定后重新审阅，不能整批写 accepted 代替目视检查。工具可以强制记录完整，却不能证明记录内容真实。
-
-外部图片通过工作台的 keyframe import 接口进入候选池；角色 refs 上传不是关键帧导入。具体命令见工作台 skill。视频检查至少看首、中、尾及运动过程；仅看抽帧要如实说明，不写成逐帧播放验收。
-
-## 分批回轨
-
-首次按现有 pack/lay 契约回轨；新增 beat 使用：
-
-```sh
-gtrk ai-drama lay --project <工程> --package <新包> --append --json
-```
-
-`--append` 为本次新包新增独立轨，逐对象保留已有轨、素材与手调；拒绝重复 beat，不与 `--replace-all` 同用。需替换已有镜头时，等时长/尺寸/帧率素材用 `swap`；改变时序须重新设计并用 patch 编辑，不以“备份后重铺再猜着恢复”冒充保留手调。媒体由增量路径按 beat 和内容哈希隔离。
-
-执行前查看当前 CLI 的 `ai-drama --help` 是否已有 `--append`。skill 更新不等于已安装二进制更新；旧版本缺参数时使用已核实仓库的源码入口或完成构建，不退回覆盖手调的项目脚本。
-
-阅读 lay 回执的 reprojection：降级使用派单快照时核对它是否属于当前母带。doctor 检查结构与文件存在，不能代替语义审阅；稀疏轨的空档警告不自动触发封缝。
-
-交付明确计划数、已生成数、已审阅数和已回轨数。用户说先看样片时只交付约定样片；其他镜头保持未完成状态，不因有场景表就宣称批量完成。
+# 稀疏关键场景与角色参考
+
+用户要求“隔一段挑关键场景、其余自己补实况”时使用。它不是通篇 AI 成片图纸，不套用零缝、片头铺满或自动封缝规则。
+
+## 选镜与时基
+
+先通读正文及上下文，再按叙事转折选场景。间隔是密度目标，不是机械切秒。每镜登记原句、源音频起点、母带起点、预计画面时长、人物、年龄阶段、场景与关键道具。母带含 OP/ED 时显式登记正文范围与 offset；用对应音频片段核对，不能把正文从零开始的 ASR 时码直接当母带时码。
+
+一处独立关键场景对应一个短 beat 窗口，窗口只覆盖这条片段的计划时长；不要把直到下一处场景的整个间隔当窗口让末镜吃满。CLI beat 使用 B 开头数字编号；其他展示编号应显式映射，不私改接口。其余时间留给实况，禁止自动 seal、循环或拉伸填满。用户指定只做正文时，OP/ED 不派视觉生成。
+
+## 原作资产与逐镜判断
+
+- 从叙事语义识别人物，不能靠“他、父亲、刀”等关键词自动加入主角。角色随时间改变时分别绑定年龄、发型、服装参考。
+- 实际查看参考图。只带本镜需要的角色；物证或空镜不要夹带多人图作为角色参考。原作 CG 可以锁角色/画风，但画中事件不等于当前镜头事件。
+- 参考路径逐镜登记，禁止按镜号取模轮换 CG。用户指定宿主 Image2 时使用该能力，不擅自换成本地生图或云模型。
+- 图片提示词描述一个明确瞬间；I2V 提示词描述该瞬间里有剧情含义的小动作，以及须保持稳定的脸、手、道具与空间。实际时长、尺寸、帧率以模型配置及成品探测为准，不硬编码样片参数到全部项目。
+
+## 分阶段审阅
+
+已生成、已选中、已审阅、已回轨是不同状态。逐镜看实际输出，记录人物与年龄、场景关系、道具比例、手部接触和微动可行性。审阅记录绑定具体文件与内容哈希；替换图片、分镜或人物设定后重新审阅，不能整批写 accepted 代替目视检查。工具可以强制记录完整，却不能证明记录内容真实。
+
+外部图片通过工作台的 keyframe import 接口进入候选池；角色 refs 上传不是关键帧导入。具体命令见工作台 skill。视频检查至少看首、中、尾及运动过程；仅看抽帧要如实说明，不写成逐帧播放验收。
+
+## 分批回轨
+
+首次按现有 pack/lay 契约回轨；新增 beat 使用：
+
+```sh
+gtrk ai-drama lay --project <工程> --package <新包> --append --json
+```
+
+`--append` 为本次新包新增独立轨，逐对象保留已有轨、素材与手调；拒绝重复 beat，不与 `--replace-all` 同用。需替换已有镜头时，等时长/尺寸/帧率素材用 `swap`；改变时序须重新设计并用 patch 编辑，不以“备份后重铺再猜着恢复”冒充保留手调。媒体由增量路径按 beat 和内容哈希隔离。
+
+执行前查看当前 CLI 的 `ai-drama --help` 是否已有 `--append`。skill 更新不等于已安装二进制更新；旧版本缺参数时使用已核实仓库的源码入口或完成构建，不退回覆盖手调的项目脚本。
+
+阅读 lay 回执的 reprojection：降级使用派单快照时核对它是否属于当前母带。doctor 检查结构与文件存在，不能代替语义审阅；稀疏轨的空档警告不自动触发封缝。
+
+交付明确计划数、已生成数、已审阅数和已回轨数。用户说先看样片时只交付约定样片；其他镜头保持未完成状态，不因有场景表就宣称批量完成。