@gitruck/cli 1.1.9 → 1.2.0

package/AGENT.md

@@ -112,7 +112,12 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 > （用户协议 / 隐私政策链接 + 「你是所处理内容合法性的第一责任人」），**恰好一次**、之后不再复读。
 > 它**不阻断命令、不等任何输入、没有 `--accept-terms` 之类开关**，也不写 stdout（`--json` 机读面照旧干净）——
 > agent 见到它照常往下跑即可，**MUST NOT** 去改 `~/.gitruck/config.json` 的 `termsNoticeVersion` 来「绕过」它。
-> 内容不出本机的命令（`render` 本地渲染 / 工程互转 / `mg` 铺轨 / `doctor` / `deps install`）**不会**出现这条。
+> 内容不出本机的命令（工程互转 / `mg` 铺轨 / `doctor` / `deps install`）**不会**出现这条。
+> ⚠️ **`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. **按需装运行时资产**（只有用到本地渲染/烧录才需要）：
 
@@ -342,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. 产物结构 + 三端打开
 
 ```
@@ -421,6 +445,18 @@ gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":
 | 任务很久不动 | 轮询有 30min 墙钟上限；超时 CLI 会报，稍后重试或查云端任务 |
 | 结果 JSON / 报告丢了（stdout 没接住、进程崩了） | 别重跑 → 读产物目录 `result.json`，或 `gtrk oralcut-result <taskId> --out <目录> --json` 按 task_id 取回 |
 | 想换机器再拉产物 / 补渲成片 | `gtrk oralcut-result <taskId> --out <目录> [--render]`（须同账号 key；产物约 60 天有效，过期仍可取报告） |
+| 报「`--subtitle-type` 只支持 …」但你确信服务端支持 | 本地枚举快照旧了 → `gtrk doctor --refresh-catalog` 刷一次；急用可加 `--param subtitle_type=<值>` 绕过本地校验 |
+| 报「已被服务端临时下架」 | 该 task_type 真的停了（提交会拿 6029）。恢复后 `--refresh-catalog` 即可，**无需升级 CLI** |
+
+### 枚举校验的口径（agent MUST 知道）
+
+枚举取值（字幕样式/颜色、语种码、工程格式、节奏预设、任务可用性）由**服务端下发的清单**裁定，
+CLI 只在本地存一份快照（`~/.gitruck/catalog.json`，24h 自动刷新）用来**提前报错**。
+
+- **本地无快照 ⇒ 放行**，直接提交交服务端裁决。**「CLI 没拦」不等于「值合法」。**
+- **本地拦了 ⇒ 报错里已经列出可用集**，直接照着改，别去翻文档。
+- 服务端加了新值而本地还没刷到 ⇒ `gtrk doctor --refresh-catalog`。
+- `GITRUCK_CATALOG_OFFLINE=1` 可彻底关掉拉取（离线环境用）。
 
 ---