/gtrk-matrix

name: gtrk-matrix
description: B-roll 检索铺轨编排手册——成片管线里第一个铺的车道（SOP ③ B-roll 底轨阶段）。消费拆分派单的 FILM_BROLL 队列（`dispatch.film_broll`），检索素材并在工程里平铺 N 条候选 B-roll 轨，供用户在 opencut 里用轨道小眼睛切换对比、挑选/调整；确认后交棒同阶段的 AI 情景片段腿（`/gtrk-ai-drama`，车道非空时）。命令族还含：**本地素材模式**（`matrix index` 建索引、`--local` 用自己的素材铺轨，**视频本体不上云**，只送抽帧图；选中上轨的图片会上云转运镜，`--no-image-broll` 可排除）、**按需理解**（`matrix describe`，为排序提供画质与看点信号）、**源时间窗检索**（`--source-window`，电影解说式逐段推进）、**通用三态素材检索**（`matrix material`：clip/image/audio 整条素材下载向，BGM/配图主场）、**plan 可编辑通路**（agent 改 plan 后 `matrix lay` 消费）。当用户想「铺 B-roll / 检索素材 / 找空镜 / 给空镜配画面 / 填 B-roll 候选 / 单独搜个词补个空槽 / 找 BGM / 搜配乐 / 搜张配图 / 用我自己的素材铺 B-roll / 给素材文件夹建索引 / 理解一下这些素材能不能用 / 把这堆素材剪成片 / 影视解说配画面」时使用本 skill。凡涉及把素材检索并铺进工程，优先用本 skill 驱动 gtrk CLI 的 `matrix` 命令族，别让用户自己去终端敲、也别手搓检索。

B-roll 检索铺轨编排手册（gtrk-matrix）

把素材检索铺轨当**乐高**：CLI 提供原子零件（index / search / describe / plan / lay），你按场景裁定怎么编排——本手册给你六个起手配方、三条裁定判据、零件参数总表、plan 编辑口径与计费速查。**CLI 是手（检索/理解/下载/铺轨/写回），你是脑（裁定用哪个配方、管用户检查点、遇差调参补空）。**

> **本 skill 已含你需要的全部信息**，照它做即可，不用也无法去查外部文档。（`gtrk matrix --help` 也随时列全部 flag。）

四层架构与三条铁律（先立规矩）

裁定层（你）：按题材/素材形态/文稿有无/用户偏好，选配方或自创编排
配方层（本手册 §配方库）：原子命令的调用序列——只是起手式，可变奏可自创
原子层（gtrk CLI）：index / search(--local/--source-window) / material / describe / matrix(plan) / lay / tool image_move
服务层（云端）：embed 端点 / material_describe / 检索 2×2 四口（剪辑向×通用三态 × 公开×成员） / image_move

1. **零件不裁定**：原子命令不猜用户意图，行为全由显式参数决定。`describe` 出的 `usable_flags`（水印/字幕/黑边/模糊）只是**给你的信号**——CLI 永远不会依据它自动剔除候选，剔不剔由你编辑 plan 裁定。 2. **配方不进代码**：配方只活在本手册。遇到新场景，别等 CLI 发版——用现有零件拼。 3. **plan 是一等可编辑中间产物**：检索产 plan → 你改 plan（删候选/重排/删段/注理解/钉选）→ `matrix lay` 消费。这是你的裁定注入铺轨的**法定通道**（口径见 §plan 编辑口径）。

配方库 v1（起手式，可变奏可自创）

当前 Agent 的审片路径（本地素材优先）

视觉理解优先由用户当前会话的 Agent 完成。CLI 不启动另一个 Agent；“本地”指编排位置，不保证当前 Agent 的模型在离线设备运行。

1. **概览**：按素材时间顺序查看带时码的抽帧与照片；长场景也保留多个观察位置。结合 `gtrk transcript` 的原声转写整理事件、人物、环境和待核实之处，不从文件名猜内容。 2. **细查**：脚本要求某个动作或情绪时，对相关素材用 `describe --materials <视频> --source-window <起秒,止秒> --prepare <工程目录/审阅目录>` 加密取帧；通过当前视觉工具检查过程。有音频依赖时回看/听对应原声，不以一张图证明完整动作。 3. **回传**：查看任务中的实际图片后填写 `visual-review.json`，以相同输入参数加 `--review <回执路径>` 导入。全部本地完成时零豆包调用；不能看图或无法完成的单项标 `unavailable` 并说明原因，只有这些项由豆包补齐。不得把未查看项批量写成完成，也不得仅因省事直接调用豆包。 4. **编排**：从已观察证据中按脚本意图选择片段。按脚本语义选材，本手册不调用视频高光算法；该增强仅由 Vlog 图纸按需编排。看片范围、未确认事实和原声覆盖均如实记录。

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"`，累加不覆盖），别塞进一串里 —— 缺省按半角逗号分隔。整串在盘上存在时会自动不拆，中文全角「，」从不参与拆分。

配方 A · 纯匹配铺轨（默认主路）

• **适用线索**：文稿强（口播/解说已定）、素材净（策划过的素材夹或云端素材库）、节奏快、成本敏感。
• **命令序列**：

  gtrk split <拆分稿>                                   # ② 产派单
  gtrk matrix --project <目录> --json                    # ③ 检索+铺轨一步走（云端）
  # 本地素材版：gtrk matrix --local --dirs <素材夹> --project <目录> --json

