@gitruck/cli 1.3.3 → 1.3.5

package/docs/reference.md

@@ -1,12 +1,12 @@
-# Agent、配置与命令参考
-
-`project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080` 在本地组装分段工程，不上传原片、不自动合成声音。清单示例：
-
-```json
-{"version":1,"segments":[{"kind":"live","source":"原片.mp4","in":3,"out":11},{"kind":"narration","source":"旁白.wav","transcript":"旁白.json"},{"kind":"image","source":"照片.jpg","duration":4}]}
-```
-
-路径相对清单；视频默认保留独立同期声，`keep_audio:false` 关闭；旁白段留同长画面空档。图片段为静帧，运镜先经 `tool image_move` 产视频。文稿用源时基 `utterances:[{st,ed,text}]`；合并文稿逐句绑定素材，供 `split`、`subtitle lay` 随剪辑重投影，切点截断的整句会省略并报告。输出目录必须不存在，已有工程精修走 `patch`，避免覆盖。
+# Agent、配置与命令参考
+
+`project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080` 在本地组装分段工程，不上传原片、不自动合成声音。清单示例：
+
+```json
+{"version":1,"segments":[{"kind":"live","source":"原片.mp4","in":3,"out":11},{"kind":"narration","source":"旁白.wav","transcript":"旁白.json"},{"kind":"image","source":"照片.jpg","duration":4}]}
+```
+
+路径相对清单；视频默认保留独立同期声，`keep_audio:false` 关闭；旁白段留同长画面空档。图片段为静帧，运镜先经 `tool image_move` 产视频。文稿用源时基 `utterances:[{st,ed,text}]`；合并文稿逐句绑定素材，供 `split`、`subtitle lay` 随剪辑重投影，切点截断的整句会省略并报告。输出目录必须不存在，已有工程精修走 `patch`，避免覆盖。
 
 `matrix describe` 的本地视觉交接：`--prepare <工程内目录>` 生成带时码、源指纹与图片哈希的审阅任务，零豆包调用；当前 Agent 看图填写回执后，以相同 `--materials` 或 `--plan` 参数加 `--review <visual-review.json>` 导入。仅明确标记无法完成并给出原因的条目回退豆包；缺答、素材变化或准则不一致会报错，不自动上云。这个接力由 Agent 完成，不要求用户填表。纯本地完成时无需 API Key，回退豆包时需要云端配置。
 
@@ -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` 会把 18 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`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` 会把 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 不再硬编码各家路径。
 
 默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
 
@@ -70,6 +70,7 @@ gtrk skills install --copy
 | ③ | `/gtrk-ai-drama` | （无命令，纯创作） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
 | ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent 纪律硬门，供 ⑤ 的排版避让决策使用 |
 | ⑤ | `/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 pip lay` | 把口播粗剪的切点镜像到同步录的屏录 / 第二机位，铺屏录满幅轨 + 人像画中画副本轨（圆 / 圆角方 / 爱心 / 菱形 / 星形蒙版，可圆角）；纯本地零计费；低置信时产对齐工程让客户端拖齐后 `--resume` |
 | — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4（含 overlay 与 MG 颗粒；颗粒未命中缓存时云渲计费，`--no-particles` 可跳过） |
@@ -87,7 +88,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 替你跑命令。
-> 上面 18 个 `/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 里。
+> 上面 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 里。
 
 **各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
@@ -190,7 +191,7 @@ GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4   # 环境变量，临时关一次（
 
 ### `gtrk long2short` / `gtrk pip` / `gtrk qc` — 常用补充
 
-- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。完整参数见 `gtrk long2short --help`。
+- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕；`--speed-factor 0.5–2.0` 把整体调速（保音高）写进逐 clip 工程（云端不渲染、不加价）；`--camera-move` 让云端把推 / 拉镜头写成主轨片段的缩放关键帧（客户端与剪映可见可改，本地 `gtrk render` 与 PR 工程不呈现；`clips.md` 标「运镜 N 处」），之后 `gtrk patch` 裁剪 / 切分会同步维护关键帧。产物根另落整片转写 `json/transcript.json`，可对任一 clip 上客户端字幕轨：`gtrk subtitle lay --gtrk <clip 目录>/gtrk/<工程>.gtrk --transcript <产物根>/json/transcript.json --language <源语种>`（`--language` 为云端拆行语种，缺省 zh-CN）。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。完整参数见 `gtrk long2short --help`。
 - `gtrk pip lay`：把同步录制的屏录或第二机位按口播剪点铺成画中画。两源需有可对齐的公共声音；低置信时先在客户端校准，再按提示恢复。运行 `gtrk pip lay --help` 查看输入、形状、位置和偏移参数。
 - `gtrk qc <成片>`：检查闪帧、黑帧、冻结、音量和同步问题；用 `--gtrk` 提供工程上下文，`--fail-on` 控制管线门槛。检查结论供定位问题，不自动替你修片。
 
@@ -291,8 +292,8 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--to <sec\|Nf>` | `move` 的落点 | — |
 | `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | `trim` 的五种语义（前两个相对、中两个绝对、`--slip` 只换源窗） | — |
 | `--cut <sec\|Nf>` | `split` 的切点。⚠️ 与寻址用的 `--at` 是两个参数 | — |
-| `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
-| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨 | — |
+| `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
+| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨 | — |
 | `--total <sec\|Nf\|max>` | `set` 的顶层总长（工程级 op，与元素寻址互斥） | — |
 | `--ops <file\|->` | 批量事务：一次读、全算、全校验、一次写；任一条失败**零写** | 关 |
 | `--dry-run` | 只算与校验、不写文件 | 关 |
@@ -330,8 +331,8 @@ gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt -
 | `--lay <n>` | 候选铺轨数：平铺 N 条 B-roll 候选轨（`0` = 只出 plan 不铺轨） | `1` |
 | `--top-k <n>` | 每 query 候选数上限（覆盖派单 shots；服务端上限 50） | 派单值 |
 | `--material-class <c>` | 素材类型 `real_shot` \| `concept`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
-| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——留空处**露黑底垫轨**（默认铺；除非 `--no-black-bed` 才露主轨）。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
-| `--no-black-bed` | 不铺纯黑底垫轨（默认铺一条） | 默认铺 |
+| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——口播工程里留空处由候选轨**补纯黑片**。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
+| `--black-bed` | 旧形态：铺一条纯黑底垫轨、候选片段不带底板（给不认片段底板的老版客户端过渡用）；`--no-black-bed` 已是缺省（无操作） | 关 |
 | `--force-relay` | 候选轨已被你在客户端编辑过时仍强剥重铺（缺省会拒铺并保留那条轨）——**会删掉已确认原片的 `broll-raw-*` 素材登记、盘上原片成孤儿** | 关 |
 | `--arrange <m>` | **B-roll 编排取数路**，**按素材来源自动定档、一般不用传**：铺你自己电脑里的素材 → `cloud`（编排在云端做，按「编排量」计费，跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 → `local`（编排仍在本机、不计费，逐字不动）。`shadow` 是观测档：本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` 不受理（传了报参数错）；云端拿不到产物时**直接报错**，不会悄悄换算法把活干完 | 按素材来源自动 |
 | `--arrange-qc` | **编排期质检**（缺省关）：落轨**之前**就查每个 beat 的卡点句「画面有没有给到稿子说的东西」，没给到就换候选重排，最多 2 轮，到限即交付并如实登记还差哪几句。全程零渲染——替代「铺完 → 渲 → 看 → 重铺 → 再渲」那两轮。⚠️ 判定走素材理解口、**按帧计费**（每个卡点句 1 帧/轮，命中判定缓存的不重复计费），跑前报预估并征求确认（`--yes` 跳过）。与 `--arrange` 正交：本机档与云端档都能开 | 关 |
@@ -395,7 +396,9 @@ 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` 字段。
 >
