@gitruck/cli 1.2.5 → 1.2.7

package/AGENT.md

@@ -132,6 +132,16 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
    - **不越过用户自装的 ffmpeg**：定位仍是 `--ffmpeg-path` → `~/.gitruck/ffmpeg` → 系统 PATH。
    - 字体落 `~/.gitruck/fonts`，经 `ass` 滤镜 `fontsdir` 供给——**不动用户的系统字体表**。
    - 平台未覆盖时（如 linux-arm64）会明确报错并指引手工安装，**不会错装其他架构的包**。
+
+6. **skill 新鲜度（agent 纪律 · fix-skill-install-staleness）**：随包 `/gtrk-*` skill 是
+   **装进去的那一刻的快照**，`npm i -g @gitruck/cli@latest` 升级 CLI **不会**刷新它们。
+   ⇒ **你正在读的这份 skill 有可能落后于当前 CLI 版本，而且落后时不会报任何错。**
+   需要 skill 的命令在检测到落后时会往 **stderr** 打一次提示并附修复命令；
+   见到它 **MUST** 转告用户跑 `gtrk skills install`（或 `gtrk upgrade`），
+   **MUST NOT** 当噪音忽略 —— 「照着旧口径继续干活」正是这条提示要防的事。
+   随时自查：`gtrk doctor` 里的「Skill 新鲜度」一行。判不出或一致时**零输出**，
+   所以没看到提示不等于装过（没装过 manifest 就不存在，doctor 会如实说判不出）。
+
 
 ---
 
@@ -225,7 +235,7 @@ gtrk oralcut-result 88269671080189958 --render --out "D:/回收/某条"
 
 ## 2.2 视觉拆分派单器：`gtrk split`（成片 → 分镜派单）
 
