@gitruck/cli 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # 更新日志
 
+## 未发布
+
+### 成片终于有人声了
+
+`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 铺过的工程不会自愈
@@ -16,6 +147,17 @@
 本地复算自校验会判定不一致、弃用服务端产物改用本地编排，而那次调用**已经计费**。
 也就是说停在 1.0.8 的每一次云端编排都在白花钱。请尽快升级。
 
+### 编排取数路：本地素材缺省改走云端（补记于 2026-09-03）
+
+这一条随 1.1.0 上线，但当时的更新日志没有写明，补记如下。
+
+- 不传 `--arrange` 时按素材来源自动定档：**铺你自己电脑里的素材 ⇒ `cloud`**（编排在云端做，按编排量计费，
+  跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 ⇒ `local`（编排仍在本机，不计费，行为逐字不变）。
+- 本地素材路**不再自动回落本机**：连不上、被拒、产物违约这类系统故障直接报错，并给出逃生舱
+  `--arrange local`（它是冻结的旧口径，只应急）。你自己拒绝预估确认或开了总闸，仍照旧回落，但会明说换了引擎。
+- 本地复算自校验保持开启：服务端产物与本机算得不一致时如实告警，不会悄悄采纳。
+- 这不是省钱开关：两条路都要花钱，只是花在不同环节（云端编排量 vs 矩阵检索次数）。
+
 ### 快速模式不再留黑片
 
 `--gap-fill fast` 的填充顺序从三级扩到五级：
@@ -64,3 +206,22 @@ gtrk tool audio_tts_clone --text-file 稿.txt --speaker <音色> --fragment-inte
 
 - 极少数情况下主轨会留下 **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 自动走老口径，行为与本版之前一致。

package/README.en.md

@@ -459,11 +459,17 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--arrange <m>` | **B-roll arrangement route** — **picked automatically by material source; you normally do not pass it**: your own local footage → `cloud` (arranged in the cloud, billed by **arrangement volume**, with an estimate and a confirmation prompt first; `--yes` skips). Material from the asset matrix → `local` (arranged on your machine, not billed, unchanged byte for byte). `shadow` is an observation mode: your machine lays as usual while the cloud runs the same arrangement for comparison only. ⚠️ On the local-footage route `--arrange local` is not accepted (passing it is a parameter error), and if the cloud cannot deliver a result the command **fails outright** instead of quietly switching to a different algorithm. It is **not a way to save credits** either — asset-matrix material is billed for search. Both routes cost something; they just cost it at different steps | picked by material source |
 | `--arrange-qc` | **Arrangement-time QC** (off by default): before anything is laid, check each beat's anchor sentence for whether the picture actually shows what the script says; if not, swap candidates and re-arrange, at most 2 rounds, then deliver and report honestly which lines still do not match. Zero rendering throughout — it replaces the "lay → render → look → re-lay → render again" loop. ⚠️ Judging goes through the material-understanding endpoint and is **billed per frame** (1 frame per anchor sentence per round); an estimate and a confirmation prompt come first (`--yes` skips). Orthogonal to `--arrange`: works on both the local and cloud routes | off |
 | `--arrange-cost-cap <n>` | Hard cap on arrangement volume for a single cloud run: over the cap the server **refuses up front** — zero execution, zero charge (it does not cut off midway). Only meaningful with `--arrange shadow\|cloud` | uncapped |
