gitruck/cli/gtrk-narration

gtrk-narration（通用解说 · 解说链正本图纸）

把一个很长的东西——旅行素材夹、影视长片、游戏实况、探店/做饭流程记录——提炼梗概、高光、看点，用精简叙述重讲成一条解说成片工程。

定位：解说链的正本图纸（structure 级，不新增命令，只编排零件）。旅拍解说

gtrk-travel-recap 是先行垂类实例；通用框架层（三段式写稿规约/文风铁律/自校验）

正本在旅拍图纸 §三，双模式与决策前置公约见仓内《成片型图纸公约》。CLI 是手，你是脑。

一、解说链判据（先想清楚这个再开工）

解说的充要条件 = 素材语料自带叙事时序，且成片必须尊重它。 旅行有时间线、电影有剧情线、游戏有进程线、探店/做饭有流程线。

由此推出两条边界：

• 和长剪短的关系：同一个输入（一个很长的东西）、两种做法——长剪短是让它自己说（切原声高光），解说是你替它说（提炼后重述）。真实解说片常是两者的混合（见 §四 引用段）。
• 和通用配音（`gtrk-voiceover`）的关系：素材没有自己的时间线（科普/情感/盘点，素材只是插画）→ 那是配音链的活，转 gtrk-voiceover，MUST NOT 用本图纸硬套时序。

素材来源边界：解说的主体画面只用本地素材——素材就是被讲的对象本身，平台素材库在主体画面上是范畴错误；平台库最多补空镜/概念镜头作辅料，缺省不掺、问了才加。

二、输入契约与开工七问

输入：本地素材语料（素材夹，或单条长片——影视/游戏实况先建索引拆条）±稿件 ± 用户自己念的口播毛片。MUST NOT 执行任何网络下载（版权责任归用户）。

②③④⑤⑦ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。

精剪包装（公约 §三⁵）：开工时告知一句「快速成片会在适合的段落做合成包装，最多全片四分之一，不要就说一声」——不是问题，用户说不要即零动作；gtrk composite bake --abi 报烘焙浏览器没装时，在这张问询表里多问一句装不装（不装用本机 Chrome / Edge）。

推荐面（公约 §三‴）：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 gtrk skills recommend --scene <id> --json；用户拒绝后不执行推荐动作。

语种必须在转写前确认。非中文素材传错语种会让检查点①拿到错误稿件并产生重复 ASR 成本；不要静默使用 zh-CN。粤语建议填写 zh-HK 作为元数据，当前 --json 路径按字级转写；无对白素材回答「无对白 / 不转写」即可。

三、时序铺排三档（本图纸的技术正本）

每段叙述配什么画面，按下面三档路由，高档优先：

⚠️ 甲档的适用范围：

整份手写 plan（免索引直排）降级为「引用段与硬出处段专用」，叙述段缺省不再走它。

手写 plan 缺少检索结果携带的质量信号，因此：

| 信号 | 断在哪 | 后果 |

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

| mark 美观度 | 无检索 plan ⇒ matrix describe --plan 无作用对象 | --mark-weight 0.3 全部候选中性，30% 权重原样回吐 sim |

| highlight 看点 | 同上 | 看点排序不生效 |

| blurry 模糊 | flag 随 describe 注入，同上 | 糊帧与清晰帧同权 |

| motion 高运动 | 手写 segments 不带该字段 | 抖/摇段不降权 |

| cuts 切点 | 同上 | 端点残片收缩失效 = 闪帧的机制性根因 |

⇒ 叙述段缺省走「出处窗内检索」（见下方「甲′」），既保出处准、又拿回五条信号。

用户坚持免索引时照办，但 MUST 先把上表的代价说清——它不是「快一点」，是质量档位下降，

且 MUST 在交付说明里如实登记本片走的是降档路径。

甲 · 锚定直排（出处优先，最高档）

检索再聪明也是猜，出处不用猜。 稿段与素材区间的对应关系在写稿阶段就建立：

• AI 代写稿（③=代写）：提炼时逐段带出证据链——每段稿标注「本段对应素材哪个文件哪个区间」（影视类从台词转写提炼，天然带时码；素材夹类从索引场景描述提炼，带场景座标）。
• 用户自备稿（③=自备）：补一步出处对齐——拿稿件逐段与素材索引/台词转写做语义对齐，产一张稿段↔素材区间对照表（逐段带置信度）。对照表进检查点①给用户过目：高置信段直接用，低置信段标出来请用户指认或改判（同对轨的置信门姿势——机器有把握就不打扰，没把握才请人）。用户也可以在稿里用轻量标记直接指定出处（如「【素材：片段03 2:10-2:40】」），标记段跳过对齐直接采信。

