@gitruck/cli 1.3.16 → 1.3.17

package/CHANGELOG.md

@@ -1,1231 +1,1262 @@
-# 更新日志
-
-> 📌 **1.2.6 ~ 1.2.11 六个版本段补录于 2026-09-19**：此前这六版没有版本段，改动全堆在「未发布」里。
-> 判据取自 registry 拉回的包体（`npm pack @gitruck/cli@<ver>` 解包，认 `dist/index.js` 里的**运行期中文串**，
-> 外加随包的 `skills/` `contracts/` `README.md`）——不按提交时间倒推，也不查本机 `node_modules`
-> （那是指向开发仓的符号链接，照它判会把没发的算成已发）。
-> npm 记录的各版 `gitHead`：1.2.6 `c2a0f46` · 1.2.7 `03cd95c` · 1.2.8 `a55fb66` · 1.2.9 `e35f311` ·
-> 1.2.10 `966651c` · 1.2.11 `7a58f02`。
-> ⚠️ **`gitHead` 只是旁证**：1.2.7 是从**带未提交改动的工作区**发的——`link-cloud-font-library` 的实现
-> 在 1.2.7 的包体里逐字可见，却要到 2026-09-19 的 `4ee4f74` 才进仓。判版本归属一律以包体为准。
-
-## 未发布
-
-- 新：`gtrk matrix describe --layout grid` 可选让服务端把帧拼成 3×3 宫格一次理解，同一 beat / 检索词的候选尽量拼在同一页；缺省仍逐张（`--layout single`），计费不变（1 积分/张）。服务端是否真按宫格执行只看回执：未升级或被运维停用时如实说明「按逐张理解」，`--json` 带 `layout_receipt` / `layout_counts`。宫格产物的 mark / highlight 只在同一页内可比、景别与黑边不如逐张稳，人读输出会提醒；缓存记下产出方式，逐张运行不复用宫格产出的缓存（`--json` 的 `stale_layout`）。需服务端同步上线宫格批量后才生效（link-add-material-describe-grid-batch）。
-
-## 1.3.15（2026-11-07）
-
-- 新：`gtrk matrix search` 的 `--query` 可重复给，几个角度一次跑完：结果按素材合并（留最高分），逐条标 `matched_queries`、按分数排，回执带 `queries`；只给一个检索词时输出不变。外网检索仍一次一个词（fix-agent-harness-feedback）。
-- 新：`gtrk matrix search --estimate-only` 只报这次最多花多少积分、不检索：`--json` 的 `billing_estimate: {credits, basis}`（成员口与 `--local` 为 0，公开口按价目表 × 检索词数，算不出为 `null`）。`gtrk oralcut` / `gtrk long2short` 的 `--dry-run --json` 同带 `billing_estimate`。即剪内置 AI 据此对估价不超过 100 积分的命令不再弹确认（fix-agent-harness-feedback）。
-- 新：`gtrk matrix search "<词>" --beat <id> --project <目录>` 把结果写进这个 beat 的候选池：并进本层快照 `split/broll-plan.<层>.json`、追加进工程候选登记，客户端 B-roll 面板立刻能看到，`gtrk patch add --candidate` 直接认得；不铺轨，重跑不重复（fix-agent-harness-feedback）。
-- 新：`gtrk matrix lay --pool-only [--beat <id,…>]` 只把 plan 里还没进工程候选池的候选登记进去——不铺轨、不下载、不动任何轨，也不需要联网。治「`matrix status` 报 `not_in_pool`、面板里看不到」；此前只能跑局部 `matrix lay`，会按铺轨口径另起一条候选轨（fix-agent-harness-feedback）。
-- 新：`gtrk patch add` 一次放多段：`--to 263.7 --candidate A --to 266.2 --candidate B`，`--to` 每给一次是一段，`--candidate` / `--material` / `--track` / `--beat` / `--from` / `--dur` 只给一次就各段共用、给同样多次就按顺序配对。一次下载、一次写回；同一条轨上前一段缺省停在后一段起点；某段出错报「第 N 段」、整批不写（fix-agent-harness-feedback）。
-- 新：`gtrk patch remove (--clip <id> | --track video:<N> --at <秒>)` 删掉一个片段，原位置留空、后面的片段不动；视频与同 id 的镜像音频一起删；`--ops` 里也能用（fix-agent-harness-feedback）。
-- 改：`gtrk patch add / replace` 放上轨的候选只在 plan 里、不在工程候选池时，顺手登记进该 beat 的候选池（层取它所在那份 plan），回执 `source.pooled`——此前轨上有画面、面板里却找不到这条候选（fix-agent-harness-feedback）。
-- 改：`gtrk client state` 读到客户端实时状态时带 `disk`：与盘上工程的轨号对照（客户端有没保存的轨道增删时两边会错开）、是否有未保存改动；对不上时 stderr 提示 `gtrk patch` / `gtrk matrix` 按盘上的轨号写（fix-agent-harness-feedback）。
-- 改：`gtrk matrix status` 顶层带 `video_tracks[]` 全工程视频轨总览（轨号、口播主轨、判定、来源层、片段数），人读首行列出（fix-agent-harness-feedback）。
-- 修：重铺某一层时，候选池里「添加视频链接」/ `gtrk matrix source-import` 导入的候选（没登记来源层）被当成老式条目洗掉；客户端随后把导入任务当检索翻页，「加载更多外网候选」报「更多候选来源或时间段不一致」。现在手动导入的候选哪一层重铺都保留，连同它的导入任务号；没登记层但来自外网的候选按外网层算（fix-agent-harness-feedback）。
-
-## 1.3.14（2026-11-07）
-
-- 修：`gtrk patch --ops` 清单里的时刻写成 JSON 数字（如 `"at": 375`）时，按 `track` + `at` 寻址的动作崩在 `f.trim is not a function`；现在数字与字符串同一口径（`at` / `to` / `cut` / `track` / `total` 均可）（fix-matrix-partial-relay 3.2）。
-- 修：`gtrk matrix` / `gtrk matrix lay` 重铺某一层时，plan 只含这一层的部分 beat（只补空缺）会把同层其余 beat 的候选登记整个冲掉——客户端 B-roll 面板显示「这个区域还没有素材」，原来的候选池也没了；旧轨若没被动过，那些 beat 的画面也会被一并剥掉。现在 plan 外的 beat 原样保留：本层旧轨上属于它们的片段按原轨序带到新轨（旧轨比本轮 `--lay` 多时本层带区相应加宽），候选（含老式无层登记的）、外网检索任务号与 laid 登记照旧；与本轮 plan 内 beat 时间窗重叠、带不回的旧片段丢掉并告警。人读出一条「局部重铺：…其余 N 个 beat 原样保留」，`--json` 带 `lay.partial_relay`。plan 含这一层全部 beat 时行为不变（fix-matrix-partial-relay）。
-
-## 1.3.13（2026-11-06）
-
-- 新：`gtrk matrix --online --online-concurrency <n>`（1–8，缺省 3）：外网检索按派单顺序提前提交、同时至多 n 单，不再一单跑完（8–11 分钟）才提交下一单；plan、逐条日志与进度落盘仍按派单顺序，和串行时一样。提交与进度日志带 beat 名。`1` = 旧行为（fix-matrix-layered-plans-and-ux）。
-- 改：每轮检索除主 plan `split/broll-plan.json` 外另存本层快照 `split/broll-plan.<层>.json`（local / online / concept / common；外网零候选、主 plan 被保住时不写），`--json` 带 `layer_plan_path`。换层检索覆盖主 plan 后，别的层仍可 `gtrk matrix lay --plan split/broll-plan.<层>.json` 重铺；`gtrk patch --candidate` 与 `gtrk matrix status` 连同快照一起找候选（主 plan 优先）。概念层检索的 plan 带 `source_layer: "concept"`，`matrix lay` 据此铺进概念层（此前会被当成通用层）；其余层不写该键，既有 plan 不变；`source_layer` 与 `member_type` 不配套的 plan 拒收（fix-matrix-layered-plans-and-ux）。
-- 改：`gtrk patch add / replace` 放上 / 换过的片段带 patch 自己的产出方身份（此前 `add` 不写、`replace` 删掉），所在候选轨判「已编辑」：同一层再 `matrix lay` 拒铺（`tracks_edited`，工程零改动），不再当成你的轨保留、另铺一条越铺越多。整条都是 patch 放的、又不在铺轨登记里的轨仍算你的轨（fix-matrix-layered-plans-and-ux）。
-- 改：已编辑候选轨的拒铺只看本轮要铺的层：别的层的已编辑轨（客户端确认过原片的、patch 改过的）随它的层带保留、不挡本层铺轨，`--force-relay` 也不剥它；告警写明「本轮铺的是 X 层，不动它」。`gtrk matrix status` 的 `lay.edited_track_layers` 报出各已编辑轨所属的层（fix-matrix-layered-plans-and-ux）。
-- 新：铺轨后点名被地板藏起来的候选——整条分（`result.score`）过了 `--score-floor`、片段分（`segments[].score`）却全低于它、一条也没铺上的，逐 beat 报条数与最高片段分，并说明地板卡的是片段分、给出调低地板或钉选两条出路；`--json` 带 `lay.floor_hidden`。`gtrk matrix status` 的候选带片段分（`seg.score`），与整条分不同时人读输出并列「（片段 x）」；`--score-floor` 帮助写明卡的是片段分。地板算法不变（fix-matrix-layered-plans-and-ux）。
-- 改：已装的 gtrk skill 落后于 CLI 包时，没被你改过的（已装副本与安装时的戳一致）直接换成包内版本、只说一行「已把 N 个 gtrk skill 更新到当前 CLI 包的版本」；改过的、换不动的、新加的照旧提示 `gtrk skills install`。`GTRK_SKILL_FRESHNESS=off` 同时关掉自动换新（fix-matrix-layered-plans-and-ux）。
-- 改：`gtrk matrix --online` 不带 `--platforms` 时只检索 `youtube` / `vimeo` / `bilibili` / `pexels`，TikTok 须显式写进 `--platforms`（服务端 TikTok 发现改走按次计费的 TikHub）。升级前同一批次（`--online-session`）按旧缺省（五平台、最早的四平台）建过单的，照旧沿用原请求续跑、不新建单、不重复扣费；要按新缺省检索请换批次名（link-online-broll-tikhub-discovery-cli）。
-- 修：外网检索产出的 plan 被 `gtrk matrix lay` 整单拒收（「segment cuts 须为升序有限数字且严格落在 (start,end) 开区间内」）。服务端把片段起止点本身也列成切点：现在写进 plan 前去掉这些端点切点，`matrix lay` 校验也容忍恰在段起止点上的切点，盘上已有的旧 plan 不用改就能铺；乱序、越界照旧拒收（fix-matrix-online-relay-and-review）。
-- 修：`gtrk patch add / replace --candidate` 在工程根目录本身叫 `gtrk`（`<x>/gtrk/project.gtrk` + `<x>/gtrk/split/`）时读到外层 `<x>/split/broll-plan.json`，报「都没有候选」。现在与 `gtrk matrix` 同一口径：给了 `--project` 且其下有 `split/` 就以它为根，否则看工程文件所在目录有没有 `split/`，再否则退到 `gtrk/` 的上一级；找不到候选时报错写出实际读的 plan 路径（fix-matrix-online-relay-and-review）。
-- 修：外网检索没有可自动铺的候选、只有待人工确认候选（需求里的地点 / 事件 / 年份 / 素材类型等硬条件服务端核实不了）时，CLI 此前报「0 条候选」或「外网平台或素材处理失败」、计入 `errors`，还建议「调整检索描述后重试」（换描述会新建计费任务）。现在逐条写「0 条自动候选，另有 N 条待人工确认」、不计 `errors`；汇总单独列出，说明它们在 plan 的 `queries[].online.review_candidates`、挑中后移进 `results`（可加 `pinned:true`）再 `gtrk matrix lay` 即可铺，并说明不必重跑；铺轨阶段的零候选告警点名各 beat 的待核条数（已进客户端候选池）；`--json` 的 `counts` 加 `review_only` 与 `review_candidates`，既有字段不变。真正零召回的仍给重试建议（fix-matrix-online-relay-and-review）。
-
-## 1.3.12（2026-11-05）
-
-- 新：`gtrk patch add --track video:<N> --to <秒> (--candidate <clip_id> [--beat <id>] | --material <id>) [--from <秒>] [--dur <秒|Nf>]`，把一条 B-roll 候选或已登记素材放到视频轨的空位上：候选先查工程候选池（含邻居）再查 `split/broll-plan.json`，素材还没登记时顺手下载预览到 `assets/broll-preview/` 并登记（与 `gtrk matrix lay` 同一份落地实现，已登记的不重下）——`matrix source-import` 之后一条命令就能上轨。缺省时长取落点所在空位、出点与右邻同一帧；入点缺省与客户端拖候选同一取窗。落点与已有片段重叠即拒并列出挡路片段（黑底补片指路 `patch replace`），覆盖到的空档让位；源片不够长钳短告警、不拉伸；图片候选不收；不建轨、不 ripple。新片段 `<beat>-add-<n>`、不带产出方身份（add-patch-insert-replace）。
-- 新：`gtrk patch replace (--clip <id> | --track video:<N> --at <秒>) (--candidate … | --material …) [--from <秒>]`，原地换源：只换素材与源窗，起点 / 轨 / `clip_id` / 倍速 / 变换 / 填充 / 转场 / 关键帧不动；新素材不够长如实缩短（`replace_shortened`），不拉伸；去掉产出方身份，下一次 `gtrk matrix` 铺轨把这条轨当用户轨保留；镜像对不收（add-patch-insert-replace）。
-- `add` / `replace` 先按自述值把全部改动算一遍、全档校验，过了才下载落地，落地完再读工程写回；`--dry-run` 不下载、不写文件，回执带 `would_download`；`--ops` 条目可用这两个动作，同批先统一落地。回执 op 另带 `source` 与 `gaps_consumed`。预览下载失败零写、非 0（`preview_download_failed`），已落盘的预览留作下次复用（add-patch-insert-replace）。
-- 修：`gtrk patch` 的未知动作报错与 `--ops` 合法动作列表此前漏列 `seal` / `snap`，现在列全（`seal` / `snap` 是轨级动作，只能单发）（add-patch-insert-replace）。
-- 改：`gtrk matrix` 铺轨的候选落地（代理文件名、复用 / 下载、ffprobe 实测、素材条目）抽到 `src/lib/broll-landing.ts`，与 `patch add / replace` 共用；同输入铺轨产物、日志与 `--json` 回执与抽出前逐字节相同（add-patch-insert-replace）。
-- 新：`gtrk matrix status --project <工程目录> [--beat <id>[,<id>…]] [--json]`，一条命令看清某个 beat 的现状：时间窗（现场重投影，降级时标明原因）、候选池（精简字段、不带下载地址，标出预览是否已落地、已用在哪些片段上）、plan 里其余候选的条数与得分最高 5 条、时间窗内各视频轨上的片段与类别、主轨之上的空缺（另列只有黑底补片的区间，短于一帧的缝不算）；不带 `--beat` 时全部 B-roll beat 一行一个概要。顶层给工程 `revision`（可作 `gtrk patch --expected-revision`）、各候选轨剥离判定与整轮重铺会不会被 `tracks_edited` 拒。只读、不联网、不需要 Key、不写任何文件；beat 不存在时退出码 1 并列出全部已知 beat（add-matrix-beat-status）。
-- 新：外网检索授权码。`gtrk matrix --online` 检索和 `gtrk matrix source-import` 导入完成后，CLI 用当前 Key 向服务端取这次检索的授权码，写进每条外网候选（含待核候选）的 `origin.search_grant`，plan、回执与工程都带上；工程交给别的账号后，对方凭它在客户端读候选、确认 B-roll。服务端还不支持（404）、未启用或网络失败时照常完成，只是不带码，终端提示一行（派单多条检索时同一原因只提示一次）。格式不对（不是 `g1.` 加 43 位 base64url）的授权码解析时丢掉，候选照常可用；`gtrk matrix lay` 原样带进工程（link-online-broll-search-grant-cli）。
-- 新：`gtrk matrix grant --project <工程目录或 .gtrk>`，给工程补检索授权码（授权码上线前的老工程也适用）。只为一个码都没有的检索取码，同检索已有码的直接沿用；取不到的（不是当前账号的检索、已删除、服务端不支持）逐个列任务号与原因，候选不动，退出码非 0；输出「补了几个、已有几个、取不到几个」，`--json` 给 `granted` / `existing` / `failed`。工程没有变化时不写盘，有变化时原子写回、只改外网候选的 `origin`（link-online-broll-search-grant-cli）。
-
-- 新：`gtrk cover embed <工作台.html> [--bg-16x9 <图>] [--bg-4x3 <图>] [--bg-3x4 <图>] -o <输出.html>`。封面工作台把背景图按尺寸压成 JPEG（16:9 长边 ≤1280、4:3 ≤1600、3:4 ≤1400）并以 base64 嵌进去，替掉 `/gtrk-cover` 里「临时脚本压缩 + 注入」那一步；纯本地、零计费，压缩结果经管道回内存、不写中间图片。`-o` 必填（可与输入同名），没给图的尺寸占位符保留并提示，工作台超过 600 KB 提示、超过 1 MB 告警（link-in-app-agent-capability-shelf）。
-- 新：`gtrk ai-drama validate <候选分镜稿.md> [...]`。`/gtrk-ai-drama` 落盘前的分镜稿校验收成子命令，判据、输出与退出码与随包的 `scripts/validate-storyboard.mjs` 逐字节一致（脚本再保留一个版本周期）；即剪内置 AI 只许运行 gtrk，这一步此前跑不了（link-in-app-agent-capability-shelf）。
-- 新：`gtrk-cover` / `gtrk-tools` / `gtrk-transcript` / `gtrk-matrix` / `gtrk-ai-drama` / `gtrk-music-visualizer` / `gtrk-ref-reading` 标 `in_app_agent`：即剪内置 AI 每轮常驻这 7 个 skill（加上原来的 4 个共 11 个），客户端输入区「常驻能力」里的封面制作、小工具等入口据此出现；测试闸照常守住「要 agent 执行的命令全是 gtrk」（link-in-app-agent-capability-shelf）。
-
-## 1.3.11（2026-11-04）
-
-> 本段补录于 2026-11-05：1.3.11 于 2026-11-04 从 `7f605ce`（版本号改动未提交的工作区）发出，当时没写版本段，改动留在「未发布」里。
-> 归属按包体抽查：本机装的 1.3.11 `dist/index.js` 里有 `--neighbors`、转场、音频淡变、`volume_zero_use_muted`、`--redraw`，
-> 没有检索授权码、`patch add` 的 `would_download`、分镜稿校验——与「`7f605ce` 之前进仓的归 1.3.11、之后的归 1.3.12」一致。
-
-- 新：工程片段的**转场**（即剪客户端写进 `.gtrk` 的 `transition_in` / `transition_out` / `transition_next`）CLI 全程认得、本期不产出。任何命令都原样带着转场走，新铺的片段不带转场。`gtrk patch split` 入场转场留前段、出场与接下一段的转场归后段（此前两半都复制同一个转场，前段那个立刻悬空、切口凭空多出一个入场）；每次 `gtrk patch`（单发或整个 `--ops` 批）写回前对改动过的轨统一维护：下一段被移走后不再紧邻的「两段之间」转场删除（不改挂到新邻居），剪短后放不下的按帧缩短（先头后尾），回执逐条给 `transition_dropped` / `transition_shortened`；与本次编辑无关的存量转场问题只报不拦。`matrix` / `mg` / `ai-drama` / `pip` / `audio` / `composite lay` 重铺自产轨时，被替换掉的片段若带你在客户端加的转场，日志与 `--json` 回执给出 `replacedTransitionClips`。`gtrk project export` 上行前把工程规整一遍（悬空、越界的删缩并列进 `result.json` 的 `transitions`，盘上工程不动），免得云端整单拒收；云端各格式本期不承接转场，导到剪映 / Pr 里是硬切，回执里的 `transition_not_carried` 逐条打出。`gtrk render` 本期按硬切出片并计 `transition_not_carried`（无转场工程滤镜串逐字节不变）。转场颗粒目录不随 npm 包分发：工程带转场时才从后端拉 `cloud/static/assets/transitions/catalog.json`，缓存在与客户端共用的统一静态资源缓存 `~/.gitruck/cache/transitions/catalog.json`（24 小时一刷）；离线、目录不可用或颗粒不在目录里时转场原样保留，命令照常工作。⚠️ **编辑含转场的工程需本版本及以上**：旧版不报错，但切分会复制转场、移动后留下悬空转场、重铺静默删掉用户的转场、上云被拒收（link-gtrk-clip-transitions）。
-
-- 改：`gtrk mg fetch` 的 MG 区块与文字模板（`--source text`）改走统一静态资源下发，目录格式与本机缓存同即剪客户端共用一套（unify-static-resource-delivery）。
-  - 文字模板：目录缓存从 `~/.gitruck/text-templates/` 挪到 `~/.gitruck/cache/text-templates/`（旧位置不再读，首次联网自动重拉）；拉到远端目录即用，不再按版本号择新（服务器回滚就是换回旧目录）；正文按内容寻址取，每份都校 sha256 与字节数，命中本机缓存不打网。候选不再列「预览」（封面从未发布过）。
-  - MG 区块：候选态照旧零网络（读本机缓存的目录，没有就用随包快照）；取块前先刷新一次目录（24 小时一刷，缓存在 `~/.gitruck/cache/mg-registry/`），镜像改为同合云优先、取不到再经 GitHub raw / jsDelivr fastly / jsDelivr gcore / gh-proxy 回源；目录里块被下架或改判 excluded 时按刷新后的目录拒取。
-  - `GITRUCK_TEXT_TEMPLATE_BASE` / `GITRUCK_MG_REGISTRY_BASE` 现在指镜像根：`<根>/catalog.json` 与 `<根>/files/…`（即统一发布的暂存包 / 静态盘布局，不再是 `blocks/<名>/<文件>`），设了就只用它，不写本机缓存。
-  - `--json` 回执：取块与候选多了 `catalog`（目录版本与来源）；命中本机缓存时 `fetched_from` / `source` 是 `cache`、`url` 是 `null`；全部镜像失败的报错改为逐个镜像列原因（不再是「三源皆不可用」）。
-
-- 改：`gtrk deps install --font` / `--font-family` 改从统一静态资源下发的字体目录装（`cloud/static/assets/fonts/catalog.json`，与客户端同一份目录、同一套命名），不再读字体库 `manifest.json`。`--font` 装的是目录顶层登记的字幕字体（思源黑体 CN Bold，落 `~/.gitruck/fonts/sourcehansanscn-bold.otf`）；每款都校 sha256 与字节数，取不到时逐个镜像说明原因、不落半成品；字体文件不另存一份到 `~/.gitruck/cache/`。已装按文件名归一比对，历史命名 `SourceHanSansCN-Bold.otf` 也算已装、照旧跳过；`--force` 重下时换成目录里的命名。`gtrk deps status` 的字体一行改报目录版本、族数 / 款数与字幕字体装没装（unify-static-resource-delivery）。
-
-- 新：`gtrk matrix --neighbors <n>`（0–5）。矩阵成员检索概念素材时，命中镜头连同它在原片里前后各 n 个镜头一起带回，适合接成一串蒙太奇。
-  - `matrix search` 加上它后，有邻居的结果下面会按原片顺序列出整段（不相接处标 `⋯`），并给出现成的 `gtrk matrix fetch` 命令，邻居可直接拉原片。
-  - 派单检索缺省带 2：邻居写进工程，在客户端 B-roll 面板里折叠，由你单张挑选，不参与自动铺轨；`--neighbors 0` 关闭。
-  - 服务端返回的出处字段 `source` 在 CLI 里改叫 `source_ref`（link-clip-search-neighbors-cli）。
-
-- 改：`gtrk audio lay --volume 0`（含 `0.0` / `-0`）现在直接拒绝、不写工程。它不会静音——客户端、`gtrk render` 与云端都把 `volume: 0` 读成原音量，BGM 照样满音量；不想要 BGM 就别铺，铺好后要静音用 `gtrk patch set --muted`，要很轻的垫底给个小正数。其它越界值照旧按默认 0.1 回落并告警。
-- 改：`gtrk patch set --volume 0` 现在直接拒绝（`volume_zero_use_muted`），提示改用 `--muted`。契约 §4 不以线性 0 表达静音，客户端、`gtrk render` 与云端工程导出 / 时间线渲染都把 `volume: 0` 当旧客户端 0 dB 残档读成原音量，此前这条命令「成功」却听不出变化；`--ops` 批量里出现同样整批不写。
-- 改：`gtrk patch set` 的静音改按「轨是总开关」判，与客户端、`gtrk render` 一致——轨或片段任一静音即静音，片段上的 `muted: false` 打不开已静音的轨。⚠️ **原来在静音轨上「成功」的 `set --no-muted` 现在报错** `track_muted_master`（以前写进 `muted: false`、回执说已取消静音，实际照样静音）：`patch set` 不改轨级参数，请在客户端点开该轨喇叭。静音轨上 `set --muted` 显式写 `muted: true`（之后轨解除静音，这段仍静）。`set --audio-track` 转轨按有效静音保真：从静音轨移到不静音的轨，片段写上 `muted: true`；把原本出声的片段移进静音轨报 `audio_track_target_muted`、工程不动。音量照旧按「片段覆盖轨」（link-gtrk-track-muted-precedence）。
-- 新：工程片段的**音频淡入淡出**（即剪客户端写进 `.gtrk` 的 `audio_fade_in` / `audio_fade_out`）CLI 全程认得。`gtrk patch` 剪短片段时淡变放不下就按比例缩、回执出 `audio_fade_clamped`，切开片段时前段只留淡入、后段只留淡出（此前切点处会凹一下）；新参数 `gtrk patch set --audio-fade-in / --audio-fade-out`（秒或帧，0 即删键，两侧之和超过片段时长直接拒）。`gtrk render` 按淡变出声（按成片时间计、变速片段不换算，无淡变工程滤镜串逐字节不变）。`gtrk audio tighten` 遇到带淡变的音频片段拒绝并点名、工程不动；`gtrk audio lay` 同源重铺把带淡变的旧片段替换掉时如实告知条数。`gtrk project export` 把云端返回的产物级告警全部打出并写进 `result.json` 的 `warnings`（含剪映 / Pr 等格式对淡变的降级说明，顺带变速保调降级告警也不再被吞）。⚠️ **编辑或渲染含音频淡变的工程需本版本及以上**：旧版不报错，但切分会让两半都带两侧淡变、剪短不缩、`audio tighten` 逐段复制、渲染没有淡变（link-gtrk-clip-audio-fade）。
-
-- 修：`gtrk render` 不认音频轨的静音——客户端里点了 BGM 轨的喇叭、或用 `gtrk patch set --muted` 静了某段音频，本地渲染出来照样有声，与客户端导出不一致。现在音频轨的轨级与片段级 `muted` 都生效：轨静音是总开关（片段上写着 `muted: false` 也不出声，与客户端一致），片段静音只静那一段；静音部分不再读素材音频，成片总长不变。所有音源都被静音时照常出无声成片，并打「本片无音源」提示。没有静音音频轨的工程，渲染结果与之前相同（fix-render-audio-track-muted）。
-- 修：同一台机器既装了 gtrk 插件（Claude Code / Codex 插件市场）又跑了安装器，Agent 里的 Skill 会出现两份——插件自己的引导让人跑的 `npx -y @gitruck/cli@latest install` 会再装一份。现在：`gtrk install --no-skills` 只装 CLI 和配置、不装 Skill，插件的引导（Claude Code 会话开头提示、Codex 详情、README 插件一节）都改用它；安装器认得已启用的 gtrk 插件，默认安装时按宿主让路——Claude Code 有插件就照装给其他 Agent、撤掉 Claude Code 里那几条链接，Codex 有插件就这一步不装（它直接读 `~/.agents/skills`，再装一份就是两份），让路算成功，`gtrk upgrade` 不再误报「skill 没刷成」；点名 `--agents` 时照装，会重复就提示一行。已经重复的只报不删：`gtrk doctor` 新增「Skill 来源」一行，新命令 `gtrk skills uninstall` 移除安装器装的那份（第三方 Skill 与插件那份不动）；Codex 插件在场时过期提示改指移除。（fix-plugin-installer-duplicate-skills）
-- 新：Codex 插件市场与 Cursor 插件清单——仓库根即插件，随包 20 个 `gtrk-*` Skill 照旧取 `skills/`。Codex：`codex plugin marketplace add Gitruck/cli` 后 `codex plugin add gtrk@gitruck`（只装 Skills，CLI 与 API Key 用 `npx -y @gitruck/cli@latest install --no-skills` 另装）；Cursor 清单 `.cursor-plugin/plugin.json` 供插件市场审核。发版闸 `plugin-manifest-check` 改为 Claude Code / Codex / Cursor 三份清单的 version 都须与 package.json 一致。
-- 新：`gtrk client state / segment / frame`——读编辑器里的工程。即剪客户端开着这个工程时经本机通道读活状态（选中哪段、播放头、编辑器所见的画面）；没开时读工程文件、本地渲出一帧（零计费、不含 MG 颗粒），两条路输出同形、`source` 标明是哪条，客户端缺席不影响任何子命令。`frame --at` 收的是**时间线**时刻：粗剪过的工程拿轨上时码去 seek 毛片会取到另一处画面，`gtrk-splitter` / `gtrk-mg` 的抽帧步骤因此改用它。`gtrk media probe` 收目录（列出这一层的音视频与参数），`gtrk media cut --copy` 流拷贝截段（秒级、起点按关键帧对齐），`gtrk media frames` 没给 `-o` 时认 `$GTRK_FRAMES_DIR`。`gtrk-splitter` / `gtrk-mg` / `gtrk-oralcut` 标 `in_app_agent`：要 agent 执行的命令全是 gtrk（装 CLI 那一步标为外部 agent 的前置），测试闸守住。
-- 修：`gtrk qc --gtrk` 与 `gtrk render` 渲后质检的报告里从来没有换段备选——`gtrk-mg` 出片后 QC 闭环第 2 步「读它给的排序备选」无从读起，只能手找候选段。现在段内跳切与判为严重的过短镜头条目带 `alternatives`：同一 beat 里还没上轨的候选段（从工程登记的 `split/broll-plan.json` 取），每条给 `clip_id`、段区间与排序依据，按运动量 → 切点密度 → 分数排序，列前 3 段（多于 3 段另报总数）；候选缺运动或切点信号时 `alternatives_note` 注明口径受限。「未上轨」按段判：此前按 `clip_id` 判，一个 beat 只有一条素材、底下好几段的工程会被判成零备选。该 beat 的段都已上轨时给空列表并说明；没读到 plan 时不给列表、只给说明。判为严重的过短镜头此前不带 beat / 槽位坐标，现在带上，紧贴拼接处的极短镜头（一两帧）也能归到槽位（add-material-motion-signal 4.2）。
-
-- 新增：`gtrk tool image_purify --redraw` 图片去水印「重绘模式」——整张图交给图片编辑模型重新生成，铺满全图的半透明、网格水印也能去掉；与 `--purify-scope region` 同用时只替换框内。单独计价，运行前报价按重绘档；也可 `--params-json '{"purify_method":"redraw"}'`。不加 `--redraw` 时请求与之前逐字节相同。价格表里挂在父项下的分档（`tiers`，如重绘、区分说话人、云配音各音色档）现在也能按自己的 key 查到实时价格（link-add-image-purify-redraw-mode-cli）。
-- Skill 措辞订正（ClawHub 安全扫描指出的自相矛盾与告知缺口）：`gtrk-matrix` 的描述把「素材本体不上云」改准为视频本体不上云、选中上轨的图片会上云转运镜（正文早已写明）；`gtrk-narration` / `gtrk-food-recap` / `gtrk-vlog-docu` 的「不执行任何网络下载」收窄为不下载二创源片与主体素材，素材矩阵的 BGM / 空镜可按签名直链落地（与旅拍图纸同口径，此前与各自的 BGM 伴奏下载步骤字面冲突）；`gtrk-narration` 开工问询补一句内容离机告知（转写上传音轨、建索引上传抽帧图）；`gtrk-style-maker` 安装用户 skill 前先问装到哪些 Agent（缺省只装当前这个），适配器钉在 `skills@1.7.4`。下载禁令的射程同步写进解说链规格（fix-narration-download-ban-scope）。
-- `gtrk-oralcut` 剪完不再一律往下接力：只要剪辑工程、草稿或去停顿时，剪完停在交工，一句话交代下一步，说一声就接着做；看不出要不要成片时也先停。要成片、完整包装，或点名 B-roll、字卡、BGM、字幕之一时，照旧接着拆分镜派单。按 `/gtrk-talking-head` 跑粗剪时交回图纸，停在检查点①（adjust-oralcut-relay-by-request-scope）。
-- `gtrk-splitter` 派单后不再一律往下铺：直接调用只要拆分稿或派单时，落地后停下，一句话交代下一步（下一步会往工程里加 B-roll 候选轨），说一声就接着做；看不出要不要往成片做时也先停。要成片、点名要铺 B-roll 等，或是被 `/gtrk-oralcut` 按「要成片」接力过来时，照旧交棒铺 B-roll（adjust-splitter-relay-by-request-scope）。
-- `gtrk-mg` 出片后 QC 报出可换段的画面问题时，不再直接把你选定的 B-roll 换成排序第一的备选：先列出哪几处、拟换成哪段，以及连带影响（B-roll 重铺、受影响的 MG 颗粒重铺并覆盖手调、重渲可能计费），你同意后只换同意的那几处；改 plan 前留 `broll-plan.before-qc-<时间戳>.json` 与 `project.before-qc-<时间戳>.gtrk` 两份副本，拷回原文件名即回退、不再计费。事先说过「QC 报的问题直接换」也只免换段那一问，重铺（本地素材走云端编排计费）与重渲照旧先报预估、等你同意（fix-mg-qc-swap-needs-approval）。
-- `gtrk-mg` 出片后 QC 报出可换段的画面问题时，不再自己换 B-roll：转述缺陷后把换段交回 `gtrk-matrix`，先列拟换方案、等你同意、留副本这些规矩照旧。重铺完会先停下，请你在客户端看换过的那几处画面，以及上面的 MG 有没有挡住主体；你认可新底轨之后才回到 MG，没点名的颗粒一颗不重铺，手调保留。事先说过「QC 报的问题直接换」也不免这一次认可（adjust-mg-qc-swap-handoff-to-matrix）。
-- `gtrk-matrix` 出片 QC 换段时，换进来的段接过被替换段的排序分、占它原来的位置，重铺后只有你同意换的那几处变。此前照「原样搬」保留检索相似度，本地素材的 plan 会被段序校验整单拒绝；重排后再铺，同一 beat 的其余镜头会整体挪位，还可能挤进一段没上轨的备用段。原检索相似度记进与副本同一时间戳的 `split/qc-swap-<时间戳>.json`；换进段来自另一条素材、位置保不住时，会先告诉你哪几处跟着挪。另订正一处说法：钉选（`pinned`）只保证落得上，不保证落在第几槽（fix-qc-swap-slot-order）。
-- `gtrk-talking-head` 快速成片开剪前先停一次：有没有文稿、B-roll 从哪来、有没有屏录或第二机位（多条毛片时再加一问是不是同一期），一张表问完才跑粗剪——粗剪是这条链第一个计费的命令。请求里已经说清的不再问；目录里没看到文稿或屏录只作提示，不再当成答案；检查点①也不再补问这几项（fix-talking-head-kickoff-gate）。
-- 修：`gtrk oralcut` 两条不同目录下的同名毛片（如换卡后重复的 `C0001.MP4`）同一秒开剪时，后落的剪映草稿会整份覆盖先落的那份，且没有任何提示。现在开剪前就在剪映草稿根里占好草稿文件夹，撞名时后到的那份改叫 `…-2` 并提示，原草稿逐字节不动；同一目录下同名毛片同秒并行时，产物目录同样追加 `-2`。显式 `--out` 重跑同一目录时，产物目录照旧复用，剪映草稿另起 `-2`，不再覆盖可能已在剪映里改过的旧草稿。顺带修正草稿信息里的名称与位置：此前每份 oralcut 草稿都写成草稿根本身（名称为「JianyingPro Drafts」），现在是草稿自己的文件夹。`gtrk oralcut-result` 取回时落回原跑批占好的文件夹；`gtrk project export` 落草稿时也不再覆盖同名草稿（fix-oralcut-jianying-draft-collision）。
-- 修：`gtrk long2short` 与 `gtrk tool video_translate_dub` 的剪映草稿名不带时间戳，不同目录下的同名毛片哪怕先后跑，后跑的也会把先跑的草稿整份覆盖（long2short 两次条数不同时，一组草稿里还会混着两条毛片的片段），且没有提示。现在提交前就定下草稿名：同一条毛片在同一产物目录重跑，照旧覆盖上一次的草稿；撞上别的毛片的草稿时改落 `…-2`（long2short 整组改名，如 `talk-long2short-2_clip0`）并提示，原草稿逐字节不动。升级前跑过的产物目录第一次重跑会多出一份 `-2`。`gtrk project export` 的剪映草稿信息里的名称与位置也改正为草稿自己的文件夹（此前写成草稿根本身，名称为「JianyingPro Drafts」）（fix-long2short-dub-export-draft-collision）。
-- 修：`gtrk oralcut` 与 `gtrk long2short` 跑之前不打印价格——skill 一直写着「跑前 CLI 自动查实时价并打印」，实际这两条命令从来没接价格查询。现在抽音频之前查一次官网实时价格，往 stderr 打一行「计费提示」：单价，加上按原片时长算的本次预估积分（以服务端结算为准）；`--json` 结果与 `result.json` 增加 `pricing`。查不到时打「实时价格暂不可用，以服务端结算为准」，照常往下跑。两条命令新增 `--dry-run`：只探测并报价，不抽取、不上传、不计费、不建任何目录，适合长片或开工问询时先报价。`gtrk-oralcut`、`gtrk-long2short`、`gtrk-talking-head`、`gtrk-live-slicing`、`gtrk-narration` 的计费说明同步改写，`gtrk-live-slicing` 里写死的单价已删（fix-oralcut-long2short-price-line）。
-
-## 1.3.10（2026-10-26）
-
-- **改**：`gtrk tool video_canvas_adapt` 的 `--clip-start` / `--clip-end` 改为**秒**（可带小数），原为帧序号。服务端同步改为按秒截取（此前文档站写秒、后端按帧号截，传 `5` 只截到 5 帧）；区间为空或起点不小于视频时长时，服务端建单前即拒（错误码 6016，不扣费），CLI 对 `--clip-end` 不大于 `--clip-start` 也当场拦下。旧版 CLI 传的帧号会被当成秒（link-video-canvas-adapt-start-end-unit）。
-- 修：`gtrk tool image_classic_template --template-mode image`（只要拼图、不画标题）不传 `--main-title` 也被当场拦下。现在与服务端同口径：`--main-title` 只在封面模式（缺省 / `full` / `text`）必填，`image` 时可省、payload 不带标题。标题含 emoji 等封面字体画不出的字符，服务端建单前即拒（错误码 6046，不扣费），CLI 原样转述（fix-cover-title-font-coverage）。
-- 文档：README 补两种装法——通用 skills CLI（`npx skills add Gitruck/cli`）与 Claude Code 插件市场；`gtrk mg edit` 的计价说明同步为 6 积分/候选、前 200 个之后 8。
-
-## 1.3.8（2026-10-18）
-
-- 新增参考片精读：`gtrk media` 看片命令族（`probe` / `lines` / `frames` / `tile` / `tiles` / `boundaries` / `cut`，纯本地、不计费）。取帧网格下方标出源片秒、时码与正在念的字；`--around` 按台词定位；`boundaries` 给视觉变化候选（机械证据，不是镜头判定）。配套随包 skill `/gtrk-ref-reading`：按「改不改变讲者的位置、大小或可见区域」把参考片的每个视觉系统归到 MG 或合成风格；`/gtrk-style-maker` 的作品逆向可接视频参考。
-- 竖屏 / 方形工程也能做合成：合成舞台随工程画布。`gtrk composite scaffold` 按工程 `.gtrk` 的 `video_size` 写场景 `stage`（缺席按 1920×1080）；`build` 遇场景舞台与工程画布不一致逐颗报错，不缩放了事；机检、静帧与烘焙都按舞台尺寸出，烘焙产物尺寸与缓存身份随舞台；`--abi` 增 `stage:"canvas"`。客户端对竖屏合成的导出支持随下一版客户端发出。
-- 成片图纸缺省带精剪包装（合成层）：口播、解说、美食、配音、旅拍、Vlog 图纸的快速成片在字幕之后、出片之前做一轮合成（auto 选窗口不超过全片 25%，逐窗口复核、构建机检至多三轮，再铺轨烘焙），开工时告知一句；直播切片开工多问一句（缺省不做），长剪短跑前问一次。
-- 修：竖屏 / 方形工程的 MG 颗粒经 `gtrk render` / `gtrk project export` 预渲后被压扁（横胖竖扁、旋转被拉平）。颗粒预渲原先一律按 1280×720 开舞台，云端按「舞台 / 颗粒声明尺寸」非等比挂载；现在舞台按颗粒声明的 `data-width` / `data-height` 等比缩到短边 720（竖屏 1080×1920 → 720×1280，方形 → 720×720），`project export` 登记的颗粒 MOV 尺寸随之对齐。横屏 16:9 颗粒的舞台与缓存键不变，存量缓存照常命中；竖屏 / 方形颗粒升级后首次渲染会重烤一次（旧缓存是压扁的，不复用）。客户端导出剪映 / PR 的颗粒预渲需客户端同步跟进（fix-particle-capture-follows-declared-aspect）。
-- 修：`gtrk tool image_matting` 处理带 EXIF 方向标记的手机照片（如 Orientation=6），产物转了 90°。上传前先按显示方向摆正（原图不动，摆正件按原图指纹缓存在 `~/.gitruck/audio-cache/`）；无方向标记或非 JPEG 照旧原文件直传；缺 ffmpeg 等摆正失败时提示后按原像素上传（fix-image-matting-exif-orientation）。
-- `gtrk-mg` skill / 参考文档改准画幅口径：颗粒画幅须等于工程画布，竖屏可用；registry 中性块仍只有 1920×1080。
-- 修：竖屏 / 方形工程取文字模板（`gtrk mg fetch --source text`）恒得 1920×1080 颗粒，铺进去被拉伸。`--canvas` 原先在这条路上只被收下、不生效；现在按目标画幅编：派单模式缺省取工程 `.gtrk` 的 `video_size`（显式 `--canvas` 与工程不符当场拒，找不到工程文件时按 1920×1080 编并提示），独立模式按 `--canvas`。`gtrk mg compile` 新增 `--canvas`，重置颗粒时缺省沿用颗粒自己的画幅，`--remote` 同样把画幅交给服务端。横屏工程与不给 `--canvas` 时产物不变（fix-text-template-canvas-not-compiled）。
-- 修：画幅比例不对的 MG 颗粒（如竖屏工程里声明 1920×1080 的手写颗粒或旧颗粒）照样能铺进工程，渲染时被拉伸，全程不报错。`gtrk mg --project`（铺轨，含 `--lint-only`）与 `gtrk mg lint --dispatch / --project` 现在按工程 `.gtrk` 的 `video_size` 比对颗粒声明的比例：跨比例判 `1-canvas-match` 致命、不铺；同比例不同尺寸（如 4K 横屏工程里的 1920×1080 颗粒）照常放行，比例差 7% 以内视为同比例（DCI 4K 4096×2160 这类 17:9 工程里的 16:9 颗粒放行，接受 6.7% 横向拉伸）。工程缺 `.gtrk` 或 `video_size` 不合法时不比对并提示一句。裸 `gtrk mg lint <file>` 不变（fix-mg-lay-lint-reads-project-canvas）。
-- 修：竖屏 / 方形工程派单取 registry 中性块（`gtrk mg fetch --pick <块> --slot <beat> --project <dir>`）照样下载并落一颗 1920×1080 颗粒，要到 lint / 铺轨才被拦。现在按工程 `.gtrk` 的 `video_size` 比例判（同上，容差 7%）：比例不是 16:9 在下载前就拒、不落盘，报错指路 `--source text`（文字模板按工程画幅编）或栏目 skill。横屏 16:9 工程（含 4K）与 DCI 17:9 工程照取、产物不变；独立模式（`--as`）不读工程；找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示一句（fix-mg-fetch-registry-reads-project-canvas）。
-- 修：`gtrk composite bake --progress jsonl` 的取消恰好落在工作页打开出片台时，要约 24 秒才报 `cancelled` 并退出（浏览器已被结束，打开页面却仍按每轮 8 秒等到期限）；现在浏览器一退出即放弃，取消照常几秒内收尾。开烤前建工作目录那一段也有进度行了（原先这段可能超过 1 秒没有输出）；装渲染组件期间关闭 stdin，装完即按取消收尾（原先会漏掉、照常烤完）（add-composite-bake）。
-- 修：`gtrk matrix` 铺轨三处坑：
-  - `clip_id` 带来源层（`<beat>-<layer>-broll/bedfill/gapfill-…`），通用层与本地层同 beat 同序号不再撞名，`gtrk patch --clip` 可直接寻址；老工程重铺不受影响。
-  - 口播（fill 形态）工程里片段间 1–2 帧的缝、锚点前短于 1.2 秒的空档，在素材余量内并入相邻片段，不再闪黑；余量不够仍补黑，并逐段告警。
-  - `gtrk matrix --online` 收尾零候选时不再覆盖盘上已有的 plan（结果带 `plan_kept`）。
-- 合成层在英文口播片上更好用：
-  - 场景锚点的关键词照句子原文写即可：匹配时关键词与句子都忽略空格、标点与大小写，英文按整词（`"cold brew"` 直接写，`tea` 不再先命中 `teas`）；找不到时报错打印句子原文。
-  - `gtrk composite plan` 的「建议画面」识别英文的对照（unlike / but / instead of …）、列举（逗号列举，或转写不带标点时的一长串并列）、数字与分点；其他语种不做文字信号，审稿稿里写明。中文判定不变。
-  - `gtrk composite lay` 的回执改为当前出片口径：客户端（1.2.13 起）原生导出与剪映 / Pr 导出、`gtrk render`、`gtrk project export` 都先在本机烤合成，失败段按粗剪出画。
-  - `/gtrk-composite` 场景速查写明：工具箱只给舞台直接子元素定位，容器里的元素自己写 `position:absolute` 或加 `.abs`。
-- `gtrk composite lint` 新增 `unpositioned-offset`：容器里的元素写了 `left` / `top` 偏移、却没写 `position:absolute` 也没加 `.abs`（偏移不生效、挤成一列）时报出来，点名元素与容器。只在 lint 时检查，颗粒与烘焙缓存不变、已烤的颗粒不用重烤。
-
-## 1.3.7（2026-10-18）
-
-- 新增匿名使用统计：每条命令结束时记下命令名（注册名，不含任何参数）、成败、失败时的错误码或分类、耗时区间与调用方（终端或 agent 名称），用于了解命令热度、失败率与版本铺开情况。
-  - 不发参数、文件名、路径、内容、API Key、错误原文，也不带设备标识。
-  - 首次配置时（紧跟崩溃上报那一行）告知一次，默认开；`gtrk init --no-usage-stats`、`GITRUCK_USAGE_STATS=0` 或 `DO_NOT_TRACK=1` 可关，`gtrk doctor` 显示当前状态。
-  - 源码运行、单测与 `CI` 环境不发送。
-  - 只往 `~/.gitruck/usage-queue.jsonl` 追加一行，由后台进程发送，不拖慢命令；断网时留在本机最多 7 天，联网后补发。
-  - 隐私政策已同步更新（3.6「使用统计」）；说明见 `docs/reference.md`「使用统计与关闭方式」。
-
-## 1.3.6（2026-10-18）
-
-- `gtrk composite bake` 认合成槽位的用户覆盖 `crop` / `box` / `slip_ms`：校验与输入快照和服务端参考实现同口径，出片台按「颗粒几何 → box → crop → 适配 / 构图 → 形状圆角」绘制，ref 槽取帧加 `slip_ms`；`--abi` 新增 `overrides` 能力位。**客户端 1.2.13 起会写这些覆盖**，旧版 CLI 遇到带覆盖的合成按粗剪出片并提示升级。
-- 烘焙取消或出错时，满载机器上也能很快收尾：先提高被结束进程的优先级再结束，浏览器遗留子进程合并一次查询收掉，删除工作目录限时。
-
-## 1.3.5（2026-10-17）
-
-- 新增合成层命令族 `gtrk composite`：`plan` / `review` / `scaffold` / `shots` 把候选窗口写进 `struct_meta.composite`（客户端大纲 CP 行），支持整片铺满 / AI 判定 / 指定区间三种入口；`build` 把场景构建成自包含合成颗粒（随包工具箱 `composite-kit@1`）；`lint` 做静态校验加本机 Chrome / Edge 逐帧排版机检（穿模 / 线条穿画面 / 越界）；`lay` 按自产身份幂等铺进 beat 轨最上层。新增 `/gtrk-composite` skill，口播图纸挂可选合成步。
-- `gtrk composite bake`：用钉定版本的 chrome-headless-shell（`gtrk deps install --browser`）逐帧确定性出帧，按段并发、带缓存；`render` / `project export` 接管已烘焙的合成颗粒，`lint` 增帧纯度检查；支持 `--progress jsonl`，关闭 stdin 即取消（退出码 130），取消或出错时连同浏览器遗留子进程一起收掉。
-- 片段背景填充：`gtrk matrix` 的候选片段自带纯黑 `background_fill`，不再另铺黑底垫轨（`--black-bed` 回到旧形态）；`ai-drama lay` 的 AI 片段同样带黑底；`gtrk project background` 缺省改为逐片段写底板；本地 `gtrk render` 承接片段底板；`project export` 承接云端物化，先写出纯色图再落工程（剪映 / Pr 的上层轨模糊为真模糊，FCPXML / OTIO 降级为纯黑，铺满画布的片段不垫底）。**需配合客户端 1.2.12 起**，旧客户端不认片段底板。
-- `gtrk render` / `project export` 遇到工程里有客户端专属视觉状态（文字 / 贴纸 / 图形 / 特效、画布背景）时用人话提示一次，`--json` 恒带 `clientOnly`；`project export` 的 `clientVisualElementCount` 改按元素计数（原误按车道数）。
-- 外网 B-roll 缺省加入 Pexels 第五平台：解析可选署名字段（`uploader_url` / `license`），平台 `disabled` 不算降级；旧服务端不认 pexels 时提示加 `--platforms` 继续；未指定平台时先回看四平台旧续跑记录，不重复扣费；`source_urls` 接受 Pexels 视频页。**服务端开关打开前 Pexels 只报 `disabled`、不出候选。**
-- `matrix material --scope clip|image` 缺省附带 Pexels 补充结果：单列在 `--json` 顶层 `pexels_results`（另有 `pexels_status`、`counts.pexels`），不进 `results`、不算候选数，人读输出另起一段并在段首署名 Pexels；`--no-stock` 关闭，`audio` 不带。补充素材直接用 `download_url` 下载，`matrix fetch` 见 `pexels:` id 会整批拒绝。**需服务端 `add-pexels-stock-material-search` 上线并打开开关后才会出现补充结果**，老服务端下只提示一次、不报错。
-- `tool video_highlight` 分析代理升至 448p/4fps（libx264 CRF 28；本地代理缓存按编码参数区分，参数变更后自动重新生成），缺省附单声道低码率原声，新增 `--no-audio`；上传前本地自检，旧版 224 代理不再复用。**需云端先升级，旧云端会以「短边必须224」拒绝新代理。**
-- MAD 缓存目录不可写时给出权限提示与诊断类别。
-- 交工文案补 Premiere 自动重链提醒：正本在 `gtrk-oralcut`「回给用户」的 PR / FCP 条，`long2short` / `live-slicing` / `tools` 引用同一条。
-
-## 1.3.4（2026-10-14）
-
-> 版本段补录于 2026-10-17：发版时这几条留在「未发布」里。归属按 npm 记录的 `gitHead`（1.3.4 `144ed89`）与写入这些条目的提交时间判定，未逐条核对包体。
-
-- `long2short --camera-move`：云端按与精剪同一套调度把推 / 拉镜头写成主轨片段的 `clip_keyframes.scale_x / scale_y`，客户端与剪映可见可改；`clips.md` 标「运镜 N 处」，未能加运镜的切片单列；`/gtrk-live-slicing` 开工问询变五问（⑤ 运镜，缺省不加）。需配合服务端 `add-long2short-for-cli-camera-move` 与客户端承接 `clip_keyframes` 的版本。
-- `gtrk patch` 的 trim / split / seal / snap 同步维护 `clip_keyframes`（入点平移、越界截断补插值端点、切分两段各自合法），写前校验拒绝任何非法关键帧并点名 clip 与通道；`audio tighten` 遇带音量关键帧的音频片段拒绝；本地 `gtrk render` 读到关键帧时提示按静态画面出片。
-- `gtrk project background --blur [--intensity n] | --color #RRGGBB | --clear`：写客户端画布背景 `struct_meta.client_background`（零计费、不访问云端），横屏源进竖屏画布时用模糊底替代黑边；`/gtrk-live-slicing` 对横竖互转的入选切片缺省加模糊底。剪映 / PR 与本地 `gtrk render` 不带该设置。
-- `long2short --speed-factor 0.5–2.0`：整体调速（保音高）写进逐 clip 工程，客户端 / 剪映 / PR 都按倍率播放，云端不渲染、不加价；`clips.md` 标注倍率，未能变速的 clip 单列。需配合服务端 `add-long2short-for-cli-speed` 上线。
-- `long2short` 产物根新增整片转写 `json/transcript.json`，可用 `gtrk subtitle lay --gtrk … --transcript …` 给任一 clip 上客户端字幕轨；字幕文件来源时 `clips.md` 提示词级时间为近似值。需配合服务端 `add-long2short-for-cli-transcript` 上线，老服务端下不报错。
-- `subtitle lay --language <code>`：指定云端拆行语种（缺省仍为 zh-CN），非中文源上字幕不再按中文断句。
-- `/gtrk-live-slicing` 选题确认后对入选切片缺省字幕上轨；调速只在用户主动要求时加。
-
-## 1.3.3（2026-10-08）
-
-> 版本段补录于 2026-10-17。npm 记录的 `gitHead` 为 `13d43e9`，但同步版本号的提交 `2f5c68d` 晚于发布约 4 分钟，推断与 1.2.7 一样是从带未提交改动的工作区发的；以下按该提交说明补记，未核包体。
-
-- 完善 Vlog 分段组装、旁白归轨和颗粒检查。
-
-## 1.3.2（2026-10-08）
-
-- 本地视觉理解增加当前 Agent 审阅交接：`matrix describe --prepare/--review`，已完成的本地判断不调用豆包，明确无法完成的条目按需补齐。
-- stable 长场景保留时间覆盖，素材概览同步多点抽帧；支持对指定源时间窗加密理解，检索帧预算避免同一密集素材独占。
-
-## 1.3.0（2026-09-28）
-
-- 视频去水印不再默认 FFmpeg：Agent 必须在处理前说明快速模糊与慢速内容修复的效果代价，等待用户选模式；`purify run/apply`、人工框和 `tool video_purify` 缺少显式模式时在上传前停止。仅检测、编辑和空清单不受影响；旧记录未建处理单时需补选模式，已建单继续原任务。失败后不得擅自改用快速或本地 FFmpeg。
-
-- `tool --batch` 补齐整批费用预估：标准价/超额价积分与额度包单位数分别汇总，按分钟收费先本地探时长，逐任务取整后求和；跳过项不计费、不探测。价格或计量不可用时明确说明无法预估。
-
-- `ai-drama lay` 成功回轨后提示先显式指定口播音频运行 `patch snap --dry-run` 检查，再执行吸附并用 `patch seal` 补缝；只提示，不自动编辑。
-
-- 清理随包 skills、共享 Agent 规则、GSAP handoff 契约和双语参考文档中的历史叙事；当前执行规则不变，GSAP 证据保留在维护者附录。
-
-## 1.2.13（2026-09-22，AI 漫剧工具批次补记）
-
-> npm 发布时点为 2026-09-22 08:26:53 UTC。本节补记这批已实现能力；不表示其全部 OpenSpec 已归档。后续音轨识别、素材内容寻址和镜头锚定仍在独立待办中。
-
-- `ai-drama pack` 从本地镜头与派单构建 return-v1 包，实测尺寸、帧率、时长，缺镜或校验失败不落包；`swap` 验证结构等价后替换并默认备份，工程文件不改。
-- `patch snap` 按音频能量定位切点，支持干跑和诊断；当前自动选音轨仍有已登记缺陷，含 BGM 的工程应显式给 `--audio`。`patch seal` 按指定轨和阈值补小缝，重叠及超阈值间隙只报，推荐顺序为 snap → seal。
-- `patch --json` 输出单行 JSON，补齐 `ok`、`dry_run`、`project`、`invariants`；旧 `gtrk` 与 `preexisting` 别名保留。依赖多行缩进输出的外部脚本请改为逐行解析完整 JSON。工程级操作补齐 `frames:null`、`before` 与参数回执。
-- 投影选轨加入口播素材匹配；视频主轨有画面却不含目标口播素材时可回退音轨，避免配音工程被额外视频轨阻断。
-- `mg` / `split` 增加覆盖区间与空档读数，以最长空档提示，不因颗粒稀疏阻断工作流。
-- `doctor --project` 汇总素材、轨道和工程结构检查；只对视觉底轨提示缝隙，缺省环境体检入口不变。
-- `qc contact-sheet` 生成带镜号和时长标签的分页联络表，标签与源文件保持绑定。
-- `tool --batch` 增加受限并发、已有产物跳过、失败汇总与 JSONL 明细；本地工具默认串行。该发布版的计费提示仅提供批次条数和单价；整批总费用估算已在上方「未发布」条目补齐。
-
-## 1.2.11（2026-09-19）
-
-### 改：`gtrk transcript --json` 带字级时码，成片字幕时间按语音贴（adjust-transcript-json-word-level）
-
-`--json` 现在按**成片消费面**索取字级识别：产出的 `transcript.json` 每句多一份 `words[]`（`{w, st, ed}`，秒、三位小数、不含标点）。下游 `gtrk subtitle lay` 与客户端一键上字幕据此把每一行的起止贴到真实语音上——此前没有字级时码，一句拆成多行时只能按字数在句子区间里摊分，实测 125 个行边界里偏差中位 148ms、最大 2.6s（一句话快说完了字幕才上来）。升级后同一份语料 235 条字幕起点与首字时码误差恒为 0，末条也不再拖到片尾静音。
-
-**不带 `--json` 的产物形态没变**：只出 Markdown 文字稿时仍是句级（Markdown 本来也不承载字级时码），响应 `word_count` 为 0 是正常的——不过这一版起它走的是另一条引擎腿，见下面 `switch-transcript-to-selfhosted-asr` 那条。`gtrk project init --transcript` 透传 `words[]`，畸形条目跳过并计数。
-
-### 改：一键上字幕不再吞掉完整的短句（adjust-caption-keep-complete-sentence）
-
-最小可读时长过滤（0.8s）以前对「被剪掉一半的残片」和「本来就短的完整句」一视同仁，于是「这不是比喻」「这不是隐喻」这类 0.7 秒的强调句被整条删掉。现在**只有残片**才受这条过滤，完整句无论多短都保留——后一步的空隙桥接本来就能把它延到下一行起点（实测这两句桥接后各 1.08s / 1.24s，与手工修的值一致）。`--json` 报表里 `droppedShort` 的语义随之收窄为「丢掉的残片数」。
-
-### 改：字幕里的感叹号也换成空格，问号保留（adjust-subtitle-punctuation-exclamation-to-space）
-
-落轨字幕的标点清洗扩表：中英**感叹号**（`！` `!`）并入「换成空格」，中英**问号**（`？` `?`）明确保留。逗号句号照旧换空格，小数 `3.5`、千分位 `1,000`、域名 `example.com`、缩写 `U.S.` 照旧不误伤。`--keep-punctuation` 仍可整体关掉清洗。
-
-> 这条以前之所以没人提，是因为语音识别一直把句读剥光了、字幕里根本见不到感叹号；识别侧改成保留句读之后它才第一次出现。
-
-### 改：不带 `--json` 的 `gtrk transcript` 改走自部署识别引擎（switch-transcript-to-selfhosted-asr）
-
-`word_level` 在服务端决定的是**引擎**而不是一个参数：要字级走字级腿（当前是外部厂商 ASR），不要就走
-自部署引擎 + 服务端纠错。CLI 现在按**产物消费面**分流——只出 Markdown 文字稿（不带 `--json`）时传
-`false`，走自部署腿当小工具用；带 `--json` 时传 `true`，因为 `transcript.json` 的 `words[]` 要承载字级
-时码（见上一条）。口径对所有语种一致，**CLI 不按语种挑引擎**：那要在端侧手抄一份「哪些码厂商引擎更好」
-的表，而正本在服务端引擎表里，手抄的那份不会报错，只会在某天悄悄分叉；粤语的质量取舍由服务端语种
-白名单承接。
-
-### 修：旁路记账写不进去，不再把已经挣到的结果一起带走（fix-sidecar-write-failure-kills-command）
-
-生产报错 `base_error#202`（外部客户）：文件已经传完，去写那条约 1 KB 的上传记账时 `EPERM` 一抛，
-**第三步挣来的 `fileId` 跟着陪葬**，整条命令死在第五步；客户重试时缓存里没那条记录，整个文件再传一遍。
-而同一个文件的读侧一直写着「缓存损坏不致命，当空处理」——坏了能忍，写不进去却要命。
-
-现在四处**旁路记账**——上传记账、分片续传断点、BGM 使用历史、MG 例外账本——写失败只打一行 WARN，
-并当场说清后果（如「下次同一个文件会重新上传」「断线后续不上，得从头传」），命令照常把结果交出去。
-
-**交付物类写入不在此列**：`gtrk init` 存 API Key、`gtrk skills` 登记栏目配置都是用户按下的动作，
-写失败照旧抛错，只把 Node 的原文换成人话（多半是文件正被别的程序占着，或者目录不让写）。
-判据是**调用语境**不是写入函数——同一个写函数在一处是交付物、在另一处是旁路记账，是常态。
-
-## 1.2.10（2026-09-18）
-
-### 加：`gtrk ai-drama lay` 可按工作台项目 id 取包（add-desk-project-resolution）
-
-新增 `--desk-project <id>`（可重复，与 `--package` 混用、按路径去重）：用户手上有的是 AI Drama Desk 的**项目 id**，命令自己解析成导出包目录，走两条确定性路径——服务可达就问 `GET /api/v1/projects/<id>` 取 `exportDir`（**字段缺席即判「尚未导出」**，不据 id 拼路径去试）；服务没起就读 `~/.gitruck/ai-drama-desk.json` 的 `instances[]` 逐条试。零命中会列出已查过哪些数据根（源码部署与打包部署的数据根不同，找不到多半是「在另一个部署里」），多命中报歧义不猜，两条都不通就报错并给出路。**全程不做任何目录遍历**——解析层有一条反向自证用例锁住这点。解析出的包走的仍是既有那条校验与写回路径，清单校验、不完整包整批拒收、路径穿越拒收、幂等与手调保护一律不放宽；`--json` 每个包多标 `via`（按 id / 按路径）与 `resolved_via`（服务 / 落脚点）。
-
-### 改：`gtrk render` 颗粒缓存键补交付配方版本，与客户端重新互通（fix-particle-cache-identity-parity）
-
-颗粒 qtrle 缓存的内容寻址键加回 `recipe`（qtrle 交付配方版本，客户端 2026-09-13 起已带、CLI 未跟），键序与客户端逐字节对齐；两端各钉一组写死 hex 的金样，任一端改公式该端先红。此前客户端在工程目录烤好的颗粒 `gtrk render` 一颗都不命中、全部重新云渲计费。升级后对客户端已烤颗粒全命中、零新任务；代价是升级后第一次 `gtrk render` 会把 CLI 自己此前烤的旧键产物 miss 一次（旧文件不删、不回退读取）。身份里的 `duration` 一律取 `.gtrk` 契约投影值原值，两端同源（客户端侧同批调整）。
-
-## 1.2.9（2026-09-18）
-
-### 加：推荐目录收一方 MG 排版技法族（add-first-party-technique-catalog-entry）
-
-`gtrk skills recommend` 多一个场景 `technique`：同合云自己的排版技法族（首个技法 doc-reveal：文献页叠放 / 发牌 / 局部强调）。技法不是栏目 MG 生产 skill——`gtrk skills add` 装完登记为 `routing:none` 且 `status: "first-party"`，由 agent 在 MG 步按槽位取用；显式 `--produces` 绑车道会照登记并告警一行。人读输出对一方条目印「一方维护」不印 star；`--json` 每条多 `origin`。`/gtrk-mg` 手册在「无匹配」与「有匹配缺省不用」两处各加一句指路，公约 §三‴ 补一方口径。
-
-### 改：`gtrk mg lint` 补体积规则（add-particle-html-size-lint）
-
-颗粒 HTML 超过 2,000,000 字符（客户端颗粒运行时的硬上限，超了在客户端永远加载不出来）现在判致命 `4-html-size`：铺轨跳过该 beat、`mg render` 不提交零计费；命中即短路，其余检查项不跑。超过 500,000 字符给非致命 `4-html-size-heavy`（客户端每次 seek 整份快照回传，体积直接决定预览帧率）。
-报错点名最大的一段 data: URI（类型、字符数、解码字节数、落点），给「按实际显示尺寸裁剪缩放后再内嵌」的改法；没有 data: URI 的超限如实归因为标记与脚本本身。契约 `contracts/gsap-emit-v1.md` 铁律 4 增补⑤，`gtrk-mg` 图纸 lint 节同步。
-
-### 修：环境类失败在端侧落成人话，不再炸到顶层当崩溃（三条生产报错归一件）
-
-读不动的 JSON 与写不进去的文件，此前把 Node 的原始异常直接抛到顶层、走崩溃上报。现在：
-
-- **读**：`.gtrk 工程` / `派单清单` / `拆分稿` / `AI 导出清单` 等按名报错，并附一句诊断——
-  文件是空的（产它的那一步没写成）/ 正文里夹着 `U+FEFF`（两份文本被直接拼在了一起）/ 有 NUL 字节
-  （多半被存成了 UTF-16）/ 有解不开的字节（编码不是 UTF-8）/ 就是不合法 JSON，各给各的出路。
-- **写**：目标被别的程序占着时退避重试（5 次、约 750 ms 窗口；**不做无上限重试**——编辑器开着那个
-  文件可以开一整天，无上限只会把「报错」换成「卡死」），仍失败则保留内容完整的 `.tmp` 并告诉你
-  可以直接改名收走；跨卷改不了名、磁盘没空间各给各的出路。写成功后顺手清掉够老的同目标 temp 残骸。
-
-## 1.2.8（2026-09-17）
-
-### 加：视频译制配音 `video_translate_dub`（link-video-translate-dub-cli）
-
-`gtrk tool video_translate_dub <视频或音频> --language <源语种> --translate-language <目标语种> --speaker <clone 或音色代号>`：
-把原片里的话翻译成目标语种，用所选音色或克隆原片说话人的声音逐句重新配音，画面保持原样（不做口型同步）。
-单条最长 120 分钟，超了上传前直接拒；按分钟计费，运行前实时查价。
-可选 `--ref <参考音频或视频>`（仅 `clone` 有意义，克隆别人的声音须先取得本人同意）、`--ref-lang`、`--no-keep-bgm`、`--fit-policy`、
-`--speed-band <最小,最大>`、`--subtitle-mode`、`--subtitle-type`、`--project-formats <逗号分隔>`；各参数的合法取值以服务端为准，CLI 不内置枚举。
-
-产物：`<输入名>-dub.mp4`（音频输入为 `-dub.mp3`）、`dub.wav`、`bgm.wav` 与 `base.mp4`（有则落）、字幕 `.srt`、逐句对齐记录 `transcript.json`、
-工程文件按格式分目录（`gtrk/`、`jianying/` …），`result-output.json` 为配音对齐报告。
-提交时自动带上原片与产物目录的本机路径，各格式工程里的素材都指向本机文件，打开即用。要剪映草稿加 `--project-formats gtrk,jianying`：草稿两件套齐全后自动放进剪映草稿目录（新增 `--jianying-draft-dir`，缺省读 `gtrk init` 配置或自动探测，与 `gtrk oralcut` 一致）；CapCut 草稿留在产物目录。服务端尚未升级时工程里仍是占位名、剪映草稿缺 meta，终端会各打一行提示。
-字幕、逐句记录、工程文件等附带产物偶尔缺项时只打一行 WARN，任务照常判成功。
-
-### 加：工具族通用「附加输入文件」
-
-工具可声明除主输入之外的本地文件参数（首个使用者是上面的 `--ref`）：任何上传之前先本地校验文件存在与扩展名，
-主输入之后上传，`--reupload` 同样生效，`task.json` 记录 `extraInputs`；没声明的工具行为与面包屑不变。
-产物文件名带子目录时自动建父目录。
-
-### 改：共享参数说明与超时长报错
-
-`--language` / `--translate-language` / `--speaker` / `--subtitle-type` 的说明改为不绑定单一工具的表述，参数名不变。
-视频类工具输入超时长的报错改为「输入时长超过 N 分钟上限，请先裁剪或分段后再提交」。
-
-### 文档：`gtrk-travel-recap` 图纸的写稿语速改读栏目 catalog
-
-随包旅拍图纸不再内嵌语速常量，改读栏目 catalog 的两个键；档案登记 `narrator` 五项齐备时回校样本 §3.5。
-
-## 1.2.7（2026-09-16）
-
-### 加：渲染字体改从同合云统一字体库装（link-cloud-font-library）
-
-`gtrk deps install` 的字体这一步改走**同合云统一字体库**（与客户端同源、同一份服务端投影，
-所以共享目录里同款字体只存一份），不再跟着 ffmpeg 分发清单里那几项走。新增
-`--font-family <family...>`：按 `font_id` 或中英族名点名装、可多个；缺省只装字幕字体
-`sourcehansanscn-bold.otf`。清单里没有 `sha256` 的字体**拒绝安装**（强校验不可降级）。
-
-`gtrk deps status` 多列一行字体库（地址、schema、族数 / 款数、生成时间）。字体清单与 ffmpeg 分发
-manifest 是**两条链路、各拉各的**，取不到只少列这一段，不影响上面的 ffmpeg 信息。
-
-### 修：固定名面包屑覆盖不再静默，`gtrk mad` 跟修产物目录防撞（fix-tool-outdir-collision）
-
-两处：
-
-- **面包屑覆盖**：`task.json` / `result.json` / `result-output.json` 三个**固定名**面包屑按固定名被
-  下游消费，撞名时 MUST NOT 改名——但此前也一声不吭。现在打一条 WARN 点名会被覆盖的是哪几个，
-  并说清代价（上一次的 `task_id` 与产物清单不可回溯，产物文件本身不受影响、撞名会自动改名保留），
-  末了提醒「要并行跑多条，给每条一个独立的 `--out`」。
-- **`gtrk mad` 防撞**：产物目录从 `mkdir(recursive:true)`（已存在即**静默复用**）改成与 `gtrk tool`
-  族共用同一份原子探路实现——同一秒起两条 mad，后者的 `mad.jsx` 会盖掉前者。`--out` 是用户明示的
-  落点，仍不替他改名。顺带把 mad 自己那份逐字等价的时间戳实现收敛掉。
-
-### 改：「AI 再现」全面改叫「AI 情景动画」
-
-随包 `README` / `AGENT.md` / 各 skill 图纸里的叫法统一换掉；车道标识 `AI_DRAMA` 与命令面不变。
-
-### 文档：升级 CLI 不会自动刷新已装的 skill（fix-skill-install-staleness）
-
-`npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，各 Agent 目录下那份 skill 仍是**上次装进去的快照**
-——agent 会照着旧口径干活，**而且不报错**。README 补上这条口径与修法：走 `gtrk upgrade`（升 CLI +
-刷 skill）或单独 `gtrk skills install`；自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」。
-`AGENT.md` 同步补上 agent 侧纪律：见到那条 stderr 提示 MUST 转告用户，MUST NOT 当噪音忽略。
-
-## 1.2.6（2026-09-16）
-
-### 加：MG 槽位视觉职能四档 + 生产侧硬闸 + 排产顺序闸（gate-mg-visual-job）
-
-派单里每个 MG 槽位的 `handoff.visual_job` 转为必填，四档 `statement` / `relation` / `data` / `decor`
-（判据是「这段的意思里有没有第二个东西与它并置」，**与用不用文字无关**）；`relation` 还须填
-`visual_brief`。全片一个关系型视觉都没声明时，顶层须具名 `mg_visual_job_note` 说明为什么通篇只有单一
-陈述（纯字卡包装的口播片是合法形态，本条只要求它是个有意识的选择）。派单阶段**不得引用具体模板 id**
-——判「这段要什么」的那一步不该看见模板库。
-
-两道闸落在生产侧：
-
-- **生产侧硬闸**：`relation` / `data` 槽位交上来一颗文字模板库的颗粒（内嵌 `v:"text-v0"` 的 IR）即拒。
-  被禁的是「从库里捞一个套上」，**不是「用文字」**——用排版画关系的手写颗粒（并置两列 + 破折号那种）
-  正是要保住的东西，本条不拦它。
-- **排产顺序闸**：本片还有 `relation` / `data` 槽位没产出源 HTML 时，`gtrk mg fetch --source text` 的
-  派单模式**拒绝执行**。理由是防锚定：连着看过十几颗现成品之后，「MG 该长什么样」的默认印象已被那批
-  东西定住，这时再自由发挥，发挥出来的多半还是它们的形状——顺序本身就是一道隔离。
-
-两道闸各留一次性例外，**必须同时给理由**、随工程留痕（铺轨侧写 `struct_meta.mg.exceptions`，取块侧写
-`<工程>/split/mg-exceptions.json`）：`--allow-text-for-relation <beatId> --why "<一句话>"` 与
-`--allow-template-first --why "<一句话>"`。它们 MUST NOT 被做成常开配置。
-
-### 加：`gtrk mg compile` 本地编译先校验再编译（fix-local-ir-compile-skips-validation）
-
-本地编译这条路此前**零校验**：`transparent:false`、`canvas:1280x720@60fps` 这类服务端会当场拒的 IR，
-本地一律 `exit 0` 落盘——于是「本地能编出来」不再蕴含「这份 IR 合法」。2026-09-15 实测有三颗带
-`transparent:false` 内嵌 IR 的颗粒，就是从这个口子溜进 `.gtrk` 的。
-
-现在编译前先跑一遍校验器，报错**指名到键**（`layers[2].font.size 须 8–600` 这种）。位置必须在编译之前：
-编译器对某些非法输入会抛它自己的异常（如未定义颜色引用），那句话没有路径、用户拿不到定位。
-
-### 加：`canvas.scrim` 压板层——半透明压板不再冒充实心底（link-text-ir-scrim-opaque）
-
-文字模板 IR 新增 `canvas.scrim`（压暗底轨用的半透明矩形：`fill` 必填且**必须带 alpha**，可选
-`rect` / `radius`），与 `canvas.bg` 互斥——要满幅实心底用 `bg`，要压暗用 `scrim`；写了 `scrim` 的颗粒
-`transparent` 仍须 `true`。
-
-此前压板恰好落在「根下第一个渲染子层」这个取样点上，而 `bgOf` 只认 `transparent`/`none`/`rgba(...,0)`
-三种透明形态，于是 `#000000A6` 被判成非透明——**一块压板被登记成合格实心底**，满屏槽位据此过闸，
-出片时底轨从压板后面透出来。取样时现在跳过压板层，继续往下找真正的全幅子层。
-
-同批补上一处漏接：`gtrk mg lint --dispatch`（用户检查已铺颗粒最自然的那条命令）此前**一个 category
-都不读**——`--category` 在命令面注册着、派单里也写着，满屏闸却只活在 `mg fetch` 那条路上，
-「取块时合规、后来颗粒被换掉」这条最常见的失守路径完全没人看。
-
-### 改：放开画幅硬闸，文字模板按工程画幅现编（link-aspect-agnostic-layout）
-
-`gtrk mg fetch` 与 `gtrk mg compile` 的 `--canvas` 从「只收 1920×1080」改成「须为正整数」：引擎早已按颗粒声明尺寸挂载缩放，原来那条硬闸拦的
-是一个**不存在的失败形态**；文字模板的 IR 住在 1920 参考系、画幅是编译入参，按目标画幅现编即可。
-
-**registry 中性块仍只收 1920×1080**：那批是手写 HTML、几何写死在块里，取块改写不会跟着缩，
-给它别的画幅出来就是错的。lint 相应改成按工程画幅对拍——颗粒声明的画幅与工程不符时点名
-「挂载走的是**非等比** `scale(w/dw, h/dh)`，跨比例会把颗粒拉伸变形（不是加黑边），而两边都不报错」，
-手写颗粒请按工程画幅重做。
-
-### 加：文字模板候选态可按分类过滤（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`。
-
-### 文档：`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` 按列校验，防止文案被改回。
-
-## 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）
-
-真机上这条命令**从来没成功过**：
-
-```bash
-gtrk mg fetch --source text --pick tfx-type-terminal --slot B05 --project <工程>
-# → composition_id "B05" / lint 致命 1-cid-expect / 不落盘
-```
-
-两处不对。① `--slot` 收的是 beat id（`B05`），而派单里的 `composition_id` 是
-`<工程slug>-<beatId>`（`t07-B05`）——铺轨与 `mg lint --dispatch` 都按后者对账，旧实现却把前者
-直接当 id 用，`dispatch.json` 一个字没读。② 取到的模板 HTML 原样送 lint，而模板内的
-`data-composition-id` 恒为模板 id、期望 id 恒为 `<slug>-<beat>`，两者永远不等 ⇒ 必然致命。
-
-文字模板是 `ir` 态、**不能直改 HTML**（改一字节就掉成 `detached`，云端再也调不动），
-所以钉 id 的合法路径只有一条：改内嵌 IR → 走 `mg compile` 同一条本地编译链重编。现在命令替你做：
-
-- 派单模式的 `composition_id` / 坑位包络 / `category` 全部取自 `dispatch.mg` 那条（与中性块
-  `registry` 路共用同一份 `matchSlot`，两条路不再各写一份）；
-- 内嵌 IR 的 `id` 钉成期望 composition_id，`canvas.duration` 钉到**坑位包络 + 0.3s 余量**
-  （铁律⑦），且**原本贴在模板末尾的层跟着钉**——不钉的话坑位长于模板时，那些层会在原时长处
-  被隐藏，后半段元素凭空消失；
-- 重编产物自证仍须是 `ir` 态，否则报错零落盘；`id` 与时长都没改时**原字节落盘**，不重编。
-
-独立模式同病一并修：`--as` 过去只改文件名、不改颗粒内部 id；`--duration` 在 text 路被**静默忽略**
-（命令面照收、代码里根本没这个字段）。现在 `--as` 改写 IR `id`、`--duration` 钉 `canvas.duration`，
-且 `--slot` 与 `--duration` **互斥**（派单的包络由 `track_st` / `track_ed` 定，显式给时长会与它打架）。
-
-另两条顺带：镜像块自身不是 `ir` 态时**报错零落盘**（那是发布事故，静默落一颗改不动的颗粒，
-用户要到 `mg edit` 被拒才发现）；派单 `category` 透传给 lint，槽位派 `fullscreen` 而模板是透明叠加时
-报**非致命**的 `x-category-opaque`——不拦落盘，但提醒你给这颗补一层全幅实心底。
-
-## 1.2.4（2026-09-14）
-
-### `gtrk mg` 文字模板三口：`fetch --source text` / `compile` / `edit`（add-text-template-source）
-
-同合云自己 clean-room 重写的文字特效模板库进了 CLI。与中性块 `registry` 那条路**刻意不同**：
-文字模板 MUST NOT 走机械改写——中性块来自第三方、要替字体换色板才合规；文字模板的块**自带 IR**，
-一旦直接改 HTML 字节，它就从 `ir` 态掉成 `detached`，云端再也调不动。改内容只有两条路：
-
-```bash
-gtrk mg fetch --source text 打字机                       # 候选态：只列不取（--offline 用本地目录）
-gtrk mg fetch --source text --pick tfx-title-typeline    # 取块态：三源择优取，逐字节校 sha256
-gtrk mg compile ./mg-fetch/tfx-title-typeline.ir.json    # 改完 IR 重编译（L0，本地跑、0 积分、零请求）
-gtrk mg edit ./mg-fetch/xxx.html --say "打字机快一倍，副标改成青色" --n 3   # 云端改写（2 积分/候选）
-```
-
-`--n` 只收 1 或 3，**它就是计费单位数**。改写被拒绝（模型说「词表里做不到」）同样计费——
-那是为了不让「拒绝」变成免费试探，但拒绝理由会原文给你，不会只丢一句失败。
-
-### 文字模板目录：随包兜底 + 远端择新 + 8 个人话分类（add-text-template-source / add-text-template-category）
-
-目录走「远端择新、随包兜底」：扩批是纯写 IR 的轮次，不该被 CLI 发版卡住，所以**随包那份会过期，
-这是设计**——运行时按 `version` 择新，随包只在三源都不可达时顶上。本版随包 **v2026-09-14.11 / 103 件**。
-
-分类从 37 个收成 8 个：`F`/`M`/`R` 是内部来源编号（喵影家族 / MAD 图鉴技法号 / 参考视频），
-用户看不懂，而且 93 件摊出 37 个分类里有 16 个只有 1 件。改由**目录下发** `category`
-（快照脚本算，两端只读不算——各算一份会漂且漂了不报错），判据是规则不是手工名单：
-满 7 件才配独立、其余进「其他」、总数 ≤8。`family` 保留供溯源、仍进检索干草堆
-（老用户按 F02 搜不该搜不到）。
-
-### IR 编译默认走本地，`--remote` 留给排查与对拍（move-text-ir-compiler-to-client）
-
-`gtrk mg compile` 此前每次都要打一趟服务端。现在 L0 编译在本地跑完：**零请求、零延迟、断网可用**。
-TS 编译器是 Python 正本的第二实现，靠一道**逐字节等价闸**钉住（全量金样两侧逐字节相同，
-本版 103/103）。
-
-⚠️ `--remote` **MUST NOT 下线**：它是等价闸的参照系，也是真机上排查「本地编出来的和服务端一样吗」
-时手上唯一的另一条路。
-
-### IR 词表 v0.2：八项新表达 + 片段引用槽位（add-text-ir-vocabulary-v02）
-
-`mask` 收数组（多条并存）/ `feather` 收两元数组（不等量羽化）/ `animTarget:"inner"`（蒙版钉死、
-内容在后面滚）/ `repeatText` / `charRoll`（逐字滚码落定）/ `sweep`（扫光）/ `shape.glow` /
-`anim` 新增 `skx`·`sky`，外加 **`runs[].slot`**。
-
-`runs[].slot` 修的是一个缺口：`brush-title` / `caption-emoji-arrow` / `caption-keyword` 三颗的文字
-写在 `runs[].t` 字面量里，**此前没有任何字段能改**。现在它们的槽位回来了。
-
-⚠️ **`blur` 通道判否，且这是有射程的口径**：`filter: blur()` 被补间驱动正是 `gtrk mg lint` 的
-`c-filter-animated` 所指、r69 真渲实测 **+36.2%** 的最贵形态。往后任何要 `filter` 的通道
-（`drop-shadow` / `saturate` …）一律先找零卷积等价物，真找不到再单独拍板。
-
-### `gtrk tool mad`：技法点名 `--technique` 与目录检索 `--search`
-
-一键剪 MAD 此前只能让它自己挑技法。现在可以点名，也可以先查目录看有哪些
-（语义匹配仍留给 Agent，命令面只做目录检索）。
-
-### 其他
-
-- `gtrk mg lint`：内嵌 IR 的**两代载体都认**——换载体那次产物字节全变，只认新的会把线上已发的颗粒
-  整批判成 `detached`。
-
-## 1.2.3（2026-09-13）
-
-> ℹ️ **本节是补写的**。1.2.3 当时发到了 npm 却没进更新日志（包里那份 CHANGELOG 顶到 1.2.2 为止）。
-> 补写口径是**发布产物实证**、不是按提交时间猜：拉 `@gitruck/cli@1.2.3` 的 tarball 逐项 grep，
-> 确认 `text-template` / `compileIrBody` / `--technique` **一个都不在**（同时 `pip` 42 处、
-> `subtitle_line_split` 3 处命中，证明探针本身能响）——文字模板那批全部落在 1.2.4。
-
-### `gtrk mg lint`：新增非致命哨兵 `x-soft-alpha`（fix-alpha-delivery-discipline）
-
-颗粒里只要有**半透明面积**（`rgba`/`hsla` 半透明色、`#RRGGBBAA`、渐变到 `transparent`、
-带 blur 的 `text-shadow`/`box-shadow`、静态 `opacity<1`），lint 会提醒一句。
-
-**恒非致命、不要求改写**——半透明本身完全合法。它提醒的是交付纪律：剪映的 qtrle 交付依赖渲染管线
-在编码前**预乘 alpha**（剪映按预乘合成，直通 alpha 的软边会塌成实心，2026-09-14 真机实证）。
-所以**剪映路径的真机验收 MUST 用这颗颗粒本身验，MUST NOT 拿实心颗粒代验**——实心颗粒对预乘错配
-结构性失明，验了也是白验。
-
-⚠️ 颗粒与 CLI **MUST NOT 自行预乘**，那会双重压暗。预乘是渲染管线那一侧的事。
-
-哨兵刻意**不认** GSAP 补间参数里的 `opacity:0`：淡入淡出的端点是 0/1，不是驻留的半透明面积。
-
-契约 `gsap-emit-v1.md` 同批增补「Alpha 交付口径」一节，`gtrk-mg` 图纸补剪映预乘纪律。
-
-## 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）
-
-讲软件 / 讲课件 / 讲代码的口播多是**两条文件同步录**：屏录一条、人像一条。此前流水线只能剪其中一条——
-`gtrk oralcut` 粗剪的每个切点没法落到另一条上，画中画只能去客户端手工摆，圆角与蒙版只有客户端看得见。
-镜像切点是纯算术（每颗 clip 一个偏移），却是「每片必做、手工必错」的事，现在做成命令：
-
-```bash
-gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape ellipse|rectangle|heart|diamond|star|none] [--feather 10] [--corner-radius 0.25] [--border-radius <px>] [--anchor bottom-right] [--scale 0.28] [--margin 40] [--offset <秒>] [--dry-run] [--expected-revision <sha256>] [--json]
-gtrk pip lay --resume <屏录名>_pip_align.gtrk
-```
-
-**测偏移三分支，与 `gtrk audio align` 同一套原语**：缺省互相关自动对齐（人像为参考、屏录为待对齐）；
-置信度不足 ⇒ 产 `<屏录名>_pip_align.gtrk`（人像整段 + 屏录整段按估测偏移摆好），用户在客户端把「伴随源」轨拖齐保存后 `--resume` 读回偏移再铺；
-`--offset <秒>` 显式给值跳过检测。偏移口径全库统一：**正 = 屏录晚开录**。
-⚠️ 屏录 **MUST 带麦克风音轨**才能自动对齐（互相关没有参照就没法算），只有系统音的屏录只剩后两条路——开工时就要提醒用户；
-本命令与 `audio align` 一样只做**恒定偏移**，两台设备采样钟差导致的长片渐飘不矫正。
-
-**镜像切点**：主轨每颗非空档 clip 的 `track_st / duration` 原样落到屏录轨，`clip_st′ = clip_st − offset`，整毫秒域、不累加游标；
-越过屏录素材上界 / 下界的部分**钳位 + 留空 + 回执逐颗点名毫秒数**，MUST NOT 拉伸或变速——
-屏录比人像短 / 晚开录的那几段成片只见人像主轨，如实告诉用户。
-
-**铺两条轨，主轨与音轨一字不动**：屏录满幅轨（`track_index` = 现存视频轨最大值 + 1，静音）+ 人像画中画副本轨（再 + 1，静音，
-带 `clip_transform` / `border_radius` / `clip_mask`）。人声仍由主轨镜像音轨承担，副本轨 MUST NOT 双声；
-主轨不动 ⇒ 下游 `split` / `subtitle lay` / `mg` 照旧按 main 对 transcript，零感知。
-形状缺省 `ellipse` = 以画中画短边内切的正圆；`rectangle` 满幅可带 `--corner-radius`；`heart` / `diamond` / `star` 短边内切；`none` 只摆位不遮。
-`--scale` 的语义是**画中画显示高度占画布高度的比例**（缺省 0.28），写进 `clip_transform` 时按 contain-fit 反算。
-
-**幂等 + 不覆盖用户改动**：改参数直接重跑，自产 clip（`producer = gtrk:pip@1`）先剥后铺、空轨删除；
-用户在客户端动过、被清掉身份的画中画 clip **保留并在回执 `strip.keptForeign` 点名**（与 `matrix lay` 同一条认领纪律）。
-写方自检（恒等式 / 接缝 / 素材上界）破了即抛零副作用；原子写回 + revision 断言，`--expected-revision` 跨命令拒写口径同 `gtrk patch`；`--dry-run` 只算不写。
-回执打印的是**数字**（每颗的偏移 / 钳位 / 留空毫秒），不是一句「已验证」。
-
-链路位置：`oralcut` 检查点① → **`pip lay`** → 拆分 / 字幕 → 出片，**不新增必停点**，铺完让用户在客户端看一眼即可；
-口播图纸（`gtrk-talking-head`）开工五问加第 ⑥ 问（有没有同步录的屏录或第二机位、画中画形状 / 位置 / 大小），屏录题材默认不铺 B-roll。
-出片三口：客户端本地导出 / `gtrk render`（见下一节）/ 导剪映（`diamond` 剪映无对应，跳过并明示）。
-纯本地**零计费**，素材不上行。一条伴随源起步，多机位切人另立。
-⚠️ 客户端预览里看到画中画的圆角与形状蒙版，要等客户端同步更新（消费这两个契约字段的那一半随客户端发版）。
-
-### `gtrk render`：画中画的缩放 / 落位 / 旋转 / 透明、圆角与五形状蒙版随工程本地合成（link-clip-mask-contract-render）
-
-1.1.10 把叠加层渲进了成片，但每一层的**几何**还没读：叠加输入一律 contain-fit 后贴满画布，
-客户端里摆好的画中画渲出来是**满幅信箱**，圆角与蒙版更是零支持。现在按契约逐 clip 消费：
-
-- **`clip_transform`**：`scale_x/y` 在 contain-fit 之后再乘（与客户端「先 contain 再乘 scale」同口径，负值 = 翻转）；
-  `position_x/y` 以画布中心为原点落位；`rotation` 旋转（落点按旋转后包围盒算）；`alpha` 透明。
-- **`border_radius`**（画布像素）与 **`clip_mask`** 五形状（`rectangle` + `corner_radius` / `ellipse` / `heart` / `diamond` / `star`，与契约枚举一字不差）：
-  支持 `invert` 反相、蒙版自身 `rotation`、`feather` 羽化（0..100 = 占蒙版短边百分比）；两者同时在场**叠乘**（元素圆角 ∩ 形状窗），不降级。
-- 颗粒（`beat_track`）不动：契约不给颗粒这两个字段，颗粒尺寸由 HTML 自带。
-
-**不引图形库**：五形状 + 圆角 + 反相 + 旋转都是闭合路径填充，用纯 JS 扫描线光栅成一张 8-bit 灰度 PNG（node 内置 `zlib` 编码，**零新依赖**——
-多一个原生依赖就多一条安装故障面），ffmpeg 只负责 `gblur`（羽化）+ `alphamerge` + `overlay`。确定性、离线、**零计费**。
-蒙版纹理按参数 + 尺寸内容寻址落 `<工程目录>/.tonghe-cache/masks/<sha256>.png`，可复用、丢了重生；
-缓存目录不可写退系统临时目录，两处都写不了才放弃该纹理——此时该 clip **只按几何叠加并明示**（`maskSkipped`），MUST NOT 阻断渲染。
-
-**零回归门**：`clip_transform` 缺席或恒等、且无圆角 / 蒙版的 clip，滤镜链与 1.1.10 **逐字节相同**，既有黄金向量原样通过。
-`--json` 的 `overlay` 段新增 `transformed` / `masked` / `maskSkipped` 三个计数，完成话术逐类点名
-「几段按 clip_transform 落位 / 几段合成了蒙版或圆角 / 几段纹理不可用只按几何叠加」。
-两条口径：羽化是高斯近似，与客户端的距离场羽化**观感等价、不逐像素等价**；
-客户端专有蒙版形态（钢笔 / 文字 / 分屏 / 黑边 / 描边 / 多蒙版）只在客户端状态里，本地渲染不读。
-
-### `gtrk oralcut --lang`：按识别源语种分档校验，切点线不支持的码在抽取前就拒（link-enum-catalog-cli §7）
-
-1.1.10 的枚举清单把 `--lang` 改成按快照校验，但拿的是 `subtitle.languages`——那是翻译目标语与识别源语种的 **11 项共同范围**，
-会放行 `es-ES` / `pt-PT` / `ru-RU` / `vi-VN`，让用户抽完音频、传完文件，才被服务端 6015 拒。
-现在 `/catalog` 下发 `subtitle.source_languages`，**按 task_type 分档**（切点三线 7 项：`en-US` / `fr-FR` / `ja-JP` / `ko-KR` / `zh-CHS` / `zh-CHT` / `zh-CN`；
-`video_ai_subtitle` / `subtitle_translate` 11 项），`oralcut --lang` 改按 `video_oral_cut` 那一档在**抽取之前**校验，报错只列本线 7 项。
-退回规则不破 1.1.10 的两条既定口径：分档整体缺失（老服务端 / 旧快照）/ 缺该线 / 形态不合 ⇒ 退回 11 项共同范围；
-共同范围也拿不到或无快照 ⇒ 放行交服务端裁决——**fail-open、只降不升**。
-`long2short --language` / `transcript --lang` / `gtrk tool` 的翻译语种参数本来就不做本地取值校验，这次一格不动。
-
-## 1.1.10（2026-09-10）
-
-### `gtrk render` 现在会把 MG 颗粒与 overlay 真的渲进成片（add-render-overlay-compositing）
-
-此前本地渲染的视频侧**只投影一条主轨**：铺了 65 颗 MG 颗粒、铺了整轨 B-roll 候选，渲出来一个都没有，
-而且退出码 0、渲后质检一切正常——**缺件成品，却一声不吭**。
-现在按契约 z 序（`track_index` **升序**，越大越靠前）把**全部可见叠加层**叠进成片：
-overlay 视频轨（B-roll 候选 / AI 再现回铺）与 `beat_track` 的 MG 颗粒都在内。
-在客户端关了「小眼睛」的轨（`hidden`）整条不进片；多条候选轨都可见时成片取最上层（= 客户端预览所见）——
-渲染器**只读字段不猜**，与音频侧「只认 `muted`」是同一条纪律。
-
-颗粒那一段有计费：CLI 没有 HTML 渲染引擎，颗粒送同合云烤成 qtrle 透明 MOV 再本地叠。
-计量 = **唯一颗粒数 × 未命中缓存数**（按分钟），未命中时先出预估并要确认（`--yes` 跳过；
-`--json` 下必须显式 `--yes`，否则硬拒——机读模式没有 stdin，不静默提交计费任务）。
-缓存落 `<工程目录>/.tonghe-cache/particles/`，**与客户端导出剪映那条链同键同落点** ⇒
-任一端烤过，另一端直接命中：**第二次渲染零计费**，客户端烤过的工程 CLI 首渲即零计费。
-不想花钱用 `--no-particles` 出无颗粒版（overlay 视频轨照常合成，那部分零计费、纯本地）；
-`--particle-concurrency <n>`（1–8，默认 6）调并发。
-
-三条如实告知：跳过的颗粒、隐藏未叠的轨、缺素材未叠的 clip 都在人读日志与 `--json`
-（`particles` / `overlay` 两个新字段）里逐类点名。overlay 素材本地缺失**只降级不阻断**——
-B-roll 代理没下全，不该让一条 45 分钟的片子出不来。
-无叠加层的工程**滤镜图逐字节不变**（零回归门有黄金向量守）。
-⚠️ 顺带一条口径更正：`gtrk render` 不再是纯本地零计费命令——工程有未命中缓存的颗粒时，
-**颗粒 HTML 文本会上行**（素材本体仍不上行），此时会打一次合规告知。
-
-### 本地渲染的 clip 上限 500 → 2000：长口播不再被一个「借来的」阈值挡在门外（adjust-local-render-clip-ceiling）
-
-45 分钟口播经 `gtrk oralcut` 逐停顿切出 **593 个 clip**，本地渲染直接报「clip 总数 593 超过上限 500」——
-按 13 clip/分钟折算，这等于给本地渲染判了「口播不得超过约 38 分钟」，而这个限制**从来没有被当成产品决策做出过**：
-500 是**镜像后端**的常量，那边的语境是云端多租户资源保护（防单任务吃掉渲染机）。
-本地渲染没有多租户、输入还按路径去重（593 clip / 1 素材 = 1 个 `-i`），代价只是本机自己变慢、由本机用户自己承担。
-
-新值 **2000 由实测裁定**，不是「翻个倍听起来合理」——本机实测 ffmpeg 构建滤镜图的成本：
-
-| clip 数 | 初始化墙钟 | 峰值内存 |
-|---|---|---|
-| 500 | 1.25 s | 151 MB |
-| 1000 | 5.2 s | 264 MB |
-| **2000** | **20.3 s** | **476 MB** |
-| 5000 | 167.9 s | 1138 MB |
-
-时间近 **O(N²)**、内存线性（约 0.23 MB/clip），而且这只是**开渲之前**的等待。
-所以一度考虑的 5000 被自己的实测否掉（干等 2.8 分钟 + 1.1 GB）；2000 ≈ 2.5 小时口播，覆盖已知全部形态。
-
-配套两条：**超限话术**改成说清三件事（这是**本机**的闸、不是云端限制 / 当前多少 / 出路是拆工程或来提 issue）；
-clip 数 **超过 1000** 时先打一行 INFO 说明「构建滤镜图要花点时间，不是卡死」——
-那段没有任何输出，最容易被读成卡住。告知档是**绝对值**不是「上限的百分比」（相对量说不出用户要等多久）。
-叠加元素（overlay clip / 颗粒）**不计入**这个计数，闸值与计数口径一次只动一个。
-
-### `gtrk mg fetch`：registry 中性颗粒源，不会做动画也能拿到能用的颗粒（add-mg-registry-neutral-source）
-
-MG 车道此前只有一条路——你自己的栏目 MG 生产 skill 从零写 GSAP 颗粒。没有那套资产的人，`dispatch.mg` 就是空的。
-现在随包带一份 **Hyperframes registry 快照**（`src/data/mg-registry-catalog.json`，180 件，
-钉死来源 `heygen-com/hyperframes@8bf5b44`，快照日 2026-09-10）：`gtrk mg fetch` 不给 `--pick` 是**候选态**（只列不取，**离线可用**），
-给了才取块——取块三源按序试：**我方镜像（大陆可达）→ jsdelivr → GitHub raw**，每源 5 秒超时，
-任一源返回的字节 **MUST 过 sha256 与快照比对**（版本错位 / 篡改在这一步被拒）。
-`GITRUCK_MG_REGISTRY_BASE` 可整体覆盖取块前缀（自建端点 / 内网），与运行时资产的 env 覆盖同形。
-取回的块经**机械改写**成合规颗粒并过 `mg lint` 门：改画布 / 改透明底或满屏底 / 换字体（缺省取运行时镜像可证的 CJK 字体）/ 钉 composition_id。
-两种用法：`--slot <beat>` **派单模式**（从 `dispatch.mg` 取 composition_id 与坑位包络，产物落 `<工程>/mg/`）、
-`--id` + `--duration` **独立模式**。契约当前只收 1920×1080，其余画布明确拒绝。
-**刻意不引 hyperframes CLI**：端点是静态文件，Node 内置 fetch 够用——省掉用户侧 33 MB + 原生二进制 + Node ≥22 的负担。
-
-### `gtrk skills recommend` / `gtrk skills add`：第三方 skill 随包推荐目录（add-third-party-skill-catalog）
-
-我们的图纸只覆盖成片编排，视觉玩法（钩子 / 动态图讲解 / 动态字幕 / 数据可视化 / 地图 / AI 再现 / 拼贴 / 字幕 / 设计原则）
-一直是「你自己去找」。现在随包带一份**第三方 skill 推荐目录**（快照 2026-09-10，九个场景），
-`gtrk skills recommend` 无参列场景枚举、`--scene <id>` 按 tier（T1 在前）列条目，`gtrk skills add <repo>` 直接装。
-人读输出**恒走 stderr**，`--json` 时 stdout 只有 JSON。
-星数是**快照值**，回执明写「以仓库页为准」——目录随包发版，不联网校核，不假装是实时数据。
-公约正本同批立 §三‴「第三方 skill 推荐面：**三档、克制、不点名**」，六份成片图纸 SKILL.md 按它接推荐面：
-图纸先给自持方案，再轻提一句「要更多变体可以看第三方 skill」，**不在正文点名具体仓库**——点名要靠 `recommend` 命令去查。
-
-### 成片型图纸公约加一节「前六秒：钩子层」（add-blueprint-opening-hook-layer）
-
-公约正本（`docs/成片型图纸公约.md`）新增 §三⁗：前六秒决定完播，而外部钩子 skill 全是纯文本、不知道我方四车道，
-所以「钩子文案 + 前六秒画面 + 字卡节奏」三合一**由图纸自持**。
-口播链 / 配音链同批落执行文本：**检查点①之前**由 agent 产一份「前六秒方案」——
-钩子文案三候选（只改开口方式，**MUST NOT 改动用户的事实与数据**）+ 画面层三选一（A_ROLL / MG 字卡 / 拼贴或 AI 片段）+ 字卡节奏，
-**与其他拍板项同屏一次拍板**，MUST NOT 单独追问、MUST NOT 在检查点①之后再冒出来。
-答「开场照原样」= 零动作、后续不再提。
-
-### 首跑与 `gtrk init` 收尾补一句交接指路（add-agent-handoff-signpost）
-
-新用户跑完 `gtrk init` 常以为下一步该去客户端里跟 AI 对话。首跑块与 `init` 收尾各补一句明示：
-**客户端目前没有 AI 对话框，对话在 Agent 里进行**，客户端负责精修与出片。
-
-### 枚举清单：校验取值改由服务端下发，服务端加一种样式不用等 CLI 发版（link-enum-catalog-cli）
-
-此前 `--subtitle-type` / `--subtitle-color` 的可选值被**抄在 CLI 本地常量**里：服务端新增一种字幕样式，CLI 会当场拒掉那个**合法值**；服务端临时下架一个能力，CLI 还在往外发。两种都不报错，只是行为不对。
-现在启动云端命令时向 `GET /catalog`（公开只读口）拉一份枚举清单，落 `~/.gitruck/catalog.json`：新鲜期 24 h 内**零网络**，过期走条件请求（304 只推进时刻、200 整体替换），拉不到就沿用旧快照并打**一行**降级提示。
-`--subtitle-type` / `--subtitle-color` / `gtrk oralcut` 的 `--lang` / `--preset` / `--formats` 都改按快照在**上传之前**校验并列出可用集；`gtrk tool list` 与直调按服务端下架名单标「暂停服务」并拒绝提交（**只降不升、且只在快照新鲜时生效**）。
-`gtrk doctor` 新增「枚举清单」行（版本 / 拉取时间 / 落点）与 `--refresh-catalog`。
-三条硬性质：① **拉不到 MUST NOT 让命令失败**——任何失败分支都放行，交服务端白名单裁决；② **`--help` 路径零网络**（注册期只读快照文件，有真进程 fetch 计数守卫）；③ 服务端白名单**恒为唯一真相源**，本地校验只是「早点告诉用户」，所以无快照是放行而不是拒绝。
-本地清单有可能比服务端旧 ⇒ 报错文案一并告知逃生口：`--refresh-catalog` 立刻刷新，`--param` 绕过本地校验。与 infra `add-enum-catalog-api` 联动（该端点 2026-09-10 已上生产）。
-
-## 1.1.9（2026-09-10）
-
-### CLI 崩溃自动上报：崩了不再只留一句红字（link-client-error-report-cli）
-
-CLI 崩溃时**只上传错误消息与堆栈**到同合云 `POST /error/report`，不带素材、工程内容与凭据。
-四路收口：`uncaughtException` / `unhandledRejection` / 顶层命令异常 / 已知崩溃形态；
-同一进程内的连环崩溃按「名字 + 首帧」压成一条并累加 `occurrence_count`，不刷屏也不刷库。
-首次运行打一行告知，关闭方式两种：`gtrk init --no-crash-report`，或设 `GITRUCK_CRASH_REPORT=0`；
-`gtrk doctor` 新增「崩溃自动上报」行显示当前开关状态。上报前做凭据洗白与长度截断。
-与 infra 主件 `add-client-error-report`、客户端半 `link-client-error-report-client` 同线。
-
-### 长剪短：分屏开不开由开工一问决定，clips.md 回显分屏请求态
-
-（补记）分屏不再默认硬开：开工时先问一句「是否多人同框」，据此决定本次是否请求分屏；
-`clips.md` 回显本次的分屏请求态，避免「以为开了其实没开 / 以为没开其实开了」。
-
-### 倍帧素材的假切点：切点判定改在去重帧序列上进行
-
-（补记）倍帧（同一画面重复多帧）素材此前会在重复帧之间判出并不存在的切点，
-现在切点判定改在**去重后的帧序列**上进行。
-
----
-
-## 1.1.8（bump 了但没发）
-
-`package.json` 从 1.1.7 bump 到 1.1.8（`2f20453`），但**这一版从未推上 npm** ——
-registry 上 1.1.7 之后直接是 1.1.9。留此条只为解释版本号为什么跳，无内容变更。
-
----
-
-## 1.1.7（2026-09-09）
-
-### `gtrk` 装完即可敲：install 自持全局副本 + Windows 用户级 PATH + doctor「命令可达」+ upgrade 沿自己的通道升级（add-gtrk-command-availability）
-
-此前 `npx @gitruck/cli@latest install`（官网默认路线、全套 `install.ps1` 第三步）只装 skill 与配置，**从不安装 gtrk 本体**——npx 跑完把包丢掉，新开终端敲 `gtrk` 不是命令；`npm i -g` 路线则要靠 npm 全局目录恰好在 PATH 上。
-现在 `gtrk install` 先做第 ⓪ 步：运行中的自己若不是持久 PATH 能解析到的那份（npx 临时态 / 未 link 的本地检出），先 `npm i -g @gitruck/cli@<运行中版本>` 自持（钉运行版、已有更高版本不动）；随后按**持久** PATH（Windows 读注册表 HKLM+HKCU，不是启动它的终端给的 PATH）核对启动器目录，不在就追加到 HKCU 用户 PATH **尾部**（保留 `REG_EXPAND_SZ`、原值 `%…%` 不展开、不去重不重排、幂等）并广播 `WM_SETTINGCHANGE`；写被拒只给可读原因与手工指引、不让 install 退非零。macOS/Linux 不改任何 rc 文件，不可达时打一行 `export PATH=…`。
-`gtrk doctor` 新增「命令可达」行：持久 PATH 解析到且版本一致为绿，解析不到为红并指向 `gtrk install`，敲到另一版为黄。`gtrk upgrade` 按 `process.execPath` 是否在 `~/.gitruck/node/` 之下判定通道：私有运行时（桌面端自举落位）用私有 node + 私有 npm + `--prefix ~/.gitruck/npm` 升级并复核启动器，**不去找系统 npm**；npm 全局通道维持现状。
-规格：新立 `gtrk-command-availability`；`ffmpeg-runtime` 的「用户环境零侵入」条款收窄射程为 ffmpeg/字体等运行时资产（gtrk 自身启动器目录进用户 PATH 是明确例外）；`gitruck-home` 登记 `node/` `npm/` `bin/` 三目录（客户端自举的私有运行时布局）。与 opencut 仓 `add-cli-bootstrap-runtime` 联动：本版先发，客户端再发。
-
-### 封面工作台：T1 字体读用户本机、描边缺省 0（add-cover-workbench-font-switcher）
-
-`gtrk-cover` 排字工作台右栏新增「字体」下拉与「字重」档位（400 / 700 / 900）：下拉首项恒为 skill 注入的当期默认字（`T1_DEFAULT_FONT`，仍是 skill 按栏目封面风格资产或中性默认做的审美决策），
-其余项来自**用户本机已装字体**，三级取数、任一级成功即可用——打开即按内置候选表（约 70 款常见中文字体，中英文名两写法）做 canvas `measureText` 已安装探测；Chrome / Edge 点「读取本机字体」经 Local Font Access API 取全量（需授权一次，结果与探测结果取并集、当前选中项恒保留，接口返回空按失败退化并解释）；
-两条都没列出的在输入框敲 family 名回车应用。三级全失败不阻塞。导出走本机 `html2canvas`，本机字体天然可用；与 MG 颗粒「字体名 MUST 命中服务端注册表」是两条线，guide §10 已写明分界。
-T1 描边缺省由 2 改 0：思源黑 / 宋这类重叠轮廓的特黑字体加 `text-stroke` 会把部件内部轮廓描成镂空积木（缩略预览看不出、导出才炸），托底改用暗色双层 `text-shadow`，滑杆保留。
-引擎层（拖拽 / 方向键 / 滚轮 / 导出 / 舞台缩放）零改动。同批：SKILL.md 铁律 3 暴露面加「T1 字体与字重档位」、中性默认「描边不加」，checklist ⑥ 补描边与切字体后可读性。
-
----
-
-## 1.1.6（2026-09-08）
-
-### 产物落点硬闸：计费前先实证落点可写，缺 `--out` 当场硬拒
-
-（补记）`gtrk oralcut` / `gtrk mg` 在**上传与计费之前**先实证产物目录真的写得进去，
-写不进就阻塞拉用户处理到可写为止（非交互当场硬失败），**不静默改投别的目录**；
-缺 `--out` 不再猜一个落点而是当场硬拒；MG 颗粒必须产在工程目录内。
-
----
-
-## 1.1.5（2026-09-07）
-
-### 锚点金样入册（fix-anchor-top-hit-guarantee §5）：决策 pin v5 的金样清单 53 → 57、哈希重登记不升 v6
-
-`test/fixtures/broll-arrange/cases/` 新增 `44-anchor-sim-order-real-q1`（真机复刻 Q1/B04 两刀合璧：锚槽按原始 sim 取校门段而非融合分顶上来的广告牌，B02 泛化槽让位转次优）/
-`45-anchor-cross-beat-reserve-lay2`（备选轨同受预留约束 + 不相交 beat 零回归）/ `46-anchor-reserve-release`（逐锚 finally 与零长度 beat 早退两条释放路）/
-`47-anchor-vs-anchor-at-sec-order`（at_sec 先到先得、`reserved` 与 `consumed`+`top_by` 两种归因形态），均由 `regenerate.mjs` 产出，临时变异实证各自在「锚序退回融合分 / 关掉预留」下 expected 会变。
-决策层零改动（`matrix-lay.ts` 零 diff），既有 53 项金样逐字节不变、`cloud-form.json` 逐字节不变、`metering.json` 只多 4 条派生 entry（`METERING_ALGO_PIN` 不动）。
-v5 尚未发版 ⇒ `PIN_TO_MANIFEST_SHA[v5]` 由 `3bcc7aef…` 重登记为 `cc82e20e…`（57 项）而不升 v6，infra `link-anchor-top-hit-guarantee` 同批把 `_PIN_TO_MANIFEST_SHA[v5]` 改成同一个数。
-
-### gap 填充：恰等 1ms 的残量并入前一颗、合并容差统一到整毫秒格（决策 pin v5）
-
-`matrix lay` 主轨 gap 填充的合并容差从秒域浮点 `BLACK_BED_MERGE_EPS = 0.001` 改为整毫秒格具名常量 `BLACK_BED_MERGE_TOL_MS = 1`（`sec2ms` 整数差比较）。
-此前同一行 `x > 0.001` 在不同时间线位置上因浮点相位给出两种答案（0–300s 毫秒格上 `r3(t + 0.001) − r3(t)` 65.08% 的位置 `> 1e-3`、34.92% 的位置 `≤ 1e-3`），
-真机三条片里恰等 1ms 的残洞一处排出 0.001s 黑片、一处留 0.001s 裸缝。现在恰等 1ms 的残量恒判「有量」、恒进既有 ②a / ②a′ 延长链由前一颗吸收
-（前一颗 `track_ed` 与源窗终点同延 1ms、`track_st` 不动、`kind: "extend"`，不新增分支不新增 kind；源窗为此越出检索段界 ≤ 1ms 是具名例外，既有 `MICRO_SLOP` 松弛档覆盖）。
-同批改整毫秒格的判据（A 档）：`beatGaps` / `computeBlackBedHoles` / `mergeBlackBedSegments`、`fastFillBeatGaps` 全部容差消费点、高档直排的落位重叠与越 beat、碎尾吸收、锚槽 room、段界包含
-（52 份金样 + 3 份真机 plan 的 2182 段段界实测全在毫秒格上，逐值同解）。只改名不改值（B 档）：`CUT_ALIGN_EPS → CUT_ALIGN_WINDOW_SEC`（业务阈值 0.1s）。
-明确不改（C 档，登记转出）：吸附率比例 `1e-9`、`refineWindow` 帧号域与秒域 ε、`1/fps` 亏空、句界吸附带。
-「主轨零 gap」不再无条件打印：由整毫秒格对填充后主轨产物（含 solid 与 gap 填充槽位）的实扫得出，仍有 ≥ 1ms 缝即如实报数并 WARN；
-lay JSON `gap_fill` 新增**条件键** `residual_gaps { count, sec, items[] }`（零缝整键缺席）。
-决策产物字节：既有 52 项金样逐字节不变，新增 `cases/43-gapfill-eps-exact-residue`（同一 1ms 残量两相位同解）⇒ `LOCAL_DECISION_ALGO_PIN` v4 → v5、金样清单 52 → 53
-（`PIN_TO_MANIFEST_SHA[v5] = 3bcc7aef…`，infra `link-gapfill-eps-boundary-residue` 同批镜像、逐字相同；`METERING_ALGO_PIN` 不动，metering.json 只多一条派生 entry）。
-**发版序**：infra `add-arrange-decision-pin-echo` 回传先上线 → infra 决策层 v5 上线 → 本包发版；顺序错则 ≥ 1.1.3 客户端在读到 `server_ahead` 之前整轮退回自校验、
-`self_check_failed` 回落本地并白付一次编排费（服务端不按决策 pin 拒绝客户端；真会前置拒绝的是 `METERING_ALGO_PIN`）。
-
-### 时间消费侧统一：`gtrk render` 接缝判据与 `gtrk patch` 校验器同源（整毫秒格）、匿名 ε 清退、`qc` 阈值具名
-
-`gtrk render` 的同轨重叠 / 缝 / 尾补判据从 `±1e-6` 浮点秒改为**整毫秒格**（`sec2ms`），与 `gtrk patch` 的 E9 `same_track_overlap` 同一判据：
-`sec2ms(track_st)` 小于前一元素终点即拒渲、大于即补 gap、相等即相邻。**`render` 变严的一面**：重叠 ≥ 0.5ms 的工程拒渲，话术含修复指引
-（用 `gtrk patch` 校验并修正该轨，或用客户端打开工程重存一次后再渲染）；此前 render 收而 patch 拒的「一收一拒」不再存在。
-**变宽的一面**（只影响时码不在毫秒格上的老工程 / 客户端按帧写出的工程）：亚毫秒（< 0.5ms）重叠视为相邻不再拒渲，亚毫秒缝不再插一个 0 帧黑场元素；
-gap / 尾补时长落在整毫秒格上（`atrim=end=` 一类字面从 `276.366667` 变 `276.367000`）。三位小数工程的 filter_complex 逐字节不变；
-`allocateFrames` 累计量改整毫秒和、帧化经 `sec2frame`，真机工程副本（客户端按帧写出，110 元素）裁定帧数与改前相同（8291 帧）。
-`caption-align` 三种时间比较（同句回缝 gap / 字级去重 / 行推进与小 gap 桥接）统一到具名 `CAPTION_TIME_GRID_MS = 1`，`EPS = 1e-6` 与裸 `1e-3` 清退
-（亚毫秒差的重复字现在会去重、亚毫秒缝不再算一次桥接）；`audio align` 的 `adelay` 分流阈从 `0.0005s` 改整毫秒（不足 1ms 的偏移即零偏移）。
-全仓 32 处内联换算收编为 `frame-domain` 的 `r3`（15 处）/ `sec2ms`（15 处）/ `sec2frame`（2 处），逐值同；`matrix lay` 代理帧率不等判据改用
-`VFR_MISMATCH_RATIO`（相对差 1%，此前本地 `PROXY_FPS_EPS` 按绝对差 0.01 比、与其头注「1% 以内」不符）。
-`qc`：`cutMatchTolSec` 改名 `cutMatchWindowSec`（未经 `--json` 暴露，无别名），`cutMaxDriftSec / slotLookupSec / knownBlackHoleMatchSec` 进
-`QC_THRESHOLDS`（值不变），`av_drift` 项新增 `frames: {probed, expected}` 佐证（成片 `nb_frames` vs `sec2frame(工程时间线终点或音频时长, video_rate)`，判级不变）。
-决策层（`matrix lay` 的 `refineWindow / fillSlots / layAnchored / planBeatFills / slotTimes` 与 gap 填充）零改动，铺轨金样与 `MANIFEST` 逐字节不变。
-
-### 标准帧率表与 VFR 可见；`gtrk render` 对非整数 `video_rate` 从静默渲染改为报错（含修复指引）
-
-`frame-domain.ts` 新增本仓唯一的标准帧率表 `STANDARD_RATES`（`24000/1001, 24, 25, 30000/1001, 30, 50, 60000/1001, 60, 120`）与两个视图：
-`snapRationalRate`（源真值：与表中值相对差 ≤ 0.2% 才吸附，`29.970029 → 30000/1001`，非标值原样）、`deliveryRate`（交付整数：NLE 表
-`[23.976, 24, 25, 29.97, 30, 50, 59.94, 60]` 最近邻后取整，与客户端同口径、封顶 60，`(0, ∞)` 无洞）。`audio align` 兜底工程的顶层与素材
-`video_rate` 改经 `deliveryRate`（29.97 → 30、23.98 → 24 与此前同值；源片帧率解析不到时改为报错，不再静默写出 1fps 工程）。
-`probeGeometry` 在同一次 ffprobe 里加读 `avg_frame_rate`，给出 `avgFps` 与三态 `vfr`（`|avg − r| / r > 1%`；容器无 avg 时 `null` 不判）；
-判据阈值 `VFR_MISMATCH_RATIO` 一处定义，成片质检 `qc` 的 `vfr` 项改 import 同一常量（行为不变）。
-
-**`gtrk render` 变严**：顶层 `video_rate` 缺席、非正或非整数（典型是老工程里的 29.97）此前会按 29.97 静默分配帧数并进 `fps=` 滤镜，
-现在与 `matrix lay` / `gtrk patch` 同一条判据、同一条话术报错退出，且在解析 ffmpeg、探测素材、写临时滤镜文件**之前**即止（无产物、无残留）。
-修复：用客户端打开该工程重存一次即吸附到标准帧率（29.97 → 30、23.976 → 24），或手工把顶层 `video_rate` 改成正整数；
-`video_rate` 已是正整数的工程渲染结果与此前逐字节相同。
-
-`oralcut` / `long2short` 上传前：源片判为 VFR 时 WARN 一行（名义 `r_frame_rate` 与平均 `avg_frame_rate` 两值）但不阻断，上行几何仍是
-真实 `r_frame_rate`；`--json` 与 result.json 多一个 `source: { path, fps, avg_fps, vfr }`。源片帧率解析不到（`r_frame_rate = 0/0`）时
-在上传前报错退出（零抽取、零上传、不留产物目录），不以 25 / 30 兜底。`matrix index` 入库：VFR 视频素材逐条 WARN、`--json` 多
-`vfr_materials` 计数（不加索引列，检索透出的 `fps` 仍是名义值）；帧率解析不到的视频素材跳过不入库并 WARN（计入 `failed`）。
-`ai-drama lay` 拷贝后探测顺带 VFR 告警。决策层的吸附网格、铺轨金样与 `.gtrk` 字段零改动。
-
-### 跨时钟适配器：preview 代理落盘即实测、云端产物落地复核、写方自检覆盖音频轨
-
-`matrix lay` 下载（或缓存命中）每颗 preview 代理后现场 ffprobe 一次，`materials[]` 条目的 `duration / video_size / video_rate`
-改写**落盘文件本身**的实测值（此前写的是云端自述的原片时长与猜测尺寸）；云端自述只用于比对——时长差超一帧或帧率不等各打一条
-WARN，全量明细进 `--json lay.clock`（`proxy_probed / unverified / proxy_mismatch[] / proxy_fps_mismatch[]`）；探测失败回退自述并计
-`unverified`，不让铺轨失败。槽位选段与吸附网格不消费实测值（云本平价，决策与金样逐字节不变）。`ai-drama lay` 同款：拷贝后实测覆盖
-工作台 manifest 的 `measuredSec`，差 > 1ms 告警并进 `--json clock.manifest_mismatch[]`。`subtitle lay` 云端拆行的兜底行时码钳进父句
-包络（越出父句的行不再原样落轨），计数进 INFO 与 `--json clamped_lines`。`oralcut` / `long2short` 拉回 `.gtrk` 后以本地原片实测时长
-为墙复核不变量，只 WARN + `--json landing_check`，产物一个字节不改、退出码不变。写方自检射程扩到 `audio_track`，`audio lay` 写回前自检
-本次 BGM clip（存量违例只 WARN）。本地索引代理三档解码参数由单测锁定无任何时基滤镜。
-
-### matrix lay 落轨在工程帧网格上（写出侧变换，决策与金样不变）；gtrk patch 的毫秒投影改向下
-
-`matrix lay` 写出的每一颗 B-roll 槽位与黑底 clip，起止时码现在都是顶层 `video_rate` 帧网格上某个整帧号的投影
-（与 `gtrk patch` 同一套 `sec2frame / f2ms`）。帧格化是**写出前的一次变换**：填槽 / 锚定 / gap 填充 / 源窗精修等
-决策层仍以毫秒与实数游标工作，选段、切分位置（`clip_st`）与金样逐字节不变；写出时每颗槽位两端各取一次帧号
-（端点挪动 ≤ 半帧 + 1ms），相邻槽位的接缝由同一个帧号构成，黑底按 beat 包络投影、与首槽起点天然封口。取整帧后
-`clip_ed` 越过检索段界（或素材时长）时宁短一帧并让同轨后续槽位整体前移一帧（接缝仍相等），逐次 INFO 可见。
-本地槽位与云端编排返回的槽位走同一入口。此前槽位只知道毫秒，真机 30fps 工程里 B-roll 轨 62 颗有 30 颗、黑底
-10 颗全部离网格，客户端帧级缩放下「没有一条边对得上」，还有两处一帧黑闪与一处溢出一帧。
-工程顶层缺 `video_rate`（或非正、非整数）时 `matrix lay` 直接报错退出、工程零改动，不再有毫秒路可退；
-`--json` 的 `lay` 多一个 `frame_grid: { rate, slots, black_bed, shifted }` 诊断块；过短黑片账面的帧数按就近取整判
-（网格上的一帧黑片如实进账）。
-
-`gtrk patch` 的帧号 → 毫秒投影由就近改为**向下**（`f2ms`）：客户端合成器按「起点 ≤ t < 终点」采样，
-就近投影会让 24 / 30 / 60fps 下三分之一的帧位晚一帧才在场；向下之后客户端与 `gtrk render` 对同一帧号
-得到同一有效帧。可见变化：这些帧位上写出的 `track_st / track_ed` 比以前小 1ms，帧号不变，往返照旧可逆。
-
-### ai-drama lay / mg lay 落轨帧格；投影终点规则
-
-`ai-drama lay` 写出的每颗 AI clip 与 `mg lay` 写出的每颗 MG 颗粒，起止时码现在都是顶层 `video_rate` 帧网格上整帧号的投影
-（与 `matrix lay` / `gtrk patch` 同一套换算、同一个向下方向）。`ai-drama lay` 的毫秒决策链（建议时长 / 剩余 / 末镜吃满 /
-不足即跳）一字不改，帧号由累计位置一次取整，相邻镜的接缝由同一个帧号构成；取整帧后越过素材实测时长时宁短一帧、同包后续镜整体前移
-一帧（逐次 INFO 可见），不足半帧的镜跳过。`mg lay` 对每颗颗粒的窗口两端各取一次帧号，同 beat 的主颗粒与 `-aux` 覆层同窗即同一对
-帧号，`--only` 保留搬运的存量颗粒不重投影；拆分稿的 beat 毫秒包络本身不变。此前两者只知道毫秒，真机 60fps 工程里 21 颗 MG 颗粒
-全部离网格，客户端向上帧化与 `html_animate_render` 就近帧化会在同一颗颗粒上差一帧。工程顶层缺 `video_rate`（或非正、非整数）
-时两条命令直接报错退出、素材 / 颗粒不复制、工程零改动；`ai-drama lay --json` 多一个 `frame_grid: { rate, shifted, dropped }`。
-
-`gtrk split` / `gtrk subtitle` 所依赖的时间线投影改为**起点取整一次、终点由时长导出**（`track_ed = track_st + r3(e − s)`），
-不再两端各自取整；非整毫秒相位下终点与以前最多差 1ms，投影产物仍留在毫秒域、不吸帧。
-
-### lay 命令写回前自检不变量
-
-`matrix lay` / `mg lay` / `ai-drama lay` 在写回工程之前自检**本次写出的** clip：裁剪恒等式、同轨零重叠（含与既有邻居）、
-`clip_ed` 不超素材实测时长（容差 1ms）；违约直接抛错点名 clip_id 与不变量，工程文件逐字节不写。工程里由旧客户端重存留下的
-存量违例只打一条 WARN 汇总（kind 计数 + clip_id 样本 + 修复指引），不阻断本次写回。
-
-### 字幕拆行改走云端，剪掉的字不再上屏
-
-`gtrk subtitle lay` 的拆行不再在本地按字宽硬切：缺省把回缝后的句子送到同合云 `subtitle_line_split`
-（HanLP 分词 + 词性权重 + 按你所选样式模板与真实画布实算的宽度预算，**0 积分**、照留痕），
-拿回的每一行再按**字级时码**贴回时间线——行首行尾落在真正开口的那个字上，不是按字数比例内插。
-
-投影也改成字级：口播剪辑常在句内剪口吃 / 重读，以前整句文本会把剪掉的字显示回来（真机一份 52 句工程，
-88% 的字幕文字对不上那一刻说的话）；现在只有时间线上存活的字才上轨，被剪成多片的同一句按时间线序拼回一条。
-
-相邻字幕的空隙桥接阈值从 0.5s 放到 **1.5s**：语义对齐剪映的「自动填充文本空隙」，句间换气（真机 0.5~1.3s）
-不再留黑屏闪断；≥1.5s 的真实停顿仍然不硬填。`--max-gap` 照旧可调，0 关。
-
-云端不可达（没配 key / 离线 / 超时）**不报错**：回缝后的句整句上轨、长句未拆，WARN 说清楚下一步；
-`--json` 多了 `splitter` / `cloudUnavailable` / `cloudDegraded`。要走老的本地拆窗器加 `--offline`
-（它已冻结、只做兜底；`--max-units` 只在离线下有意义）。两条 skill 里「字幕纯本地零云端」的说法随之改口。
-
-### 内部重构：时间换算收敛到一处
-
-秒 / 毫秒 / 帧换算（`sec2frame / f2ms / derive` 与 17 处各自复制的 `r3`）收敛到 `src/lib/frame-domain.ts` 一份正本，行为零变化——不改任何写出值与取整方向。
-
-## 1.1.4（2026-09-06）
-
-### AI 片段回填不用再手搓脚本了
-
-`gtrk ai-drama lay` 收下 AI Drama Desk 的 return-v1 导出包，把你在外面生成好、自己挑过的片段
-确定性地铺成一条独立 AI 轨——**纯本地、零模型调用、零计费**，生成那一步仍然发生在你和外部平台之间。
-
-在这之前，回填是靠现写脚本干的。真机上那份脚本把 `setpts` 系数写反过一次（本该放慢写成了加速，
-差了 0.42 秒才被发现），而且每条片子都要重写一遍、工程文件上不留任何登记。
-
-两条你会撞到的行为：
-
-- **不完整的包整批拒收**。导出清单里只要还有镜头没导出，命令直接报错、一个 clip 都不铺——
-  半个包铺进去，成片会在那个窗口无声无息地缺镜。
-- **素材比窗口短就留空档**，不拉伸也不循环。末镜尽量吸收到窗口终点，但不会为了填满而凭空造帧。
-
-已经铺过的 AI 轨若被你在客户端拖动过，重跑会拒绝覆盖并提示 `--replace-all`；判不准时一律按
-「拒绝覆盖」处理——手调丢了不可逆，多问一次便宜得多。
-
-## 1.1.3（2026-09-05）
-
-### 成片终于有人声了
-
-`gtrk render` 此前只混 `audio_track`，**视频 clip 自带的音轨从来没进过混音**——口播工程的人声正是
-跟着视频素材走的，所以渲出来的成片实测只有 −70 LUFS（数字静音）。现在遍历全部 `video_track`
-取内嵌音轨，与 BGM 一起混，收口加上与客户端同口径的限幅与总音量。
-
-叠加轨（B-roll / AI 再现）的原声默不作声——静音的**唯一依据是 `muted` 字段**，铺轨命令落轨时
-写什么就是什么，渲染器不按轨序或车道名自作主张。解说链里要保留原片原声的片段，把该轨 `muted`
-置 `false` 即可。工程一个音源都没有时会明说「将出无声成片」，成片照常产出。
-
-### 整片没声音的片子不会再被报成合格
-
-上面那条缺陷之所以能一路走到交付，是因为 QC 把静音一律判成提示级——一段留白和整片哑掉用的是
-同一个级别。现在按整片响度（`ebur128` 的 integrated loudness）单独判定，低于 −50 LUFS 判严重、
-退出码非零。逐段静音仍是提示级，一个字没动。
-
-已知边界：只有极轻 BGM、刻意无人声的成片可能被误判；完全数字静音时 `ebur128` 输出 `-inf`，
-按远低于阈值处理、不会漏判。
-
-**射程**：质检的前提是你走了 `gtrk render`。只铺轨、或改由客户端出片的流程不会触发这条判定——
-它是「渲出来的片子有没有声音」的闸，不是成片质量的全局保障。
-
-### 字幕不再重复
-
-一句话被智能剪辑切成几片后，`gtrk subtitle lay` 会给每一片都写一条**完整整句**的字幕——真机上
-151 条字幕里有 39 种文本重复、共 89 个实例，时间线上肉眼可见一串重复块。现在同一句的多个片段
-先按时间缝回一条再上轨（同工程 151 → 102 条，重复归零）。回缝与 `--max-gap` 是两个开关：
-关掉小 gap 桥接，回缝照样生效。
-
-### skill 过期会被主动告诉你
-
-**`npm i -g` 只更新 CLI 包，不会刷新已经装好的 skill**——这条认知缺口让 skill 在真机上停了 43 天，
-agent 一直照着废弃的作业指令干活。现在需要 skill 的命令启动时会做一次廉价核对，落后了就点名说明
-并给出修复命令（`gtrk skills install` 或 `gtrk upgrade`）；一致时一个字都不输出。
-`gtrk doctor` 也会显示新鲜度。`GTRK_SKILL_FRESHNESS=off` 可整块关闭。
-
-前提是先跑过一次 `gtrk skills install`（那时才会写下比对基准）；在那之前判不出，静默跳过。
-
-### 爆音检测此前从未生效过
-
-**这不是阈值调优，是一个检测项从产品第一天起就是死的。** 旧版本报「爆音 0」不代表你的片子没问题——
-它代表这项压根没跑出结果。两条判定腿双双恒假：true peak 的正则按同一行匹配，而 ffmpeg 把数值写在
-`True peak:` 的**下一行**；另一条腿匹配的 `Number of clipped samples` **根本不是 astats 的指标**，
-那行永远不会出现。而消费侧「取不到值就跳过」的写法，让解析失败和「测出来没超标」在报告里长得一模一样。
-
-修好之后重新标定了分级，因为原来那条 −1 dBTP 是广播交付线、前提是内容已做响度归一，而成片没有：
-14 条真实语料里 12 条越过它。现在 **−1 dBTP 报提示**（已越交付上限，平台二压可能被削），
-**+1.0 dBTP 或样本域削波比例越限才报严重**。实测真·硬削波成片能被稳定判严重，真实语料一条不误伤。
-
-同时补了一条闸：**测量值解析不到时会明说「本次未生效」**，不再静默放行。这个洞能潜伏一整个产品
-生命周期，就是因为它连一行日志都没有。
-
-已知边界：true peak 是 4 倍过采样的 inter-sample peak，与「听得见的失真」不是一回事——越线不等于一定难听。
-
-### 会听懂「逐步推进」了
-
-`docs/成片型图纸公约.md` 早就把「逐步推进（每步停等确认）」定为正式模式名，但只有图纸层认识它，
-命令手册层的 skill 只认「只要这版工程」这类**范围**信号。于是用户说「先剪口播、然后我们逐步推进」
-时，逃生门逐字判定为不触发，agent 一路连跑了三个 skill。现在公约新立「节奏信号识别」条款，
-射程覆盖一切会自动接力的 skill；四份命令手册层 skill 的逃生门同时认范围与节奏。
-没有这两类信号时，自动接力的默认一字未改。
-
-### 其他
-
-- `gtrk mg` 铺轨完的提示不再宣称「预览需某个 change 上线」——那个 change 在客户端
-  2026-07-12 就已归档，这行字却一直在误导人。同时立下纪律：用户可见文案不得写死跨仓件名、
-  目录路径或对侧上线状态断言，要表达「暂不可用」得用能自动失效的运行时判据。
-- `gtrk render --json` 回执新增 `audio` 字段（音源盘点与是否无声）。
-
-## 1.1.2（2026-09-03）
-
-### 编排结果多了一份机读账本
-
-`gtrk matrix lay --json` 的回执新增 `lay.arrange_run`：这一轮云端编排调了几次（`rounds` 恒在）、
-每次的编排量与合计（`units_total`，幂等回放的那一轮不重复计）、本地复算与服务端产物有没有差
-（`diff_count` 与 `diffs` 同在同缺，不再出现 `diff_count: 0` 却没有 `diffs` 的假「比过且一致」）。
-只在真的调过云端时才出这个键；走素材矩阵、或总闸压回本地的零回归路径照旧没有。
-
-### 服务端会回报它用的是哪一版决策算法
-
-编排回执带 `decision_pin`：CLI 把它与自己内置的版本号比对，服务端比本机新时采纳服务端产物并把
-自校验差异降为提示，比本机旧或对不上时如实告警。升级 CLI 与服务端不同步时，你会第一时间知道。
-
-### 素材理解的判决只作用于被看过的那一段
-
-`matrix describe` 每个候选只理解一帧，此前那一帧的 `blurry` 等判决会挂到整个候选的所有片段上。
-现在判决只作用于被理解的那一段（回执里的 `describe.at_sec` 就是那一帧的时刻），其余片段按中性处理，
-不再因为一帧模糊就把整条素材降权。
-
-### 其他
-
-- `gtrk patch`：既存违规的判定改用与位置无关的键（元素身份 + 违规码 + 证据值），在既存违规元素之前
-  插入新元素不再把旧账误判成本次造成而硬拒。
-
-## 1.1.1（2026-09-02）
-
-两轮旅拍解说真机复盘（五条素材、27 条问题逐条求证）落地的一批修正，多数是你能直接感知的行为变化：
-
-### BGM 对齐换了语义
-
-- `gtrk audio lay --beat-align` 现在把 **BGM 的情绪峰值锚到成片的高潮点**，锚点前后按小节线平铺补齐；
-  两侧都够长时不平铺。旧行为是把整条 BGM 往后推到首个重拍，片头会凭空多一段静音。
-- 成片高潮点由拆分稿的叙事结构推定（升华段 → 转折 → 回扣 → 0.75 处兜底，兜底档会明说是猜的），
-  可用 `--climax <秒>` 直接指定。
-- 顺带修复：`--no-loop` 此前从未生效。
-
-### 铺画面更准
-
-- 关键词锚改取**原始相似度最高**的合格命中，并为锚预留第一名，不再被前面 beat 的普通槽位吃掉
-  （此前钉过排第 29 的段）。
-- 索引同趟解码并联黑场检测，治「叠化过黑」漏检：匀速渐变的场景切换分数被压到零，此前会把横跨两个
-  镜头的过黑整段包进一颗 B-roll。
-- `describe` 回执如实报「理解帧数 / 段总数」的覆盖率（`describe_coverage`），并对「描述里写了叠加物
-  而对应标记为假」的帧出提示。
-
-### 素材入口更结实
-
-- `--dirs` / `--materials` 能表达含英文逗号的路径（重复传即可），枚举跟随符号链接（跨域照收、断链只跳不崩）。
-- **全域零枚举改为硬失败**：`ok:false`、退出码 1，并点名真因（逗号切分 / 断链 / 扩展名不在白名单），
-  此前是「✅ 完成 0/0」加退出码 0，agent 会接着往下跑。
-- `gtrk tool` 产物目录带唯一后缀防撞，并行两条同类任务不再互相覆盖。
-
-### 图纸与计费口径
-
-- 旅拍图纸：开工两问补为三问（新增源片语种 / 方言，粤语写 `zh-HK`）；写稿语速改按音色的实测挂钟语速取
-  （缺省约 330 字/分，不再用计费常量 240）；写稿前加素材适配性退出闸；检查点①补编排量预估。
-- `is_copyright` 口径写准：`1` = 可商用（自有或已授权），`0` = 不可商用。
-- describe / qc 的计费报数改按实探的成员身份：`credits_estimated` 即实耗，`credits_would_be` 为原价。
-
-## 1.1.0（2026-09-02）
-
-### ⚠️ 升级须知：1.0.8 铺过的工程不会自愈
-
-1.0.8 有一处**槽位接缝**缺陷：铺出的主轨会带 −1 毫秒的同轨重叠，
-`gtrk render` 检出后**硬拒**，成片渲不出来。
-
-- **本版修掉了产生它的原因**，但**修不了已经铺坏的工程**。
-- 手上有 1.0.8 铺的工程 ⇒ 重跑一次 `gtrk matrix lay --project <目录>`，
-  或用 `gtrk patch trim` 逐颗修端点。
-- 升级后打开旧工程仍渲不出，**不是新版没修好**，是那份工程还带着旧缺陷。
-
-另外：服务端的新编排逻辑 2026-09-01 已上线。**1.0.8 与它不配套**——
-本地复算自校验会判定不一致、弃用服务端产物改用本地编排，而那次调用**已经计费**。
-也就是说停在 1.0.8 的每一次云端编排都在白花钱。请尽快升级。
-
-### 编排取数路：本地素材缺省改走云端（补记于 2026-09-03）
-
-这一条随 1.1.0 上线，但当时的更新日志没有写明，补记如下。
-
-- 不传 `--arrange` 时按素材来源自动定档：**铺你自己电脑里的素材 ⇒ `cloud`**（编排在云端做，按编排量计费，
-  跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 ⇒ `local`（编排仍在本机，不计费，行为逐字不变）。
-- 本地素材路**不再自动回落本机**：连不上、被拒、产物违约这类系统故障直接报错，并给出逃生舱
-  `--arrange local`（它是冻结的旧口径，只应急）。你自己拒绝预估确认或开了总闸，仍照旧回落，但会明说换了引擎。
-- 本地复算自校验保持开启：服务端产物与本机算得不一致时如实告警，不会悄悄采纳。
-- 这不是省钱开关：两条路都要花钱，只是花在不同环节（云端编排量 vs 矩阵检索次数）。
-
-### 快速模式不再留黑片
-
-`--gap-fill fast` 的填充顺序从三级扩到五级：
-
-本 beat 候选 → 相邻颗粒延长 → **跨 beat 借候选** → **次地板补真画面** → 仍不够才黑片。
-
-- **跨 beat 借**：某几句自己的候选被别的段先占光时，从全片没人用过的素材里取料。
-  真机 `proj2-B` 的 B18 曾整段 8.952 秒落黑，而全片供给/需求是 4.10× ——
-  不缺料，缺的是分配。借来的画面与那几句稿子相关性会弱一些，日志里**指名报出**。
-- **次地板补真画面**：短于最小镜头长（1.2s）的残洞也填真画面。
-  这些是快切，同样指名报出。真机三条片的黑片从 8 处降到 **0 处**。
-- **逐步模式（`--gap-fill solid`）刻意保留黑片**——黑的地方就是没匹配上的地方，
-  精修时一眼看得见。两档的差别现在不只是「停几次」，是**产物形态不同**。
-
-### 新增：`gtrk audio tighten`
-
-收紧配音的**句间**停顿，纯本地零计费。
-
-```bash
-gtrk audio tighten --project <工程目录> --dry-run   # 先看会压几处
-gtrk audio tighten --project <工程目录>             # 落盘
-```
-
-- 真机实测：一条 203 秒的解说里 54 秒是句间静音（26.6%），收到 0.2 秒后全片缩到 171 秒。
-- **只压跨句界的停顿**，句内换气与原声引用段一律不动。
-- 产物是**原件多 clip 铺轨**，不烤新音频文件 —— 每处停顿都是可拖的刀口，随时能退回原样。
-- ⚠️ 它会改变 beat 窗口，**跑完必须重铺**（命令会提醒）。建议在铺画面**之前**跑。
-
-### 新增：`--fragment-interval`（TTS 句间停顿）
-
-```bash
-gtrk tool audio_tts_clone --text-file 稿.txt --speaker <音色> --fragment-interval 0.2
-```
-
-**仅自训音色生效**；云引擎音色传了会**明确报错**，不会静默忽略。
-不传时产物与本版之前逐字节一致。云引擎音色请改用上面的 `gtrk audio tighten`。
-
-### 其它
-
-- 幂等回放时不再误报「已执行并计费」——服务端命中缓存回放时本就不二次扣费，
-  旧版会无条件断言已计费，把用户引向一笔不存在的账。
-- 随包文档订正：`audio_tts_clone` 的文本上限是 **5000 字**（旧文写 2000）；
-  计量单位与单价一律以 `gtrk tool list` 实时显示为准，文档不再写死。
-
-### 已知问题
-
-- 极少数情况下主轨会留下 **1 毫秒**级的黑片或裸缝（30fps 下 0.03 帧，渲染不可见）。
-  已立案追踪，不影响出片。
-
-### 「刚修好的误删又出现了」——客户端版本下限（补记于 2026-09-04）
-
-本版起，`gtrk matrix` 铺出的每一颗 clip 都带一个**产出方身份**（`producer`），
-用来回答「这颗是我铺的、还是你自己复制粘贴出来的」。有了它，重铺时不会再把你复制出来的副本
-当成自产物删掉。
-
-⚠️ **但这个身份要客户端帮忙保住**，而 **2026-08-26 之前装机的打包客户端不会**——
-它保存工程时是逐键重造 clip 的，不认识的键**存一次就丢**。所以：
-
-- 用旧客户端打开工程、**保存一次**，这一批身份就没了；
-- 下次再 `gtrk matrix` 重铺，判据回落到老口径（材料前缀 + 条数），
-  于是**你复制出来的那颗又会被删掉**——看起来像「刚修好的毛病又犯了」。
-
-**这不是新事故，是回落到本版之前的行为。** 处置：把客户端升级到 2026-08-26 之后的版本，
-然后重跑一次 `gtrk matrix lay --project <目录>` 把身份补回去。
-
-> 身份只在**本机 `.gtrk`** 上存在。工程上云再取回来（经 `video_project_struct` 往返）该键**不会保留**，
-> 这是契约里就写好的，不是缺陷；此时 CLI 自动走老口径，行为与本版之前一致。
+# 更新日志
+
+> 📌 **1.2.6 ~ 1.2.11 六个版本段补录于 2026-09-19**：此前这六版没有版本段，改动全堆在「未发布」里。
+> 判据取自 registry 拉回的包体（`npm pack @gitruck/cli@<ver>` 解包，认 `dist/index.js` 里的**运行期中文串**，
+> 外加随包的 `skills/` `contracts/` `README.md`）——不按提交时间倒推，也不查本机 `node_modules`
+> （那是指向开发仓的符号链接，照它判会把没发的算成已发）。
+> npm 记录的各版 `gitHead`：1.2.6 `c2a0f46` · 1.2.7 `03cd95c` · 1.2.8 `a55fb66` · 1.2.9 `e35f311` ·
+> 1.2.10 `966651c` · 1.2.11 `7a58f02`。
+> ⚠️ **`gitHead` 只是旁证**：1.2.7 是从**带未提交改动的工作区**发的——`link-cloud-font-library` 的实现
+> 在 1.2.7 的包体里逐字可见，却要到 2026-09-19 的 `4ee4f74` 才进仓。判版本归属一律以包体为准。
+
+## 未发布
+
+## 1.3.17（2026-11-09）
+
+- 新：画面三层（unify-visual-layer-planning）。成片画面按「整幅画面归谁管」分成底（讲者、B-roll、AI 片段、图片）/ 版（合成）/ 叠（叠层 OV），正本见随包 `docs/成片型图纸公约.md`「画面三层」一节。拆分稿可选顶层键 `layouts[]` 声明版式窗口（`id` / `span` / `visual_job` / `visual_brief` / `slot_hints`，窗口不占车道、底下的 beat 照常派），`gtrk split` 校验七条后写进 `dispatch.composite` 与 `struct_meta.split.layouts`，人读稿多「版式窗口」一节；整段落在窗口里的叠层不派单（`skipped` 记 `covered_by_layout`）。`gtrk composite plan --mode split` 从拆分稿取窗口（有 `layouts` 键的工程精剪包装改用它，不再 `auto` 另挑）。`gtrk mg status --json` 多 `covered_by` / `covered` / `todo`，整段落在合成窗口里的槽位不产不铺（`skipped` 记 `covered_by_composite`，与出片同口径，不看场景 `takeover`）。合成 `lint` 的机检舞台认图片素材。制片顺序改为字幕 → 合成 → MG，三份框架 skill、八张图纸、风格自建、AGENT.md 与参考文档同步。
+- 改：满屏卡并入合成（merge-fullscreen-mg-into-composite）。标题牌、章节卡、数据卡这类整幅纯排版的卡，拆分稿改写成**零槽位版式窗口**（`zero_slot: true`，可带 `theme` / `bg`，窗口底下的 beat 派 `A_ROLL`），由合成做成满屏卡——**本机烘焙出片、不再云渲计费**（每张约省 1 积分首渲费；内置 AI 写一张满屏卡仍按「颗」计）。`gtrk split` 落地时把旧稿里 `lane: MG` + 满屏类品类（`fullscreen` / `title`，遗留 `mg-fullscreen` / `op-ed-title`）的 beat 自动转成满屏卡（窗口 `L` + beat id，如 `LB07`），回执逐条列出、`--json` 带 `layouts.converted`，拆分稿文件不改；`dispatch.mg` 不再出满屏条目，派单顶层多 `layouts_declared`。零槽位窗口不告「短于 5 秒」、不计 25% 密度。`gtrk composite`：`plan --mode split` 透传满屏卡字段、不写 `layout_hint`，`auto` 的密度预算不扣满屏卡；`scaffold` 给满屏卡只写字幕输入 `subs`；`build` 对声明了画面槽位的满屏卡告警、对删了 `subs` 的场景给定向提示；`status --json` 多 `pending_cards`。`gtrk mg` 只剩叠层：旧派单里的满屏槽位照旧产铺云渲，`status --json` 报 `legacy_fullscreen`；**迁移办法 = 重跑 `gtrk split`**，满屏卡做成合成之前 `gtrk mg` 先留着对应的旧满屏颗粒（`kept_superseded`），做成之后再剥（`removed_superseded`）。满屏卡出片要客户端 ≥ 1.2.13（能烘焙合成）。栏目 MG 风格里的满屏卡怎么迁到 composite 风格，见随包 `skills/gtrk-composite/references/fullscreen-card-migration.md`。
+
+- 新：`gtrk composite materials add <图片> [--from-web-source <来源 id>] [--id <素材 id>]` 把一张图登记成合成 `own` 素材：确认是图片（扩展名 + ffprobe 宽高）、拷进 `gtrk/assets/web/`、原子写入 `composite/materials.json`（同 id 同内容幂等、同 id 不同图报错）；带 `--from-web-source` 时读内置 AI `web_fetch` 落盘的 `web/sources.jsonl`，条目多带 `source` 与出处卡文字 `credit`（`站点｜标题`，只用来源原文字段拼，不经模型改写），裁过的图记 `derived_from`。`gtrk composite materials list` 列出已登记素材、出处与被哪些槽位引用。`scaffold` 的上下文多一段「联网素材与出处」。`gtrk composite lint` 对绑定联网素材的槽位核对出处卡（`data-credit-for` 元素）：缺出处、文字不一致、来源记录已变、指向不存在的槽位四条为致命，图可见而出处卡看不见为告警（`particles[].warnings`）；不含联网素材的颗粒结果不变（add-composite-web-materials）。
+- 新：合成窗口两端对齐换片点（fix-composite-field-findings）。`gtrk composite plan` 各入口与 `review --adjust / --add` 吸附句界与帧格之后，再看窗口边外侧的顶层片段：它横跨窗口边（窗口里本来就在播）、出窗后 0.6 秒内就换片的，把窗口外扩到那个换片点，迭代到稳定、不越过相邻窗口；窗口边之后才开始的新片段（例如有意铺的转场）一律不碰。外扩逐条写进回执 `edge_snaps`、`plan.md` 与窗口理由（挪了多少毫秒、原来露几帧）。`gtrk composite lint` 用同一判据查 `edge-flash`（读当前时间线，已铺的颗粒照样查），点名哪颗、哪端、哪条轨的哪段、露几帧，给出 `review --adjust` 建议值。治合成一结束先闪出几帧 B-roll 尾巴再回到讲者。
+- 改：`gtrk composite review --adjust` 能调已铺的窗口（仍记已做），并同步已起场景规格里的 `window`（回执 `scene_sync`）——此前场景照旧窗口构建，lay 又把计划窗口改回旧起止（fix-composite-field-findings）。
+- 改：合成工具箱的缺省变量从 `#stage` 挪到 `:root`：`composite/theme.css` 只写 `:root { --bg: … }` 现在就生效——此前舞台元素读到的仍是工具箱写在 `#stage` 自身上的值，只能写成 `:root, #stage` 绕开；旧工程的 `:root, #stage` 写法照样生效。屏上文字类缺省字号抬到社媒地板 32px（`.tag` 26、`.kicker` 28、`.num` 30、`.pill` 28、`.ptag` 26 → 32，标签盒高随之加高），出处卡 `.credit` 补缺省样式（24px 白字配深色半透明底条）。工具箱版本号不变（`composite-kit@2` 记的是宿主协议），已铺颗粒不会因此变「需重渲」；重跑 `build` 的颗粒才用上新样式，烘焙随之重烤一次（fix-composite-field-findings）。
+- 改：`gtrk composite lint --stills` 写明填时间线秒；落不进任何合成窗口时报错列出各窗口的时间线起止，这个值按局部秒能落进窗口时给出对应的时间线秒。浏览器放不了的素材封装（m2ts / ts / avi / mpg / wmv / flv）不再让静帧卡 60 秒后整条报错：静帧里那个槽位空着并告警（以烘焙或客户端预览为准）；某张静帧出不来时其余照出（fix-composite-field-findings）。
+- 修：`gtrk composite lint` 遇到前景层空的 `<path d="">` 只报「颗粒无回应」、指不到病因：现在机检先把空路径挪开再查、查完放回，记 `empty-path` 告警点名是哪一个；工具箱排版自检真报错时按帧记 `lint-error`（带原因，不再等 8 秒超时）；某颗逐帧机检没跑完记 `lint-aborted`，不再拖垮其余颗（fix-composite-field-findings）。
+- 修：`gtrk subtitle lay` 把「近1/3」铺成「近1//3」：转写的字级时码把 `/` 单独出成一个词，挂回原文标点时又把它挂给了前一个字。下一个词就是原文这里的符号时不再挂给前字（`50%` 同理）。客户端一键上字幕用的是同一份 `caption-align.ts`，待同步（fix-composite-field-findings）。
+- 改：`gtrk qc contact-sheet` 清单里每格写了 `label` 就照用，`beatId` 不再必填；标签含中文时用系统中文字体（微软雅黑 / 苹方 / Noto Sans CJK 等），不再画成方块；带冒号、单引号、百分号的标签不再让 ffmpeg 整条报错（drawtext 转义按三层改正）（fix-composite-field-findings）。
+- 改：`gtrk-composite` skill。「风格」：栏目没有 composite 风格、但有 `produces == "MG"` 的风格 skill 时，MUST 先读它、以它为正本按它的硬规则定 `theme.css`（主题怎么选、底色是否分阶段迁移、焦点色稀缺、单页语义色上限、字号地板与字幕安全区、动效密度、图标与线型），场景里不写死色值；窗口内字幕与窗口外全片字幕同款（从工程字幕样式读，进出窗口不跳）；编排规则补「窗口边与底轨片段边对齐」（现第 10 条）；场景速查补字号地板；「已知限制」补 lint 静帧放不了 m2ts（烘焙正常）；排错表补 `edge-flash`、静帧局部秒、`empty-path`、`lint-error` / `lint-aborted`（fix-composite-field-findings）。
+- 新：合成槽位复用片段的去字幕 / 水印遮罩：`composite bake` 与 `composite lint --stills` 按片段 `element_state` 里启用的去水印区域给槽位取的帧套模糊（ref / ref-lane 取该片段的，own 取同素材全部片段并集），模糊度、羽化与客户端时间线一致；烘焙缓存键含实际套上的遮罩；`--abi` 的 `host_features` 增 `slot-dewatermark`。出片台改动后已有合成烘焙缓存各重烤一次（add-composite-slot-dewatermark）。
+- 改：`gtrk-composite` skill 编排规则新增第 3 条「合成与底轨融合，不切两半」（原 3–9 条顺延为 4–10）：不用不透明底板把画面切成左板右人 / 左板右图；讲者 / 素材满幅不挪，包装叠在约 0.6 不透明度、向画面羽化的半透明衬底上；讲者段可加毛玻璃（同路讲者另开满幅模糊槽位垫底、清晰讲者左裁对齐、分界藏在衬底满浓度区、开窗时模糊从 0 渐起）；衬底给视频槽位开洞；同画面交接时开窗渐起、出窗前约 0.4 秒退让，接换片时随剪点切走；满屏卡不受约束；栏目 MG 风格 skill 有更具体的衬底规则时以栏目为准。场景写法速查补三句（`data-filter` / `data-crop` / 槽位框每帧重读可动态改；前景层 `<path>` 含 `<mask>` 里的会被当线条查、描边遮罩用 `<rect>`；图标飞入路径别扫过视频槽位），新增「槽位里的去字幕 / 去水印」一小节，规则 4（裁黑边与烧录字幕）补「已挂去字幕 / 水印遮罩的交给遮罩、别再硬裁」。
+- 修：`gtrk composite review --adjust` 与片段边吸附改了窗口起止后，`composite status` 仍报旧窗口：窗口的 `source_ranges` 没跟着改，`status` 又按「源时基落在区间内的整句」取句包络，对齐到换片点的窗口投影不回来。现在改起止（`review --adjust / --add`、plan 的片段边吸附、`lay` 按颗粒回写）时按口播片段重算 `source_ranges`（端点落在空档里取窗口内侧最近的保留帧），`status` 与 `gtrk mg` 的接管判定改按口播片段投影回时间线（与客户端 CP 行同一算法）。旧窗口要用上新值，重跑一次 `review --adjust`（fix-composite-field-findings）。
+- 修：`gtrk composite bake` 槽位取画面时片段的首末帧按帧格取：片段边先吸到第一个不早于它的采样帧再比（与客户端底轨同一口径），片段之后 / `ref-lane` 空档定格的是底轨真正显示的最后一帧——此前取 `track_ed − 1/帧率`，终点不在帧格上时比底轨末帧早，恰跨源帧边界时定格成底轨从没显示过的前一源帧；窗口前无片段时取后段在底轨上的首帧。帧格上的采样时刻逐帧不变；出片台改动后已有合成烘焙缓存各重烤一次（fix-composite-frame-edges）。
+- 修：`gtrk composite` 放行语法错的场景脚本（fix-composite-agent-run-findings）。实例：场景里一个行内 `//` 注释吃掉了同一行的右花括号，整段脚本不执行、`CP.render` 没设上，画面全停在默认位置，`lint` 却报 0 问题、照出静帧。现在 `build` 先按浏览器同一套语法解析场景脚本，语法错就这颗构建失败、报场景文件第几行，行内注释吃括号的另报「疑似病因」；`lint` 静态报 `script-syntax`（`lay` 也拒铺），逐帧时颗粒加载就抛错记 `script-error`（带行号）、页面上没有 `CP.render` 记 `render-missing`，都判不过，这类颗粒不出静帧（`stills_failed` 写明原因）；render 在某帧抛错时报原文，不再只剩「颗粒无回应」。
+- 改：`gtrk composite scaffold / build / lint / lay / bake --only` 窗口 id（`W21`）与颗粒 id（`cp-w21`）都认，大小写不敏感——此前 `--only W21` 一个都选不中，`build` 还静默成功。一个都没选中时报错并列出现有的；规范 id 精确比，`W2` 不再串选 `cp-w20`–`cp-w29`（fix-composite-agent-run-findings）。
+- 修：合成窗口边吸附吞掉有意的短插入（fix-composite-agent-run-findings）。横跨窗口边的片段短于 1 秒、不在口播主轨上、另一头落在窗口里（栏目 OP、转场、卡点短镜）时，窗口收到它的边上让它完整露出，不再外扩吞掉；窗口里本来就在播的长片段尾巴照旧外扩。回执 `edge_snaps` 每行多 `action`（`shrink` 收 / `extend` 扩）与 `reason`；`lint` 对盖住短插入的窗口报 `edge-insert`。`review --adjust / --add` 新增 `--no-edge-snap`：给的起止原样保留（只投影帧格），只告警照常会怎么挪，窗口记 `edge_snap: false`，之后 `lint` 对它的窗口边问题只告警。
+- 新：合成窗口越过口播告警（fix-composite-agent-run-findings）。`plan`、`review --adjust / --add` 与 `build` 发现窗口任一端越过口播（终点晚于最后一句、起点早于第一句）超过 1 秒时，回执 `warnings` 写明越过几秒、盖住的是什么（哪条轨的哪段，纯色垫片点明黑场 / 色底，没画面写空档），提示确认是有意为之；只告警，不改窗口。实例：收尾窗口被拉到片尾，盖住了 14.5 秒母版黑场。
+- 改：`gtrk-composite` skill 补六条：锚点关键词照 `cp-wNN.context.md` 原句抄，不凭拆分稿转述；派单给子代理 / 颗粒档写了「不要再读 skill」就把栏目 MG 风格 skill 的硬规则要点原文写进订单（`gtrk-mg` skill 同步）；窗内暗底迁亮底按 `t` 挂 `dark` 类、过渡用 `color-mix`；字幕贴字底条同时写 `span:empty { padding: 0; background: transparent; }`；选片核对用联系表与静帧、一次读两三张；改起止写明理由，越过口播先问用户。编排规则 10 补「短插入先收」与反例，排错表补 `script-syntax` / `render-missing` / `edge-insert` / 越过口播 / `--only`（fix-composite-agent-run-findings）。
+- 新：`gtrk composite lint` 契约检查（add-composite-contract-checks），在渲染静帧之前就报、报文带改法。致命三条：`slot-css-ignored`——槽位元素的内联样式、命中它的样式规则、场景脚本赋值（含 `wipe()`）或逐帧计算样式里写了对视频无效的 CSS（`filter` / `clip-path` / `mask` / `border-radius` / 旋转斜切的 `transform` 等），提示改用 `data-filter` / `data-crop` / `data-shape` / `at()`；`slot-filter-unsupported`——`data-filter` 不在客户端白名单（客户端整串丢弃、烘焙却照画）；`slot-never-placed`——规格声明的画面槽位 render 里从没 `at()` 放置过（实例：W30 三个讲者槽位一次都没放、整颗空白），循环里放这类静态认不出的由逐帧机检「从未可见」兜底，没有浏览器时只告警。告警三条：`no-anchors`（窗口有口播、场景既没锚点也没 `A()`，点名写死的分拍秒数）、`kit-class-collision`（自定义了与工具箱同名的 `.card` / `.rule` / `.pill` 等却没覆盖它给的背景 / 高度 / 圆角——实例：`.card` 被刷成白底圆角挡住视频、`.rule` 高度锁成 3px 文字叠在一起）、`small-text`（屏上文字 < 32px；有浏览器时按缩放后的有效字号）。`gtrk composite lay` 铺之前也跑这三条致命规则的静态部分（不起浏览器），不过就拒铺、报文与 lint 同一句；静态认不出放置的不拦，回执 `warnings` 提示先跑 lint。工具箱 `kit.js` / `kit.css` 与颗粒字节不改。
+- 改：`gtrk composite scaffold` 按窗口形态给起手模板（add-composite-contract-checks）：讲者段（讲者主轨露出过半）= 三路同源毛玻璃 `frost` / `frost2` / `presenter`，`data-filter` 起雾、`data-crop` 左裁像素对齐、半透衬底 `#veil` 用 mask 羽化；素材段 = 素材满幅 + 半透衬底；满屏卡（零槽位）= 开窗 0.35 秒内落位的骨架。三种都把窗口里的口播原句预填成锚点、分拍走 `A()`，颜色只用主题变量、类名不撞工具箱，竖屏按讲者 / 素材在上、板在下排。回执多 `shapes[]`；已有场景照旧不覆盖（`--force` 才重起）。此前骨架只有一个讲者圆窗。
+- 改：`gtrk-composite` skill 补「工具箱预置类一览」（kit.css 里会作用到场景的通用类、关键缺省值与撞名时要覆盖的几项）与「槽位契约一页纸」（`data-slot` / `data-z` / `data-fit` / `data-shape` / `data-radius` / `data-crop` 上右下左 / `data-filter` 白名单 / `data-layer` / `data-for`，`at()` / `look()` / `place()` 对槽位做什么，哪些 CSS 对视频无效），按 kit.js / kit.css / 出片台与客户端的实际行为写；scaffold 一步、机检一步与排错表同步（add-composite-contract-checks）。
+- 改：CLI 自己说清 API Key 去哪拿。安装命令不只出现在同合云官网，客户装完常不知道去哪取 Key；现在每个要 Key 的地方都指路——打开 https://cloud.ai-mcn.tv/zh-CN ，点「注册 / 登录」（登录即开通），进入「仪表盘」复制 API Key。出现在：`gtrk init` / `gtrk install` 的 Key 输入框前先给这句，还没有 Key 时在输入框直接回车会替你用浏览器打开官网（只开一次）；非终端跑 init、`-y` 缺 `--api-key`、命令缺 Key 报错（原句「缺 API Key —— 先跑 `gtrk init`…」开头不变，后面接指路）、`gtrk doctor` 的 API Key 未配行与鉴权失败行、`matrix` 鉴权失败、`--api-key` 的帮助说明、首跑指路块的 `gtrk init` 那一步都带上了。文案单一副本在 `src/lib/api-key-guide.ts`；随包五个 skill 的缺 Key 处置、AGENT.md、参考文档与中英 README 同步。
+
+## 1.3.16（2026-11-07）
+
+- 与 1.3.15 内容相同的重发：npm 上两版 `gitHead` 都是 `0da78f5`、文件数与解包大小一致；当时版本号改动未进仓，本段为 2026-11-09 补记。
+
+## 1.3.15（2026-11-07）
+
+- 新：`gtrk matrix describe --layout grid` 可选让服务端把帧拼成 3×3 宫格一次理解，同一 beat / 检索词的候选尽量拼在同一页；缺省仍逐张（`--layout single`），计费不变（1 积分/张）。服务端是否真按宫格执行只看回执：未升级或被运维停用时如实说明「按逐张理解」，`--json` 带 `layout_receipt` / `layout_counts`。宫格产物的 mark / highlight 只在同一页内可比、景别与黑边不如逐张稳，人读输出会提醒；缓存记下产出方式，逐张运行不复用宫格产出的缓存（`--json` 的 `stale_layout`）。需服务端同步上线宫格批量后才生效（link-add-material-describe-grid-batch）。
+- 新：`gtrk matrix search` 的 `--query` 可重复给，几个角度一次跑完：结果按素材合并（留最高分），逐条标 `matched_queries`、按分数排，回执带 `queries`；只给一个检索词时输出不变。外网检索仍一次一个词（fix-agent-harness-feedback）。
+- 新：`gtrk matrix search --estimate-only` 只报这次最多花多少积分、不检索：`--json` 的 `billing_estimate: {credits, basis}`（成员口与 `--local` 为 0，公开口按价目表 × 检索词数，算不出为 `null`）。`gtrk oralcut` / `gtrk long2short` 的 `--dry-run --json` 同带 `billing_estimate`。即剪内置 AI 据此对估价不超过 100 积分的命令不再弹确认（fix-agent-harness-feedback）。
+- 新：`gtrk matrix search "<词>" --beat <id> --project <目录>` 把结果写进这个 beat 的候选池：并进本层快照 `split/broll-plan.<层>.json`、追加进工程候选登记，客户端 B-roll 面板立刻能看到，`gtrk patch add --candidate` 直接认得；不铺轨，重跑不重复（fix-agent-harness-feedback）。
+- 新：`gtrk matrix lay --pool-only [--beat <id,…>]` 只把 plan 里还没进工程候选池的候选登记进去——不铺轨、不下载、不动任何轨，也不需要联网。治「`matrix status` 报 `not_in_pool`、面板里看不到」；此前只能跑局部 `matrix lay`，会按铺轨口径另起一条候选轨（fix-agent-harness-feedback）。
+- 新：`gtrk patch add` 一次放多段：`--to 263.7 --candidate A --to 266.2 --candidate B`，`--to` 每给一次是一段，`--candidate` / `--material` / `--track` / `--beat` / `--from` / `--dur` 只给一次就各段共用、给同样多次就按顺序配对。一次下载、一次写回；同一条轨上前一段缺省停在后一段起点；某段出错报「第 N 段」、整批不写（fix-agent-harness-feedback）。
+- 新：`gtrk patch remove (--clip <id> | --track video:<N> --at <秒>)` 删掉一个片段，原位置留空、后面的片段不动；视频与同 id 的镜像音频一起删；`--ops` 里也能用（fix-agent-harness-feedback）。
+- 改：`gtrk patch add / replace` 放上轨的候选只在 plan 里、不在工程候选池时，顺手登记进该 beat 的候选池（层取它所在那份 plan），回执 `source.pooled`——此前轨上有画面、面板里却找不到这条候选（fix-agent-harness-feedback）。
+- 改：`gtrk client state` 读到客户端实时状态时带 `disk`：与盘上工程的轨号对照（客户端有没保存的轨道增删时两边会错开）、是否有未保存改动；对不上时 stderr 提示 `gtrk patch` / `gtrk matrix` 按盘上的轨号写（fix-agent-harness-feedback）。
+- 改：`gtrk matrix status` 顶层带 `video_tracks[]` 全工程视频轨总览（轨号、口播主轨、判定、来源层、片段数），人读首行列出（fix-agent-harness-feedback）。
+- 修：重铺某一层时，候选池里「添加视频链接」/ `gtrk matrix source-import` 导入的候选（没登记来源层）被当成老式条目洗掉；客户端随后把导入任务当检索翻页，「加载更多外网候选」报「更多候选来源或时间段不一致」。现在手动导入的候选哪一层重铺都保留，连同它的导入任务号；没登记层但来自外网的候选按外网层算（fix-agent-harness-feedback）。
+
+## 1.3.14（2026-11-07）
+
+- 修：`gtrk patch --ops` 清单里的时刻写成 JSON 数字（如 `"at": 375`）时，按 `track` + `at` 寻址的动作崩在 `f.trim is not a function`；现在数字与字符串同一口径（`at` / `to` / `cut` / `track` / `total` 均可）（fix-matrix-partial-relay 3.2）。
+- 修：`gtrk matrix` / `gtrk matrix lay` 重铺某一层时，plan 只含这一层的部分 beat（只补空缺）会把同层其余 beat 的候选登记整个冲掉——客户端 B-roll 面板显示「这个区域还没有素材」，原来的候选池也没了；旧轨若没被动过，那些 beat 的画面也会被一并剥掉。现在 plan 外的 beat 原样保留：本层旧轨上属于它们的片段按原轨序带到新轨（旧轨比本轮 `--lay` 多时本层带区相应加宽），候选（含老式无层登记的）、外网检索任务号与 laid 登记照旧；与本轮 plan 内 beat 时间窗重叠、带不回的旧片段丢掉并告警。人读出一条「局部重铺：…其余 N 个 beat 原样保留」，`--json` 带 `lay.partial_relay`。plan 含这一层全部 beat 时行为不变（fix-matrix-partial-relay）。
+
+## 1.3.13（2026-11-06）
+
+- 新：`gtrk matrix --online --online-concurrency <n>`（1–8，缺省 3）：外网检索按派单顺序提前提交、同时至多 n 单，不再一单跑完（8–11 分钟）才提交下一单；plan、逐条日志与进度落盘仍按派单顺序，和串行时一样。提交与进度日志带 beat 名。`1` = 旧行为（fix-matrix-layered-plans-and-ux）。
+- 改：每轮检索除主 plan `split/broll-plan.json` 外另存本层快照 `split/broll-plan.<层>.json`（local / online / concept / common；外网零候选、主 plan 被保住时不写），`--json` 带 `layer_plan_path`。换层检索覆盖主 plan 后，别的层仍可 `gtrk matrix lay --plan split/broll-plan.<层>.json` 重铺；`gtrk patch --candidate` 与 `gtrk matrix status` 连同快照一起找候选（主 plan 优先）。概念层检索的 plan 带 `source_layer: "concept"`，`matrix lay` 据此铺进概念层（此前会被当成通用层）；其余层不写该键，既有 plan 不变；`source_layer` 与 `member_type` 不配套的 plan 拒收（fix-matrix-layered-plans-and-ux）。
+- 改：`gtrk patch add / replace` 放上 / 换过的片段带 patch 自己的产出方身份（此前 `add` 不写、`replace` 删掉），所在候选轨判「已编辑」：同一层再 `matrix lay` 拒铺（`tracks_edited`，工程零改动），不再当成你的轨保留、另铺一条越铺越多。整条都是 patch 放的、又不在铺轨登记里的轨仍算你的轨（fix-matrix-layered-plans-and-ux）。
+- 改：已编辑候选轨的拒铺只看本轮要铺的层：别的层的已编辑轨（客户端确认过原片的、patch 改过的）随它的层带保留、不挡本层铺轨，`--force-relay` 也不剥它；告警写明「本轮铺的是 X 层，不动它」。`gtrk matrix status` 的 `lay.edited_track_layers` 报出各已编辑轨所属的层（fix-matrix-layered-plans-and-ux）。
+- 新：铺轨后点名被地板藏起来的候选——整条分（`result.score`）过了 `--score-floor`、片段分（`segments[].score`）却全低于它、一条也没铺上的，逐 beat 报条数与最高片段分，并说明地板卡的是片段分、给出调低地板或钉选两条出路；`--json` 带 `lay.floor_hidden`。`gtrk matrix status` 的候选带片段分（`seg.score`），与整条分不同时人读输出并列「（片段 x）」；`--score-floor` 帮助写明卡的是片段分。地板算法不变（fix-matrix-layered-plans-and-ux）。
+- 改：已装的 gtrk skill 落后于 CLI 包时，没被你改过的（已装副本与安装时的戳一致）直接换成包内版本、只说一行「已把 N 个 gtrk skill 更新到当前 CLI 包的版本」；改过的、换不动的、新加的照旧提示 `gtrk skills install`。`GTRK_SKILL_FRESHNESS=off` 同时关掉自动换新（fix-matrix-layered-plans-and-ux）。
+- 改：`gtrk matrix --online` 不带 `--platforms` 时只检索 `youtube` / `vimeo` / `bilibili` / `pexels`，TikTok 须显式写进 `--platforms`（服务端 TikTok 发现改走按次计费的 TikHub）。升级前同一批次（`--online-session`）按旧缺省（五平台、最早的四平台）建过单的，照旧沿用原请求续跑、不新建单、不重复扣费；要按新缺省检索请换批次名（link-online-broll-tikhub-discovery-cli）。
+- 修：外网检索产出的 plan 被 `gtrk matrix lay` 整单拒收（「segment cuts 须为升序有限数字且严格落在 (start,end) 开区间内」）。服务端把片段起止点本身也列成切点：现在写进 plan 前去掉这些端点切点，`matrix lay` 校验也容忍恰在段起止点上的切点，盘上已有的旧 plan 不用改就能铺；乱序、越界照旧拒收（fix-matrix-online-relay-and-review）。
+- 修：`gtrk patch add / replace --candidate` 在工程根目录本身叫 `gtrk`（`<x>/gtrk/project.gtrk` + `<x>/gtrk/split/`）时读到外层 `<x>/split/broll-plan.json`，报「都没有候选」。现在与 `gtrk matrix` 同一口径：给了 `--project` 且其下有 `split/` 就以它为根，否则看工程文件所在目录有没有 `split/`，再否则退到 `gtrk/` 的上一级；找不到候选时报错写出实际读的 plan 路径（fix-matrix-online-relay-and-review）。
+- 修：外网检索没有可自动铺的候选、只有待人工确认候选（需求里的地点 / 事件 / 年份 / 素材类型等硬条件服务端核实不了）时，CLI 此前报「0 条候选」或「外网平台或素材处理失败」、计入 `errors`，还建议「调整检索描述后重试」（换描述会新建计费任务）。现在逐条写「0 条自动候选，另有 N 条待人工确认」、不计 `errors`；汇总单独列出，说明它们在 plan 的 `queries[].online.review_candidates`、挑中后移进 `results`（可加 `pinned:true`）再 `gtrk matrix lay` 即可铺，并说明不必重跑；铺轨阶段的零候选告警点名各 beat 的待核条数（已进客户端候选池）；`--json` 的 `counts` 加 `review_only` 与 `review_candidates`，既有字段不变。真正零召回的仍给重试建议（fix-matrix-online-relay-and-review）。
+
+## 1.3.12（2026-11-05）
+
+- 新：`gtrk patch add --track video:<N> --to <秒> (--candidate <clip_id> [--beat <id>] | --material <id>) [--from <秒>] [--dur <秒|Nf>]`，把一条 B-roll 候选或已登记素材放到视频轨的空位上：候选先查工程候选池（含邻居）再查 `split/broll-plan.json`，素材还没登记时顺手下载预览到 `assets/broll-preview/` 并登记（与 `gtrk matrix lay` 同一份落地实现，已登记的不重下）——`matrix source-import` 之后一条命令就能上轨。缺省时长取落点所在空位、出点与右邻同一帧；入点缺省与客户端拖候选同一取窗。落点与已有片段重叠即拒并列出挡路片段（黑底补片指路 `patch replace`），覆盖到的空档让位；源片不够长钳短告警、不拉伸；图片候选不收；不建轨、不 ripple。新片段 `<beat>-add-<n>`、不带产出方身份（add-patch-insert-replace）。
+- 新：`gtrk patch replace (--clip <id> | --track video:<N> --at <秒>) (--candidate … | --material …) [--from <秒>]`，原地换源：只换素材与源窗，起点 / 轨 / `clip_id` / 倍速 / 变换 / 填充 / 转场 / 关键帧不动；新素材不够长如实缩短（`replace_shortened`），不拉伸；去掉产出方身份，下一次 `gtrk matrix` 铺轨把这条轨当用户轨保留；镜像对不收（add-patch-insert-replace）。
+- `add` / `replace` 先按自述值把全部改动算一遍、全档校验，过了才下载落地，落地完再读工程写回；`--dry-run` 不下载、不写文件，回执带 `would_download`；`--ops` 条目可用这两个动作，同批先统一落地。回执 op 另带 `source` 与 `gaps_consumed`。预览下载失败零写、非 0（`preview_download_failed`），已落盘的预览留作下次复用（add-patch-insert-replace）。
+- 修：`gtrk patch` 的未知动作报错与 `--ops` 合法动作列表此前漏列 `seal` / `snap`，现在列全（`seal` / `snap` 是轨级动作，只能单发）（add-patch-insert-replace）。
+- 改：`gtrk matrix` 铺轨的候选落地（代理文件名、复用 / 下载、ffprobe 实测、素材条目）抽到 `src/lib/broll-landing.ts`，与 `patch add / replace` 共用；同输入铺轨产物、日志与 `--json` 回执与抽出前逐字节相同（add-patch-insert-replace）。
+- 新：`gtrk matrix status --project <工程目录> [--beat <id>[,<id>…]] [--json]`，一条命令看清某个 beat 的现状：时间窗（现场重投影，降级时标明原因）、候选池（精简字段、不带下载地址，标出预览是否已落地、已用在哪些片段上）、plan 里其余候选的条数与得分最高 5 条、时间窗内各视频轨上的片段与类别、主轨之上的空缺（另列只有黑底补片的区间，短于一帧的缝不算）；不带 `--beat` 时全部 B-roll beat 一行一个概要。顶层给工程 `revision`（可作 `gtrk patch --expected-revision`）、各候选轨剥离判定与整轮重铺会不会被 `tracks_edited` 拒。只读、不联网、不需要 Key、不写任何文件；beat 不存在时退出码 1 并列出全部已知 beat（add-matrix-beat-status）。
+- 新：外网检索授权码。`gtrk matrix --online` 检索和 `gtrk matrix source-import` 导入完成后，CLI 用当前 Key 向服务端取这次检索的授权码，写进每条外网候选（含待核候选）的 `origin.search_grant`，plan、回执与工程都带上；工程交给别的账号后，对方凭它在客户端读候选、确认 B-roll。服务端还不支持（404）、未启用或网络失败时照常完成，只是不带码，终端提示一行（派单多条检索时同一原因只提示一次）。格式不对（不是 `g1.` 加 43 位 base64url）的授权码解析时丢掉，候选照常可用；`gtrk matrix lay` 原样带进工程（link-online-broll-search-grant-cli）。
+- 新：`gtrk matrix grant --project <工程目录或 .gtrk>`，给工程补检索授权码（授权码上线前的老工程也适用）。只为一个码都没有的检索取码，同检索已有码的直接沿用；取不到的（不是当前账号的检索、已删除、服务端不支持）逐个列任务号与原因，候选不动，退出码非 0；输出「补了几个、已有几个、取不到几个」，`--json` 给 `granted` / `existing` / `failed`。工程没有变化时不写盘，有变化时原子写回、只改外网候选的 `origin`（link-online-broll-search-grant-cli）。
+
+- 新：`gtrk cover embed <工作台.html> [--bg-16x9 <图>] [--bg-4x3 <图>] [--bg-3x4 <图>] -o <输出.html>`。封面工作台把背景图按尺寸压成 JPEG（16:9 长边 ≤1280、4:3 ≤1600、3:4 ≤1400）并以 base64 嵌进去，替掉 `/gtrk-cover` 里「临时脚本压缩 + 注入」那一步；纯本地、零计费，压缩结果经管道回内存、不写中间图片。`-o` 必填（可与输入同名），没给图的尺寸占位符保留并提示，工作台超过 600 KB 提示、超过 1 MB 告警（link-in-app-agent-capability-shelf）。
+- 新：`gtrk ai-drama validate <候选分镜稿.md> [...]`。`/gtrk-ai-drama` 落盘前的分镜稿校验收成子命令，判据、输出与退出码与随包的 `scripts/validate-storyboard.mjs` 逐字节一致（脚本再保留一个版本周期）；即剪内置 AI 只许运行 gtrk，这一步此前跑不了（link-in-app-agent-capability-shelf）。
+- 新：`gtrk-cover` / `gtrk-tools` / `gtrk-transcript` / `gtrk-matrix` / `gtrk-ai-drama` / `gtrk-music-visualizer` / `gtrk-ref-reading` 标 `in_app_agent`：即剪内置 AI 每轮常驻这 7 个 skill（加上原来的 4 个共 11 个），客户端输入区「常驻能力」里的封面制作、小工具等入口据此出现；测试闸照常守住「要 agent 执行的命令全是 gtrk」（link-in-app-agent-capability-shelf）。
+
+## 1.3.11（2026-11-04）
+
+> 本段补录于 2026-11-05：1.3.11 于 2026-11-04 从 `7f605ce`（版本号改动未提交的工作区）发出，当时没写版本段，改动留在「未发布」里。
+> 归属按包体抽查：本机装的 1.3.11 `dist/index.js` 里有 `--neighbors`、转场、音频淡变、`volume_zero_use_muted`、`--redraw`，
+> 没有检索授权码、`patch add` 的 `would_download`、分镜稿校验——与「`7f605ce` 之前进仓的归 1.3.11、之后的归 1.3.12」一致。
+
+- 新：工程片段的**转场**（即剪客户端写进 `.gtrk` 的 `transition_in` / `transition_out` / `transition_next`）CLI 全程认得、本期不产出。任何命令都原样带着转场走，新铺的片段不带转场。`gtrk patch split` 入场转场留前段、出场与接下一段的转场归后段（此前两半都复制同一个转场，前段那个立刻悬空、切口凭空多出一个入场）；每次 `gtrk patch`（单发或整个 `--ops` 批）写回前对改动过的轨统一维护：下一段被移走后不再紧邻的「两段之间」转场删除（不改挂到新邻居），剪短后放不下的按帧缩短（先头后尾），回执逐条给 `transition_dropped` / `transition_shortened`；与本次编辑无关的存量转场问题只报不拦。`matrix` / `mg` / `ai-drama` / `pip` / `audio` / `composite lay` 重铺自产轨时，被替换掉的片段若带你在客户端加的转场，日志与 `--json` 回执给出 `replacedTransitionClips`。`gtrk project export` 上行前把工程规整一遍（悬空、越界的删缩并列进 `result.json` 的 `transitions`，盘上工程不动），免得云端整单拒收；云端各格式本期不承接转场，导到剪映 / Pr 里是硬切，回执里的 `transition_not_carried` 逐条打出。`gtrk render` 本期按硬切出片并计 `transition_not_carried`（无转场工程滤镜串逐字节不变）。转场颗粒目录不随 npm 包分发：工程带转场时才从后端拉 `cloud/static/assets/transitions/catalog.json`，缓存在与客户端共用的统一静态资源缓存 `~/.gitruck/cache/transitions/catalog.json`（24 小时一刷）；离线、目录不可用或颗粒不在目录里时转场原样保留，命令照常工作。⚠️ **编辑含转场的工程需本版本及以上**：旧版不报错，但切分会复制转场、移动后留下悬空转场、重铺静默删掉用户的转场、上云被拒收（link-gtrk-clip-transitions）。
+
+- 改：`gtrk mg fetch` 的 MG 区块与文字模板（`--source text`）改走统一静态资源下发，目录格式与本机缓存同即剪客户端共用一套（unify-static-resource-delivery）。
+  - 文字模板：目录缓存从 `~/.gitruck/text-templates/` 挪到 `~/.gitruck/cache/text-templates/`（旧位置不再读，首次联网自动重拉）；拉到远端目录即用，不再按版本号择新（服务器回滚就是换回旧目录）；正文按内容寻址取，每份都校 sha256 与字节数，命中本机缓存不打网。候选不再列「预览」（封面从未发布过）。
+  - MG 区块：候选态照旧零网络（读本机缓存的目录，没有就用随包快照）；取块前先刷新一次目录（24 小时一刷，缓存在 `~/.gitruck/cache/mg-registry/`），镜像改为同合云优先、取不到再经 GitHub raw / jsDelivr fastly / jsDelivr gcore / gh-proxy 回源；目录里块被下架或改判 excluded 时按刷新后的目录拒取。
+  - `GITRUCK_TEXT_TEMPLATE_BASE` / `GITRUCK_MG_REGISTRY_BASE` 现在指镜像根：`<根>/catalog.json` 与 `<根>/files/…`（即统一发布的暂存包 / 静态盘布局，不再是 `blocks/<名>/<文件>`），设了就只用它，不写本机缓存。
+  - `--json` 回执：取块与候选多了 `catalog`（目录版本与来源）；命中本机缓存时 `fetched_from` / `source` 是 `cache`、`url` 是 `null`；全部镜像失败的报错改为逐个镜像列原因（不再是「三源皆不可用」）。
+
+- 改：`gtrk deps install --font` / `--font-family` 改从统一静态资源下发的字体目录装（`cloud/static/assets/fonts/catalog.json`，与客户端同一份目录、同一套命名），不再读字体库 `manifest.json`。`--font` 装的是目录顶层登记的字幕字体（思源黑体 CN Bold，落 `~/.gitruck/fonts/sourcehansanscn-bold.otf`）；每款都校 sha256 与字节数，取不到时逐个镜像说明原因、不落半成品；字体文件不另存一份到 `~/.gitruck/cache/`。已装按文件名归一比对，历史命名 `SourceHanSansCN-Bold.otf` 也算已装、照旧跳过；`--force` 重下时换成目录里的命名。`gtrk deps status` 的字体一行改报目录版本、族数 / 款数与字幕字体装没装（unify-static-resource-delivery）。
+
+- 新：`gtrk matrix --neighbors <n>`（0–5）。矩阵成员检索概念素材时，命中镜头连同它在原片里前后各 n 个镜头一起带回，适合接成一串蒙太奇。
+  - `matrix search` 加上它后，有邻居的结果下面会按原片顺序列出整段（不相接处标 `⋯`），并给出现成的 `gtrk matrix fetch` 命令，邻居可直接拉原片。
+  - 派单检索缺省带 2：邻居写进工程，在客户端 B-roll 面板里折叠，由你单张挑选，不参与自动铺轨；`--neighbors 0` 关闭。
+  - 服务端返回的出处字段 `source` 在 CLI 里改叫 `source_ref`（link-clip-search-neighbors-cli）。
+
+- 改：`gtrk audio lay --volume 0`（含 `0.0` / `-0`）现在直接拒绝、不写工程。它不会静音——客户端、`gtrk render` 与云端都把 `volume: 0` 读成原音量，BGM 照样满音量；不想要 BGM 就别铺，铺好后要静音用 `gtrk patch set --muted`，要很轻的垫底给个小正数。其它越界值照旧按默认 0.1 回落并告警。
+- 改：`gtrk patch set --volume 0` 现在直接拒绝（`volume_zero_use_muted`），提示改用 `--muted`。契约 §4 不以线性 0 表达静音，客户端、`gtrk render` 与云端工程导出 / 时间线渲染都把 `volume: 0` 当旧客户端 0 dB 残档读成原音量，此前这条命令「成功」却听不出变化；`--ops` 批量里出现同样整批不写。
+- 改：`gtrk patch set` 的静音改按「轨是总开关」判，与客户端、`gtrk render` 一致——轨或片段任一静音即静音，片段上的 `muted: false` 打不开已静音的轨。⚠️ **原来在静音轨上「成功」的 `set --no-muted` 现在报错** `track_muted_master`（以前写进 `muted: false`、回执说已取消静音，实际照样静音）：`patch set` 不改轨级参数，请在客户端点开该轨喇叭。静音轨上 `set --muted` 显式写 `muted: true`（之后轨解除静音，这段仍静）。`set --audio-track` 转轨按有效静音保真：从静音轨移到不静音的轨，片段写上 `muted: true`；把原本出声的片段移进静音轨报 `audio_track_target_muted`、工程不动。音量照旧按「片段覆盖轨」（link-gtrk-track-muted-precedence）。
+- 新：工程片段的**音频淡入淡出**（即剪客户端写进 `.gtrk` 的 `audio_fade_in` / `audio_fade_out`）CLI 全程认得。`gtrk patch` 剪短片段时淡变放不下就按比例缩、回执出 `audio_fade_clamped`，切开片段时前段只留淡入、后段只留淡出（此前切点处会凹一下）；新参数 `gtrk patch set --audio-fade-in / --audio-fade-out`（秒或帧，0 即删键，两侧之和超过片段时长直接拒）。`gtrk render` 按淡变出声（按成片时间计、变速片段不换算，无淡变工程滤镜串逐字节不变）。`gtrk audio tighten` 遇到带淡变的音频片段拒绝并点名、工程不动；`gtrk audio lay` 同源重铺把带淡变的旧片段替换掉时如实告知条数。`gtrk project export` 把云端返回的产物级告警全部打出并写进 `result.json` 的 `warnings`（含剪映 / Pr 等格式对淡变的降级说明，顺带变速保调降级告警也不再被吞）。⚠️ **编辑或渲染含音频淡变的工程需本版本及以上**：旧版不报错，但切分会让两半都带两侧淡变、剪短不缩、`audio tighten` 逐段复制、渲染没有淡变（link-gtrk-clip-audio-fade）。
+
+- 修：`gtrk render` 不认音频轨的静音——客户端里点了 BGM 轨的喇叭、或用 `gtrk patch set --muted` 静了某段音频，本地渲染出来照样有声，与客户端导出不一致。现在音频轨的轨级与片段级 `muted` 都生效：轨静音是总开关（片段上写着 `muted: false` 也不出声，与客户端一致），片段静音只静那一段；静音部分不再读素材音频，成片总长不变。所有音源都被静音时照常出无声成片，并打「本片无音源」提示。没有静音音频轨的工程，渲染结果与之前相同（fix-render-audio-track-muted）。
+- 修：同一台机器既装了 gtrk 插件（Claude Code / Codex 插件市场）又跑了安装器，Agent 里的 Skill 会出现两份——插件自己的引导让人跑的 `npx -y @gitruck/cli@latest install` 会再装一份。现在：`gtrk install --no-skills` 只装 CLI 和配置、不装 Skill，插件的引导（Claude Code 会话开头提示、Codex 详情、README 插件一节）都改用它；安装器认得已启用的 gtrk 插件，默认安装时按宿主让路——Claude Code 有插件就照装给其他 Agent、撤掉 Claude Code 里那几条链接，Codex 有插件就这一步不装（它直接读 `~/.agents/skills`，再装一份就是两份），让路算成功，`gtrk upgrade` 不再误报「skill 没刷成」；点名 `--agents` 时照装，会重复就提示一行。已经重复的只报不删：`gtrk doctor` 新增「Skill 来源」一行，新命令 `gtrk skills uninstall` 移除安装器装的那份（第三方 Skill 与插件那份不动）；Codex 插件在场时过期提示改指移除。（fix-plugin-installer-duplicate-skills）
+- 新：Codex 插件市场与 Cursor 插件清单——仓库根即插件，随包 20 个 `gtrk-*` Skill 照旧取 `skills/`。Codex：`codex plugin marketplace add Gitruck/cli` 后 `codex plugin add gtrk@gitruck`（只装 Skills，CLI 与 API Key 用 `npx -y @gitruck/cli@latest install --no-skills` 另装）；Cursor 清单 `.cursor-plugin/plugin.json` 供插件市场审核。发版闸 `plugin-manifest-check` 改为 Claude Code / Codex / Cursor 三份清单的 version 都须与 package.json 一致。
+- 新：`gtrk client state / segment / frame`——读编辑器里的工程。即剪客户端开着这个工程时经本机通道读活状态（选中哪段、播放头、编辑器所见的画面）；没开时读工程文件、本地渲出一帧（零计费、不含 MG 颗粒），两条路输出同形、`source` 标明是哪条，客户端缺席不影响任何子命令。`frame --at` 收的是**时间线**时刻：粗剪过的工程拿轨上时码去 seek 毛片会取到另一处画面，`gtrk-splitter` / `gtrk-mg` 的抽帧步骤因此改用它。`gtrk media probe` 收目录（列出这一层的音视频与参数），`gtrk media cut --copy` 流拷贝截段（秒级、起点按关键帧对齐），`gtrk media frames` 没给 `-o` 时认 `$GTRK_FRAMES_DIR`。`gtrk-splitter` / `gtrk-mg` / `gtrk-oralcut` 标 `in_app_agent`：要 agent 执行的命令全是 gtrk（装 CLI 那一步标为外部 agent 的前置），测试闸守住。
+- 修：`gtrk qc --gtrk` 与 `gtrk render` 渲后质检的报告里从来没有换段备选——`gtrk-mg` 出片后 QC 闭环第 2 步「读它给的排序备选」无从读起，只能手找候选段。现在段内跳切与判为严重的过短镜头条目带 `alternatives`：同一 beat 里还没上轨的候选段（从工程登记的 `split/broll-plan.json` 取），每条给 `clip_id`、段区间与排序依据，按运动量 → 切点密度 → 分数排序，列前 3 段（多于 3 段另报总数）；候选缺运动或切点信号时 `alternatives_note` 注明口径受限。「未上轨」按段判：此前按 `clip_id` 判，一个 beat 只有一条素材、底下好几段的工程会被判成零备选。该 beat 的段都已上轨时给空列表并说明；没读到 plan 时不给列表、只给说明。判为严重的过短镜头此前不带 beat / 槽位坐标，现在带上，紧贴拼接处的极短镜头（一两帧）也能归到槽位（add-material-motion-signal 4.2）。
+
+- 新增：`gtrk tool image_purify --redraw` 图片去水印「重绘模式」——整张图交给图片编辑模型重新生成，铺满全图的半透明、网格水印也能去掉；与 `--purify-scope region` 同用时只替换框内。单独计价，运行前报价按重绘档；也可 `--params-json '{"purify_method":"redraw"}'`。不加 `--redraw` 时请求与之前逐字节相同。价格表里挂在父项下的分档（`tiers`，如重绘、区分说话人、云配音各音色档）现在也能按自己的 key 查到实时价格（link-add-image-purify-redraw-mode-cli）。
+- Skill 措辞订正（ClawHub 安全扫描指出的自相矛盾与告知缺口）：`gtrk-matrix` 的描述把「素材本体不上云」改准为视频本体不上云、选中上轨的图片会上云转运镜（正文早已写明）；`gtrk-narration` / `gtrk-food-recap` / `gtrk-vlog-docu` 的「不执行任何网络下载」收窄为不下载二创源片与主体素材，素材矩阵的 BGM / 空镜可按签名直链落地（与旅拍图纸同口径，此前与各自的 BGM 伴奏下载步骤字面冲突）；`gtrk-narration` 开工问询补一句内容离机告知（转写上传音轨、建索引上传抽帧图）；`gtrk-style-maker` 安装用户 skill 前先问装到哪些 Agent（缺省只装当前这个），适配器钉在 `skills@1.7.4`。下载禁令的射程同步写进解说链规格（fix-narration-download-ban-scope）。
+- `gtrk-oralcut` 剪完不再一律往下接力：只要剪辑工程、草稿或去停顿时，剪完停在交工，一句话交代下一步，说一声就接着做；看不出要不要成片时也先停。要成片、完整包装，或点名 B-roll、字卡、BGM、字幕之一时，照旧接着拆分镜派单。按 `/gtrk-talking-head` 跑粗剪时交回图纸，停在检查点①（adjust-oralcut-relay-by-request-scope）。
+- `gtrk-splitter` 派单后不再一律往下铺：直接调用只要拆分稿或派单时，落地后停下，一句话交代下一步（下一步会往工程里加 B-roll 候选轨），说一声就接着做；看不出要不要往成片做时也先停。要成片、点名要铺 B-roll 等，或是被 `/gtrk-oralcut` 按「要成片」接力过来时，照旧交棒铺 B-roll（adjust-splitter-relay-by-request-scope）。
+- `gtrk-mg` 出片后 QC 报出可换段的画面问题时，不再直接把你选定的 B-roll 换成排序第一的备选：先列出哪几处、拟换成哪段，以及连带影响（B-roll 重铺、受影响的 MG 颗粒重铺并覆盖手调、重渲可能计费），你同意后只换同意的那几处；改 plan 前留 `broll-plan.before-qc-<时间戳>.json` 与 `project.before-qc-<时间戳>.gtrk` 两份副本，拷回原文件名即回退、不再计费。事先说过「QC 报的问题直接换」也只免换段那一问，重铺（本地素材走云端编排计费）与重渲照旧先报预估、等你同意（fix-mg-qc-swap-needs-approval）。
+- `gtrk-mg` 出片后 QC 报出可换段的画面问题时，不再自己换 B-roll：转述缺陷后把换段交回 `gtrk-matrix`，先列拟换方案、等你同意、留副本这些规矩照旧。重铺完会先停下，请你在客户端看换过的那几处画面，以及上面的 MG 有没有挡住主体；你认可新底轨之后才回到 MG，没点名的颗粒一颗不重铺，手调保留。事先说过「QC 报的问题直接换」也不免这一次认可（adjust-mg-qc-swap-handoff-to-matrix）。
+- `gtrk-matrix` 出片 QC 换段时，换进来的段接过被替换段的排序分、占它原来的位置，重铺后只有你同意换的那几处变。此前照「原样搬」保留检索相似度，本地素材的 plan 会被段序校验整单拒绝；重排后再铺，同一 beat 的其余镜头会整体挪位，还可能挤进一段没上轨的备用段。原检索相似度记进与副本同一时间戳的 `split/qc-swap-<时间戳>.json`；换进段来自另一条素材、位置保不住时，会先告诉你哪几处跟着挪。另订正一处说法：钉选（`pinned`）只保证落得上，不保证落在第几槽（fix-qc-swap-slot-order）。
+- `gtrk-talking-head` 快速成片开剪前先停一次：有没有文稿、B-roll 从哪来、有没有屏录或第二机位（多条毛片时再加一问是不是同一期），一张表问完才跑粗剪——粗剪是这条链第一个计费的命令。请求里已经说清的不再问；目录里没看到文稿或屏录只作提示，不再当成答案；检查点①也不再补问这几项（fix-talking-head-kickoff-gate）。
+- 修：`gtrk oralcut` 两条不同目录下的同名毛片（如换卡后重复的 `C0001.MP4`）同一秒开剪时，后落的剪映草稿会整份覆盖先落的那份，且没有任何提示。现在开剪前就在剪映草稿根里占好草稿文件夹，撞名时后到的那份改叫 `…-2` 并提示，原草稿逐字节不动；同一目录下同名毛片同秒并行时，产物目录同样追加 `-2`。显式 `--out` 重跑同一目录时，产物目录照旧复用，剪映草稿另起 `-2`，不再覆盖可能已在剪映里改过的旧草稿。顺带修正草稿信息里的名称与位置：此前每份 oralcut 草稿都写成草稿根本身（名称为「JianyingPro Drafts」），现在是草稿自己的文件夹。`gtrk oralcut-result` 取回时落回原跑批占好的文件夹；`gtrk project export` 落草稿时也不再覆盖同名草稿（fix-oralcut-jianying-draft-collision）。
+- 修：`gtrk long2short` 与 `gtrk tool video_translate_dub` 的剪映草稿名不带时间戳，不同目录下的同名毛片哪怕先后跑，后跑的也会把先跑的草稿整份覆盖（long2short 两次条数不同时，一组草稿里还会混着两条毛片的片段），且没有提示。现在提交前就定下草稿名：同一条毛片在同一产物目录重跑，照旧覆盖上一次的草稿；撞上别的毛片的草稿时改落 `…-2`（long2short 整组改名，如 `talk-long2short-2_clip0`）并提示，原草稿逐字节不动。升级前跑过的产物目录第一次重跑会多出一份 `-2`。`gtrk project export` 的剪映草稿信息里的名称与位置也改正为草稿自己的文件夹（此前写成草稿根本身，名称为「JianyingPro Drafts」）（fix-long2short-dub-export-draft-collision）。
+- 修：`gtrk oralcut` 与 `gtrk long2short` 跑之前不打印价格——skill 一直写着「跑前 CLI 自动查实时价并打印」，实际这两条命令从来没接价格查询。现在抽音频之前查一次官网实时价格，往 stderr 打一行「计费提示」：单价，加上按原片时长算的本次预估积分（以服务端结算为准）；`--json` 结果与 `result.json` 增加 `pricing`。查不到时打「实时价格暂不可用，以服务端结算为准」，照常往下跑。两条命令新增 `--dry-run`：只探测并报价，不抽取、不上传、不计费、不建任何目录，适合长片或开工问询时先报价。`gtrk-oralcut`、`gtrk-long2short`、`gtrk-talking-head`、`gtrk-live-slicing`、`gtrk-narration` 的计费说明同步改写，`gtrk-live-slicing` 里写死的单价已删（fix-oralcut-long2short-price-line）。
+
+## 1.3.10（2026-10-26）
+
+- **改**：`gtrk tool video_canvas_adapt` 的 `--clip-start` / `--clip-end` 改为**秒**（可带小数），原为帧序号。服务端同步改为按秒截取（此前文档站写秒、后端按帧号截，传 `5` 只截到 5 帧）；区间为空或起点不小于视频时长时，服务端建单前即拒（错误码 6016，不扣费），CLI 对 `--clip-end` 不大于 `--clip-start` 也当场拦下。旧版 CLI 传的帧号会被当成秒（link-video-canvas-adapt-start-end-unit）。
+- 修：`gtrk tool image_classic_template --template-mode image`（只要拼图、不画标题）不传 `--main-title` 也被当场拦下。现在与服务端同口径：`--main-title` 只在封面模式（缺省 / `full` / `text`）必填，`image` 时可省、payload 不带标题。标题含 emoji 等封面字体画不出的字符，服务端建单前即拒（错误码 6046，不扣费），CLI 原样转述（fix-cover-title-font-coverage）。
+- 文档：README 补两种装法——通用 skills CLI（`npx skills add Gitruck/cli`）与 Claude Code 插件市场；`gtrk mg edit` 的计价说明同步为 6 积分/候选、前 200 个之后 8。
+
+## 1.3.8（2026-10-18）
+
+- 新增参考片精读：`gtrk media` 看片命令族（`probe` / `lines` / `frames` / `tile` / `tiles` / `boundaries` / `cut`，纯本地、不计费）。取帧网格下方标出源片秒、时码与正在念的字；`--around` 按台词定位；`boundaries` 给视觉变化候选（机械证据，不是镜头判定）。配套随包 skill `/gtrk-ref-reading`：按「改不改变讲者的位置、大小或可见区域」把参考片的每个视觉系统归到 MG 或合成风格；`/gtrk-style-maker` 的作品逆向可接视频参考。
+- 竖屏 / 方形工程也能做合成：合成舞台随工程画布。`gtrk composite scaffold` 按工程 `.gtrk` 的 `video_size` 写场景 `stage`（缺席按 1920×1080）；`build` 遇场景舞台与工程画布不一致逐颗报错，不缩放了事；机检、静帧与烘焙都按舞台尺寸出，烘焙产物尺寸与缓存身份随舞台；`--abi` 增 `stage:"canvas"`。客户端对竖屏合成的导出支持随下一版客户端发出。
+- 成片图纸缺省带精剪包装（合成层）：口播、解说、美食、配音、旅拍、Vlog 图纸的快速成片在字幕之后、出片之前做一轮合成（auto 选窗口不超过全片 25%，逐窗口复核、构建机检至多三轮，再铺轨烘焙），开工时告知一句；直播切片开工多问一句（缺省不做），长剪短跑前问一次。
+- 修：竖屏 / 方形工程的 MG 颗粒经 `gtrk render` / `gtrk project export` 预渲后被压扁（横胖竖扁、旋转被拉平）。颗粒预渲原先一律按 1280×720 开舞台，云端按「舞台 / 颗粒声明尺寸」非等比挂载；现在舞台按颗粒声明的 `data-width` / `data-height` 等比缩到短边 720（竖屏 1080×1920 → 720×1280，方形 → 720×720），`project export` 登记的颗粒 MOV 尺寸随之对齐。横屏 16:9 颗粒的舞台与缓存键不变，存量缓存照常命中；竖屏 / 方形颗粒升级后首次渲染会重烤一次（旧缓存是压扁的，不复用）。客户端导出剪映 / PR 的颗粒预渲需客户端同步跟进（fix-particle-capture-follows-declared-aspect）。
+- 修：`gtrk tool image_matting` 处理带 EXIF 方向标记的手机照片（如 Orientation=6），产物转了 90°。上传前先按显示方向摆正（原图不动，摆正件按原图指纹缓存在 `~/.gitruck/audio-cache/`）；无方向标记或非 JPEG 照旧原文件直传；缺 ffmpeg 等摆正失败时提示后按原像素上传（fix-image-matting-exif-orientation）。
+- `gtrk-mg` skill / 参考文档改准画幅口径：颗粒画幅须等于工程画布，竖屏可用；registry 中性块仍只有 1920×1080。
+- 修：竖屏 / 方形工程取文字模板（`gtrk mg fetch --source text`）恒得 1920×1080 颗粒，铺进去被拉伸。`--canvas` 原先在这条路上只被收下、不生效；现在按目标画幅编：派单模式缺省取工程 `.gtrk` 的 `video_size`（显式 `--canvas` 与工程不符当场拒，找不到工程文件时按 1920×1080 编并提示），独立模式按 `--canvas`。`gtrk mg compile` 新增 `--canvas`，重置颗粒时缺省沿用颗粒自己的画幅，`--remote` 同样把画幅交给服务端。横屏工程与不给 `--canvas` 时产物不变（fix-text-template-canvas-not-compiled）。
+- 修：画幅比例不对的 MG 颗粒（如竖屏工程里声明 1920×1080 的手写颗粒或旧颗粒）照样能铺进工程，渲染时被拉伸，全程不报错。`gtrk mg --project`（铺轨，含 `--lint-only`）与 `gtrk mg lint --dispatch / --project` 现在按工程 `.gtrk` 的 `video_size` 比对颗粒声明的比例：跨比例判 `1-canvas-match` 致命、不铺；同比例不同尺寸（如 4K 横屏工程里的 1920×1080 颗粒）照常放行，比例差 7% 以内视为同比例（DCI 4K 4096×2160 这类 17:9 工程里的 16:9 颗粒放行，接受 6.7% 横向拉伸）。工程缺 `.gtrk` 或 `video_size` 不合法时不比对并提示一句。裸 `gtrk mg lint <file>` 不变（fix-mg-lay-lint-reads-project-canvas）。
+- 修：竖屏 / 方形工程派单取 registry 中性块（`gtrk mg fetch --pick <块> --slot <beat> --project <dir>`）照样下载并落一颗 1920×1080 颗粒，要到 lint / 铺轨才被拦。现在按工程 `.gtrk` 的 `video_size` 比例判（同上，容差 7%）：比例不是 16:9 在下载前就拒、不落盘，报错指路 `--source text`（文字模板按工程画幅编）或栏目 skill。横屏 16:9 工程（含 4K）与 DCI 17:9 工程照取、产物不变；独立模式（`--as`）不读工程；找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示一句（fix-mg-fetch-registry-reads-project-canvas）。
+- 修：`gtrk composite bake --progress jsonl` 的取消恰好落在工作页打开出片台时，要约 24 秒才报 `cancelled` 并退出（浏览器已被结束，打开页面却仍按每轮 8 秒等到期限）；现在浏览器一退出即放弃，取消照常几秒内收尾。开烤前建工作目录那一段也有进度行了（原先这段可能超过 1 秒没有输出）；装渲染组件期间关闭 stdin，装完即按取消收尾（原先会漏掉、照常烤完）（add-composite-bake）。
+- 修：`gtrk matrix` 铺轨三处坑：
+  - `clip_id` 带来源层（`<beat>-<layer>-broll/bedfill/gapfill-…`），通用层与本地层同 beat 同序号不再撞名，`gtrk patch --clip` 可直接寻址；老工程重铺不受影响。
+  - 口播（fill 形态）工程里片段间 1–2 帧的缝、锚点前短于 1.2 秒的空档，在素材余量内并入相邻片段，不再闪黑；余量不够仍补黑，并逐段告警。
+  - `gtrk matrix --online` 收尾零候选时不再覆盖盘上已有的 plan（结果带 `plan_kept`）。
+- 合成层在英文口播片上更好用：
+  - 场景锚点的关键词照句子原文写即可：匹配时关键词与句子都忽略空格、标点与大小写，英文按整词（`"cold brew"` 直接写，`tea` 不再先命中 `teas`）；找不到时报错打印句子原文。
+  - `gtrk composite plan` 的「建议画面」识别英文的对照（unlike / but / instead of …）、列举（逗号列举，或转写不带标点时的一长串并列）、数字与分点；其他语种不做文字信号，审稿稿里写明。中文判定不变。
+  - `gtrk composite lay` 的回执改为当前出片口径：客户端（1.2.13 起）原生导出与剪映 / Pr 导出、`gtrk render`、`gtrk project export` 都先在本机烤合成，失败段按粗剪出画。
+  - `/gtrk-composite` 场景速查写明：工具箱只给舞台直接子元素定位，容器里的元素自己写 `position:absolute` 或加 `.abs`。
+- `gtrk composite lint` 新增 `unpositioned-offset`：容器里的元素写了 `left` / `top` 偏移、却没写 `position:absolute` 也没加 `.abs`（偏移不生效、挤成一列）时报出来，点名元素与容器。只在 lint 时检查，颗粒与烘焙缓存不变、已烤的颗粒不用重烤。
+
+## 1.3.7（2026-10-18）
+
+- 新增匿名使用统计：每条命令结束时记下命令名（注册名，不含任何参数）、成败、失败时的错误码或分类、耗时区间与调用方（终端或 agent 名称），用于了解命令热度、失败率与版本铺开情况。
+  - 不发参数、文件名、路径、内容、API Key、错误原文，也不带设备标识。
+  - 首次配置时（紧跟崩溃上报那一行）告知一次，默认开；`gtrk init --no-usage-stats`、`GITRUCK_USAGE_STATS=0` 或 `DO_NOT_TRACK=1` 可关，`gtrk doctor` 显示当前状态。
+  - 源码运行、单测与 `CI` 环境不发送。
+  - 只往 `~/.gitruck/usage-queue.jsonl` 追加一行，由后台进程发送，不拖慢命令；断网时留在本机最多 7 天，联网后补发。
+  - 隐私政策已同步更新（3.6「使用统计」）；说明见 `docs/reference.md`「使用统计与关闭方式」。
+
+## 1.3.6（2026-10-18）
+
+- `gtrk composite bake` 认合成槽位的用户覆盖 `crop` / `box` / `slip_ms`：校验与输入快照和服务端参考实现同口径，出片台按「颗粒几何 → box → crop → 适配 / 构图 → 形状圆角」绘制，ref 槽取帧加 `slip_ms`；`--abi` 新增 `overrides` 能力位。**客户端 1.2.13 起会写这些覆盖**，旧版 CLI 遇到带覆盖的合成按粗剪出片并提示升级。
+- 烘焙取消或出错时，满载机器上也能很快收尾：先提高被结束进程的优先级再结束，浏览器遗留子进程合并一次查询收掉，删除工作目录限时。
+
+## 1.3.5（2026-10-17）
+
+- 新增合成层命令族 `gtrk composite`：`plan` / `review` / `scaffold` / `shots` 把候选窗口写进 `struct_meta.composite`（客户端大纲 CP 行），支持整片铺满 / AI 判定 / 指定区间三种入口；`build` 把场景构建成自包含合成颗粒（随包工具箱 `composite-kit@1`）；`lint` 做静态校验加本机 Chrome / Edge 逐帧排版机检（穿模 / 线条穿画面 / 越界）；`lay` 按自产身份幂等铺进 beat 轨最上层。新增 `/gtrk-composite` skill，口播图纸挂可选合成步。
+- `gtrk composite bake`：用钉定版本的 chrome-headless-shell（`gtrk deps install --browser`）逐帧确定性出帧，按段并发、带缓存；`render` / `project export` 接管已烘焙的合成颗粒，`lint` 增帧纯度检查；支持 `--progress jsonl`，关闭 stdin 即取消（退出码 130），取消或出错时连同浏览器遗留子进程一起收掉。
+- 片段背景填充：`gtrk matrix` 的候选片段自带纯黑 `background_fill`，不再另铺黑底垫轨（`--black-bed` 回到旧形态）；`ai-drama lay` 的 AI 片段同样带黑底；`gtrk project background` 缺省改为逐片段写底板；本地 `gtrk render` 承接片段底板；`project export` 承接云端物化，先写出纯色图再落工程（剪映 / Pr 的上层轨模糊为真模糊，FCPXML / OTIO 降级为纯黑，铺满画布的片段不垫底）。**需配合客户端 1.2.12 起**，旧客户端不认片段底板。
+- `gtrk render` / `project export` 遇到工程里有客户端专属视觉状态（文字 / 贴纸 / 图形 / 特效、画布背景）时用人话提示一次，`--json` 恒带 `clientOnly`；`project export` 的 `clientVisualElementCount` 改按元素计数（原误按车道数）。
+- 外网 B-roll 缺省加入 Pexels 第五平台：解析可选署名字段（`uploader_url` / `license`），平台 `disabled` 不算降级；旧服务端不认 pexels 时提示加 `--platforms` 继续；未指定平台时先回看四平台旧续跑记录，不重复扣费；`source_urls` 接受 Pexels 视频页。**服务端开关打开前 Pexels 只报 `disabled`、不出候选。**
+- `matrix material --scope clip|image` 缺省附带 Pexels 补充结果：单列在 `--json` 顶层 `pexels_results`（另有 `pexels_status`、`counts.pexels`），不进 `results`、不算候选数，人读输出另起一段并在段首署名 Pexels；`--no-stock` 关闭，`audio` 不带。补充素材直接用 `download_url` 下载，`matrix fetch` 见 `pexels:` id 会整批拒绝。**需服务端 `add-pexels-stock-material-search` 上线并打开开关后才会出现补充结果**，老服务端下只提示一次、不报错。
+- `tool video_highlight` 分析代理升至 448p/4fps（libx264 CRF 28；本地代理缓存按编码参数区分，参数变更后自动重新生成），缺省附单声道低码率原声，新增 `--no-audio`；上传前本地自检，旧版 224 代理不再复用。**需云端先升级，旧云端会以「短边必须224」拒绝新代理。**
+- MAD 缓存目录不可写时给出权限提示与诊断类别。
+- 交工文案补 Premiere 自动重链提醒：正本在 `gtrk-oralcut`「回给用户」的 PR / FCP 条，`long2short` / `live-slicing` / `tools` 引用同一条。
+
+## 1.3.4（2026-10-14）
+
+> 版本段补录于 2026-10-17：发版时这几条留在「未发布」里。归属按 npm 记录的 `gitHead`（1.3.4 `144ed89`）与写入这些条目的提交时间判定，未逐条核对包体。
+
+- `long2short --camera-move`：云端按与精剪同一套调度把推 / 拉镜头写成主轨片段的 `clip_keyframes.scale_x / scale_y`，客户端与剪映可见可改；`clips.md` 标「运镜 N 处」，未能加运镜的切片单列；`/gtrk-live-slicing` 开工问询变五问（⑤ 运镜，缺省不加）。需配合服务端 `add-long2short-for-cli-camera-move` 与客户端承接 `clip_keyframes` 的版本。
+- `gtrk patch` 的 trim / split / seal / snap 同步维护 `clip_keyframes`（入点平移、越界截断补插值端点、切分两段各自合法），写前校验拒绝任何非法关键帧并点名 clip 与通道；`audio tighten` 遇带音量关键帧的音频片段拒绝；本地 `gtrk render` 读到关键帧时提示按静态画面出片。
+- `gtrk project background --blur [--intensity n] | --color #RRGGBB | --clear`：写客户端画布背景 `struct_meta.client_background`（零计费、不访问云端），横屏源进竖屏画布时用模糊底替代黑边；`/gtrk-live-slicing` 对横竖互转的入选切片缺省加模糊底。剪映 / PR 与本地 `gtrk render` 不带该设置。
+- `long2short --speed-factor 0.5–2.0`：整体调速（保音高）写进逐 clip 工程，客户端 / 剪映 / PR 都按倍率播放，云端不渲染、不加价；`clips.md` 标注倍率，未能变速的 clip 单列。需配合服务端 `add-long2short-for-cli-speed` 上线。
+- `long2short` 产物根新增整片转写 `json/transcript.json`，可用 `gtrk subtitle lay --gtrk … --transcript …` 给任一 clip 上客户端字幕轨；字幕文件来源时 `clips.md` 提示词级时间为近似值。需配合服务端 `add-long2short-for-cli-transcript` 上线，老服务端下不报错。
+- `subtitle lay --language <code>`：指定云端拆行语种（缺省仍为 zh-CN），非中文源上字幕不再按中文断句。
+- `/gtrk-live-slicing` 选题确认后对入选切片缺省字幕上轨；调速只在用户主动要求时加。
+
+## 1.3.3（2026-10-08）
+
+> 版本段补录于 2026-10-17。npm 记录的 `gitHead` 为 `13d43e9`，但同步版本号的提交 `2f5c68d` 晚于发布约 4 分钟，推断与 1.2.7 一样是从带未提交改动的工作区发的；以下按该提交说明补记，未核包体。
+
+- 完善 Vlog 分段组装、旁白归轨和颗粒检查。
+
+## 1.3.2（2026-10-08）
+
+- 本地视觉理解增加当前 Agent 审阅交接：`matrix describe --prepare/--review`，已完成的本地判断不调用豆包，明确无法完成的条目按需补齐。
+- stable 长场景保留时间覆盖，素材概览同步多点抽帧；支持对指定源时间窗加密理解，检索帧预算避免同一密集素材独占。
+
+## 1.3.0（2026-09-28）
+
+- 视频去水印不再默认 FFmpeg：Agent 必须在处理前说明快速模糊与慢速内容修复的效果代价，等待用户选模式；`purify run/apply`、人工框和 `tool video_purify` 缺少显式模式时在上传前停止。仅检测、编辑和空清单不受影响；旧记录未建处理单时需补选模式，已建单继续原任务。失败后不得擅自改用快速或本地 FFmpeg。
+
+- `tool --batch` 补齐整批费用预估：标准价/超额价积分与额度包单位数分别汇总，按分钟收费先本地探时长，逐任务取整后求和；跳过项不计费、不探测。价格或计量不可用时明确说明无法预估。
+
+- `ai-drama lay` 成功回轨后提示先显式指定口播音频运行 `patch snap --dry-run` 检查，再执行吸附并用 `patch seal` 补缝；只提示，不自动编辑。
+
+- 清理随包 skills、共享 Agent 规则、GSAP handoff 契约和双语参考文档中的历史叙事；当前执行规则不变，GSAP 证据保留在维护者附录。
+
+## 1.2.13（2026-09-22，AI 漫剧工具批次补记）
+
+> npm 发布时点为 2026-09-22 08:26:53 UTC。本节补记这批已实现能力；不表示其全部 OpenSpec 已归档。后续音轨识别、素材内容寻址和镜头锚定仍在独立待办中。
+
+- `ai-drama pack` 从本地镜头与派单构建 return-v1 包，实测尺寸、帧率、时长，缺镜或校验失败不落包；`swap` 验证结构等价后替换并默认备份，工程文件不改。
+- `patch snap` 按音频能量定位切点，支持干跑和诊断；当前自动选音轨仍有已登记缺陷，含 BGM 的工程应显式给 `--audio`。`patch seal` 按指定轨和阈值补小缝，重叠及超阈值间隙只报，推荐顺序为 snap → seal。
+- `patch --json` 输出单行 JSON，补齐 `ok`、`dry_run`、`project`、`invariants`；旧 `gtrk` 与 `preexisting` 别名保留。依赖多行缩进输出的外部脚本请改为逐行解析完整 JSON。工程级操作补齐 `frames:null`、`before` 与参数回执。
+- 投影选轨加入口播素材匹配；视频主轨有画面却不含目标口播素材时可回退音轨，避免配音工程被额外视频轨阻断。
+- `mg` / `split` 增加覆盖区间与空档读数，以最长空档提示，不因颗粒稀疏阻断工作流。
+- `doctor --project` 汇总素材、轨道和工程结构检查；只对视觉底轨提示缝隙，缺省环境体检入口不变。
+- `qc contact-sheet` 生成带镜号和时长标签的分页联络表，标签与源文件保持绑定。
+- `tool --batch` 增加受限并发、已有产物跳过、失败汇总与 JSONL 明细；本地工具默认串行。该发布版的计费提示仅提供批次条数和单价；整批总费用估算已在上方「未发布」条目补齐。
+
+## 1.2.11（2026-09-19）
+
+### 改：`gtrk transcript --json` 带字级时码，成片字幕时间按语音贴（adjust-transcript-json-word-level）
+
+`--json` 现在按**成片消费面**索取字级识别：产出的 `transcript.json` 每句多一份 `words[]`（`{w, st, ed}`，秒、三位小数、不含标点）。下游 `gtrk subtitle lay` 与客户端一键上字幕据此把每一行的起止贴到真实语音上——此前没有字级时码，一句拆成多行时只能按字数在句子区间里摊分，实测 125 个行边界里偏差中位 148ms、最大 2.6s（一句话快说完了字幕才上来）。升级后同一份语料 235 条字幕起点与首字时码误差恒为 0，末条也不再拖到片尾静音。
+
+**不带 `--json` 的产物形态没变**：只出 Markdown 文字稿时仍是句级（Markdown 本来也不承载字级时码），响应 `word_count` 为 0 是正常的——不过这一版起它走的是另一条引擎腿，见下面 `switch-transcript-to-selfhosted-asr` 那条。`gtrk project init --transcript` 透传 `words[]`，畸形条目跳过并计数。
+
+### 改：一键上字幕不再吞掉完整的短句（adjust-caption-keep-complete-sentence）
+
+最小可读时长过滤（0.8s）以前对「被剪掉一半的残片」和「本来就短的完整句」一视同仁，于是「这不是比喻」「这不是隐喻」这类 0.7 秒的强调句被整条删掉。现在**只有残片**才受这条过滤，完整句无论多短都保留——后一步的空隙桥接本来就能把它延到下一行起点（实测这两句桥接后各 1.08s / 1.24s，与手工修的值一致）。`--json` 报表里 `droppedShort` 的语义随之收窄为「丢掉的残片数」。
+
+### 改：字幕里的感叹号也换成空格，问号保留（adjust-subtitle-punctuation-exclamation-to-space）
+
+落轨字幕的标点清洗扩表：中英**感叹号**（`！` `!`）并入「换成空格」，中英**问号**（`？` `?`）明确保留。逗号句号照旧换空格，小数 `3.5`、千分位 `1,000`、域名 `example.com`、缩写 `U.S.` 照旧不误伤。`--keep-punctuation` 仍可整体关掉清洗。
+
+> 这条以前之所以没人提，是因为语音识别一直把句读剥光了、字幕里根本见不到感叹号；识别侧改成保留句读之后它才第一次出现。
+
+### 改：不带 `--json` 的 `gtrk transcript` 改走自部署识别引擎（switch-transcript-to-selfhosted-asr）
+
+`word_level` 在服务端决定的是**引擎**而不是一个参数：要字级走字级腿（当前是外部厂商 ASR），不要就走
+自部署引擎 + 服务端纠错。CLI 现在按**产物消费面**分流——只出 Markdown 文字稿（不带 `--json`）时传
+`false`，走自部署腿当小工具用；带 `--json` 时传 `true`，因为 `transcript.json` 的 `words[]` 要承载字级
+时码（见上一条）。口径对所有语种一致，**CLI 不按语种挑引擎**：那要在端侧手抄一份「哪些码厂商引擎更好」
+的表，而正本在服务端引擎表里，手抄的那份不会报错，只会在某天悄悄分叉；粤语的质量取舍由服务端语种
+白名单承接。
+
+### 修：旁路记账写不进去，不再把已经挣到的结果一起带走（fix-sidecar-write-failure-kills-command）
+
+生产报错 `base_error#202`（外部客户）：文件已经传完，去写那条约 1 KB 的上传记账时 `EPERM` 一抛，
+**第三步挣来的 `fileId` 跟着陪葬**，整条命令死在第五步；客户重试时缓存里没那条记录，整个文件再传一遍。
+而同一个文件的读侧一直写着「缓存损坏不致命，当空处理」——坏了能忍，写不进去却要命。
+
+现在四处**旁路记账**——上传记账、分片续传断点、BGM 使用历史、MG 例外账本——写失败只打一行 WARN，
+并当场说清后果（如「下次同一个文件会重新上传」「断线后续不上，得从头传」），命令照常把结果交出去。
+
+**交付物类写入不在此列**：`gtrk init` 存 API Key、`gtrk skills` 登记栏目配置都是用户按下的动作，
+写失败照旧抛错，只把 Node 的原文换成人话（多半是文件正被别的程序占着，或者目录不让写）。
+判据是**调用语境**不是写入函数——同一个写函数在一处是交付物、在另一处是旁路记账，是常态。
+
+## 1.2.10（2026-09-18）
+
+### 加：`gtrk ai-drama lay` 可按工作台项目 id 取包（add-desk-project-resolution）
+
+新增 `--desk-project <id>`（可重复，与 `--package` 混用、按路径去重）：用户手上有的是 AI Drama Desk 的**项目 id**，命令自己解析成导出包目录，走两条确定性路径——服务可达就问 `GET /api/v1/projects/<id>` 取 `exportDir`（**字段缺席即判「尚未导出」**，不据 id 拼路径去试）；服务没起就读 `~/.gitruck/ai-drama-desk.json` 的 `instances[]` 逐条试。零命中会列出已查过哪些数据根（源码部署与打包部署的数据根不同，找不到多半是「在另一个部署里」），多命中报歧义不猜，两条都不通就报错并给出路。**全程不做任何目录遍历**——解析层有一条反向自证用例锁住这点。解析出的包走的仍是既有那条校验与写回路径，清单校验、不完整包整批拒收、路径穿越拒收、幂等与手调保护一律不放宽；`--json` 每个包多标 `via`（按 id / 按路径）与 `resolved_via`（服务 / 落脚点）。
+
+### 改：`gtrk render` 颗粒缓存键补交付配方版本，与客户端重新互通（fix-particle-cache-identity-parity）
+
+颗粒 qtrle 缓存的内容寻址键加回 `recipe`（qtrle 交付配方版本，客户端 2026-09-13 起已带、CLI 未跟），键序与客户端逐字节对齐；两端各钉一组写死 hex 的金样，任一端改公式该端先红。此前客户端在工程目录烤好的颗粒 `gtrk render` 一颗都不命中、全部重新云渲计费。升级后对客户端已烤颗粒全命中、零新任务；代价是升级后第一次 `gtrk render` 会把 CLI 自己此前烤的旧键产物 miss 一次（旧文件不删、不回退读取）。身份里的 `duration` 一律取 `.gtrk` 契约投影值原值，两端同源（客户端侧同批调整）。
+
+## 1.2.9（2026-09-18）
+
+### 加：推荐目录收一方 MG 排版技法族（add-first-party-technique-catalog-entry）
+
+`gtrk skills recommend` 多一个场景 `technique`：同合云自己的排版技法族（首个技法 doc-reveal：文献页叠放 / 发牌 / 局部强调）。技法不是栏目 MG 生产 skill——`gtrk skills add` 装完登记为 `routing:none` 且 `status: "first-party"`，由 agent 在 MG 步按槽位取用；显式 `--produces` 绑车道会照登记并告警一行。人读输出对一方条目印「一方维护」不印 star；`--json` 每条多 `origin`。`/gtrk-mg` 手册在「无匹配」与「有匹配缺省不用」两处各加一句指路，公约 §三‴ 补一方口径。
+
+### 改：`gtrk mg lint` 补体积规则（add-particle-html-size-lint）
+
+颗粒 HTML 超过 2,000,000 字符（客户端颗粒运行时的硬上限，超了在客户端永远加载不出来）现在判致命 `4-html-size`：铺轨跳过该 beat、`mg render` 不提交零计费；命中即短路，其余检查项不跑。超过 500,000 字符给非致命 `4-html-size-heavy`（客户端每次 seek 整份快照回传，体积直接决定预览帧率）。
+报错点名最大的一段 data: URI（类型、字符数、解码字节数、落点），给「按实际显示尺寸裁剪缩放后再内嵌」的改法；没有 data: URI 的超限如实归因为标记与脚本本身。契约 `contracts/gsap-emit-v1.md` 铁律 4 增补⑤，`gtrk-mg` 图纸 lint 节同步。
+
+### 修：环境类失败在端侧落成人话，不再炸到顶层当崩溃（三条生产报错归一件）
+
+读不动的 JSON 与写不进去的文件，此前把 Node 的原始异常直接抛到顶层、走崩溃上报。现在：
+
+- **读**：`.gtrk 工程` / `派单清单` / `拆分稿` / `AI 导出清单` 等按名报错，并附一句诊断——
+  文件是空的（产它的那一步没写成）/ 正文里夹着 `U+FEFF`（两份文本被直接拼在了一起）/ 有 NUL 字节
+  （多半被存成了 UTF-16）/ 有解不开的字节（编码不是 UTF-8）/ 就是不合法 JSON，各给各的出路。
+- **写**：目标被别的程序占着时退避重试（5 次、约 750 ms 窗口；**不做无上限重试**——编辑器开着那个
+  文件可以开一整天，无上限只会把「报错」换成「卡死」），仍失败则保留内容完整的 `.tmp` 并告诉你
+  可以直接改名收走；跨卷改不了名、磁盘没空间各给各的出路。写成功后顺手清掉够老的同目标 temp 残骸。
+
+## 1.2.8（2026-09-17）
+
+### 加：视频译制配音 `video_translate_dub`（link-video-translate-dub-cli）
+
+`gtrk tool video_translate_dub <视频或音频> --language <源语种> --translate-language <目标语种> --speaker <clone 或音色代号>`：
+把原片里的话翻译成目标语种，用所选音色或克隆原片说话人的声音逐句重新配音，画面保持原样（不做口型同步）。
+单条最长 120 分钟，超了上传前直接拒；按分钟计费，运行前实时查价。
+可选 `--ref <参考音频或视频>`（仅 `clone` 有意义，克隆别人的声音须先取得本人同意）、`--ref-lang`、`--no-keep-bgm`、`--fit-policy`、
+`--speed-band <最小,最大>`、`--subtitle-mode`、`--subtitle-type`、`--project-formats <逗号分隔>`；各参数的合法取值以服务端为准，CLI 不内置枚举。
+
+产物：`<输入名>-dub.mp4`（音频输入为 `-dub.mp3`）、`dub.wav`、`bgm.wav` 与 `base.mp4`（有则落）、字幕 `.srt`、逐句对齐记录 `transcript.json`、
+工程文件按格式分目录（`gtrk/`、`jianying/` …），`result-output.json` 为配音对齐报告。
+提交时自动带上原片与产物目录的本机路径，各格式工程里的素材都指向本机文件，打开即用。要剪映草稿加 `--project-formats gtrk,jianying`：草稿两件套齐全后自动放进剪映草稿目录（新增 `--jianying-draft-dir`，缺省读 `gtrk init` 配置或自动探测，与 `gtrk oralcut` 一致）；CapCut 草稿留在产物目录。服务端尚未升级时工程里仍是占位名、剪映草稿缺 meta，终端会各打一行提示。
+字幕、逐句记录、工程文件等附带产物偶尔缺项时只打一行 WARN，任务照常判成功。
+
+### 加：工具族通用「附加输入文件」
+
+工具可声明除主输入之外的本地文件参数（首个使用者是上面的 `--ref`）：任何上传之前先本地校验文件存在与扩展名，
+主输入之后上传，`--reupload` 同样生效，`task.json` 记录 `extraInputs`；没声明的工具行为与面包屑不变。
+产物文件名带子目录时自动建父目录。
+
+### 改：共享参数说明与超时长报错
+
+`--language` / `--translate-language` / `--speaker` / `--subtitle-type` 的说明改为不绑定单一工具的表述，参数名不变。
+视频类工具输入超时长的报错改为「输入时长超过 N 分钟上限，请先裁剪或分段后再提交」。
+
+### 文档：`gtrk-travel-recap` 图纸的写稿语速改读栏目 catalog
+
+随包旅拍图纸不再内嵌语速常量，改读栏目 catalog 的两个键；档案登记 `narrator` 五项齐备时回校样本 §3.5。
+
+## 1.2.7（2026-09-16）
+
+### 加：渲染字体改从同合云统一字体库装（link-cloud-font-library）
+
+`gtrk deps install` 的字体这一步改走**同合云统一字体库**（与客户端同源、同一份服务端投影，
+所以共享目录里同款字体只存一份），不再跟着 ffmpeg 分发清单里那几项走。新增
+`--font-family <family...>`：按 `font_id` 或中英族名点名装、可多个；缺省只装字幕字体
+`sourcehansanscn-bold.otf`。清单里没有 `sha256` 的字体**拒绝安装**（强校验不可降级）。
+
+`gtrk deps status` 多列一行字体库（地址、schema、族数 / 款数、生成时间）。字体清单与 ffmpeg 分发
+manifest 是**两条链路、各拉各的**，取不到只少列这一段，不影响上面的 ffmpeg 信息。
+
+### 修：固定名面包屑覆盖不再静默，`gtrk mad` 跟修产物目录防撞（fix-tool-outdir-collision）
+
+两处：
+
+- **面包屑覆盖**：`task.json` / `result.json` / `result-output.json` 三个**固定名**面包屑按固定名被
+  下游消费，撞名时 MUST NOT 改名——但此前也一声不吭。现在打一条 WARN 点名会被覆盖的是哪几个，
+  并说清代价（上一次的 `task_id` 与产物清单不可回溯，产物文件本身不受影响、撞名会自动改名保留），
+  末了提醒「要并行跑多条，给每条一个独立的 `--out`」。
+- **`gtrk mad` 防撞**：产物目录从 `mkdir(recursive:true)`（已存在即**静默复用**）改成与 `gtrk tool`
+  族共用同一份原子探路实现——同一秒起两条 mad，后者的 `mad.jsx` 会盖掉前者。`--out` 是用户明示的
+  落点，仍不替他改名。顺带把 mad 自己那份逐字等价的时间戳实现收敛掉。
+
+### 改：「AI 再现」全面改叫「AI 情景动画」
+
+随包 `README` / `AGENT.md` / 各 skill 图纸里的叫法统一换掉；车道标识 `AI_DRAMA` 与命令面不变。
+
+### 文档：升级 CLI 不会自动刷新已装的 skill（fix-skill-install-staleness）
+
+`npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，各 Agent 目录下那份 skill 仍是**上次装进去的快照**
+——agent 会照着旧口径干活，**而且不报错**。README 补上这条口径与修法：走 `gtrk upgrade`（升 CLI +
+刷 skill）或单独 `gtrk skills install`；自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」。
+`AGENT.md` 同步补上 agent 侧纪律：见到那条 stderr 提示 MUST 转告用户，MUST NOT 当噪音忽略。
+
+## 1.2.6（2026-09-16）
+
+### 加：MG 槽位视觉职能四档 + 生产侧硬闸 + 排产顺序闸（gate-mg-visual-job）
+
+派单里每个 MG 槽位的 `handoff.visual_job` 转为必填，四档 `statement` / `relation` / `data` / `decor`
+（判据是「这段的意思里有没有第二个东西与它并置」，**与用不用文字无关**）；`relation` 还须填
+`visual_brief`。全片一个关系型视觉都没声明时，顶层须具名 `mg_visual_job_note` 说明为什么通篇只有单一
+陈述（纯字卡包装的口播片是合法形态，本条只要求它是个有意识的选择）。派单阶段**不得引用具体模板 id**
+——判「这段要什么」的那一步不该看见模板库。
+
+两道闸落在生产侧：
+
+- **生产侧硬闸**：`relation` / `data` 槽位交上来一颗文字模板库的颗粒（内嵌 `v:"text-v0"` 的 IR）即拒。
+  被禁的是「从库里捞一个套上」，**不是「用文字」**——用排版画关系的手写颗粒（并置两列 + 破折号那种）
+  正是要保住的东西，本条不拦它。
+- **排产顺序闸**：本片还有 `relation` / `data` 槽位没产出源 HTML 时，`gtrk mg fetch --source text` 的
+  派单模式**拒绝执行**。理由是防锚定：连着看过十几颗现成品之后，「MG 该长什么样」的默认印象已被那批
+  东西定住，这时再自由发挥，发挥出来的多半还是它们的形状——顺序本身就是一道隔离。
+
+两道闸各留一次性例外，**必须同时给理由**、随工程留痕（铺轨侧写 `struct_meta.mg.exceptions`，取块侧写
+`<工程>/split/mg-exceptions.json`）：`--allow-text-for-relation <beatId> --why "<一句话>"` 与
+`--allow-template-first --why "<一句话>"`。它们 MUST NOT 被做成常开配置。
+
+### 加：`gtrk mg compile` 本地编译先校验再编译（fix-local-ir-compile-skips-validation）
+
+本地编译这条路此前**零校验**：`transparent:false`、`canvas:1280x720@60fps` 这类服务端会当场拒的 IR，
+本地一律 `exit 0` 落盘——于是「本地能编出来」不再蕴含「这份 IR 合法」。2026-09-15 实测有三颗带
+`transparent:false` 内嵌 IR 的颗粒，就是从这个口子溜进 `.gtrk` 的。
+
+现在编译前先跑一遍校验器，报错**指名到键**（`layers[2].font.size 须 8–600` 这种）。位置必须在编译之前：
+编译器对某些非法输入会抛它自己的异常（如未定义颜色引用），那句话没有路径、用户拿不到定位。
+
+### 加：`canvas.scrim` 压板层——半透明压板不再冒充实心底（link-text-ir-scrim-opaque）
+
+文字模板 IR 新增 `canvas.scrim`（压暗底轨用的半透明矩形：`fill` 必填且**必须带 alpha**，可选
+`rect` / `radius`），与 `canvas.bg` 互斥——要满幅实心底用 `bg`，要压暗用 `scrim`；写了 `scrim` 的颗粒
+`transparent` 仍须 `true`。
+
+此前压板恰好落在「根下第一个渲染子层」这个取样点上，而 `bgOf` 只认 `transparent`/`none`/`rgba(...,0)`
+三种透明形态，于是 `#000000A6` 被判成非透明——**一块压板被登记成合格实心底**，满屏槽位据此过闸，
+出片时底轨从压板后面透出来。取样时现在跳过压板层，继续往下找真正的全幅子层。
+
+同批补上一处漏接：`gtrk mg lint --dispatch`（用户检查已铺颗粒最自然的那条命令）此前**一个 category
+都不读**——`--category` 在命令面注册着、派单里也写着，满屏闸却只活在 `mg fetch` 那条路上，
+「取块时合规、后来颗粒被换掉」这条最常见的失守路径完全没人看。
+
+### 改：放开画幅硬闸，文字模板按工程画幅现编（link-aspect-agnostic-layout）
+
+`gtrk mg fetch` 与 `gtrk mg compile` 的 `--canvas` 从「只收 1920×1080」改成「须为正整数」：引擎早已按颗粒声明尺寸挂载缩放，原来那条硬闸拦的
+是一个**不存在的失败形态**；文字模板的 IR 住在 1920 参考系、画幅是编译入参，按目标画幅现编即可。
+
+**registry 中性块仍只收 1920×1080**：那批是手写 HTML、几何写死在块里，取块改写不会跟着缩，
+给它别的画幅出来就是错的。lint 相应改成按工程画幅对拍——颗粒声明的画幅与工程不符时点名
+「挂载走的是**非等比** `scale(w/dw, h/dh)`，跨比例会把颗粒拉伸变形（不是加黑边），而两边都不报错」，
+手写颗粒请按工程画幅重做。
+
+### 加：文字模板候选态可按分类过滤（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`。
+
+### 文档：`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` 按列校验，防止文案被改回。
+
+## 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）
+
+真机上这条命令**从来没成功过**：
+
+```bash
+gtrk mg fetch --source text --pick tfx-type-terminal --slot B05 --project <工程>
+# → composition_id "B05" / lint 致命 1-cid-expect / 不落盘
+```
+
+两处不对。① `--slot` 收的是 beat id（`B05`），而派单里的 `composition_id` 是
+`<工程slug>-<beatId>`（`t07-B05`）——铺轨与 `mg lint --dispatch` 都按后者对账，旧实现却把前者
+直接当 id 用，`dispatch.json` 一个字没读。② 取到的模板 HTML 原样送 lint，而模板内的
+`data-composition-id` 恒为模板 id、期望 id 恒为 `<slug>-<beat>`，两者永远不等 ⇒ 必然致命。
+
+文字模板是 `ir` 态、**不能直改 HTML**（改一字节就掉成 `detached`，云端再也调不动），
+所以钉 id 的合法路径只有一条：改内嵌 IR → 走 `mg compile` 同一条本地编译链重编。现在命令替你做：
+
+- 派单模式的 `composition_id` / 坑位包络 / `category` 全部取自 `dispatch.mg` 那条（与中性块
+  `registry` 路共用同一份 `matchSlot`，两条路不再各写一份）；
+- 内嵌 IR 的 `id` 钉成期望 composition_id，`canvas.duration` 钉到**坑位包络 + 0.3s 余量**
+  （铁律⑦），且**原本贴在模板末尾的层跟着钉**——不钉的话坑位长于模板时，那些层会在原时长处
+  被隐藏，后半段元素凭空消失；
+- 重编产物自证仍须是 `ir` 态，否则报错零落盘；`id` 与时长都没改时**原字节落盘**，不重编。
+
+独立模式同病一并修：`--as` 过去只改文件名、不改颗粒内部 id；`--duration` 在 text 路被**静默忽略**
+（命令面照收、代码里根本没这个字段）。现在 `--as` 改写 IR `id`、`--duration` 钉 `canvas.duration`，
+且 `--slot` 与 `--duration` **互斥**（派单的包络由 `track_st` / `track_ed` 定，显式给时长会与它打架）。
+
+另两条顺带：镜像块自身不是 `ir` 态时**报错零落盘**（那是发布事故，静默落一颗改不动的颗粒，
+用户要到 `mg edit` 被拒才发现）；派单 `category` 透传给 lint，槽位派 `fullscreen` 而模板是透明叠加时
+报**非致命**的 `x-category-opaque`——不拦落盘，但提醒你给这颗补一层全幅实心底。
+
+## 1.2.4（2026-09-14）
+
+### `gtrk mg` 文字模板三口：`fetch --source text` / `compile` / `edit`（add-text-template-source）
+
+同合云自己 clean-room 重写的文字特效模板库进了 CLI。与中性块 `registry` 那条路**刻意不同**：
+文字模板 MUST NOT 走机械改写——中性块来自第三方、要替字体换色板才合规；文字模板的块**自带 IR**，
+一旦直接改 HTML 字节，它就从 `ir` 态掉成 `detached`，云端再也调不动。改内容只有两条路：
+
+```bash
+gtrk mg fetch --source text 打字机                       # 候选态：只列不取（--offline 用本地目录）
+gtrk mg fetch --source text --pick tfx-title-typeline    # 取块态：三源择优取，逐字节校 sha256
+gtrk mg compile ./mg-fetch/tfx-title-typeline.ir.json    # 改完 IR 重编译（L0，本地跑、0 积分、零请求）
+gtrk mg edit ./mg-fetch/xxx.html --say "打字机快一倍，副标改成青色" --n 3   # 云端改写（2 积分/候选）
+```
+
+`--n` 只收 1 或 3，**它就是计费单位数**。改写被拒绝（模型说「词表里做不到」）同样计费——
+那是为了不让「拒绝」变成免费试探，但拒绝理由会原文给你，不会只丢一句失败。
+
+### 文字模板目录：随包兜底 + 远端择新 + 8 个人话分类（add-text-template-source / add-text-template-category）
+
+目录走「远端择新、随包兜底」：扩批是纯写 IR 的轮次，不该被 CLI 发版卡住，所以**随包那份会过期，
+这是设计**——运行时按 `version` 择新，随包只在三源都不可达时顶上。本版随包 **v2026-09-14.11 / 103 件**。
+
+分类从 37 个收成 8 个：`F`/`M`/`R` 是内部来源编号（喵影家族 / MAD 图鉴技法号 / 参考视频），
+用户看不懂，而且 93 件摊出 37 个分类里有 16 个只有 1 件。改由**目录下发** `category`
+（快照脚本算，两端只读不算——各算一份会漂且漂了不报错），判据是规则不是手工名单：
+满 7 件才配独立、其余进「其他」、总数 ≤8。`family` 保留供溯源、仍进检索干草堆
+（老用户按 F02 搜不该搜不到）。
+
+### IR 编译默认走本地，`--remote` 留给排查与对拍（move-text-ir-compiler-to-client）
+
+`gtrk mg compile` 此前每次都要打一趟服务端。现在 L0 编译在本地跑完：**零请求、零延迟、断网可用**。
+TS 编译器是 Python 正本的第二实现，靠一道**逐字节等价闸**钉住（全量金样两侧逐字节相同，
+本版 103/103）。
+
+⚠️ `--remote` **MUST NOT 下线**：它是等价闸的参照系，也是真机上排查「本地编出来的和服务端一样吗」
+时手上唯一的另一条路。
+
+### IR 词表 v0.2：八项新表达 + 片段引用槽位（add-text-ir-vocabulary-v02）
+
+`mask` 收数组（多条并存）/ `feather` 收两元数组（不等量羽化）/ `animTarget:"inner"`（蒙版钉死、
+内容在后面滚）/ `repeatText` / `charRoll`（逐字滚码落定）/ `sweep`（扫光）/ `shape.glow` /
+`anim` 新增 `skx`·`sky`，外加 **`runs[].slot`**。
+
+`runs[].slot` 修的是一个缺口：`brush-title` / `caption-emoji-arrow` / `caption-keyword` 三颗的文字
+写在 `runs[].t` 字面量里，**此前没有任何字段能改**。现在它们的槽位回来了。
+
+⚠️ **`blur` 通道判否，且这是有射程的口径**：`filter: blur()` 被补间驱动正是 `gtrk mg lint` 的
+`c-filter-animated` 所指、r69 真渲实测 **+36.2%** 的最贵形态。往后任何要 `filter` 的通道
+（`drop-shadow` / `saturate` …）一律先找零卷积等价物，真找不到再单独拍板。
+
+### `gtrk tool mad`：技法点名 `--technique` 与目录检索 `--search`
+
+一键剪 MAD 此前只能让它自己挑技法。现在可以点名，也可以先查目录看有哪些
+（语义匹配仍留给 Agent，命令面只做目录检索）。
+
+### 其他
+
+- `gtrk mg lint`：内嵌 IR 的**两代载体都认**——换载体那次产物字节全变，只认新的会把线上已发的颗粒
+  整批判成 `detached`。
+
+## 1.2.3（2026-09-13）
+
+> ℹ️ **本节是补写的**。1.2.3 当时发到了 npm 却没进更新日志（包里那份 CHANGELOG 顶到 1.2.2 为止）。
+> 补写口径是**发布产物实证**、不是按提交时间猜：拉 `@gitruck/cli@1.2.3` 的 tarball 逐项 grep，
+> 确认 `text-template` / `compileIrBody` / `--technique` **一个都不在**（同时 `pip` 42 处、
+> `subtitle_line_split` 3 处命中，证明探针本身能响）——文字模板那批全部落在 1.2.4。
+
+### `gtrk mg lint`：新增非致命哨兵 `x-soft-alpha`（fix-alpha-delivery-discipline）
+
+颗粒里只要有**半透明面积**（`rgba`/`hsla` 半透明色、`#RRGGBBAA`、渐变到 `transparent`、
+带 blur 的 `text-shadow`/`box-shadow`、静态 `opacity<1`），lint 会提醒一句。
+
+**恒非致命、不要求改写**——半透明本身完全合法。它提醒的是交付纪律：剪映的 qtrle 交付依赖渲染管线
+在编码前**预乘 alpha**（剪映按预乘合成，直通 alpha 的软边会塌成实心，2026-09-14 真机实证）。
+所以**剪映路径的真机验收 MUST 用这颗颗粒本身验，MUST NOT 拿实心颗粒代验**——实心颗粒对预乘错配
+结构性失明，验了也是白验。
+
+⚠️ 颗粒与 CLI **MUST NOT 自行预乘**，那会双重压暗。预乘是渲染管线那一侧的事。
+
+哨兵刻意**不认** GSAP 补间参数里的 `opacity:0`：淡入淡出的端点是 0/1，不是驻留的半透明面积。
+
+契约 `gsap-emit-v1.md` 同批增补「Alpha 交付口径」一节，`gtrk-mg` 图纸补剪映预乘纪律。
+
+## 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）
+
+讲软件 / 讲课件 / 讲代码的口播多是**两条文件同步录**：屏录一条、人像一条。此前流水线只能剪其中一条——
+`gtrk oralcut` 粗剪的每个切点没法落到另一条上，画中画只能去客户端手工摆，圆角与蒙版只有客户端看得见。
+镜像切点是纯算术（每颗 clip 一个偏移），却是「每片必做、手工必错」的事，现在做成命令：
+
+```bash
+gtrk pip lay --project <口播工程目录> --companion <屏录.mp4> [--shape ellipse|rectangle|heart|diamond|star|none] [--feather 10] [--corner-radius 0.25] [--border-radius <px>] [--anchor bottom-right] [--scale 0.28] [--margin 40] [--offset <秒>] [--dry-run] [--expected-revision <sha256>] [--json]
+gtrk pip lay --resume <屏录名>_pip_align.gtrk
+```
+
+**测偏移三分支，与 `gtrk audio align` 同一套原语**：缺省互相关自动对齐（人像为参考、屏录为待对齐）；
+置信度不足 ⇒ 产 `<屏录名>_pip_align.gtrk`（人像整段 + 屏录整段按估测偏移摆好），用户在客户端把「伴随源」轨拖齐保存后 `--resume` 读回偏移再铺；
+`--offset <秒>` 显式给值跳过检测。偏移口径全库统一：**正 = 屏录晚开录**。
+⚠️ 屏录 **MUST 带麦克风音轨**才能自动对齐（互相关没有参照就没法算），只有系统音的屏录只剩后两条路——开工时就要提醒用户；
+本命令与 `audio align` 一样只做**恒定偏移**，两台设备采样钟差导致的长片渐飘不矫正。
+
+**镜像切点**：主轨每颗非空档 clip 的 `track_st / duration` 原样落到屏录轨，`clip_st′ = clip_st − offset`，整毫秒域、不累加游标；
+越过屏录素材上界 / 下界的部分**钳位 + 留空 + 回执逐颗点名毫秒数**，MUST NOT 拉伸或变速——
+屏录比人像短 / 晚开录的那几段成片只见人像主轨，如实告诉用户。
+
+**铺两条轨，主轨与音轨一字不动**：屏录满幅轨（`track_index` = 现存视频轨最大值 + 1，静音）+ 人像画中画副本轨（再 + 1，静音，
+带 `clip_transform` / `border_radius` / `clip_mask`）。人声仍由主轨镜像音轨承担，副本轨 MUST NOT 双声；
+主轨不动 ⇒ 下游 `split` / `subtitle lay` / `mg` 照旧按 main 对 transcript，零感知。
+形状缺省 `ellipse` = 以画中画短边内切的正圆；`rectangle` 满幅可带 `--corner-radius`；`heart` / `diamond` / `star` 短边内切；`none` 只摆位不遮。
+`--scale` 的语义是**画中画显示高度占画布高度的比例**（缺省 0.28），写进 `clip_transform` 时按 contain-fit 反算。
+
+**幂等 + 不覆盖用户改动**：改参数直接重跑，自产 clip（`producer = gtrk:pip@1`）先剥后铺、空轨删除；
+用户在客户端动过、被清掉身份的画中画 clip **保留并在回执 `strip.keptForeign` 点名**（与 `matrix lay` 同一条认领纪律）。
+写方自检（恒等式 / 接缝 / 素材上界）破了即抛零副作用；原子写回 + revision 断言，`--expected-revision` 跨命令拒写口径同 `gtrk patch`；`--dry-run` 只算不写。
+回执打印的是**数字**（每颗的偏移 / 钳位 / 留空毫秒），不是一句「已验证」。
+
+链路位置：`oralcut` 检查点① → **`pip lay`** → 拆分 / 字幕 → 出片，**不新增必停点**，铺完让用户在客户端看一眼即可；
+口播图纸（`gtrk-talking-head`）开工五问加第 ⑥ 问（有没有同步录的屏录或第二机位、画中画形状 / 位置 / 大小），屏录题材默认不铺 B-roll。
+出片三口：客户端本地导出 / `gtrk render`（见下一节）/ 导剪映（`diamond` 剪映无对应，跳过并明示）。
+纯本地**零计费**，素材不上行。一条伴随源起步，多机位切人另立。
+⚠️ 客户端预览里看到画中画的圆角与形状蒙版，要等客户端同步更新（消费这两个契约字段的那一半随客户端发版）。
+
+### `gtrk render`：画中画的缩放 / 落位 / 旋转 / 透明、圆角与五形状蒙版随工程本地合成（link-clip-mask-contract-render）
+
+1.1.10 把叠加层渲进了成片，但每一层的**几何**还没读：叠加输入一律 contain-fit 后贴满画布，
+客户端里摆好的画中画渲出来是**满幅信箱**，圆角与蒙版更是零支持。现在按契约逐 clip 消费：
+
+- **`clip_transform`**：`scale_x/y` 在 contain-fit 之后再乘（与客户端「先 contain 再乘 scale」同口径，负值 = 翻转）；
+  `position_x/y` 以画布中心为原点落位；`rotation` 旋转（落点按旋转后包围盒算）；`alpha` 透明。
+- **`border_radius`**（画布像素）与 **`clip_mask`** 五形状（`rectangle` + `corner_radius` / `ellipse` / `heart` / `diamond` / `star`，与契约枚举一字不差）：
+  支持 `invert` 反相、蒙版自身 `rotation`、`feather` 羽化（0..100 = 占蒙版短边百分比）；两者同时在场**叠乘**（元素圆角 ∩ 形状窗），不降级。
+- 颗粒（`beat_track`）不动：契约不给颗粒这两个字段，颗粒尺寸由 HTML 自带。
+
+**不引图形库**：五形状 + 圆角 + 反相 + 旋转都是闭合路径填充，用纯 JS 扫描线光栅成一张 8-bit 灰度 PNG（node 内置 `zlib` 编码，**零新依赖**——
+多一个原生依赖就多一条安装故障面），ffmpeg 只负责 `gblur`（羽化）+ `alphamerge` + `overlay`。确定性、离线、**零计费**。
+蒙版纹理按参数 + 尺寸内容寻址落 `<工程目录>/.tonghe-cache/masks/<sha256>.png`，可复用、丢了重生；
+缓存目录不可写退系统临时目录，两处都写不了才放弃该纹理——此时该 clip **只按几何叠加并明示**（`maskSkipped`），MUST NOT 阻断渲染。
+
+**零回归门**：`clip_transform` 缺席或恒等、且无圆角 / 蒙版的 clip，滤镜链与 1.1.10 **逐字节相同**，既有黄金向量原样通过。
+`--json` 的 `overlay` 段新增 `transformed` / `masked` / `maskSkipped` 三个计数，完成话术逐类点名
+「几段按 clip_transform 落位 / 几段合成了蒙版或圆角 / 几段纹理不可用只按几何叠加」。
+两条口径：羽化是高斯近似，与客户端的距离场羽化**观感等价、不逐像素等价**；
+客户端专有蒙版形态（钢笔 / 文字 / 分屏 / 黑边 / 描边 / 多蒙版）只在客户端状态里，本地渲染不读。
+
+### `gtrk oralcut --lang`：按识别源语种分档校验，切点线不支持的码在抽取前就拒（link-enum-catalog-cli §7）
+
+1.1.10 的枚举清单把 `--lang` 改成按快照校验，但拿的是 `subtitle.languages`——那是翻译目标语与识别源语种的 **11 项共同范围**，
+会放行 `es-ES` / `pt-PT` / `ru-RU` / `vi-VN`，让用户抽完音频、传完文件，才被服务端 6015 拒。
+现在 `/catalog` 下发 `subtitle.source_languages`，**按 task_type 分档**（切点三线 7 项：`en-US` / `fr-FR` / `ja-JP` / `ko-KR` / `zh-CHS` / `zh-CHT` / `zh-CN`；
+`video_ai_subtitle` / `subtitle_translate` 11 项），`oralcut --lang` 改按 `video_oral_cut` 那一档在**抽取之前**校验，报错只列本线 7 项。
+退回规则不破 1.1.10 的两条既定口径：分档整体缺失（老服务端 / 旧快照）/ 缺该线 / 形态不合 ⇒ 退回 11 项共同范围；
+共同范围也拿不到或无快照 ⇒ 放行交服务端裁决——**fail-open、只降不升**。
+`long2short --language` / `transcript --lang` / `gtrk tool` 的翻译语种参数本来就不做本地取值校验，这次一格不动。
+
+## 1.1.10（2026-09-10）
+
+### `gtrk render` 现在会把 MG 颗粒与 overlay 真的渲进成片（add-render-overlay-compositing）
+
+此前本地渲染的视频侧**只投影一条主轨**：铺了 65 颗 MG 颗粒、铺了整轨 B-roll 候选，渲出来一个都没有，
+而且退出码 0、渲后质检一切正常——**缺件成品，却一声不吭**。
+现在按契约 z 序（`track_index` **升序**，越大越靠前）把**全部可见叠加层**叠进成片：
+overlay 视频轨（B-roll 候选 / AI 再现回铺）与 `beat_track` 的 MG 颗粒都在内。
+在客户端关了「小眼睛」的轨（`hidden`）整条不进片；多条候选轨都可见时成片取最上层（= 客户端预览所见）——
+渲染器**只读字段不猜**，与音频侧「只认 `muted`」是同一条纪律。
+
+颗粒那一段有计费：CLI 没有 HTML 渲染引擎，颗粒送同合云烤成 qtrle 透明 MOV 再本地叠。
+计量 = **唯一颗粒数 × 未命中缓存数**（按分钟），未命中时先出预估并要确认（`--yes` 跳过；
+`--json` 下必须显式 `--yes`，否则硬拒——机读模式没有 stdin，不静默提交计费任务）。
+缓存落 `<工程目录>/.tonghe-cache/particles/`，**与客户端导出剪映那条链同键同落点** ⇒
+任一端烤过，另一端直接命中：**第二次渲染零计费**，客户端烤过的工程 CLI 首渲即零计费。
+不想花钱用 `--no-particles` 出无颗粒版（overlay 视频轨照常合成，那部分零计费、纯本地）；
+`--particle-concurrency <n>`（1–8，默认 6）调并发。
+
+三条如实告知：跳过的颗粒、隐藏未叠的轨、缺素材未叠的 clip 都在人读日志与 `--json`
+（`particles` / `overlay` 两个新字段）里逐类点名。overlay 素材本地缺失**只降级不阻断**——
+B-roll 代理没下全，不该让一条 45 分钟的片子出不来。
+无叠加层的工程**滤镜图逐字节不变**（零回归门有黄金向量守）。
+⚠️ 顺带一条口径更正：`gtrk render` 不再是纯本地零计费命令——工程有未命中缓存的颗粒时，
+**颗粒 HTML 文本会上行**（素材本体仍不上行），此时会打一次合规告知。
+
+### 本地渲染的 clip 上限 500 → 2000：长口播不再被一个「借来的」阈值挡在门外（adjust-local-render-clip-ceiling）
+
+45 分钟口播经 `gtrk oralcut` 逐停顿切出 **593 个 clip**，本地渲染直接报「clip 总数 593 超过上限 500」——
+按 13 clip/分钟折算，这等于给本地渲染判了「口播不得超过约 38 分钟」，而这个限制**从来没有被当成产品决策做出过**：
+500 是**镜像后端**的常量，那边的语境是云端多租户资源保护（防单任务吃掉渲染机）。
+本地渲染没有多租户、输入还按路径去重（593 clip / 1 素材 = 1 个 `-i`），代价只是本机自己变慢、由本机用户自己承担。
+
+新值 **2000 由实测裁定**，不是「翻个倍听起来合理」——本机实测 ffmpeg 构建滤镜图的成本：
+
+| clip 数 | 初始化墙钟 | 峰值内存 |
+|---|---|---|
+| 500 | 1.25 s | 151 MB |
+| 1000 | 5.2 s | 264 MB |
+| **2000** | **20.3 s** | **476 MB** |
+| 5000 | 167.9 s | 1138 MB |
+
+时间近 **O(N²)**、内存线性（约 0.23 MB/clip），而且这只是**开渲之前**的等待。
+所以一度考虑的 5000 被自己的实测否掉（干等 2.8 分钟 + 1.1 GB）；2000 ≈ 2.5 小时口播，覆盖已知全部形态。
+
+配套两条：**超限话术**改成说清三件事（这是**本机**的闸、不是云端限制 / 当前多少 / 出路是拆工程或来提 issue）；
+clip 数 **超过 1000** 时先打一行 INFO 说明「构建滤镜图要花点时间，不是卡死」——
+那段没有任何输出，最容易被读成卡住。告知档是**绝对值**不是「上限的百分比」（相对量说不出用户要等多久）。
+叠加元素（overlay clip / 颗粒）**不计入**这个计数，闸值与计数口径一次只动一个。
+
+### `gtrk mg fetch`：registry 中性颗粒源，不会做动画也能拿到能用的颗粒（add-mg-registry-neutral-source）
+
+MG 车道此前只有一条路——你自己的栏目 MG 生产 skill 从零写 GSAP 颗粒。没有那套资产的人，`dispatch.mg` 就是空的。
+现在随包带一份 **Hyperframes registry 快照**（`src/data/mg-registry-catalog.json`，180 件，
+钉死来源 `heygen-com/hyperframes@8bf5b44`，快照日 2026-09-10）：`gtrk mg fetch` 不给 `--pick` 是**候选态**（只列不取，**离线可用**），
+给了才取块——取块三源按序试：**我方镜像（大陆可达）→ jsdelivr → GitHub raw**，每源 5 秒超时，
+任一源返回的字节 **MUST 过 sha256 与快照比对**（版本错位 / 篡改在这一步被拒）。
+`GITRUCK_MG_REGISTRY_BASE` 可整体覆盖取块前缀（自建端点 / 内网），与运行时资产的 env 覆盖同形。
+取回的块经**机械改写**成合规颗粒并过 `mg lint` 门：改画布 / 改透明底或满屏底 / 换字体（缺省取运行时镜像可证的 CJK 字体）/ 钉 composition_id。
+两种用法：`--slot <beat>` **派单模式**（从 `dispatch.mg` 取 composition_id 与坑位包络，产物落 `<工程>/mg/`）、
+`--id` + `--duration` **独立模式**。契约当前只收 1920×1080，其余画布明确拒绝。
+**刻意不引 hyperframes CLI**：端点是静态文件，Node 内置 fetch 够用——省掉用户侧 33 MB + 原生二进制 + Node ≥22 的负担。
+
+### `gtrk skills recommend` / `gtrk skills add`：第三方 skill 随包推荐目录（add-third-party-skill-catalog）
+
+我们的图纸只覆盖成片编排，视觉玩法（钩子 / 动态图讲解 / 动态字幕 / 数据可视化 / 地图 / AI 再现 / 拼贴 / 字幕 / 设计原则）
+一直是「你自己去找」。现在随包带一份**第三方 skill 推荐目录**（快照 2026-09-10，九个场景），
+`gtrk skills recommend` 无参列场景枚举、`--scene <id>` 按 tier（T1 在前）列条目，`gtrk skills add <repo>` 直接装。
+人读输出**恒走 stderr**，`--json` 时 stdout 只有 JSON。
+星数是**快照值**，回执明写「以仓库页为准」——目录随包发版，不联网校核，不假装是实时数据。
+公约正本同批立 §三‴「第三方 skill 推荐面：**三档、克制、不点名**」，六份成片图纸 SKILL.md 按它接推荐面：
+图纸先给自持方案，再轻提一句「要更多变体可以看第三方 skill」，**不在正文点名具体仓库**——点名要靠 `recommend` 命令去查。
+
+### 成片型图纸公约加一节「前六秒：钩子层」（add-blueprint-opening-hook-layer）
+
+公约正本（`docs/成片型图纸公约.md`）新增 §三⁗：前六秒决定完播，而外部钩子 skill 全是纯文本、不知道我方四车道，
+所以「钩子文案 + 前六秒画面 + 字卡节奏」三合一**由图纸自持**。
+口播链 / 配音链同批落执行文本：**检查点①之前**由 agent 产一份「前六秒方案」——
+钩子文案三候选（只改开口方式，**MUST NOT 改动用户的事实与数据**）+ 画面层三选一（A_ROLL / MG 字卡 / 拼贴或 AI 片段）+ 字卡节奏，
+**与其他拍板项同屏一次拍板**，MUST NOT 单独追问、MUST NOT 在检查点①之后再冒出来。
+答「开场照原样」= 零动作、后续不再提。
+
+### 首跑与 `gtrk init` 收尾补一句交接指路（add-agent-handoff-signpost）
+
+新用户跑完 `gtrk init` 常以为下一步该去客户端里跟 AI 对话。首跑块与 `init` 收尾各补一句明示：
+**客户端目前没有 AI 对话框，对话在 Agent 里进行**，客户端负责精修与出片。
+
+### 枚举清单：校验取值改由服务端下发，服务端加一种样式不用等 CLI 发版（link-enum-catalog-cli）
+
+此前 `--subtitle-type` / `--subtitle-color` 的可选值被**抄在 CLI 本地常量**里：服务端新增一种字幕样式，CLI 会当场拒掉那个**合法值**；服务端临时下架一个能力，CLI 还在往外发。两种都不报错，只是行为不对。
+现在启动云端命令时向 `GET /catalog`（公开只读口）拉一份枚举清单，落 `~/.gitruck/catalog.json`：新鲜期 24 h 内**零网络**，过期走条件请求（304 只推进时刻、200 整体替换），拉不到就沿用旧快照并打**一行**降级提示。
+`--subtitle-type` / `--subtitle-color` / `gtrk oralcut` 的 `--lang` / `--preset` / `--formats` 都改按快照在**上传之前**校验并列出可用集；`gtrk tool list` 与直调按服务端下架名单标「暂停服务」并拒绝提交（**只降不升、且只在快照新鲜时生效**）。
+`gtrk doctor` 新增「枚举清单」行（版本 / 拉取时间 / 落点）与 `--refresh-catalog`。
+三条硬性质：① **拉不到 MUST NOT 让命令失败**——任何失败分支都放行，交服务端白名单裁决；② **`--help` 路径零网络**（注册期只读快照文件，有真进程 fetch 计数守卫）；③ 服务端白名单**恒为唯一真相源**，本地校验只是「早点告诉用户」，所以无快照是放行而不是拒绝。
+本地清单有可能比服务端旧 ⇒ 报错文案一并告知逃生口：`--refresh-catalog` 立刻刷新，`--param` 绕过本地校验。与 infra `add-enum-catalog-api` 联动（该端点 2026-09-10 已上生产）。
+
+## 1.1.9（2026-09-10）
+
+### CLI 崩溃自动上报：崩了不再只留一句红字（link-client-error-report-cli）
+
+CLI 崩溃时**只上传错误消息与堆栈**到同合云 `POST /error/report`，不带素材、工程内容与凭据。
+四路收口：`uncaughtException` / `unhandledRejection` / 顶层命令异常 / 已知崩溃形态；
+同一进程内的连环崩溃按「名字 + 首帧」压成一条并累加 `occurrence_count`，不刷屏也不刷库。
+首次运行打一行告知，关闭方式两种：`gtrk init --no-crash-report`，或设 `GITRUCK_CRASH_REPORT=0`；
+`gtrk doctor` 新增「崩溃自动上报」行显示当前开关状态。上报前做凭据洗白与长度截断。
+与 infra 主件 `add-client-error-report`、客户端半 `link-client-error-report-client` 同线。
+
+### 长剪短：分屏开不开由开工一问决定，clips.md 回显分屏请求态
+
+（补记）分屏不再默认硬开：开工时先问一句「是否多人同框」，据此决定本次是否请求分屏；
+`clips.md` 回显本次的分屏请求态，避免「以为开了其实没开 / 以为没开其实开了」。
+
+### 倍帧素材的假切点：切点判定改在去重帧序列上进行
+
+（补记）倍帧（同一画面重复多帧）素材此前会在重复帧之间判出并不存在的切点，
+现在切点判定改在**去重后的帧序列**上进行。
+
+---
+
+## 1.1.8（bump 了但没发）
+
+`package.json` 从 1.1.7 bump 到 1.1.8（`2f20453`），但**这一版从未推上 npm** ——
+registry 上 1.1.7 之后直接是 1.1.9。留此条只为解释版本号为什么跳，无内容变更。
+
+---
+
+## 1.1.7（2026-09-09）
+
+### `gtrk` 装完即可敲：install 自持全局副本 + Windows 用户级 PATH + doctor「命令可达」+ upgrade 沿自己的通道升级（add-gtrk-command-availability）
+
+此前 `npx @gitruck/cli@latest install`（官网默认路线、全套 `install.ps1` 第三步）只装 skill 与配置，**从不安装 gtrk 本体**——npx 跑完把包丢掉，新开终端敲 `gtrk` 不是命令；`npm i -g` 路线则要靠 npm 全局目录恰好在 PATH 上。
+现在 `gtrk install` 先做第 ⓪ 步：运行中的自己若不是持久 PATH 能解析到的那份（npx 临时态 / 未 link 的本地检出），先 `npm i -g @gitruck/cli@<运行中版本>` 自持（钉运行版、已有更高版本不动）；随后按**持久** PATH（Windows 读注册表 HKLM+HKCU，不是启动它的终端给的 PATH）核对启动器目录，不在就追加到 HKCU 用户 PATH **尾部**（保留 `REG_EXPAND_SZ`、原值 `%…%` 不展开、不去重不重排、幂等）并广播 `WM_SETTINGCHANGE`；写被拒只给可读原因与手工指引、不让 install 退非零。macOS/Linux 不改任何 rc 文件，不可达时打一行 `export PATH=…`。
+`gtrk doctor` 新增「命令可达」行：持久 PATH 解析到且版本一致为绿，解析不到为红并指向 `gtrk install`，敲到另一版为黄。`gtrk upgrade` 按 `process.execPath` 是否在 `~/.gitruck/node/` 之下判定通道：私有运行时（桌面端自举落位）用私有 node + 私有 npm + `--prefix ~/.gitruck/npm` 升级并复核启动器，**不去找系统 npm**；npm 全局通道维持现状。
+规格：新立 `gtrk-command-availability`；`ffmpeg-runtime` 的「用户环境零侵入」条款收窄射程为 ffmpeg/字体等运行时资产（gtrk 自身启动器目录进用户 PATH 是明确例外）；`gitruck-home` 登记 `node/` `npm/` `bin/` 三目录（客户端自举的私有运行时布局）。与 opencut 仓 `add-cli-bootstrap-runtime` 联动：本版先发，客户端再发。
+
+### 封面工作台：T1 字体读用户本机、描边缺省 0（add-cover-workbench-font-switcher）
+
+`gtrk-cover` 排字工作台右栏新增「字体」下拉与「字重」档位（400 / 700 / 900）：下拉首项恒为 skill 注入的当期默认字（`T1_DEFAULT_FONT`，仍是 skill 按栏目封面风格资产或中性默认做的审美决策），
+其余项来自**用户本机已装字体**，三级取数、任一级成功即可用——打开即按内置候选表（约 70 款常见中文字体，中英文名两写法）做 canvas `measureText` 已安装探测；Chrome / Edge 点「读取本机字体」经 Local Font Access API 取全量（需授权一次，结果与探测结果取并集、当前选中项恒保留，接口返回空按失败退化并解释）；
+两条都没列出的在输入框敲 family 名回车应用。三级全失败不阻塞。导出走本机 `html2canvas`，本机字体天然可用；与 MG 颗粒「字体名 MUST 命中服务端注册表」是两条线，guide §10 已写明分界。
+T1 描边缺省由 2 改 0：思源黑 / 宋这类重叠轮廓的特黑字体加 `text-stroke` 会把部件内部轮廓描成镂空积木（缩略预览看不出、导出才炸），托底改用暗色双层 `text-shadow`，滑杆保留。
+引擎层（拖拽 / 方向键 / 滚轮 / 导出 / 舞台缩放）零改动。同批：SKILL.md 铁律 3 暴露面加「T1 字体与字重档位」、中性默认「描边不加」，checklist ⑥ 补描边与切字体后可读性。
+
+---
+
+## 1.1.6（2026-09-08）
+
+### 产物落点硬闸：计费前先实证落点可写，缺 `--out` 当场硬拒
+
+（补记）`gtrk oralcut` / `gtrk mg` 在**上传与计费之前**先实证产物目录真的写得进去，
+写不进就阻塞拉用户处理到可写为止（非交互当场硬失败），**不静默改投别的目录**；
+缺 `--out` 不再猜一个落点而是当场硬拒；MG 颗粒必须产在工程目录内。
+
+---
+
+## 1.1.5（2026-09-07）
+
+### 锚点金样入册（fix-anchor-top-hit-guarantee §5）：决策 pin v5 的金样清单 53 → 57、哈希重登记不升 v6
+
+`test/fixtures/broll-arrange/cases/` 新增 `44-anchor-sim-order-real-q1`（真机复刻 Q1/B04 两刀合璧：锚槽按原始 sim 取校门段而非融合分顶上来的广告牌，B02 泛化槽让位转次优）/
+`45-anchor-cross-beat-reserve-lay2`（备选轨同受预留约束 + 不相交 beat 零回归）/ `46-anchor-reserve-release`（逐锚 finally 与零长度 beat 早退两条释放路）/
+`47-anchor-vs-anchor-at-sec-order`（at_sec 先到先得、`reserved` 与 `consumed`+`top_by` 两种归因形态），均由 `regenerate.mjs` 产出，临时变异实证各自在「锚序退回融合分 / 关掉预留」下 expected 会变。
+决策层零改动（`matrix-lay.ts` 零 diff），既有 53 项金样逐字节不变、`cloud-form.json` 逐字节不变、`metering.json` 只多 4 条派生 entry（`METERING_ALGO_PIN` 不动）。
+v5 尚未发版 ⇒ `PIN_TO_MANIFEST_SHA[v5]` 由 `3bcc7aef…` 重登记为 `cc82e20e…`（57 项）而不升 v6，infra `link-anchor-top-hit-guarantee` 同批把 `_PIN_TO_MANIFEST_SHA[v5]` 改成同一个数。
+
+### gap 填充：恰等 1ms 的残量并入前一颗、合并容差统一到整毫秒格（决策 pin v5）
+
+`matrix lay` 主轨 gap 填充的合并容差从秒域浮点 `BLACK_BED_MERGE_EPS = 0.001` 改为整毫秒格具名常量 `BLACK_BED_MERGE_TOL_MS = 1`（`sec2ms` 整数差比较）。
+此前同一行 `x > 0.001` 在不同时间线位置上因浮点相位给出两种答案（0–300s 毫秒格上 `r3(t + 0.001) − r3(t)` 65.08% 的位置 `> 1e-3`、34.92% 的位置 `≤ 1e-3`），
+真机三条片里恰等 1ms 的残洞一处排出 0.001s 黑片、一处留 0.001s 裸缝。现在恰等 1ms 的残量恒判「有量」、恒进既有 ②a / ②a′ 延长链由前一颗吸收
+（前一颗 `track_ed` 与源窗终点同延 1ms、`track_st` 不动、`kind: "extend"`，不新增分支不新增 kind；源窗为此越出检索段界 ≤ 1ms 是具名例外，既有 `MICRO_SLOP` 松弛档覆盖）。
+同批改整毫秒格的判据（A 档）：`beatGaps` / `computeBlackBedHoles` / `mergeBlackBedSegments`、`fastFillBeatGaps` 全部容差消费点、高档直排的落位重叠与越 beat、碎尾吸收、锚槽 room、段界包含
+（52 份金样 + 3 份真机 plan 的 2182 段段界实测全在毫秒格上，逐值同解）。只改名不改值（B 档）：`CUT_ALIGN_EPS → CUT_ALIGN_WINDOW_SEC`（业务阈值 0.1s）。
+明确不改（C 档，登记转出）：吸附率比例 `1e-9`、`refineWindow` 帧号域与秒域 ε、`1/fps` 亏空、句界吸附带。
+「主轨零 gap」不再无条件打印：由整毫秒格对填充后主轨产物（含 solid 与 gap 填充槽位）的实扫得出，仍有 ≥ 1ms 缝即如实报数并 WARN；
+lay JSON `gap_fill` 新增**条件键** `residual_gaps { count, sec, items[] }`（零缝整键缺席）。
+决策产物字节：既有 52 项金样逐字节不变，新增 `cases/43-gapfill-eps-exact-residue`（同一 1ms 残量两相位同解）⇒ `LOCAL_DECISION_ALGO_PIN` v4 → v5、金样清单 52 → 53
+（`PIN_TO_MANIFEST_SHA[v5] = 3bcc7aef…`，infra `link-gapfill-eps-boundary-residue` 同批镜像、逐字相同；`METERING_ALGO_PIN` 不动，metering.json 只多一条派生 entry）。
+**发版序**：infra `add-arrange-decision-pin-echo` 回传先上线 → infra 决策层 v5 上线 → 本包发版；顺序错则 ≥ 1.1.3 客户端在读到 `server_ahead` 之前整轮退回自校验、
+`self_check_failed` 回落本地并白付一次编排费（服务端不按决策 pin 拒绝客户端；真会前置拒绝的是 `METERING_ALGO_PIN`）。
+
+### 时间消费侧统一：`gtrk render` 接缝判据与 `gtrk patch` 校验器同源（整毫秒格）、匿名 ε 清退、`qc` 阈值具名
+
+`gtrk render` 的同轨重叠 / 缝 / 尾补判据从 `±1e-6` 浮点秒改为**整毫秒格**（`sec2ms`），与 `gtrk patch` 的 E9 `same_track_overlap` 同一判据：
+`sec2ms(track_st)` 小于前一元素终点即拒渲、大于即补 gap、相等即相邻。**`render` 变严的一面**：重叠 ≥ 0.5ms 的工程拒渲，话术含修复指引
+（用 `gtrk patch` 校验并修正该轨，或用客户端打开工程重存一次后再渲染）；此前 render 收而 patch 拒的「一收一拒」不再存在。
+**变宽的一面**（只影响时码不在毫秒格上的老工程 / 客户端按帧写出的工程）：亚毫秒（< 0.5ms）重叠视为相邻不再拒渲，亚毫秒缝不再插一个 0 帧黑场元素；
+gap / 尾补时长落在整毫秒格上（`atrim=end=` 一类字面从 `276.366667` 变 `276.367000`）。三位小数工程的 filter_complex 逐字节不变；
+`allocateFrames` 累计量改整毫秒和、帧化经 `sec2frame`，真机工程副本（客户端按帧写出，110 元素）裁定帧数与改前相同（8291 帧）。
+`caption-align` 三种时间比较（同句回缝 gap / 字级去重 / 行推进与小 gap 桥接）统一到具名 `CAPTION_TIME_GRID_MS = 1`，`EPS = 1e-6` 与裸 `1e-3` 清退
+（亚毫秒差的重复字现在会去重、亚毫秒缝不再算一次桥接）；`audio align` 的 `adelay` 分流阈从 `0.0005s` 改整毫秒（不足 1ms 的偏移即零偏移）。
+全仓 32 处内联换算收编为 `frame-domain` 的 `r3`（15 处）/ `sec2ms`（15 处）/ `sec2frame`（2 处），逐值同；`matrix lay` 代理帧率不等判据改用
+`VFR_MISMATCH_RATIO`（相对差 1%，此前本地 `PROXY_FPS_EPS` 按绝对差 0.01 比、与其头注「1% 以内」不符）。
+`qc`：`cutMatchTolSec` 改名 `cutMatchWindowSec`（未经 `--json` 暴露，无别名），`cutMaxDriftSec / slotLookupSec / knownBlackHoleMatchSec` 进
+`QC_THRESHOLDS`（值不变），`av_drift` 项新增 `frames: {probed, expected}` 佐证（成片 `nb_frames` vs `sec2frame(工程时间线终点或音频时长, video_rate)`，判级不变）。
+决策层（`matrix lay` 的 `refineWindow / fillSlots / layAnchored / planBeatFills / slotTimes` 与 gap 填充）零改动，铺轨金样与 `MANIFEST` 逐字节不变。
+
+### 标准帧率表与 VFR 可见；`gtrk render` 对非整数 `video_rate` 从静默渲染改为报错（含修复指引）
+
+`frame-domain.ts` 新增本仓唯一的标准帧率表 `STANDARD_RATES`（`24000/1001, 24, 25, 30000/1001, 30, 50, 60000/1001, 60, 120`）与两个视图：
+`snapRationalRate`（源真值：与表中值相对差 ≤ 0.2% 才吸附，`29.970029 → 30000/1001`，非标值原样）、`deliveryRate`（交付整数：NLE 表
+`[23.976, 24, 25, 29.97, 30, 50, 59.94, 60]` 最近邻后取整，与客户端同口径、封顶 60，`(0, ∞)` 无洞）。`audio align` 兜底工程的顶层与素材
+`video_rate` 改经 `deliveryRate`（29.97 → 30、23.98 → 24 与此前同值；源片帧率解析不到时改为报错，不再静默写出 1fps 工程）。
+`probeGeometry` 在同一次 ffprobe 里加读 `avg_frame_rate`，给出 `avgFps` 与三态 `vfr`（`|avg − r| / r > 1%`；容器无 avg 时 `null` 不判）；
+判据阈值 `VFR_MISMATCH_RATIO` 一处定义，成片质检 `qc` 的 `vfr` 项改 import 同一常量（行为不变）。
+
+**`gtrk render` 变严**：顶层 `video_rate` 缺席、非正或非整数（典型是老工程里的 29.97）此前会按 29.97 静默分配帧数并进 `fps=` 滤镜，
+现在与 `matrix lay` / `gtrk patch` 同一条判据、同一条话术报错退出，且在解析 ffmpeg、探测素材、写临时滤镜文件**之前**即止（无产物、无残留）。
+修复：用客户端打开该工程重存一次即吸附到标准帧率（29.97 → 30、23.976 → 24），或手工把顶层 `video_rate` 改成正整数；
+`video_rate` 已是正整数的工程渲染结果与此前逐字节相同。
+
+`oralcut` / `long2short` 上传前：源片判为 VFR 时 WARN 一行（名义 `r_frame_rate` 与平均 `avg_frame_rate` 两值）但不阻断，上行几何仍是
+真实 `r_frame_rate`；`--json` 与 result.json 多一个 `source: { path, fps, avg_fps, vfr }`。源片帧率解析不到（`r_frame_rate = 0/0`）时
+在上传前报错退出（零抽取、零上传、不留产物目录），不以 25 / 30 兜底。`matrix index` 入库：VFR 视频素材逐条 WARN、`--json` 多
+`vfr_materials` 计数（不加索引列，检索透出的 `fps` 仍是名义值）；帧率解析不到的视频素材跳过不入库并 WARN（计入 `failed`）。
+`ai-drama lay` 拷贝后探测顺带 VFR 告警。决策层的吸附网格、铺轨金样与 `.gtrk` 字段零改动。
+
+### 跨时钟适配器：preview 代理落盘即实测、云端产物落地复核、写方自检覆盖音频轨
+
+`matrix lay` 下载（或缓存命中）每颗 preview 代理后现场 ffprobe 一次，`materials[]` 条目的 `duration / video_size / video_rate`
+改写**落盘文件本身**的实测值（此前写的是云端自述的原片时长与猜测尺寸）；云端自述只用于比对——时长差超一帧或帧率不等各打一条
+WARN，全量明细进 `--json lay.clock`（`proxy_probed / unverified / proxy_mismatch[] / proxy_fps_mismatch[]`）；探测失败回退自述并计
+`unverified`，不让铺轨失败。槽位选段与吸附网格不消费实测值（云本平价，决策与金样逐字节不变）。`ai-drama lay` 同款：拷贝后实测覆盖
+工作台 manifest 的 `measuredSec`，差 > 1ms 告警并进 `--json clock.manifest_mismatch[]`。`subtitle lay` 云端拆行的兜底行时码钳进父句
+包络（越出父句的行不再原样落轨），计数进 INFO 与 `--json clamped_lines`。`oralcut` / `long2short` 拉回 `.gtrk` 后以本地原片实测时长
+为墙复核不变量，只 WARN + `--json landing_check`，产物一个字节不改、退出码不变。写方自检射程扩到 `audio_track`，`audio lay` 写回前自检
+本次 BGM clip（存量违例只 WARN）。本地索引代理三档解码参数由单测锁定无任何时基滤镜。
+
+### matrix lay 落轨在工程帧网格上（写出侧变换，决策与金样不变）；gtrk patch 的毫秒投影改向下
+
+`matrix lay` 写出的每一颗 B-roll 槽位与黑底 clip，起止时码现在都是顶层 `video_rate` 帧网格上某个整帧号的投影
+（与 `gtrk patch` 同一套 `sec2frame / f2ms`）。帧格化是**写出前的一次变换**：填槽 / 锚定 / gap 填充 / 源窗精修等
+决策层仍以毫秒与实数游标工作，选段、切分位置（`clip_st`）与金样逐字节不变；写出时每颗槽位两端各取一次帧号
+（端点挪动 ≤ 半帧 + 1ms），相邻槽位的接缝由同一个帧号构成，黑底按 beat 包络投影、与首槽起点天然封口。取整帧后
+`clip_ed` 越过检索段界（或素材时长）时宁短一帧并让同轨后续槽位整体前移一帧（接缝仍相等），逐次 INFO 可见。
+本地槽位与云端编排返回的槽位走同一入口。此前槽位只知道毫秒，真机 30fps 工程里 B-roll 轨 62 颗有 30 颗、黑底
+10 颗全部离网格，客户端帧级缩放下「没有一条边对得上」，还有两处一帧黑闪与一处溢出一帧。
+工程顶层缺 `video_rate`（或非正、非整数）时 `matrix lay` 直接报错退出、工程零改动，不再有毫秒路可退；
+`--json` 的 `lay` 多一个 `frame_grid: { rate, slots, black_bed, shifted }` 诊断块；过短黑片账面的帧数按就近取整判
+（网格上的一帧黑片如实进账）。
+
+`gtrk patch` 的帧号 → 毫秒投影由就近改为**向下**（`f2ms`）：客户端合成器按「起点 ≤ t < 终点」采样，
+就近投影会让 24 / 30 / 60fps 下三分之一的帧位晚一帧才在场；向下之后客户端与 `gtrk render` 对同一帧号
+得到同一有效帧。可见变化：这些帧位上写出的 `track_st / track_ed` 比以前小 1ms，帧号不变，往返照旧可逆。
+
+### ai-drama lay / mg lay 落轨帧格；投影终点规则
+
+`ai-drama lay` 写出的每颗 AI clip 与 `mg lay` 写出的每颗 MG 颗粒，起止时码现在都是顶层 `video_rate` 帧网格上整帧号的投影
+（与 `matrix lay` / `gtrk patch` 同一套换算、同一个向下方向）。`ai-drama lay` 的毫秒决策链（建议时长 / 剩余 / 末镜吃满 /
+不足即跳）一字不改，帧号由累计位置一次取整，相邻镜的接缝由同一个帧号构成；取整帧后越过素材实测时长时宁短一帧、同包后续镜整体前移
+一帧（逐次 INFO 可见），不足半帧的镜跳过。`mg lay` 对每颗颗粒的窗口两端各取一次帧号，同 beat 的主颗粒与 `-aux` 覆层同窗即同一对
+帧号，`--only` 保留搬运的存量颗粒不重投影；拆分稿的 beat 毫秒包络本身不变。此前两者只知道毫秒，真机 60fps 工程里 21 颗 MG 颗粒
+全部离网格，客户端向上帧化与 `html_animate_render` 就近帧化会在同一颗颗粒上差一帧。工程顶层缺 `video_rate`（或非正、非整数）
+时两条命令直接报错退出、素材 / 颗粒不复制、工程零改动；`ai-drama lay --json` 多一个 `frame_grid: { rate, shifted, dropped }`。
+
+`gtrk split` / `gtrk subtitle` 所依赖的时间线投影改为**起点取整一次、终点由时长导出**（`track_ed = track_st + r3(e − s)`），
+不再两端各自取整；非整毫秒相位下终点与以前最多差 1ms，投影产物仍留在毫秒域、不吸帧。
+
+### lay 命令写回前自检不变量
+
+`matrix lay` / `mg lay` / `ai-drama lay` 在写回工程之前自检**本次写出的** clip：裁剪恒等式、同轨零重叠（含与既有邻居）、
+`clip_ed` 不超素材实测时长（容差 1ms）；违约直接抛错点名 clip_id 与不变量，工程文件逐字节不写。工程里由旧客户端重存留下的
+存量违例只打一条 WARN 汇总（kind 计数 + clip_id 样本 + 修复指引），不阻断本次写回。
+
+### 字幕拆行改走云端，剪掉的字不再上屏
+
+`gtrk subtitle lay` 的拆行不再在本地按字宽硬切：缺省把回缝后的句子送到同合云 `subtitle_line_split`
+（HanLP 分词 + 词性权重 + 按你所选样式模板与真实画布实算的宽度预算，**0 积分**、照留痕），
+拿回的每一行再按**字级时码**贴回时间线——行首行尾落在真正开口的那个字上，不是按字数比例内插。
+
+投影也改成字级：口播剪辑常在句内剪口吃 / 重读，以前整句文本会把剪掉的字显示回来（真机一份 52 句工程，
+88% 的字幕文字对不上那一刻说的话）；现在只有时间线上存活的字才上轨，被剪成多片的同一句按时间线序拼回一条。
+
+相邻字幕的空隙桥接阈值从 0.5s 放到 **1.5s**：语义对齐剪映的「自动填充文本空隙」，句间换气（真机 0.5~1.3s）
+不再留黑屏闪断；≥1.5s 的真实停顿仍然不硬填。`--max-gap` 照旧可调，0 关。
+
+云端不可达（没配 key / 离线 / 超时）**不报错**：回缝后的句整句上轨、长句未拆，WARN 说清楚下一步；
+`--json` 多了 `splitter` / `cloudUnavailable` / `cloudDegraded`。要走老的本地拆窗器加 `--offline`
+（它已冻结、只做兜底；`--max-units` 只在离线下有意义）。两条 skill 里「字幕纯本地零云端」的说法随之改口。
+
+### 内部重构：时间换算收敛到一处
+
+秒 / 毫秒 / 帧换算（`sec2frame / f2ms / derive` 与 17 处各自复制的 `r3`）收敛到 `src/lib/frame-domain.ts` 一份正本，行为零变化——不改任何写出值与取整方向。
+
+## 1.1.4（2026-09-06）
+
+### AI 片段回填不用再手搓脚本了
+
+`gtrk ai-drama lay` 收下 AI Drama Desk 的 return-v1 导出包，把你在外面生成好、自己挑过的片段
+确定性地铺成一条独立 AI 轨——**纯本地、零模型调用、零计费**，生成那一步仍然发生在你和外部平台之间。
+
+在这之前，回填是靠现写脚本干的。真机上那份脚本把 `setpts` 系数写反过一次（本该放慢写成了加速，
+差了 0.42 秒才被发现），而且每条片子都要重写一遍、工程文件上不留任何登记。
+
+两条你会撞到的行为：
+
+- **不完整的包整批拒收**。导出清单里只要还有镜头没导出，命令直接报错、一个 clip 都不铺——
+  半个包铺进去，成片会在那个窗口无声无息地缺镜。
+- **素材比窗口短就留空档**，不拉伸也不循环。末镜尽量吸收到窗口终点，但不会为了填满而凭空造帧。
+
+已经铺过的 AI 轨若被你在客户端拖动过，重跑会拒绝覆盖并提示 `--replace-all`；判不准时一律按
+「拒绝覆盖」处理——手调丢了不可逆，多问一次便宜得多。
+
+## 1.1.3（2026-09-05）
+
+### 成片终于有人声了
+
+`gtrk render` 此前只混 `audio_track`，**视频 clip 自带的音轨从来没进过混音**——口播工程的人声正是
+跟着视频素材走的，所以渲出来的成片实测只有 −70 LUFS（数字静音）。现在遍历全部 `video_track`
+取内嵌音轨，与 BGM 一起混，收口加上与客户端同口径的限幅与总音量。
+
+叠加轨（B-roll / AI 再现）的原声默不作声——静音的**唯一依据是 `muted` 字段**，铺轨命令落轨时
+写什么就是什么，渲染器不按轨序或车道名自作主张。解说链里要保留原片原声的片段，把该轨 `muted`
+置 `false` 即可。工程一个音源都没有时会明说「将出无声成片」，成片照常产出。
+
+### 整片没声音的片子不会再被报成合格
+
+上面那条缺陷之所以能一路走到交付，是因为 QC 把静音一律判成提示级——一段留白和整片哑掉用的是
+同一个级别。现在按整片响度（`ebur128` 的 integrated loudness）单独判定，低于 −50 LUFS 判严重、
+退出码非零。逐段静音仍是提示级，一个字没动。
+
+已知边界：只有极轻 BGM、刻意无人声的成片可能被误判；完全数字静音时 `ebur128` 输出 `-inf`，
+按远低于阈值处理、不会漏判。
+
+**射程**：质检的前提是你走了 `gtrk render`。只铺轨、或改由客户端出片的流程不会触发这条判定——
+它是「渲出来的片子有没有声音」的闸，不是成片质量的全局保障。
+
+### 字幕不再重复
+
+一句话被智能剪辑切成几片后，`gtrk subtitle lay` 会给每一片都写一条**完整整句**的字幕——真机上
+151 条字幕里有 39 种文本重复、共 89 个实例，时间线上肉眼可见一串重复块。现在同一句的多个片段
+先按时间缝回一条再上轨（同工程 151 → 102 条，重复归零）。回缝与 `--max-gap` 是两个开关：
+关掉小 gap 桥接，回缝照样生效。
+
+### skill 过期会被主动告诉你
+
+**`npm i -g` 只更新 CLI 包，不会刷新已经装好的 skill**——这条认知缺口让 skill 在真机上停了 43 天，
+agent 一直照着废弃的作业指令干活。现在需要 skill 的命令启动时会做一次廉价核对，落后了就点名说明
+并给出修复命令（`gtrk skills install` 或 `gtrk upgrade`）；一致时一个字都不输出。
+`gtrk doctor` 也会显示新鲜度。`GTRK_SKILL_FRESHNESS=off` 可整块关闭。
+
+前提是先跑过一次 `gtrk skills install`（那时才会写下比对基准）；在那之前判不出，静默跳过。
+
+### 爆音检测此前从未生效过
+
+**这不是阈值调优，是一个检测项从产品第一天起就是死的。** 旧版本报「爆音 0」不代表你的片子没问题——
+它代表这项压根没跑出结果。两条判定腿双双恒假：true peak 的正则按同一行匹配，而 ffmpeg 把数值写在
+`True peak:` 的**下一行**；另一条腿匹配的 `Number of clipped samples` **根本不是 astats 的指标**，
+那行永远不会出现。而消费侧「取不到值就跳过」的写法，让解析失败和「测出来没超标」在报告里长得一模一样。
+
+修好之后重新标定了分级，因为原来那条 −1 dBTP 是广播交付线、前提是内容已做响度归一，而成片没有：
+14 条真实语料里 12 条越过它。现在 **−1 dBTP 报提示**（已越交付上限，平台二压可能被削），
+**+1.0 dBTP 或样本域削波比例越限才报严重**。实测真·硬削波成片能被稳定判严重，真实语料一条不误伤。
+
+同时补了一条闸：**测量值解析不到时会明说「本次未生效」**，不再静默放行。这个洞能潜伏一整个产品
+生命周期，就是因为它连一行日志都没有。
+
+已知边界：true peak 是 4 倍过采样的 inter-sample peak，与「听得见的失真」不是一回事——越线不等于一定难听。
+
+### 会听懂「逐步推进」了
+
+`docs/成片型图纸公约.md` 早就把「逐步推进（每步停等确认）」定为正式模式名，但只有图纸层认识它，
+命令手册层的 skill 只认「只要这版工程」这类**范围**信号。于是用户说「先剪口播、然后我们逐步推进」
+时，逃生门逐字判定为不触发，agent 一路连跑了三个 skill。现在公约新立「节奏信号识别」条款，
+射程覆盖一切会自动接力的 skill；四份命令手册层 skill 的逃生门同时认范围与节奏。
+没有这两类信号时，自动接力的默认一字未改。
+
+### 其他
+
+- `gtrk mg` 铺轨完的提示不再宣称「预览需某个 change 上线」——那个 change 在客户端
+  2026-07-12 就已归档，这行字却一直在误导人。同时立下纪律：用户可见文案不得写死跨仓件名、
+  目录路径或对侧上线状态断言，要表达「暂不可用」得用能自动失效的运行时判据。
+- `gtrk render --json` 回执新增 `audio` 字段（音源盘点与是否无声）。
+
+## 1.1.2（2026-09-03）
+
+### 编排结果多了一份机读账本
+
+`gtrk matrix lay --json` 的回执新增 `lay.arrange_run`：这一轮云端编排调了几次（`rounds` 恒在）、
+每次的编排量与合计（`units_total`，幂等回放的那一轮不重复计）、本地复算与服务端产物有没有差
+（`diff_count` 与 `diffs` 同在同缺，不再出现 `diff_count: 0` 却没有 `diffs` 的假「比过且一致」）。
+只在真的调过云端时才出这个键；走素材矩阵、或总闸压回本地的零回归路径照旧没有。
+
+### 服务端会回报它用的是哪一版决策算法
+
+编排回执带 `decision_pin`：CLI 把它与自己内置的版本号比对，服务端比本机新时采纳服务端产物并把
+自校验差异降为提示，比本机旧或对不上时如实告警。升级 CLI 与服务端不同步时，你会第一时间知道。
+
+### 素材理解的判决只作用于被看过的那一段
+
+`matrix describe` 每个候选只理解一帧，此前那一帧的 `blurry` 等判决会挂到整个候选的所有片段上。
+现在判决只作用于被理解的那一段（回执里的 `describe.at_sec` 就是那一帧的时刻），其余片段按中性处理，
+不再因为一帧模糊就把整条素材降权。
+
+### 其他
+
+- `gtrk patch`：既存违规的判定改用与位置无关的键（元素身份 + 违规码 + 证据值），在既存违规元素之前
+  插入新元素不再把旧账误判成本次造成而硬拒。
+
+## 1.1.1（2026-09-02）
+
+两轮旅拍解说真机复盘（五条素材、27 条问题逐条求证）落地的一批修正，多数是你能直接感知的行为变化：
+
+### BGM 对齐换了语义
+
+- `gtrk audio lay --beat-align` 现在把 **BGM 的情绪峰值锚到成片的高潮点**，锚点前后按小节线平铺补齐；
+  两侧都够长时不平铺。旧行为是把整条 BGM 往后推到首个重拍，片头会凭空多一段静音。
+- 成片高潮点由拆分稿的叙事结构推定（升华段 → 转折 → 回扣 → 0.75 处兜底，兜底档会明说是猜的），
+  可用 `--climax <秒>` 直接指定。
+- 顺带修复：`--no-loop` 此前从未生效。
+
+### 铺画面更准
+
+- 关键词锚改取**原始相似度最高**的合格命中，并为锚预留第一名，不再被前面 beat 的普通槽位吃掉
+  （此前钉过排第 29 的段）。
+- 索引同趟解码并联黑场检测，治「叠化过黑」漏检：匀速渐变的场景切换分数被压到零，此前会把横跨两个
+  镜头的过黑整段包进一颗 B-roll。
+- `describe` 回执如实报「理解帧数 / 段总数」的覆盖率（`describe_coverage`），并对「描述里写了叠加物
+  而对应标记为假」的帧出提示。
+
+### 素材入口更结实
+
+- `--dirs` / `--materials` 能表达含英文逗号的路径（重复传即可），枚举跟随符号链接（跨域照收、断链只跳不崩）。
+- **全域零枚举改为硬失败**：`ok:false`、退出码 1，并点名真因（逗号切分 / 断链 / 扩展名不在白名单），
+  此前是「✅ 完成 0/0」加退出码 0，agent 会接着往下跑。
+- `gtrk tool` 产物目录带唯一后缀防撞，并行两条同类任务不再互相覆盖。
+
+### 图纸与计费口径
+
+- 旅拍图纸：开工两问补为三问（新增源片语种 / 方言，粤语写 `zh-HK`）；写稿语速改按音色的实测挂钟语速取
+  （缺省约 330 字/分，不再用计费常量 240）；写稿前加素材适配性退出闸；检查点①补编排量预估。
+- `is_copyright` 口径写准：`1` = 可商用（自有或已授权），`0` = 不可商用。
+- describe / qc 的计费报数改按实探的成员身份：`credits_estimated` 即实耗，`credits_would_be` 为原价。
+
+## 1.1.0（2026-09-02）
+
+### ⚠️ 升级须知：1.0.8 铺过的工程不会自愈
+
+1.0.8 有一处**槽位接缝**缺陷：铺出的主轨会带 −1 毫秒的同轨重叠，
+`gtrk render` 检出后**硬拒**，成片渲不出来。
+
+- **本版修掉了产生它的原因**，但**修不了已经铺坏的工程**。
+- 手上有 1.0.8 铺的工程 ⇒ 重跑一次 `gtrk matrix lay --project <目录>`，
+  或用 `gtrk patch trim` 逐颗修端点。
+- 升级后打开旧工程仍渲不出，**不是新版没修好**，是那份工程还带着旧缺陷。
+
+另外：服务端的新编排逻辑 2026-09-01 已上线。**1.0.8 与它不配套**——
+本地复算自校验会判定不一致、弃用服务端产物改用本地编排，而那次调用**已经计费**。
+也就是说停在 1.0.8 的每一次云端编排都在白花钱。请尽快升级。
+
+### 编排取数路：本地素材缺省改走云端（补记于 2026-09-03）
+
+这一条随 1.1.0 上线，但当时的更新日志没有写明，补记如下。
+
+- 不传 `--arrange` 时按素材来源自动定档：**铺你自己电脑里的素材 ⇒ `cloud`**（编排在云端做，按编排量计费，
+  跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 ⇒ `local`（编排仍在本机，不计费，行为逐字不变）。
+- 本地素材路**不再自动回落本机**：连不上、被拒、产物违约这类系统故障直接报错，并给出逃生舱
+  `--arrange local`（它是冻结的旧口径，只应急）。你自己拒绝预估确认或开了总闸，仍照旧回落，但会明说换了引擎。
+- 本地复算自校验保持开启：服务端产物与本机算得不一致时如实告警，不会悄悄采纳。
+- 这不是省钱开关：两条路都要花钱，只是花在不同环节（云端编排量 vs 矩阵检索次数）。
+
+### 快速模式不再留黑片
+
+`--gap-fill fast` 的填充顺序从三级扩到五级：
+
+本 beat 候选 → 相邻颗粒延长 → **跨 beat 借候选** → **次地板补真画面** → 仍不够才黑片。
+
+- **跨 beat 借**：某几句自己的候选被别的段先占光时，从全片没人用过的素材里取料。
+  真机 `proj2-B` 的 B18 曾整段 8.952 秒落黑，而全片供给/需求是 4.10× ——
+  不缺料，缺的是分配。借来的画面与那几句稿子相关性会弱一些，日志里**指名报出**。
+- **次地板补真画面**：短于最小镜头长（1.2s）的残洞也填真画面。
+  这些是快切，同样指名报出。真机三条片的黑片从 8 处降到 **0 处**。
+- **逐步模式（`--gap-fill solid`）刻意保留黑片**——黑的地方就是没匹配上的地方，
+  精修时一眼看得见。两档的差别现在不只是「停几次」，是**产物形态不同**。
+
+### 新增：`gtrk audio tighten`
+
+收紧配音的**句间**停顿，纯本地零计费。
+
+```bash
+gtrk audio tighten --project <工程目录> --dry-run   # 先看会压几处
+gtrk audio tighten --project <工程目录>             # 落盘
+```
+
+- 真机实测：一条 203 秒的解说里 54 秒是句间静音（26.6%），收到 0.2 秒后全片缩到 171 秒。
+- **只压跨句界的停顿**，句内换气与原声引用段一律不动。
+- 产物是**原件多 clip 铺轨**，不烤新音频文件 —— 每处停顿都是可拖的刀口，随时能退回原样。
+- ⚠️ 它会改变 beat 窗口，**跑完必须重铺**（命令会提醒）。建议在铺画面**之前**跑。
+
+### 新增：`--fragment-interval`（TTS 句间停顿）
+
+```bash
+gtrk tool audio_tts_clone --text-file 稿.txt --speaker <音色> --fragment-interval 0.2
+```
+
+**仅自训音色生效**；云引擎音色传了会**明确报错**，不会静默忽略。
+不传时产物与本版之前逐字节一致。云引擎音色请改用上面的 `gtrk audio tighten`。
+
+### 其它
+
+- 幂等回放时不再误报「已执行并计费」——服务端命中缓存回放时本就不二次扣费，
+  旧版会无条件断言已计费，把用户引向一笔不存在的账。
+- 随包文档订正：`audio_tts_clone` 的文本上限是 **5000 字**（旧文写 2000）；
+  计量单位与单价一律以 `gtrk tool list` 实时显示为准，文档不再写死。
+
+### 已知问题
+
+- 极少数情况下主轨会留下 **1 毫秒**级的黑片或裸缝（30fps 下 0.03 帧，渲染不可见）。
+  已立案追踪，不影响出片。
+
+### 「刚修好的误删又出现了」——客户端版本下限（补记于 2026-09-04）
+
+本版起，`gtrk matrix` 铺出的每一颗 clip 都带一个**产出方身份**（`producer`），
+用来回答「这颗是我铺的、还是你自己复制粘贴出来的」。有了它，重铺时不会再把你复制出来的副本
+当成自产物删掉。
+
+⚠️ **但这个身份要客户端帮忙保住**，而 **2026-08-26 之前装机的打包客户端不会**——
+它保存工程时是逐键重造 clip 的，不认识的键**存一次就丢**。所以：
+
+- 用旧客户端打开工程、**保存一次**，这一批身份就没了；
+- 下次再 `gtrk matrix` 重铺，判据回落到老口径（材料前缀 + 条数），
+  于是**你复制出来的那颗又会被删掉**——看起来像「刚修好的毛病又犯了」。
+
+**这不是新事故，是回落到本版之前的行为。** 处置：把客户端升级到 2026-08-26 之后的版本，
+然后重跑一次 `gtrk matrix lay --project <目录>` 把身份补回去。
+
+> 身份只在**本机 `.gtrk`** 上存在。工程上云再取回来（经 `video_project_struct` 往返）该键**不会保留**，
+> 这是契约里就写好的，不是缺陷；此时 CLI 自动走老口径，行为与本版之前一致。