@gitruck/cli 1.3.0 → 1.3.3

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
@@ -302,6 +306,19 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 > ⚠️ A gap cannot be addressed with `--clip ""`: the contract lets multiple gaps share that value, so it is
 > not an address. Use `--track/--at` instead.
 
+### `gtrk matrix source-import` — Put selected video URLs into a B-roll beat
+
+When the source videos are already known, send them directly to one beat instead of running keyword search:
+
+```bash
+gtrk matrix source-import --project <project-dir> --beat B07 --url <video-url> --url <another-url> --json
+gtrk matrix source-import --project <project-dir> --beat B07 --urls links.txt --json
+```
+
+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.
+
 ### `gtrk matrix` — B-roll retrieval + candidate track laying
 
 **No positional argument = consume the dispatch**: reads the `film_broll` queue from `split/dispatch.json` → dual-endpoint retrieval → produces the candidate list `split/broll-plan.json`, downloads preview proxies, and lays N candidate tracks in the project (open it in opencut and toggle track visibility to compare and choose). **`matrix search "<query>"` = a one-off ad-hoc search** (independent of any dispatch). **`matrix fetch <clip_id...>` = pull raw footage during the fine cut** (project-independent; see below).
@@ -437,6 +454,27 @@ Project entry points that start from **a voice-over** instead of a talking-head
 
 `project init` also takes `--canvas <WxH>` (default 1080x1920), `-o/--out`, `--reupload`, `--no-open` and `--json` with the same semantics as `oralcut`; with `--json` both commands emit a single-line result JSON on stdout (human logs go to stderr).
 