铺轨时出处段直排。用 `arrange_mode` + `direct_slots` 标注，别去手写整份 plan 的 假 `queries`/`segments`——那条路会让窗口精修拿不到 cuts，而精修正是这一档的价值所在。

{
  "beat": "B03",
  "track_st": 12.4, "track_ed": 18.9,
  "arrange_mode": "direct",          // 逐 beat 标；同一片内可混档
  "direct_slots": [
    { "clip_id": "local-a1b2…", "clip_st": 132.0, "clip_ed": 138.5,
      "track_st": 12.4, "track_ed": 18.9,        // 引用段**必给**
      "slot_role": "quote" },                     // 画音逐秒对齐，端点是硬约束
    { "clip_id": "local-c3d4…", "clip_st": 40.0, "clip_ed": 44.0,
      "slot_role": "provenance" }                 // 硬出处段：位置可协商，缺位置则在 beat 内顺排
  ],
  "queries": [ /* 可留：直排槽先钉死，剩余区间才走检索 */ ]
}

两类的区别只在一件事上——端点动不动得：

缺席 = 按硬出处处置。帧网格吸附两类都做（位移 ≤ 半帧，保证端点落在可播帧边界上）。

两条诚实边界（MUST NOT 对用户说成「直排就一定不闪帧」）：

① 端点残片收缩要 cuts ⇒ 素材未索引就无数据可用，只得部分收益；

② 帧网格吸附要帧率——全 plan 任一 beat 见过这条素材即可（不必索引），

都查不到则回执报 fps: null，那一步整步没生效。

两条独立，回执分别以 has_cuts / fps 报，cut_snap 三态再把「按你的标注主动不吸」

与「素材没索引想吸也无从吸」分开。

直写 plan 操作注记：整份 plan 可以手写——甚至不依赖本地索引

（4K 长片索引很慢，甲档直排等不起也不必等）。逐 beat 一条 query、逐出处窗一条 result，

segments:[{start,end,best,score}]（源片秒）。三条铁则：① best 是窗内代表帧时刻

（秒），落窗外会被校验拒；lay 取段大致以 best 为中心——想 start 锚定就把 best 设为

「窗起点 + 意图时长/2」；② 预算三量齐足——per_shot_sec 按「beat 时长 / 窗数」给、窗宽 ≥ 份额，长出处区间拆成多个子窗；③ 引用段窗与配音时轴逐秒对齐（窗起点 = 引用音频对应的

源时刻），铺后按 clip_st 与 track_st 的差恒等 复核零漂移；④ **口播基座下 beat 预算按

dispatch 的成片轴包络算**——transcript.json 的 st/ed 是源时码，且 beat 连续化会把句间

停顿带并入下一 beat，窗预算不足会产生空洞；

⑤ beat 粒度以关键句为主，采用约七三的对齐与游离比例。先认清机制：

matrix lay 在 beat 内按候选分数贪心铺满、槽序与句序无关——一个 beat 跨多句时，

只有「领衔句」能拿到为它挑的画面，其余句是跟随。由此定编排法（顺序不可颠倒）：

①关键词卡点先行：先挑出有明确视觉指涉的句子（实体/动作/可拍之物），逐句独立成 beat、

一 beat 一窗，保证「稿说什么就给什么」。划分判据是「素材里有没有」，不是「句子抽不抽象」

——素材里有对应画面的句子 MUST 卡点

（哪怕它夹在抽象段里，如「昨天的老汤兑进今天的新汤」有汤锅镜头就必须给汤锅）；素材里

确实没有的才允许降为跟随（「卖过三十年汽车」片里无车、「多线程游戏」无从拍）。判据的

落地取证=渲后 gtrk qc --alignment：**卡点句 mismatch MUST 收敛到 0，且每一条 mismatch

都要先问「是我窗选错了，还是素材真没有」；②其余填坑：抽象句、数字句、修辞句、情绪句

（日期/克数/"比太阳起得早"/"多线程游戏"）没有对应画面可给，合并进相邻关键句的

长镜头当跟随，或用主题相近的群像长镜头覆盖；③七三开收口：约 70% 时长逐句对齐、

