@gitruck/cli 1.1.9 → 1.2.0

package/package.json

@@ -1,68 +1,69 @@
-{
-  "name": "@gitruck/cli",
-  "version": "1.1.9",
-  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
-  "license": "MIT",
-  "author": "Gitruck (同合云)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Gitruck/cli.git"
-  },
-  "homepage": "https://github.com/Gitruck/cli#readme",
-  "bugs": {
-    "url": "https://github.com/Gitruck/cli/issues"
-  },
-  "type": "module",
-  "bin": {
-    "gtrk": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "assets",
-    "skills",
-    "contracts",
-    "AGENT.md",
-    "README.md",
-    "README.en.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "engines": {
-    "node": ">=20.6"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "gitruck",
-    "同合云",
-    "video",
-    "oral-cut",
-    "口播剪辑",
-    "cli",
-    "jianying",
-    "剪映",
-    "agent"
-  ],
-  "scripts": {
-    "gtrk": "bun run src/index.ts",
-    "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/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"
-  },
-  "devDependencies": {
-    "@xmldom/xmldom": "^0.9.6",
-    "bun-types": "^1.1.0",
-    "commander": "^12.1.0",
-    "esbuild": "^0.28.1",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "hash-wasm": "^4.12.0",
-    "jszip": "^3.10.1"
-  }
-}
+{
+  "name": "@gitruck/cli",
+  "version": "1.2.0",
+  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
+  "license": "MIT",
+  "author": "Gitruck (同合云)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gitruck/cli.git"
+  },
+  "homepage": "https://github.com/Gitruck/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Gitruck/cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "gtrk": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "skills",
+    "contracts",
+    "AGENT.md",
+    "README.md",
+    "README.en.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "gitruck",
+    "同合云",
+    "video",
+    "oral-cut",
+    "口播剪辑",
+    "cli",
+    "jianying",
+    "剪映",
+    "agent"
+  ],
+  "scripts": {
+    "gtrk": "bun run src/index.ts",
+    "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/config.ts src/lib/crash-report.ts src/lib/enum-catalog.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/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.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/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.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 src/lib/pip-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",
+    "mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs"
+  },
+  "devDependencies": {
+    "@xmldom/xmldom": "^0.9.6",
+    "bun-types": "^1.1.0",
+    "commander": "^12.1.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "hash-wasm": "^4.12.0",
+    "jszip": "^3.10.1"
+  }
+}

package/skills/gtrk-ai-drama/SKILL.md

@@ -208,7 +208,7 @@ face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how
 > **中性 Style Lock**：影视级自然主义画面，真实可信的光源（窗光 / 实用光 / 自然天光，不炫技），克制稳定的镜头语言（固定或缓慢推拉摇，无手持抖动 / 无广告级动态运镜 / 无无人机炫技），近单色到低饱和的克制调色（不追 HDR、不追霓虹），胶片颗粒质感。忌塑料 3D 渲染、忌动漫二次元、忌过度戏剧化打光。
 > **EN**: Cinematic naturalism, believable practical light sources (window / practical / natural daylight, no showing off), restrained stable camera language (locked or slow dolly/pan/tilt, no handheld shake, no ad-grade dynamic moves, no drone stunts), near-monochrome to low-saturation restrained grade (no HDR, no neon), visible film grain. Avoid plastic 3D render, anime, and over-dramatic lighting.
 