+### `gtrk project export` — export a refined project
+
+Exports an already refined `.gtrk` project (after `matrix lay` / `mg` / `audio lay`) to Jianying, Premiere XML, FCPXML or OTIO without rewriting the source project. The default output directory is `export-<YYMMDD-HHMMSS>/` under the project directory.
+
+```bash
+gtrk project export --project <project-dir>
+gtrk project export --gtrk <project-file> --formats jianying,xml --out <output-dir>
+```
+
+| Option | Purpose |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | Locate the standard `gtrk/project.gtrk`, or explicitly select a project file; use one of the two |
+| `-f, --formats <list>` | `xml`, `fcpxml`, `otio`, `jianying`, `capcut`, `gtrk`; default `jianying,xml`; legacy fine-grained names are also accepted |
+| `--jianying-draft-dir <dir>` | Jianying/CapCut draft root; when omitted, use user config and standard locations |
+| `--no-particles` | Skip MG particle pre-rendering while continuing structural export; skipped particles are recorded in the result |
+| `--particle-concurrency <n>` | Particle qtrle pre-render concurrency, 1–8, default 6 |
+
+There are two billing surfaces: structural project export is billed per task, while unique particles missing from `.tonghe-cache/particles/` are billed per minute. `gtrk project init` remains zero-credit; that does not apply to `export`. Particle cache keys and the client implementation are byte-compatible, so particles rendered by the client can be reused.
+
+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.
+
 > **`--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.
 
 
@@ -593,3 +631,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,4 +1,16 @@
-# Agent、配置与命令参考
+# 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)
 
@@ -279,7 +291,8 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--to <sec\|Nf>` | `move` 的落点 | — |
 | `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | `trim` 的五种语义（前两个相对、中两个绝对、`--slip` 只换源窗） | — |
 | `--cut <sec\|Nf>` | `split` 的切点。⚠️ 与寻址用的 `--at` 是两个参数 | — |
-| `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
+| `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
+| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨 | — |
 | `--total <sec\|Nf\|max>` | `set` 的顶层总长（工程级 op，与元素寻址互斥） | — |
 | `--ops <file\|->` | 批量事务：一次读、全算、全校验、一次写；任一条失败**零写** | 关 |
 | `--dry-run` | 只算与校验、不写文件 | 关 |
@@ -292,6 +305,19 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 >
 > ⚠️ 空档（gap）不能用 `--clip ""` 寻址：契约允许多个 gap 共享该取值，它不构成地址；用 `--track/--at`。
 
+### `gtrk matrix source-import` — 指定视频链接进入某个 B-roll beat
+
+当你已经选定视频链接，不需要关键词检索时，可以把它们直接送进指定 beat：
+
+```bash
+gtrk matrix source-import --project <工程目录> --beat B07 --url <视频链接> --url <另一个链接> --json
+gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt --json
+```
+
+`--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`，由云端下载高清窗口并置换当前低清素材。`更多外网候选` 只对关键词检索任务分页，不会把指定来源任务重复当作搜索结果。
+
 ### `gtrk matrix` — B-roll 检索 + 候选铺轨
 
 **无 positional = 派单消费**：读 `split/dispatch.json` 的 `film_broll` 队列 → 双口检索 → 产候选清单 `split/broll-plan.json` + 下载 preview 代理、在工程里平铺 N 条候选轨（opencut 打开即可用轨道小眼睛对比挑选）。**`matrix search "<query>"` = 单条 ad-hoc 检索**（不依赖派单）。**`matrix fetch <clip_id...>` = 精剪期拉原片**（脱离工程，见下）。
@@ -460,6 +486,27 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 
 `project init` 另有 `--canvas <WxH>`（默认 1080x1920）、`-o/--out`、`--reupload`、`--no-open`、`--json`，语义与 `oralcut` 一致；两命令 `--json` 恒出单行结果 JSON（人读日志走 stderr）。
 
+### `gtrk project export` — 精修工程导出
+
+把已经经过 `matrix lay` / `mg` / `audio lay` 精修的 `.gtrk` 只读导出为剪映、Premiere XML、FCPXML 或 OTIO。源工程不会被改写；缺省产物目录为工程目录下的 `export-<YYMMDD-HHMMSS>/`。
+
+```bash
+gtrk project export --project <工程目录>
+gtrk project export --gtrk <工程文件> --formats jianying,xml --out <产物目录>
+```
+
+| 参数 | 作用 |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | 自动定位标准布局的 `gtrk/project.gtrk`，或显式指定工程文件，二选一 |
+| `-f, --formats <list>` | `xml`、`fcpxml`、`otio`、`jianying`、`capcut`、`gtrk`；缺省 `jianying,xml`，也兼容旧细粒度格式名 |
+| `--jianying-draft-dir <dir>` | 剪映/CapCut 草稿根；省略时按用户配置与标准位置探测 |
+| `--no-particles` | 不预渲 MG 颗粒；结构导出仍继续，结果会记录被跳过的颗粒 |
+| `--particle-concurrency <n>` | 颗粒 qtrle 预渲并发数，1–8，默认 6 |
+
+本命令有两个计费面：工程结构导出按次计费；未命中本地 `.tonghe-cache/particles/` 的唯一颗粒按分钟计费。`gtrk project init` 仍是 0 积分，不能把这个结论套到 `export`。颗粒缓存键与客户端逐字节同构，客户端烤过的颗粒可直接复用。
+
+颗粒预渲前会先完成 HTML、路径和缓存预检；预检失败不会提交任何云任务。单颗粒渲染或下载失败会记录在 `result.json`，其余格式继续导出。`--json` 输出单行结果 JSON，人读日志走 stderr。
+
 > **`--beat-align`**：按表格中的高潮点锚定规则工作；显式 `--climax` 会覆盖自动判据。该模式会调用 `audio_music_analyze` 并产生相应计费。
 
 
@@ -627,3 +674,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.0",
+	"version": "1.3.3",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",

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

package/skills/gtrk-tools/SKILL.md

@@ -28,6 +28,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `video_purify` | 「清理我有权处理的视频水印 / 去字幕 / 只净化指定区域 / 只抹我圈的这块 / 只抹片头几秒的角标」 | 单条本地视频（仅处理你有权处理的素材）；可选范围、方式、归一化 ROI 和带时间段的区域框 | 一条净化视频 | 运行前实时查询 | 已上线 |
 | `video_upscale` | 「视频超分 / 低清视频放大 / 动漫视频变清晰」 | 单条本地视频（≤1 分钟）；倍数 `2` / `3` / `4`，类型 `Reality` / `Anime` | 一条超分视频 | 运行前实时查询 | 已上线 |
 | `video_interpolate` | 「视频补帧 / 提高帧率 / 让画面更流畅」 | 单条本地视频；倍数 `2` / `3` / `4`，不附加 1 分钟限制 | 一条插帧视频 | 运行前实时查询 | 已上线 |
+| `video_highlight` | 泛高光发现（视频高光算法）；明确脚本优先语义检索 | 本地视频，3秒以上、30分钟以内；只传224p/4fps无声代理 | 按请求分组的三秒候选，需 Agent 复核 | 未开放外部收费 | 内部验收候选 |
 | `video_segment` | 「机械分镜 / 按画面变动切分镜区间 / 场景切分」 | 单条本地视频；可选 `--detector content\|adaptive`、`--threshold` | 分镜区间结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
 | `video_ai_segment` | 「智能分镜 / 语义切镜头 / 按类目景别拆镜头」 | 单条本地视频；可选 `--segment-mode scene\|shot_type\|narrative\|subject` | 语义分镜结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
 | `video_motion_cut` | 「运镜高光 / 提取运镜片段 / 找高光镜头」 | 单条本地视频 | 运镜/高光片段结构 `result-output.json`（非下载文件） | 运行前实时查询 | 已上线 |
@@ -118,11 +119,11 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 
 ## 调用纪律（每次都照做）
 
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
-> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
 > 一切产物只落 `outDir`（缺省 = 输入同目录）或**用户显式指定的 `--out`**；
 > **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
-> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
+> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
 
 1. **先看清单、再对号**：用户的意图对到某个工具名（拿不准就 `gtrk tool list --json` 核对触发语与输入要求）。
 2. **执行前转述实时计费提示**：先读本次 `gtrk tool list --json` 的 `billingHint`/`pricing`，再把实时结果如实告诉用户；不得引用本文件或记忆中的旧价格。若显示价格暂不可用，就说明最终以服务端结算为准。
@@ -133,7 +134,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 7. **透传高级参数**：命令没为某个云端参数开 flag 时，用 `--param k=v`（可重复）或 `--params-json '<对象>'` 直接透传（如 `image_move` 想指定输出几何 `--param width=1080 --param height=1920`）。
 8. **单发单收、批量靠循环**：一次一份输入；用户要批处理就你逐个循环调。例外是多文件图片工具（`image_classic_template` / `image_vertical_stitch`）——它们的一份输入天然是一组图片（一次任务一次计费），传参顺序即拼装顺序，别把它当批处理。
 
-图片比例转换常用形态：`gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --json`。`--canvas-type` 只接受 `normal`、`rectangle`、`square`；省略画布参数时不替服务端写死默认值。
+图片比例转换常用形态：`gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --json`。`--canvas-type` 只接受 `normal`、`rectangle`、`square`；省略画布参数时不替服务端写死默认值。
 
 图转运镜可指定运镜方式：`gtrk tool image_move ./photo.jpg --motion zoom_in_center --json`。`--motion` 未传时云端自动选择（构图 + 主体识别 + 随机，同图重跑结果会变）；显式指定后同图同参重跑结果一致。合法值 26 个、分三组，用户说「往右推 / 拉远 / 从左往右扫」这类自然语言时按语义对号入座，对不上就问清，别瞎猜：
 
@@ -204,3 +205,17 @@ Agent 在任何去除处理之前 MUST 主动向用户说明两种模式，并
 **慢速失败、排队或暂不可用时，必须先告知原因及切换快速去除的效果代价，等用户同意后才能另建快速任务；严禁自行手搓本地 ffmpeg 交差。** 长片超出 raft 限制时先说明限制，讨论分段或改模式，不因时长自动降档。交付时写明实际模式与已知效果问题，不把 ffmpeg 结果描述为无痕修复。
 
 完整万级区域保存在文件，勿逐条读进模型上下文。保护框优先于去除框，新处理请求会先检查服务支持 review_protocol=2，否则在上传计费前停止。
+
+## 视频高光发现
+
+### 高光发现与失败兜底
+
+该工具只由 `gtrk-vlog-docu` 图纸按需调用，或响应用户明确的单点工具调用；其他成片图纸不自动启用。Vlog 在全批概览之后，需要探索动态看点时执行：
+
+```bash
+gtrk tool video_highlight "<本地视频>" --out "<工程目录>/highlight/<素材名>" --json
+```
+
+该入口当前仅供内部验收。只上传本地生成的224p/4fps无声代理，结果在 `result-output.json`。`groups` 各自的 `top3` 只代表该请求内的三秒候选；不可跨素材、跨分块混排分数。用 `matrix describe --materials <原片> --source-window <起秒,止秒> --prepare <目录>` 查看候选前后过程，再结合原声判定它能否进入脚本。不要用三秒评分推断整段事件完整性。已有明确脚本时优先语义检索，不自动调用视频高光算法，也不覆盖语义 best 或 VLM highlight。
+
+服务忙、冷却、超时、坏响应、无候选或接口未部署时，记录素材、任务号（若有）、失败原因和后续来源 `agent_semantic_overview`，继续从已观察素材按故事选材。视觉项当前 Agent 确实无法完成才标 `unavailable` 交豆包；两者都不可用则保留缺口，不写成已看过。纯粹请求“高光评分结果”时，原子失败就如实报告未完成。已有任务号优先查询原任务；提交状态未知时用同一素材、模型、输出目录恢复，不换身份盲目建单。

package/skills/gtrk-vlog-docu/SKILL.md

@@ -5,21 +5,49 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 
 # gtrk-vlog-docu（Vlog 纪实类 · 组合成片图纸）
 
+## 审片与脚本的实际工作顺序
+
+先建立全批素材概览，包含视频、照片和原声，再提出影响主线的关键问题。已有回答直接沿用，不重复问。不要先定故事，再只找支持它的几张画面。
+
+视觉部分沿用 `gtrk-matrix` 的当前 Agent 优先通路：`describe --materials ... --prepare <工程目录/visual-overview>` → 当前 Agent 按时码看图、记录事实与不确定项 → `--review <回执>` 导入。长场景多个观察点；动作、表情、剪辑入出点在相关窗口内加密查看。原声有内容时结合转写/试听；不能把抽帧概览称为完整看过原片。Agent 无视觉能力或单项无法完成时才由豆包补齐，注明回退原因。
+
+概览后组织可审阅的视听脚本：每段表达什么、采用哪条素材的哪个时间区间、保留什么同期声、哪里需要旁白、照片如何进入。交给用户审阅；有异议则多轮修改同一份脚本，认可后继续成片。照片可由既有图片运镜能力进入时间线，但不能虚构照片之外的事件。
+
+明确脚本的取材由语义与实际画面证据主导；泛高光发现只是探索素材的一种工具，其分数不能覆盖脚本意图。下方云端 describe 示例仅在当前 Agent 无法完成时直接使用；有视觉能力时先 prepare/review，交接由 Agent 完成，不让用户填逐帧表格。
+
 把**一批现场素材**变成**一条纪实成片工程**：素材理解 → 选档写稿 → 检查点①一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端出片。
 
 > **定位**：structure 级组合图纸，不新增命令，只编排既有原子零件。零件参数以各自 skill（`gtrk-transcript` / `gtrk-matrix` / `gtrk-splitter` / `gtrk-mg`）与 `--help` 为准，**本图纸引用不复制**；编排次序、检查点、配方参数以本图纸为准。**CLI 是手，你是脑。**
 >
-> **本体定性**：
-> **纪实 Vlog 是散文的载体——用有限的素材，把一个故事、或一个几个思想，最终串联起来。**
+> **本体定性**：
+> **纪实 Vlog 是散文的载体——用有限的素材，把一个故事、或一个几个思想，最终串联起来。**
 >
 > 三个推论，构成本图纸的全部决策原点：
-> - **形散神不散**：素材可以跳跃、场景可以断裂、时间可以不连续，但**必须有一根线**。没有那根线的片子叫「相册」不叫作品。
+> - **形散神不散**：素材可以跳跃、场景可以断裂、时间可以不连续，但**必须有一根线**。没有那根线的片子叫「相册」不叫作品。
 > - **素材有限是前提不是缺陷**：创作力体现在「用手上这些素材能串出什么」，不是「还差什么素材」。**先看素材里有什么，再决定串什么**——这是散文与说明文的分野。
 > - **先立神，再选材**：写稿的第一步不是排素材顺序，是找到那根线（§3.2）。顺序反了就会写成流水账。
 >
 > **表达形态上的定义性特征**：纪实类是**双声道交替**——现场同期声承载真实感与人格，后期旁白承载知识与升华。**同期声片段是内容本体，不是可替换的配画**。这是它区别于口播链与配音链的根本。
 >
-> ⚠️ **当前实现状态**：链路形态采用 **C 分段拼接** 与默认保留部分毛边，但 `gtrk project compose` 命令**尚未实现**。A/C 档在 compose 落地前不可跑；B 档可走配音链，「立神+选段+旁白稿」创作件可独立交付。用户要做时**MUST**先说明当前状态，细节见 `openspec/.plans/explore-vlog-docu-skill.md` §四之二。
+> **当前实现状态**：本地候选 CLI 已支持 `gtrk project compose`，按清单组装视频、图片和已合成旁白。先用 `gtrk project --help` 核对当前安装版本是否提供 compose；旧版不支持时停在图纸，不手写工程冒充链路。声音仍经检查点确认后生成。
+
+### 高光发现与失败兜底（仅本图纸使用）
+
+在全批概览之后，用户只说“挑高光”或某段值得探索但缺少明确事件线索时，按需执行：
+
+```bash
+gtrk tool video_highlight "<本地视频>" --out "<工程目录>/highlight/<素材名>" --json
+```
+
+该入口当前仅供内部验收。只上传本地生成的224p/4fps无声代理，结果在 `result-output.json`。`groups` 各自的 `top3` 只代表该请求内的三秒候选；不可跨素材、跨分块混排分数。用 `matrix describe --materials <原片> --source-window <起秒,止秒> --prepare <目录>` 查看候选前后过程，再结合原声判定它能否进入脚本。不要用三秒评分推断整段事件完整性。已有明确脚本时优先语义检索，不自动调用视频高光算法，也不覆盖语义 best 或 VLM highlight。
+
+服务忙、冷却、超时、坏响应、无候选或接口未部署时，记录素材、任务号（若有）、失败原因和后续来源 `agent_semantic_overview`，继续从已观察素材按故事选材。视觉项当前 Agent 确实无法完成才标 `unavailable` 交豆包；两者都不可用则保留缺口，不写成已看过。纯粹请求“高光评分结果”时，原子失败就如实报告未完成。已有任务号优先查询原任务；提交状态未知时用同一素材、输出目录恢复，不换身份盲目建单。
+
+### 脚本验收交付物
+
+在工程目录维护一份可持续修改的视听脚本，按顺序列出：段落目的、源素材、源入出点、预计片长、画面事实、同期声或环境声、旁白、照片运镜、证据覆盖与待核对项。素材时间轴与成片时间轴分列。旁白草稿不当作录音事实，未听清的同期声不编台词，文件名日期不自动当作真实行程日期。
+
+连同全批素材概览、采用/舍弃理由、高光调用与回退记录一起交付。先审这份完整图纸；用户认可后再合成旁白、组装工程和渲染。组装必须走 `project compose`，不能手写 `.gtrk`；图纸确认和成片验收分别记账。
 
 ## 一、输入契约与三档识别
 
@@ -46,7 +74,7 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 
 **判别动作**：`gtrk transcript` 抽听 1-2 条代表素材——转写出大量口语碎句、语气词、对话接话 → A 档；几乎无人声或只有环境音 → B 档；有对话但用户明显想表达观点 → C 档。**拿不准问用户一句**：「你是想让现场的声音说话，还是你来讲？」
 
-> **C 档适合需要升华观点的自制片**：以纪实同期声承载事件，中后程切入议论式旁白，把当天经历升华为观点与私人自白，落一句可摘录的态度句。有条件优先推 C。
+> **C 档适合需要升华观点的自制片**：以纪实同期声承载事件，中后程切入议论式旁白，把当天经历升华为观点与私人自白，落一句可摘录的态度句。有条件优先推 C。
 
 ## 二、全链总览（快速成片）
 
@@ -57,7 +85,7 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 ④ 写稿        只写定调层旁白（§三）→ 稿 + 标题 + HashTag
 ⑤ 检查点①    【必停】神 · 配比档 · 稿件 · 画幅 · 音色 · BGM · 字幕样式（§四）
 ⑥ 配音        gtrk tool audio_tts_clone（仅旁白段，★ 分段合成）
-⑦ 拼主轨      gtrk project compose（分段清单 → live 段引用原片区间 + narration 段落位）★ 待实现
+⑦ 拼主轨      gtrk project compose（分段清单 → live 段引用原片区间 + narration 段落位）
 ⑧ 拆分派单    gtrk split：live 段=A_ROLL/真人出镜|口播继续；narration 段=FILM_BROLL|MG/旁白主导
 ⑨ B-roll      matrix --local --dirs → describe → lay（只铺 narration 段空档）
 ⑩ 字幕层      吐槽/观察/进度/梗卡进 MG 派单（§六）→ mg lint → mg --project
@@ -66,7 +94,7 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 ⑬ 交付        客户端打开工程出片
 ```
 