30% 游离创造自然感——游离不是妥协是设计。

⚠️ 不要追求 100% 逐句硬切：对齐质检的靶子是「关键句零 mismatch」，其余句允许跟随；一个 beat 也不要跨太多关键句，以免集体错位。

⑥ 盲选窗跨源镜头切点——direct_slots 的直排槽同样会过窗口精修，provenance 段的端点会自动吸到切点。

仍会剩下两种情形，都要如实报账而不是靠重铺硬碰：

· 素材未索引（无 cuts）⇒ 收缩无数据可用。先索引再铺是正解，等不起就照实说明。

· `quote` 引用段 ⇒ 它按设计不吸（吸走就是画音错开）。若那一口确实横跨切换，

那是内容本身如此，正确处置是改稿或改引用区间，不是让铺轨替你挪。

渲后 QC 的 flash/intra_cut 证据仍可反算源切点（clip_st + into_clip_sec）供人工复核。

甲′ · 出处窗内检索（叙述段缺省路）

出处准与检索对齐可以兼得，不必二选一：把出处区间当检索域而不是当答案。

# 卡点句：窗收到出处邻域，让检索在窗内挑最好的那颗（而不是我盲猜一个窗）
# ★ 铁则：解说链**一稿对一片**，--dirs MUST 钉到那一部片的绝对路径，**不许传素材夹**
gtrk matrix --project "<工程>" --local --dirs "<这一部片的绝对路径>"   --source-window "<出处起,出处止>" --lay 0 --json

它同时给到四样甲档给不了的东西：① 段边界天然落在场景切点上（闪帧从源头消失，不必事后 QC 反算重铺）；② 段带 cuts，端点残片收缩生效；③ 段带 motion，抖/摇降权生效； ④ 候选进了 plan 就能 matrix describe --plan，mark/highlight/blurry 三条一起活过来。

窗怎么给：出处区间前后各放宽一点（让检索有得挑，别收成一个点），但不要放宽到跨场次—— 窗太宽等于退回纯语义、出处就白标了。窗内零命中不是错误（返回空结果），扩窗与否你裁定。

仍然直排的两类：引用段（画音必须逐秒对齐，检索无从保证）与硬出处段 （用户在稿里显式写了「【素材：片段03 2:10-2:40】」，那是指令不是线索）。

乙 · 语义 × 时序先验（软窗，中档）

出处缺失的段落走检索，但打分 = 语义分 × 时序先验：按稿件进度比例映射到素材时长的期望位置，偏离越远先验越低。两条铁则：

• 单调性是不变量，窗宽只是参数：窗口下界随稿件推进只进不退。违序命中须有显著语义优势才放行。单调性顺手让「素材不二用」成为自然结果。
• 硬窗只留给剧透敏感档（影视类 ②=严格按顺序）：窗口成为硬约束，窗外零候选。

落地即旅拍图纸 §五 的 --source-window（时间窗约束检索）加上你在 plan 层的排序裁决——先验计算是你的活，CLI 收敛候选。

丙 · 纯语义（低档 = 出链）

②答「顺序无所谓」且素材确无时序 → 这片子按判据出解说链，转 gtrk-voiceover 纯语义铺排，别硬留。

四、叙述段 × 引用段

解说片的声音轨是两种声音交替：叙述段（你的配音在讲，画面铺素材）与引用段（配音停下，源素材原声原样播几秒——角色亲口说那句台词、主播原声的呐喊、巷口的现场声）。引用段是证据和情绪冲击，转述一百句抵不过原声一句。

• 引用点在写稿时定：稿件里显式留引用窗口（出处 = 甲档对照表里的区间），MUST NOT 铺轨时临时起意。
• 切取用流拷贝（ffmpeg -c copy，零重编码）；想让 AI 帮你海选可引用的高光，可先跑一遍 gtrk long2short 拿选段清单当候选（可选辅助，明示计费）。
• 装配：逐段 TTS + 引用段原声按稿序拼成总音频 → 合成 transcript（各段句级时码换算到拼接轴）→ gtrk project init --audio <总音频> --transcript <合成转写> 建工程（自备配音兜底路）；引用段画面 = 该源区间直排上轨。无引用段时装配退化为单条 TTS + --tts-task 主路（与旅拍同款）。