-中性默认下**不设单点强调色 / 不指定影视导演锚点**（那些是栏目资产）。用完顺带提醒用户：**想要这条栏目有自己的 AI 再现视觉 DNA，去 `/gtrk-style-maker` 沉淀一套 AI_DRAMA 风格资产并登记进 `style.skills`**，之后每次生成都会自动注入。
+中性默认下**不设单点强调色 / 不指定影视导演锚点**（那些是栏目资产）。用完顺带提醒用户：**想要这条栏目有自己的 AI 再现视觉 DNA，去 `/gtrk-style-maker` 沉淀一套 AI_DRAMA 风格资产并登记进 `style.skills`**，之后每次生成都会自动注入。分镜稿与提示词层也可查推荐目录（公约 §三‴）：`gtrk skills recommend --scene ai-drama`，装完用 `gtrk skills add <owner/repo>` 登记；本 skill 正文不点名任何仓。
 
 **禁忌行**（写进 ①）分两层：
 - **通用 AI slop 兜底（本 skill 自带，任何栏目都写）**：glossy 3D render / plastic skin、HDR look / oversaturated、generic AI anime / saccharine、deformed face / extra fingers / mutated limbs、text overlay / captions / 字幕（字幕剪辑阶段另做）、heavy lens flare / chromatic aberration、cartoon / low-res / unfinished。

package/skills/gtrk-food-recap/SKILL.md

@@ -19,7 +19,7 @@ description: 美食解说垂类图纸（解说链示例）——把探店/密着
 | **探店 · 密着** | 一条纪实长片（二创；带字幕文件的直接当台词锚，无则转写）或自拍探店素材夹 | 软窗档缺省：进店→点单→出品→吃→人的故事，流程线单调、允许蒙太奇跳 |
 | **做饭流程** | 一条做饭记录或素材夹 | 软窗档且**步骤线忠实**：工序 MUST NOT 乱序重排（先炸后腌是事故） |
 
-稿源与声音基座随正本开工问询（AI 代写/自备稿；TTS/自己念）。**MUST NOT 执行任何网络下载**；二创长片是第三方作品——版权与平台二创规则责任归用户，开工先说。
+稿源与声音基座随正本开工问询（AI 代写/自备稿；TTS/自己念）。⟲ **推荐面（公约 §三‴）**：问答收口时多问一句「要不要看看第三方 skill？」，不列名；题材命中场景触发词才多 1–2 句定向推（`gtrk skills recommend --scene <id> --json` 取 tier 最高者，各给一句为什么），用户追问才展开完整块；轻提加定向合计不超三句、同会话同场景只推一次、答「不要」零动作。**MUST NOT 执行任何网络下载**；二创长片是第三方作品——版权与平台二创规则责任归用户，开工先说。
 
 ## 二、美食要素层（写稿规约，叠在通用框架层之上）
 

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

@@ -42,6 +42,8 @@ description: 直播切片图纸——把一场数小时的直播回放，拆成
 > ② 与 `/gtrk-long2short`、`/gtrk-tools` 精剪开工的「多人同框」一问同口径：是就开、不确定按否；
 > 分屏单段最长 8 秒、每条最多 3 处。
 
+> ⟲ **推荐面（公约 §三‴）**：问答收口时多问一句「要不要看看第三方 skill？」，不列名；题材命中场景触发词才多 1–2 句定向推（`gtrk skills recommend --scene <id> --json` 取 tier 最高者，各给一句为什么），用户追问才展开完整块；轻提加定向合计不超三句、同会话同场景只推一次、答「不要」零动作。
+
 ## 二、分段规约（本图纸的骨干）
 
 ### 两道闸（都是实测，不是推算）

package/skills/gtrk-mg/SKILL.md

@@ -13,7 +13,7 @@ description: MG 动态图颗粒铺轨器——成片 SOP 第 ⑤ 步（**最后
 
 成片是**有序 SOP + 用户检查点**，不是并行一次铺完。全序：
 
