@gitruck/cli 1.1.4 → 1.1.6

package/AGENT.md

@@ -20,6 +20,15 @@
   （如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）。
   需要引用媒体时**用原路径引用**，不做副本。
 - 临时文件（抽帧图 / 中间物等）一律放系统 temp 且**用完即删**（含中断 / 失败路径也要清干净）。
+- **交付物 SHALL 直写工程目录，MUST NOT 中转暂存**（2026-09-07 事故后立）。
+  产颗粒 / 产工程 / 产派单稿时，**写入路径本身**就必须是工程目录里的最终路径；
+  MUST NOT 先写 agent 自有工作目录（会话工作区 / `work/` / 暂存区）再拷进工程。
+  · **中转本身即违规**，不以「最后确实拷进去了」免责——事故当晚工程目录里的 10 个颗粒
+    全都正确落地了，漏出来的是那份留在 agent 工作目录里的副本。
+  · **体积不是豁免理由**：上一条禁的是「大媒体文件」，而事故里漂掉的是 2.7–6.2 KB 的 HTML。
+  · 与上一条的分界：抽帧图这类**不交付**的中间物走系统 temp；**要交付的东西没有暂存态**。
+  · 直观后果：一份无主副本只要留着，迟早与工程正本漂成两版，而**两份读起来各自都自洽**，
+    没有任何信号提示谁是正本。
 - 违反本条的直观后果：用户系统盘被静默吃满——这是真机发生过的事故，不是假设。
 
 **在 gtrk-cli 仓库自身里跑真机走查时，追加一条（2026-08-23 立）：**
@@ -162,7 +171,7 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 - **节奏预设**：`steady` 保留更多停顿（稳）、`concise` 默认精炼、`compact` 最紧凑（压停顿最狠）。
 - **部分格式失败不致命**：CLI 如实回显云端 `errors`（某格式没出来不影响其余）。
 - **本地预处理 · 只传抽出物**：跑批先本地探几何 + 抽 16k 单声道 mp3（默认）/ 压 720p 代理（`--visual-assist`）；**毛片永不上传**，只传几十 MB 抽出物。抽出物按原片 `size:mtime` 指纹缓存在 `~/.gitruck/audio-cache/`，同毛片重剪免重抽（720p 与 mp3 各缓存各的、互不覆盖）。
-- **结果恒落盘 · 可按 task_id 恢复**：每次跑批恒写 `<产物目录>/result.json`（含完整 `report`，**不受 `--json` 约束**）；submit 一成功就写 `task.json`（含 `taskId`）面包屑，且产物目录**延后到首次写入才建**（提交前失败不留空壳、提交后失败留 `task.json` 可恢复）。→ stdout 丢了 / 中途崩了，报告与 `taskId` 都在盘上，用 `gtrk oralcut-result <taskId>` 秒级取回、**别重跑整条 `oralcut`**（见 §2.1）。
+- **结果恒落盘 · 可按 task_id 恢复**：每次跑批恒写 `<产物目录>/result.json`（含完整 `report`，**不受 `--json` 约束**）；submit 一成功就写 `task.json`（含 `taskId`）面包屑，且产物目录**延后到首次写入才建**（提交前失败不留空壳、提交后失败留 `task.json` 可恢复）。→ stdout 丢了 / 中途崩了，报告与 `taskId` 都在盘上，用 `gtrk oralcut-result <taskId> --out <目录>` 秒级取回、**别重跑整条 `oralcut`**（见 §2.1）。
 
 **细节微调 —— 按用户诉求因势象形、自由组合**（上表是常用一等 flag；下面是节奏细调 + 完整取值）。你有云端全部参数，按需自由决定用哪些。**唯一要求：名字 / 取值 / 范围照文档用**（别记错拼错）；传越界云端报 `6016` 附原因、照改即可（乱传不产错误成片、只明确报错）。没特别诉求就跑默认。
 
@@ -185,14 +194,14 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 
 - 优先级：`--preset` → 一等 flag → 透传（后者覆盖前者）。用户**自己点名**某参数 + 值 → 照他原样透传（CLI 底层支持任意云端参数）。**以上即 agent 需要的全部参数、本文档自足**（`gtrk oralcut --help` 也列全部 flag）；官网的原始 HTTP API 文档是给人看的，agent 不必也无法访问。
 
-### 2.1 取回命令：`gtrk oralcut-result <taskId>`（报告丢了别重跑）
+### 2.1 取回命令：`gtrk oralcut-result <taskId> --out <目录>`（报告丢了别重跑）
 
 按 `task_id` 从云端取回一个**已完成**任务的报告 + 三方工程产物（可选本地渲染成片），**跳过预处理 / 上传 / 提交 / 轮询**。用在：`--json` 的 stdout 丢了、进程中途崩了、或想换台机器再拉一次产物 —— **不要重跑整条 `gtrk oralcut`**（后端 `get_task_by_id` 幂等，报告本就存着）。`taskId` 从产物目录 `task.json`、上次结果 JSON 或日志里取。
 
 | 参数 | 作用 | 缺省 |
 |---|---|---|
 | `<taskId>`（位置参数） | 任务 id | 必填 |