-> **纯黑底垫轨**：默认在候选轨之下、口播主轨之上铺满已落成的 beat 包络，避免 B-roll 留空处露出底下画面。候选轨未填满的部分会形成「黑底空洞」；`--json` 恒出 `lay.blackBedHoleSec` 与 `lay.blackBedHoles`，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时给非致命告警。可调 `--score-floor`、改用 `--no-black-bed` 或在客户端补片。素材落在 `assets/builtin/solid-000000-<W>x<H>.png` 并幂等复用；换片请拖到候选轨，不要拖到黑底条。客户端 0.2.10+ 拖到黑底条会直接拒绝，旧客户端先升级；不需要黑底时用 `--no-black-bed` 重跑。
+> **片段底板（缺省）**：每个候选片段自带纯黑底（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` 并幂等复用。
+>
+> **纯黑底垫轨（`--black-bed`，旧形态）**：在候选轨之下、口播主轨之上铺满已落成的 beat 包络，候选片段不带底板；空洞口径与数值同上。老工程里已有的黑底轨在下次缺省重铺时被换成片段底板。
 
 **本地素材模式（`matrix index` / `--local`）**：素材不必入云端素材库，用你本地的素材文件夹（视频+图片混合）直接检索铺轨：
 
@@ -414,7 +417,7 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 - **看点准则**：`--highlight-rubric <text|@file>`（describe 与 lay 同参，≤2000 字符，`@<路径>` 从文件读）给看点分（`--highlight-weight`）指定**评判基准**——垂类图纸各持一份（美食判分量对比/价格实物，旅拍判奇观地貌/极端天候）。**不传 = 整个字段不上行、服务端走领域无关缺省，与本参数引入前逐字节一致**。看点分按准则分桶缓存：换准则只重打分、客观描述缓存照常复用不被覆盖；`describe --plan` 会把本轮准则的 `rubric_hash` 钉进 plan，`lay` 据此自动取同一个桶（无需重复传参），两者不同源时**硬失败**而不是静默择一。⚠️ 换准则要重新打分就得重新看片（按张计费）——免看片的文本级重打分要等服务端轻通道，现在没有。
 - **索引参数与量纲**：`--scene-threshold` 调场景切分粒度、`--stability-threshold` 固定机位判稳收敛抽帧、`--rebuild` 强制重建（理解缓存不清）；索引跨机不可移植（键=绝对路径，换机重跑 index 即可）。本地 score 量纲与云端不同（完美命中可低至 ~0.25），`--score-floor` 别按云端直觉调高。
 
-**`gtrk matrix material "<词>"`（通用三态素材检索）**：与上面的 B-roll 检索并列的第二条线，出**整条素材**的下载直链（不是段落）——`--scope clip|image|audio`（缺省 `audio`，BGM 主场）、`--commercial-only` 只搜可商用（**按需收紧的显式开关，缺省不带**）、`--min-duration/--max-duration` 按成片时长挑、`--top-k`（缺省 5，服务端上限 50）、`--diversity` 去同质、`--json` 机读、`--out` 落盘。
+**`gtrk matrix material "<词>"`（通用三态素材检索）**：与上面的 B-roll 检索并列的第二条线，出**整条素材**的下载直链（不是段落）——`--scope clip|image|audio`（缺省 `audio`，BGM 主场）、`--commercial-only` 只搜可商用（**按需收紧的显式开关，缺省不带**）、`--min-duration/--max-duration` 按成片时长挑、`--top-k`（缺省 5，服务端上限 50）、`--diversity` 去同质、`--json` 机读、`--out` 落盘。`--scope clip|image` 时另附 **Pexels 补充结果**，单列在 `pexels_results`、不计入候选数（`--no-stock` 关闭）；补充素材直接用 `download_url` 下载（不走 `matrix fetch`），引用时保留摄影师署名与 Pexels 链接。
 
 > ⚠️ **`is_copyright` 读作「能不能商用」，不是「有没有被版权保护」**：`true` = **可商用**（自有 ∪ 已授权），`false` = **不可商用**。
 >
@@ -470,6 +473,39 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 > **aux 叠层颗粒**：`gtrk split` 若在某 beat 的 `aux_layers` 派了 `overlay` 颗粒，会派生 `<beat>-aux<n>` 合成条目进 `dispatch.mg`——`gtrk mg` 一并铺，实现「同段既有底轨主视觉、又叠透明概念图解」。
 > **双读兼容**：`dispatch.mg`（读旧 `rrv_mg`）、源目录 `mg/`（读旧 `rrv/`）、素材前缀 `mg-`（读旧 `rrv-`）——去品牌化前的既有工程零迁移。
 
+### `gtrk composite` — 合成层（plan / review / scaffold / build / lint / lay / shots / bake）
+
+粗剪、B-roll、字幕都定了之后，把选定时间窗做成**合成颗粒**：一段时间内的整个画面由一颗代码颗粒接管，讲者与 B-roll 作为槽位由客户端画进去。由 `/gtrk-composite` 驱动（含编排规则与两个检查点）；纯本地、零计费。
+
+```bash
+gtrk composite plan --project <工程> [--mode 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 scaffold --project <工程> [--only W03] [--force]
+gtrk composite shots --project <工程> --material <素材 id 或文件> [--around <秒> --span <秒> | --from <秒> --to <秒>] [--every <秒>]
+gtrk composite build --project <工程> [--only cp-w03] [--theme <css>] [--materials <json>]
+gtrk composite lint --project <工程> [--only cp-w03] [--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] [--json]
+gtrk composite bake --input <快照.gtrk> --base <工程 gtrk 目录> [--progress jsonl]
+gtrk composite bake --abi
+```
+
+- `plan`：候选窗口写进 `.gtrk` 的 `struct_meta.composite`（只动这一个键、原子写回；与 `gtrk split` 写 `struct_meta.split` 同一套做法），客户端大纲 CP 行据此画提案块；另出审稿稿 `composite/plan.md`。重跑保留已做的、不再提用户不要的。
+- `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`）。
+- `lay`：按自产身份幂等铺进 beat 轨最上层、补登记素材、窗口记为已做；过期颗粒拒铺；用户在客户端改过的同 id 颗粒不覆盖。
+- `bake`：把已铺的合成颗粒在本机**烘焙成不透明视频**，产物落 `gtrk/assets/composite-bake/<键>.mp4`；输入（槽位画面、字幕、锚点）按**当前时间线**现算。纯本地、零计费。
+  - **浏览器**：优先钉定版本的 chrome-headless-shell（确定性出帧、最快）；没有时退回本机 Chrome / Edge（截图模式，更慢、并发降一档）。**不会静默下载**：`gtrk deps install --browser` 或本命令 `--install-browser` 显式授权才装（约 110 MB）。`GTRK_CHROME` 可指定浏览器。
+  - **并发**：常驻工作页分段并发，缺省 `min(逻辑核数/3, 6)`，`--workers` 覆盖；分段与顺序烤出的画面逐位相同。
+  - **缓存**：键含颗粒、现算输入、素材文件指纹（大小 + 修改时间）、帧率、浏览器版本与编码参数；命中直接复用。改并发不换键。
+  - **帧率**：缺省 = 工程帧率；`--fps` 指定（例如导出 30fps）。帧数 = `ceil(窗口 × fps)`，盖满整个窗口。
+  - **退出码**：0 全部成功（含命中缓存）/ 1 有颗失败（其余照常，逐颗给原因）/ 2 参数或环境错误 / 130 被取消。
+  - **机读**：`--progress jsonl` 逐行输出 `type` 为 `start` / `browser` / `prep` / `progress` / `composite` / `cancelled` / `done` 的事件，相邻两行不超过 1 秒；此模式下**关闭 stdin 即取消**（其它模式不认 stdin）。`--abi` 只输出 `{abi, version}`，不读工程。`--input <快照> --base <目录>`：以快照为时间线来源（客户端交未保存状态用），相对素材路径与产物落点按 `--base` 解析，快照不回写。
+- `gtrk render` / `gtrk project export` 会先烘焙工程里的合成颗粒：烘焙成功的那段以烘焙视频出画（剪映 / Pr 里是该层位上的一段视频），**时段整段落在合成窗口内的 MG / OV 不再预渲、不计费**；烘焙失败（素材丢失、找不到浏览器等）的那颗按粗剪出画并点名原因，不拦导出。
+
 ### `gtrk project init` / `gtrk audio lay` / `gtrk audio tighten` — 音频驱动工程零件（配音先行）
 
 不从口播毛片、而从**一条配音**起盘的工程入口：先有配音（TTS 合成或自己录的），`project init` 建好 `.gtrk` 工程，之后 `gtrk split --project` 投影拆分照常接成片流水线；`audio lay` 则给任意工程补音频轨（BGM/配乐）；`audio tighten` 收紧配音的句间停顿。
@@ -507,6 +543,35 @@ gtrk project export --gtrk <工程文件> --formats jianying,xml --out <产物
 
 颗粒预渲前会先完成 HTML、路径和缓存预检；预检失败不会提交任何云任务。单颗粒渲染或下载失败会记录在 `result.json`，其余格式继续导出。`--json` 输出单行结果 JSON，人读日志走 stderr。
 
+**只在客户端出画的东西**（客户端加的文字、贴纸、图形、特效与画布背景）进不了这次导出的工程文件：工程里有它们时提交前提示一次哪几类、各几个；有文字时指向客户端导出剪映草稿（客户端会把文字带成可编辑字幕）。`result.json` 的 `droppedByContract.clientOnly` 记分类计数，`clientVisualElementCount` 为元素个数（此前误按车道数计）。
+
+**片段底板**（`background_fill`）：剪映 / CapCut 的最底层轨原生承接；其它轨由云端在该片段之下插一条辅助轨——纯色 = 一段同色纯色图，模糊 = 同一段素材（同一时间段、静音、铺满画布）加剪映「模糊」特效。Pr 工程全部轨同样处理，模糊用高斯模糊；FCPXML / OTIO 只做纯色，模糊降级为纯黑并在日志里点名（素材缺尺寸信息、没法铺满时，剪映 / Pr 也降级）。片段自己就铺满画布时不垫底。纯色图引用产物目录里的 `solid-<rrggbb>-<W>x<H>.png`，命令在写工程文件之前把它们写好——**挪动或删除产物目录会让这些纯色图脱机**。`result.json` 的 `backgroundFill` 记录写出的纯色图与降级告警（工程不带底板时整键缺席）。
+
+### `gtrk project background` — 片段底板（模糊底 / 纯色）
+
+缺省给**主轨每个视频 / 图片片段**写片段级底板 `background_fill`（gtrk 契约字段）：片段之下、仅在其时长内铺满画布，模糊 = 片段自己画面铺满后的模糊。典型用途是横屏源进竖屏画布时用模糊底替代黑边。客户端可逐片段或多选批量改；从客户端或 `gtrk project export` 导出的剪映草稿原生承接（主轨是最底层轨），Pr 工程用同一素材铺满加高斯模糊，FCPXML / OTIO 降级为纯黑并提示，本地 `gtrk render` 承接。叠加轨片段与空档不写不改，`struct_meta.client_background` 不动（回执点名它是否仍在）。零计费、不访问云端。
+
+`--scope canvas` 走旧的画布级写法：只改 `struct_meta.client_background` 一个键（客户端打开即按它呈现画布背景；剪映 / PR 工程与本地渲染不承接）。
+
+```bash
+gtrk project background --gtrk <工程文件> --blur
+gtrk project background --project <工程目录> --blur --intensity 300
+gtrk project background --gtrk <工程文件> --color "#1A1A1A"
+gtrk project background --gtrk <工程文件> --clear
+```
+
+| 参数 | 作用 |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | 定位工程，规则同 `project export` |
+| `--blur` | 模糊底：片段自己画面铺满后的模糊（画布级 = 主轨画面的模糊副本） |
+| `--intensity <n>` | 配合 `--blur`，0–1000，缺省 200（逐片段须为整数） |
+| `--color <#RRGGBB>` | 纯色底（六位十六进制） |
+| `--clear` | 去掉底板（逐片段 = 去掉主轨片段的 `background_fill`；画布级 = 删 `client_background`，回到客户端缺省黑底） |
+| `--scope <clips\|canvas>` | 作用面：`clips`（缺省）主轨逐片段；`canvas` 画布级（旧写法） |
+| `--dry-run` | 只校验并回执将写入的值，不写文件 |
+
+三种模式恰好选一个。写回走原子替换与内容 revision 守卫，其余内容原样保留；值未变时不写盘。`--json` 回执含写前写后 revision。
+
 > **`--beat-align`**：按表格中的高潮点锚定规则工作；显式 `--climax` 会覆盖自动判据。该模式会调用 `audio_music_analyze` 并产生相应计费。
 
 
@@ -632,11 +697,12 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 把 `.gtrk` 当 EDL 用本地 ffmpeg 出成片。**素材一律取本地原片**（`materials[].path`），云端不产成片。
 
-**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。
+**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。合成颗粒先在本机烘焙（见 `gtrk composite bake`，零计费），以烘焙视频叠在原层位；被它整段盖住的 MG 不再云渲。
 
 - **可见性只读 `hidden` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
 - **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。
 - overlay 素材本地缺失（如 B-roll 代理没下全）**只降级不阻断**：该 clip 不叠 + 告警，片子照出。
+- **只在客户端出画的东西不进片**：客户端加的文字（含 `gtrk subtitle lay` 铺的字幕）、贴纸、图形、特效，以及画布背景（`gtrk project background --scope canvas`）。工程里有它们时，渲染前提示一次哪几类、各几个，并指向客户端本地导出；不拦、不改渲染。`--json` 结果恒带 `clientOnly`（`text / sticker / graphic / effect / other` 计数与 `background` 布尔，全零也给）。
 
 **颗粒那一段有计费**（本命令唯一的云端出口）：
 
@@ -663,8 +729,8 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 - `gtrk install [--api-key … -y --skill-agents codex,cursor --all-agents --copy-skills --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
 - `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
 - `gtrk doctor` — 体检（含 CLI 版本 / 有无新版）。
-- `gtrk deps status` — 查 ffmpeg/ffprobe 与渲染字体的**当前来源**（`--ffmpeg-path` / `~/.gitruck` / 系统 / 缺失）、版本、授权与源码地址。
-- `gtrk deps install [--ffmpeg] [--font] [--force]` — 从同合云镜像安装运行时资产，**已存在则跳过**。
+- `gtrk deps status` — 查 ffmpeg/ffprobe、渲染字体与合成烘焙浏览器的**当前来源**（`--ffmpeg-path` / `~/.gitruck` / 系统 / 缺失）、版本、授权与源码地址。
+- `gtrk deps install [--ffmpeg] [--font] [--browser] [--force]` — 从同合云镜像安装运行时资产，**已存在则跳过**。不带开关装 ffmpeg 与字体；`--browser` 另装合成烘焙用的钉定版本 chrome-headless-shell（约 110 MB，落 `~/.gitruck/browsers`，BSD 许可，来源与源码见分发点 `SOURCE.md`），**只在显式点名时装**。
   - **不会静默自动下载**：任何缺失路径只报错并指向本命令（包体 30–90 MB，且分发物涉及授权，须由用户/agent 显式触发）。
   - 下载一律 https + **sha256 强校验**，校验不过即丢弃、不落地；解包调**系统 tar**（Win10+/macOS/Linux 自带），不引第三方解压依赖。
   - 定位优先级不变：`--ffmpeg-path` → `~/.gitruck/ffmpeg` → 系统 PATH。镜像只填中间那一格，**不越过你自己装的 ffmpeg**。
@@ -677,4 +743,4 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 ### 视频高光发现（内部验收）
 
-`gtrk tool video_highlight <视频> --out <工程目录> --json`：本地224p/4fps无声代理，只上传代理；返回分请求三秒候选。3秒以上、30分钟以内。候选须按制片语义复核；不可跨请求比较分数。服务失败不冒充成功，Vlog可继续Agent素材理解。尚未开放外部收费。
+`gtrk tool video_highlight <视频> --out <工程目录> [--no-audio] --json`：本地生成448p/4fps分析代理（缺省附单声道低码率原声，`--no-audio` 去声），只上传代理、原片不上传；返回分请求三秒候选。3秒以上、30分钟以内。候选须按制片语义复核；不可跨请求比较分数。服务失败不冒充成功，Vlog可继续Agent素材理解。尚未开放外部收费。

package/docs/workflow.en.md

@@ -1,72 +1,72 @@
-# From footage to an editable project
-
-[Back to README](../README.en.md) · [Command reference](reference.en.md) · [简体中文](workflow.md)
-
-## Choose an entry point
-
-| Input | Entry point | First deliverable |
-| --- | --- | --- |
-| One or more talking-head recordings, optionally with external audio | `gtrk-talking-head` Skill; `gtrk oralcut` for a rough cut only | Aligned, joined and roughly edited project plus transcript |
-| An existing script | `gtrk-voiceover` Skill | Voiceover, sentence timing and an audio-driven project |
-| Podcast, interview, course or livestream replay | `gtrk-long2short`; `gtrk-live-slicing` Skill for long replays | A separate project for each highlight |
-| Film, gameplay, travel or restaurant footage | `gtrk-narration`, or travel/food presets | A retold script, voiceover and assembled visuals |
-| Location footage with live sound to preserve | `gtrk-vlog-docu` Skill | A documentary project alternating live sound and narration |
-
-The per-source limit for `oralcut` / `long2short` is **2 hours**. Longer sources are rejected before extraction or upload; split long replays first. Tutorials: [talking heads](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) · [voiceover](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) · [long to short](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) · [narrated videos](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre).
-
-## Follow the production order
-
-1. **Set the content and production plan.** Check footage, script, aspect ratio, voice and visual direction. Listen to and adjust a voiceover before building its timeline.
-2. **Create the project and transcript.** Rough-cut, select highlights or build from voiceover. Review pacing and content before packaging.
-3. **Arrange visuals.** Dispatch segments and search platform or local footage. B-roll and AI reenactment clips are both base visuals and can be prepared separately.
-4. **Settle the composition.** Choose candidate tracks in the client and inspect faces, subjects and safe areas. You may explicitly defer missing AI clips, then revisit affected compositions when they return.
-5. **Add motion graphics.** Place titles, diagrams and transparent overlays around the settled footage without obscuring its subjects.
-6. **Music, captions and delivery.** Add captions after the timeline settles, then preview, check and export video or supported editing projects.
-
-Optional stages can be skipped. Quick mode groups key decisions; ask for step-by-step progress when you want to review each stage. Checkpoints and cost confirmations follow the relevant Skill.
-
-## Where to chat and where to edit
-
-Conversations currently happen in your own AI agent; the desktop client has no built-in AI chat. The agent creates or updates `.gtrk` through the CLI. The Windows client opens that same project for preview, selection and refinement.
-
-Give further requests to your agent or make manual changes in the client. Scripts can also render an existing project with `gtrk render`; opening the desktop client is not a prerequisite for every render.
-
-## Deliverables and export boundaries
-
-| Deliverable | How to use it | Boundary |
-| --- | --- | --- |
-| `gtrk/project.gtrk` | Open in the desktop client | Keeps the multitrack structure and supported motion graphics information |
-| Jianying drafts from talking-head / long-to-short cuts | Configure the draft folder during setup; open from Jianying's project list | Requires both fixed filenames, `draft_content.json` and `draft_meta_info.json` |
-| `xml/premiere.xml` from those cuts | Import into Premiere | Describes the corresponding rough cut; it does not promise lossless transfer of every later client effect |
-| Jianying drafts exported by the client | Continue refining a packaged project | Preserves supported tracks and captions; graphics may be baked into video and are no longer editable as the original HTML |
-| MP4 from `gtrk render` | Playback, review or publishing | Composites visible video overlays and graphics; hidden tracks stay out. This command does not export Jianying drafts |
-
-Client-specific elements, complex effects and third-party formats are not universally interchangeable. Check the rendered video for final appearance, and keep `.gtrk` plus its media for further editing.
-
-## Uploads and costs
-
-- **Talking-head and long-to-short project workflows:** originals stay local. Extracted audio is uploaded by default; visual assistance or smart split-screen uses a compressed proxy.
-- **Local B-roll:** original media stays local. Understanding may send sampled frames; cloud arrangement uses structured information and is billed under its own rules.
-- **Individual cloud tools:** upload requirements vary. Cloud video processing may require the video itself.
-- **CLI rendering:** video composition is local. Uncached graphics require cloud rendering with a cost prompt. `--no-particles` skips those graphics while still compositing other visible video overlays.
-- **AI generation:** external model services, separate production desks and your agent follow their own pricing.
-
-Prices and free allowances may change. Check the [billing guide](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd) and runtime pricing.
-
-## Recovery and troubleshooting
-
-| Situation | Action |
-| --- | --- |
-| Skills do not appear | Open a new agent session; use `gtrk skills install` if needed. Not every agent uses a `/` menu |
-| Configuration, connection or runtime problem | Run `gtrk doctor`; check `gtrk deps status` before explicitly installing missing FFmpeg assets |
-| Draft is missing in Jianying | Check the draft root and both fixed filenames listed above |
-| Talking-head task completed, but results are missing | Use the recovery command below, or read `result.json` in the output folder before rerunning a cloud job |
-| A long task timed out | Timeout does not mean cancellation. Keep `task.json` / `result.json` and query or recover by task ID |
-| Upgrade needed | `gtrk upgrade` upgrades the CLI and refreshes Skills; `npm i -g` alone does not refresh agent Skills |
-| An older project has compatibility problems | Check the [CHANGELOG](../CHANGELOG.md) and follow the relevant version instructions |
-
-```bash
-gtrk oralcut-result <taskId> --out <output-directory>
-```
-
-See the [command reference](reference.en.md) for parameters, JSON receipts, billing confirmation and recovery limits.
+# From footage to an editable project
+
+[Back to README](../README.en.md) · [Command reference](reference.en.md) · [简体中文](workflow.md)
+
+## Choose an entry point
+
+| Input | Entry point | First deliverable |
+| --- | --- | --- |
+| One or more talking-head recordings, optionally with external audio | `gtrk-talking-head` Skill; `gtrk oralcut` for a rough cut only | Aligned, joined and roughly edited project plus transcript |
+| An existing script | `gtrk-voiceover` Skill | Voiceover, sentence timing and an audio-driven project |
+| Podcast, interview, course or livestream replay | `gtrk-long2short`; `gtrk-live-slicing` Skill for long replays | A separate project for each highlight |
+| Film, gameplay, travel or restaurant footage | `gtrk-narration`, or travel/food presets | A retold script, voiceover and assembled visuals |
+| Location footage with live sound to preserve | `gtrk-vlog-docu` Skill | A documentary project alternating live sound and narration |
+
+The per-source limit for `oralcut` / `long2short` is **2 hours**. Longer sources are rejected before extraction or upload; split long replays first. Tutorials: [talking heads](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) · [voiceover](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) · [long to short](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) · [narrated videos](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre).
+
+## Follow the production order
+
+1. **Set the content and production plan.** Check footage, script, aspect ratio, voice and visual direction. Listen to and adjust a voiceover before building its timeline.
+2. **Create the project and transcript.** Rough-cut, select highlights or build from voiceover. Review pacing and content before packaging.
+3. **Arrange visuals.** Dispatch segments and search platform or local footage. B-roll and AI reenactment clips are both base visuals and can be prepared separately.
+4. **Settle the composition.** Choose candidate tracks in the client and inspect faces, subjects and safe areas. You may explicitly defer missing AI clips, then revisit affected compositions when they return.
+5. **Add motion graphics.** Place titles, diagrams and transparent overlays around the settled footage without obscuring its subjects.
+6. **Music, captions and delivery.** Add captions after the timeline settles, then preview, check and export video or supported editing projects.
+
+Optional stages can be skipped. Quick mode groups key decisions; ask for step-by-step progress when you want to review each stage. Checkpoints and cost confirmations follow the relevant Skill.
+
+## Where to chat and where to edit
+
+Conversations currently happen in your own AI agent; the desktop client has no built-in AI chat. The agent creates or updates `.gtrk` through the CLI. The Windows client opens that same project for preview, selection and refinement.
+
+Give further requests to your agent or make manual changes in the client. Scripts can also render an existing project with `gtrk render`; opening the desktop client is not a prerequisite for every render.
+
+## Deliverables and export boundaries
+
+| Deliverable | How to use it | Boundary |
+| --- | --- | --- |
+| `gtrk/project.gtrk` | Open in the desktop client | Keeps the multitrack structure and supported motion graphics information |
+| Jianying drafts from talking-head / long-to-short cuts | Configure the draft folder during setup; open from Jianying's project list | Requires both fixed filenames, `draft_content.json` and `draft_meta_info.json` |
+| `xml/premiere.xml` from those cuts | Import into Premiere | Describes the corresponding rough cut; it does not promise lossless transfer of every later client effect. If the *Link Media* dialog appears, check the *Media Path* column after relinking — Premiere's automatic relink matches by file name and may pick a same-named file from another project |
+| Jianying drafts exported by the client | Continue refining a packaged project | Preserves supported tracks and captions; graphics may be baked into video and are no longer editable as the original HTML |
+| MP4 from `gtrk render` | Playback, review or publishing | Composites visible video overlays and graphics; hidden tracks stay out. This command does not export Jianying drafts |
+
+Client-specific elements, complex effects and third-party formats are not universally interchangeable. Check the rendered video for final appearance, and keep `.gtrk` plus its media for further editing.
+
+## Uploads and costs
+
+- **Talking-head and long-to-short project workflows:** originals stay local. Extracted audio is uploaded by default; visual assistance or smart split-screen uses a compressed proxy.
+- **Local B-roll:** original media stays local. Understanding may send sampled frames; cloud arrangement uses structured information and is billed under its own rules.
+- **Individual cloud tools:** upload requirements vary. Cloud video processing may require the video itself.
+- **CLI rendering:** video composition is local. Uncached graphics require cloud rendering with a cost prompt. `--no-particles` skips those graphics while still compositing other visible video overlays.
+- **AI generation:** external model services, separate production desks and your agent follow their own pricing.
+
+Prices and free allowances may change. Check the [billing guide](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd) and runtime pricing.
+
+## Recovery and troubleshooting
+
+| Situation | Action |
+| --- | --- |
+| Skills do not appear | Open a new agent session; use `gtrk skills install` if needed. Not every agent uses a `/` menu |
+| Configuration, connection or runtime problem | Run `gtrk doctor`; check `gtrk deps status` before explicitly installing missing FFmpeg assets |
+| Draft is missing in Jianying | Check the draft root and both fixed filenames listed above |
+| Talking-head task completed, but results are missing | Use the recovery command below, or read `result.json` in the output folder before rerunning a cloud job |
+| A long task timed out | Timeout does not mean cancellation. Keep `task.json` / `result.json` and query or recover by task ID |
+| Upgrade needed | `gtrk upgrade` upgrades the CLI and refreshes Skills; `npm i -g` alone does not refresh agent Skills |
+| An older project has compatibility problems | Check the [CHANGELOG](../CHANGELOG.md) and follow the relevant version instructions |
+
+```bash
+gtrk oralcut-result <taskId> --out <output-directory>
+```
+
+See the [command reference](reference.en.md) for parameters, JSON receipts, billing confirmation and recovery limits.

package/docs/workflow.md

@@ -1,72 +1,72 @@
-# 从素材到可编辑工程
-
-[返回首页](../README.md) · [命令参考](reference.md) · [English](workflow.en.md)
-
-## 先选入口
-
-| 输入 | 入口 | 首轮交付 |
-| --- | --- | --- |
-| 真人口播，一条或多条，可带外录音频 | `gtrk-talking-head` Skill；只粗剪用 `gtrk oralcut` | 对轨、拼段、粗剪后的工程与文稿 |
-| 已有文字稿 | `gtrk-voiceover` Skill | 配音、句级时码与音频驱动工程 |
-| 播客、访谈、课程或直播回放 | `gtrk-long2short`；超长直播用 `gtrk-live-slicing` Skill | 每个高光独立的剪辑工程 |
-| 影视、游戏、旅拍或探店素材 | `gtrk-narration`，或旅拍、美食预设 | 提炼后的解说稿、配音与配画面工程 |
-| 保留现场同期声的素材集 | `gtrk-vlog-docu` Skill | 同期声与旁白交替的纪实工程 |
-
-`oralcut` / `long2short` 的单次源片上限为 **2 小时**，超过会在抽取与上传前拒绝；超长回放先分段。完整教程：[口播](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) · [配音](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) · [长剪短](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) · [解说](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre)。
-
-## 按创作顺序推进
-
-1. **确定内容和制作方案。** 核对素材、稿件、画幅、声音和视觉方向。配音先试听调整，满意后再建时间线。
-2. **拿到工程与文稿。** 粗剪、选段或从配音建工程；先检查节奏与内容，再继续包装。
-3. **安排画面。** 分段派单，检索平台或本地素材。B-roll 与 AI 再现片段都属于底层画面，可分别准备。
-4. **确定底层构图。** 在客户端挑选候选轨，检查人脸、主体和安全区。AI 片段未回轨时，可明确先跳过，并在回轨后复查相关构图。
-5. **叠加动效。** 按最终画面安排字卡、图解和透明叠层，避免遮住主体。
-6. **配乐、字幕与交付。** 时间线确定后上字幕，预览、质检、导出成片或支持的剪辑工程。
-
-可选环节可以省略。快速成片会集中确认关键选择；需要逐步看结果时，对 Agent 说“逐步来”。具体检查点与费用确认以对应 Skill 为准。
-
-## 在哪里对话，在哪里编辑
-
-当前在自己的 AI Agent 里对话，客户端没有内置 AI 对话框。Agent 通过 CLI 创建或修改 `.gtrk`；Windows 客户端打开同一工程，供你预览、挑选和精修。
-
-想调整某一步，可以把具体要求交回 Agent；想自己改，可以在客户端操作。自动化或脚本也可用 `gtrk render` 渲染已有工程，无需把“打开客户端”当作每次渲染的前置条件。
-
-## 交付物与导出边界
-
-| 交付物 | 怎么用 | 边界 |
-| --- | --- | --- |
-| `gtrk/project.gtrk` | 客户端打开 | 保存多轨结构与支持的动态图等信息 |
-| 口播／长剪短的剪映草稿 | 安装时配置草稿目录，完成后在剪映项目列表打开 | 草稿目录内需要固定名 `draft_content.json` 和 `draft_meta_info.json` 成对存在 |
-| 口播／长剪短的 `xml/premiere.xml` | 在 Premiere 导入 | 是对应粗剪工程，不代表后续所有客户端效果都可无损互转 |
-| 客户端导出的剪映草稿 | 完整包装后继续精修 | 按当前导出能力保留支持的轨道与字幕；动态图可能烤成视频素材，不能当作原 HTML 继续编辑 |
-| `gtrk render` 输出的 MP4 | 播放、审核、发布 | 合成可见视频叠层与动态图；关闭的轨道不入片。该命令不导出剪映草稿 |
-
-客户端专有元素、复杂效果和第三方工程格式不能笼统视为全部兼容。需要保留最终视觉效果时，检查渲染成片；需要继续编辑时，同时保留 `.gtrk` 与素材。
-
-## 上传与费用
-
-- **口播粗剪、长剪短工程流程：** 原片保留本地，默认上传抽出的音频。视觉辅助或智能分屏改传压缩代理。
-- **本地 B-roll：** 原始素材保留本地；理解可能发送抽帧，云端编排使用结构化信息并按相应规则计费。
-- **单点云端工具：** 上传要求取决于工具，例如云端视频处理可能需要视频本体。
-- **CLI 渲染：** 视频合成在本地；未命中缓存的动态图需云端渲染，先提示费用。`--no-particles` 可跳过动态图，其他可见视频叠层仍正常合成。
-- **AI 生成：** 外部模型服务、独立工作台与 Agent 的费用按各自规则结算。
-
-实际价格和免费额度会变化，查看[计费说明](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd)及运行时查询结果。
-
-## 常用恢复与排障
-
-| 情况 | 处理 |
-| --- | --- |
-| Skills 未出现 | 新开 Agent 会话；必要时 `gtrk skills install`。不同 Agent 的 Skills 入口不一定是 `/` 菜单 |
-| 配置、连接或环境有问题 | `gtrk doctor`；缺 FFmpeg 时先 `gtrk deps status`，再按提示显式安装 |
-| 剪映里没有草稿 | 核对草稿根目录及两个固定文件名，详见上表 |
-| 口播任务已完成，但结果丢失 | 使用下方恢复命令，或读取产物目录中的 `result.json`，不要先重跑云端 |
-| 长任务等待超时 | 超时不等于任务取消；保存 `task.json` / `result.json`，按任务 ID 查询或恢复 |
-| 需要升级 | `gtrk upgrade` 同时升级 CLI、刷新 Skills；仅 `npm i -g` 不会刷新 Agent 中的 Skills |
-| 旧工程有兼容问题 | 先查 [CHANGELOG](../CHANGELOG.md)，按对应版本说明修复 |
-
-```bash
-gtrk oralcut-result <taskId> --out <output-directory>
-```
-
-详细参数、JSON 回执、计费确认和恢复限制见[命令参考](reference.md)。
+# 从素材到可编辑工程
+
+[返回首页](../README.md) · [命令参考](reference.md) · [English](workflow.en.md)
+
+## 先选入口
+
+| 输入 | 入口 | 首轮交付 |
+| --- | --- | --- |
+| 真人口播，一条或多条，可带外录音频 | `gtrk-talking-head` Skill；只粗剪用 `gtrk oralcut` | 对轨、拼段、粗剪后的工程与文稿 |
+| 已有文字稿 | `gtrk-voiceover` Skill | 配音、句级时码与音频驱动工程 |
+| 播客、访谈、课程或直播回放 | `gtrk-long2short`；超长直播用 `gtrk-live-slicing` Skill | 每个高光独立的剪辑工程 |
+| 影视、游戏、旅拍或探店素材 | `gtrk-narration`，或旅拍、美食预设 | 提炼后的解说稿、配音与配画面工程 |
+| 保留现场同期声的素材集 | `gtrk-vlog-docu` Skill | 同期声与旁白交替的纪实工程 |
+
+`oralcut` / `long2short` 的单次源片上限为 **2 小时**，超过会在抽取与上传前拒绝；超长回放先分段。完整教程：[口播](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) · [配音](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) · [长剪短](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) · [解说](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre)。
+
+## 按创作顺序推进
+
+1. **确定内容和制作方案。** 核对素材、稿件、画幅、声音和视觉方向。配音先试听调整，满意后再建时间线。
+2. **拿到工程与文稿。** 粗剪、选段或从配音建工程；先检查节奏与内容，再继续包装。
+3. **安排画面。** 分段派单，检索平台或本地素材。B-roll 与 AI 再现片段都属于底层画面，可分别准备。
+4. **确定底层构图。** 在客户端挑选候选轨，检查人脸、主体和安全区。AI 片段未回轨时，可明确先跳过，并在回轨后复查相关构图。
+5. **叠加动效。** 按最终画面安排字卡、图解和透明叠层，避免遮住主体。
+6. **配乐、字幕与交付。** 时间线确定后上字幕，预览、质检、导出成片或支持的剪辑工程。
+
+可选环节可以省略。快速成片会集中确认关键选择；需要逐步看结果时，对 Agent 说“逐步来”。具体检查点与费用确认以对应 Skill 为准。
+
+## 在哪里对话，在哪里编辑
+
+当前在自己的 AI Agent 里对话，客户端没有内置 AI 对话框。Agent 通过 CLI 创建或修改 `.gtrk`；Windows 客户端打开同一工程，供你预览、挑选和精修。
+
+想调整某一步，可以把具体要求交回 Agent；想自己改，可以在客户端操作。自动化或脚本也可用 `gtrk render` 渲染已有工程，无需把“打开客户端”当作每次渲染的前置条件。
+
+## 交付物与导出边界
+
+| 交付物 | 怎么用 | 边界 |
+| --- | --- | --- |
+| `gtrk/project.gtrk` | 客户端打开 | 保存多轨结构与支持的动态图等信息 |
+| 口播／长剪短的剪映草稿 | 安装时配置草稿目录，完成后在剪映项目列表打开 | 草稿目录内需要固定名 `draft_content.json` 和 `draft_meta_info.json` 成对存在 |
+| 口播／长剪短的 `xml/premiere.xml` | 在 Premiere 导入 | 是对应粗剪工程，不代表后续所有客户端效果都可无损互转；若弹出「链接媒体」框，链接后在「媒体路径」列核对——Premiere 的自动重新链接按文件名匹配，可能链到别的工程里的同名文件 |
+| 客户端导出的剪映草稿 | 完整包装后继续精修 | 按当前导出能力保留支持的轨道与字幕；动态图可能烤成视频素材，不能当作原 HTML 继续编辑 |
+| `gtrk render` 输出的 MP4 | 播放、审核、发布 | 合成可见视频叠层与动态图；关闭的轨道不入片。该命令不导出剪映草稿 |
+
+客户端专有元素、复杂效果和第三方工程格式不能笼统视为全部兼容。需要保留最终视觉效果时，检查渲染成片；需要继续编辑时，同时保留 `.gtrk` 与素材。
+
+## 上传与费用
+
+- **口播粗剪、长剪短工程流程：** 原片保留本地，默认上传抽出的音频。视觉辅助或智能分屏改传压缩代理。
+- **本地 B-roll：** 原始素材保留本地；理解可能发送抽帧，云端编排使用结构化信息并按相应规则计费。
+- **单点云端工具：** 上传要求取决于工具，例如云端视频处理可能需要视频本体。
+- **CLI 渲染：** 视频合成在本地；未命中缓存的动态图需云端渲染，先提示费用。`--no-particles` 可跳过动态图，其他可见视频叠层仍正常合成。
+- **AI 生成：** 外部模型服务、独立工作台与 Agent 的费用按各自规则结算。
+
+实际价格和免费额度会变化，查看[计费说明](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd)及运行时查询结果。
+
+## 常用恢复与排障
+
+| 情况 | 处理 |
+| --- | --- |
+| Skills 未出现 | 新开 Agent 会话；必要时 `gtrk skills install`。不同 Agent 的 Skills 入口不一定是 `/` 菜单 |
+| 配置、连接或环境有问题 | `gtrk doctor`；缺 FFmpeg 时先 `gtrk deps status`，再按提示显式安装 |
+| 剪映里没有草稿 | 核对草稿根目录及两个固定文件名，详见上表 |
+| 口播任务已完成，但结果丢失 | 使用下方恢复命令，或读取产物目录中的 `result.json`，不要先重跑云端 |
+| 长任务等待超时 | 超时不等于任务取消；保存 `task.json` / `result.json`，按任务 ID 查询或恢复 |
+| 需要升级 | `gtrk upgrade` 同时升级 CLI、刷新 Skills；仅 `npm i -g` 不会刷新 Agent 中的 Skills |
+| 旧工程有兼容问题 | 先查 [CHANGELOG](../CHANGELOG.md)，按对应版本说明修复 |
+
+```bash
+gtrk oralcut-result <taskId> --out <output-directory>
+```
+
+详细参数、JSON 回执、计费确认和恢复限制见[命令参考](reference.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.3.3",
+	"version": "1.3.5",
 	"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/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.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/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/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/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/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:linux": "node scripts/test-linux.mjs",
 		"openspec:gate": "node openspec/gate.mjs",
 		"mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs",