@gitruck/cli 1.0.5 → 1.0.7

package/AGENT.md

@@ -8,6 +8,9 @@
 > → 拉回 gtrk/剪映/PR 三方工程文件 →（可选）本地 ffmpeg 渲染成片 → 三端打开**。云端零改动、纯结构产物，
 > 源视频不出本地。结果/报告恒落盘 `result.json`，可按 `task_id` 秒级取回、无需重跑（见 §2.1 / §4）。
 
+> **写/改 structure 级成片图纸**（旅拍 / 口播链 / 直播切片 / Vlog……）先过 `docs/成片型图纸公约.md`
+> ——双模式命名（快速成片 / 逐步推进）、决策前置三条腿、MG 临场泛化的横切正本与自检清单都在那里。
+
 ---
 
 ## 产物落点纪律（全局 MUST · 本 playbook 与随包全部 skill 通用）
@@ -34,6 +37,41 @@
 
 ---
 
+## 工程文件改动纪律（全局 MUST · 2026-08-25 立）
+
+- **agent MUST NOT 裸手改 `.gtrk` JSON。** 元素级编辑（挪位置 / 改时长 / 切开 / 改参数）
+  一律走 **`gtrk patch`**。
+- **为什么不是「小心点就行」**：`.gtrk` 一个片段的时码是**两套并存**的
+  （`clip_st`+`clip_ed` 与 `clip_st`+`duration`）。改 `duration` 不同步 `clip_ed`，
+  **客户端 importer 优先读 `clip_ed`** ⇒ 用的是陈旧出点；而**后端 Profile A 反而不强校验它**
+  ⇒ 没人报错。这是**静默失败**：命令说成功、你以为改了、实际没改。
+- 另外轨道时基端点要落在 `video_rate` 的帧边界上，浮点秒累加会漂。这两件 `gtrk patch`
+  都替你做（恒等式同步 + 帧对齐 + 写前全档校验 + 原子写回 + 机器可读回执）。
+- **例外只有一个**：铺自产物的那几条既有链路（`gtrk matrix` 铺轨、`gtrk mg` 铺颗粒、
+  `gtrk audio` / `gtrk subtitle` 建新轨）—— 它们只动自己新建的东西，不改既有 clip 的时码。
+
+## 标定数据落点纪律（全局 MUST · 2026-08-29 立 · tighten-distribution-surface）
+
+**新增**的实测标定数据 MUST 写进对应 change 的 `design.md` 附录，MUST NOT 写进代码注释或
+随包分发的 `skills/*/SKILL.md`。
+
+- **什么算标定数据**：写明了**取值理由 / 代价曲线 / 实测分布 / 禁区论证 / 真机实验结论**的内容
+  ——即别人据以能省下试错的东西。例如「MUST NOT ≥1.5：槽位 51→53、扰动 26/51、吃进 9 条真实
+  短镜头」「score 集中于 0.1~0.4，0.25+ 已是强命中」「p10=2.12 / p90=4.97」。
+- **什么不算、MUST NOT 迁走**（这三类留在代码里）：
+  ① **正确性约束**——`MUST NOT` 开头的行为契约、不变量、耦合关系（如「不消耗随机序列」
+     「MUST NOT 复用云端地板的校准假设」「MUST NOT 改吃 candidates 精简集」）；
+  ② **丑话**——副作用、风险、不对称后果（如「误判 stable 丢检索粒度，误判 unstable 只是不省钱」）。
+     丑话属于「怎么用」，是使用者的决策依据；
+  ③ **算法本体**——公式与判定式本身就是代码在做的事，注释是它的可读投影。
+- **代码注释的目标口径**：只讲**是什么 + 怎么用**，不讲**为什么是这个值**。
+- **存量不清洗**（主理人 260829 拍板）：既有注释里的标定数据已随公开镜像与 npm 发布出去，
+  删它们保护为零、却净损失维护者上下文，且那两个文件是承重墙密集区、误伤代价高。
+  本纪律**只管新增**。已知的存量标定已在 `tighten-distribution-surface/design.md 附录 A`
+  留档（含「改值前必须知道什么」速查表）——**改那些常量前先读它**。
+
+---
+
 ## 0. 一句话流程
 
 ```
@@ -85,6 +123,12 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 
 ## 2. 核心命令：`gtrk oralcut <毛片>`
 
+> **双轨收音的毛片先对轨**：用户有独立外录音轨（领夹麦/录音笔的 wav/mp3/m4a/flac）时，先跑
+> `gtrk audio align "<毛片>" "<外录>"`（纯本地零计费）——自动互相关测偏移+置信度，高置信直接换轨
+> 产 `<名>_extaudio.mp4`（视频流零像素改动），低置信产对齐工程交客户端拖齐后 `--resume` 读回；
+> 然后拿换轨产物进 oralcut，转写与成片就都是外录声。已换好轨/无外录的毛片直接进，零差别。
+> 场景编排细节见 `/gtrk-talking-head` 图纸 §二。
+
 | 参数 | 作用 | 缺省 |
 |---|---|---|
 | `<毛片>`（位置参数） | 本地口播原视频路径 | 必填 |
@@ -224,6 +268,71 @@ gtrk transcript "D:/素材/采访视频.mp4" --json
 
 ---
 
+## 2.4 元素级编辑：`gtrk patch`（改工程唯一入口）
+
+```bash
+gtrk patch move  --project <dir> --clip c2 --to 5.0        # 挪位置
+gtrk patch trim  --project <dir> --clip c2 --out -1s       # 改时长（出点相对增量）
+gtrk patch split --project <dir> --clip c2 --cut 5.5       # 切成两段
+gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
+gtrk patch set   --project <dir> --total max               # 改顶层总长（工程级）
+```
+
+**寻址两条路**（互斥，二选一）：
+
+| | 用法 | 说明 |
+|---|---|---|
+| 按 id | `--clip <clip_id>` | 最常用。命中 video/audio **镜像对**时视为**一个编辑单元** |
+| 按位置 | `--track <video\|audio\|beat>:<track_index> --at <sec>` | 命中条件 `track_st ≤ at < track_ed` |
+
+⚠️ **`--at` 是寻址参数，不是 split 的切点**；split 的切点是独立的 **`--cut`**。
+两者可同时给：`patch split --track video:0 --at 5.0 --cut 5.5` = 「定位 5.0s 处那个元素，在 5.5s 切开」。
+
+⚠️ **空档（gap）不能用 `--clip ""` 寻址** —— 契约允许多个 gap 共享 `clip_id=""`，它不构成地址；用 `--track/--at`。
+
+**四个动作的参数**：
+
+| 动作 | 参数 | 语义 |
+|---|---|---|
+| `move` | `--to <sec\|Nf>` | 只改落点，时长与源窗都不动 |
+| `trim` | `--in` / `--out` | **相对增量**。`--in` 让源窗与轨上入点**同动**（标准 trim）；`--out` 只改出点 |
+| | `--set-in` / `--set-out` | 同上，但给**绝对时码** |
+| | `--slip <delta>` | **只换源窗**：轨上落点与时长都不动。⚠️ trim-in 有两种业界语义，所以必须你显式选一种 |
+| `split` | `--cut <sec\|Nf>` | 切点。两段各须 ≥1 帧；新片段 id 为 `<orig>-2` 递增 |
+| `set` | `--muted` / `--no-muted` / `--volume <gain>` / `--opaque` | 元素级参数。`--volume` 是**线性增益不是 dB** |
+| | `--total <sec\|Nf\|max>` | 顶层总长。**工程级 op，与元素寻址互斥** |
+
+**通用**：`--dry-run` 只算不写；`--json` 回执到 stdout（人读日志转 stderr）；
+`--ops <file|->` 批量事务（一次读、全算、全校验、一次写；**任一条失败零写**并报第几条）。
+
+**`--expected-revision <sha256>` — 跨命令写回断言**（并发写仲裁，你多半用得上）：
+`patch` 每次都会自己护住「本次读→改→写」这段窗口，但它护不到**你两条命令之间**的空隙——
+典型形态是「先 `--dry-run` 看一眼 → 用户在客户端顺手改了 → 你再真写」，第二条命令重新读盘、
+拿到的是新内容，于是**照写不误、把用户的改动覆盖掉**。
+做法：把上一条回执里的 `revision` 原样传给下一条的 `--expected-revision`；盘上内容一旦变过即拒写。
+缺省不传 = 只护进程内窗口（既有行为不变）。
+
+**时码字面**：秒（`3.5` / `3.5s`）或帧（`105f`）；相对量带正负号（`-1s` / `-2f`）。
+
+**回执字段**：`applied`（是否真写了）、`revision`（工程当前内容指纹：写入成功=**落盘后的新值**、
+干跑=读取时刻的值）、`ops[]`（每条含 `action` / `scope` / `resolved` 定位三元组
+`{track, clip_id, track_st}`、改前改后时码）、`warnings[]`、`preexisting[]`（入档既存问题，非本次造成）。
+⇒ **下一轮据 `resolved` 复核「我上轮改的还是这一个吗」**，据 `revision` 作下一条的 `--expected-revision`。
+
+**它会拒你的几种情况**（都是零副作用、文件逐字节未变）：
+
+- 幻觉 id / `--track/--at` 没命中
+- `clip_id` 真撞名（同轨重复 id）⇒ 列出候选，改用 `--track/--at`
+- 镜像对上做**参数类**改动 ⇒ 参数是投影私有的，要 `--track` 指明改哪个投影
+- 本次改动会造成时码不变量违规（如同轨重叠）⇒ 硬拒；**入档既存的**违规只报 `preexisting` 不阻断
+- **写回冲突**：读进来之后工程内容被改过（客户端保存了实质改动 / 你传的 `--expected-revision` 已过期）
+  ⇒ 拒写并回 `conflict: {expected_revision, actual_revision}`。**处置：重读工程、在新内容上重算你的改动、再写**，
+  MUST NOT 硬覆盖。⚠️ 判据是**内容**不是时间戳——用户只是按了保存但一个字没改（内容逐字节相同）**不会**触发拒写
+- 顶层 `duration` 键不在场时用 `--total` ⇒ 缺席自带「按末端机械算出」语义，新增该键会改消费与计费口径
+- 只给 `--track` 不给 `--at` ⇒ v1 射程是**元素级**，不写轨对象上的键
+
+---
+
 ## 3. 产物结构 + 三端打开
 
 ```