-> ① `/gtrk-oralcut`（剪口播）→ ② `/gtrk-splitter`（拆分派单出 `dispatch.json`）→ **③ B-roll 底轨全铺齐**（`/gtrk-matrix` 铺影视/本地素材 + `/gtrk-ai-drama` 产稿→外部出片→用户手动回铺，**两条腿同一阶段**）→ **④ 全局抽帧检查画面构图（用户确认）** → **⑤ 本 skill：MG（含 ov）最后叠上** → `gtrk subtitle lay` 上字幕（快速成片模式必做）→ `gtrk render` 收口
+> ① `/gtrk-oralcut`（剪口播）→ ② `/gtrk-splitter`（拆分派单出 `dispatch.json`）→ **③ B-roll 底轨全铺齐**（`/gtrk-matrix` 铺影视/本地素材 + `/gtrk-ai-drama` 产稿→外部出片→用户手动回铺，**两条腿同一阶段**）→ **④ 全局抽帧检查画面构图（用户确认）** → **⑤ 本 skill：MG（含 ov）最后叠上** → `gtrk subtitle lay` 上字幕（快速成片模式必做）→ `gtrk render` 收口（**会对未命中缓存的颗粒云渲、有计费**，见末节）
 
 **你是第 ⑤ 步、也是最后一层。** MG 颗粒是**唯一的叠加层**——底下那整层底轨必须先定死（**三源全落齐**），否则你的排版避让是对着一个不完整的画面做的。
 
@@ -30,7 +30,7 @@ description: MG 动态图颗粒铺轨器——成片 SOP 第 ⑤ 步（**最后
    - （为空 = 本片没 AI 车道，此门自动通过。）
 3. ★ **④ 全局抽帧检查已过、用户已确认构图**：对**三源合并后的最终底轨**抽帧看主体位置 / 安全区 / 画面朝向 / 明暗，用户确认无误。**这与 ③ 那次「挑选 B-roll」的确认是两次不同的确认**，别拿前一次顶替。没做 → 先做 ④ 再回来。
 4. **有 split 产物**：需要一个跑过 `gtrk split` 的产物目录（含 `split/dispatch.json` 与工程 `.gtrk`）。没有 → 先回 ② `/gtrk-splitter`。
-5. **`dispatch.mg` 非空**：为空 = 本片没有 MG 车道 → **别硬造**，直接 `gtrk render` 收口（见末节）。
+5. **`dispatch.mg` 非空**：为空 = 本片没有 MG 车道 → **别硬造**，直接 `gtrk render` 收口（见末节；无颗粒 = 零计费）。
 6. **CLI 在**：`gtrk` 找不到 → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js）。
 
 ## 业务分离：谁产颗粒（栏目），谁铺轨（本 skill）
@@ -40,7 +40,26 @@ description: MG 动态图颗粒铺轨器——成片 SOP 第 ⑤ 步（**最后
 **车道 → 栏目生产 skill 的解析（照此，别猜）**：读**有效栏目配置**的 `style.skills[]`（配置文件 `~/.gitruck/columns/<id>.json`；栏目 id 由 `--column <id>` 或 config `defaultColumn` 选取；零配置 = L0 内置默认栏目，**不携带 style 清单** → 必然走下方「无匹配」分支）。在 `style.skills[]` 里取 **`produces` 归一后（旧 `RRV_MG` → `MG`）等于 `MG`** 的条目 → 触发它 `ref` 指向的 skill 产颗粒。
 - 命中多条 → 按栏目约定取其一（一般栏目只登记一个 MG 生产 skill）。
 - 条目带 `routing:"none"`（管线外产物，如封面）→ 跳过，不当 MG 生产 skill。
