@gitruck/cli 1.3.15 → 1.3.17

package/AGENT.md

@@ -28,7 +28,8 @@
 - 新处理请求会先查询 /task/video_purify/capabilities，必须支持 review_protocol=2；未升级会在上传与计费前停止。先更新 worker，再开放 HTTP 能力声明。
 
 > **写/改 structure 级成片图纸**（旅拍 / 口播链 / 直播切片 / Vlog……）先过 `docs/成片型图纸公约.md`
-> ——双模式命名（快速成片 / 逐步推进）、决策前置三条腿、MG 临场泛化的横切正本与自检清单都在那里。
+> ——双模式命名（快速成片 / 逐步推进）、决策前置三条腿、画面三层（底 / 版 / 叠）与制片位次、MG 临场泛化的横切正本与自检清单都在那里。
+> 制片位次（正本 `production-order`）：① 剪口播 → ② 拆分（含版式窗口，满屏卡写成零槽位窗口）→ ③ 底轨三源铺齐 → ④ 全局抽帧检查 → ⑤ 字幕 → ⑥ 合成（版，含满屏卡）→ ⑦ 叠层（`gtrk mg`）→ 出片；BGM 不受顺序约束。
 
 ---
 
@@ -108,12 +109,15 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 2. **拿到 CLI**：进入 `gtrk-cli/` 仓库，`bun install`。
 3. **调用方式**（二选一）：仓库内 `bun run src/index.ts <命令> …`；或 `bun link` 后全局 `gtrk <命令> …`（本文档统一写 `gtrk`）。
 4. **跑 `gtrk init` 引导式配置**（对标飞书 lark-cli install，只做一次）：
-   - 填 **API Key**（鉴权 Header `Authorization` 的裸值，非 Bearer）；根地址默认生产、回车即用。
+   - 填 **API Key**（鉴权 Header `Authorization` 的裸值，非 Bearer）；根地址默认生产、回车即用。
+     Key 去哪拿：打开 https://cloud.ai-mcn.tv/zh-CN ，点「注册 / 登录」（登录即开通），进入「仪表盘」复制 API Key。
+     还没有 Key 时在输入框直接回车，CLI 会替用户打开这个网页。
    - **自动扫描剪映草稿目录**：扫到让你确认；扫不到会**自动打开一张指引图**（剪映 → 全局设置 → 草稿 →「草稿位置」）让你把路径粘过来；可留空跳过。
    - 配置写到 `~/.gitruck/config.json`，之后所有命令免重复配置。
    - 环境变量 `GITRUCK_API_KEY` / `GITRUCK_API_BASE` 仍可覆盖（CI / 临时切换）。
 
-> agent 自检：没配 Key 时任何命令会明确报「缺 API Key —— 先跑 `gtrk init`」。剪映目录没配只影响剪映直开，不挡 gtrk/PR。
+> agent 自检：没配 Key 时任何命令会明确报「缺 API Key —— 先跑 `gtrk init`」，报错后半句写明 Key 去哪拿——**原样转告用户**，
+> 别替用户编别的入口；用户可能是在官网以外的页面看到安装命令的，手里没有官网链接。剪映目录没配只影响剪映直开，不挡 gtrk/PR。
 > `init` 是**人手一次性**交互配置（会弹提示）；agent 日常只跑非交互的 `oralcut`。
 
 > **合规告知（只告知、不是闸门）**：`init` 配好、以及首次把内容送上云之前，CLI 会往 **stderr** 打一次条款告知
@@ -244,7 +248,7 @@ gtrk oralcut-result 88269671080189958 --render --out "D:/回收/某条"
 
 ## 2.2 视觉拆分派单器：`gtrk split`（成片 → 分镜派单）
 
-`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 情景动画 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
+`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 情景动画 / FILM_BROLL 影视素材），另在拆分稿顶层 `layouts[]` 声明哪些时间窗交给合成（版式窗口）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
 
 编排顺序（脑=`gtrk-splitter` skill / 手=本命令）：
 
@@ -270,7 +274,9 @@ gtrk split <拆分稿.json> --project <目录> --md --json  # ⑤ 校验落地
 - **dropped 处理**：beat 的 span 内 utterance 全被剪 → 跳过该 beat 并入报告；部分被剪 → 按存活句包络收缩、标 `shrunk`。均不使命令失败。
 - **transcript 缺失**（旧任务）→ 明确报错引导「用新版本重跑 oralcut（恒出工程所需的结构化 transcript）」，不做降级猜测；`gtrk transcript` 只产人读 Markdown，不能替代 split 所需的结构化词表。
 - **只动 `struct_meta.split`**：写回不碰 materials/tracks，配合客户端「保存 → 发起 → 写回 → 重载」闭环（opencut 联动）。
