@gitruck/cli 0.2.20 → 0.2.22

package/AGENT.md

@@ -227,7 +227,7 @@ gtrk transcript "D:/素材/采访视频.mp4" --json
 **跑完读 `report`、验证、给用户交代**（`--json` 的 stdout 那行带 `files` / `errors` / **`report`**；别只信"成功"、别谎报三端都好）：
 - **读 `report`（因势象形的另一半）**：`duration_before`→`after`（剪了多少）；`script_source`/`final_script`（无稿 `rebuilt` 时把 `final_script` 回给用户核对）；`dropped[]`（剔了哪些、`reason` retake/misread）；`coverage`（<0.6 附 `low_coverage` = 文稿与实拍严重不符）；`uncovered_script[]`（**漏读**：文稿有、实拍没找到 → 如实说，疑似漏识别则建议 `--visual-assist` 重跑）；`review_points[]`（建议复核处）；开了 visual_assist 还有 `suspect_omissions` / `stt_recovered` / `visual_assist_degraded`。**据此因势象形**：覆盖率低 / 漏读多 → 开 `--visual-assist` 或核对文稿重跑；节奏不满意 → 调 `--preset` / 散参数重跑（同毛片可反复剪对比）。
 - **报告也在盘上、丢了能取回**：同一份 `report` 恒写在 `<产物目录>/result.json`（不必依赖 stdout）。万一 stdout 没接住或进程崩了 → 直接读 `result.json`，或 `gtrk oralcut-result <taskId> --json` 按 task_id 重新取回，**不要重跑 `oralcut`**（见 §2.1）。
