gitruck/cli/gtrk-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 · 纯匹配铺轨（默认主路）

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

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

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

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

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

``bash 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 不自动推进）：

``bash # ⚠️ --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 的告警原文里也是这么写的）。 另注：cuts: []（空数组）不是「没有 cuts」，那是「扫过了，这段里恰好没切点」，可判且无风险，不会触发告警。

配方 D · 理解先行编剧（vlog 式，素材→文稿）

• 适用线索：没有文稿、素材是叙事源头（「帮我把这堆素材剪成片」、旅行胶卷、活动跟拍）。查询不存在，无物可匹配——先理解素材，再由你编剧。
• 命令序列：

``bash gtrk matrix index --dirs <素材夹> --json gtrk matrix describe --materials <素材路径列表> --json # 全量或抽样理解（视频按场景抽帧、图片直传） # 你拿着逐场景描述编剧：大纲 → 章节 → 逐章旁白（与用户对话定基调） # 旁白定稿 → 走口播管线反填：oralcut/TTS 出口播 → gtrk split → 配方 A/B 反填 B-roll ``

• 变奏点：素材多时先抽样（每夹几条）理解定大纲，定了再补理解入选素材；描述有缓存，二次编排零成本；>20 张会有计费确认（1 积分/张），先跟用户对齐预算。

配方 E · 三层层叠（企业动线）

• 适用线索：本地素材不够填、需要栏目概念素材/通用素材补空洞；企业客户三源混用。
• 命令序列（任意顺序，层序铁律自动保序 local > concept > common）：

``bash gtrk matrix --local --dirs <素材夹> --project <目录> --lay 2 --json # 本地层 gtrk matrix --project <目录> --column <id> --material-class concept --json # 概念层（internal 矩阵成员口） gtrk matrix --project <目录> --json # 通用层垫底填空洞 ``

• 变奏点：每层可独立换配方（本地层走 B 先理解再铺）；每层铺完停下让用户看（见「三条业务动线」节）；重铺某层不碰他层。
• 注意：概念层重铺请走上面的检索命令（matrix lay 从 plan 推导层归属：local→local、云端→common，概念层信息不在 plan 里）。

配方 F · 图文混排

• 适用线索：素材夹含大量剧照/海报/示意图；图片值得上轨（被选中时自动经云端 image_move 转运镜视频，2 积分/张）。
• 命令序列：任意配方照跑——图片默认参与索引/检索/铺轨；--no-image-broll 反向排除（零图片上云）。
• 变奏点：describe 对图片是文件直传理解；出域与计费口径见「图片候选运镜入轨」节——图片本体会上云这条差异必须跟用户说清。

裁定线索（判断素材，不是分支条件）

拿到一个活，先过三个判据。它们帮你倾向某配方，不是 if-else——边界情况跟用户对话确认。

1. 信息流方向：成片从素材长出来（素材→文稿），还是素材服务既有叙事（文稿→素材）？

用户给了完整口播/文稿/解说 → 查询存在，匹配主导（A/B/C）。用户只有一堆素材、叙事尚未诞生 → 无物可匹配，理解主导（D）。「先剪口播再配画面」是前者，「把这堆素材剪成片」是后者——同一个用户两天能各来一次，别拿昨天的路径套今天。

1. 素材可信度：素材越「野」，理解的前置价值越大。策划过的素材（成片切片/精选夹/云素材库）→ 纯匹配直接吃（A）；下载杂片/用户随手拍（可能混水印、字幕残留、糊片）→ 匹配后理解过一道（B），甚至先 describe 全量过滤再谈其他。判断不了就问用户素材哪来的。
2. 规模 × 决策类型：几十个镜头 → 描述装得进上下文，你直接读 describe 产物做编排；万级库 → embedding 粗筛必须先行（index/search），理解只花在 top 候选（B 的成本结构：O(候选) 而非 O(素材库)）。「找相似画面」→ 检索足矣；「排叙事/定取舍/避剧透」→ 必须理解物+你裁定（B/C/D）。

再叠两条场景特征：解说与素材同源（影视解说）→ C 的时间窗；素材夹里图片占比高 → F 的口径先交代。

零件参数总表

检索/铺轨主命令（gtrk matrix，云端派单消费为默认路）：

⚠️ 编排档位不是 flag。 --arrange 管的是取数路（在哪算：本机还是云端），

与「怎么排」无关。编排档位（direct 高档锚定直排 / temporal 中档 / semantic 低档）

是 plan 层字段 beat.arrange_mode，由 agent 在图纸层逐 beat 标注，

同一片内可混档。没有 --arrange-tier 这种参数，CLI 不猜档位。

高档还要在同一个 beat 上给 direct_slots[]：

{ clip_id, clip_st, clip_ed, track_st?, track_ed?, query?, slot_role? }。

slot_role 二选一——quote 引用段（画音逐秒对齐，端点是硬约束，**必须给

track_st/track_ed**）、provenance 硬出处段（位置可协商，要精修消端点残片）；

缺席 = 按硬出处处置。越界取值一律拒绝，MUST NOT 静默降级。

通用三态素材检索零件（gtrk matrix material，云端素材库、下载向出参）：

与上面那张表的剪辑向检索是并列的第二条线，出参契约独立（下载向直链 vs 剪辑向 segments），别混用：要 B-roll 段落走 matrix search/派单主路，要整条素材（BGM、配图、整条原片）走本零件。

2×2 路由矩阵（身份自动判定，每次运行探一次、不降级不缓存）：

| | external 公开口 | internal 矩阵成员口 |

|---|---|---|

| 剪辑向 | /task/video_clip_search | /task/custom/video_clip_search |

| 通用三态 | /task/material_search | /task/custom/material_search |

成员口搜全库（含非商用/概念素材）且 0 积分；公开口只含可商用实拍素材、1 积分/次。差距不是理论值：Artlist 全库 2397 条音乐 is_copyright=0，同一 query 公开口 0 条、成员口 5/5 命中。