+| `--dump-request <file>` | **For troubleshooting**: write the **exact bytes actually sent** for the cloud arrangement request to this file. The server **does not keep your plan** (only a size summary), so when something goes wrong this file is the only thing that can reproduce the call — just send it to us. ⚠️ It **must not point inside the project directory** (projects get zipped, copied and synced around, and this file contains your beat names and search queries); with `--arrange-qc` each round writes its own file, round N landing at the same name plus `.roundN`. The machine-readable receipt is `lay.arrange_run.dump_request` | not written |
+| `--explain` | **Emit the tuning gauges**: by default the machine-readable accounting gives only the empty-slot count `lay.dedup.emptySlots` (enough to tell whether your material pool is too thin); the rest of the tuning detail (how many of those were caused by window refinement, how many jump-cut waivers were exhausted, how many high-motion / blurry segments were used) sits behind this flag, and the human-readable log follows the same rule. It changes no decision — the project output is byte-for-byte identical | off |
 | `--arrange-estimate-only` | **Estimate only, do not execute**: stop right at the cloud-arrangement billing confirmation, report the arrangement volume and return **successfully** (`ok:true` + `estimateOnly:true` — that is "I am deciding", not "I declined"). Zero cloud calls, zero changes to the project file. Machine-readable values live in `lay.arrange.units` / `lay.arrange.scale`. ⚠️ What it saves is **that one cloud call and its charge** (plus the candidate downloads and laying that follow), not the whole chain: the denominators of the arrangement volume still require reading the project, the plan, and re-projection. On the asset-matrix route it reports `applicable:false` rather than **0**. When given together with `--yes`, this flag wins | off |
 
 **`matrix fetch <clip_id...>` (pull raw footage during the fine cut, project-independent)**: for materials you have **searched with billing** (hits in the grant ledger), re-signs fresh download links for free by clip_id and lands them as `<clip_id>.<ext>` — when the rough cut is already exported to Jianying and one more B-roll is needed, you can pull the raw file locally and drag it straight in without going back to the client app. The flow is always **two-step**: pick clip_ids from `matrix search` → `matrix fetch` to pull (fetch itself is free of charge, performs no search, and has no confirmation gate). **Grants are persistent**: the 24h-expiring signature is no obstacle — a clip searched three days ago still fetches fine. Ungranted items are reported one by one as "not granted" with the way out (run one billed search for that keyword to obtain the grant) and never block the rest; one batch ≤ 500. **The initial scope covers video clip raws only** (the re-sign surface for image/audio materials is not open yet; such ids land in missing with a hint). Outputs never enter `.gtrk` and never land in the Jianying draft folder; material added inside Jianying does not flow back into the project (export is one-way).
 | `--json` | Machine-readable: stdout carries only the result JSON | off |
 
+> **Cloud arrangement keeps nothing on the server**: the projected plan you send up is **not stored**. What we keep is a size summary, the metering version and the recomputed amount — enough to settle a billing dispute independently, but nothing that reveals your material structure. The price of that is that **when something goes wrong we have nothing to reproduce it with** — hence `--dump-request <file>`, which keeps the exact bytes that went up **on your own machine**; send us that file when you need help. It is off by default and **refuses to write inside the project directory** (projects get zipped and copied around).
+>
+> Two protections sit in front of the endpoint, both answering **429 with zero execution and zero charge**: a per-key rate limit, and a check that recognizes "the same plan resubmitted over and over with different parameters". Transport retries send **byte-for-byte identical** request bodies and are never counted against either.
+>
 > **Beat windows are re-projected on the spot**: in dispatch-consumption mode, **before the first cloud retrieval**, each beat's `[track_st, track_ed]` is recomputed from "`transcript` × the current `.gtrk`", and retrieval, `broll-plan.json` and track laying all use the recomputed values (`--lay 0` obeys the same rule; ad-hoc `search` is unaffected). The timecodes in `dispatch.json` are only a **projection-time snapshot**, used as a fallback solely when re-projection is impossible — **so after editing the talking-head track you can run this command directly without re-running `gtrk split`**. `--json` always emits `reprojection:{mode,degraded,reason?,drifted,max_offset,shrunk,dropped}`; beats with **zero surviving span** after re-projection are skipped (no retrieval quota is burned on them and nothing is laid). If re-projection is impossible (missing transcript / project not found / no talking-head material on the main track) → it **degrades to the snapshot with a warning and a `--json` marker**, while retrieval and the plan still complete instead of hard-failing; behaviour for non-v1 projects is unchanged (the plan lands first, then the version gate exits non-zero).
 >
 > Candidates' `preview_url`/`cover_url` **are unsigned and never expire** (once the local proxy is on disk it is always reused); what carries a signature and expires in roughly 24 h is the **source `url`**, re-signed by the client's "confirm source clip" flow — **you do not need to re-run this command just to re-sign**.

package/README.md

@@ -449,6 +449,8 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--arrange <m>` | **B-roll 编排取数路**，**按素材来源自动定档、一般不用传**：铺你自己电脑里的素材 → `cloud`（编排在云端做，按「编排量」计费，跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 → `local`（编排仍在本机、不计费，逐字不动）。`shadow` 是观测档：本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` 不受理（传了报参数错）；云端拿不到产物时**直接报错**，不会悄悄换算法把活干完 | 按素材来源自动 |
 | `--arrange-qc` | **编排期质检**（缺省关）：落轨**之前**就查每个 beat 的卡点句「画面有没有给到稿子说的东西」，没给到就换候选重排，最多 2 轮，到限即交付并如实登记还差哪几句。全程零渲染——替代「铺完 → 渲 → 看 → 重铺 → 再渲」那两轮。⚠️ 判定走素材理解口、**按帧计费**（每个卡点句 1 帧/轮，命中判定缓存的不重复计费），跑前报预估并征求确认（`--yes` 跳过）。与 `--arrange` 正交：本机档与云端档都能开 | 关 |
 | `--arrange-cost-cap <n>` | 云端编排单次编排量上限：超限服务端**前置拒绝**、零执行零计费（不是跑到一半掐断）。只在 `--arrange shadow\|cloud` 时有意义 | 不限 |
