@gitruck/cli 1.2.11 → 1.2.13

package/CHANGELOG.md

@@ -1,15 +1,66 @@
 # 更新日志
 
-## 未发布
+> 📌 **1.2.6 ~ 1.2.11 六个版本段补录于 2026-09-19**：此前这六版没有版本段，改动全堆在「未发布」里。
+> 判据取自 registry 拉回的包体（`npm pack @gitruck/cli@<ver>` 解包，认 `dist/index.js` 里的**运行期中文串**，
+> 外加随包的 `skills/` `contracts/` `README.md`）——不按提交时间倒推，也不查本机 `node_modules`
+> （那是指向开发仓的符号链接，照它判会把没发的算成已发）。
+> npm 记录的各版 `gitHead`：1.2.6 `c2a0f46` · 1.2.7 `03cd95c` · 1.2.8 `a55fb66` · 1.2.9 `e35f311` ·
+> 1.2.10 `966651c` · 1.2.11 `7a58f02`。
+> ⚠️ **`gitHead` 只是旁证**：1.2.7 是从**带未提交改动的工作区**发的——`link-cloud-font-library` 的实现
+> 在 1.2.7 的包体里逐字可见，却要到 2026-09-19 的 `4ee4f74` 才进仓。判版本归属一律以包体为准。
 
-### 改：`gtrk render` 颗粒缓存键补交付配方版本，与客户端重新互通（fix-particle-cache-identity-parity）
+## 1.2.11（2026-09-19）
 
