@gitruck/cli 1.1.7 → 1.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitruck/cli",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
   "license": "MIT",
   "author": "Gitruck (同合云)",
@@ -50,7 +50,7 @@
     "build": "bun build ./src/index.ts --target=node --minify --outfile dist/index.js",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm test && bun run build",
-    "test": "esbuild src/lib/compliance-notice.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.ts src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/jianying.ts src/lib/clip-brief.ts src/lib/media.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/local-index.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/solid-png.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/ai-drama-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/patch-cmd.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\"",
+    "test": "esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.ts src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/jianying.ts src/lib/clip-brief.ts src/lib/media.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/local-index.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/solid-png.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/ai-drama-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/patch-cmd.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\"",
     "test:linux": "node scripts/test-linux.mjs",
     "openspec:gate": "node openspec/gate.mjs"
   },

package/skills/gtrk-live-slicing/SKILL.md

@@ -39,6 +39,8 @@ description: 直播切片图纸——把一场数小时的直播回放，拆成
 > **②④ MUST 问用户、MUST NOT 代猜。** ②猜错的代价是白跑一轮分屏（几十分钟 + 积分）；
 > ④缺省是**不叠**——用户没要就零 MG 动作，MUST NOT 硬塞。
 > **③ 的取证目的只是「告知」，不是「处置」**——看到贴片不要动手，见定位铁律。
+> ② 与 `/gtrk-long2short`、`/gtrk-tools` 精剪开工的「多人同框」一问同口径：是就开、不确定按否；
+> 分屏单段最长 8 秒、每条最多 3 处。
 
 ## 二、分段规约（本图纸的骨干）
 

package/skills/gtrk-long2short/SKILL.md

@@ -19,6 +19,13 @@ description: 长剪短闭环——把一条长视频（课程/直播/播客/访
 > `gtrk tool video_long2short_pro`（走 `/gtrk-tools`，整片上传、云端渲染、计费约为粗剪两倍）。
 > 判断句：**「剪完还要不要再动？」要动 → 留在这儿；不动 → 转精剪。** 选错一次要白花积分重来。
 
+> **⚠️ 开工再问一句：素材是不是多人同框（对谈 / 访谈 / 多人直播）？** 与 `/gtrk-tools` 精剪同一问、同一措辞，
+> 和上一问**一起问、一次答完**，MUST NOT 代猜。
+> 答「是」⇒ 带 `--split-screen`，**并在同一句里告知**：本地会改传一份压过的 720p 代理（否则只传抽出的音频、
+> 毛片不出本地），处理时间明显变长（实测 0.09× → 0.53× 源时长）；分屏素材落毛片旁 `split_screen/`。
+> 答「否 / 不确定」⇒ 不带（「不确定」按「否」）。分屏是点缀：单段最长 8 秒、每条最多 3 处，落在子轨、
+> 不合心意在客户端隐藏该段即回退原片。
+
 ## 前置：CLI 装没装 + 体检
 
 先跑 `gtrk doctor`：
@@ -32,7 +39,7 @@ description: 长剪短闭环——把一条长视频（课程/直播/播客/访
 gtrk long2short "D:/毛片/课程.mp4" --language zh-CN --json
 ```
 
-对谈/多人同框想要分屏：
+开工问「多人同框」答「是」时（对谈 / 访谈 / 多人直播）：
 
 ```bash
 gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-orientation tb --json

package/skills/gtrk-matrix/SKILL.md

@@ -229,7 +229,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 | **源时间窗过滤** | `--source-window <start,end>` | 秒，`start<end` · 不过滤 | 仅 `--local`：只返回与窗口**有交集**的命中段（段边界不裁剪）；与其他过滤器 AND 叠加；图片候选自动排除；**空窗 = ok 空结果非错误**，扩窗是你的裁定 |
 | 场景切分粒度 | `--scene-threshold <f>` | 浮点 (0,1) · `0.3` | 仅 index：镜头切换快调高、长镜头调低 |
 | 固定机位判稳阈值 | `--stability-threshold <f>` | 浮点 (0,1) · `0.05` | 仅 index：场景内最大帧间变化低于此值判 stable，抽帧收敛为**中点 1 帧**（60s 固定机位从 30 帧省到 1 帧）；summary 分列 stable/unstable 场景数与省帧数；误判 stable 丢检索粒度、误判 unstable 只是不省钱——**宁严勿松**；默认为保守值待标定 |