-| `-o, --out <dir>` | 产物目录 | `<当前目录>/<taskId>-video-project-<时间戳>` |
+| `-o, --out <dir>` | 产物目录 | **必填**（2026-09-08 起无缺省；`--out .` = 当前目录本身） |
 | `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
 | `--jianying-draft-dir` / `--ffmpeg-path` / `--crf` / `--codec` / `--no-open` / `--json` | 同 `oralcut` | — |
 
@@ -202,7 +211,7 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 
 ```bash
 # 报告丢了、按 task_id 取回（不重跑云端）
-gtrk oralcut-result 88269671080189958 --json
+gtrk oralcut-result 88269671080189958 --out ./88269671080189958-video-project --json
 # 顺带本地重渲成片（原毛片需仍在 gtrk 内嵌路径）
 gtrk oralcut-result 88269671080189958 --render --out "D:/回收/某条"
 ```
@@ -368,7 +377,7 @@ gtrk patch set   --project <dir> --total max               # 改顶层总长（
 
 **跑完读 `report`、验证、给用户交代**（`--json` 的 stdout 那行带 `files` / `errors` / **`report`**；别只信"成功"、别谎报三端都好）：
 - **读 `report`（因势象形的另一半）**：`duration_before`→`after`（剪了多少）；`script_source`/`final_script`（无稿 `rebuilt` 时把 `final_script` 回给用户核对）；`dropped[]`（剔了哪些、`reason` retake/misread）；`coverage`（<0.6 附 `low_coverage` = 文稿与实拍严重不符）；`uncovered_script[]`（**漏读**：文稿有、实拍没找到 → 如实说，疑似漏识别则建议 `--visual-assist` 重跑）；`review_points[]`（建议复核处）；开了 visual_assist 还有 `suspect_omissions` / `stt_recovered` / `visual_assist_degraded`。**据此因势象形**：覆盖率低 / 漏读多 → 开 `--visual-assist` 或核对文稿重跑；节奏不满意 → 调 `--preset` / 散参数重跑（同毛片可反复剪对比）。
-- **报告也在盘上、丢了能取回**：同一份 `report` 恒写在 `<产物目录>/result.json`（不必依赖 stdout）。万一 stdout 没接住或进程崩了 → 直接读 `result.json`，或 `gtrk oralcut-result <taskId> --json` 按 task_id 重新取回，**不要重跑 `oralcut`**（见 §2.1）。
+- **报告也在盘上、丢了能取回**：同一份 `report` 恒写在 `<产物目录>/result.json`（不必依赖 stdout）。万一 stdout 没接住或进程崩了 → 直接读 `result.json`，或 `gtrk oralcut-result <taskId> --out <目录> --json` 按 task_id 重新取回，**不要重跑 `oralcut`**（见 §2.1）。
 - 确认产物目录在、`gtrk/project.gtrk` 非空（>0 字节）；要剪映就确认剪映草稿根里有**同名工程目录**，且目录里是 `draft_content.json` + `draft_meta_info.json` **两个精确文件名**——剪映只认这两个固定名，带前缀的（如 `clip0_draft_content.json`）它扫不到、草稿列表里不显示。`long2short` 逐 clip 草稿同判据。
 - 云端 `errors` 非空 → 如实告知哪个格式失败、原因。
 - 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`），并**据 `report` 给一句交代**（剪了多久 → 多久、去掉了什么、有无漏读需复核）。
@@ -410,8 +419,8 @@ gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":
 | 云端 errors 含某格式 | 该格式单独失败、其余可用；把 errors 原文回给用户/反馈维护方 |
 | 同毛片改了内容但产物像旧的 | 指纹意外没变 → 加 `--reupload` 强制重传 |
 | 任务很久不动 | 轮询有 30min 墙钟上限；超时 CLI 会报，稍后重试或查云端任务 |
-| 结果 JSON / 报告丢了（stdout 没接住、进程崩了） | 别重跑 → 读产物目录 `result.json`，或 `gtrk oralcut-result <taskId> --json` 按 task_id 取回 |
-| 想换机器再拉产物 / 补渲成片 | `gtrk oralcut-result <taskId> [--out <目录>] [--render]`（须同账号 key；产物约 60 天有效，过期仍可取报告） |
+| 结果 JSON / 报告丢了（stdout 没接住、进程崩了） | 别重跑 → 读产物目录 `result.json`，或 `gtrk oralcut-result <taskId> --out <目录> --json` 按 task_id 取回 |
+| 想换机器再拉产物 / 补渲成片 | `gtrk oralcut-result <taskId> --out <目录> [--render]`（须同账号 key；产物约 60 天有效，过期仍可取报告） |
 
 ---
 

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 片段回填不用再手搓脚本了

package/README.en.md