-**快速成片的「免打扰」只覆盖 ⑥ 之后的执行环节**：①–⑤ 的立神访谈与检查点①**双模式都必须问**，MUST NOT 因为用户选了快速成片就跳过立神对话自行拍板——那是把创作者的片子做成 agent 的片子。用户要精修按 §七 逐步停。
+**快速成片的「免打扰」只覆盖 ⑥ 之后的执行环节**：①–⑤ 沿用已有创作意图，补问必要信息并保留检查点①，MUST NOT 因为用户选了快速成片就跳过立神对话自行拍板——那是把创作者的片子做成 agent 的片子。用户要精修按 §七 逐步停。
 
 ## 三、写稿规约
 
@@ -87,7 +115,7 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 
 纪实 Vlog 是散文的载体——**用有限的素材，把一个故事、或一个几个思想，串联起来**。「神」就是那根线。**没有神的片子是相册，不是作品。**
 
-**★ 立神是多轮访谈，不是单点拍板**：**神的所有权在创作者**——素材分析只能提名候选，真正的神往往在创作者的经历和冲动里。本 skill SHALL 围绕神与创作者做多次沟通和确认，问够为止；快速成片免打扰只覆盖执行环节（⑥以后）。
+**主线由创作者决定**：先利用已有回答和素材概览，只有仍影响主线的缺失信息才提问。用户已经讲清经历、重点和感受，或授权其余内容按素材编排时，直接写出可审阅脚本，不机械增加访谈轮数。多轮修改围绕同一份脚本进行，快速成片也保留脚本确认。
 
 **访谈协议（写稿前必做）**：
 