-- 确认产物目录在、`gtrk/project.gtrk` 非空（>0 字节）；要剪映就确认剪映草稿根里有**同名工程目录** + `draft_meta_info.json`。
+- 确认产物目录在、`gtrk/project.gtrk` 非空（>0 字节）；要剪映就确认剪映草稿根里有**同名工程目录**，且目录里是 `draft_content.json` + `draft_meta_info.json` **两个精确文件名**——剪映只认这两个固定名，带前缀的（如 `clip0_draft_content.json`）它扫不到、草稿列表里不显示。`long2short` 逐 clip 草稿同判据。
 - 云端 `errors` 非空 → 如实告知哪个格式失败、原因。
 - 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`），并**据 `report` 给一句交代**（剪了多久 → 多久、去掉了什么、有无漏读需复核）。
 

package/README.md

@@ -502,7 +502,7 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 
 ## 注意
 
-- 剪映 / CapCut 草稿需 `draft_content.json` + `draft_meta_info.json` **成对**才被软件识别——要么 `gtrk init` 配好草稿目录、要么 `--jianying-draft-dir` 指定，否则只产 content、需手动导入。
+- 剪映 / CapCut 草稿需 `draft_content.json` + `draft_meta_info.json` **成对**（且必须是这两个**精确文件名**，带前缀的扫不到）才被软件识别——要么 `gtrk init` 配好草稿目录、要么 `--jianying-draft-dir` 指定，否则只产 content、需手动导入。拷进草稿根这一跳由 CLI 统一落成固定名（`long2short` 逐 clip 同），产物目录里保留带 clip 前缀的归档原名。
 - 多台机器盘符不同时，配置走 `~/.gitruck/`（用户级；旧 `~/.gtrk-cli` 首次启动自动迁移），产物默认落毛片同目录。
 - 节奏预设强度以云端为准；`--preset` 只选预设、不改源裁剪。
 

package/contracts/gsap-emit-v1.md

@@ -204,11 +204,29 @@
 - **MUST NOT 用时间线补间驱动 `filter` 属性**（也包括补间驱动被引用 SVG 滤镜的 `stdDeviation`）：
   滤镜值一变，上一帧的卷积结果**当场失效**，缓存彻底失灵，这是本节里最贵的形态。
   同一叙事动作请改用 `opacity` / `transform`（`scale` / 位移）表达；确需滤镜就做成**静态两态切换**，别让它随时间连续变。
+- **元素带静态滤镜时 MUST NOT 用补间驱动它的 `transform`**（2026-08-06 增补，真机实测 **+42.7%**，
+  比补间驱动 `filter` 本身的 **+36.2%** **还贵**——它是本节里最容易被忽略、也最贵的一档）：
+  滤镜值虽然没变，但**被滤子树每帧换一个几何**，上一帧的卷积结果同样当场失效，
+  与「补间驱动 filter」是**同一类缓存失效**，只是驱动源换成了 transform。
+  改法按优先级：① 把滤镜**移到不参与位移/缩放的那一层**（滤镜层与运动层拆开，运动交给外层容器）；
+  ② 缩小被滤元素的几何覆盖面积；③ 预烘成 RGBA PNG 再随 transform 走（预烘图平移是零卷积）。
+  ⚠️ **射程只收 `transform`**：`opacity` 被补间驱动**不在本节射程**——opacity 侧尚无对照实测，不凭推测扩；
+  且现网唯一含滤镜的生产颗粒恰恰只被 `opacity` 驱动，收它等于把一个已知便宜的写法打成命中。
+- **`gsap.set(el, {filter: …})` 只设一次 = 静态形态**（2026-08-06 实测坐实：与写死在 CSS 里
+  **产物逐字节相同**、墙钟差 0.6% 在噪声内）。它按「整幅静态滤镜」那条走，**不按「补间驱动」那条判成本**。
+  （消费侧 lint 出于「宁误报不漏报」把它归在动画化项里报，属**检查项的保守取值**，不是本节的成本判定。）
 - **整幅静态滤镜 SHOULD 缩小被滤元素的几何覆盖面积**：把滤镜收到它真正需要的那块矩形上。
   面积一项**同时**压掉「卷积」与「整幅逐帧合成」两笔成本，故它是首选改法。
 - **MUST NOT 把「预烘成图」写成一律解法**：整幅静态滤镜的每帧成本由**两项**构成——① 卷积本身；② 整幅逐帧合成。
   预烘只消得掉 ①，② **照样每帧付**，故预烘的收益**存在上限、必有残差**；而且把活颗粒烤死会牺牲「全程可拖可调」这一产品前提。
   预烘是**次选**，不是缺省答案。
+  ⚠️ **2026-08-06 真机实测把这条推到更强的位置：整幅静态滤镜的预烘在本管线上可以是净亏。**
+  同颗对照下「把整幅 blur 层换成等效的无 filter 半透明渐变」= **64.46s vs 原样 38.07s，贵 69%**——
+  因为预烘把 blur 抹掉的高频还了回来，capture 与 ProRes 编码双双变贵（同 §证据锚 的频谱机制）。
+  ⇒ **对「整幅静态滤镜」这一形态，首选改法只有「缩小被滤面积」一条**；
+  预烘 SHOULD 先做同颗对照实测再决定，**MUST NOT 当成默认改法开出去**。
+  （口径声明：该实测的「预烘」是**近似**——换成等效无 filter 渐变，给的是「每帧重卷积 → 一次性 blit」那一侧的**下界**；
+  下界已经是净亏，真离线烘图只会更差或持平。）
 - **确要预烘时 MUST 用 RGBA PNG**，**MUST NOT** 用 JPEG 或任何无 alpha 格式：透明叠加颗粒的 alpha 是成片合成的**必需通道**，
   丢了 alpha 的图在成片里会塌成一块不透明色块（前景盖住底轨）。
 - **判断权在作者**：去不去某个滤镜属**视觉取值**，本契约不规定视觉取值——本节只给成本机制与改法。
@@ -219,11 +237,32 @@
   测量在真机（生产同款渲染主机）取得，非本地无头模拟。
 - **现网既有栏目语料（21 颗生产颗粒）**：去掉真卷积滤镜的可省墙钟 **0~3.1%**——即**本节对现有语料近似零收益**，
   它立在这里是**前置门**（防止大批带滤镜的新语料进渲染管线后整批返工），**不是**提速手段。
+- ⚠️ **「去滤镜省墙钟」依颗粒形态而定，MUST NOT 一概而论**（2026-08-06 真机同颗粒对照，**测出方向相反的两侧**）：
+  | 形态 | 去滤镜后墙钟 | 产物字节 | 方向 |
+  |---|---|---|---|
+  | **局部**滤镜、底下**平坦**（现网真颗粒：790×290 衬底 + 词光） | 51.66s → **46.10s（省 10.76%）** | −62% | **省** |
+  | **整幅**滤镜、底下**带抖动渐变** | 38.07s → **69.70s（慢 83%）** | +29%（356 MB → 459 MB） | **亏** |
+  **机制是同一条**：本管线的墙钟由 **capture + encode** 主导（capture 约占单次 CLI 全程 **89%**），
+  而 `blur` **抹掉高频** ⇒ 每帧截图与 ProRes 4444 编码都更便宜。
+  ⇒ **决定墙钟的是「去掉滤镜后画面频谱的变化方向」，不是「有没有滤镜」**——
+  去滤镜让画面变平就省，让高频回来就亏。
+  📌 **这条不动摇本节的立项与条文**：本节真正要抓的是**每帧重卷积导致缓存失效**那一类
+  （补间驱动 `filter` / 静态 filter 而 `transform` 被补间驱动），它们是**同一颗粒内的对照**、方向确定为正
+  （实测 **+36.2%** / **+42.7%**），与「去不去某个滤镜」是两个不同的问题。
 - **单次误用的止损量级（同一颗粒内对照）**：**1.3~3.3×**。
+- **同一颗粒内的形态对照（2026-08-06 真机，1920×1080 / 180 帧 / 30fps，每档 3 次取中位数）**——
+  这组才是本节条文的直接依据（**控制内容不变、只换 filter 的用法**）：
+  | 形态 | 中位墙钟 | 相对整幅静态 blur |
+  |---|---|---|
+  | 整幅**静态** `blur(24px)`（基准） | 38.07s | — |
+  | `gsap.set` **只设一次** filter | 38.29s | **+0.6%（噪声内，产物逐字节相同）** ⇒ 等价于静态 |
+  | 整幅 blur **被补间驱动**（8→40px） | 51.86s | **+36.2%** |
+  | **静态** filter、其 `transform` **被补间驱动** | 54.32s | **+42.7%（最贵的一档）** |
 - **滤镜重语料（技法颗粒，单颗 646 帧）**：**7.0×**（339.6s → 48.3s）。
   ⚠️ 该数**只对该语料成立**，MUST NOT 外推成通用提速承诺。
-- **消费侧沉默不等于便宜**：`gtrk mg lint` 的三个成本项（`c-filter-animated` / `c-filter-static-fullbleed` /
-  `c-filter-indeterminate`）是**形态提示**，**当期一律非致命、不拦铺轨**；没报**不代表**这颗渲得快——
+- **消费侧沉默不等于便宜**：`gtrk mg lint` 的四个成本项（`c-filter-animated` / `c-filter-static-fullbleed` /
+  **`c-filter-static-transformed`**（2026-08-06 增补，覆盖上面那条 +42.7% 的漏报面）/ `c-filter-indeterminate`）
+  是**形态提示**，**当期一律非致命、不拦铺轨**；没报**不代表**这颗渲得快——
   真判据永远是**真渲染出片计时**。
 - **致命性的升级触发器（登记在此，免得日后凭印象改）**：把 `c-filter-animated` 提为**致命**
   SHALL 另走一个独立 change，且 SHALL 同时满足两项前提——① 「滤镜重语料批量进渲染管线」那条路线**已立项**；
@@ -297,5 +336,5 @@
 - **transform-origin（SVG）**：缩放 `<g>` 用 GSAP `svgOrigin:"x y"`（SVG 用户坐标），别用 CSS transform-origin。
 - **时间线总长 ≥ 坑位时长**：颗粒 tl 总时长 ≥ 落轨 clip 时长（坑位包络），否则 seek 越界（已升格为铁律 7，含终态驻留要求）。
 - **整组同步驱动的重复图元必须合并**：网格、排线、刻度、点阵用单元素表达，SVG 以一条 `<path>` 的多子路径合成；逐元素动画批次豁免。详见 gsap-emit v1 铁律 8。
-- **真卷积滤镜别用补间驱动、整幅静态滤镜先缩面积**：`blur()` / `drop-shadow()` / `feGaussianBlur` 按「面积 × 半径 × 帧数」吃每帧墙钟；预烘是次选且必须 RGBA PNG。`box-shadow` 整族不在射程内。详见本文件「渲染成本：真卷积滤镜」一节。
+- **真卷积滤镜别用补间驱动（也别让带滤镜的元素被 `transform` 补间驱动）、整幅静态滤镜先缩面积**：`blur()` / `drop-shadow()` / `feGaussianBlur` 按「面积 × 半径 × 帧数」吃每帧墙钟；**每帧重卷积**才是最贵的形态（补间驱动 filter +36.2%、静态 filter + transform 补间 **+42.7%**）。预烘是次选、必须 RGBA PNG，且**对整幅静态滤镜实测可能净亏**（先做同颗对照再用）。`box-shadow` 整族不在射程内。⚠️「去滤镜省墙钟」**依颗粒形态而定、不能一概而论**。详见本文件「渲染成本：真卷积滤镜」一节。
 - **别用 `requestAnimationFrame`/`setInterval` 驱动画面**——不被 seek，等于冻结。所有视觉变化必须挂在 tl 上。（与「回调与 seek 语义」一节同源：任何**不经 tl** 的自有时钟都不被定帧驱动；而挂在 tl 上的回调是否被触发，则由该节的引擎侧条款保证。`gtrk mg lint` 对本条给**非致命**项 `x-raf-interval`——静态正则分不清「驱动画面」与其它用途，故只提醒不拦。）