@gitruck/cli 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # 更新日志
 
+## 未发布
+
+### 锚点金样入册（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 片段回填不用再手搓脚本了