@gitruck/cli 1.0.8 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# 更新日志
+
+## 1.1.0（2026-09-02）
+
+### ⚠️ 升级须知：1.0.8 铺过的工程不会自愈
+
+1.0.8 有一处**槽位接缝**缺陷：铺出的主轨会带 −1 毫秒的同轨重叠，
+`gtrk render` 检出后**硬拒**，成片渲不出来。
+
+- **本版修掉了产生它的原因**，但**修不了已经铺坏的工程**。
+- 手上有 1.0.8 铺的工程 ⇒ 重跑一次 `gtrk matrix lay --project <目录>`，
+  或用 `gtrk patch trim` 逐颗修端点。
+- 升级后打开旧工程仍渲不出，**不是新版没修好**，是那份工程还带着旧缺陷。
+
+另外：服务端的新编排逻辑 2026-09-01 已上线。**1.0.8 与它不配套**——
+本地复算自校验会判定不一致、弃用服务端产物改用本地编排，而那次调用**已经计费**。
+也就是说停在 1.0.8 的每一次云端编排都在白花钱。请尽快升级。
+
+### 快速模式不再留黑片
+
+`--gap-fill fast` 的填充顺序从三级扩到五级：
+
+本 beat 候选 → 相邻颗粒延长 → **跨 beat 借候选** → **次地板补真画面** → 仍不够才黑片。
+
+- **跨 beat 借**：某几句自己的候选被别的段先占光时，从全片没人用过的素材里取料。
+  真机 `proj2-B` 的 B18 曾整段 8.952 秒落黑，而全片供给/需求是 4.10× ——
+  不缺料，缺的是分配。借来的画面与那几句稿子相关性会弱一些，日志里**指名报出**。
+- **次地板补真画面**：短于最小镜头长（1.2s）的残洞也填真画面。
+  这些是快切，同样指名报出。真机三条片的黑片从 8 处降到 **0 处**。
+- **逐步模式（`--gap-fill solid`）刻意保留黑片**——黑的地方就是没匹配上的地方，
+  精修时一眼看得见。两档的差别现在不只是「停几次」，是**产物形态不同**。
+
+### 新增：`gtrk audio tighten`
+
+收紧配音的**句间**停顿，纯本地零计费。
+
+```bash
+gtrk audio tighten --project <工程目录> --dry-run   # 先看会压几处
+gtrk audio tighten --project <工程目录>             # 落盘
+```
+
+- 真机实测：一条 203 秒的解说里 54 秒是句间静音（26.6%），收到 0.2 秒后全片缩到 171 秒。
+- **只压跨句界的停顿**，句内换气与原声引用段一律不动。
+- 产物是**原件多 clip 铺轨**，不烤新音频文件 —— 每处停顿都是可拖的刀口，随时能退回原样。
+- ⚠️ 它会改变 beat 窗口，**跑完必须重铺**（命令会提醒）。建议在铺画面**之前**跑。
+
+### 新增：`--fragment-interval`（TTS 句间停顿）
+
+```bash
+gtrk tool audio_tts_clone --text-file 稿.txt --speaker <音色> --fragment-interval 0.2
+```
+
+**仅自训音色生效**；云引擎音色传了会**明确报错**，不会静默忽略。
+不传时产物与本版之前逐字节一致。云引擎音色请改用上面的 `gtrk audio tighten`。
+
+### 其它
+
+- 幂等回放时不再误报「已执行并计费」——服务端命中缓存回放时本就不二次扣费，
+  旧版会无条件断言已计费，把用户引向一笔不存在的账。
+- 随包文档订正：`audio_tts_clone` 的文本上限是 **5000 字**（旧文写 2000）；
+  计量单位与单价一律以 `gtrk tool list` 实时显示为准，文档不再写死。
+
+### 已知问题
+
+- 极少数情况下主轨会留下 **1 毫秒**级的黑片或裸缝（30fps 下 0.03 帧，渲染不可见）。
+  已立案追踪，不影响出片。

package/README.en.md

@@ -197,6 +197,13 @@ CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再
 
 ## Upgrading
 
+> **Read this first if you are coming from 1.0.x**: projects laid by 1.0.8 and earlier carry a slot-seam
+> defect (a −1 ms same-track overlap on the main track, which `gtrk render` hard-rejects). **This release
+> fixes the cause but cannot repair projects that were already laid** — re-run
+> `gtrk matrix lay --project <dir>` on any existing project. If an old project still fails to render after
+> upgrading, that is the old defect baked into that project, not a regression in this release.
+> See the [CHANGELOG](./CHANGELOG.md).
+
 **CLI + skills** (config preserved as-is):
 
 ```bash
@@ -470,8 +477,8 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 **Local-footage mode (`matrix index` / `--local`)**: footage does not have to live in the cloud library — retrieve and lay tracks straight from your local footage folders (video and images mixed):
 
 ```bash
-gtrk matrix index --dirs <folder1,folder2>                     # ① build a slice-free index: content-fingerprint incremental, resumable; renames/moves are not recomputed
-gtrk matrix --local --dirs <folder1,folder2> --project <dir>   # ② local retrieval + track laying (--lay 0 = plan only, no laying)
+gtrk matrix index --dirs <folder-or-file,...>                  # ① build a slice-free index: content-fingerprint incremental, resumable; renames/moves are not recomputed
+gtrk matrix --local --dirs <folder-or-file,...> --project <dir>  # ② local retrieval + track laying (--lay 0 = plan only; pass a single media file to narrow the search scope to it)
 gtrk matrix lay --project <dir> [--plan <path>]                # ③ consume the (edited) plan and lay tracks, zero retrieval cost
 ```
 

package/README.md

@@ -195,6 +195,11 @@ CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再
 
 ## 升级
 
+> **从 1.0.x 升上来的先看这一条**：1.0.8 及更早版本铺出的工程带一处槽位接缝缺陷
+> （主轨 −1 毫秒同轨重叠，`gtrk render` 会硬拒）。**本版修掉了产生它的原因，但修不了已经铺坏的工程**——
+> 手上有旧工程就重跑一次 `gtrk matrix lay --project <目录>`。升级后旧工程仍渲不出，
+> 不是新版没修好，是那份工程还带着旧缺陷。详见 [CHANGELOG](./CHANGELOG.md)。
+
 **CLI + skill**（配置原样保留）：
 
 ```bash
@@ -488,8 +493,8 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 **本地素材模式（`matrix index` / `--local`）**：素材不必入云端素材库，用你本地的素材文件夹（视频+图片混合）直接检索铺轨：
 
 ```bash
-gtrk matrix index --dirs <素材夹1,素材夹2>                     # ① 免切片建索引：内容指纹增量、断点续传，素材改名/移动不重算
-gtrk matrix --local --dirs <素材夹1,素材夹2> --project <目录>   # ② 本地检索铺轨（--lay 0 = 只出 plan 不铺轨）
+gtrk matrix index --dirs <素材夹或素材文件,...>                # ① 免切片建索引：内容指纹增量、断点续传，素材改名/移动不重算
+gtrk matrix --local --dirs <素材夹或素材文件,...> --project <目录>  # ② 本地检索铺轨（--lay 0 = 只出 plan 不铺轨；传单个素材文件即把检索域收窄到它）
 gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（可编辑后的）plan 铺轨，零检索开销
 ```