@gitruck/cli 1.3.3 → 1.3.5

package/AGENT.md

@@ -39,28 +39,28 @@
   （如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）。
   需要引用媒体时**用原路径引用**，不做副本。
 - 临时文件（抽帧图 / 中间物等）一律放系统 temp 且**用完即删**（含中断 / 失败路径也要清干净）。
-- **交付物 SHALL 直写工程目录，MUST NOT 中转暂存**。
+- **交付物 SHALL 直写工程目录，MUST NOT 中转暂存**。
   产颗粒 / 产工程 / 产派单稿时，**写入路径本身**就必须是工程目录里的最终路径；
   MUST NOT 先写 agent 自有工作目录（会话工作区 / `work/` / 暂存区）再拷进工程。
-  · 中转本身即违规，体积不构成例外（体积不是豁免理由）；抽帧图等不交付的中间物走系统 temp，用完即删。
-  · 交付物没有暂存态，避免工程正本与副本漂移。
+  · 中转本身即违规，体积不构成例外（体积不是豁免理由）；抽帧图等不交付的中间物走系统 temp，用完即删。
+  · 交付物没有暂存态，避免工程正本与副本漂移。
 
-**在 gtrk-cli 仓库自身里跑真机走查时：**
+**在 gtrk-cli 仓库自身里跑真机走查时：**
 
 - **仓根不落任何产物**。工作区一律 `--out .runs/<名字>`；命令回执与日志一律重定向进
   `.runs/_receipts-<日期>/`，例如
   `gtrk audio lay ... > .runs/_receipts-260823/audio-lay-out.json 2> .runs/_receipts-260823/audio-lay-stderr.log`。
 - **MUST NOT** 使用 `> foo-out.json 2> foo-stderr.log` 这类**落在仓根**的重定向，
   也 **MUST NOT** 让 `--out` 缺省落到仓根。
-- 仓根文件可能包含素材绝对路径和本机目录结构；`.gitignore` 只能兜底，第一道闸仍是落点纪律。
+- 仓根文件可能包含素材绝对路径和本机目录结构；`.gitignore` 只能兜底，第一道闸仍是落点纪律。
 
 ---
 
-## 工程文件改动纪律（全局 MUST）
+## 工程文件改动纪律（全局 MUST）
 
 - **agent MUST NOT 裸手改 `.gtrk` JSON。** 元素级编辑（挪位置 / 改时长 / 切开 / 改参数）
   一律走 **`gtrk patch`**。
-- `.gtrk` 一个片段的时码是**两套并存**的
+- `.gtrk` 一个片段的时码是**两套并存**的
   （`clip_st`+`clip_ed` 与 `clip_st`+`duration`）。改 `duration` 不同步 `clip_ed`，
   **客户端 importer 优先读 `clip_ed`**，后端可能不强校验它，导致命令成功但实际出点未变。
 - 另外轨道时基端点要落在 `video_rate` 的帧边界上，浮点秒累加会漂。这两件 `gtrk patch`
@@ -68,7 +68,7 @@
 - **例外只有一个**：铺自产物的那几条既有链路（`gtrk matrix` 铺轨、`gtrk mg` 铺颗粒、
   `gtrk audio` / `gtrk subtitle` 建新轨）—— 它们只动自己新建的东西，不改既有 clip 的时码。
 
-## 标定数据落点纪律（全局 MUST）
+## 标定数据落点纪律（全局 MUST）
 
 **新增**的实测标定数据 MUST 写进对应 change 的 `design.md` 附录，MUST NOT 写进代码注释或
 随包分发的 `skills/*/SKILL.md`。
@@ -83,7 +83,7 @@
      丑话属于「怎么用」，是使用者的决策依据；
   ③ **算法本体**——公式与判定式本身就是代码在做的事，注释是它的可读投影。
 - **代码注释的目标口径**：只讲**是什么 + 怎么用**，不讲**为什么是这个值**。
-- **存量不清洗**：既有注释里的标定数据已经随公开镜像与 npm 发布；删除它们收益有限，且容易损失维护上下文。
+- **存量不清洗**：既有注释里的标定数据已经随公开镜像与 npm 发布；删除它们收益有限，且容易损失维护上下文。
   本纪律**只管新增**。已知的存量标定已在 `tighten-distribution-surface/design.md 附录 A`
   留档（含「改值前必须知道什么」速查表）——**改那些常量前先读它**。
 
@@ -224,7 +224,7 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 | 参数 | 作用 | 缺省 |
 |---|---|---|
 | `<taskId>`（位置参数） | 任务 id | 必填 |
-| `-o, --out <dir>` | 产物目录 | **必填**（无缺省；`--out .` = 当前目录本身） |
+| `-o, --out <dir>` | 产物目录 | **必填**（无缺省；`--out .` = 当前目录本身） |
 | `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
 | `--jianying-draft-dir` / `--ffmpeg-path` / `--crf` / `--codec` / `--no-open` / `--json` | 同 `oralcut` | — |
 
@@ -271,23 +271,23 @@ gtrk split <拆分稿.json> --project <目录> --md --json  # ⑤ 校验落地
 - **只动 `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。
 
-> **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
-
-### 2.2 精修工程导出：`gtrk project export --project <目录>`
-
-口播起盘用 `gtrk project init`，精修收尾用 `gtrk project export`；已经在客户端铺过 B-roll、MG 或 BGM 的 `.gtrk`，直接导出 NLE 工程，**不要重跑 `oralcut`**，否则会丢掉精修并重复计费。
-
-```bash
-gtrk project export --project ./my-video --formats jianying,xml
-gtrk project export --gtrk ./my-video/gtrk/project.gtrk --formats xml --no-open
-```
-
-- 颗粒会随 NLE 工程一起导出：命令会预渲 qtrle；首次导出按分钟计费，客户端已经烤过或第二次导出命中 `.tonghe-cache/particles/` 时复用缓存。
-- 本命令有两个计费面：工程结构按次，颗粒按分钟；这和 `project init` 的 0 积分不是一回事。执行前会分别提示实时价格。
-- 只选择 `gtrk` 时会自动跳过颗粒预渲（gtrk 原生保留 `beat_track`），不要再手动加 `--no-particles`；`--no-particles` 只在明确接受 NLE 导出缺少颗粒时使用。
-- `--json` 只在 stdout 输出一行结果 JSON；产物目录恒写 `result.json`，源 `.gtrk` 只读不改。
-
-### 2.3 视频转文字稿：`gtrk transcript <本地视频>`
+> **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
+
+### 2.2 精修工程导出：`gtrk project export --project <目录>`
+
+口播起盘用 `gtrk project init`，精修收尾用 `gtrk project export`；已经在客户端铺过 B-roll、MG 或 BGM 的 `.gtrk`，直接导出 NLE 工程，**不要重跑 `oralcut`**，否则会丢掉精修并重复计费。
+
+```bash
+gtrk project export --project ./my-video --formats jianying,xml
+gtrk project export --gtrk ./my-video/gtrk/project.gtrk --formats xml --no-open
+```
+
+- 颗粒会随 NLE 工程一起导出：命令会预渲 qtrle；首次导出按分钟计费，客户端已经烤过或第二次导出命中 `.tonghe-cache/particles/` 时复用缓存。
+- 本命令有两个计费面：工程结构按次，颗粒按分钟；这和 `project init` 的 0 积分不是一回事。执行前会分别提示实时价格。
+- 只选择 `gtrk` 时会自动跳过颗粒预渲（gtrk 原生保留 `beat_track`），不要再手动加 `--no-particles`；`--no-particles` 只在明确接受 NLE 导出缺少颗粒时使用。
+- `--json` 只在 stdout 输出一行结果 JSON；产物目录恒写 `result.json`，源 `.gtrk` 只读不改。
+
+### 2.3 视频转文字稿：`gtrk transcript <本地视频>`
 
 这一能力由独立的 `gtrk-transcript` Skill 驱动，不属于 `gtrk-tools` 单点工具族。用户说「视频转文字 / 视频转文字稿 / 提取视频文稿 / 把本地视频整理成妙记式文稿」时，直接运行：
 
@@ -398,6 +398,31 @@ gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape el
 
 ---
 