-颗粒 qtrle 缓存的内容寻址键加回 `recipe`（qtrle 交付配方版本，客户端 2026-09-13 起已带、CLI 未跟），键序与客户端逐字节对齐；两端各钉一组写死 hex 的金样，任一端改公式该端先红。此前客户端在工程目录烤好的颗粒 `gtrk render` 一颗都不命中、全部重新云渲计费。升级后对客户端已烤颗粒全命中、零新任务；代价是升级后第一次 `gtrk render` 会把 CLI 自己此前烤的旧键产物 miss 一次（旧文件不删、不回退读取）。身份里的 `duration` 一律取 `.gtrk` 契约投影值原值，两端同源（客户端侧同批调整）。
+### 改：`gtrk transcript --json` 带字级时码，成片字幕时间按语音贴（adjust-transcript-json-word-level）
+
+`--json` 现在按**成片消费面**索取字级识别：产出的 `transcript.json` 每句多一份 `words[]`（`{w, st, ed}`，秒、三位小数、不含标点）。下游 `gtrk subtitle lay` 与客户端一键上字幕据此把每一行的起止贴到真实语音上——此前没有字级时码，一句拆成多行时只能按字数在句子区间里摊分，实测 125 个行边界里偏差中位 148ms、最大 2.6s（一句话快说完了字幕才上来）。升级后同一份语料 235 条字幕起点与首字时码误差恒为 0，末条也不再拖到片尾静音。
+
+**不带 `--json` 的产物形态没变**：只出 Markdown 文字稿时仍是句级（Markdown 本来也不承载字级时码），响应 `word_count` 为 0 是正常的——不过这一版起它走的是另一条引擎腿，见下面 `switch-transcript-to-selfhosted-asr` 那条。`gtrk project init --transcript` 透传 `words[]`，畸形条目跳过并计数。
+
+### 改：一键上字幕不再吞掉完整的短句（adjust-caption-keep-complete-sentence）
+
+最小可读时长过滤（0.8s）以前对「被剪掉一半的残片」和「本来就短的完整句」一视同仁，于是「这不是比喻」「这不是隐喻」这类 0.7 秒的强调句被整条删掉。现在**只有残片**才受这条过滤，完整句无论多短都保留——后一步的空隙桥接本来就能把它延到下一行起点（实测这两句桥接后各 1.08s / 1.24s，与手工修的值一致）。`--json` 报表里 `droppedShort` 的语义随之收窄为「丢掉的残片数」。
+
+### 改：字幕里的感叹号也换成空格，问号保留（adjust-subtitle-punctuation-exclamation-to-space）
+
+落轨字幕的标点清洗扩表：中英**感叹号**（`！` `!`）并入「换成空格」，中英**问号**（`？` `?`）明确保留。逗号句号照旧换空格，小数 `3.5`、千分位 `1,000`、域名 `example.com`、缩写 `U.S.` 照旧不误伤。`--keep-punctuation` 仍可整体关掉清洗。
+
+> 这条以前之所以没人提，是因为语音识别一直把句读剥光了、字幕里根本见不到感叹号；识别侧改成保留句读之后它才第一次出现。
+
+### 改：不带 `--json` 的 `gtrk transcript` 改走自部署识别引擎（switch-transcript-to-selfhosted-asr）
+
+`word_level` 在服务端决定的是**引擎**而不是一个参数：要字级走字级腿（当前是外部厂商 ASR），不要就走
+自部署引擎 + 服务端纠错。CLI 现在按**产物消费面**分流——只出 Markdown 文字稿（不带 `--json`）时传
+`false`，走自部署腿当小工具用；带 `--json` 时传 `true`，因为 `transcript.json` 的 `words[]` 要承载字级
+时码（见上一条）。口径对所有语种一致，**CLI 不按语种挑引擎**：那要在端侧手抄一份「哪些码厂商引擎更好」
+的表，而正本在服务端引擎表里，手抄的那份不会报错，只会在某天悄悄分叉；粤语的质量取舍由服务端语种
+白名单承接。
+
+### 修：旁路记账写不进去，不再把已经挣到的结果一起带走（fix-sidecar-write-failure-kills-command）
+
+生产报错 `base_error#202`（外部客户）：文件已经传完，去写那条约 1 KB 的上传记账时 `EPERM` 一抛，
+**第三步挣来的 `fileId` 跟着陪葬**，整条命令死在第五步；客户重试时缓存里没那条记录，整个文件再传一遍。
+而同一个文件的读侧一直写着「缓存损坏不致命，当空处理」——坏了能忍，写不进去却要命。
+
+现在四处**旁路记账**——上传记账、分片续传断点、BGM 使用历史、MG 例外账本——写失败只打一行 WARN，
+并当场说清后果（如「下次同一个文件会重新上传」「断线后续不上，得从头传」），命令照常把结果交出去。
+
+**交付物类写入不在此列**：`gtrk init` 存 API Key、`gtrk skills` 登记栏目配置都是用户按下的动作，
+写失败照旧抛错，只把 Node 的原文换成人话（多半是文件正被别的程序占着，或者目录不让写）。
+判据是**调用语境**不是写入函数——同一个写函数在一处是交付物、在另一处是旁路记账，是常态。
+
+## 1.2.10（2026-09-18）
 
 ### 加：`gtrk ai-drama lay` 可按工作台项目 id 取包（add-desk-project-resolution）
 
 新增 `--desk-project <id>`（可重复，与 `--package` 混用、按路径去重）：用户手上有的是 AI Drama Desk 的**项目 id**，命令自己解析成导出包目录，走两条确定性路径——服务可达就问 `GET /api/v1/projects/<id>` 取 `exportDir`（**字段缺席即判「尚未导出」**，不据 id 拼路径去试）；服务没起就读 `~/.gitruck/ai-drama-desk.json` 的 `instances[]` 逐条试。零命中会列出已查过哪些数据根（源码部署与打包部署的数据根不同，找不到多半是「在另一个部署里」），多命中报歧义不猜，两条都不通就报错并给出路。**全程不做任何目录遍历**——解析层有一条反向自证用例锁住这点。解析出的包走的仍是既有那条校验与写回路径，清单校验、不完整包整批拒收、路径穿越拒收、幂等与手调保护一律不放宽；`--json` 每个包多标 `via`（按 id / 按路径）与 `resolved_via`（服务 / 落脚点）。
 