-- **下游消费**：`dispatch.json` 的 `film_broll` 队列 → `gtrk matrix --project <dir>`（B-roll 双口检索 → `split/broll-plan.json` 候选清单;url 24h 过期,重跑即重签）；`mg` 槽位表（去品牌化前 `rrv_mg`）→ `gtrk mg` 铺轨 / real-roam-viz 产颗粒；`ai_drama` 队列 → ai-drama-prompter。
+- **版式窗口（`layouts[]`，可选顶层键）**：每项 `id`（`L` + 序号）/ `span`（utterance id 区间）/ `visual_job` / `visual_brief`（必填：这段怎么排）/ `slot_hints?` / `zero_slot?` / `theme?` / `bg?`。窗口不占车道，beat 的 `lane` 照旧描述底下要什么画面。校验：两端 id 存在、不倒序、窗口互不重叠、端点不落在某个 beat 中间、不与满屏类 MG beat 相交 —— 拒；整段落在窗口里的叠层（overlay aux、`category: overlay` 的 MG beat）一律不派（出片时窗口里的颗粒不出画），记进 `beats.skipped[]`（`covered_by_layout`），要点进窗口的 `covered_overlays`，稿里写了已收回的旧字段只告警、忽略；单窗 5–25 秒以外、带画面槽位的窗口总覆盖超过全片 25% 而没写 `layout_density_note` —— 告警；写了 `layouts` 键而为空数组、没写 `layout_note` —— 拒。没写 `layouts` 键 = 旧稿，规则全跳过。落地多出 `dispatch.composite` 队列（与 `mg` / `film_broll` 同口径现场重投影，顶层带 `layouts_declared`）、`struct_meta.split.layouts` 快照与人读稿「版式窗口」一节；字段正本 `skills/gtrk-splitter/references/field-schema.md`。
+- **满屏卡（零槽位版式窗口）**：`zero_slot: true` 的窗口是整幅纯排版、没有画面槽位的满屏卡（标题牌、章节卡、数据卡、纯排版的并置面板），由合成以零槽位场景承接、本机烘焙出片；不写 `slot_hints`（写了就拒）、不告「短于 5 秒」、不计 25% 密度，窗口底下的 beat 派 `A_ROLL`（盖住 `FILM_BROLL` / `AI_DRAMA` 告警），`bg` 不是 `#RRGGBB` / `#RRGGBBAA` 告警忽略。旧稿里 `lane: MG` + 满屏类品类（`fullscreen` / `title`，遗留 `mg-fullscreen` / `op-ed-title`）的 beat 落地时**自动转成满屏卡**：窗口 `L` + beat id（B07 ⇒ `LB07`，带 `converted_from`），beat 按 `A_ROLL` 落地带 `converted`、不进 `dispatch.mg`，回执人读一行「B07 → LB07」、`--json` 带 `layouts.converted`；拆分稿文件不改。写了 `layouts` 键而 MG 主 beat 没写 `category` ⇒ 告警「按叠层理解」。
+- **下游消费**：`dispatch.json` 的 `film_broll` 队列 → `gtrk matrix --project <dir>`（B-roll 双口检索 → `split/broll-plan.json` 候选清单;url 24h 过期,重跑即重签）；`mg` 槽位表（去品牌化前 `rrv_mg`）→ `gtrk mg` 铺轨 / real-roam-viz 产颗粒；`ai_drama` 队列 → ai-drama-prompter；`composite` 队列 → `gtrk composite plan --mode split`。
 - **看某个 beat 的现状**：`gtrk matrix status --project <dir> --beat <id>[,<id>…] --json`（不带 `--beat` = 全部 B-roll beat 一行一个概要）。只读、零网络、零写盘，读盘上工程：时间窗（现场重投影，降级时标明原因）、候选池（精简字段、不带下载地址）、plan 里其余候选的条数与前 5、时间窗内各视频轨上的片段与类别、主轨之上的空缺（另列只有黑底补片的区间）、`revision`（可作 `gtrk patch --expected-revision`）、各候选轨剥离判定与整轮重铺会不会被 `tracks_edited` 拒。**精修前先跑它，别去翻 `split/broll-plan.json` 与 `.gtrk`**。beat 不存在 ⇒ `ok:false`、非 0 退出并列出全部已知 beat。
 
 > **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