产物文件名别硬拼（fix-tool-outdir-collision）：多段 TTS 落同一个 `--out` 时，第二段起的产物会带 taskId 后 6 位后缀（tts-narrator-a1b2c3.wav），基名只有第一份是干净的。拼接清单 MUST 按每次回执的 files 取路径，MUST NOT 按 tts-<speaker>.wav 猜——猜出来的名字会一路指向第一段，拼出来的总音频会把某一段重复多遍而不报错。 主轨无缝铁则：合成 transcript 里引用段 utterance 的 st/ed MUST 写物理拼接位（拼接轴上的真实起止），MUST NOT 加字幕 pad；已有 pad 的工程按「改时刻→重导视图→重落拆分→重铺→字幕重出」修复。

• 克制丑话：引用段是佐料——时长占比失衡会让片子变成搬运，平台判定风险归用户（§八 一并告知）。

五、快速成片编排

# ① 索引前置（第一步就起，不是可选项——它是质量信号的载体，见 §三 代价表）
#    4K 长片索引慢，未提速期**与写稿/TTS/检查点①并行跑**，别串行干等
gtrk matrix index --dirs "<这一部片的绝对路径>" &     # 后台起，写稿同时跑（索引侧同口径：也钉单片）
#   ⚠️ **后台起就看不见失败**：全域零枚举现在是**硬失败**（退出码 1），而 `&` 把它吞了 ——
#     回头 MUST 看那一行的 `materials.total` 与 `per_dir`，别等到检索阶段才发现索引是空的。
#     报 0/0 先看两件事：路径里有没有**英文半角逗号**（有就把 --dirs 重复传，别塞一串）、素材夹里有没有断链。
gtrk transcript "<长片>" --lang <开工⑦所答语种> --json   # 影视/游戏类：台词与时码双锚（可选）
#   ↑ 语种取开工⑦所答，MUST NOT 拿缺省顶上去 —— 但「传错就白花钱」只在**非中文**这一档成立；
#     粤语 SHOULD 如实填 zh-HK（元数据诚实 + 备链路切换），当前链路下对粤语无差别：
#     CLI 写死 word_level: true ⇒ 钉在豆包，豆包字典里 zh-CN 与 zh-HK 都映射空串 ⇒ 请求逐字段相同。
#     MUST NOT 以「粤语传错」为由重跑（la 进 ASR 缓存键，换码必 cache miss、白扣一次时长）。详见 §二 ⑦ 注
 
# ②③ 写稿（甲档出处共生 / 乙路对照表对齐）→ 检查点①拍板（§六）
gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
#   ⚠️ is_copyright 的权威语义是 1/true=可商用、0/false=**不可商用**，MUST NOT 把 false
#   读成「无版权、可随便用」。矩阵成员档**缺省搜全库**，MUST NOT 默认加 --commercial-only、
#   也 MUST NOT 以「保险起见」为由剔掉 is_copyright:false 的候选（全库正是成员身份买到的东西）。
#   对价是**如实标注**：推荐时 MUST 逐条带上 copyright_label（派生位，中文标签），不可商用的照直说，
#   但 MUST NOT 升级成追问或阻塞。用户**特意说明**只要可商用 / 要商用发布 / 客户商单时才加
#   --commercial-only 收紧；「用户没说」MUST NOT 当成「用户要求收紧」。
 
# ④ 声音基座（按开工④路由）
gtrk tool audio_tts_clone --text-file <稿段.txt> --speaker <voice_id> --json   # TTS 路
#   口播路：用户念稿毛片 → gtrk oralcut（外录先 gtrk audio align）→ 粗剪工程即时间基座
 
# ⑤ 建工程（有引用段=拼装总音频走 --audio+--transcript 兜底路；无引用段= --tts-task 主路）
gtrk project init --tts-task <id> --canvas <WxH> --no-open --json
 
# ⑥⑦ 拆分派单 → 铺排（叙述段走甲′出处窗内检索；引用段/硬出处段才直写 plan）
gtrk split --project "<工程>" --json && gtrk split "<拆分稿>" --project "<工程>" --json
# ★ 同上铁则：--dirs 钉单片，MUST NOT 传素材夹
gtrk matrix --project "<工程>" --local --dirs "<这一部片的绝对路径>" --source-window "<出处起,出处止>" --lay 0 --json
gtrk matrix describe --plan "<工程>/split/broll-plan.json" --yes --json   # ← 不跑这步，下面三个权重全是摆设
gtrk matrix lay --project "<工程>" --mark-weight 0.3 --highlight-weight 0.2 --gap-fill fast --json
#   ↑ lay 会在「开了权重但本片零缓存覆盖」时告警——看到它就说明 describe 那步漏了或没生效
 