+### 改：`gtrk render` 颗粒缓存键补交付配方版本，与客户端重新互通（fix-particle-cache-identity-parity）
+
+颗粒 qtrle 缓存的内容寻址键加回 `recipe`（qtrle 交付配方版本，客户端 2026-09-13 起已带、CLI 未跟），键序与客户端逐字节对齐；两端各钉一组写死 hex 的金样，任一端改公式该端先红。此前客户端在工程目录烤好的颗粒 `gtrk render` 一颗都不命中、全部重新云渲计费。升级后对客户端已烤颗粒全命中、零新任务；代价是升级后第一次 `gtrk render` 会把 CLI 自己此前烤的旧键产物 miss 一次（旧文件不删、不回退读取）。身份里的 `duration` 一律取 `.gtrk` 契约投影值原值，两端同源（客户端侧同批调整）。
+
+## 1.2.9（2026-09-18）
+
 ### 加：推荐目录收一方 MG 排版技法族（add-first-party-technique-catalog-entry）
 
 `gtrk skills recommend` 多一个场景 `technique`：同合云自己的排版技法族（首个技法 doc-reveal：文献页叠放 / 发牌 / 局部强调）。技法不是栏目 MG 生产 skill——`gtrk skills add` 装完登记为 `routing:none` 且 `status: "first-party"`，由 agent 在 MG 步按槽位取用；显式 `--produces` 绑车道会照登记并告警一行。人读输出对一方条目印「一方维护」不印 star；`--json` 每条多 `origin`。`/gtrk-mg` 手册在「无匹配」与「有匹配缺省不用」两处各加一句指路，公约 §三‴ 补一方口径。
@@ -19,6 +70,19 @@
 颗粒 HTML 超过 2,000,000 字符（客户端颗粒运行时的硬上限，超了在客户端永远加载不出来）现在判致命 `4-html-size`：铺轨跳过该 beat、`mg render` 不提交零计费；命中即短路，其余检查项不跑。超过 500,000 字符给非致命 `4-html-size-heavy`（客户端每次 seek 整份快照回传，体积直接决定预览帧率）。
 报错点名最大的一段 data: URI（类型、字符数、解码字节数、落点），给「按实际显示尺寸裁剪缩放后再内嵌」的改法；没有 data: URI 的超限如实归因为标记与脚本本身。契约 `contracts/gsap-emit-v1.md` 铁律 4 增补⑤，`gtrk-mg` 图纸 lint 节同步。
 
+### 修：环境类失败在端侧落成人话，不再炸到顶层当崩溃（三条生产报错归一件）
+
+读不动的 JSON 与写不进去的文件，此前把 Node 的原始异常直接抛到顶层、走崩溃上报。现在：
+
+- **读**：`.gtrk 工程` / `派单清单` / `拆分稿` / `AI 导出清单` 等按名报错，并附一句诊断——
+  文件是空的（产它的那一步没写成）/ 正文里夹着 `U+FEFF`（两份文本被直接拼在了一起）/ 有 NUL 字节
+  （多半被存成了 UTF-16）/ 有解不开的字节（编码不是 UTF-8）/ 就是不合法 JSON，各给各的出路。
+- **写**：目标被别的程序占着时退避重试（5 次、约 750 ms 窗口；**不做无上限重试**——编辑器开着那个
+  文件可以开一整天，无上限只会把「报错」换成「卡死」），仍失败则保留内容完整的 `.tmp` 并告诉你
+  可以直接改名收走；跨卷改不了名、磁盘没空间各给各的出路。写成功后顺手清掉够老的同目标 temp 残骸。
+
+## 1.2.8（2026-09-17）
+
 ### 加：视频译制配音 `video_translate_dub`（link-video-translate-dub-cli）
 
 `gtrk tool video_translate_dub <视频或音频> --language <源语种> --translate-language <目标语种> --speaker <clone 或音色代号>`：
@@ -43,10 +107,100 @@
 `--language` / `--translate-language` / `--speaker` / `--subtitle-type` 的说明改为不绑定单一工具的表述，参数名不变。
 视频类工具输入超时长的报错改为「输入时长超过 N 分钟上限，请先裁剪或分段后再提交」。
 
-### 文档：`gtrk-tools` 图纸写明 `audio_tts_clone` 可选出字幕（link-add-tts-subtitle-output-cli 3.2）
+### 文档：`gtrk-travel-recap` 图纸的写稿语速改读栏目 catalog
 