+## 2.6 合成层：`gtrk composite`（粗剪之上的整段包装 · 纯本地零计费）
+
+字幕之后、出片之前：把选定时间窗做成**合成颗粒**——一段时间内的整个画面由一颗代码颗粒接管（逐句换画面、对照并排、并列卡片、字幕排版），讲者与 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 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 <秒>]
+gtrk composite build --project <工程> [--only cp-w03] [--theme <css>] [--materials <json>]
+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]
+```
+
+- **候选写 `struct_meta.composite`**（只动这一个键、原子写回），客户端大纲 CP 行画提案块——与 `gtrk split` 写 `struct_meta.split`、beat 色带呈现同一套做法。要用户看提案块，先请他在客户端**重新载入工程**。
+- **解析规则不自造**：`build` 按 infra `composite-particle-profile` 解析（帧格窗口、`lane_clip_id`、锚点局部帧、字幕输入、`inputs_hash`），对拍 infra 金样逐字节一致；窗口不在帧格上会被吸附并报挪动量。
+- **机检**：`lint` 退出码 0 通过 / 1 有问题 / 3 排版未机检（本机找不到 Chrome / Edge，可设 `GTRK_CHROME`）。**3 不是通过**：照实告诉用户，用静帧人眼查。`lint` 含帧纯度检查（`impure-frame`：同一帧号随渲染顺序画出不同画面），不过的颗粒烘焙段首会画错。
+- **铺轨**：按 `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，回执给原因）时，出片该段按粗剪出画——照实告诉用户。
+
+---
+
 ## 3. 产物结构 + 三端打开
 
 ```
@@ -526,7 +551,7 @@ gtrk feedback "<一句话说清哪里不顺手>" --command <命令名> [--catego
 ## 7. 扩展（给改 CLI 的 agent）
 
 新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
-云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`；单发取结果 `getTaskResult`、`pollTask` 复用之）；上传一律走 `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存；≥256MiB 自动分片断点续传，见 `src/lib/chunk-upload.ts`）。本地预处理（探几何 / 抽音频 / 压 720p）在 `src/lib/media.ts`；本地渲染（gtrk EDL → ffmpeg filter_complex）在 `src/lib/render.ts`；三方产物落地 + `result.json` 两段写在 `src/lib/materialize.ts`（`oralcut` 与 `oralcut-result` 共用）。已上线：`oralcut`（云剪）、`oralcut-result`（按 task_id 取回）、`render`（本地渲染 gtrk）、`split`（视觉拆分派单器：`src/lib/projection.ts` 投影纯函数 + `src/lib/splitdoc.ts` 拆分稿校验/落地 + `src/lib/gtrk-writeback.ts` 原子写回 `struct_meta.split`，随包分发 `skills/gtrk-splitter/`）。`matrix`（B-roll 检索：`src/lib/matrix.ts` 双口路由/派单翻译/plan 构建 + `src/commands/matrix.ts`;`matrix search "<词>"` ad-hoc）。写回 `.gtrk` 的命令（`matrix` 铺轨 / `mg` 铺轨）在写回**之后**跑一次**素材落盘自检**（`src/lib/material-integrity.ts`，纯只读、可注入 `exists` 谓词）：遍历 `materials[].path` 确认文件真在盘上，相对路径**恒以 `.gtrk` 所在目录为基准**（历史坑：按工程根解析会全面误报），结果以 `integrity` 字段出 `--json`、以摘要 + 逐条清单出人读日志。**非致命**——查出悬空不改 `ok` / 退出码，也**不删任何素材条目或文件**（预防面在 opencut 客户端侧，本仓只做检测）。规划中：`struct`（已有 gtrk → 三方工程）。
+云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`；单发取结果 `getTaskResult`、`pollTask` 复用之）；上传一律走 `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存；≥256MiB 自动分片断点续传，见 `src/lib/chunk-upload.ts`）。本地预处理（探几何 / 抽音频 / 压 720p）在 `src/lib/media.ts`；本地渲染（gtrk EDL → ffmpeg filter_complex）在 `src/lib/render.ts`；三方产物落地 + `result.json` 两段写在 `src/lib/materialize.ts`（`oralcut` 与 `oralcut-result` 共用）。已上线：`oralcut`（云剪）、`oralcut-result`（按 task_id 取回）、`render`（本地渲染 gtrk）、`split`（视觉拆分派单器：`src/lib/projection.ts` 投影纯函数 + `src/lib/splitdoc.ts` 拆分稿校验/落地 + `src/lib/gtrk-writeback.ts` 原子写回 `struct_meta.split`，随包分发 `skills/gtrk-splitter/`）。`matrix`（B-roll 检索：`src/lib/matrix.ts` 双口路由/派单翻译/plan 构建 + `src/commands/matrix.ts`;`matrix search "<词>"` ad-hoc）。写回 `.gtrk` 的命令（`matrix` 铺轨 / `mg` 铺轨）在写回**之后**跑一次**素材落盘自检**（`src/lib/material-integrity.ts`，纯只读、可注入 `exists` 谓词）：遍历 `materials[].path` 确认文件真在盘上，相对路径**恒以 `.gtrk` 所在目录为基准**（历史坑：按工程根解析会全面误报），结果以 `integrity` 字段出 `--json`、以摘要 + 逐条清单出人读日志。**非致命**——查出悬空不改 `ok` / 退出码，也**不删任何素材条目或文件**（预防面在 opencut 客户端侧，本仓只做检测）。精修工程导出已由 `gtrk project export` 承接（已有 gtrk → 多格式工程），不另设 `struct` 命令。
 
 ### 工具族：接单点云能力 = 加一个 descriptor（不写编排）
 

package/CHANGELOG.md

@@ -11,6 +11,36 @@
 
 ## 未发布
 
+## 1.3.5（2026-10-17）
+
+- 新增合成层命令族 `gtrk composite`：`plan` / `review` / `scaffold` / `shots` 把候选窗口写进 `struct_meta.composite`（客户端大纲 CP 行），支持整片铺满 / AI 判定 / 指定区间三种入口；`build` 把场景构建成自包含合成颗粒（随包工具箱 `composite-kit@1`）；`lint` 做静态校验加本机 Chrome / Edge 逐帧排版机检（穿模 / 线条穿画面 / 越界）；`lay` 按自产身份幂等铺进 beat 轨最上层。新增 `/gtrk-composite` skill，口播图纸挂可选合成步。
+- `gtrk composite bake`：用钉定版本的 chrome-headless-shell（`gtrk deps install --browser`）逐帧确定性出帧，按段并发、带缓存；`render` / `project export` 接管已烘焙的合成颗粒，`lint` 增帧纯度检查；支持 `--progress jsonl`，关闭 stdin 即取消（退出码 130），取消或出错时连同浏览器遗留子进程一起收掉。
+- 片段背景填充：`gtrk matrix` 的候选片段自带纯黑 `background_fill`，不再另铺黑底垫轨（`--black-bed` 回到旧形态）；`ai-drama lay` 的 AI 片段同样带黑底；`gtrk project background` 缺省改为逐片段写底板；本地 `gtrk render` 承接片段底板；`project export` 承接云端物化，先写出纯色图再落工程（剪映 / Pr 的上层轨模糊为真模糊，FCPXML / OTIO 降级为纯黑，铺满画布的片段不垫底）。**需配合客户端 1.2.12 起**，旧客户端不认片段底板。
+- `gtrk render` / `project export` 遇到工程里有客户端专属视觉状态（文字 / 贴纸 / 图形 / 特效、画布背景）时用人话提示一次，`--json` 恒带 `clientOnly`；`project export` 的 `clientVisualElementCount` 改按元素计数（原误按车道数）。
+- 外网 B-roll 缺省加入 Pexels 第五平台：解析可选署名字段（`uploader_url` / `license`），平台 `disabled` 不算降级；旧服务端不认 pexels 时提示加 `--platforms` 继续；未指定平台时先回看四平台旧续跑记录，不重复扣费；`source_urls` 接受 Pexels 视频页。**服务端开关打开前 Pexels 只报 `disabled`、不出候选。**
+- `matrix material --scope clip|image` 缺省附带 Pexels 补充结果：单列在 `--json` 顶层 `pexels_results`（另有 `pexels_status`、`counts.pexels`），不进 `results`、不算候选数，人读输出另起一段并在段首署名 Pexels；`--no-stock` 关闭，`audio` 不带。补充素材直接用 `download_url` 下载，`matrix fetch` 见 `pexels:` id 会整批拒绝。**需服务端 `add-pexels-stock-material-search` 上线并打开开关后才会出现补充结果**，老服务端下只提示一次、不报错。
+- `tool video_highlight` 分析代理升至 448p/4fps（libx264 CRF 28；本地代理缓存按编码参数区分，参数变更后自动重新生成），缺省附单声道低码率原声，新增 `--no-audio`；上传前本地自检，旧版 224 代理不再复用。**需云端先升级，旧云端会以「短边必须224」拒绝新代理。**
+- MAD 缓存目录不可写时给出权限提示与诊断类别。
+- 交工文案补 Premiere 自动重链提醒：正本在 `gtrk-oralcut`「回给用户」的 PR / FCP 条，`long2short` / `live-slicing` / `tools` 引用同一条。
+
+## 1.3.4（2026-10-14）
+
+> 版本段补录于 2026-10-17：发版时这几条留在「未发布」里。归属按 npm 记录的 `gitHead`（1.3.4 `144ed89`）与写入这些条目的提交时间判定，未逐条核对包体。
+
+- `long2short --camera-move`：云端按与精剪同一套调度把推 / 拉镜头写成主轨片段的 `clip_keyframes.scale_x / scale_y`，客户端与剪映可见可改；`clips.md` 标「运镜 N 处」，未能加运镜的切片单列；`/gtrk-live-slicing` 开工问询变五问（⑤ 运镜，缺省不加）。需配合服务端 `add-long2short-for-cli-camera-move` 与客户端承接 `clip_keyframes` 的版本。
+- `gtrk patch` 的 trim / split / seal / snap 同步维护 `clip_keyframes`（入点平移、越界截断补插值端点、切分两段各自合法），写前校验拒绝任何非法关键帧并点名 clip 与通道；`audio tighten` 遇带音量关键帧的音频片段拒绝；本地 `gtrk render` 读到关键帧时提示按静态画面出片。
+- `gtrk project background --blur [--intensity n] | --color #RRGGBB | --clear`：写客户端画布背景 `struct_meta.client_background`（零计费、不访问云端），横屏源进竖屏画布时用模糊底替代黑边；`/gtrk-live-slicing` 对横竖互转的入选切片缺省加模糊底。剪映 / PR 与本地 `gtrk render` 不带该设置。
+- `long2short --speed-factor 0.5–2.0`：整体调速（保音高）写进逐 clip 工程，客户端 / 剪映 / PR 都按倍率播放，云端不渲染、不加价；`clips.md` 标注倍率，未能变速的 clip 单列。需配合服务端 `add-long2short-for-cli-speed` 上线。
+- `long2short` 产物根新增整片转写 `json/transcript.json`，可用 `gtrk subtitle lay --gtrk … --transcript …` 给任一 clip 上客户端字幕轨；字幕文件来源时 `clips.md` 提示词级时间为近似值。需配合服务端 `add-long2short-for-cli-transcript` 上线，老服务端下不报错。
+- `subtitle lay --language <code>`：指定云端拆行语种（缺省仍为 zh-CN），非中文源上字幕不再按中文断句。
+- `/gtrk-live-slicing` 选题确认后对入选切片缺省字幕上轨；调速只在用户主动要求时加。
+
+## 1.3.3（2026-10-08）
+
+> 版本段补录于 2026-10-17。npm 记录的 `gitHead` 为 `13d43e9`，但同步版本号的提交 `2f5c68d` 晚于发布约 4 分钟，推断与 1.2.7 一样是从带未提交改动的工作区发的；以下按该提交说明补记，未核包体。
+
+- 完善 Vlog 分段组装、旁白归轨和颗粒检查。
+
 ## 1.3.2（2026-10-08）
 
 - 本地视觉理解增加当前 Agent 审阅交接：`matrix describe --prepare/--review`，已完成的本地判断不调用豆包，明确无法完成的条目按需补齐。

