@gitruck/cli 1.2.1 → 1.2.3

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）

package/contracts/gsap-emit-v1.md

@@ -279,6 +279,19 @@
 - **④ 根治后的处置预案**：若渲染侧将来换掉光栅路径并经真机复测确认成本塌陷，本节由 MUST NOT/SHOULD **降为提示**，
   并保留「本节曾于 2026-07-30、本证据锚所载版本口径下作为降本规范所必需」的历史记录。
 
+## Alpha 交付口径（2026-09-14 增补 · 真机事故沉淀）
+
+> **一句话**：颗粒内**一律直通 alpha**（浏览器语义），半透明是合法且鼓励的手段；把直通换成预乘是**渲染管线在剪映交付面上的义务**，不是颗粒作者或 CLI 的事。本节是该主题的唯一口径来源，`gtrk mg lint` 的 `x-soft-alpha` 文案指向这里。
+
+**事故**：文字特效模板库首批颗粒（径向渐变星芒 + `text-shadow` 软晕）经云端 qtrle 交付拖进剪映，软光晕塌成实心白多边形、50% 黄晕成满强度橙边。根因 = 剪映按**预乘** alpha 合成 qtrle（`dst×(1−α)+src`），而管线交付的是**直通** alpha；此前颗粒几乎全实心只有抗锯齿边，错配只在 1px 边缘上、看不出。修法落在 infra `html-render-qtrle-layer`（`fix-qtrle-premultiplied-alpha-for-jianying`）：qtrle 编码前 `format=rgba,premultiply=inplace=1`。
+
+### 条款
+
+1. **颗粒侧（MUST）**：颗粒里的一切颜色按**直通 alpha** 写（`rgba(r,g,b,a)` / `#RRGGBBAA` / `opacity` / 渐变里的 `transparent`），作者 **MUST NOT** 为迁就任何 NLE 自行"预乘"（把半透明色改暗）或回避半透明。软光晕、渐变、`text-shadow` 软晕、`opacity<1` 图层都是合法手段；真卷积滤镜另见「渲染成本」节。
+2. **交付面（事实，作者应知）**：客户端预览、本地 webm 层、云端 overlay 合成 = **直通**；剪映 qtrle 交付 = **管线预乘**（唯一一处）。颗粒与 CLI **MUST NOT** 再做第二次预乘（双重预乘会把软边压暗）。
+3. **验收纪律（MUST）**：凡颗粒含**半透明面积**（软光晕 / 渐变到 transparent / `text-shadow` 带 blur / `opacity<1` 图层，半透明像素占比 ≥1%），剪映路径的真机格 **MUST 用这颗本身或同类颗粒**验，**MUST NOT** 拿实心 + 抗锯齿边的颗粒代验——后者对预乘错配结构性失明。抽帧判据：解出的 qtrle 帧里半透明像素满足 `RGB ≈ 直通色 × α`。
+4. **哨兵**：`gtrk mg lint` 对含半透明面积的颗粒给**非致命**信息项 `x-soft-alpha`，只提醒「本颗粒的剪映交付依赖管线预乘配方（infra ≥ fix-qtrle-premultiplied-alpha-for-jianying），旧渲染服务会把软边渲成实心」，不拦铺轨、不要求作者改写。
+
 ## 颗粒骨架（中性模板）
 
 ```html