-| 索引强制重建 | `--rebuild` | 开关 · 关 | 忽略指纹全部重算向量；**理解缓存（describes）不清**。存量索引库（2026-08-19 闪帧修复之前建的）**没有切点全集**：铺轨消不到段内切点、消不掉 2~3 帧异景残片——用户报「成片有闪帧」且素材是高帧率长视频时，先带本开关重建一次索引 |
+| 索引强制重建 | `--rebuild` | 开关 · 关 | 忽略指纹全部重算向量；**理解缓存（describes）不清**。存量索引库（2026-08-19 闪帧修复之前建的）**没有切点全集**：铺轨消不到段内切点、消不掉 2~3 帧异景残片——用户报「成片有闪帧」且素材是高帧率长视频时，先带本开关重建一次索引。⟲ 2026-09-10 起多一条重建理由：**倍帧素材的假切点治法**与**段级运动量信号**都只在重建时落库（见「本地素材检索模式要点」） |
 | 不要图片候选 | `--no-image-broll` | 开关 · 默认参与 | 检索与铺轨完全排除图片（零图片上云）；pinned 也不豁免这条 |
 | 跳过计费确认 | `--yes` | 开关 · 关 | 图片运镜 / describe >20 张两处护栏通用 |
 
@@ -314,6 +314,14 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 - 两步走：`gtrk matrix index --dirs <a,b> --json` 建索引（增量零重算）→ `gtrk matrix --local --dirs <a,b> --project <目录> --json` 检索铺轨。
 - **score 地板观察（重要）**：本地域 score 量纲与云端不同，完美命中可低至 0.246——默认 `0.2` 是松地板，排名靠查询内相对顺序。**别按云端直觉调高**（0.3 可能把正确命中砍光）。
 - 索引跨机不可移植（键=绝对路径）：换机重跑 `matrix index` 即可（分钟级）；素材改名/移动身份不变（内容哈希）。
+- **段带运动量，据此换段（`add-material-motion-signal`）**：重建过索引的素材，检索结果的每个 `segments[]` 会多带一个可选 `motion`（去重后帧间跳变分位 `p50`/`p90` + 样本数 + 有效帧率）。它答的是**「这段抖不抖」**，与 `score`（像不像）正交：`p50` 超 `0.05` 视为高运动，铺轨排序时降权 0.02 分（**只降权、不排除**——候选稀疏时宁可用高运动段也不留空，留空的观感代价更大）。用户报「这段画面晃得看不清 / 想换一段」时，`motion.p50` 就是挑替补的依据：同 beat 里挑 `p50` 更低的段。
+  - ⚠️ **缺席 = 不可判，不是「平稳」**。存量索引库（本能力上线前建的）没有这份信号，段上整键无 `motion`；此时高运动降权对该素材**不生效**，不是「它很稳」。要拿到信号得 `gtrk matrix index --dirs <夹> --rebuild` 重建一次。
+  - ⚠️ **样本不足也报缺席**：长静止镜头去重后可能只剩个位数帧，分位不可信，`p50`/`p90` 如实为 `null`（`samples` 仍照报）。同样 MUST NOT 读成「平稳」。
+- **倍帧素材（30fps 内容装进 60fps 容器）**：这类素材每隔一帧就是上一帧的复制。索引会认出来并落**有效帧率**（`motion.effective_fps`，如容器 60 而实际 30）。判据取近零帧的**连续长度**而非占比——倍帧运动段呈单帧交替（连零 ≤2），静止镜头是长串连零（实测 15–118 帧），两者近零帧都多、只有连零长度分得开。
+  - 见到 `effective_fps` 明显低于容器帧率时，**如实告诉用户这条素材是倍帧的**（画面实际流畅度只有标称的一半，不是铺轨铺坏了）。
+  - **假切点已在索引侧治掉**（2026-09-10）：倍帧会让快摇镜头的帧间分被顶过切点阈值，从而在**单一镜头内**吐出一串假切点（实测某段 0.43s 内记了 11 个）。现在切点判定在**去重后的帧序列**上进行——持续快摇在去重序列上是一条连续高分串、整串不算刀，真实一刀仍是孤立尖峰、照留。非倍帧素材的判定一字未动。
+  - ⚠️ **存量索引里的假切点不会自己消失**：这条修法只在**重建索引**时生效。素材被判 `doubled` 且某段 `cuts` 密得离谱（零点几秒里十几刀）时，多半是本能力上线前建的库 ⇒ `gtrk matrix index --dirs <夹> --rebuild` 重建一次；重建前别把那些切点当真。
+  - ⚠️ **一个已知取舍**：倍帧区里**紧挨着**的两刀（去重后相邻）会被判成持续运动而漏掉。它们在信号上与「快摇的头两帧」不可分——宁可漏这一对，也好过把十几个假切点放进去。
 - 含本地 B-roll 的工程云渲会被提交口直接拒绝（`local_broll_cloud_render_rejected`）——走客户端本地出片或 `gtrk render`。
 - embed 端点连不通（`embed_endpoint_unreachable`）：查 `~/.gitruck` config `embedUrl` / env `GITRUCK_EMBED_URL`；describe 端点同理（`describe_endpoint_unreachable`，`describeUrl` / `GITRUCK_DESCRIBE_URL`）；CLI 绝不回落第三方端点。会话失效（6033）重跑即自动重开续跑。
 