# ⑧⑨⑩ 字卡（MG 临场泛化，公约 §三）→ BGM（0.10 垫底、短了自动循环铺满）→ 字幕直出
# BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
# 不得用 download_url 原曲（人声与配音会打架）
gtrk mg --project "<工程>" --json
# --beat-align 的高潮点取自 split.beats 的 narrative / container_stage（升华段 → 容器转折 → 回扣段）；
# 拆分稿没带这两个字段 ⇒ 落 0.75×全片兜底档，**CLI 会明示那是猜的**。不接受就用 --climax <轨秒> 指定。
# 两侧都够长时零平铺（恰好 1 个 clip）；不够长才按小节线平铺补齐、接缝吸附 downbeat。
gtrk audio lay --project "<工程>" --file "<bgm>" --volume 0.1 --beat-align --json
gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
# 精剪包装：见下方引注

精剪包装（字幕之后、出片之前）：交棒 /gtrk-composite 做精剪包装（公约 §三⁵：快速成片 auto ≤ 25% → 逐窗口复核 → 构建机检 → 铺轨烘焙，不停；回执列「做了 / 建议了没做 / 烘焙结果」；逐步推进按合成 skill 两个检查点停；开工时用户说了不要就跳过）。没有讲者的工程只用 B-roll 与排版。

停顿太长时：自训音色加 --fragment-interval 0.2（合成时就对）；云引擎音色不支持该参数（传了会报错，不会静默忽略），改在合成后跑 gtrk audio tighten --project <工程> 收紧句间停顿（纯本地零计费；只压跨句界的停顿，句内换气与原声引用段不动）。

配方口径（--mark-weight 0.3、BGM 0.10、--gap-fill fast、句界吸附缺省）与旅拍图纸 §五 同源，本图纸引用不复制。 --highlight-weight 0.2：看点维度与 mark 正交——mark 判「好不好看」、highlight 判 「有没有看点」（信息量/戏剧性/情绪强度/稀缺性）。看点准则按垂类走 L1 rubric（美食/旅拍图纸各持一份 画面投影版）。两权之和 0.5，语义仍占一半——MUST NOT 加到语义压不住的程度，那会变成 「专挑好看的，不管说的是什么」。 ⚠️ 三个权重（mark/highlight）与 blurry 降权全都依赖 `matrix describe --plan` 跑过； 没跑就是全部候选中性、排序与不开权重逐字节一致。 质检按公约「三级收敛」执行：L1 恒开；L2 落轨前可用 gtrk matrix lay --arrange-qc 检查卡点句画音对齐；L3 渲后终检随本来就要交付的本地渲附带，不为质检单独逼渲。跑过的质检结论随交付分层呈现。

六、检查点①（拍板停一次；铺画面前另有一次用量确认）

本地素材的编排缺省走云端并按编排量计费。matrix lay 跑前必须报告预估用量，取得同意后才能带 --yes；无 TTY 且未确认时整轮中止，工程不改动，plan 可重跑。

稿件（含引用窗口标注）+ 出处对照表（乙路时；低置信段标出）+ 画幅 + 音色（附试听）+ BGM（附试听）+ 字幕样式（不挑走默认）——一屏给齐一次拍板。未经确认 MUST NOT 发起 TTS/长剪短等计费动作。

六′、稿句↔镜头对照表（铺轨前必给）

候选选定、铺轨动作发起之前，把「哪句配哪个镜头、为什么是它」摊开给用户过目。 出处对照表回答「这段稿从哪来」，本表回答「这段稿给什么画面」——两张表不互替。

三条呈现纪律：① 卡点句与跟随句要标出来（用户一眼能看出哪些是承诺对齐的、哪些是有意游离）； ② 附缩略图（公约 §二″：给用户眼睛看的，不是给 agent 看的）；③ 「选它的理由」写人话， 不写分数——看点 71 是佐证不是理由。

用户在这里改判的成本最低：他说「u0012 我记得片尾还有个更好的标牌镜头」，此时换窗重检索 只花几秒；等铺完渲完再改，就是整轮返工。

六″、验收判据

含 B-roll 覆盖的成片，验收 MUST 同时满足两条：