-- **无匹配** = 本栏目没有 MG 生产 skill → 别硬铺；告诉用户「本栏目还没有 MG 生产 skill，先用 `/gtrk-style-maker` 建一个，或换个已配置的栏目（`--column`）」。
+- **无匹配** = 本栏目没有 MG 生产 skill → 别硬铺，给用户**三选一**（都不替他选）：
+  1. **建栏目**：`/gtrk-style-maker` 沉淀自己的 MG 生产 skill（一次性，长期资产）；
+  2. **换栏目**：`--column <id>` 指向已配置的栏目；
+  3. **用中性块**：Hyperframes registry 的中性颗粒骨架（`gtrk mg fetch`，见下节「中性块工作流」）——没建栏目也能当场出 MG，但**骨架不是成品**，内容与审美 MUST 改写。
+  另可查推荐目录（公约 §三‴）：`gtrk skills recommend --scene mg-explainer` 列第三方 MG 生产 skill，装完 `gtrk skills add <owner/repo> --produces MG` 登记即被本节解析到——本 skill 正文不点名任何仓、不点名任何块。
+- **有匹配时中性块缺省不用**：只当栏目 skill 明显不擅长某类（如数据图表 / 界面拟物）时可**提议**「这一槽用中性块」，用户点头才用。
+
+## 中性块工作流（registry 骨架 → 改内容审美 → lint → 铺）
+
+> 快照随包（钉 commit，候选态离线可用）；取块走三源（我方镜像优先，大陆可达）并校 sha256；改写八条是机械活（template 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉 / GSAP 源 / 字体 / 时长贴坑位 / 信箱缩放），**内容与审美不在机械活里**。
+
+逐槽位：
+
+1. **候选**：`gtrk mg fetch "<按 handoff.theme 与 beat 语义组的检索词>" --top 3 --json`（中文词可用：数据 / 图表 / 标题 / 字幕 / 转场 / 通知 / 代码 / 地图 / 手写 / 卡片 / 片头 …）。把 2–3 件候选连**海报链接**给用户选（**候选选择是检查点**，形状同 matrix 的 B-roll 候选）；快速成片模式取首选、铺完在抽帧检查里一并给用户看。`[review]` 件可选但 MUST 真渲验收（多为 canvas / 铁律 8 高危形态）；`[excluded]` 不在可取范围，命令会拒。
+2. **取块改写**：`gtrk mg fetch --pick <块名> --slot <beatId> --project <目录> --json`——从派单取 composition_id / 坑位包络 / category，产物直接落 `<产物目录>/mg/<composition_id>.html`。返回里的 `editable`（文案 / 数值数组 / 色值）就是你下一步要改的地方。
+3. **改内容与审美（你的活，MUST 做）**：按 beat 语义改文案与数据；色板与字体——有栏目 skill 按栏目的，没有按公约 §三「内容驱动的临场泛化」全片自洽一套；**MUST NOT 把块的示例文案 / 示例数据 / 默认色板原样铺进成片**。字体缺省已换成运行时镜像可证的 CJK 字体，要换用 `--font`。
+4. **lint → 铺**：`gtrk mg lint` 过致命项 → `gtrk mg --project <目录>`（与栏目产颗粒同门槛）。
+5. **竖屏工程**：契约当前只收 1920×1080 颗粒（lint 铁律 1），中性块不适用；提示用户走栏目 skill，MUST NOT 拉伸。
+
+独立模式（脱离派单补一颗）：`gtrk mg fetch --pick <块名> --as <composition_id> --duration <坑位秒> [--category overlay|fullscreen] [--out <目录>]`，随后同 `gtrk mg render` 的独立颗粒路。
 
 > **生产 skill 是栏目的纯净资产**：它只懂本栏目的视觉语法、只产 html-particle 颗粒，**不知道 gtrk 命令、不知道产物落哪**。由本 skill 驱动它、并**由本 skill 负责让它以 `gtrk mg` 要读的路径为写入路径**：颗粒 SHALL **直接写到** `<产物目录>/mg/<composition_id>.html`，MUST NOT 先写 agent 自有目录再拷入（中转本身即违规，见上「产物落点纪律」第 5 条）。举例（仅示意解析机制，非硬编）：`real-roam-guide` 栏目配置里 `style.skills` 有一条 `{produces:"MG", ref:"…/real-roam-viz"}` → 驱动它产颗粒；换个栏目、换个 ref，产颗粒的就是另一个生产 skill。**本 skill 正文里不绑死任何栏目的生产 skill。**
 
