@gitruck/cli 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # 更新日志
 
+## 1.2.2（2026-09-13）
+
+### `gtrk subtitle lay` 云端拆行：`subtitle_type` 直传预设 id，PascalCase 映射表删除（link-subtitle-lay-cloud-line-split §6.2）
+
+拆行接口 2026-09-06 生产实测只认 infra `SubtitleType` 枚举**值**（`Default` / `Outline` / `CinemaYellow` /
+`ImmersiveBox` / `WideSpacing` / `DeepShadow` / `Boxed`），传 CLI 侧的预设 id `immersive_box` 会被拒「subtitle_type 未知」——
+同一枚举在 infra 两个接口上口径不一致，当时由消费方顶着，CLI 里挂了一张 `CLOUD_SUBTITLE_TYPE_BY_PRESET` 映射表兜。
+
+现在 infra 把写法归一收进零依赖轻模块 `subtitle_styles.canonical_subtitle_type_name`（`add-subtitle-line-split-api` §9），
+两个口同源。**部署后生产实测**：`immersive_box` / `ImmersiveBox` / `cinema_yellow` / `cinemayellow` 四种写法均 200、
+拆行结果逐条一致，未知值报 6016 且可选集以 snake_case 列出 ⇒ 映射表退化为恒等，按联动件收尾删除，
+预设 id 原样上行。
+
+对用户**零行为变化**：`subtitle lay` 传哪个预设、拆出来的行与上一版一字不差。
+未知 id 仍原样透传交服务端裁决（**fail-open 口径不变**）。
+⚠️ 这张表为什么拖到今天才删：删表直传 snake_case 的前提是服务端那个改动**已部署**——
+部署前删，线上就直接退回 09-06 那个「`immersive_box` 被拒」的缺陷。部署后它只是冗余而非有害，所以不急。
+
+本版无其他面向用户的改动（其余提交是 openspec 子模块指针推进）。
+
+## 1.2.1（2026-09-13）
+
+### `gtrk tool video_purify` / `image_purify`：region 作用域——按框直接去除，视频可限定时间段（link-add-purify-region-scope-cli）
+
+此前去水印只能「让服务端自己找」：`full_screen` 全片扫、`subtitle` 扫字幕带、`custom` 在归一化 ROI 里找水印。
+用户明明知道要去的东西在哪一块、在哪几秒，却没法直说。新增 **`region` 作用域**——框内**全部内容**直接去除，不做识别：
+
+```bash
+gtrk tool video_purify <视频> --purify-scope region --purify-region 0.7,0.02,0.28,0.1 --purify-region 0.1,0.8,0.3,0.12,12,48
+gtrk tool image_purify <图片> --purify-scope region --purify-region 0.7,0.02,0.28,0.1
+```
+
+`--purify-region` **可重复**，单次最多 16 个框（与服务端 `purify_roi.MAX_PURIFY_REGIONS` 同值）。
+视频的框是 `x,y,w,h[,start[,end]]`——空间四元归一化，时间两元为秒，`end` 省略即到结尾，
+**同一条片子里不同时间段的不同水印可以一次交清**。图片的框只有 `x,y,w,h`。
+`image_purify` 由此**第一次有了选项**（`--purify-scope full_screen|region`）。
+
+**组合矛盾一律前置报错**，不让用户上传完再被服务端拒：非 `region` 作用域给了 `--purify-region`、
+`region` 作用域一个框都没给、框数超上限、图片的框带了 `start` / `end`（服务端会忽略它们，CLI 让你当场知道没生效）。
+`params-json.regions` 通路照旧：只走 params-json 时只校验不改写，由 runner 的 `mergeParams` 合入（与 `custom` 的 roi 同款）。
+
+两个工具**共引同一个选项对象**（注册器按完整 flag 串去重、先注册者的 desc 生效），
+`validateRegistry` 新增一道闸拦同名选项写法不一致；`ToolOption` 加 `repeatable` 语义，注册时挂收集器、**缺省是空数组而非 undefined**。
+⚠️ 本条依赖服务端 `add-purify-region-scope` 已部署。
+
+### `gtrk matrix describe`：缓存键并入服务端判据版本，判据一改旧产物不再蒙混过关（fix-describe-window-coverage §10）
+
+`describes` 缓存的 `usable_flags` 四维是**服务端判据**的产物。判据一改（把取景器 HUD 纳入 `text_overlay` 正例、
+把被拍物体上的印字排除出 `watermark`），同一帧的正确读数就变了——而缓存键里没有判据版本的话，
+旧口径条目**永不重跑**，用户读到的还是旧判据的产物，且完全无感。
+
+现在缓存键实际是 `(material_id, ts_ms, criteria_version)`：新列**不进主键，而是读时比对**——
+行还在、版本对不上就算未命中，下一轮按正常路径重跑。**旧行不删不改、仍可读**，
+它是「用户上一轮看到过什么」的唯一凭据。写入侧改条件 upsert：版本相同维持原 `OR IGNORE` 语义
+（换准则不许改写客观层，防 VLM 措辞漂移悄悄改掉下游在读的 `desc`）；版本不同才整行刷新，
+否则新判据的 flags 永远落不进来、每轮重复计费还读到旧值。既有库幂等 ALTER 补列，旧行为 `NULL`、同走旧口径路。
+
+**报数分栏**：`--json` 新增 `cached_stale_criteria`，是 `called` 的**子集**而不是额外开销，
+专门回答「上轮明明理解过、这轮怎么又扣」——这些帧的旧产物出自更早的判据版本，不再作数。
+首值 `overlay-enum@2026-09-12`，对应 infra `link-describe-overlay-flag-recall` 当日上线的判据枚举化（叠加物两维扩枚举 + 按维分级）。
+⚠️ bump 的代价是真金白银：旧口径帧下一轮会重新调用、重新计费。这是有意的——判据变了还端旧产物，比多花一次钱坏得多。
+服务端判据上线与本常量 bump **MUST 同批发版**。
+
+### 文档：路径含英文逗号、零枚举硬失败、高潮点锚定口径（fix-material-intake-path-and-enumeration §5.2–5.4 等）
+
+- **路径含英文半角逗号**就重复传 `--dirs`，**累加不覆盖**；整串在盘上存在时自动不拆，全角「，」从不参与拆分。
+  `index` 报 0/0 先看这一条，再去查断链——README 中英与 `gtrk-matrix` 图纸排障表各补一行。
+- **零枚举是硬失败**：`gtrk matrix index && describe` 串里，零枚举会真的拦住 `describe`（个别素材失败不算硬失败）；
+  `index ... &` 后台起会把硬失败吞掉，回头要看 `materials.total` / `per_dir`——写进 `gtrk-travel-recap` / `gtrk-narration` 两份图纸。
+- README 中英与四张旗舰图纸改写**高潮点锚定**口径。
+
 ## 1.2.0（2026-09-11）
 
 ### `gtrk pip lay`：屏幕一条 + 人像一条同步录的口播，一句话合成画中画（add-pip-companion-lay）