@@ -125,7 +153,7 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 - **要求**每一段都能回答「它为神做了什么」——是铺垫、是印证、是转折、还是留白？答不上来的段**砍掉**，哪怕画面好看；
 - **素材有限是前提不是缺陷**：不要为「素材不够」而注水或强行拉长。手上有什么，就串什么——这正是本类型的创作力所在。
 
-> ⚠️ **主要失败模式**：素材拍得不差却没有串成一条神，记录了一天的见闻，每段都成立，合起来仍像相册。它比文笔差、素材糙更致命。
+> ⚠️ **主要失败模式**：素材拍得不差却没有串成一条神，记录了一天的见闻，每段都成立，合起来仍像相册。它比文笔差、素材糙更致命。
 
 ### 3.3 纪实要素层（本类型专属）
 
@@ -146,9 +174,9 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 到场定位（口播或旁白一句）→ 背景科普（旁白）→ 现场体验（同期声，让开）→ 攻略数字（旁白/字卡）→ 转场（车程字卡）
 ```
 
-**攻略信息件标准化（收藏钩）**：凡有地点/消费属性，每站必报**车程 + 价格 + 免费与否 + 避坑**，缺一项就少一分收藏价值。数字进字卡比进旁白更好用。
+**攻略信息件标准化（收藏钩）**：凡有地点/消费属性，每站必报**车程 + 价格 + 免费与否 + 避坑**，缺一项就少一分收藏价值。数字进字卡比进旁白更好用。
 
-**Resonance 素材优先（有则必用、无则不硬造）**：用**坦白脆弱**（落榜、心碎、没钱、亲人离世）与**集体记忆锚点**（城市旧地标、经典电影、老游戏）建立共鸣。写稿前问用户一句：这趟有没有什么真话想说？有就放进升华段，**没有就老实做知识与快乐，不要编情绪**。
+**Resonance 素材优先（有则必用、无则不硬造）**：用**坦白脆弱**（落榜、心碎、没钱、亲人离世）与**集体记忆锚点**（城市旧地标、经典电影、老游戏）建立共鸣。写稿前问用户一句：这趟有没有什么真话想说？有就放进升华段，**没有就老实做知识与快乐，不要编情绪**。
 
 **态度金句是收尾硬指标**：升华段必须落一句**可摘录**的话（能被观众截图、能当评论区引用）。写完自问：这句话单独拎出来，有人愿意转发吗？
 
@@ -195,9 +223,13 @@ HKRR 四维（缺哪补哪）：
 
 ## 五、快速成片编排
 
-> **链路形态：C 分段拼接**——全片切 N 段，每段声明 `live`（同期声段，引用原片区间，**内容本体**）或 `narration`（旁白段，TTS + B-roll 空档），由 `gtrk project compose` 按序拼主轨。设计草案见探索工件 §四之二。
+> **链路形态：C 分段拼接**——全片切 N 段，每段声明 `live`（同期声段，引用原片区间，**内容本体**）或 `narration`（旁白段，TTS + B-roll 空档），由 `gtrk project compose` 按序拼主轨。设计草案见探索工件 §四之二。
 >
-> ⚠️ **`gtrk project compose` 尚未实现**。当前可跑的降级通道：**B 档（旁白主导）走配音链**（`project init`，同期声片段当带声 B-roll）。**A/C 档在 compose 落地前 MUST NOT 假装能跑**；可先交付「立神+选段+旁白稿」创作件。
+> compose 只引用本地文件：TTS 先合成落地，再以 narration 的 source 引用；需要旁白叠在已确认画面上时，用既有 `audio lay --offset` 另铺音轨。图片要运动，先用 image_move 产视频再入 live；image 段本身只显示静帧。
+
+分段旁白铺完后，使用 `gtrk patch set --clip <旁白片段ID> --audio-track <首条旁白轨的track_index> --project <工程目录>` 将同一讲述者的各段收进同一条旁白轨，保持原时间位置；同期声与 BGM 各自独立。重铺旁白后也要归轨，不能把“一段一轨”的阶梯布局作为交付。目标时间段已有片段时先检查重叠，不强行合并。
+
+大场景或活动转换处用简短 MG 交代叙事关系（如从游览转到参与体验），不按每个镜头机械加字卡，不杜撰日期/地点。手写 GSAP 颗粒须在 template 内先声明 gsap.min.js，再创建并注册 paused 时间线；静态 lint 通过不等于预览可见，交付前还应检查客户端播放环境内的入场与驻留。
 
 ```bash
 # ① 理解与定档（抽听 1-2 条代表素材；live 段的 in/out 时码后面全从这份转写里读）