-`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 再现 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
+`oralcut` 出的是「剪好的口播成片」；`split` 把它拆成 **beat 级视觉分镜**并派单给下游四车道（真人 A-roll / MG 动态图 / AI_DRAMA 情景动画 / FILM_BROLL 影视素材）。**纯本地、同步、无云端任务**。上游依赖 `transcript.json`（oralcut 家族恒出的句级词表，源时基）。
 
 编排顺序（脑=`gtrk-splitter` skill / 手=本命令）：
 

package/CHANGELOG.md

@@ -1,6 +1,51 @@
 # 更新日志
 
-## 1.2.5（2026-09-14）
+## 未发布
+
+### 文档：`gtrk-tools` 图纸写明 `audio_tts_clone` 可选出字幕（link-add-tts-subtitle-output-cli 3.2）
+
+输入列补 `--subtitle-format <fmt>`（可选、缺省不出、不额外计费、取值以服务端为准），产物列补另产 `tts-<音色代号>.srt`（服务端降级时不留空文件）；
+新增守卫 `test/skill-tools-tts-subtitle.test.mjs` 按列校验，防止文案被改回。
+
+### 加：文字模板候选态可按分类过滤（add-text-template-category 2.2）
+
+`gtrk mg fetch --source text [检索词] --category 打字机` 先按目录分类圈池子再检索，JSON 多返回 `category` 与 `categories`；
+分类不存在时零候选并列出可用分类，不会退回成「不过滤」。取块态给了 `--category` 就要与模板分类对得上，对不上直接拒。
+⚠️ `--category overlay|fullscreen` 是 registry 路的不透明度品类，文字模板路收到这两个值会当场报错，并指路到 `--slot <beat> --project <dir>` 派单模式。
+
+### 改：B-roll 云端编排版本不一致时，告警不再列「命中旧幂等条目」这条成因（link-arrange-decision-pin-echo 9.7）
+
+服务端已把决策层版本钉进幂等键，且入键前写下的条目已随 24 小时有效期排空（2026-09-16 生产核实：
+新鲜请求与逐字节重放都回传当前版本、重放不二次计费）。这条成因在当前部署下不可能发生，继续列出只会把排查引向不存在的地方。
+`IDEM_KEY_PINNED_DEPLOYED` 改为 `true`；服务端若回滚到版本钉入键之前，须改回 `false`。
+
+## 1.2.5（2026-09-14 定版，2026-09-15 发布）
+
+> 下面四条补录于 2026-09-16：**它们随 1.2.5 一起发出去了，但当时漏写了用户面条目**。
+> 判据取自 registry 拉回的 `@gitruck/cli@1.2.5` 包体（`dist/index.js` 里的运行期串），
+> 不是本地源码——本机全局 `gtrk` 是指向开发仓的符号链接，照它判会把未发的算进来。
+> 已发的 1.2.5 代码切在 `69a1f51`：`gate-mg-visual-job` 与「本地编译补校验」**不在这一版里**。
+
+### 修：`maxWidth` 的文字层换画幅会被挤窄（fix-text-ir-maxwidth-shrink）
+
+编译器给带 `maxWidth` 的文字层补 `width:max-content`。原先只给 `max-width`，
+块级盒会占满父宽，居中与右对齐算出来的落点因此偏。
+
+### 加：满屏槽位必须真有实心底（gate-fullscreen-slot-needs-solid-bed）
+
+`dispatch.mg` 的 `category:"fullscreen"` 表达「这段 MG 盖住画面」，此前**声明了也不会兑现**——
+信号打过（`x-category-opaque`），但走灰字 `log.info`、夹在一模一样的 `x-soft-alpha` 之间、
+`exit 0`，等于没打。现在拿不出满幅实心底就**致命拒落盘**，并给两条出路（改 `overlay`／补 `canvas.bg`）。
+配套：`dispatch.mg[].bg` 这个一直没有消费方的字段接上了——取块时钉进 IR 的 `canvas.bg`，
+声明当场兑现。**判据只取产物不取出身**：按「这颗是不是文字模板」写的闸，在加档上线当天就会错。
+
+### 修：`mg lay` 拿会漂的 `track_index` 当自产轨主键（fix-mg-lay-track-identity）
+
+契约明写它会漂、MUST NOT 当身份判据；客户端保存时按 `10+i` 重发，还会按有无物化视频劈轨。
+失败形态是「剥一半」（静默重复叠加）与「误剥用户轨」。改用内容指纹，口径照抄 `matrix-lay`
+那边早修过的成熟实现。
+
+### 改：随包文字模板目录刷到 `v2026-09-15.1` / 103 件
 
 ### 修：`mg fetch --source text --slot` 派单模式必败（fix-mg-fetch-text-slot-identity）
 

package/README.en.md

@@ -121,7 +121,7 @@ Lanes are laid **in order, with a checkpoint at every step**: first fill the B-r
         ↓                                               │
    gtrk matrix     按文稿铺 B-roll                       │
         ↓                                               │
-   AI 再现（可选）  外部平台出片 → 手动回铺               │
+   AI 情景动画（可选）  外部平台出片 → 手动回铺           │
         ↓                                               │
    客户端挑选      抽帧核构图 ← 底轨定稿前别往下走        │
         ↓                                               │
@@ -253,6 +253,17 @@ gtrk skills install --all
 gtrk skills install --copy
 ```
 
+> ⚠️ **Upgrading the CLI does not refresh the skills you already installed.**
+> `npm i -g @gitruck/cli@latest` swaps the CLI package only; the copy under each agent's directory is still
+> **the snapshot from your last install** — the agent keeps working from the stale wording, **and nothing errors out**.
+> Refresh with `gtrk upgrade` (CLI + skills) or run `gtrk skills install` on its own.
+>
+> Since **1.1.3** this is no longer silent: the skill-backed commands (`oralcut`, `long2short`, `split`,
+> `matrix`, `mg`, `subtitle`, `project`) print a one-off notice on **stderr** with the fix command when they
+> detect that the installed skills lag behind the package; when they match, or cannot be judged, output is
+> **empty**. Run `gtrk doctor` any time for the "Skill freshness" row, or set
+> `GTRK_SKILL_FRESHNESS=off` to silence the whole thing.
+
 `--agents` accepts agent IDs from both the upstream adapter and the gtrk supplement layer. Chinese agents already covered include `trae`, `trae-cn`, `codebuddy`, `qoder`, `qoder-cn`, `qwen-code`, `kimi-code-cli`, `iflow-cli`, `codearts-agent` and `lingma`, plus `workbuddy`, `qoderwork` and `comate` which upstream has not registered yet. Common shorthands — `qwen`, `kimi`, `iflow`, `codearts`, `tongyi-lingma`, `qoder-work`, `baidu-comate` — are mapped automatically. When upstream adds new agents, gtrk can use the new IDs without a release; if an existing script must hardcode a directory, `--dir <skills dir>` still gives you the compatible copy mode.
 
 **Agent input UIs are not standardized**: Claude usually surfaces skill names in `/` completion; different Codex clients enter via `$`, `/skills` or a Skills panel; TRAE relies mostly on Skills settings, explicit naming or semantic triggering. So not seeing a Claude-style `/gtrk-*` dropdown does not mean the skill is missing. If a new skill does not show up, refresh the window or start a new session.