@@ -168,6 +187,19 @@ gtrk mg --project "<split产物目录>" --json
 
 `dispatch.mg` 全铺满、`gtrk mg status` 全绿后**别收工**——你已是最后一层，顺势收口。快速成片模式先 `gtrk subtitle lay --project <目录>` 把字幕上好（样式取用户拍板值，没选用 default）再 `gtrk render` 出片。一句话交代即推进：「MG 颗粒已叠铺完，我接着上字幕出片」。
 
+### ⚠️ `render` 收口会花钱（2026-09-09 起，add-render-overlay-compositing）
+
+`gtrk render` 现在**会把 MG 颗粒真的渲进成片**——做法是把每颗颗粒送去同合云烤成透明 MOV，再本地叠。于是这条命令**不再是零计费**：
+
+- **计量 = 唯一颗粒数 × 未命中缓存数**（按分钟）。同一颗粒在轨上出现 N 次只烤一次。
+- **第二次渲染全命中缓存 ⇒ 零计费**；用户先在客户端导出过剪映的工程，CLI 首渲即全命中（两端共用同一份工程目录缓存）。
+- 未命中时 CLI **会先出预估并要确认**。`--yes` 跳过确认；`--json` 模式下**必须**显式 `--yes`，否则硬拒。
+- 不想花钱：`--no-particles` 出无颗粒版（B-roll 等 overlay 轨照常合成，那部分零计费）。
+
+**MUST 在推进前把这件事说给用户**（一句话即可：「渲这条会对 N 颗未命中缓存的颗粒云渲、约 X 分钟计费；不想花钱可以先出无颗粒版」），**MUST NOT** 一声不吭替他确认。
+
+另一条路仍在：**客户端出片**（opencut 打开工程 → 云渲）同样能出带颗粒的成片，且与 CLI 共用缓存。两条路选哪条由用户定。
+
 ★ **若你是走前置硬门 2 的「明示跳过 AI」进来的**：收口前 MUST 把那份「**AI 回铺后待复查构图**」清单复述给用户（哪几颗颗粒、对应哪几个 AI beat 区间），并说明「AI 片段回铺后这几颗可能要重产」。**MUST NOT 静默收口。**
 
 

package/skills/gtrk-narration/SKILL.md