@@ -212,15 +244,18 @@ gtrk tool audio_tts_clone --text-file <旁白段1.txt> --speaker <voice_id> --js
 gtrk tool audio_tts_clone --text-file <旁白段2.txt> --speaker <voice_id> --json
 #   ↑ 每段单独合成，compose 按段落位；同参重合成走缓存不重复扣费
 
-# ⑦ 拼主轨（★ 待实现：add-project-compose-command 落地后启用）
-# gtrk project compose --list <分段清单.json> --canvas 1920x1080 --json
-#   分段清单：agent 写语义（live: source+in/out+keep_rough / narration: tts_task），
-#   时间线时码全归 CLI（沿用 split 的「时码归 CLI」纪律）；
-#   live 段引用原片区间零切片零上传；narration 段留空档给 B-roll；
-#   产物含合并 transcript.json（live 句级时码按落位偏移 + TTS segments），下游零改造
-#
-#   ★ 毛边口径（拍板默认）：live 段 keep_rough=true——只剪长静默/明显重来/跑题闲聊，
-#     语气词与自然停顿保留（「嗯…那个…」是真实感的组成部分，MUST NOT 照口播链剪干净）
+# ⑦ 拼主轨（新目录；不覆盖既有精修工程）
+gtrk project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080 --json
+# 清单：{"version":1,"segments":[
+#   {"kind":"live","source":"原片.mp4","in":3,"out":11},
+#   {"kind":"narration","source":"旁白.wav","transcript":"旁白-transcript.json"},
+#   {"kind":"image","source":"合影.jpg","duration":4}
+# ]}
+# live 默认保留原声；keep_audio:false 才关闭。旁白段留画面空档给 B-roll。
+# 原片不上传；路径相对清单；in/out 单位秒。transcript 为源时基 st/ed/text 句表。
+# 毛边由选段保留；compose 不做静默删除或自动精剪。
+# 多源文稿逐句绑定素材，split/subtitle 根据当刻工程重投影。
+# 没提供 transcript 的素材不生成猜测字幕，跨切点整句会省略并报告。
 
 # ⑧ 拆分派单（★ 本类型的车道映射，词表无需扩展）
 gtrk split --project "<工程目录>" --json          # 投影拿句表
