/gtrk-narration

name: gtrk-narration
description: 通用解说视频创作图纸（解说链正本）——把「一个很长的东西」（旅行素材夹/影视长片/游戏实况/探店与做饭流程记录）提炼梗概、高光与看点，用精简叙述重讲成一条解说成片工程。判据=素材语料自带叙事时序且成片尊重它；声音基座无关（TTS 配音 / 用户自己念的口播毛片皆可，稿可 AI 代写可自备）。当用户想「做影视解说 / 游戏解说 / 探店解说 / 做饭流程解说 / 把这段素材讲成一条片 / 解说视频 / 把这部片子讲一遍」时使用本图纸。旅拍解说（gtrk-travel-recap）是本链先行垂类实例。凡解说类成片，优先用本图纸编排，别直接裸跑零件。

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

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

> **定位**：解说链的**正本图纸**（structure 级，不新增命令，只编排零件）。旅拍解说 > `gtrk-travel-recap` 是先行垂类实例；通用框架层（三段式写稿规约/文风铁律/自校验） > 正本在旅拍图纸 §三，双模式与决策前置公约见仓内《成片型图纸公约》。**CLI 是手，你是脑。**

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

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

由此推出两条边界：

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

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

二、输入契约与开工七问

**输入**：本地素材语料（素材夹，或单条长片——影视/游戏实况先建索引拆条）±稿件 ± 用户自己念的口播毛片。**MUST NOT 下载二创源片 / 主体素材**（版权责任归用户）。平台授权素材（素材矩阵的 BGM / 空镜）可按其签名直链落地；这条例外不适用于源片与主体画面素材。

| # | 问 | 怎么取证 | 决定什么 | |---|---|---|---| | ① | 素材语料形态 | 看目录：素材夹（多条短素材）还是单条长片 | 长片先 `gtrk matrix index` 建索引拆条（场景切分即时序坐标系）；影视类加转写（台词是语义+时序双锚） | | ② | 时序档位 | **问用户**：成片要不要按素材自己的顺序讲？ | §三 三档路由（影视缺省最严档，旅拍/游戏/探店缺省软窗档） | | ③ | 稿从哪来 | **问用户**：AI 代写 / 你自备稿 | AI 代写走出处共生（§三 甲）；自备稿走出处对齐（§三 乙）。自备稿喂口播对齐（`--script`）前 SHOULD 剥离舞台指示括注（「（停顿两秒）」「（插入某片段）」——没念出的字进终稿只会计入缺失段） | | ④ | 声音基座 | **问用户**：TTS 配音（挑音色附试听）/ 你自己念（给口播毛片） | §五 基座路由：TTS 走配音工程；口播毛片先走 `gtrk oralcut` 粗剪（外录先 `gtrk audio align` 对轨） | | ⑤ | 要不要引用段 | **问用户**，按题材给建议：影视/游戏强建议开，旅拍/探店可选 | §四；答不要 = 全程零引用动作 | | ⑥ | 画幅 | 按投放平台问；素材几何 ffprobe 取证 | 画布；横屏素材硬做竖屏有黑边/裁切，丑话先说 | | ⑦ | **源片语种 / 方言** | **问用户**：听一段 / 看片内有无内嵌字幕 / 看素材出处 | `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）；素材通篇无对白答「无对白 / 不转写」即闭合，MUST NOT 因缺这个答案阻塞开工 |

> ②③④⑤⑦ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。 > **精剪包装（公约 §三⁵）**：开工时告知一句「快速成片会在适合的段落做合成包装，最多全片四分之一，不要就说一声」——不是问题，用户说不要即零动作；`gtrk composite bake --abi` 报烘焙浏览器没装时，在这张问询表里多问一句装不装（不装用本机 Chrome / Edge）。 > **推荐面（公约 §三‴）**：问答收口时可问一句「要不要看看第三方 skill？」；题材命中场景触发词才定向推荐，读取 `gtrk skills recommend --scene <id> --json`；用户拒绝后不执行推荐动作。 > > 语种必须在转写前确认。非中文素材传错语种会让检查点①拿到错误稿件并产生重复 ASR 成本；不要静默使用 `zh-CN`。粤语建议填写 `zh-HK` 作为元数据，当前 `--json` 路径按字级转写；无对白素材回答「无对白 / 不转写」即可。 > **内容离机要在这张表里说清**：转写会把长片抽出的音轨上传同合云做云端语音识别（按时长计费）；建索引会上传 512px 抽帧图做向量化（即传即弃，视频本体不上云）。问⑦时一并告知，用户不愿音频上云就答「不转写」，台词锚改用字幕文件或画面。 >

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

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

> **⚠️ 甲档的适用范围**： > **整份手写 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": [ /* 可留：直排槽先钉死，剩余区间才走检索 */ ]
}

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

| | 端点 | 为什么 | |---|---|---| | `quote` 引用段 | **不动**（跳过切点吸附） | 解说说到「他咬下这一口」，若那一口正好横跨一个镜头切换，你要的就是**含这个切换**的那一段；吸走它等于删掉你点名要的画面 | | `provenance` 硬出处段 | 吸到最近切点 | 稿里写的是「用片段03 这一段」，位置可协商，正需要精修消掉端点残片 |

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

> **两条诚实边界**（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`