-输入列补 `--subtitle-format <fmt>`（可选、缺省不出、不额外计费、取值以服务端为准），产物列补另产 `tts-<音色代号>.srt`（服务端降级时不留空文件）；
-新增守卫 `test/skill-tools-tts-subtitle.test.mjs` 按列校验，防止文案被改回。
+随包旅拍图纸不再内嵌语速常量，改读栏目 catalog 的两个键；档案登记 `narrator` 五项齐备时回校样本 §3.5。
+
+## 1.2.7（2026-09-16）
+
+### 加：渲染字体改从同合云统一字体库装（link-cloud-font-library）
+
+`gtrk deps install` 的字体这一步改走**同合云统一字体库**（与客户端同源、同一份服务端投影，
+所以共享目录里同款字体只存一份），不再跟着 ffmpeg 分发清单里那几项走。新增
+`--font-family <family...>`：按 `font_id` 或中英族名点名装、可多个；缺省只装字幕字体
+`sourcehansanscn-bold.otf`。清单里没有 `sha256` 的字体**拒绝安装**（强校验不可降级）。
+
+`gtrk deps status` 多列一行字体库（地址、schema、族数 / 款数、生成时间）。字体清单与 ffmpeg 分发
+manifest 是**两条链路、各拉各的**，取不到只少列这一段，不影响上面的 ffmpeg 信息。
+
+### 修：固定名面包屑覆盖不再静默，`gtrk mad` 跟修产物目录防撞（fix-tool-outdir-collision）
+
+两处：
+
+- **面包屑覆盖**：`task.json` / `result.json` / `result-output.json` 三个**固定名**面包屑按固定名被
+  下游消费，撞名时 MUST NOT 改名——但此前也一声不吭。现在打一条 WARN 点名会被覆盖的是哪几个，
+  并说清代价（上一次的 `task_id` 与产物清单不可回溯，产物文件本身不受影响、撞名会自动改名保留），
+  末了提醒「要并行跑多条，给每条一个独立的 `--out`」。
+- **`gtrk mad` 防撞**：产物目录从 `mkdir(recursive:true)`（已存在即**静默复用**）改成与 `gtrk tool`
+  族共用同一份原子探路实现——同一秒起两条 mad，后者的 `mad.jsx` 会盖掉前者。`--out` 是用户明示的
+  落点，仍不替他改名。顺带把 mad 自己那份逐字等价的时间戳实现收敛掉。
+
+### 改：「AI 再现」全面改叫「AI 情景动画」
+
+随包 `README` / `AGENT.md` / 各 skill 图纸里的叫法统一换掉；车道标识 `AI_DRAMA` 与命令面不变。
+
+### 文档：升级 CLI 不会自动刷新已装的 skill（fix-skill-install-staleness）
+
+`npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，各 Agent 目录下那份 skill 仍是**上次装进去的快照**
+——agent 会照着旧口径干活，**而且不报错**。README 补上这条口径与修法：走 `gtrk upgrade`（升 CLI +
+刷 skill）或单独 `gtrk skills install`；自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」。
+`AGENT.md` 同步补上 agent 侧纪律：见到那条 stderr 提示 MUST 转告用户，MUST NOT 当噪音忽略。
+
+## 1.2.6（2026-09-16）
+
+### 加：MG 槽位视觉职能四档 + 生产侧硬闸 + 排产顺序闸（gate-mg-visual-job）
+
+派单里每个 MG 槽位的 `handoff.visual_job` 转为必填，四档 `statement` / `relation` / `data` / `decor`
+（判据是「这段的意思里有没有第二个东西与它并置」，**与用不用文字无关**）；`relation` 还须填
+`visual_brief`。全片一个关系型视觉都没声明时，顶层须具名 `mg_visual_job_note` 说明为什么通篇只有单一
+陈述（纯字卡包装的口播片是合法形态，本条只要求它是个有意识的选择）。派单阶段**不得引用具体模板 id**
+——判「这段要什么」的那一步不该看见模板库。
+
+两道闸落在生产侧：
+
+- **生产侧硬闸**：`relation` / `data` 槽位交上来一颗文字模板库的颗粒（内嵌 `v:"text-v0"` 的 IR）即拒。
+  被禁的是「从库里捞一个套上」，**不是「用文字」**——用排版画关系的手写颗粒（并置两列 + 破折号那种）
+  正是要保住的东西，本条不拦它。
+- **排产顺序闸**：本片还有 `relation` / `data` 槽位没产出源 HTML 时，`gtrk mg fetch --source text` 的
+  派单模式**拒绝执行**。理由是防锚定：连着看过十几颗现成品之后，「MG 该长什么样」的默认印象已被那批
+  东西定住，这时再自由发挥，发挥出来的多半还是它们的形状——顺序本身就是一道隔离。
+
+两道闸各留一次性例外，**必须同时给理由**、随工程留痕（铺轨侧写 `struct_meta.mg.exceptions`，取块侧写
+`<工程>/split/mg-exceptions.json`）：`--allow-text-for-relation <beatId> --why "<一句话>"` 与
+`--allow-template-first --why "<一句话>"`。它们 MUST NOT 被做成常开配置。
+
+### 加：`gtrk mg compile` 本地编译先校验再编译（fix-local-ir-compile-skips-validation）
+
+本地编译这条路此前**零校验**：`transparent:false`、`canvas:1280x720@60fps` 这类服务端会当场拒的 IR，
+本地一律 `exit 0` 落盘——于是「本地能编出来」不再蕴含「这份 IR 合法」。2026-09-15 实测有三颗带
+`transparent:false` 内嵌 IR 的颗粒，就是从这个口子溜进 `.gtrk` 的。
+
+现在编译前先跑一遍校验器，报错**指名到键**（`layers[2].font.size 须 8–600` 这种）。位置必须在编译之前：
+编译器对某些非法输入会抛它自己的异常（如未定义颜色引用），那句话没有路径、用户拿不到定位。
+
+### 加：`canvas.scrim` 压板层——半透明压板不再冒充实心底（link-text-ir-scrim-opaque）
+
+文字模板 IR 新增 `canvas.scrim`（压暗底轨用的半透明矩形：`fill` 必填且**必须带 alpha**，可选
+`rect` / `radius`），与 `canvas.bg` 互斥——要满幅实心底用 `bg`，要压暗用 `scrim`；写了 `scrim` 的颗粒
+`transparent` 仍须 `true`。
+
+此前压板恰好落在「根下第一个渲染子层」这个取样点上，而 `bgOf` 只认 `transparent`/`none`/`rgba(...,0)`
+三种透明形态，于是 `#000000A6` 被判成非透明——**一块压板被登记成合格实心底**，满屏槽位据此过闸，
+出片时底轨从压板后面透出来。取样时现在跳过压板层，继续往下找真正的全幅子层。
+
+同批补上一处漏接：`gtrk mg lint --dispatch`（用户检查已铺颗粒最自然的那条命令）此前**一个 category
+都不读**——`--category` 在命令面注册着、派单里也写着，满屏闸却只活在 `mg fetch` 那条路上，
+「取块时合规、后来颗粒被换掉」这条最常见的失守路径完全没人看。
+
+### 改：放开画幅硬闸，文字模板按工程画幅现编（link-aspect-agnostic-layout）
+
+`gtrk mg fetch` 与 `gtrk mg compile` 的 `--canvas` 从「只收 1920×1080」改成「须为正整数」：引擎早已按颗粒声明尺寸挂载缩放，原来那条硬闸拦的
+是一个**不存在的失败形态**；文字模板的 IR 住在 1920 参考系、画幅是编译入参，按目标画幅现编即可。
+
+**registry 中性块仍只收 1920×1080**：那批是手写 HTML、几何写死在块里，取块改写不会跟着缩，
+给它别的画幅出来就是错的。lint 相应改成按工程画幅对拍——颗粒声明的画幅与工程不符时点名
+「挂载走的是**非等比** `scale(w/dw, h/dh)`，跨比例会把颗粒拉伸变形（不是加黑边），而两边都不报错」，
+手写颗粒请按工程画幅重做。
 
 ### 加：文字模板候选态可按分类过滤（add-text-template-category 2.2）
 
@@ -60,6 +214,11 @@
 新鲜请求与逐字节重放都回传当前版本、重放不二次计费）。这条成因在当前部署下不可能发生，继续列出只会把排查引向不存在的地方。
 `IDEM_KEY_PINNED_DEPLOYED` 改为 `true`；服务端若回滚到版本钉入键之前，须改回 `false`。
 
+### 文档：`gtrk-tools` 图纸写明 `audio_tts_clone` 可选出字幕（link-add-tts-subtitle-output-cli 3.2）
+
+输入列补 `--subtitle-format <fmt>`（可选、缺省不出、不额外计费、取值以服务端为准），产物列补另产 `tts-<音色代号>.srt`（服务端降级时不留空文件）；
+新增守卫 `test/skill-tools-tts-subtitle.test.mjs` 按列校验，防止文案被改回。
+
 ## 1.2.5（2026-09-14 定版，2026-09-15 发布）
 
 > 下面四条补录于 2026-09-16：**它们随 1.2.5 一起发出去了，但当时漏写了用户面条目**。