@@ -37,6 +37,7 @@ description: 通用解说视频创作图纸（解说链正本）——把「一
 | ⑦ | **源片语种 / 方言** | **问用户**：听一段 / 看片内有无内嵌字幕 / 看素材出处 | `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）；素材通篇无对白答「无对白 / 不转写」即闭合，MUST NOT 因缺这个答案阻塞开工 |
 
 > ②③④⑤⑦ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。
+> ⟲ **推荐面（公约 §三‴）**：问答收口时多问一句「要不要看看第三方 skill？」，不列名；题材命中场景触发词才多 1–2 句定向推（`gtrk skills recommend --scene <id> --json` 取 tier 最高者，各给一句为什么），用户追问才展开完整块；轻提加定向合计不超三句、同会话同场景只推一次、答「不要」零动作。
 >
 > ⟲ **2026-09-02 六问补为七问（新增 ⑦ 语种）**：260902 真机一条**粤语对白**的片子按缺省 `zh-CN`
 > 静默转写跑完，整条链上无一处问过语种。⑦ MUST 早于 ① 的转写发起：转写是计费动作且在检查点①**之前**，

package/skills/gtrk-talking-head/SKILL.md

@@ -31,6 +31,10 @@ description: 通用口播视频创作图纸（口播链）——把一条或一
 | ④ | 毛片几何 | ffprobe | 画幅随片（**非拍板项**，与旅拍不同——那边是无中生有须拍板画幅）；非标帧率会被吸附到标准值，属预期 |
 | ⑤ | **B-roll 素材来源**（主理人 2026-08-27 真机挑刺拍板） | **问用户，MUST NOT 硬塞**：有没有本地素材文件夹（要路径）？要不要用云端素材填充？ | §五 matrix 走法三选一：本地（`--local --dirs`）/ 云端 / **都不要 = 不铺 B-roll**（纯 A_ROLL + MG 字卡也是完整成片形态） |
 
+| ⑥ | **有没有与人像同步录制的屏录 / 第二机位？** | **问用户，MUST NOT 代猜**（看目录里有没有同时段的屏录 / 另一机位文件只是提示，不是答案）。有则追问三样：画中画形状（圆 / 圆角方 / 爱心 / 菱形 / 星形，缺省圆）、位置（缺省右下）、大小（缺省约 28% 画幅高） | 走不走 §二′ 双源画中画（`gtrk pip lay`）；屏录题材 **⑤ 默认答「不铺 B-roll」**（屏幕本身即画面） |
+
+> ⟲ **推荐面（公约 §三‴）**：问答收口时多问一句「要不要看看第三方 skill？」，不列名；题材命中场景触发词才多 1–2 句定向推（`gtrk skills recommend --scene <id> --json` 取 tier 最高者，各给一句为什么），用户追问才展开完整块；轻提加定向合计不超三句、同会话同场景只推一次、答「不要」零动作。
+
 ## 二、双轨收音：对轨 → 换轨（本图纸最大的新东西）
 
 真实口播几乎都是**双轨收音**：相机内录只是参考声，领夹麦/录音笔的外录才是成片要用的。而粗剪链吃的是视频文件里的音轨 ⇒ **先把外录换进去，转写和成片就都是外录声**。
@@ -66,6 +70,42 @@ gtrk audio align --resume "<名>_align.gtrk"
 - **内录不丢弃**：原毛片原地不动就是保底轨，外录出问题（爆音/断录）随时回退重跑。
 - 闭环：oralcut 产的工程本来就进客户端 ⇒ **对齐效果（唇音同步）最终以客户端预览为准**——兜底与验收用同一个工具。
 
+## 二′、屏录 / 第二机位：双源画中画（`gtrk pip lay`）
+
+真实的「讲软件 / 讲代码 / 讲课件」口播几乎都是**两条文件同步录**：屏幕一条、人像一条。粗剪只剪人像；本零件把粗剪的**每个切点镜像到屏录**，
+铺出「屏录满幅轨 + 人像画中画副本轨」，画中画带形状蒙版 / 圆角，客户端打开即所见。**纯本地、零计费。**
+
+### 链路位置
+
+对轨（§二，可选）→ `oralcut` → **检查点①** → **`gtrk pip lay`** → 包装（字卡 / BGM / 字幕）→ 客户端出片。
+`pip lay` **不新增必停点**——铺完让用户在客户端看一眼即可；只有低置信兜底会停（那是数据正确性问题，两种模式都停）。
+
+### 一条命令
+
+```bash
+gtrk pip lay --project "<口播工程目录>" --companion "<屏录.mp4>" \
+  [--shape ellipse|rectangle|heart|diamond|star|none] [--feather 10] [--border-radius 24] \
+  [--anchor bottom-right] [--scale 0.28] [--margin 40] [--offset <秒>] [--dry-run]
+```
+
+自动分支：以人像为参考、屏录为待对齐做互相关，置信度 ≥ 阈值直接铺，回执逐颗打印偏移与钳位（**打印数字，不打「已验证」**）；
+置信度不足 → 产 `<屏录名>_pip_align.gtrk`，让用户在客户端把「伴随源」轨拖到与人像画面对齐后保存，再：
+
+```bash
+gtrk pip lay --project "<口播工程目录>" --resume "<屏录名>_pip_align.gtrk"
+```
+
+### 四条纪律
+
+- **录制规约**（开工时就说）：两条文件同步录；**屏录 MUST 带麦克风音轨**（互相关的参照，无麦只能 `--offset` 或客户端拖齐）；开录后拍一下手。
+- **主轨不动**：人像仍是主轨（`split` / `subtitle lay` 对 transcript 的锚不变），屏录与画中画都是叠加轨；画中画副本恒静音，人声由主轨承担。
+- **屏录比人像短 / 晚开录**：对应段留空、回执点名毫秒数，MUST NOT 拉伸或变速补齐；成片该段只见人像主轨——这是如实，不是缺陷。
+- **幂等**：改了参数直接重跑，自产轨剥旧重铺；用户在客户端动过的画中画 clip 会被保留并点名，不会被覆盖。
+
+### 出片口径
+
+客户端本地导出（所见即所得）/ `gtrk render`（本地合成画中画几何与蒙版）/ 导剪映（圆窗 / 圆角进草稿；**菱形剪映无对应会跳过并明示**）。
+
 ## 三、多段一期：concat-first
 
 一期内容由多段毛片构成时（分场景拍摄、换机位重启录制），**先拼后剪**：
@@ -93,8 +133,9 @@ gtrk oralcut "<inputs/…_full.mp4>" --lang zh-CN [--script 稿.txt] [--preset c
 1. **粗剪回执走查**：时长压缩比是否合理（口播毛片通常剪去 20–50%）、report 剪除项抽查 2–3 处是否真是废话。**剪错了真内容** → 换 `--preset steady` 或开 `--visual-assist` 重跑，MUST NOT 带着错误粗剪往下铺。
 2. **BGM 拍板（双来源，推荐必附试听链接）**：用户自带音乐 → 问是否 `audio_separation` 分离取伴奏；没带 → 素材矩阵按内容基调搜 3–5 首附试听直链。
 3. **字幕样式拍板**：给样式候选，用户没选用 default。
+4. **前六秒方案拍板**（公约 §三⁗ 执行文本，引用不复制）：粗剪回执到手后、检查点①之前由你产——基于粗剪转写**首段**改写**钩子文案三候选**（五型任选，每条一行，只改开口方式、MUST NOT 改动用户的事实与数据）+ **画面层建议**（A_ROLL / MG 字卡 / 拼贴或 AI 片段三选一）+ **字卡节奏**（屏字与出现时机按公约口径）。与前三项同屏一次拍板；用户答「开场照原样」= 零动作、后续不再提。先给自持方案，再一句轻提「要更多变体也可以看第三方钩子 skill」（推荐面 §三‴ 的 `hook` 场景，不列名）。拍了 MG 字卡 ⇒ §五 拆分稿里开场 beat 的 MG `handoff.theme` 写 `"opening-hook｜屏字：<拍板文案>"`；拍了 A_ROLL ⇒ 开场不派辅助层。
 
-以上三项一次确认完 = 检查点①收口。
+以上四项一次确认完 = 检查点①收口。
 
 ## 五、拆分与铺轨：三车道，无 AI 再现
 

package/skills/gtrk-travel-recap/SKILL.md

@@ -43,6 +43,8 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 | 声音怎么来 | **TTS 配音**（缺省，检查点①挑音色）/ **用户自己念**——拿念稿毛片先走 `gtrk oralcut` 粗剪（带稿最准；外录收音先 `gtrk audio align` 对轨），产出的粗剪工程即时间基座，§五 的「配音④→建工程⑤」两步跳过，从拆分⑥接入，后续铺排/字卡/BGM/字幕照旧 |
 | **源片语种 / 方言** | 取证=**听一段 / 看片内有无内嵌字幕 / 看素材出处**；答案定 §五 ① 的 `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）。**MUST 问用户、MUST NOT 代猜、MUST NOT 以缺省 `zh-CN` 静默开跑转写**——转写是计费动作**且早于检查点①**：**非中文素材**（`en-US` / `ja-JP`…）语种传错，用户在检查点①拿到的稿子就是坏的、重来要再付一次 ASR（真机实证）。**中文这一档（`zh-CN` ↔ `zh-HK`）不在此列**：粤语 **SHOULD** 如实填 `zh-HK`（元数据诚实 + 备将来链路切换），但当前实现下该参数**对粤语无影响**——两种写法发出的请求逐字段相同，详见 §五 ① 注。素材无对白：答「无对白 / 不转写」即闭合 |
 