• **变奏点**：`--lay N` 多候选轨；`--score-floor` 卡准入；`--top-k` 扩候选面；`--lay 0` 先出 plan 人审再 `matrix lay`。

配方 B · 匹配后理解铺轨（求稳/素材可信度存疑）

• **适用线索**：素材夹很「野」（下载杂片/相机胶卷，可能混着带水印、烧字幕、黑边、糊片）；高价值成片求稳；用户抱怨过「搜出来的像但不能用」。
• **命令序列**：

  gtrk matrix --local --dirs <素材夹> --project <目录> --lay 0 --json     # ① 只出 plan 不铺
  gtrk matrix describe --plan <目录>/split/broll-plan.json --top-k 5 --json  # ② 理解 top 候选，产物注入 plan
  # ③ 你读 plan 各 result.describe，裁定：剔除 usable_flags 命中且描述证实不能用的候选（删 result 条目）、
  #    按描述调顺序（重排）、把非留不可的候选标 pinned:true —— 直接编辑 plan 文件
  gtrk matrix lay --project <目录> --json                                  # ④ 消费你编辑后的 plan 铺轨

• **变奏点**：`--top-k` 控理解成本（1 积分/张，只理解你会认真考虑的那几条）；云端 plan 同样可 describe（帧从签名 url 现抽）；理解产物有本地缓存，反复迭代不重复扣费。
• **裁定要点**：`usable_flags` 是信号不是判决——结合 `desc` 复核（水印在角落的航拍也许仍可用）；剔除动作=从 plan 删掉那条 result，CLI 不会替你剔。

另读 describe 输出的**剔除风险**清单：候选数 ≤1 的 beat 一删就掏空（音频驱动 ⇒ 整段黑屏或跨 beat 借片；口播 ⇒ 露 A-roll）。先补素材再剔，MUST NOT 见 flag 就删。 该清单只是判据，剔不剔仍归你（铁律①「零件不裁定」，见 §四层架构与三条铁律）。

配方 C · 时间窗匹配（电影解说式）

• **适用线索**：解说顺序≈素材内时间顺序（影视解说、赛事复盘、长录像剪辑）——第 N 段解说该配影片第 N 段邻域的画面，全片乱配会剧透/错位。
• **命令序列**（逐段推进窗口，窗口推进是你的编排逻辑，CLI 不自动推进）：

  # ⚠️ --dirs 钉到**这一部片的绝对路径**，不是它所在的夹——同夹邻片会抢占候选
  gtrk matrix index --dirs <这一部片的绝对路径> --json
  # 对解说的每一段（第 i 段，共 n 段，影片时长 D 秒）：
  #   窗口中心 ≈ D × (i/n)（解说进度比），半径 r 可调（起手 ±D/n 到 ±2D/n）
  gtrk matrix search "<该段画面描述>" --local --dirs <这一部片的绝对路径> --source-window <中心-r>,<中心+r> --out seg-i.json --json
  # ↑ --dirs（文件域）与 --source-window（源时间域）是**两个维度**，AND 叠加：
  #   前者限定「哪一部片」，后者限定「片内哪一段」。只用后者不限文件域，邻片的同时段照样进候选。
  # 空窗（results 空）→ 你裁定：扩半径重试 / 接受留空 / 放弃时序约束去全片搜
  # 汇总各段命中组一份 plan（结构照 broll-plan.json；每段一个 beat、track_st/ed=该段口播窗口）
  # ★ 每个 seg-i.json 里的 results 条目**原样搬进去**，MUST NOT 自己重写 segments
  gtrk matrix lay --project <目录> --plan <你组的 plan 路径> --json
  #（可选）组 plan 前先 describe 一轮候选帮助取舍（配方 B ③ 的动作）

• **变奏点**：窗口公式只是起手——非线性叙事（倒叙/闪回）按你对片子的理解手排窗口；`--source-window` 与 `--score-floor` AND 叠加；窗口显式传入时图片候选自动排除（无时间轴）。
• **要点**：段边界不被窗口裁剪（有交集即完整返回），截多长归铺轨槽长逻辑；扩窗与否永远是你的裁定，CLI 绝不自动扩。
• **★ 组 plan 时最容易丢的东西**：`cuts`（段内切点）与 `motion`（段级运动量）住在 **`segments[]` 里面**，检索结果本来就带着它们。你**原样搬** `results` 条目就都在；一旦按「我自己写个 start/end/best」的姿势重写 segments，它们一起没了，后果具体是：
• 丢 `cuts` ⇒ 铺轨的**端点残片收缩空转**（只剩帧网格吸附，还得候选带 `fps` 才生效）——成片上可能出现一闪而过的异景帧；
• 丢 `motion` ⇒ **高运动降权不生效**（缺席=不可判，不是「平稳」）；
• 没跑过 `describe` ⇒ 美观度 / 看点 / 模糊降权三条一并不生效（那是配方 B ② 的产物）。
• **两种「没有 cuts」要分开处理**：① 素材压根没扫过切点 ⇒ 跑 `gtrk matrix index --dirs <夹> --rebuild` 补上；② 你重写了 segments 把 `cuts` 抹掉了 ⇒ 重跑索引一万遍也不会消，改姿势**原样搬回** `results` 条目即可。

⚠️ 告警本身**分不清这两档**——两者在 plan 里长得一模一样（都是 `cuts` 整键缺席）。判别法是**先跑 ①，若告警还在就是 ②**（`matrix lay` 的告警原文里也是这么写