@@ -464,7 +470,8 @@ gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape el
   偏移口径全库统一：正 = 屏录晚开录（`clip_st' = clip_st − offset`）。**屏录 MUST 带麦克风音轨**才能自动对齐，无音轨只剩后两条路——开工时就要提醒用户。
 - **钳位与留空**：屏录比人像短 / 晚开录 ⇒ 对应 beat 留空或只铺可用部分，回执逐颗点名毫秒数；MUST NOT 拉伸或变速。成片该段只见人像主轨，如实告诉用户。
 - **幂等 + 不覆盖用户改动**：改参数直接重跑，自产 clip（`producer=gtrk:pip@1`）剥旧重铺；用户在客户端动过的画中画 clip 失去身份 ⇒ 保留并在回执 `strip.keptForeign` 点名。
-- **位置**：`oralcut` → 检查点① → `pip lay` → `subtitle lay` / `audio lay` → 出片。**不新增必停点**，铺完让用户在客户端看一眼即可。
+- **位置**：`oralcut` → 检查点① → `pip lay` → `subtitle lay` → 合成 → `mg`（`audio lay` 不受顺序约束）→ 出片。**不新增必停点**，铺完让用户在客户端看一眼即可。
+- **与合成**：客户端在合成窗口里只藏字幕与 MG 颗粒，不藏画中画轨；合成场景要铺满幅底、讲者只出现一次（`/gtrk-composite` 编排规则 2）。
 - 出片：客户端本地导出 / `gtrk render`（本地合成几何与蒙版）/ 导剪映（菱形无对应会跳过并明示）。
 - 拒写口径同 `gtrk patch`（内容 revision 冲突回 `conflict`、写方自检违例硬拒零写）。
 
@@ -472,10 +479,10 @@ gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape el
 
 ## 2.6 合成层：`gtrk composite`（粗剪之上的整段包装 · 纯本地零计费）
 
-字幕之后、出片之前：把选定时间窗做成**合成颗粒**——一段时间内的整个画面由一颗代码颗粒接管（逐句换画面、对照并排、并列卡片、字幕排版），讲者与 B-roll 作为槽位由客户端画进去。由 `/gtrk-composite` 驱动，**编排规则与两个检查点在 skill 里**，本节只列命令面。
+字幕之后、`gtrk mg`（叠层）之前（位次 ⑥，正本 `production-order`）：把选定时间窗做成**合成颗粒**——一段时间内的整个画面由一颗代码颗粒接管（逐句换画面、对照并排、并列卡片、字幕排版），讲者、B-roll 与图片作为槽位由客户端画进去；没有画面槽位的标题牌、章节卡、数据卡是**满屏卡**（零槽位合成）。合成是画面三层里的「版」；叠层只产在合成窗口以外。由 `/gtrk-composite` 驱动，**编排规则与两个检查点在 skill 里**，本节只列命令面。
 
 ```bash
-gtrk composite plan --project <工程> [--mode full|auto|ranges] [--range 11,32 | --range u0004-u0009]... [--density 0.25]
+gtrk composite plan --project <工程> [--mode split|full|auto|ranges] [--range 11,32 | --range u0004-u0009]... [--density 0.25]
 gtrk composite review --project <工程> [--approve W01,W03] [--reject W02] [--adjust W04=80,90.9] [--add 140,150] [--approve-all]
 gtrk composite status --project <工程> [--json]
 gtrk composite scaffold --project <工程> [--only W03] [--force]
@@ -484,18 +491,41 @@ gtrk composite build --project <工程> [--only cp-w03] [--theme <css>] [--mater
 gtrk composite lint --project <工程> [--stills 26,86.6] [--no-browser]
 gtrk composite lay --project <工程> [--only cp-w03] [--dry-run]
 gtrk composite bake --project <工程> [--only cp-w03] [--fps 30] [--workers 4] [--install-browser] [--progress jsonl]
+gtrk composite materials add <图片> --project <工程> [--from-web-source <来源 id>] [--id <素材 id>] [--json]
+gtrk composite materials list --project <工程> [--json]
 ```
 
 - **候选写 `struct_meta.composite`**（只动这一个键、原子写回），客户端大纲 CP 行画提案块——与 `gtrk split` 写 `struct_meta.split`、beat 色带呈现同一套做法。要用户看提案块，先请他在客户端**重新载入工程**。