+> ⟲ **推荐面（公约 §三‴）**：问答收口时多问一句「要不要看看第三方 skill？」，不列名；题材命中场景触发词才多 1–2 句定向推（`gtrk skills recommend --scene <id> --json` 取 tier 最高者，各给一句为什么），用户追问才展开完整块；轻提加定向合计不超三句、同会话同场景只推一次、答「不要」零动作。
+
 ## 一′、素材适配闸（写稿前必过 · ★ 2026-09-02 真机事故立）
 
 > **事故形态**：三条素材里有一条是**有剧情、有台词、有摆拍的学生短片**，本图纸从头到尾跑完（含 TTS 计费步骤）、**零提示**。

package/skills/gtrk-voiceover/SKILL.md

@@ -28,10 +28,12 @@ description: 通用配音视频创作图纸（配音链快速成片预设）—
 
 一张表一次问完；**未经检查点①确认 MUST NOT 发起 TTS 计费动作**。
 
+> ⟲ **推荐面（公约 §三‴）**：问答收口时多问一句「要不要看看第三方 skill？」，不列名；题材命中场景触发词才多 1–2 句定向推（`gtrk skills recommend --scene <id> --json` 取 tier 最高者，各给一句为什么），用户追问才展开完整块；轻提加定向合计不超三句、同会话同场景只推一次、答「不要」零动作。
+
 ## 二、快速成片编排
 
 ```bash
-# ①② 写稿（三段式通用框架层 + 文风铁律自校验）→ 检查点①拍板
+# ①② 写稿（三段式通用框架层 + 文风铁律自校验）→ 产前六秒方案（公约 §三⁗：基于稿件首段改写钩子文案三候选 + 画面层建议 + 字卡节奏，只改开口不改事实）→ 检查点①拍板
 gtrk matrix material "<情绪 调性 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
 #   ⚠️ is_copyright：1/true=可商用、0/false=**不可商用**（反直觉，MUST NOT 读成「无版权、可随便用」）。
 #   ⟲ 260906 拍板：矩阵成员档**缺省搜全库**，MUST NOT 默认加 --commercial-only、也 MUST NOT 擅自剔掉
@@ -60,7 +62,7 @@ gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
 
 ## 三、检查点①（必停一次）
 
-稿件全文 + 画幅 + 音色（试听）+ BGM（试听）+ 字幕样式，一屏给齐一次拍板。改稿在这站改到满意——配音之前全部免费。
+稿件全文 + **前六秒方案**（公约 §三⁗ 执行文本，引用不复制：钩子文案三候选各一行 + 画面层 A_ROLL / MG 字卡 / 拼贴或 AI 片段三选一 + 字卡节奏；只改开口方式、MUST NOT 改动用户的事实与数据；答「开场照原样」= 零动作、后续不再提；先给自持方案，再一句轻提「要更多变体也可以看第三方钩子 skill」，推荐面 §三‴ 的 `hook` 场景、不列名）+ 画幅 + 音色（试听）+ BGM（试听）+ 字幕样式，一屏给齐一次拍板。改稿在这站改到满意——配音之前全部免费。拍了 MG 字卡 ⇒ §二 ④ 拆分稿里开场 beat 的 MG `handoff.theme` 写 `"opening-hook｜屏字：<拍板文案>"`；拍了拼贴或 AI 片段 ⇒ 开场 beat 派 AI_DRAMA；拍了 A_ROLL ⇒ 开场不派辅助层。
 
 ## 四、MG 风格（公约 §三 执行文本）