@gitruck/cli 1.1.10 → 1.2.0

package/AGENT.md

@@ -116,6 +116,8 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 > ⚠️ **`render` 自 1.1.10 起分两种情形**：工程无 MG 颗粒（或带 `--no-particles`）时仍是纯本地、不出现这条；
 > 有未命中缓存的颗粒时，**颗粒 HTML 文本会上行**去云端烤（素材本体仍不上行），此时会打这条告知，
 > 且在它之前先出计费预估确认。
+> 另：`render` 会按叠加 clip 的 `clip_transform` / `border_radius` / `clip_mask` 本地合成画中画几何与形状蒙版
+> （纯本地、零计费，蒙版纹理缓存在工程旁 `.tonghe-cache/masks/`），`--json` 的 `overlay.transformed / masked / maskSkipped` 如实计数。
 
 5. **按需装运行时资产**（只有用到本地渲染/烧录才需要）：
 
@@ -345,6 +347,25 @@ gtrk patch set   --project <dir> --total max               # 改顶层总长（
 
 ---
 
+## 2.5 双源画中画：`gtrk pip lay`（屏录 / 第二机位 · 纯本地零计费）
+
+讲软件 / 讲代码的口播多是**两条文件同步录**（屏幕一条、人像一条）。`oralcut` 只剪人像；本命令把粗剪的**每个切点镜像到屏录**，
+铺「屏录满幅轨（N+1，静音）+ 人像画中画副本轨（N+2，静音、带 `clip_transform` / `border_radius` / `clip_mask`）」，主轨与音轨**逐字节不动**。
+
+```bash
+gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape ellipse|rectangle|heart|diamond|star|none] [--feather 10] [--border-radius 24] [--anchor bottom-right] [--scale 0.28] [--margin 40] [--offset <秒>] [--dry-run] [--json]
+```
+
+- **三分支偏移**：缺省互相关自动对齐（人像为参考、屏录为待对齐，阈值沿 `audio align`）；置信度不足 → 产 `<屏录名>_pip_align.gtrk` 让用户在客户端把「伴随源」轨拖齐后 `--resume <该工程>`；`--offset <秒>` 跳过检测。
+  偏移口径全库统一：正 = 屏录晚开录（`clip_st' = clip_st − offset`）。**屏录 MUST 带麦克风音轨**才能自动对齐，无音轨只剩后两条路——开工时就要提醒用户。
+- **钳位与留空**：屏录比人像短 / 晚开录 ⇒ 对应 beat 留空或只铺可用部分，回执逐颗点名毫秒数；MUST NOT 拉伸或变速。成片该段只见人像主轨，如实告诉用户。
+- **幂等 + 不覆盖用户改动**：改参数直接重跑，自产 clip（`producer=gtrk:pip@1`）剥旧重铺；用户在客户端动过的画中画 clip 失去身份 ⇒ 保留并在回执 `strip.keptForeign` 点名。
+- **位置**：`oralcut` → 检查点① → `pip lay` → `subtitle lay` / `audio lay` → 出片。**不新增必停点**，铺完让用户在客户端看一眼即可。
+- 出片：客户端本地导出 / `gtrk render`（本地合成几何与蒙版）/ 导剪映（菱形无对应会跳过并明示）。
+- 拒写口径同 `gtrk patch`（内容 revision 冲突回 `conflict`、写方自检违例硬拒零写）。
+
+---
+
 ## 3. 产物结构 + 三端打开
 
 ```

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # 更新日志
 
+## 1.2.0（2026-09-11）
+
+### `gtrk pip lay`：屏幕一条 + 人像一条同步录的口播，一句话合成画中画（add-pip-companion-lay）
+
+讲软件 / 讲课件 / 讲代码的口播多是**两条文件同步录**：屏录一条、人像一条。此前流水线只能剪其中一条——
+`gtrk oralcut` 粗剪的每个切点没法落到另一条上，画中画只能去客户端手工摆，圆角与蒙版只有客户端看得见。
+镜像切点是纯算术（每颗 clip 一个偏移），却是「每片必做、手工必错」的事，现在做成命令：
+
+```bash
+gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape ellipse|rectangle|heart|diamond|star|none] [--feather 10] [--corner-radius 0.25] [--border-radius <px>] [--anchor bottom-right] [--scale 0.28] [--margin 40] [--offset <秒>] [--dry-run] [--expected-revision <sha256>] [--json]
+gtrk pip lay --resume <屏录名>_pip_align.gtrk
+```
+
+**测偏移三分支，与 `gtrk audio align` 同一套原语**：缺省互相关自动对齐（人像为参考、屏录为待对齐）；
+置信度不足 ⇒ 产 `<屏录名>_pip_align.gtrk`（人像整段 + 屏录整段按估测偏移摆好），用户在客户端把「伴随源」轨拖齐保存后 `--resume` 读回偏移再铺；
+`--offset <秒>` 显式给值跳过检测。偏移口径全库统一：**正 = 屏录晚开录**。
+⚠️ 屏录 **MUST 带麦克风音轨**才能自动对齐（互相关没有参照就没法算），只有系统音的屏录只剩后两条路——开工时就要提醒用户；
+本命令与 `audio align` 一样只做**恒定偏移**，两台设备采样钟差导致的长片渐飘不矫正。
+
+**镜像切点**：主轨每颗非空档 clip 的 `track_st / duration` 原样落到屏录轨，`clip_st′ = clip_st − offset`，整毫秒域、不累加游标；
+越过屏录素材上界 / 下界的部分**钳位 + 留空 + 回执逐颗点名毫秒数**，MUST NOT 拉伸或变速——
+屏录比人像短 / 晚开录的那几段成片只见人像主轨，如实告诉用户。
+
+**铺两条轨，主轨与音轨一字不动**：屏录满幅轨（`track_index` = 现存视频轨最大值 + 1，静音）+ 人像画中画副本轨（再 + 1，静音，
+带 `clip_transform` / `border_radius` / `clip_mask`）。人声仍由主轨镜像音轨承担，副本轨 MUST NOT 双声；
+主轨不动 ⇒ 下游 `split` / `subtitle lay` / `mg` 照旧按 main 对 transcript，零感知。
+形状缺省 `ellipse` = 以画中画短边内切的正圆；`rectangle` 满幅可带 `--corner-radius`；`heart` / `diamond` / `star` 短边内切；`none` 只摆位不遮。
+`--scale` 的语义是**画中画显示高度占画布高度的比例**（缺省 0.28），写进 `clip_transform` 时按 contain-fit 反算。
+
+**幂等 + 不覆盖用户改动**：改参数直接重跑，自产 clip（`producer = gtrk:pip@1`）先剥后铺、空轨删除；
+用户在客户端动过、被清掉身份的画中画 clip **保留并在回执 `strip.keptForeign` 点名**（与 `matrix lay` 同一条认领纪律）。
+写方自检（恒等式 / 接缝 / 素材上界）破了即抛零副作用；原子写回 + revision 断言，`--expected-revision` 跨命令拒写口径同 `gtrk patch`；`--dry-run` 只算不写。
+回执打印的是**数字**（每颗的偏移 / 钳位 / 留空毫秒），不是一句「已验证」。
+
+链路位置：`oralcut` 检查点① → **`pip lay`** → 拆分 / 字幕 → 出片，**不新增必停点**，铺完让用户在客户端看一眼即可；
+口播图纸（`gtrk-talking-head`）开工五问加第 ⑥ 问（有没有同步录的屏录或第二机位、画中画形状 / 位置 / 大小），屏录题材默认不铺 B-roll。
+出片三口：客户端本地导出 / `gtrk render`（见下一节）/ 导剪映（`diamond` 剪映无对应，跳过并明示）。
+纯本地**零计费**，素材不上行。一条伴随源起步，多机位切人另立。
+⚠️ 客户端预览里看到画中画的圆角与形状蒙版，要等客户端同步更新（消费这两个契约字段的那一半随客户端发版）。
+
+### `gtrk render`：画中画的缩放 / 落位 / 旋转 / 透明、圆角与五形状蒙版随工程本地合成（link-clip-mask-contract-render）
+
+1.1.10 把叠加层渲进了成片，但每一层的**几何**还没读：叠加输入一律 contain-fit 后贴满画布，
+客户端里摆好的画中画渲出来是**满幅信箱**，圆角与蒙版更是零支持。现在按契约逐 clip 消费：
+
+- **`clip_transform`**：`scale_x/y` 在 contain-fit 之后再乘（与客户端「先 contain 再乘 scale」同口径，负值 = 翻转）；
+  `position_x/y` 以画布中心为原点落位；`rotation` 旋转（落点按旋转后包围盒算）；`alpha` 透明。
+- **`border_radius`**（画布像素）与 **`clip_mask`** 五形状（`rectangle` + `corner_radius` / `ellipse` / `heart` / `diamond` / `star`，与契约枚举一字不差）：
+  支持 `invert` 反相、蒙版自身 `rotation`、`feather` 羽化（0..100 = 占蒙版短边百分比）；两者同时在场**叠乘**（元素圆角 ∩ 形状窗），不降级。
+- 颗粒（`beat_track`）不动：契约不给颗粒这两个字段，颗粒尺寸由 HTML 自带。
+
+**不引图形库**：五形状 + 圆角 + 反相 + 旋转都是闭合路径填充，用纯 JS 扫描线光栅成一张 8-bit 灰度 PNG（node 内置 `zlib` 编码，**零新依赖**——
+多一个原生依赖就多一条安装故障面），ffmpeg 只负责 `gblur`（羽化）+ `alphamerge` + `overlay`。确定性、离线、**零计费**。
+蒙版纹理按参数 + 尺寸内容寻址落 `<工程目录>/.tonghe-cache/masks/<sha256>.png`，可复用、丢了重生；
+缓存目录不可写退系统临时目录，两处都写不了才放弃该纹理——此时该 clip **只按几何叠加并明示**（`maskSkipped`），MUST NOT 阻断渲染。
+
+**零回归门**：`clip_transform` 缺席或恒等、且无圆角 / 蒙版的 clip，滤镜链与 1.1.10 **逐字节相同**，既有黄金向量原样通过。
+`--json` 的 `overlay` 段新增 `transformed` / `masked` / `maskSkipped` 三个计数，完成话术逐类点名
+「几段按 clip_transform 落位 / 几段合成了蒙版或圆角 / 几段纹理不可用只按几何叠加」。
+两条口径：羽化是高斯近似，与客户端的距离场羽化**观感等价、不逐像素等价**；
+客户端专有蒙版形态（钢笔 / 文字 / 分屏 / 黑边 / 描边 / 多蒙版）只在客户端状态里，本地渲染不读。
+
+### `gtrk oralcut --lang`：按识别源语种分档校验，切点线不支持的码在抽取前就拒（link-enum-catalog-cli §7）
+
+1.1.10 的枚举清单把 `--lang` 改成按快照校验，但拿的是 `subtitle.languages`——那是翻译目标语与识别源语种的 **11 项共同范围**，
+会放行 `es-ES` / `pt-PT` / `ru-RU` / `vi-VN`，让用户抽完音频、传完文件，才被服务端 6015 拒。
+现在 `/catalog` 下发 `subtitle.source_languages`，**按 task_type 分档**（切点三线 7 项：`en-US` / `fr-FR` / `ja-JP` / `ko-KR` / `zh-CHS` / `zh-CHT` / `zh-CN`；
+`video_ai_subtitle` / `subtitle_translate` 11 项），`oralcut --lang` 改按 `video_oral_cut` 那一档在**抽取之前**校验，报错只列本线 7 项。
+退回规则不破 1.1.10 的两条既定口径：分档整体缺失（老服务端 / 旧快照）/ 缺该线 / 形态不合 ⇒ 退回 11 项共同范围；
+共同范围也拿不到或无快照 ⇒ 放行交服务端裁决——**fail-open、只降不升**。
+`long2short --language` / `transcript --lang` / `gtrk tool` 的翻译语种参数本来就不做本地取值校验，这次一格不动。
+
 ## 1.1.10（2026-09-10）
 
 ### `gtrk render` 现在会把 MG 颗粒与 overlay 真的渲进成片（add-render-overlay-compositing）

package/README.en.md

@@ -36,7 +36,7 @@
 | 📦 | `gtrk deps` | Runtime assets: `status` shows where ffmpeg/fonts come from and under which licence, `install` fetches them from the Gitruck Cloud mirror (**must be triggered explicitly — never a silent auto-download**) |
 | 🤖 | `gtrk skills install` | Installs the 18 bundled CLI skills into the agents detected on this machine, via the generic `skills` adapter plus a gtrk supplement layer; `--all` covers every registered host; `gtrk skills recommend --scene <id>` browses the bundled third-party skill catalog (snapshot, offline, recommend-only) and `gtrk skills add <owner/repo>` installs through the adapter and registers the skill in the show config `style.skills` |
 | ⬆️ | `gtrk upgrade` | Upgrade the CLI to the latest version + refresh skills (config preserved); `--check` only reports |
-| 🎞️ | `gtrk render` | Render a gtrk project (EDL) locally → finished mp4 (requires ffmpeg); composites **every visible overlay layer** in contract z-order (B-roll and other overlay video tracks + MG particles; `hidden` tracks stay out); output frames are allocated against the **cumulative** timeline (per-clip rounding never accumulates, so the picture cannot drift away from the voiceover); runs a QC pass afterwards and writes `.qc.json` (`--no-qc` skips it). ⚠️ MG particles that miss the cache are cloud-rendered and **billed** (estimate + confirmation first; `--no-particles` renders particle-free at zero cost) |
+| 🎞️ | `gtrk render` | Render a gtrk project (EDL) locally → finished mp4 (requires ffmpeg); composites **every visible overlay layer** in contract z-order (B-roll and other overlay video tracks + MG particles; `hidden` tracks stay out); output frames are allocated against the **cumulative** timeline (per-clip rounding never accumulates, so the picture cannot drift away from the voiceover); runs a QC pass afterwards and writes `.qc.json` (`--no-qc` skips it); picture-in-picture clips get their `clip_transform` (scale / position / rotation / opacity), `border_radius` corners and `clip_mask` shape masks (ellipse / rounded rectangle / heart / diamond / star, feathered) composited locally, visually matching the client preview. ⚠️ MG particles that miss the cache are cloud-rendered and **billed** (estimate + confirmation first; `--no-particles` renders particle-free at zero cost) |
 | 🔬 | `gtrk qc <cut>` | Final-cut QC: one decoding pass over the whole file for flash frames, black/frozen frames, clipping, silence and audio/video drift, each with a timecode; `--gtrk <project>` enables project-aware detection of **intra-clip cuts**, `--fail-on error\|warn\|never` gates pipelines via the exit code |
 | 🔎 | `gtrk matrix` | B-roll retrieval + **candidate track laying**: consumes the FILM_BROLL dispatch → produces a candidate list + downloads preview proxies and lays N candidate tracks (`--lay N`, default 1; open it in opencut and toggle track visibility to compare; `--lay 0` produces the list only); `matrix search "<query>"` is a one-off ad-hoc search; `matrix fetch <clip_id...>` pulls raw footage during the fine cut (free re-signing + download for already-granted materials, drag straight into Jianying); **local-footage mode**: `matrix index --dirs <folders>` builds a slice-free index → `--local --dirs` retrieves and lays tracks (**your footage never leaves your machine**) → `matrix lay` consumes the (editable) plan; `matrix describe` understands candidates on demand |
 | 🎨 | `gtrk mg` | MG motion-graphics particle laying: consumes the MG dispatch → lays html-particle assets (transparent overlay / full-screen bed, produced by your show's MG skill) into the `.gtrk` `beat_track`; `mg lint <particle.html>` runs the statically checkable subset of the house rules, `mg status --project <dir>` is an orchestration dashboard; `mg render <particle.html> --duration <sec>` renders a single particle in the cloud, independent of any project, into a Jianying-readable qtrle transparent MOV (the fine-cut supplement channel); aux overlay particles can be layered on the same span (one beat derives a main particle plus `-aux<n>`). The old name `gtrk rrv` remains as a deprecated alias; `gtrk mg fetch` pulls neutral block skeletons from the HyperFrames registry (offline snapshot candidates, three-source fetch with our mirror first, mechanical rewrite then lint) |
@@ -274,6 +274,7 @@ Then just say "**cut a version of this talking-head**", or explicitly pick `gtrk
 | ④ | (no skill) | (no command) | **Global frame-sampling composition check**: sample frames from the merged three-source base layer and have the user confirm the composition — a hard agent-discipline gate feeding ⑤'s placement decisions |
 | ⑤ | `/gtrk-mg` | `gtrk mg` | **MG (incl. ov) goes on last** (stacked on the settled, composition-checked base layer) |
 | — | `/gtrk-style-maker` | (no command, builds a show) | A one-time interview that builds your show's style system (skill family + show config, see next section) |