package/skills/gtrk-mg/SKILL.md

@@ -170,6 +170,20 @@ gtrk mg --project "<split产物目录>" --json
 
 ★ **若你是走前置硬门 2 的「明示跳过 AI」进来的**：收口前 MUST 把那份「**AI 回铺后待复查构图**」清单复述给用户（哪几颗颗粒、对应哪几个 AI beat 区间），并说明「AI 片段回铺后这几颗可能要重产」。**MUST NOT 静默收口。**
 
+
+### 出片后 QC 报了缺陷：怎么落回 plan 重铺（闭环，别原地调参）
+
+`gtrk render` 出片后跑 `gtrk qc <成片> --gtrk <工程> --json`。它报的缺陷**带工程坐标**（`beat` / 槽位序号 / `clip_id` / 源窗），不是一串光秃秃的成片时码——所以「换哪一段」是可答的，闭环走法：
+
+1. **读缺陷的坐标**，定位到是哪个 beat 的第几槽、用的哪条 `clip_id` 的哪个源窗。
+2. **读它给的排序备选**：同 beat 里未被采用的候选段，按「稳」排序（运动量升序 → 段内切点数升序 → score 降序）。索引无运动信号时退回单维排序，回执会标注**口径受限**——那时别把第一名当定论。
+3. **改 plan 换段**（`split/broll-plan.json`），把该槽位换成备选里的第一名。⚠️ 改的时候把候选条目**原样搬**，别自己重写 `segments`——`cuts` / `motion` 就住在里面，重写即丢（详见 `/gtrk-matrix` 的 plan 编辑口径）。
+4. **`gtrk matrix lay --project <目录> --plan <path>`** 消费改过的 plan 重铺 B-roll ⇒ 本 skill 的 MG 颗粒**按增量重铺受影响的那几颗**（`--only <beat>`）⇒ 重渲 ⇒ 再 QC 复核那条缺陷是否消失。
+
+🔴 **这是「换素材」而不是「调参数」**：QC 报的多数画面级缺陷（晃、糊、闪）根子在选中的那一段本身，调 `--score-floor` / 阈值只会连带影响全片其它槽位。先换段，换不动再谈调参。
+
+⚠️ **QC 是只读诊断**：常规扫描零写库。只有显式带回流开关时才会把确认的切点补录进本地索引（治检测阈值漏网），无法唯一映射的会跳过并报数——**别把「跳过 N 条」读成失败**。
+
 ### 逃生门：两种信号都要认（范围 + 节奏）
 
 上面的「别收工、顺势收口」是**默认**，但**用户表达了范围保留或节奏保留时 SHALL 停在铺完这一步、

package/skills/gtrk-tools/SKILL.md

@@ -68,7 +68,16 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 
 ### ⚠️ 长剪短有两条线，别选错（名字很像，产物完全不同）
 
-用户说「把这条长视频剪成短片」时，**先问清他要工程还是要成片**——选错一次的代价是白花积分重来。
+用户说「把这条长视频剪成短片」时，**开工先问两件事、一张表一次问完**（MUST NOT 碎问、MUST NOT 代猜）：
+
+| # | 问 | 决定什么 |
+|---|---|---|
+| ① | 要**可编辑工程**还是**直接成片**？ | 走粗剪 `gtrk long2short` 还是本 skill 的精剪——选错一次的代价是白花积分重来 |
+| ② | 素材是不是**多人同框**（对谈 / 访谈 / 多人直播）？ | 答「是」⇒ 命令带 `--split-screen`、不再追问；答「否 / 不确定」⇒ 不带。**「不确定」按「否」**：开错是分屏烧进成片不可回退 + 一段检测等待，不开只是少个点缀、看片后补一句重跑即可 |
+
+> 分屏是**点缀不是主体**：只挑多人同框段做，单段最长 8 秒、每条最多 3 处，不会整条变分屏。
+> 单人素材开了也不会出现分屏画面，但仍会多付一段说话人检测的等待——**不是零副作用**，别这么跟用户说。
+> 跑完 `clips.md` 头部会回显「分屏：开/关」（只是请求态，报告不知道实际做了几处）。
 
 | | `gtrk long2short`（粗剪，**独立命令、不在本 skill**） | `gtrk tool video_long2short_pro`（精剪，本 skill） |
 |---|---|---|