package/README.md

@@ -120,7 +120,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
         ↓                                               │
    gtrk matrix     按文稿铺 B-roll                       │
         ↓                                               │
-   AI 再现（可选）  外部平台出片 → 手动回铺               │
+   AI 情景动画（可选）  外部平台出片 → 手动回铺           │
         ↓                                               │
    客户端挑选      抽帧核构图 ← 底轨定稿前别往下走        │
         ↓                                               │
@@ -134,7 +134,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
                      （或导出剪映草稿 / PR 工程）
 ```
 
-**记两件事就够**：① **底下的先铺、盖在上面的最后叠**——B-roll 与 AI 再现同属底轨画面（并列的两条腿），动态图（MG 主颗粒 + OV 透明叠层）是唯一的叠加层，底轨没定稿就叠等于白做；② 出片永远在客户端或你自己的剪辑软件里完成，CLI 只负责把料铺进工程。
+**记两件事就够**：① **底下的先铺、盖在上面的最后叠**——B-roll 与 AI 情景动画同属底轨画面（并列的两条腿），动态图（MG 主颗粒 + OV 透明叠层）是唯一的叠加层，底轨没定稿就叠等于白做；② 出片永远在客户端或你自己的剪辑软件里完成，CLI 只负责把料铺进工程。
 
 > 三条链各自的完整走法（含每步产物、常见问题）见使用教程的子页：**口播链**（短视频口播 / 人文社科杂谈）· **配音链**（电影解说 / 美食解说）· **长剪短**（播客 / 圆桌 / 脱口秀 / 访谈 / 直播回放）。
 
@@ -149,7 +149,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
 
 > **次序有理由**：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版是「因势象形避主体」、**依赖底轨的最终画面构图**，所以三源（影视 / 本地 / AI）必须全落齐、构图核过，才轮到 MG。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
 >
-> ⚠️ **旧版文档曾写「④ 铺 MG → ⑤ 最后上 AI 再现」，理由是「越往后叠得越上层」——那是把「工序次序」误当成了「图层次序」，已于 2026-08-17 纠正。** 若你装的是旧版 skill，`gtrk upgrade` 刷新后才是新序。
+> ⚠️ **旧版文档曾写「④ 铺 MG → ⑤ 最后上 AI 情景动画」，理由是「越往后叠得越上层」——那是把「工序次序」误当成了「图层次序」，已于 2026-08-17 纠正。** 若你装的是旧版 skill，`gtrk upgrade` 刷新后才是新序。
 >
 > **AI 出片是异步的**：外部平台抽卡可能数天，严格串行会把 ④⑤ 无限期卡住。故进 ⑤ 的门是「**AI 片段已回铺 ∨ 你明示先跳过**」；走跳过时 agent 会把与 AI 区间相邻/重叠的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述给你。
 >
@@ -190,10 +190,10 @@ CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再
 | **B-roll 候选挑选** | `gtrk matrix` 铺 N 条候选轨，用轨道**小眼睛**逐条切换对比、选定、删多余——审美取舍只能人在客户端做 |
 | **MG / 颗粒精修** | 客户端里 html-particle **活颗粒透明预览** + Transform/Blending/Effects 参数逐帧微调 |
 | **口播精剪** | 磁性主轨 ripple、手动微调切点 / 停顿 / 分屏 |
-| **AI 再现回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ③——它属底轨阶段，MG 要等它落位后才铺） |
+| **AI 情景动画回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ③——它属底轨阶段，MG 要等它落位后才铺） |
 | **最终出片** | 多车道合成（overlay / MG / particle 云渲叠起来）+ 剪映草稿导出，都在客户端出片链 |
 
-> **`gtrk render` 现在会合成叠加层了（1.1.10 起）。** 它按契约 z 序（`track_index` 升序）把**全部可见**的叠加层叠进成片——overlay 视频轨（B-roll 候选 / AI 再现回铺）与 MG 颗粒都在内；在客户端关了「小眼睛」（`hidden`）的轨不进片。
+> **`gtrk render` 现在会合成叠加层了（1.1.10 起）。** 它按契约 z 序（`track_index` 升序）把**全部可见**的叠加层叠进成片——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 MG 颗粒都在内；在客户端关了「小眼睛」（`hidden`）的轨不进片。
 >
 > **颗粒那一段有计费**：CLI 没有 HTML 渲染引擎，颗粒要送同合云烤成透明 MOV 再本地叠。计量 = **唯一颗粒数 × 未命中缓存数**（按分钟），未命中时会先出预估并要你确认（`--yes` 跳过；`--json` 下必须显式 `--yes`）。**第二次渲染全命中缓存 ⇒ 零计费**；缓存与客户端导出剪映时那份**同键同落点**（`<工程目录>/.tonghe-cache/particles/`），所以客户端烤过的颗粒 CLI 直接命中、反之亦然。不想花钱用 `--no-particles` 出无颗粒版（overlay 视频轨照常合成，那部分零计费、纯本地）。
 >
@@ -248,6 +248,15 @@ gtrk skills install --all
 gtrk skills install --copy
 ```
 