+| ③′ | "**screen-recording PiP**" | `gtrk pip lay` | Mirror the talking-head rough cut's cut points onto a screen recording / second camera recorded in sync: lays a full-frame companion track + a muted picture-in-picture copy of the talking head (ellipse / rounded rectangle / heart / diamond / star mask, optional corner radius); purely local, zero billing; when alignment confidence is low it writes an alignment project for the client to drag into place, then `--resume` |
 | — | (wrap-up) | `gtrk render` | Render a gtrk project locally → finished mp4 (overlays and MG particles included; particles that miss the cache are cloud-rendered and billed, `--no-particles` skips them) |
 | ✂️ | `/gtrk-long2short` | `gtrk long2short` | Long-to-short rough cut: semantic segment selection + jump cuts → per-clip client/Jianying/Premiere projects (the raw file is never uploaded); **not part of the production SOP**, usable standalone at any time |
 | 📝 | `/gtrk-transcript` | `gtrk transcript` | Local video / voice-over audio → one Markdown file with an agent-written summary, timecoded record and plain text; **not part of the production SOP** |

package/README.md

@@ -36,7 +36,7 @@
 | 📦 | `gtrk deps` | 运行时资产：`status` 查 ffmpeg/字体的来源与授权，`install` 从同合云镜像装（**须显式触发，绝不静默自动下载**） |
 | 🤖 | `gtrk skills install` | 通过通用 `skills` 适配器和 gtrk 补充层，把 18 个 CLI 自带 skill 装进本机检测到的主流 Agent；`--all` 可覆盖全部已登记宿主；`gtrk skills recommend --scene <id>` 查第三方 skill 推荐目录（随包快照、不联网、只推荐不打包），`gtrk skills add <owner/repo>` 透传安装并登记进栏目配置 `style.skills` |
 | ⬆️ | `gtrk upgrade` | 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装 |