@@ -160,7 +160,7 @@ Chain names above: *口播链* = talking-head (you shot yourself: short-form mon
 | Situation | What to do (tell the agent, or it handles it) |
 |---|---|
 | You only want the editing project, no visuals yet | Stop after "cut a version": "just the editing project for now" |
-| Lost the report / want the artifacts on another machine | "fetch the previous one by taskId" → `gtrk oralcut-result <taskId>` (skips the cloud re-run) |
+| Lost the report / want the artifacts on another machine | "fetch the previous one by taskId" → `gtrk oralcut-result <taskId> --out <dir>` (skips the cloud re-run) |
 | You want to choose between several B-roll candidates | "lay a few more B-roll candidates" → `gtrk matrix --lay N`, then toggle track visibility in opencut |
 | B-roll fill is poor / there are empty slots | Adjust `--score-floor` / `--top-k` and re-run, or "search a single query" → `matrix search "<query>"` to patch it |
 | You want to lay B-roll from your own footage | "use my local footage" → `gtrk matrix index --dirs <folders>` to build the index, then `gtrk matrix --local --dirs … --project …` (**your footage never leaves your machine**; see the matrix section in the command reference) |
@@ -371,13 +371,13 @@ Live pricing is queried from the website's price table under `asr` before the ru
 
 > Every run **always writes a `result.json` into the output folder** (regardless of `--json`), and once submission succeeds it also drops a `task.json` breadcrumb. Even if stdout is lost or the run crashes midway, the report and `taskId` are on disk, and `oralcut-result` below can fetch everything back in seconds without re-running the cloud job.
 
-### `gtrk oralcut-result <taskId>`
+### `gtrk oralcut-result <taskId> --out <dir>`
 
 Fetches the report and the three project formats of an **already completed** task by `task_id` (with optional local rendering), **skipping preprocessing / upload / submission / polling** — use it when the report is lost or you want to pull the artifacts again on another machine, without re-running the cloud job.
 
 | Parameter | Purpose | Default |
 |---|---|---|
-| `-o, --out <dir>` | Output folder | `<cwd>/<taskId>-video-project-<timestamp>` |
+| `-o, --out <dir>` | Output folder | **Required** (no default since 2026-09-08; `--out .` = the current directory itself) |
 | `--render` | Additionally render locally (requires the raw file still at the path embedded in gtrk, plus ffmpeg) | off |
 | `--jianying-draft-dir <dir>` | Jianying draft root (or `auto`) | Reads the init config / auto-detects |
 | `--no-open` / `--json` | Same as `oralcut` | — |

package/README.md

@@ -158,7 +158,7 @@ gtrk transcript "D:/素材/采访视频.mp4"
 | 情况 | 怎么做（跟 agent 说，或 agent 自动） |
 |---|---|
 | 只想要剪辑工程、暂不做视觉 | 到「剪一版」就停：「先只要剪辑工程」 |
-| 报告丢了 / 换台机器再拉产物 | 「用 taskId 取回上次的」→ `gtrk oralcut-result <taskId>`（跳过重跑云端） |
+| 报告丢了 / 换台机器再拉产物 | 「用 taskId 取回上次的」→ `gtrk oralcut-result <taskId> --out <目录>`（跳过重跑云端） |
 | 想在几个 B-roll 候选里挑 | 「B-roll 多铺几条候选」→ `gtrk matrix --lay N`，opencut 里用轨道小眼睛切换对比 |
 | B-roll 填充太差 / 有空槽 | 调 `--score-floor` / `--top-k` 重跑，或「单独搜个词」→ `matrix search "<词>"` 补 |
 | 想用自己的素材铺 B-roll | 「用我本地的素材铺」→ `gtrk matrix index --dirs <素材夹>` 建索引后 `gtrk matrix --local --dirs … --project …`（**素材本体不上云**，详见命令参考 matrix 节） |
@@ -367,13 +367,13 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 
 > 每次跑批都会把这份结果**恒写一份 `result.json` 到产物目录**（不受 `--json` 约束）；提交成功后还会落一份 `task.json` 面包屑。即便 stdout 丢了、或中途崩了，报告与 `taskId` 都在盘上，可用下面的 `oralcut-result` 秒级取回、无需重跑云端。
 
-### `gtrk oralcut-result <taskId>`
+### `gtrk oralcut-result <taskId> --out <目录>`
 
 按 `task_id` 从云端取回一个**已完成**任务的报告与三方工程产物（可选本地渲染成片），**跳过预处理 / 上传 / 提交 / 轮询**——报告丢了、或想换台机器再拉一次产物时用它，不重跑云端。
 
 | 参数 | 作用 | 缺省 |
 |---|---|---|
-| `-o, --out <dir>` | 产物目录 | `<当前目录>/<taskId>-video-project-<时间戳>` |
+| `-o, --out <dir>` | 产物目录 | **必填**（2026-09-08 起无缺省；`--out .` = 当前目录本身） |
 | `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
 | `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
 | `--no-open` / `--json` | 同 `oralcut` | — |