+- **`--mode split`**（拆分是唯一规划者）：读 `split/dispatch.json` 的 `composite` 队列，按当刻时间线重投影、吸附句界与帧格（吸附量逐条写明）；理由取拆分稿的 `visual_brief`，`slot_hints` 写进 `composite/scenes/cp-wNN.context.md`；状态一律待审，已 `built` 的窗口原样保留。拆分稿带 `layouts` 键的工程，图纸的精剪包装用它、**不再跑 `auto`**；用户主动问「还有哪里适合」时 `auto` 补出的窗口不与 split 来源的窗口重叠。没有 `composite` 队列（旧稿）⇒ 报错指路（重跑拆分补版式窗口，或 `--mode auto`）；队列为空 ⇒ 零窗口，回执引述 `layout_note`。`auto` 留给不走拆分的链（直播切片、长剪短）与旧工程。
 - **解析规则不自造**：`build` 按 infra `composite-particle-profile` 解析（帧格窗口、`lane_clip_id`、锚点局部帧、字幕输入、`inputs_hash`），对拍 infra 金样逐字节一致；窗口不在帧格上会被吸附并报挪动量。
 - **机检**：`lint` 退出码 0 通过 / 1 有问题 / 3 排版未机检（本机找不到 Chrome / Edge，可设 `GTRK_CHROME`）。**3 不是通过**：照实告诉用户，用静帧人眼查。`lint` 含帧纯度检查（`impure-frame`：同一帧号随渲染顺序画出不同画面），不过的颗粒烘焙段首会画错。
-- **进度**：`status` 只读汇总——各状态窗口数、`pending`（已采纳、还没铺轨的段数）、已铺数，逐窗口起止按当刻时间线重新投影。
+- **进度**：`status` 只读汇总——各状态窗口数、`pending`（已采纳、还没铺轨的段数）、`pending_cards`（`pending` 里满屏卡的张数，只按窗口的 `zero_slot` 标记数）、已铺数，逐窗口起止按当刻时间线重新投影，满屏卡那一行带 `zero_slot: true`。
+- **满屏卡**：`--mode split` 把拆分稿窗口的 `zero_slot` / `theme` / `bg` / `converted_from` / `covered_overlays` 原样写进窗口、不写 `layout_hint`；派单 `layouts_declared: false`（窗口全是满屏 MG 转来的满屏卡）⇒ 接着 `--mode auto` 补其余窗口（满屏卡不占密度预算，补出的窗口不与它重叠）。`scaffold` 给满屏卡只写字幕输入 `subs`（工程有讲者轨也不写讲者槽位；`subs` 不用也留着，合成颗粒要求槽位非空）、`takeover` 固定字幕 + 叠层、`.bed` 取 `bg`，上下文文件多一段「满屏卡（零槽位）」。`build`：满屏卡场景声明了画面槽位 ⇒ 告警（成了带槽位的合成，按段计）照常构建；`slots` 为空 ⇒ 照 profile 拒并提示保留 `subs`。
 - **铺轨**：按 `producer=gtrk:composite@1` 认领自产轨（不按轨号）；过期颗粒（上游改过）拒铺；用户在客户端改过的同 id 颗粒不覆盖。
 - **出片**：`gtrk composite bake` 在本机把合成烤成不透明视频（缓存命中即复用，纯本地零计费）；`gtrk render` / `gtrk project export` 会自动先烤，成功的段以烘焙视频出画，整段落在合成窗口内的 MG / OV 不再预渲、不计费。
   - 浏览器优先用钉定版本 chrome-headless-shell，没有时退回本机 Chrome / Edge（更慢）。**MUST NOT 自作主张下载**：征得用户同意后 `gtrk deps install --browser`（约 110 MB）或 `bake --install-browser`。
   - 某颗烤失败（退出码 1，回执给原因）时，出片该段按粗剪出画——照实告诉用户。
 - **舞台随工程画布**：`scaffold` 按 `.gtrk` 的 `video_size` 写场景舞台，竖屏、方形与横屏同口径；场景舞台与工程画布不一致时 `build` 逐颗报错（按新画布重写，`scaffold --force` 重起骨架）。`bake --abi` 的 `stage: "canvas"` 表示能烤任意舞台尺寸。