-| 🎞️ | `gtrk render` | 本地渲染 gtrk 工程（EDL）→ 成片 mp4（需 ffmpeg）；按契约 z 序合成**全部可见叠加层**（B-roll 等 overlay 视频轨 + MG 颗粒，`hidden` 的轨不进片）；输出帧按时间线**累计对齐**（逐段取整误差不累加，画面不会对配音渐进失步）；渲完自动质检并落 `.qc.json`（`--no-qc` 跳过）。⚠️ 未命中缓存的 MG 颗粒要云渲**有计费**（先预估要确认；`--no-particles` 零计费出无颗粒版） |
+| 🎞️ | `gtrk render` | 本地渲染 gtrk 工程（EDL）→ 成片 mp4（需 ffmpeg）；按契约 z 序合成**全部可见叠加层**（B-roll 等 overlay 视频轨 + MG 颗粒，`hidden` 的轨不进片）；输出帧按时间线**累计对齐**（逐段取整误差不累加，画面不会对配音渐进失步）；渲完自动质检并落 `.qc.json`（`--no-qc` 跳过）；画中画 clip 的 `clip_transform`（缩放 / 落位 / 旋转 / 透明）、`border_radius` 圆角与 `clip_mask` 形状蒙版（圆 / 圆角方 / 爱心 / 菱形 / 星形，带羽化）随工程本地合成，与客户端预览观感等价。⚠️ 未命中缓存的 MG 颗粒要云渲**有计费**（先预估要确认；`--no-particles` 零计费出无颗粒版） |
 | 🔬 | `gtrk qc <成片>` | 成片质检：单趟扫全片查闪帧/黑帧/冻结/爆音/静音/音画不同步，带时码定位；`--gtrk <工程>` 开工程感知识别**段内跳切**，`--fail-on error\|warn\|never` 供管线门控 |
 | 🔎 | `gtrk matrix` | B-roll 检索+**候选铺轨**：消费 FILM_BROLL 派单 → 产候选清单 + 下载 preview 代理铺 N 条候选轨（`--lay N` 默认 1，opencut 打开即可用轨道小眼睛对比；`--lay 0` 只出清单）；`matrix search "<词>"` 单条 ad-hoc；`matrix fetch <clip_id...>` 精剪期拉原片（已授予素材免费重签+下载落盘，直接拖进剪映）；**本地素材模式**：`matrix index --dirs <素材夹>` 免切片建索引 → `--local --dirs` 检索铺轨（**素材本体不上云**）→ `matrix lay` 消费（可编辑的）plan；`matrix describe` 按需理解候选 |
 | 🎨 | `gtrk mg` | MG 动态图颗粒铺轨：消费 MG 派单 → 把 html-particle 颗粒（透明叠加 / 满屏底层，由你栏目的 MG 生产 skill 所产）铺进 `.gtrk` 的 beat_track；`mg lint <颗粒.html>` 铁律静态子集校验、`mg status --project <dir>` 编排看板（缺 HTML / 已产未铺 / 已铺）；`mg render <颗粒.html> --duration <sec>` 脱离工程独立云渲单颗颗粒为剪映可读 qtrle 透明 MOV（精剪补给口）；aux 叠层颗粒同段多铺（一 beat 派生主 + `-aux<n>`）。旧名 `gtrk rrv` 保留为弃用别名；`gtrk mg fetch` 从 Hyperframes registry 取中性块骨架（快照随包离线候选、三源取块我方镜像优先、机械改写后过 lint） |
@@ -269,6 +269,7 @@ gtrk skills install --copy
 | ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent 纪律硬门，供 ⑤ 的排版避让决策使用 |
 | ⑤ | `/gtrk-mg` | `gtrk mg` | **MG（含 ov）最后叠上**（叠在已定稿、构图已核的底轨之上） |
 | — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
+| ③′ | 「**屏录画中画**」 | `gtrk pip lay` | 把口播粗剪的切点镜像到同步录的屏录 / 第二机位，铺屏录满幅轨 + 人像画中画副本轨（圆 / 圆角方 / 爱心 / 菱形 / 星形蒙版，可圆角）；纯本地零计费；低置信时产对齐工程让客户端拖齐后 `--resume` |
 | — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4（含 overlay 与 MG 颗粒；颗粒未命中缓存时云渲计费，`--no-particles` 可跳过） |
 | ✂️ | `/gtrk-long2short` | `gtrk long2short` | 长剪短·粗剪：长视频语义选段+跳剪 → 逐 clip 出客户端/剪映/PR 三方工程（毛片不上传），**不在成片 SOP 序列内**、随时可独立用 |
 | 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频/配音音频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |