@gitruck/cli 1.3.1 → 1.3.4

package/docs/reference.en.md

@@ -1,5 +1,9 @@
 # Agent, configuration and command reference
 
+Local visual handoff for `matrix describe`: `--prepare <project-directory>` writes a review job with source fingerprints, timestamps and image hashes, without calling Doubao. The current agent inspects the images, fills the response, then imports it with the same `--materials` or `--plan` arguments and `--review <visual-review.json>`. Only items explicitly marked unavailable with a reason fall back to Doubao. Missing answers, changed sources and mismatched criteria fail before cloud requests. This is an agent workflow, not a form the user must fill. Fully local completion requires no API key; cloud fallback requires configuration.
+
+Video overviews cover each scene at intervals of at most six seconds. `describe --materials <video> --source-window <start,end>` inspects only that source window at intervals of at most two seconds and supports prepare/review. Images have no temporal window. Plan mode still describes each candidate's best frame; a frame is not evidence of an entire action. Indexing uses six-second cells for stable scenes and retains two-second sampling for other long scenes. Explicit indexing refreshes old stable materials with insufficient coverage and reports the extra work.
+
 [Back to README](../README.en.md) · [Workflow](workflow.en.md) · [简体中文](reference.md)
 
 ## Using it with AI agents
@@ -183,7 +187,7 @@ Common entry points: `gtrk oralcut` edits talking heads, `gtrk long2short` selec
 
 ### `gtrk long2short` / `gtrk pip` / `gtrk qc` — Additional commands
 
-- `gtrk long2short <input>`: select topics and jump-cut into per-clip gtrk / Jianying / XML projects. `--split-screen` uses a 720p proxy for smart split-screen; `--output-size` selects the aspect ratio; `--subtitle-out` writes captions for each clip. Run landscape and portrait separately; content determines the number of clips. See `gtrk long2short --help` for all options.
+- `gtrk long2short <input>`: select topics and jump-cut into per-clip gtrk / Jianying / XML projects. `--split-screen` uses a 720p proxy for smart split-screen; `--output-size` selects the aspect ratio; `--subtitle-out` writes captions for each clip; `--speed-factor 0.5–2.0` writes an overall speed change (pitch preserved) into every clip project (no cloud rendering, no extra charge); `--camera-move` has the cloud write push / pull camera moves as scale keyframes on main-track segments (visible and editable in the client and Jianying, not shown by local `gtrk render` or Premiere projects; `clips.md` marks "N camera moves"), and later `gtrk patch` trims / splits keep those keyframes valid. The output root also gets a whole-source transcript `json/transcript.json`, so any clip can get a client caption track: `gtrk subtitle lay --gtrk <clip dir>/gtrk/<project>.gtrk --transcript <output root>/json/transcript.json --language <source language>` (`--language` sets the cloud line-split language, default zh-CN). Run landscape and portrait separately; content determines the number of clips. See `gtrk long2short --help` for all options.
 - `gtrk pip lay`: lay a simultaneously recorded screen or second camera against the talking-head cut points. Both sources need shared audio for alignment; low-confidence matches require calibration in the client before resuming. Use `gtrk pip lay --help` for inputs, shapes, positions and offsets.
 - `gtrk qc <video>`: inspect flash frames, black/frozen frames, volume and synchronization. Add `--gtrk` for project context and `--fail-on` for pipeline gating. Findings locate issues; they do not automatically repair the video.
 
@@ -313,7 +317,7 @@ gtrk matrix source-import --project <project-dir> --beat B07 --urls links.txt --
 
 Repeat `--url`, or provide one URL per line with `--urls` (1–32 total). Supported pages are HTTPS YouTube, Vimeo, TikTok and bilibili URLs. With `--project`, the CLI only appends candidates to that beat's `struct_meta.broll`; it does not touch the timeline or run `matrix lay`. The complete task receipt is kept under `split/.source-import/`. For an agent or another automation to consume the result without a project, use `--out <result.json>` and omit `--project/--beat`.
 
-Each source becomes one low-resolution full-window preview candidate. `source-import` itself does not download the high-resolution source, change the timeline, or create an `online_broll_resolve` task. The client may still open the Trim dialog by double-clicking it, but the selectable range is strictly bounded by that candidate's source window; the pretrim is carried into the timeline when dragged. After the user places the candidate on a track and clicks “Confirm B-roll”, the client submits the selected source window to `online_broll_resolve`; the cloud downloads that high-resolution window and replaces the low-resolution timeline media. `更多外网候选` / `More external candidates` paginates keyword-search tasks only and never treats manually specified sources as another search page.
+Each source becomes one low-resolution full-window preview candidate. `source-import` itself does not download the high-resolution source, change the timeline, or create an `online_broll_resolve` task. The client may still open the Trim dialog by double-clicking it, but the selectable range is strictly bounded by that candidate's source window; the pretrim is carried into the timeline when dragged. After the user places the candidate on a track and clicks “Confirm B-roll”, the client submits the selected source window to `online_broll_resolve`; the cloud downloads that high-resolution window and replaces the low-resolution timeline media. `更多外网候选` / `More external candidates` paginates keyword-search tasks only and never treats manually specified sources as another search page.
 
 ### `gtrk matrix` — B-roll retrieval + candidate track laying
 
@@ -471,6 +475,28 @@ There are two billing surfaces: structural project export is billed per task, wh
 
 Before particle rendering, the command performs HTML, path and cache preflight; a preflight failure submits no cloud task. A single particle render or download failure is recorded in `result.json` while other formats continue. With `--json`, stdout contains one result JSON line and human logs go to stderr.
 
+### `gtrk project background` — client canvas background (blur / solid color)
+
+Changes only `struct_meta.client_background` in the `.gtrk`; the client renders the canvas background from it when the project opens, and the user can change it back in the client settings. The typical use is a blurred fill instead of black bars when a landscape source sits on a portrait canvas. Zero credits, no cloud access; Jianying / Premiere projects and local `gtrk render` do not carry this setting.
+
+```bash
+gtrk project background --gtrk <project-file> --blur
+gtrk project background --project <project-dir> --blur --intensity 300
+gtrk project background --gtrk <project-file> --color "#1A1A1A"
+gtrk project background --gtrk <project-file> --clear
+```
+
+| Option | Purpose |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | Locate the project, same rules as `project export` |
+| `--blur` | Blurred fill: a blurred copy of the visible main-track picture underneath |
+| `--intensity <n>` | With `--blur`, 0–1000, default 200 |
+| `--color <#RRGGBB>` | Solid color (six-digit hex) |
+| `--clear` | Remove the setting and return to the client's default black |
+| `--dry-run` | Validate and report the value that would be written, without writing |
+
+Exactly one mode is required. Writes go through atomic replace with the content-revision guard and leave everything else intact; nothing is written when the value is unchanged. The `--json` receipt includes the revisions before and after.
+
 > **`--beat-align`**: follows the climax-anchor rule in the table above; an explicit `--climax` overrides the automatic selector. The mode calls `audio_music_analyze` and incurs its listed charge.
 
 
@@ -627,3 +653,7 @@ A QC pass runs automatically afterwards and writes `.qc.json` (`--no-qc` skips i
 - `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills dir>]` — install/refresh agent skills on their own; by default the generic adapter and the gtrk supplement layer detect hosts automatically.
 - `gtrk skills recommend [--scene <id>] [--json]` — third-party skill catalog: without `--scene` lists the ten scenes (hook / mg-explainer / kinetic-text / data-viz / map / ai-drama / collage / caption / principles / technique); with a scene prints entries by tier (purpose / install command / license and dependencies / register command). **Recommend, never bundle**: the catalog ships with the package with a snapshot date, no network, no state; stars and licenses are as of the snapshot, installing is your call. GPL / AGPL / non-commercial / unlicensed / MCP-SaaS-only skills are excluded. The catalog also lists Gitruck's own first-party MG layout-technique family (`--scene technique`, entries marked `origin: first-party`): techniques are not lane producers; the agent picks them per slot at the MG step.
 - `gtrk skills add <owner/repo> [--skill <name>]... [--produces MG|AI_DRAMA|FILM_BROLL|script|none] [--column <id>] [--agents ...] [--all] [--copy]` — installs a third-party skill through the generic `skills` adapter and, on success, **appends** `{id, ref: "<owner/repo>#<skill>", produces, status: "third-party"}` (`"first-party"` for first-party entries) to the show config `style.skills` (idempotent per ref, nothing is registered on failure; `--produces` defaults to the catalog value, repos outside the catalog register with `routing:"none"`), after which `gtrk mg` / `/gtrk-ai-drama` resolve it by `produces`.
+
+### Highlight discovery (internal preview)
+
+`gtrk tool video_highlight <video> --out <project> --json` uploads a locally generated silent 224p/4fps proxy. Inputs must be longer than 3 seconds and at most 30 minutes. Results contain three-second candidates grouped by request; scores cannot be compared across requests. Review candidates against the story and actual footage. Provider failure stays explicit; Vlog planning can continue with Agent material review. External billing is not enabled.

package/docs/reference.md

@@ -1,5 +1,17 @@
 # Agent、配置与命令参考
 
+`project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080` 在本地组装分段工程，不上传原片、不自动合成声音。清单示例：
+
+```json
+{"version":1,"segments":[{"kind":"live","source":"原片.mp4","in":3,"out":11},{"kind":"narration","source":"旁白.wav","transcript":"旁白.json"},{"kind":"image","source":"照片.jpg","duration":4}]}
+```
+
+路径相对清单；视频默认保留独立同期声，`keep_audio:false` 关闭；旁白段留同长画面空档。图片段为静帧，运镜先经 `tool image_move` 产视频。文稿用源时基 `utterances:[{st,ed,text}]`；合并文稿逐句绑定素材，供 `split`、`subtitle lay` 随剪辑重投影，切点截断的整句会省略并报告。输出目录必须不存在，已有工程精修走 `patch`，避免覆盖。
+
+`matrix describe` 的本地视觉交接：`--prepare <工程内目录>` 生成带时码、源指纹与图片哈希的审阅任务，零豆包调用；当前 Agent 看图填写回执后，以相同 `--materials` 或 `--plan` 参数加 `--review <visual-review.json>` 导入。仅明确标记无法完成并给出原因的条目回退豆包；缺答、素材变化或准则不一致会报错，不自动上云。这个接力由 Agent 完成，不要求用户填表。纯本地完成时无需 API Key，回退豆包时需要云端配置。
+
+视频素材概览按场景最多六秒间距覆盖；`describe --materials <视频> --source-window <起秒,止秒>` 在指定窗内按最多两秒间距细查，可与 prepare/review 组合。图片没有源时间窗。`--plan` 保持每候选 best 帧口径，单帧描述不证明整段动作。索引的 stable 长场景同样按六秒单元抽帧，普通长场景仍每两秒；下次显式 index 会更新欠覆盖的旧 stable 素材，并报告新增处理。
+
 [返回首页](../README.md) · [工作流](workflow.md) · [English](reference.en.md)
 
 ## 给 AI Agent 用
@@ -178,7 +190,7 @@ GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4   # 环境变量，临时关一次（
 
 ### `gtrk long2short` / `gtrk pip` / `gtrk qc` — 常用补充
 
-- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。完整参数见 `gtrk long2short --help`。
+- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕；`--speed-factor 0.5–2.0` 把整体调速（保音高）写进逐 clip 工程（云端不渲染、不加价）；`--camera-move` 让云端把推 / 拉镜头写成主轨片段的缩放关键帧（客户端与剪映可见可改，本地 `gtrk render` 与 PR 工程不呈现；`clips.md` 标「运镜 N 处」），之后 `gtrk patch` 裁剪 / 切分会同步维护关键帧。产物根另落整片转写 `json/transcript.json`，可对任一 clip 上客户端字幕轨：`gtrk subtitle lay --gtrk <clip 目录>/gtrk/<工程>.gtrk --transcript <产物根>/json/transcript.json --language <源语种>`（`--language` 为云端拆行语种，缺省 zh-CN）。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。完整参数见 `gtrk long2short --help`。
 - `gtrk pip lay`：把同步录制的屏录或第二机位按口播剪点铺成画中画。两源需有可对齐的公共声音；低置信时先在客户端校准，再按提示恢复。运行 `gtrk pip lay --help` 查看输入、形状、位置和偏移参数。
 - `gtrk qc <成片>`：检查闪帧、黑帧、冻结、音量和同步问题；用 `--gtrk` 提供工程上下文，`--fail-on` 控制管线门槛。检查结论供定位问题，不自动替你修片。
 
@@ -280,6 +292,7 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | `trim` 的五种语义（前两个相对、中两个绝对、`--slip` 只换源窗） | — |
 | `--cut <sec\|Nf>` | `split` 的切点。⚠️ 与寻址用的 `--at` 是两个参数 | — |
 | `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
+| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨 | — |
 | `--total <sec\|Nf\|max>` | `set` 的顶层总长（工程级 op，与元素寻址互斥） | — |
 | `--ops <file\|->` | 批量事务：一次读、全算、全校验、一次写；任一条失败**零写** | 关 |
 | `--dry-run` | 只算与校验、不写文件 | 关 |
@@ -303,7 +316,7 @@ gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt -
 
 `--url` 可重复传，`--urls` 是逐行读取的文件；两者可同时使用，合计 1–32 条，支持 YouTube、Vimeo、TikTok、bilibili 的 HTTPS 视频页。带 `--project` 时 CLI 只追加 `struct_meta.broll` 中该 beat 的候选，不改时间线，也不会执行 `matrix lay`；完整任务回执会保存到 `split/.source-import/`。只想让 AI 或其它自动化消费结果时，改用 `--out <result.json>`，省略 `--project/--beat`。
 
-每个指定来源生成一个整段低清预览候选，`source-import` 本身不会下载高清原片、不会改时间线，也不会创建 `online_broll_resolve`。候选的时间窗就是该来源已下载预览的完整窗口。客户端对它仍可双击打开 Trim 对话框，但裁剪范围严格限制在该候选来源窗口内；预裁剪会随拖拽进入时间线。用户把候选放入轨道并点击“确认 B-roll”后，客户端才把当前源时间窗口提交给 `online_broll_resolve`，由云端下载高清窗口并置换当前低清素材。`更多外网候选` 只对关键词检索任务分页，不会把指定来源任务重复当作搜索结果。
+每个指定来源生成一个整段低清预览候选，`source-import` 本身不会下载高清原片、不会改时间线，也不会创建 `online_broll_resolve`。候选的时间窗就是该来源已下载预览的完整窗口。客户端对它仍可双击打开 Trim 对话框，但裁剪范围严格限制在该候选来源窗口内；预裁剪会随拖拽进入时间线。用户把候选放入轨道并点击“确认 B-roll”后，客户端才把当前源时间窗口提交给 `online_broll_resolve`，由云端下载高清窗口并置换当前低清素材。`更多外网候选` 只对关键词检索任务分页，不会把指定来源任务重复当作搜索结果。
 
 ### `gtrk matrix` — B-roll 检索 + 候选铺轨
 
@@ -494,6 +507,28 @@ gtrk project export --gtrk <工程文件> --formats jianying,xml --out <产物
 
 颗粒预渲前会先完成 HTML、路径和缓存预检；预检失败不会提交任何云任务。单颗粒渲染或下载失败会记录在 `result.json`，其余格式继续导出。`--json` 输出单行结果 JSON，人读日志走 stderr。
 
+### `gtrk project background` — 客户端画布背景（模糊底 / 纯色）
+
+只改 `.gtrk` 的 `struct_meta.client_background` 一个键：客户端打开工程即按它呈现画布背景，可在客户端设置里改回。典型用途是横屏源进竖屏画布时用模糊底替代黑边。零计费、不访问云端；剪映 / PR 工程与本地 `gtrk render` 不承接该设置。
+
+```bash
+gtrk project background --gtrk <工程文件> --blur
+gtrk project background --project <工程目录> --blur --intensity 300
+gtrk project background --gtrk <工程文件> --color "#1A1A1A"
+gtrk project background --gtrk <工程文件> --clear
+```
+
+| 参数 | 作用 |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | 定位工程，规则同 `project export` |
+| `--blur` | 模糊底：主轨可见画面的模糊副本垫底 |
+| `--intensity <n>` | 配合 `--blur`，0–1000，缺省 200 |
+| `--color <#RRGGBB>` | 纯色底（六位十六进制） |
+| `--clear` | 删除该设置，回到客户端缺省黑底 |
+| `--dry-run` | 只校验并回执将写入的值，不写文件 |
+
+三种模式恰好选一个。写回走原子替换与内容 revision 守卫，其余内容原样保留；值未变时不写盘。`--json` 回执含写前写后 revision。
+
 > **`--beat-align`**：按表格中的高潮点锚定规则工作；显式 `--climax` 会覆盖自动判据。该模式会调用 `audio_music_analyze` 并产生相应计费。
 
 
@@ -661,3 +696,7 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 - `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills 目录>]` — 单独安装/刷新 Agent Skills；缺省由通用适配器与 gtrk 补充层自动检测。
 - `gtrk skills recommend [--scene <id>] [--json]` — 第三方 skill 推荐目录：不带 `--scene` 列十个场景（hook / mg-explainer / kinetic-text / data-viz / map / ai-drama / collage / caption / principles / technique），带场景按 tier 给条目（用途 / 安装命令 / 许可与依赖 / 登记命令）。**只推荐不打包**：目录随包分发、带快照日期、不联网不留痕；star 与许可以仓库页为准，装不装是你的选择。GPL / AGPL / 非商用 / 无许可证 / 只能经 MCP-SaaS 运行的不入目录。目录也收同合云一方的 MG 排版技法族（`--scene technique`，条目 `origin: first-party`）：技法不当车道生产者，由 agent 在 MG 步按槽位取用。
 - `gtrk skills add <owner/repo> [--skill <name>]... [--produces MG|AI_DRAMA|FILM_BROLL|script|none] [--column <id>] [--agents ...] [--all] [--copy]` — 透传通用 `skills` 适配器安装第三方 skill，成功后把 `{id, ref: "<owner/repo>#<skill>", produces, status: "third-party"}`（一方条目 `status: "first-party"`）**追加**进栏目配置 `style.skills`（同 ref 幂等、失败不登记；`--produces` 缺省取目录值，目录外仓登记为 `routing:"none"`），之后 `gtrk mg` / `/gtrk-ai-drama` 按 `produces` 即可解析到它。
+
+### 视频高光发现（内部验收）
+
+`gtrk tool video_highlight <视频> --out <工程目录> --json`：本地224p/4fps无声代理，只上传代理；返回分请求三秒候选。3秒以上、30分钟以内。候选须按制片语义复核；不可跨请求比较分数。服务失败不冒充成功，Vlog可继续Agent素材理解。尚未开放外部收费。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.3.1",
+	"version": "1.3.4",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",
@@ -57,7 +57,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": "node scripts/workspace-pollution-gate.mjs --snapshot && esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/log.ts src/lib/read-json.ts src/lib/sidecar-write.ts src/lib/user-config.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/online-broll-client.ts src/lib/online-search-journal.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/character-input.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/project-health.ts src/lib/contact-sheet.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.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-batch.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/cut-snap.ts src/lib/mg-coverage.ts src/lib/ai-drama-lay.ts src/lib/ai-drama-pack.ts src/lib/desk-locate.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --external:bun:sqlite --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 --external:bun:sqlite --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --external:bun:sqlite --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/commands/doctor.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/doctor-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 --external:bun:sqlite --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.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 --external:bun:sqlite --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && esbuild src/commands/purify.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/purify-cmd.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\" && node scripts/workspace-pollution-gate.mjs --verify",
+		"test": "node scripts/workspace-pollution-gate.mjs --snapshot && esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/log.ts src/lib/read-json.ts src/lib/sidecar-write.ts src/lib/user-config.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/project-background.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/clip-speed.ts src/lib/clip-keyframes.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/online-broll-client.ts src/lib/online-search-journal.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/character-input.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/project-health.ts src/lib/contact-sheet.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/composite-particle.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-batch.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/cut-snap.ts src/lib/mg-coverage.ts src/lib/ai-drama-lay.ts src/lib/ai-drama-pack.ts src/lib/desk-locate.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --external:bun:sqlite --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 --external:bun:sqlite --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --external:bun:sqlite --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/commands/doctor.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/doctor-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 --external:bun:sqlite --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.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 --external:bun:sqlite --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && esbuild src/commands/purify.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/purify-cmd.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\" && node scripts/workspace-pollution-gate.mjs --verify",
 		"test:linux": "node scripts/test-linux.mjs",
 		"openspec:gate": "node openspec/gate.mjs",
 		"mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs",

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

@@ -5,7 +5,7 @@ description: 直播切片图纸——把一场数小时的直播回放，拆成
 
 # gtrk-live-slicing（直播切片 · 组合成片图纸）
 
-把**一场直播回放**（1–4 小时）变成**一批可编辑的逐 clip 粗剪工程**：四问定策略 → 分段 → 逐段选段 → **选题清单必停** → 出工程。
+把**一场直播回放**（1–4 小时）变成**一批可编辑的逐 clip 粗剪工程**：五问定策略 → 分段 → 逐段选段 → **选题清单必停** → 出工程。
 
 > **定位**：第三张 **structure 级组合图纸**（前两张=`gtrk-travel-recap` 旅拍解说、`gtrk-vlog-docu` Vlog 纪实）。不新增任何命令，只编排既有零件。参数细节以 `gtrk-long2short` 与 `--help` 为准，**本图纸引用不复制**；**编排次序、分段规约、检查点**以本图纸为准。**CLI 是手，你是脑。**
 
@@ -17,17 +17,18 @@ description: 直播切片图纸——把一场数小时的直播回放，拆成
 
 - ❌ 不去水印、❌ 不去烧录贴片、❌ 不做画面清理美化、❌ 不调色不裁切
 - 源片长什么样，切片就长什么样。要不要动那些元素，是**用户在客户端二次编辑时的决定**，不是你的。
-- 分段所需的时间轴裁切**必须用 `ffmpeg -c copy` 流拷贝**（不重编码）。
+- 分段所需的时间轴裁切**必须用 `ffmpeg -c copy` 流拷贝**（不重编码）。
+- **工程层设置不算像素改动**：变速倍率（`--speed-factor`）、运镜关键帧（`--camera-move`）、客户端字幕轨（`gtrk subtitle lay`）、画布模糊底（`gtrk project background`）都写在工程里、可在客户端撤销，源片本身一个像素不动——与本条不冲突。
 
 > **用户只要能直接发的成片、不打算再剪？** 那不是本图纸的活，转 `gtrk tool video_long2short_pro`（精剪，整片上传、云端渲染、计费约两倍）。判断句同 `gtrk-long2short`：**「剪完还要不要再动？」要动 → 留这儿；不动 → 转精剪。**
 
-## 一、输入契约与开工四问
+## 一、输入契约与开工五问
 
 **输入**：一条直播回放的**本地文件**（`.ts` / `.mp4` 等均可）。
 
 **MUST NOT 执行录制或下载**——平台动作与版权责任归用户。用户给什么文件就用什么。
 
-开工前先答四问，答案决定后面全部策略：
+开工前先答五问，答案决定后面全部策略：
 
 | # | 问 | 怎么取证 | 决定什么 |
 |---|---|---|---|
@@ -35,28 +36,30 @@ description: 直播切片图纸——把一场数小时的直播回放，拆成
 | ② | 画面形态是否单一 | **问用户**——全程主播口播位？还是含实景走播/换机位？ | **哪些段开分屏**（§四） |
 | ③ | 有无烧录贴片 | 抽 2–3 帧看（开头/中段/尾段各一） | **交付时要如实告知什么**（§五） |
 | ④ | 入选切片要不要叠 MG 动画 | **问用户**——缺省不叠（粗剪定位） | **选题清单敲定后是否走 MG 车道**（§七） |
+| ⑤ | 入选切片要不要加运镜（推拉镜头） | **问用户**——缺省不加 | **逐段提交是否带 `--camera-move`**（§七「运镜」） |
 
-> **②④ MUST 问用户、MUST NOT 代猜。** ②猜错的代价是白跑一轮分屏（几十分钟 + 积分）；
-> ④缺省是**不叠**——用户没要就零 MG 动作，MUST NOT 硬塞。
+> **②④⑤ MUST 问用户、MUST NOT 代猜。** ②猜错的代价是白跑一轮分屏（几十分钟 + 积分）；
+> ④缺省是**不叠**——用户没要就零 MG 动作，MUST NOT 硬塞；⑤缺省是**不加**——用户没要就全程不带 `--camera-move`、不再追问。
+> ⑤ 必须在提交前问：运镜是云端任务参数，交上去之后改不了（没入选的 clip 带了运镜也无害，随 clip 一起丢弃）。
 > **③ 的取证目的只是「告知」，不是「处置」**——看到贴片不要动手，见定位铁律。
 > ② 与 `/gtrk-long2short`、`/gtrk-tools` 精剪开工的「多人同框」一问同口径：是就开、不确定按否；
 > 分屏单段最长 8 秒、每条最多 3 处。
 
-> **推荐面（公约 §三‴）**：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 `gtrk skills recommend --scene <id> --json`；用户拒绝后不执行推荐动作。
+> **推荐面（公约 §三‴）**：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 `gtrk skills recommend --scene <id> --json`；用户拒绝后不执行推荐动作。
 
 ## 二、分段规约（本图纸的骨干）
 
-### 两道闸
+### 两道闸
 
 | | 闸 | 值 | 命中时的表现 |
 |---|---|---|---|
 | **闸一** | 服务端媒体探测层全局业务限制 | **2 小时** | **建单期直接拒**：`6019 媒体时长无效或超过业务限制`。**任务不创建、不计费** |
 | **闸二** | CLI 轮询墙钟 | **60 分钟** | 轮询超时报错（任务在云端照常跑完，可取回） |
 
-**处理耗时 / 源时长比值按分屏与否分档**：
+**处理耗时 / 源时长比值按分屏与否分档**：
 
-- **不开分屏**：墙钟压力较小；
-- **开分屏**：处理耗时明显增加，优先按较短段切分。
+- **不开分屏**：墙钟压力较小；
+- **开分屏**：处理耗时明显增加，优先按较短段切分。
 
 ⇒ **单段 MUST ≤ 2h（硬拒线），开分屏时 SHOULD ≤ 48min（墙钟线）。**
 
@@ -75,7 +78,7 @@ ffmpeg -ss 3600 -t 2400 -i "<直播回放>" -c copy "<工作区>/inputs/<名>_se
 
 ### ⚠️ 两条必须在动手前告诉用户
 
-1. **切段是新文件，工程指向它、不指向原片。** 逐 clip 工程的 `materials[].path` 实指切段；用户删掉切段文件，工程就素材脱机。让他把 `inputs/` 留着。
+1. **切段是新文件，工程指向它、不指向原片。** 逐 clip 工程的 `materials[].path` 实指切段；用户删掉切段文件，工程就素材脱机。让他把 `inputs/` 留着。
 2. **超过 2 小时整条提交会被直接拒**，不是慢、是拒。好消息是零计费（不进队列），但会白抽白传一个大文件——所以先分段。
 
 ### 超时兜底
@@ -96,7 +99,7 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 
 | 模式 | 停点 |
 |---|---|
-| **快速成片** | 四问 + 分段方案确认 → 逐段跑 → **【必停】选题清单** → 确认后一路出工程 |
+| **快速成片** | 五问 + 分段方案确认 → 逐段跑 → **【必停】选题清单** → 确认后一路出工程 |
 | **逐步推进模式** | 上述基础上每步都停（分段方案 / 逐段选段结果 / 逐条工程产物） |
 
 两模式共用同一套分段规约与参数配方，**差别只在停几次，不在停不停**。
@@ -121,7 +124,7 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 > **判断分屏是否真的生效，MUST 看产物证据，MUST NOT 按「没报错」推定。**
 > 证据 = `report.json` 的 `split_manifest` 条数 + 毛片旁 `split_screen/` 目录里的素材（可抽帧看）。
 
-**分屏在子轨、主轨原片可回退**：分屏素材落在独立子轨上叠放，
+**分屏在子轨、主轨原片可回退**：分屏素材落在独立子轨上叠放，
 主轨的原片全程完整在场——用户对某段分屏不满意时，在客户端隐藏/删除子轨该段即回退原片，
 零重跑。交付时把这条回退动线告诉用户。⚠️ 连带边界：本地 `gtrk render` 是快照渲染、
 **不合成子轨**——渲出来没有分屏画面；要分屏成片走客户端出片（或剪映导出）。
@@ -129,9 +132,11 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 其余参数配方：
 
 - `--language` **必填**，缺失在上传前就报错（省一次白上传）
-- 竖屏直播源通常**无需转比例**，`--output-size` 缺省即可
+- 竖屏直播源通常**无需转比例**，`--output-size` 缺省即可
 - `--duration-pref` / `--max-clip-sec` 按投放平台口径给档
-- `--subtitle-out` 产逐 clip **独立 `.srt`**（不烧进画面——符合粗剪工程定位）
+- `--subtitle-out` 产逐 clip **独立 `.srt`**（不烧进画面）——**可选**，给要拿去 PR 精修的用户；客户端用户走 §七 的字幕上轨
+- `--speed-factor` **只在用户主动要求时加**（见 §七「调速」）；开工问询里不问速度
+- `--camera-move` 按开工⑤：用户要运镜才带（见 §七「运镜」），各段一致
 
 > 完整参数表在 `gtrk-long2short`，本节只给直播场景的**配方差异**，不搬手册。
 
@@ -145,7 +150,7 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 | **时效信息贴片**（价格 / 截止日期） | 切片再发布时是**过期信息** | 额外点一句，让用户自行判断是否适合再发 |
 | **无叠加** | — | 不必提 |
 
-> 贴片可能贯穿全场且与切片主题无关，也可能包含会过期的价格或日期；交付时按实际画面如实告知。
+> 贴片可能贯穿全场且与切片主题无关，也可能包含会过期的价格或日期；交付时按实际画面如实告知。
 
 **这一节不含任何去除动作。** 用户问「能不能去掉」→ 告诉他这超出本图纸射程，可在客户端二次编辑时自行处理。
 
@@ -158,9 +163,9 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 - **格式**：B站式 `.xml` 是 `<d p="秒数,…">用户:文本</d>`，**`p` 首字段即距开播秒数 = 源片时码**；平台导出 `.txt` 通常是时钟列。归一化成「秒 + 文本 + 用户」三元组即可。
 - **两个信号**：**复述密度**（同一句话被多个用户在短窗口内重复——观众自发复述的往往就是金句）、**刷屏密度**（互动符号瞬时峰值）。
 
-### ⚠️ 别高估它：弹幕对「选哪些段」通常只是辅助
+### ⚠️ 别高估它：弹幕对「选哪些段」通常只是辅助
 
-**结论**：弹幕主要用于验证选段、提取观众原句标题和微调边界，不是必需输入：
+**结论**：弹幕主要用于验证选段、提取观众原句标题和微调边界，不是必需输入：
 
 - ❌ **不要**为了「更准地选段」去要用户补弹幕（没有就没有，主干照跑）
 - ✅ 它真正剩下的价值是 **取候选标题原句**：观众自发复述出来的那句话（如「大脑不接受否定」被 15 人复述），
@@ -180,9 +185,53 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 看板点名的三件，都不碰源片：
 
 - **标题钩子**：文本建议。有弹幕时优先取观众复述的原句。
-- **字幕**：`--subtitle-out` 已产独立 `.srt`，交用户在客户端决定烧不烧。
+- **字幕**：见下「字幕上轨」——选题确认后对入选 clip **缺省做**。
+- **模糊底**：见下「模糊底」——源片与画布横竖不一致时，对入选 clip **缺省做**。
 - **封面**：走 `/gtrk-cover`（另出图，不改片）。
 
+### 字幕上轨（缺省做，只对入选 clip）
+
+选题清单敲定之后，对**每条入选 clip** 跑一次（用户明确说不要字幕才跳过；没入选的不做）：
+
+```bash
+gtrk subtitle lay --gtrk "<产物根>/clip{i}/gtrk/<该 clip 的 .gtrk>" --transcript "<产物根>/json/transcript.json" --language <该段提交时的源语种>
+```
+
+- `json/transcript.json` 是该段任务落下的**整片**转写，一份服务该段全部 clip；分了几段就各用各段产物根里的那份。
+- `--language` 跟该段 `gtrk long2short` 的 `--language` 一致（英文直播就 `en-US`），否则云端会按中文断句。
+- 交付时说清三件事：① 字幕在**客户端字幕轨**上，可换样式、可整轨删，不烧进画面；② 云端产出的剪映 / PR 工程是在上字幕**之前**生成的，**不含**这条字幕轨，要带字幕的剪映草稿请从客户端导出；③ 用了 `--subtitle-file` 的段，字幕按行出现、词级时间是近似值（`clips.md` 会提示）。
+- 该段产物根里**没有** `json/transcript.json`（老服务端或下载失败，CLI 日志会说）：如实告诉用户这一段没法自动上字幕，其余段照常。**MUST NOT** 拿弹幕或别的文本凑一份当字幕来源（见 §六 红线）。
+
+### 模糊底（横竖互转时缺省做，只对入选 clip）
+
+横屏直播切成竖屏（缺省 9:16）时，粗剪工程上下是黑边。选题清单敲定之后，对每条**入选** clip 判断源片朝向与该段画布朝向：
+
+- 源片几何：该段 `gtrk long2short` 日志里的源分辨率，或 `ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 "<源片>"`；
+- 画布：该段提交时的 `--output-size`（没传就是 9:16 竖屏）。
+
+**朝向不一致**（横屏源进竖屏画布，或反之）⇒ 缺省跑（用户说要保持黑边才跳过）：
+
+```bash
+gtrk project background --gtrk "<产物根>/clip{i}/gtrk/<该 clip 的 .gtrk>" --blur
+```
+
+**朝向一致**（竖屏直播进竖屏画布）⇒ **不跑**。
+
+交付时说清：模糊底是**客户端画布设置**（主轨画面的模糊副本垫在底下），在客户端设置里可改回黑底；剪映 / PR 工程与本地 `gtrk render` **不带**模糊底。强度缺省 200，用户嫌太虚或不够虚可加 `--intensity <0–1000>` 重跑（幂等覆盖）。零计费、不访问云端。
+
+### 运镜（仅当开工⑤用户要了才做）
+
+⑤答「要」⇒ 逐段提交都带 `--camera-move`（细项如幅度、概率不另开旗标，确有需要走 `--params-json '{"camera_move":{"enable":true,"amplitude":0.1}}'`）。云端按与精剪同一套调度给主轨片段写推 / 拉镜头关键帧，零渲染、不加价。
+
+交付时说清：
+- 运镜写在工程里：**客户端与剪映**打开可见、可在关键帧面板改或删；**本地 `gtrk render` 与 PR 工程看不到运镜**（按静态画面出片），要成片带运镜请从客户端或剪映导出；
+- `clips.md` 每条的「运镜 N 处」是实际写入数，**0 处属正常**（按概率抽取）；有「未能加运镜的切片」小节就点名告知；
+- 之后用 `gtrk patch` 裁剪 / 切分带运镜的片段，关键帧会跟着调整，不用手改。
+
+### 调速（只在用户主动要求时）
+
+用户说「切片都加速到 1.2 倍」这类话时，逐段提交带 `--speed-factor 1.2`（范围 `0.5–2.0`，保音高）。倍率写进逐 clip 工程，客户端 / 剪映 / PR 打开都按倍率播放，可在客户端逐条改回；交付时把这句告诉用户，`clips.md` 里若有「未能变速的切片」小节就点名告知。用户没提就**全程不加、不追问**；要超出 `0.5–2.0` 的倍率，告诉他在客户端对具体片段拖边变速。
+
 ### MG 动画（仅当开工④用户要了才做）
 
 - **时机**：选题清单敲定**之后**、只对**入选** clip 做——没入选的切片不白做颗粒。
@@ -200,18 +249,18 @@ gtrk oralcut-result <task_id> --out <目录>   # task_id 在产物根 task.json
 ## 八、计费与预算速查（跑前转述给用户）
 
 - 计费基 = **上传物音频流时长**（≈源片时长），**2 积分/分钟**。
-- **分段不改总量**：切段总时长≈原片，所以分不分段花的钱差不多，分段买的是「能跑通」和「粒度更细的选题清单」。费用以实时价格和音频时长为准。
+- **分段不改总量**：切段总时长≈原片，所以分不分段花的钱差不多，分段买的是「能跑通」和「粒度更细的选题清单」。费用以实时价格和音频时长为准。
 - **建单期被拒是零计费的**（如超 2h 硬闸）——试探性提交不会烧钱，但会白传一个大文件。
-- **任务失败按服务端回执处理**；只有回执明确退款时才向用户说明可重跑。
+- **任务失败按服务端回执处理**；只有回执明确退款时才向用户说明可重跑。
 - 运行时 CLI 自动查实时价格并打印，**把提示原样转述**；长片先向用户确认再跑。
 
 ## 九、排错
 
-- **`超过最大重试次数`** → 这句是**通用兜底文案**；优先检查外部 ASR 查询接口状态。
+- **`超过最大重试次数`** → 这句是**通用兜底文案**；优先检查外部 ASR 查询接口状态。
   - **判据**：失败很快（1–2 分钟内就报，而正常 40 分钟段要跑 4–20 分钟）⇒ 卡在开头的转写阶段。
-  - **处置：先原样重跑一次**。若仍失败，说明故障可能不是瞬时的。
+  - **处置：先原样重跑一次**。若仍失败，说明故障可能不是瞬时的。
   - **重试仍失败时，别死磕同一段**：换个切点重切该时段（边界挪几分钟）、或先跑其他段把能出的先出了，
-    把这一段单独挂起问客服/换时间再试。**MUST NOT 反复重跑**——每次都会重新等待，是否退款以回执为准。
+    把这一段单独挂起问客服/换时间再试。**MUST NOT 反复重跑**——每次都会重新等待，是否退款以回执为准。
   - **别改参数、别一味切更短**——那会掩盖问题；先确认是不是 ASR 侧的事。
   - 分段跑的好处在这里体现：**只需处理失败的那一段**，其余段的成果不受影响。
 - **`6019 媒体时长无效或超过业务限制`** → 单次提交超服务端 2 小时硬闸。**分段**，别重试。

package/skills/gtrk-long2short/SKILL.md

@@ -22,7 +22,7 @@ description: 长剪短闭环——把一条长视频（课程/直播/播客/访
 > **⚠️ 开工再问一句：素材是不是多人同框（对谈 / 访谈 / 多人直播）？** 与 `/gtrk-tools` 精剪同一问、同一措辞，
 > 和上一问**一起问、一次答完**，MUST NOT 代猜。
 > 答「是」⇒ 带 `--split-screen`，**并在同一句里告知**：本地会改传一份压过的 720p 代理（否则只传抽出的音频、
-> 毛片不出本地），处理时间明显变长；分屏素材落毛片旁 `split_screen/`。
+> 毛片不出本地），处理时间明显变长；分屏素材落毛片旁 `split_screen/`。
 > 答「否 / 不确定」⇒ 不带（「不确定」按「否」）。分屏是点缀：单段最长 8 秒、每条最多 3 处，落在子轨、
 > 不合心意在客户端隐藏该段即回退原片。
 
@@ -58,6 +58,8 @@ gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-o
 | `--subtitle-file <path>` | **现成单语字幕**（.srt/.ass）作转写来源，替代云端 ASR（用户手里有片源字幕/人工校对稿时用，省一次识别）。切点精度降为**字幕行边界**；双语/多层 .ass 会被拒；与 stt 类参数互斥 |
 | `--subtitle-out` | 逐 clip 另产**单语 .srt 字幕**（按目标画布档位智能拆行：横屏约 20 字/行、竖屏约 13 字/行），落 `clip{i}/srt/` |
 | `--keep-punctuation` | 字幕保留全部标点。缺省按统一口径去标点：逗号句号→空格、`？！` 等保留 |
+| `--speed-factor <n>` | 整体调速 `0.5–2.0`（保音高）。倍率**写进逐 clip 工程**（每个片段带 `speed`），客户端 / 剪映 / PR 都按倍率播放、可在客户端改回；云端不渲染、不加价。**只在用户主动要求时加**；更高倍率请在客户端对具体片段拖边变速 |
+| `--camera-move` | 运镜：云端按与精剪同一套调度给主轨片段写推 / 拉镜头关键帧（概率抽取、推拉交替、幅度克制），零渲染、不加价。客户端与剪映可见可改；本地 `gtrk render` 与 PR 工程不呈现。**缺省不加**，直播切片图纸开工会问；细项走 `--params-json` |
 | `--output-size <s>` | 画布 `9:16|16:9|1:1` 或 `WxH`（缺省 9:16 竖版） |
 | `-f, --formats <list>` | 三方格式，缺省 `gtrk,jianying,xml`（云端逐 clip 直产；gtrk 恒有） |
 | `--jianying-draft-dir <dir>` | 剪映草稿根（或 `auto`）；各 clip 草稿落 `<草稿根>/<产物根名>_clip{i}` |
@@ -71,11 +73,17 @@ gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-o
   切段用流拷贝、秒级完成、不重编码：`ffmpeg -ss 0 -t 2400 -i "<源片>" -c copy "<源片名>_seg01.mp4"`。
   各段产出的 clip 事后汇总成一张选题清单即可。**分段是常态动作，不是降级方案**。
 - 云端处理时长随片长涨（ASR+选段），CLI 轮询墙钟 60 分钟；超时不丢——产物根 `task.json` 里有 `task_id` 可恢复。
-  40 分钟/段是稳妥起步值；若分屏段仍接近墙钟上限，再继续缩短分段。
+  40 分钟/段是稳妥起步值；若分屏段仍接近墙钟上限，再继续缩短分段。
 
 ## 产物（跑完把这些讲给用户）
 
 - 产物根 `<毛片名>-long2short/`：`report.json`（选段报告）+ `result.json` + 逐 clip 子目录 `clip0/ clip1/ …`（各含 `gtrk/` 客户端工程、`jianying/` 草稿、`xml/` PR 工程；开了 `--subtitle-out` 另有 `srt/clip{i}.srt` 单语字幕）。
+- 产物根 `json/transcript.json`：**整片**源时基转写（一份服务全部 clip）。要给某条 clip 上客户端字幕轨（可换样式、可整轨删、不烧进画面）：
+  `gtrk subtitle lay --gtrk <产物根>/clip{i}/gtrk/clip{i}_project.gtrk --transcript <产物根>/json/transcript.json --language <源语种>`
+  （clip 工程文件名以 `clip{i}/gtrk/` 下实际文件为准）。上完字幕的是**客户端工程**；云端早先产出的剪映 / PR 工程不含这条字幕轨，要带字幕的剪映草稿请从客户端导出。老服务端没有这份文件时，CLI 会提示「无法自动上字幕」。
+- 横屏源进竖屏画布（缺省 9:16）时工程上下是黑边；要模糊底：`gtrk project background --gtrk <产物根>/clip{i}/gtrk/clip{i}_project.gtrk --blur`（客户端画布设置，可在设置里改回黑底；剪映 / PR 与本地渲染不带；零计费）。
+- 用了 `--camera-move` 时：`clips.md` 每条时长后标「运镜 N 处」（0 处属正常）；若有 clip 未能加运镜，`clips.md` 会单列「未能加运镜的切片」；告诉用户运镜在客户端 / 剪映里看，本地渲染与 PR 看不到。之后用 `gtrk patch` 裁剪 / 切分带运镜的片段，关键帧会跟着调整。
+- 用了 `--speed-factor` 时：`clips.md` 的时长是**变速后**的时长并标注倍率；若有 clip 未能变速，`clips.md` 会单列「未能变速的切片」，如实告诉用户。
 - **先看 `clips.md`**（产物根，人读总览）：一张表列全部切片的标题/时长/评分/一句话简介 —— 用它给用户复述「出了哪几条、各讲什么、建议先精修哪条」，别让用户自己开工程猜。逐条的入选理由、跳剪说明、高光词在 `clip{i}/clip.md`。
 - 开了 `--split-screen` 时：**分屏素材落在毛片旁的 `split_screen/` 子目录**（工程素材路径指向那里，别移动/删除，移动了工程会缺素材）——这点要提前告知用户。
 - 剪映草稿已拷入草稿根（给了 `--jianying-draft-dir` 时），剪映里直接可见 `<产物根名>_clip{i}`。**判据**：草稿目录里必须是 `draft_content.json` + `draft_meta_info.json` 两个精确文件名（云端产物侧的 `clip{i}_` 前缀在拷进草稿根这一跳被剥掉，产物目录 `clip{i}/jianying/` 里保留带前缀的归档原名）。CLI 日志按实际齐全条数报「N/M 条两件套齐全」，不齐的记进 `result.json` 的 `errors`、该 clip 的 `jianyingDraftPath` 为 `null`。

package/skills/gtrk-matrix/SKILL.md

@@ -24,6 +24,24 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 
 ## 配方库 v1（起手式，可变奏可自创）
 
+### 当前 Agent 的审片路径（本地素材优先）
+
+视觉理解优先由用户当前会话的 Agent 完成。CLI 不启动另一个 Agent；“本地”指编排位置，不保证当前 Agent 的模型在离线设备运行。
+
+1. **概览**：按素材时间顺序查看带时码的抽帧与照片；长场景也保留多个观察位置。结合 `gtrk transcript` 的原声转写整理事件、人物、环境和待核实之处，不从文件名猜内容。
+2. **细查**：脚本要求某个动作或情绪时，对相关素材用 `describe --materials <视频> --source-window <起秒,止秒> --prepare <工程目录/审阅目录>` 加密取帧；通过当前视觉工具检查过程。有音频依赖时回看/听对应原声，不以一张图证明完整动作。
+3. **回传**：查看任务中的实际图片后填写 `visual-review.json`，以相同输入参数加 `--review <回执路径>` 导入。全部本地完成时零豆包调用；不能看图或无法完成的单项标 `unavailable` 并说明原因，只有这些项由豆包补齐。不得把未查看项批量写成完成，也不得仅因省事直接调用豆包。
+4. **编排**：从已观察证据中按脚本意图选择片段。按脚本语义选材，本手册不调用视频高光算法；该增强仅由 Vlog 图纸按需编排。看片范围、未确认事实和原声覆盖均如实记录。
+
+```bash
+gtrk matrix describe --materials <本地视频或图片> --prepare <工程目录/visual-overview> --json
+# 当前 Agent 使用自身视觉工具查看 visual-job.json 列出的图片，填写 visual-review.json
+gtrk matrix describe --materials <同一素材> --review <工程目录/visual-overview/visual-review.json> --yes --json
+# 检索后的候选同理：--plan <plan.json> --prepare <目录>，回传时保持同一 --top-k 与 --highlight-rubric
+```
+
+准备和导入是 Agent 的内部工具接力，不要求用户逐帧填表。确实没有视觉能力时，可以直接用既有豆包 `describe`，报告回退原因。远端 URL 候选尚不支持本地交接，沿用豆包通道。`--plan` 仍只看每候选 `segments[0].best` 帧，动作细查走明确的 `--materials --source-window`；不能把候选描述当作整条视频都已审过。
+
 > 配方前置都一样：能跑 `gtrk` CLI；本地素材类配方先 `gtrk matrix index --dirs <素材夹>` 建索引。每条命令都带 `--json`。
 > ⚠️ **路径里有英文半角逗号**（`Bears, Salmon and Adventure` 这种）时 `--dirs` / `--materials` MUST **重复传**（`--dirs "A" --dirs "B"`，累加不覆盖），别塞进一串里 —— 缺省按半角逗号分隔。整串在盘上存在时会自动不拆，中文全角「，」从不参与拆分。
 
@@ -52,7 +70,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 - **变奏点**：`--top-k` 控理解成本（1 积分/张，只理解你会认真考虑的那几条）；云端 plan 同样可 describe（帧从签名 url 现抽）；理解产物有本地缓存，反复迭代不重复扣费。
 - **裁定要点**：`usable_flags` 是信号不是判决——结合 `desc` 复核（水印在角落的航拍也许仍可用）；剔除动作=从 plan 删掉那条 result，CLI 不会替你剔。
   另读 describe 输出的**剔除风险**清单：候选数 ≤1 的 beat 一删就掏空（音频驱动 ⇒ 整段黑屏或跨 beat 借片；口播 ⇒ 露 A-roll）。先补素材再剔，MUST NOT 见 flag 就删。
-  该清单只是判据，剔不剔仍归你（铁律①「零件不裁定」，见 §四层架构与三条铁律）。
+  该清单只是判据，剔不剔仍归你（铁律①「零件不裁定」，见 §四层架构与三条铁律）。
 
 ### 配方 C · 时间窗匹配（电影解说式）
 
@@ -139,7 +157,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 | 填充门槛 | `--score-floor <f>` | 浮点 0–1 · `0.2` | 低于不采纳、槽位留空露黑底；调完必看空洞告警 |
 | 切点对齐字幕句 | `--cut-align <r>` | 浮点 0–1 · `0.7`（`0`=关闭） | 三七开拍板：约七成字幕句起点恰逢镜头切点、三成有意错开；句级时码取 transcript 重投影（降级自动回旧节奏并告警）；开启时结果 JSON `lay.cut_align` 报实测比例 |
 | 主轨空洞填充 | `--gap-fill <m>` | `fast` \| `solid`（默认）\| `none` | **仅音频驱动工程主轨**（口播工程不适用零回归）：fast=放宽地板随便填候选→延长相邻颗粒→**跨 beat 借候选**→**次地板补真画面**→仍不够才黑片；借来的画面与本段稿子相关性弱、次地板槽是不到 1.2s 的快切，两者都会在日志里**指名报出**（`kind` 为 `borrowed` / `subfloor`）——那是如实告知，**不是缺陷，别当 bug 上报**；solid=黑片垫齐（精修一眼看出没匹配到）；none=留 gap（客户端主轨磁吸会吸除 gap 致画面与配音错位，慎用）；生效时结果 JSON `lay.gap_fill` 报明细 |
-| 编排交给云端跑 | `--arrange <m>` | **按素材来源自动定档，一般不用传** | 铺**自己电脑里的素材**→`cloud`（编排在服务端，按编排量计费）；铺**素材矩阵的素材**→`local`（编排仍在本机、不计费，逐字不动）。`shadow`=本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` **不受理**；云端拿不到产物时**直接报错**，不会换算法把活干完。⚠️ **它不是省钱开关**——矩阵素材要付检索费，两条路都花钱、只是花在不同环节，MUST NOT 对用户说「用本地就不花钱」 |
+| 编排交给云端跑 | `--arrange <m>` | **按素材来源自动定档，一般不用传** | 铺**自己电脑里的素材**→`cloud`（编排在服务端，按编排量计费）；铺**素材矩阵的素材**→`local`（编排仍在本机、不计费，逐字不动）。`shadow`=本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` **不受理**；云端拿不到产物时**直接报错**，不会换算法把活干完。⚠️ **它不是省钱开关**——矩阵素材要付检索费，两条路都花钱、只是花在不同环节，MUST NOT 对用户说「用本地就不花钱」 |
 | 落轨前先质检画音对齐 | `--arrange-qc` | 开关 · 缺省关 | 只查各 beat 的**卡点句**（span.from 领衔句）：画面没给到稿句说的东西就换候选重排，最多 2 轮，到限即交付 + 如实登记残余。零渲染。⚠️ 按帧计费（每卡点句 1 帧/轮），跑前报预估求确认。**默认关，用户没说就别带**。拿不到卡点句（无 dispatch / 重投影降级）时会明说「跳过 ≠ 查过」，别把那条日志读成通过 |
 | 云端编排本次上限 | `--arrange-cost-cap <n>` | 正整数 · 不限 | 超限服务端**前置拒绝**、零执行零计费（不是跑一半掐断）。只在 `--arrange shadow\|cloud` 时有意义 |
 | 先估价再决定跑不跑 | `--arrange-estimate-only` | 开关 · 缺省关 | 走到云端编排的计价确认那一步就停：报出编排量后**成功**返回（`ok:true` + `estimateOnly:true`，不是「被拒绝」），零云端调用、工程零改动。机读值在 `lay.arrange.units` 与 `lay.arrange.scale`。⚠️ 它省的是**云端那一次调用与其计费**（及其后的下载落轨），不是整条链——工程/plan/重投影照样要走。素材矩阵路会报 `applicable:false` 而**不是 0**。与 `--yes` 同给时以它为准 |
@@ -196,7 +214,7 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 > **`false` MUST NOT 读作「无版权、可以随便用」——它恰恰相反。** 决定性反证：概念素材（他人版权物）
 > 入库时固定写 `is_copyright=0`；字段若真是「是否受版权保护」，那批必须是 1。
 >
-> **选材口径按档位分流**：
+> **选材口径按档位分流**：
 >
 > - **internal 矩阵成员口：缺省搜全库，MUST NOT 自设一道命令面并不存在的闸。** 命令面缺省本就是
 >   `copyright_scope=all`，你 **MUST NOT 默认写上 `--commercial-only`**，也 MUST NOT 以「保险起见」
@@ -221,11 +239,11 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 |---|---|---|---|
 | 给素材夹建索引 | `gtrk matrix index --dirs <a,b,...>` | 逗号分隔**目录或素材文件** · — | 免切片只记时间戳；指纹增量零重算；断点续传 |
 | 本地检索模式 | `--local` | 开关 · 关 | 必配 `--dirs`；跳过身份探针、不触云端检索端点；与 `--column`/`--material-class` 互斥 |
-| 圈定检索域 | `--dirs <a,b,...>` | 逗号分隔**目录或素材文件** · — | 检索域永远显式可见；绝不与云端结果混合。**传文件即把域收窄到该素材**——一稿对一片时钉到那一部片，避免同夹邻片抢候选 |
+| 圈定检索域 | `--dirs <a,b,...>` | 逗号分隔**目录或素材文件** · — | 检索域永远显式可见；绝不与云端结果混合。**传文件即把域收窄到该素材**——一稿对一片时钉到那一部片，避免同夹邻片抢候选 |
 | **源时间窗过滤** | `--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）不清**。需要补齐切点、倍帧判定或段级运动量信号时使用；这些索引信号只在重建时落库 |
+| 固定机位判稳阈值 | `--stability-threshold <f>` | 浮点 (0,1) · `0.05` | 仅 index：场景内最大帧间变化低于此值判 stable，抽帧按**不超过六秒的间隔覆盖整个场景**；summary 分列 stable/unstable 场景数与省帧数；误判 stable 丢检索粒度、误判 unstable 只是不省钱——**宁严勿松**；默认为保守值待标定 |
+| 索引强制重建 | `--rebuild` | 开关 · 关 | 忽略指纹全部重算向量；**理解缓存（describes）不清**。需要补齐切点、倍帧判定或段级运动量信号时使用；这些索引信号只在重建时落库 |
 | 不要图片候选 | `--no-image-broll` | 开关 · 默认参与 | 检索与铺轨完全排除图片（零图片上云）；pinned 也不豁免这条 |
 | 跳过计费确认 | `--yes` | 开关 · 关 | 图片运镜 / describe >20 张两处护栏通用 |
 
@@ -242,8 +260,8 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 
 **⚠️ 一条 describe 只代表一段，不代表整条候选**（`--plan` 形态）：每个候选**只抽一帧**（`segments[0]` 的 `best`），这条判决的有效射程就是**那一帧所属的那一个 segment**。`at_sec` 就是那一帧的时刻（**素材时基**秒，与 `segments[].best` 同轴——注意与 `beats[].anchors[].at_sec` 的**工程轴**秒同名不同轴，别换算）。缺这个字段的旧 plan 按 `segments[0]` 推定，**不外推到全部段**。
 
-- 命令跑完会报告「理解覆盖率：N 帧 / M 段 = X%」（`--json` 读 `describe_coverage`），**M 是段数不是候选数**——别把「注入 N 条 result.describe」读成「这 N 条候选都看过了」。
-- 量级示例：843 个候选中只有 32 段被抽帧理解时，覆盖率是 3.8%；覆盖率低时必须按段说明射程，不能外推到整条素材。
+- 命令跑完会报告「理解覆盖率：N 帧 / M 段 = X%」（`--json` 读 `describe_coverage`），**M 是段数不是候选数**——别把「注入 N 条 result.describe」读成「这 N 条候选都看过了」。
+- 量级示例：843 个候选中只有 32 段被抽帧理解时，覆盖率是 3.8%；覆盖率低时必须按段说明射程，不能外推到整条素材。
 - 转述给用户时 MUST 按段说：「这条候选的 X–Y 秒那一段有字幕」，MUST NOT 说成「这条素材有字幕」。要判更多段就得多抽帧 = 多花钱（1 积分/张），是否加抽由用户拍板，CLI 不替他加。
 
 **plan 消费零件**（`gtrk matrix lay`）：
@@ -314,9 +332,9 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 - **段带运动量，据此换段（`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`）。判据看近零帧的连续长度而非占比，以区分倍帧运动段和静止镜头。
+- **倍帧素材（30fps 内容装进 60fps 容器）**：这类素材每隔一帧就是上一帧的复制。索引会认出来并落**有效帧率**（`motion.effective_fps`）。判据看近零帧的连续长度而非占比，以区分倍帧运动段和静止镜头。
   - 见到 `effective_fps` 明显低于容器帧率时，**如实告诉用户这条素材是倍帧的**（画面实际流畅度只有标称的一半，不是铺轨铺坏了）。
-  - 倍帧素材的切点判定在**去重后的帧序列**上进行：持续快摇作为连续高分串处理，真实切换仍按孤立尖峰保留。
+  - 倍帧素材的切点判定在**去重后的帧序列**上进行：持续快摇作为连续高分串处理，真实切换仍按孤立尖峰保留。
   - ⚠️ **存量索引里的假切点不会自己消失**：这条修法只在**重建索引**时生效。素材被判 `doubled` 且某段 `cuts` 密得离谱（零点几秒里十几刀）时，多半是本能力上线前建的库 ⇒ `gtrk matrix index --dirs <夹> --rebuild` 重建一次；重建前别把那些切点当真。
   - ⚠️ **一个已知取舍**：倍帧区里**紧挨着**的两刀（去重后相邻）会被判成持续运动而漏掉。它们在信号上与「快摇的头两帧」不可分——宁可漏这一对，也好过把十几个假切点放进去。
 - 含本地 B-roll 的工程云渲会被提交口直接拒绝（`local_broll_cloud_render_rejected`）——走客户端本地出片或 `gtrk render`。
@@ -352,8 +370,8 @@ description: B-roll 检索铺轨编排手册——成片管线里第一个铺的
 
 ## 执行（每次都带 `--json`）
 
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：交付物只写入工程目录或用户显式指定的输出路径；引用媒体用原路径，不复制到 agent 工作目录；不交付的临时文件放系统 temp，用完即删。
-> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：交付物只写入工程目录或用户显式指定的输出路径；引用媒体用原路径，不复制到 agent 工作目录；不交付的临时文件放系统 temp，用完即删。
+> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
 
 ```bash
 gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-k K] [--column <id>] --json