@@ -259,7 +294,7 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 
 ## 六、字幕层规约（本类型的第二解说轨）
 
-**字幕层不是被动烧字幕，而是承载人格与信息的第二条解说轨。** 无语音段可由它承接信息。四类字卡进 MG 派单：
+**字幕层不是被动烧字幕，而是承载人格与信息的第二条解说轨。** 无语音段可由它承接信息。四类字卡进 MG 派单：
 
 | 类 | 用途 | 样本形态 | 挂点 |
 |---|---|---|---|
@@ -310,9 +345,9 @@ gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --js
 
 ## 十、已知边界与排障
 
-- **`gtrk project compose` 的当前状态见顶部实现状态块**：A/C 档当前不可跑，B 档走配音链，「立神+选段+旁白稿」创作件可独立交付；
+- **`gtrk project compose` 的当前状态见顶部实现状态块**：核对本地版本，组装与图纸分别验收；未完成声音、字幕、运镜时不得称为完整成片；
 - **毛边口径已定（默认保留部分毛边）**：只剪长静默/明显重来/跑题闲聊，语气词与自然停顿保留——MUST NOT 照口播链标准剪干净；
-- **旁白盖住现场声**：铺完先在客户端听一遍交界处；
+- **旁白盖住现场声**：铺完先在客户端听一遍交界处；
 - **三源混音**（同期声/旁白/BGM）的响度平衡当前靠客户端手调，无自动 ducking；
 - 闪帧 / 拆分注释客户端不显示 / describe 的 `text_overlay` 撞原片字幕区 / `matrix lay` 拒铺（`tracks_edited`）/ BGM 曲长不足：同旅拍图纸口径。
 
@@ -327,4 +362,4 @@ gtrk patch move --project <dir> --clip <clip_id> --to 5.0
 gtrk patch trim --project <dir> --clip <clip_id> --out -1s
 ```
 
-**MUST NOT 直接编辑 `.gtrk` 的 JSON**：片段时码两套并存（`clip_st`+`clip_ed` 与 `clip_st`+`duration`），改一份不改另一份会造成客户端与后端读取不同出点。`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。
+**MUST NOT 直接编辑 `.gtrk` 的 JSON**：片段时码两套并存（`clip_st`+`clip_ed` 与 `clip_st`+`duration`），改一份不改另一份会造成客户端与后端读取不同出点。`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。