+> ⚠️ **升级 CLI 不会自动刷新已装的 skill。** `npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，
+> 各 Agent 目录下那份 skill 仍是**上次装进去的快照** —— agent 会照着旧口径干活，**而且不报错**。
+> 刷新走 `gtrk upgrade`（升 CLI + 刷 skill）或单独跑 `gtrk skills install`。
+>
+> 自 **1.1.3** 起这件事有信号了：需要 skill 的命令（`oralcut` / `long2short` / `split` / `matrix` /
+> `mg` / `subtitle` / `project`）在检测到本机 skill 落后时，会往 **stderr** 提示一次并给出修复命令；
+> 一致或判不出时**零输出**。随时自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」；
+> 嫌吵用环境变量 `GTRK_SKILL_FRESHNESS=off` 整块关掉。
+
 `--agents` 接受上游适配器和 gtrk 补充层的 Agent ID。国产 Agent 已覆盖 `trae`、`trae-cn`、`codebuddy`、`qoder`、`qoder-cn`、`qwen-code`、`kimi-code-cli`、`iflow-cli`、`codearts-agent`、`lingma`，并额外补充上游尚未登记的 `workbuddy`、`qoderwork`、`comate`。常见简写 `qwen`、`kimi`、`iflow`、`codearts`、`tongyi-lingma`、`qoder-work`、`baidu-comate` 也会自动映射。以后上游新增 Agent，gtrk 无须发版也能直接使用新 ID；已有脚本若必须写死一个目录，仍可用 `--dir <skills目录>` 走兼容复制模式。
 
 不同 Agent 的**输入 UI 不统一**：Claude 常把 skill 名放进 `/` 补全；Codex 的不同客户端可从 `$`、`/skills` 或 Skills 面板进入；TRAE 以 Skills 设置、显式点名或语义触发为主。因此没看到 Claude 风格的 `/gtrk-*` 下拉，不代表 skill 没安装。新 skill 没出现时，刷新窗口或新开会话。
@@ -287,7 +296,7 @@ gtrk skills install --copy
 > **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑤ 步（B-roll 三源全齐、构图核过才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
 > 上面 18 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，四者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
 
-**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 再现什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
+**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
 ---
 
@@ -305,7 +314,7 @@ gtrk skills install --copy
 - 栏目配置 `~/.gitruck/columns/<id>.json`（词表 vocab + B-roll 检索偏好 + style 引用清单）
 
 **【成片层 · 每片跑】= 做菜（流程形状不变）**
-剪口播 → 拆文稿 → 派单（B-roll 检索 / 动效 / 再现）→ 装配 → 渲染。每一步显式消费当前栏目配置：拆文稿按你的词表校验（`--column <id>` 或 config `defaultColumn`），B-roll 检索按你栏目的检索偏好（`broll.column_tag_ids` 栏目标签 / `material_class_policy` / facets），各车道走你自己的生产 skill。
+剪口播 → 拆文稿 → 派单（B-roll 检索 / 动效 / 情景动画）→ 装配 → 渲染。每一步显式消费当前栏目配置：拆文稿按你的词表校验（`--column <id>` 或 config `defaultColumn`），B-roll 检索按你栏目的检索偏好（`broll.column_tag_ids` 栏目标签 / `material_class_policy` / facets），各车道走你自己的生产 skill。
 
 **不建栏目？直接用默认"厨房"。** 零配置 = 内置默认栏目，端到端照常跑通，行为与配置化之前逐字节一致——栏目层是可选资产，不是必经关卡。
 
@@ -764,7 +773,7 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 把 `.gtrk` 当 EDL 用本地 ffmpeg 出成片。**素材一律取本地原片**（`materials[].path`），云端不产成片。
 
-**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 再现回铺）与 `beat_track` 的 MG 颗粒。
+**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。
 
 - **可见性只读 `hidden` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
 - **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。

package/contracts/gsap-emit-v1.md

@@ -85,7 +85,32 @@
 
 ## 八条铁律（违反任一条 → 整片渲染失败 / 颗粒冻结 / 全黑 / 坑位内突兀消失 / 画面被切成横带、内容纵向重复叠印并逐帧闪烁）
 
-1. **`<template>` 包裹根元素**：`<template><div data-composition-id="<id>" data-width="1920" data-height="1080">…</div></template>`。编译器取的是 `<template>` 内容；裸 `<div>` 会被判 "empty or could not be parsed" 整片失败。（1920×1080 为**当前引擎版本约束**，分辨率参数化预留——升版时以本契约新版为准。）
+1. **`<template>` 包裹根元素**：`<template><div data-composition-id="<id>" data-width="1920" data-height="1080">…</div></template>`。编译器取的是 `<template>` 内容；裸 `<div>` 会被判 "empty or could not be parsed" 整片失败。（**尺寸不再固定 1920×1080**，见下方「画幅」小节。）
+
+> **画幅**（2026-09-16 改写，change `add-text-ir-aspect-agnostic-layout`）
+>
+> 原文写的是「1920×1080 为**当前引擎版本约束**，分辨率参数化预留」。
+> **那句话已经过时，但不删——读者需要知道它为什么曾经是对的，否则下次还会有人按旧结论判断
+> （2026-09-15 我自己就被它误导了整整一轮）。**
+>
+> - **曾经**：`fix-particle-subcomposition-scale` **之前**，颗粒声明尺寸与根合成尺寸不等
+>   会被 `#stage` 的 `overflow` 裁掉、只渲左上一角（真机雷：opencut 720p 降采备料
+>   根 1280×720 × 颗粒声明 1920×1080）。那时放行别的尺寸就是静默出坏片，
+>   所以「只收 1920×1080」是**当时正确的**保护。
+> - **现在**：该修复已上线并过无裁切真机验收。`html_animate_render` 按颗粒声明的
+>   `data-width/height` 挂载缩放，根合成尺寸本就是 `flags.width/height` 参数
+>   ⇒ **引擎不限画幅**。
+> - **因此现在的口径是校验器口径，不是引擎约束**：颗粒声明尺寸 MUST 为正整数，
+>   且 MUST **等于目标工程画幅**。
+>
+> ⚠️ **「引擎不限画幅」MUST NOT 被读成「随便什么尺寸丢进去都行」**：
+> 挂载用的是**非等比** `transform:scale(w/dw, h/dh)`。同比例时它退化成等比（无害），
+> **跨比例是拉伸变形，不是加黑边**——16:9 的颗粒进 9:16 工程会被纵向拉 3.16 倍。
+> 所以「声明尺寸 == 目标画幅」这条不是形式要求，它就是防拉伸的那道闸。
+>
+> 文字模板（`text-v0` IR）据此做成了**一份 IR 通吃横竖屏**：IR 恒住在 1920 宽的参考系里，
+> 画幅是**编译入参**，编译期按九宫锚点定位、所有像素量乘 `k = 目标宽 / 1920`。
+> 手写颗粒没有这条路，仍需按工程画幅各写一份。
 2. **GSAP `paused` 时间线 + 注册**：`var tl = gsap.timeline({paused:true}); … window.__timelines = window.__timelines || {}; window.__timelines["<id>"] = tl;`。`<id>` 必须等于根的 `data-composition-id`。
 3. **确定性**：禁用 `Math.random` / `Date.now` / 无参 `new Date()`（过不了引擎 StaticGuard）。要"随机感"用固定种子/解析式/递归生成（见「确定性配方」）。
 4. **自包含 + 实心底下沉子层 + 透明度显式声明**（**2026-07-26 按真机实测改写**；原文「全屏颗粒给根设明确 `background`；透明颗粒根不设 background」**已作废**，见下方证据锚）：颗粒不依赖外部文件（除脚本 CDN）。底色的**取值**由调用方按其栏目规则决定，本契约只管**摆在哪个元素上**。