+| `--dump-request <file>` | **排障用**：把**实际上行的**云端编排请求体逐字节写到该文件。服务端**不保存你的 plan**（只留规模摘要），所以出了问题只有这份文件能复现——把它发给我们即可。⚠️ **不能指向工程目录内**（工程会被打包、拷贝、同步出去，而这份文件里有你的 beat 名与检索词）；开 `--arrange-qc` 时每轮各写一份，第 N 轮落在同名加 `.roundN`。机读回执在 `lay.arrange_run.dump_request` | 不写 |
+| `--explain` | **外发调参仪表**：缺省的机读账面只给「留空槽数」`lay.dedup.emptySlots`（够判断素材池是不是不够用），其余调参用的细账（其中多少是窗口精修致空、跳剪避让枯竭放行几次、取用了几个高运动/模糊段）收在本开关后，人读日志同口径。不影响任何决策，工程产物逐字节不变 | 关 |
 | `--arrange-estimate-only` | **只要预估不要执行**：走到云端编排的计价确认那一步就停，报出编排量后**成功**返回（`ok:true` + `estimateOnly:true`——那是「我在做决定」，不是「我拒绝了」），零云端调用、工程文件零改动。机读值在 `lay.arrange.units` / `lay.arrange.scale`。⚠️ 它省的是**云端那一次调用与其计费**（以及其后的候选下载与落轨），不是整条链：编排量的分母本来就要读工程、读 plan、做重投影才算得出。素材矩阵路报 `applicable:false` 而**不是 0**。与 `--yes` 同给时以本开关为准 | 关 |
 | `--out <file>` | ad-hoc 模式结果落文件；`matrix fetch` 原片落盘目录（绝不写剪映草稿目录） | stdout / `./matrix-fetch/` |
 | `--json` | 机读：stdout 只输出结果 JSON | 关 |
@@ -482,6 +484,14 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 > ⚠️ 预估值只供双端一致性校验，**实际计费恒以服务端复算值为准**；两值不一致时服务端会拒绝执行且不计费。
 > 上行的只有决策要读的字段——素材绝对路径、签名 URL、画面描述文本、派单负词、口播原文整句一律**不出你的机器**。
 >
+> **服务端一行不留**：那份上行的 plan 我们**不保存**（留痕只有规模明细、口径版本与复算金额，
+> 够独立核对一笔账，但翻不出你的素材结构）。代价是**出了问题我们这边没有可复现的东西**——
+> 所以给了 `--dump-request <file>`：它把真上行的那串字节留在**你自己的机器上**，
+> 排障时把那个文件发给我们即可。缺省不写，且**不许写进工程目录**（工程是要被打包拷走的）。
+>
+> 频率上有两层保护，命中都是 **429、零执行零计费**：一层按次数限流；另一层认「同一份 plan
+> 被反复换参数重提」这种形态。传输失败的重试发的是**逐字节相同**的请求体，不会被算进去。
+>
 > 候选的 `preview_url`/`cover_url` **不带签名、不会过期**（本地代理落盘后一律复用）；带签名约 24h 过期的是**原片 `url`**，由客户端「确认原片」链路重签——**不必为「重签」重跑本命令**。
 >
 > **重跑会剥旧重铺，但不碰你改过的轨**：候选轨的身份按「素材前缀 + 上一轮登记指纹」认，不再认轨号（客户端保存会把 overlay 轨整体重编号）。一旦某条候选轨被判定「你编辑过」（改过 clip，或在客户端确认过原片使 material 变成 `broll-raw-*`），本次**整体不铺**：不剥任何轨、不追加新轨、`.gtrk` 逐字节不变，`broll-plan.json` 照常产出，命令给出「哪条轨 / 什么证据 / 下一步」并以非 0 退出码结束（`--json` 出 `{ok:false, refused:[…]}`）。要强行重铺加 `--force-relay`。