package/README.en.md

@@ -10,9 +10,9 @@
 <p>
 <a href="#demo">Demo</a> ·
 <a href="#quick-start">Quick start</a> ·
-<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">Tutorials</a> ·
-<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
-<a href="docs/development.en.md">Develop</a> ·
+<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">Tutorials</a> ·
+<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
+<a href="docs/development.en.md">Develop</a> ·
 <a href="README.md">简体中文</a>
 </p>
 
@@ -157,37 +157,37 @@ flowchart LR
 
 **Conversations currently happen in your own agent; the desktop client has no built-in AI chat.** Review and refine the project in the client after your agent changes it, or render with `gtrk render`. Motion graphics that require cloud rendering are billed separately; cached renders can be reused.
 
-The three-format rough-cut output and the export of a fully packaged project have different support boundaries. The [workflow guide](docs/workflow.en.md) explains where each deliverable opens and which effects need rendering.
-
-After refining a `.gtrk` project in the client, use `gtrk project export --project <dir>` to produce Jianying, Premiere XML, FCPXML or OTIO while preserving the refined timeline; do not rerun `oralcut`, which rebuilds the rough cut. Export renders MG particles into the NLE package: structural export is billed per task, and particles missing from the shared cache are billed by the minute. `project init` remains zero-credit. When only `gtrk` is requested, the native `beat_track` is kept and particle rendering is skipped.
-
-## gtrk + AI Drama Desk: from storyboard to editable clips
-
-For AI-generated story scenes, connect [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) to the same project workflow. The responsibilities stay separate:
-
-| Component | What it does | Output |
-| --- | --- | --- |
-| `gtrk CLI` | Understands the request in your agent, orchestrates workflows and manages `.gtrk` projects | An editable video project |
-| `AI Drama Desk` | Imports storyboards, manages characters and styles, generates keyframes / I2V clips and exports a handoff package | A `return-v1` clip package + `manifest` |
-| `gtrk ai-drama lay` | Places exported clips back into the project by beat windows | A dedicated AI video track |
-
-The typical path looks like this:
-
-```text
-storyboard.md → AI Drama Desk → references / keyframes / I2V → return-v1 package
-                                                                  ↓
-                                      gtrk ai-drama lay → .gtrk project → client refinement
-```
-
-The desk supports mock, cloud and optional local ComfyUI engines. Start with a zero-GPU, zero-key rehearsal, then enable a real engine when needed. For an existing desk project, the CLI only needs the **API base and project ID**; it does not scan the repository:
-
-```bash
-gtrk ai-drama lay --project ./my-video --desk-project <project-id>
-```
-
-→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI drama tutorial](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [command reference](docs/reference.en.md#command-reference)
-
-## Use just one tool, too
+The three-format rough-cut output and the export of a fully packaged project have different support boundaries. The [workflow guide](docs/workflow.en.md) explains where each deliverable opens and which effects need rendering.
+
+After refining a `.gtrk` project in the client, use `gtrk project export --project <dir>` to produce Jianying, Premiere XML, FCPXML or OTIO while preserving the refined timeline; do not rerun `oralcut`, which rebuilds the rough cut. Export renders MG particles into the NLE package: structural export is billed per task, and particles missing from the shared cache are billed by the minute. `project init` remains zero-credit. When only `gtrk` is requested, the native `beat_track` is kept and particle rendering is skipped.
+
+## gtrk + AI Drama Desk: from storyboard to editable clips
+
+For AI-generated story scenes, connect [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) to the same project workflow. The responsibilities stay separate:
+
+| Component | What it does | Output |
+| --- | --- | --- |
+| `gtrk CLI` | Understands the request in your agent, orchestrates workflows and manages `.gtrk` projects | An editable video project |
+| `AI Drama Desk` | Imports storyboards, manages characters and styles, generates keyframes / I2V clips and exports a handoff package | A `return-v1` clip package + `manifest` |
+| `gtrk ai-drama lay` | Places exported clips back into the project by beat windows | A dedicated AI video track |
+
+The typical path looks like this:
+
+```text
+storyboard.md → AI Drama Desk → references / keyframes / I2V → return-v1 package
+                                                                  ↓
+                                      gtrk ai-drama lay → .gtrk project → client refinement
+```
+
+The desk supports mock, cloud and optional local ComfyUI engines. Start with a zero-GPU, zero-key rehearsal, then enable a real engine when needed. For an existing desk project, the CLI only needs the **API base and project ID**; it does not scan the repository:
+
+```bash
+gtrk ai-drama lay --project ./my-video --desk-project <project-id>
+```
+
+→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI drama tutorial](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [command reference](docs/reference.en.md#command-reference)
+
+## Use just one tool, too
 
 | What you need | Start here |
 | --- | --- |
@@ -197,7 +197,7 @@ gtrk ai-drama lay --project ./my-video --desk-project <project-id>
 | A visual style for your show | [Style-maker Skill](skills/gtrk-style-maker/SKILL.md) |
 | Third-party animation, typography or creative Skills | [Skill map](https://hocassian.feishu.cn/wiki/SxRtwJ0G7inTbQkwckFcZmClnrd) |
 
-## FAQ
+## FAQ
 
 **Do I need to code?**
 
@@ -215,21 +215,21 @@ Talking-head and long-to-short project workflows keep the original locally and u
 
 The CLI runs across platforms. The Windows client provides visual preview and refinement; the CLI can render existing projects. Jianying and Premiere support depends on the installed software and the project format.
 
-**Skills are missing, or a task failed. What now?**
-
-Open a new agent session and run `gtrk doctor`. Use `gtrk skills install` to refresh Skills. If a task already has an ID, recover its results before submitting it again. See [workflow and troubleshooting](docs/workflow.en.md).
-
-## Star History
-
-<a href="https://star-history.com/#Gitruck/cli&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-  </picture>
-</a>
-
-## Documentation and contributions
+**Skills are missing, or a task failed. What now?**
+
+Open a new agent session and run `gtrk doctor`. Use `gtrk skills install` to refresh Skills. If a task already has an ID, recover its results before submitting it again. See [workflow and troubleshooting](docs/workflow.en.md).
+
+## Star History
+
+<a href="https://star-history.com/#Gitruck/cli&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+  </picture>
+</a>
+
+## Documentation and contributions
 
 [Full tutorials](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [Workflow](docs/workflow.en.md) · [Command reference](docs/reference.en.md) · [Development](docs/development.en.md) · [Changelog](CHANGELOG.md)
 

package/README.md

@@ -10,9 +10,9 @@
 <p>
 <a href="#demo">观看演示</a> ·
 <a href="#quick-start">快速开始</a> ·
-<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">使用教程</a> ·
-<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
-<a href="docs/development.md">开发文档</a> ·
+<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">使用教程</a> ·
+<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
+<a href="docs/development.md">开发文档</a> ·
 <a href="README.en.md">English</a>
 </p>
 
@@ -157,37 +157,37 @@ flowchart LR
 
 **当前对话入口在你自己的 Agent 中，客户端没有内置 AI 对话框。** Agent 修改工程后，在客户端查看效果、继续精修；也可以用 `gtrk render` 渲染成片。需要云端渲染的动态图会单独计费，缓存可复用。
 
-粗剪阶段的三端工程，与完整包装后的导出支持范围不同；[工作流指南](docs/workflow.md)说明每种交付物在哪打开、哪些效果需要渲染。
-
-客户端精修 `.gtrk` 后，用 `gtrk project export --project <目录>` 导出剪映、Premiere XML、FCPXML 或 OTIO，保留精修时间线；不要重跑 `oralcut`，否则会重新生成粗剪。导出会把 MG 颗粒预渲进 NLE 工程，结构导出按次计费，未命中共享缓存的颗粒按分钟计费；`project init` 仍是 0 积分。只选 `gtrk` 时会保留原生 `beat_track` 并自动跳过颗粒预渲。
-
-## gtrk + AI Drama Desk：从分镜到可回轨片段
-
-如果你的素材不是实拍，而是希望把一份分镜稿变成 AI 情景片段，可以把 [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) 接到同一条工程链里。两者分工很清楚：
-
-| 组件 | 负责什么 | 产物 |
-| --- | --- | --- |
-| `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
-| `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `manifest` |
-| `gtrk ai-drama lay` | 把工作台导出的片段按 beat 区间铺回工程 | 独立 AI 视频轨 |
-
-典型路径是：
-
-```text
-分镜稿 md → AI Drama Desk → 角色参考图 / keyframe / I2V → return-v1 导出包
-                                                          ↓
-                                      gtrk ai-drama lay → .gtrk 工程 → 客户端精修
-```
-
-工作台支持 mock、云端出口和可选的本地 ComfyUI；你可以先零 GPU、零 Key 跑通流程，再按需要启用真实引擎。已有工作台项目时，CLI 只需要 **API 地址 + 项目 ID**，不需要扫描仓库目录：
-
-```bash
-gtrk ai-drama lay --project ./my-video --desk-project <project-id>
-```
-
-→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI 漫剧教程](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [命令参考](docs/reference.md#命令参考)
-
-## 成片之外，也能只做一件事
+粗剪阶段的三端工程，与完整包装后的导出支持范围不同；[工作流指南](docs/workflow.md)说明每种交付物在哪打开、哪些效果需要渲染。
+
+客户端精修 `.gtrk` 后，用 `gtrk project export --project <目录>` 导出剪映、Premiere XML、FCPXML 或 OTIO，保留精修时间线；不要重跑 `oralcut`，否则会重新生成粗剪。导出会把 MG 颗粒预渲进 NLE 工程，结构导出按次计费，未命中共享缓存的颗粒按分钟计费；`project init` 仍是 0 积分。只选 `gtrk` 时会保留原生 `beat_track` 并自动跳过颗粒预渲。
+
+## gtrk + AI Drama Desk：从分镜到可回轨片段
+
+如果你的素材不是实拍，而是希望把一份分镜稿变成 AI 情景片段，可以把 [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) 接到同一条工程链里。两者分工很清楚：
+
+| 组件 | 负责什么 | 产物 |
+| --- | --- | --- |
+| `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
+| `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `manifest` |
+| `gtrk ai-drama lay` | 把工作台导出的片段按 beat 区间铺回工程 | 独立 AI 视频轨 |
+
+典型路径是：
+
+```text
+分镜稿 md → AI Drama Desk → 角色参考图 / keyframe / I2V → return-v1 导出包
+                                                          ↓
+                                      gtrk ai-drama lay → .gtrk 工程 → 客户端精修
+```
+
+工作台支持 mock、云端出口和可选的本地 ComfyUI；你可以先零 GPU、零 Key 跑通流程，再按需要启用真实引擎。已有工作台项目时，CLI 只需要 **API 地址 + 项目 ID**，不需要扫描仓库目录：
+
+```bash
+gtrk ai-drama lay --project ./my-video --desk-project <project-id>
+```
+
+→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI 漫剧教程](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [命令参考](docs/reference.md#命令参考)
+
+## 成片之外，也能只做一件事
 
 | 想做什么 | 从这里开始 |
 | --- | --- |
@@ -197,7 +197,7 @@ gtrk ai-drama lay --project ./my-video --desk-project <project-id>
 | 给自己的栏目建立视觉风格 | [风格体系 Skill](skills/gtrk-style-maker/SKILL.md) |
 | 接入第三方动画、排版或创作 Skills | [Skill 地图](https://hocassian.feishu.cn/wiki/SxRtwJ0G7inTbQkwckFcZmClnrd) |
 
-## 常见问题
+## 常见问题
 
 **需要会写代码吗？**
 
@@ -215,21 +215,21 @@ CLI 代码采用 MIT 许可证；同合云能力按对应规则计费，你使
 
 CLI 可以跨平台执行。Windows 客户端用于可视化预览与精修；已有工程也可通过 CLI 渲染。剪映、Premiere 的使用取决于对应软件和工程格式的支持情况。
 
-**安装后找不到 Skills，或任务出错怎么办？**
-
-重新打开 Agent 会话，运行 `gtrk doctor` 检查环境；补装用 `gtrk skills install`。任务已有 ID 时优先恢复结果，避免重新提交云端任务。详见[工作流与排障](docs/workflow.md)。
-
-## Star History
-
-<a href="https://star-history.com/#Gitruck/cli&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
-  </picture>
-</a>
-
-## 文档与参与
+**安装后找不到 Skills，或任务出错怎么办？**
+
+重新打开 Agent 会话，运行 `gtrk doctor` 检查环境；补装用 `gtrk skills install`。任务已有 ID 时优先恢复结果，避免重新提交云端任务。详见[工作流与排障](docs/workflow.md)。
+
+## Star History
+
+<a href="https://star-history.com/#Gitruck/cli&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+    <img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
+  </picture>
+</a>
+
+## 文档与参与
 
 [完整教程](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [工作流](docs/workflow.md) · [命令参考](docs/reference.md) · [开发文档](docs/development.md) · [更新日志](CHANGELOG.md)
 

package/assets/composite-kit/kit.css

@@ -0,0 +1,57 @@
+/* 合成颗粒工具箱 composite-kit@1 的公共样式（构建时内联）。
+ * 中性：配色、字体、纹理一律走变量，由栏目 / 工程风格（composite/theme.css，构建时接在本文件之后）覆盖。
+ * 变量：--bg 底色 / --bg2 次底色 / --ink 正文 / --muted 次要文字 / --line 分隔线 /
+ *       --accent 强调 / --accent2 / --accent3 辅助色 / --alert 警示 / --font 正文字体 / --font-serif 标题字体。 */
+html, body { margin: 0; height: 100%; overflow: hidden; background: transparent; }
+#stage {
+  position: absolute; left: 0; top: 0; width: 1920px; height: 1080px; transform-origin: 0 0; overflow: hidden;
+  --bg: #F4F4F2; --bg2: #E6E6E2; --ink: #1D1D1F; --muted: #6B6B70; --line: #CFCFCB;
+  --accent: #2F6FDE; --accent2: #2E8B57; --accent3: #4A5568; --alert: #D14343;
+  --font: "Noto Sans SC", "Source Han Sans CN", "Microsoft YaHei", "PingFang SC", sans-serif;
+  --font-serif: "Noto Serif SC", "Source Han Serif SC", "Source Han Serif", "SimSun", serif;
+  font-family: var(--font); color: var(--ink);
+}
+#stage > *, #stage .abs { position: absolute; box-sizing: border-box; }
+[data-slot] { visibility: hidden !important; }
+.serif { font-family: var(--font-serif); }
+.bed { left: 0; top: 0; width: 1920px; height: 1080px; background: var(--bg); }
+.bed.dark { background: radial-gradient(ellipse at 30% 35%, #2A2A2E 0%, #141416 70%); }
+/* 槽位装饰：阴影在下（back），描边在上（front）。描边只给最上层的画面——下层画面的 front 描边会压到上层画面上 */
+.shadow { border-radius: 18px; box-shadow: 0 18px 50px rgba(0, 0, 0, .22), 0 3px 10px rgba(0, 0, 0, .12); background: #000; }
+.shadow.round { border-radius: 50%; }
+.frame { border: 3px solid var(--ink); border-radius: 18px; }
+.frame.round { border-radius: 50%; }
+.frame.thin { border-width: 2px; }
+.frame.light { border-color: rgba(255, 255, 255, .85); }
+.ring { border: 4px solid var(--ink); border-radius: 50%; }
+.ring.light { border-color: rgba(255, 255, 255, .9); }
+/* 字幕：颗粒接管字幕后自己排 */
+.cap {
+  left: 160px; width: 1600px; top: 958px; height: 70px; text-align: center; white-space: nowrap;
+  font-size: 44px; font-weight: 600; letter-spacing: .02em; color: var(--ink); line-height: 70px;
+}
+.cap b { color: var(--accent); font-weight: 800; }
+.cap.dark { color: #fff; text-shadow: 0 2px 12px rgba(0, 0, 0, .55); }
+.cap.dark b { color: var(--accent); }
+/* 文字 */
+.tag { font-size: 26px; letter-spacing: .2em; color: var(--muted); white-space: nowrap; }
+.kicker { font-size: 28px; font-weight: 700; letter-spacing: .28em; color: var(--accent); white-space: nowrap; }
+.h1 { font-size: 96px; font-weight: 900; line-height: 1.12; white-space: nowrap; }
+.h2 { font-size: 64px; font-weight: 900; line-height: 1.2; white-space: nowrap; }
+.h3 { font-size: 44px; font-weight: 700; line-height: 1.3; white-space: nowrap; }
+.body { font-size: 34px; line-height: 1.5; color: var(--ink); }
+.num { font-size: 30px; font-weight: 800; color: var(--accent); letter-spacing: .1em; }
+.pill { height: 54px; padding: 0 26px; border-radius: 27px; font-size: 28px; font-weight: 700; line-height: 54px; white-space: nowrap; }
+.rule { height: 3px; background: var(--ink); }
+.card { background: #FFFFFF; border-radius: 22px; box-shadow: 0 10px 30px rgba(0, 0, 0, .08); }
+.stamp { font-size: 72px; font-weight: 900; color: var(--alert); border: 6px solid var(--alert); border-radius: 14px; padding: 6px 26px; white-space: nowrap; }
+/* 对话气泡（字幕变成一串对话时用） */
+.bubble {
+  height: 76px; padding: 0 30px; border-radius: 38px 38px 10px 38px; background: #FFFFFF; font-size: 32px; line-height: 76px;
+  white-space: nowrap; color: var(--ink); box-shadow: 0 6px 18px rgba(0, 0, 0, .08); border: 2px solid transparent;
+}
+.bubble b { color: var(--accent); font-weight: 700; }
+.bubble.now { border-color: var(--accent); }
+/* 画面标签：贴在画面左上角，说明这张画面对应台词里的哪个词 */
+.ptag { height: 46px; padding: 0 20px; border-radius: 23px; background: rgba(20, 20, 22, .74); color: #fff; font-size: 26px; font-weight: 700; line-height: 46px; letter-spacing: .06em; white-space: nowrap; }
+.ptag.warm { background: var(--accent); }