@gitruck/cli 1.0.3 → 1.0.6

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,21 @@
 
 ---
 
+## 工程文件改动纪律（全局 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 的时码。
+
+---
+
 ## 0. 一句话流程
 
 ```
@@ -85,6 +103,12 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 
 ## 2. 核心命令：`gtrk oralcut <毛片>`
 
+> **双轨收音的毛片先对轨**：用户有独立外录音轨（领夹麦/录音笔的 wav/mp3/m4a/flac）时，先跑
+> `gtrk audio align "<毛片>" "<外录>"`（纯本地零计费）——自动互相关测偏移+置信度，高置信直接换轨
+> 产 `<名>_extaudio.mp4`（视频流零像素改动），低置信产对齐工程交客户端拖齐后 `--resume` 读回；
+> 然后拿换轨产物进 oralcut，转写与成片就都是外录声。已换好轨/无外录的毛片直接进，零差别。
+> 场景编排细节见 `/gtrk-talking-head` 图纸 §二。
+
 | 参数 | 作用 | 缺省 |
 |---|---|---|
 | `<毛片>`（位置参数） | 本地口播原视频路径 | 必填 |
@@ -224,6 +248,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. 产物结构 + 三端打开
 
 ```
@@ -306,6 +395,37 @@ gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":
 
 ---
 
+## 6.5 反馈通道：`gtrk feedback` —— **告知协议，不是普通确认框**
+
+用户抱怨用得不顺手、或者你自己发现把事情办砸了/绕了远路，都可以上报一条。
+但这条通道有一条**协议要求**，与本 playbook 里其它 `-y` 场景**性质不同**：
+
+> **你替用户提交之前，MUST 先把将要发出的内容原样念给用户，得到同意，再加 `--disclosed` 重跑。**
+
+```
+gtrk feedback "<一句话说清哪里不顺手>" --command <命令名> [--category <类别>] [--quote "<用户原话>"]
+```
+
+- **不带 `--disclosed` 且不在真终端里 ⇒ 命令直接拒发**，零网络往返、非零退出，
+  并把「要念给用户的那段全文」打到 stderr（`--json` 时也在机读面的 `notice` 字段里）。
+  照着念、得到同意，再加 `--disclosed` 重跑即可。
+- ⚠️ **`-y` 不能替代那句声明。** `-y` 在别处的意思是「跳过交互提示」，
+  而这里缺的不是「有没有人按回车」，是「有没有告知过用户」——两件事。
+  加了 `-y` 结果**逐项相同**（有单测钉着）。
+- `--command` **必填**，只写命令名（可带至多两级子命令），**不要带参数**——参数里必然带路径。
+- 类别七档：`complaint`（抱怨吐槽）/ `env_unstable`（环境不稳）/ `confused`（用法困惑）/
+  `blocked`（使用受阻）/ `agent_self_detected`（**你自己搞砸了的自首**）/
+  `feature_request`（功能诉求）/ `other`。缺省 `other`。
+
+**MUST NOT**：
+- 把本机绝对路径、API Key、任何配置项塞进 `--context`（白名单只认那几个中性维度，
+  塞别的会被本地直接拒，不会静默丢弃）；
+- 因为「本地已经脱敏了」就认为内容安全 —— 脱敏的判据在服务端，本地那一遍只为让
+  **你念给用户的内容 = 实际发出的内容**；
+- 用 `-y` 或任何别的旗标去绕那道声明。
+
+---
+
 ## 7. 扩展（给改 CLI 的 agent）
 
 新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 同合云 (Gitruck)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 同合云 (Gitruck)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.