-- **成片图纸里**：口播 / 解说 / 美食 / 配音 / 旅拍 / Vlog 的快速成片缺省带这一步（「精剪包装」，开工告知一句可关），直播切片与长剪短缺省不做、开工问一次——口径正本在《成片型图纸公约》§三⁵。
+- **成片图纸里**：口播 / 解说 / 美食 / 配音 / 旅拍 / Vlog 的快速成片缺省带这一步（「精剪包装」，开工告知一句可关；拆分稿带 `layouts` 键时取 `--mode split`），直播切片与长剪短缺省不做、开工问一次——口径正本在《成片型图纸公约》§三⁵。
+- **图片槽位**：`own` 槽位可以绑图片（build、lint、bake 都认）；旧版客户端预览里图片槽位会空着、出片不受影响，旧版上要预览就先把图片转成视频（`/gtrk-composite`「已知限制」第 1 条）。
+- **图片登记**：`materials add` 校验是图片（`png / jpg / jpeg / webp / gif / bmp / avif`，ffprobe 读宽高）、拷进 `<.gtrk 所在目录>/assets/web/<素材 id>.<扩展名>`、原子写入或更新 `composite/materials.json` 一条 `{ id, path, kind: "image", width, height }`（`path` 相对 `.gtrk` 所在目录；别的条目不动；同 id 同内容幂等，同 id 不同图报错、`--id` 另起）。**联网取回的图**带 `--from-web-source <来源 id>`：读 `web/sources.jsonl`（内置 AI `web_fetch` 落盘的出处，同 id 取最后一行），条目多带 `source`（原样拷来源字段）与 `credit`（出处卡文字 = `站点｜标题`，缺一取一，都缺取网址主机名；不经模型改写），登记的不是取回的原图时记 `derived_from`；`web/` 下的图不带来源登记会告警。外部 agent 自己下载的网络图先按同一格式往 `sources.jsonl` 追加一行再登记。`list` 只读列出条目、出处与被哪些场景槽位引用。
+- **出处卡核对**：绑定联网素材的每个 `own` 槽位，场景里要有 `data-credit-for="<槽位>"` 元素、文字等于 `credit`（`scaffold` 的上下文文件列出原文）。`lint` 静态核对四条，任一不过即退出码 1：缺出处卡 `credit-missing`、文字不一致 `credit-mismatch`、`credit` 与当前 `sources.jsonl` 重拼的不一致 `credit-stale`（重跑 `materials add`）、指向不存在的槽位 `credit-orphan`；有浏览器时另做帧检，图可见而出处卡看不见 ⇒ 告警 `credit-hidden`（回执 `particles[].warnings`，不拦）。不含联网素材的颗粒结果不变。出处卡不等于获得使用许可。
+
+---
+
+## 2.7 MG 铺轨：`gtrk mg`（⑦ 叠层 · 认「被合成接管」）
+
+`dispatch.mg` 的槽位由栏目 MG 生产 skill 产颗粒、`gtrk mg` lint + 铺进 `beat_track`；编排、lint 铁律与交棒在 `/gtrk-mg`，本节只列合成落位之后多出来的那一层。
+
+```bash
+gtrk mg status --project <dir> --json            # 看板：先看 todo
+gtrk mg --project <dir> [--only <beat>] --json
+```
+
+- **判定**：槽位（主 beat 与 aux 派生颗粒，叠层与满屏同一判据）的落轨包络**整段**落在合成窗口里即被接管，记 `covered_by = <窗口 id>`；部分重叠不算。窗口来源两类：`struct_meta.composite` 里状态不是 `rejected` / `trimmed` 的窗口，以及 `dispatch.composite` 里还没导进合成的版式窗口。**不看场景 `takeover`**——与出片的覆盖判定（`coveringWindows`，帧格比较）同口径：出片时整段落在有效合成窗口里的颗粒一律不出画。
+- **看板**：`gtrk mg status --json` 被接管的槽位带 `covered_by`；顶层新增 `covered`（被接管数）与 `todo`（未产且未被接管数，**这才是要开工的颗数**）。`total` / `authored` 语义不变——旧宿主按 `total − authored` 算待产只是偏大，不出错。
+- **铺轨**：被接管的槽位不铺，回执 `skipped[]` 记 `{ composition_id, reason: "covered_by_composite", window }`，不算失败、不剥离已铺颗粒（沿用「空 queue / 全 skip 不是清空指令」）。没有照铺开关（铺了也出不了画）；要在合成里强调一个词，写进合成场景本身。
+- **只剩叠层**：满屏卡已并入合成，新派单的 `dispatch.mg` 没有满屏条目。**旧派单里的满屏槽位**（`category` 为满屏类）照旧产、铺、云渲出片：`status --json` 顶层 `legacy_fullscreen` 报这类槽位数并提示「重跑 `gtrk split` 可转成满屏卡」。迁移期：重跑拆分后，全量铺轨遇到派单里有转换窗口（`converted_from`）而满屏卡还没做成合成的旧满屏颗粒 ⇒ 原样保留（回执 `kept_superseded[]`）；做成且在轨上之后 ⇒ 照「计划变更」剥（回执 `removed_superseded[]`，不计入 `removed`）；`--only` / `--replace-all` 行为不变。独立路 `fetch --category fullscreen` / `render` 照常可用，收到或推断出满屏时回执带 `hint`「满屏卡建议做成零槽位合成」；`mg lint` 对没写 `category`、产物却有满屏实心底的派单槽位给非致命 `x-fullscreen-card-hint`。
 
 ---