Gtrk Travel Recap

---
name: gtrk-travel-recap
description: 旅拍解说一站式成片图纸——输入一个旅拍素材文件夹（长视频或素材集），AI 理解素材、写三段式解说稿、一次确认后全自动跑完配音/建工程/拆分/B-roll/字卡/BGM/字幕，直达客户端可出片工程。当用户想「旅拍解说 / 旅行视频解说 / 把这条旅行长视频做成解说视频 / 旅拍素材做成片 / 长视频二创解说 / vlog 解说化 / travel recap」时使用本 skill。凡涉及把旅拍素材（自拍或网络长视频）做成中文解说成片，优先用本 skill 编排 gtrk CLI 全链，不要手搓单命令、别让用户逐步驱动。
---

# gtrk-travel-recap（旅拍解说 · 组合成片图纸）

把**一个旅拍素材文件夹**变成**一条中文解说成片工程**：理解素材 → 三段式写稿 → 检查点①一次拍板 → 配音/建工程/拆分/B-roll/字卡/BGM/字幕 全自动 → 客户端出片。

> **定位**：本 skill 是第一张 **structure 级组合图纸**——它不新增任何命令，只编排既有原子零件（transcript / matrix / project init / split / mg / audio lay / subtitle lay / TTS 工具）。零件的参数细节以各自 skill（`gtrk-matrix` / `gtrk-splitter` / `gtrk-mg` / `gtrk-transcript`）与 `--help` 为准，**本图纸引用不复制**；但**编排次序、检查点、配方级参数**以本图纸为准。**CLI 是手，你是脑**：写稿、切 beat、挑候选信号、产字卡颗粒、管检查点，都是你的活。
>
> **家族归位**：本图纸是**解说链**（`gtrk-narration` 正本）的旅拍垂类实例。时序铺排、引用段、出处对齐等链级条款以 `gtrk-narration` 为正本；本图纸只补充旅拍要素层（贵大奇多钩子、攻略 tips、升华笔法）。素材无自带时序的题材（科普/情感/带货）走 `gtrk-voiceover`。
>
> **本 skill 已含跑通全链需要的编排信息**。

## 一、输入契约与双场景识别

用户给**一个素材文件夹**（或多个，逗号分隔传 `--dirs`）：

| 内容 | 必须性 | 说明 |
|---|---|---|
| 视频/图片素材 | **必须** | 一条长视频（二创）或一堆素材（原创拍摄）皆可；图片会被自动运镜成动态上轨 |
| BGM 音频文件 | 可选 | 没有就走素材矩阵搜索（见检查点①） |
| 介绍类文本（txt/md） | 可选 | 有则作写稿补充素材 |

**一夹多片时检索域按场景分流**：二创场景一个夹里常躺着好几条互不相干的片，
**B-roll 检索域 MUST 收窄到正在做的那一部片本身**——`--dirs` 既吃文件夹也吃**单个素材文件**，传文件即把域收窄到该素材（见 §五 ⑦ 的★铁则）。
原创（自拍素材集）那一档整夹就是这一片的素材域，**传夹正确**。

**MUST NOT 下载二创源片 / 主体素材**：网络视频二创场景下，用户提供的文件夹就是输入，下载动作归用户。平台授权素材（素材矩阵的 BGM / 空镜）可按其签名直链落地；这条例外不适用于源片与主体画面素材。

**双场景识别**（决定理解编排走法）：
- **二创**：文件夹里是网络旅行长视频（通常含博主解说语音）→ 原片文案是写稿主料；
- **原创**：用户自己拍的素材集（通常无解说语音）→ 素材理解（describe）是写稿主料。
- 拿不准就 ffprobe 看时长与条数：单条 10 分钟以上大概率二创；几十条短素材大概率原创。仍拿不准，问用户一句。
- 原创场景的素材集常常**通篇没有对白**——那就不跑转写，下表的语种一问以「无对白 / 不转写」闭合，MUST NOT 因缺这个答案阻塞开工。

**开工三问：稿源 · 声音基座 · 源片语种**。三问开工时与双场景识别**一并问清、一张表一次问完、MUST NOT 代猜**：

| 问 | 选项与走法 |
|---|---|
| 稿从哪来 | **AI 代写**（缺省，§三 规约写）/ **用户自备稿**——跳过写稿，稿直接进检查点①过目（文风铁律不强加于用户手稿，只提示明显硬伤） |
| 声音怎么来 | **TTS 配音**（缺省，检查点①挑音色）/ **用户自己念**——拿念稿毛片先走 `gtrk oralcut` 粗剪（带稿最准；外录收音先 `gtrk audio align` 对轨），产出的粗剪工程即时间基座，§五 的「配音④→建工程⑤」两步跳过，从拆分⑥接入，后续铺排/字卡/BGM/字幕照旧 |
| **源片语种 / 方言** | 取证=**听一段 / 看片内有无内嵌字幕 / 看素材出处**；答案定 §五 ① 的 `gtrk transcript --lang`（`zh-CN` 普通话 / **`zh-HK` 粤语** / `en-US` / `ja-JP`…）。**MUST 问用户、MUST NOT 代猜、MUST NOT 以缺省 `zh-CN` 静默开跑转写**——转写是计费动作且早于检查点①，非中文素材传错语种会让检查点①拿到错误稿件并产生重复 ASR 成本。粤语建议如实填 `zh-HK`；当前 `--json` 路径按字级转写。素材无对白：答「无对白 / 不转写」即闭合 |

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

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

## 一′、素材适配闸（写稿前必过）

> 本闸判的是题材，与「有无自带时序」正交。剧情短片、摆拍表演和单一室内场景不能直接套用旅拍要素层。

**取证零新增计费**（读的都是编排里本来就要产的东西，MUST NOT 为这道闸新加一次 describe 或转写）：

- **原创场景**：读 `gtrk matrix index` / `gtrk matrix describe` 已产的 `desc`（中文视觉描述）与 `tags`；
- **二创场景**：读 `gtrk transcript` 全文。

**判据（可判定，逐条素材过一遍）**：

- 主判据——这一条**能不能回答「这是在哪、看到了什么」**（可辨认的地点 + 所见之物）。能答的占比过低 ⇒ 不适配；
- 反向命中任一即不适配：文本呈现**剧情对白**（人物一来一往推进情节）/ **摆拍表演**（演出来的而非记录下来的）/ **单一室内场景**（全片不出一个可辨认的地点）。

**命中即硬停：MUST NOT 进入写稿**（形制照 `gtrk-vlog-docu` 的立神闸）。
硬停位置是**写稿之前 = TTS 计费之前**——它与 §四 检查点①「未经确认 MUST NOT 发起计费动作」是同一条防线的**前置一层**：
检查点①拦的是「稿子对不对」，本闸拦的是「**这活该不该接**」。停下时 MUST 如实列出**哪几条不适配 + 依据原文**
（引 `desc` / `tags` / 转写里的原句，别只下结论），并给三条出路：

| 出路 | 怎么走 |
|---|---|
| ① **剔除** | 把不适配的那几条摘出去，用剩下的素材继续跑本图纸 |
| ② **改投** | 剧情 / 影视 / 游戏这类有时序但非旅拍的题材走 `gtrk-narration`（解说链正本）；素材无自带时序的题材（科普/情感/带货）走 `gtrk-voiceover` |
| ③ **照跑** | 用户坚持就照办，但 **MUST 在交付说明里如实登记**「素材与旅拍垂类不匹配、要素层（贵大奇多钩子 / 攻略 tips）多半落空」（降档路径如实登记，口径同《成片型图纸公约》） |

**两条边界写死**：agent **MUST NOT 自行判死**（决定权在用户，本闸只提名不宣判）、**MUST NOT 静默照跑**——
静默照跑会让整条链在错误题材上完成并产生不必要的计费，因此必须在此停下。

## 二、全链总览（快速成片）

```
① 理解        transcript 原片（二创）/ matrix index + describe（原创）
①′ 适配闸【必过】读 ① 的既有产物判题材（见 §一′）——不是旅拍就硬停，MUST NOT 进入写稿
② 写稿        三段式规约（见 §三）→ 解说稿 + 标题 + HashTag
③ 检查点①     【必停】稿件确认 · 画幅 · 音色 · BGM（gtrk matrix material --scope audio）· 字幕样式 · B-roll 编排量预估（§四）
④ 配音        gtrk tool audio_tts_clone（≤5000 字，句级时码直出）
⑤ 建工程      gtrk project init --tts-task <id> --canvas <WxH>
⑥ 拆分派单    gtrk split 投影 → 你写拆分稿（含字卡 overlay aux）→ split 落地
⑦ B-roll      matrix --local --dirs（二创钉单片）→ describe --plan → lay --mark-weight 0.3 --yes
⑧ 抽帧检查    对字卡挂点抽帧看底轨构图（gtrk-mg SOP）
⑨ MG 字卡     按 §六 轻量规约产颗粒 → mg lint → gtrk mg --project
⑩ BGM        gtrk audio lay --volume 0.1 --beat-align（-20dB 口径）
⑪ 字幕        gtrk subtitle lay --style <检查点①拍板样式>（用户没选用 default）
⑪′ 精剪包装   交棒 /gtrk-composite（公约 §三⁵：auto ≤ 25% → 复核 → 构建机检 → 铺轨烘焙，不停）
⑫ 交付        客户端打开工程出片（gtrk render 仅主轨快照预览，见 §八）
```

检查点①之后一路跑完不再打扰用户——**垂类示例的承诺面就是快速成片一杆到底**。
⚠️ 这条承诺**以 ①′ 适配闸通过为前提**：闸命中时的那次停顿不算「打扰用户」，它是在把钱花出去之前问一句「这活该不该接」。交付后对个别环节不满意走 §七 增量重跑，对垂类玩法本身不满意走 §七 个性化出路。

## 三、三段式写稿规约

### 通用框架层（可移植——其他垂类图纸原样复用本层）

**结构三段式**：第一部分「钩子」抓眼球保留存 → 第二部分「干货」给内容价值 → 第三部分「升华」给情绪价值。爆款四属性贯穿：快乐+知识+共鸣+节奏。

**背景检索建议**：写稿信息源除了画面与音频（字幕不一定有），
**建议**执行 agent 对素材主题的关键词做一轮背景/上下文检索（地名典故、店家来历、片名与
公开报道等），检索所得须与素材内可见事实互证后才可入稿，并标注来源。
有检索能力就做、没有不强求（能力缺席按纯素材信息写，不算违约）；检索到的**外部数字与
争议性说法宁缺勿滥**。

**文风铁律**：
- 禁模板连接词：让我们/首先/然后/最后/此外 等一律不用；
- 拒翻译腔：全部短句中文语感，无欧化从句；
- **禁「否定—转折」对举句式（最高优先级）**：禁的是整个家族，不只字面：
  - 「这不是 X，而是 Y」／「与其说是 X，不如说是 Y」
  - 「X 不仅仅是 Y，更是 Z」／「X 不只是 Y，它还是 Z」
  - 「重要的不是 X，而是 Y」／「真正的 X 从来不是 Y」
  - 「不是因为 X，而是因为 Y」／「X 靠的不是 Y，是 Z」
  - **识别特征**：先立一个没人主张过的靶子再推翻它、用对偶结构制造顿悟感、句子的信息量全在后半句而前半句只是垫脚。
  - **改法**：把后半句直接说出来，删掉前面那个假靶子。「这不是一条水渠，而是一条生命线」→「几百个村民用铁锤在悬崖上凿了三年，就为这一条水渠」。**能直接陈述的事实，绝不用对举包装**。
  - 这条也适用于标题与 HashTag。
- **禁幼稚拟声与过度儿化**（★ 打样校准）：「轰隆隆砸下来」这类拟声，换成**真实事实**（「从九十多米高处坠进谷底，比尼亚加拉还高出近一倍」）——数字与事实比拟声词有力得多；
- **风格目标 = 与原素材旗鼓相当**：原片多吸引人，解说就得配得上——贴着原片气质走，**不加分**（加分是业务化的事，走栏目风格）**不减分**。

**成片时长 = min(内容所支撑, 素材所支撑)**：
- 内容支撑：有多少真东西说多少话，素材再多也不注水；
- 素材支撑：按「30% 图片×8 秒 + 70% 视频素材时长」估算上限，稿子在写稿阶段就按上限收敛（不要等铺轨时开天窗）；把这个秒数换算成字数用下一条的折算口径（**公式本身不动**）；
- **折算口径 = 挂钟语速**（wall-clock：稿件字数 ÷ 合成音频总时长，**含**句间停顿），**按检查点①选定的那条音色取值：读 catalog 该音色的 `speech_rate_cpm`（字/分钟），并把 `speech_rate_basis` 一并报给用户（`measured` = 实测 / `derived` = 由声学参数推算）**；catalog 没给该字段（非中文音色）或拉不到 catalog 时才用**缺省 ≈330 字/分钟**，并明说这是缺省估值、**不是该音色的实测值**。3 分钟成片 ≈ **1000 字**。
  缺省 330 的依据与标定方法见 `references/speech-rate.md`，本图纸只引用该单一真值源。
- ⚠️ **MUST NOT 拿计费折算常量（240 字/分钟）推稿子字数**：计费口径与写稿口径分开，计费常量只用于估算费用。

**写后自校验清单**（逐项过，不过重写）：
- [ ] 三段结构完整、时长在 min 公式内
- [ ] 禁词零命中、无翻译腔、无幼稚拟声
- [ ] **「否定—转折」对举句式零命中**（逐句扫「不是…而是」「不仅…更是」「与其…不如」及其变体；含标题与 HashTag）
- [ ] **重复字/错字扫描**（★ 打样实锤：「下瀑布瀑布」重复字 TTS 会照念）
- [ ] 事实矫正：转写稿的明显错误（如数量级离谱的数字）按常识矫正或模糊处理，不确定的不引用
- [ ] 解说序 ≈ 素材序（二创场景：按原片游览顺序写，B-roll 时间窗天然可用）
- [ ] 同批产出：标题 3-5 个（≤30 字）+ HashTag 3-5 个

### 旅拍要素层（垂类专属）

- **钩子要素**（第一部分重点找）：贵大奇多 / 热门 IP / 名人名著 / 知名历史事件 / 全球 TOP 榜 / 奇闻轶事 / 脍炙人口；
- **干货要素**（第二部分）：攻略 tips / 游览流程 / 干货&经验 / 旅途见闻，幽默口吻、隔几句一个梗（谐音/反转/无厘头），在精不在多；
- **升华笔法**（第三部分）：思考/感悟/启发/感动，正能量收束；第一人称历数、物象隐喻收尾都是成熟笔法；
- 有文化衍生空间（历史典故/风俗人文）可适当发挥，但以原素材内容为锚。

## 三′、L1 看点 rubric · 画面投影版（供 `--highlight-weight` 使用）

`highlight` 是**镜头看点分**——服务端 VLM 对着一帧画面打 0–100。旅拍这一档的准则
（`highlight_rubric`）：

```
判这一帧对旅拍短视频有没有「看点」，0-100：
- 奇观地貌：雅丹/冰川/星空/沙漠/峡谷等罕见地形
- 极端天候光线：日出日落、逆光、雪雾、暴雨、极光
- 人文场面密度：市集、节庆、宗教仪式、当地人劳作
- 反差罕见：人与巨大景观的比例、无人区里的人造物、动物
- 规模感：能看出「有多大/有多高/有多远」的构图
低分：车内挡风玻璃前方公路、酒店房间、无主体的天空、拍糊的中间帧
```

> **分工注记（MUST 遵守）**：本 rubric 只判**镜头可见之物**。知识侧要素——地名典故、
> 历史事件、人文背景——**不进画面 rubric**，它们归写稿与背景检索（§三 通用框架层已列）。
>
> 分工是：**画面 rubric 管「这一帧值不值得看」，写稿管「这件事值不值得讲」。**
> 平淡的过渡帧判低分不等于不可用——降权不排除，候选稀疏时照样上（留空更难看）。

**传入方式**：把上面代码块**原样**存成工程目录下的
`highlight-rubric.txt`，理解那一步带上它——

```bash
gtrk matrix describe --plan <工程>/split/broll-plan.json --highlight-rubric @<工程>/highlight-rubric.txt
```

存成文件而非内联，除了免去多行转义，还留下「这条片用的是哪套准则」的可查痕迹。跑完 `gtrk matrix lay`
自动读 plan 里钉存的同一个桶，不必再传；真传了而且与 plan 钉的不同源，CLI 会**硬失败**（不静默择一）。
⚠️ 换准则重新打分要**重新看片**（1 积分/张）：客观描述缓存不被覆盖，但看点分按准则分桶，新桶没分就得重打。

## 四、检查点①（双模式共有，必停）

写完稿**必须停下**，把以下六项一次给用户拍板。**未经确认 MUST NOT 发起 TTS 与 B-roll 云端编排计费动作**。

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

> **语种不在这六项里**：它在 §一 开工三问就已定，检查点①对它最多做**过目复核**。
> MUST NOT 把语种拖到这一步才问——此时 ① 的 `gtrk transcript` 已经跑完并已计费，稿子也已按错语种写出来了。

1. **解说稿 + 标题**：正文全文贴给用户（不是给路径），标题候选列出；
2. **画幅**：问目标平台——横屏 B 站/西瓜=1920x1080，竖屏抖音=1080x1920。**素材几何与画幅不一致时明确提示**（横素材→竖画布会裁切或留边）；
3. **TTS 音色**：拉 catalog（`GET {apiBase}/task/tts/voices`，免鉴权）按内容调性挑 2-4 个候选，**每个附试听链接**（catalog 的 audition_url 字段，api.ai-mcn.tv:9000 静态直链）——用户在对话框里直接点开听。internal 标注的音色注明「仅内部成员」。也可按用户描述语义挑（「要个温柔女声」）。
   **每个候选还 SHALL 附上该音色的挂钟语速与据此推的稿件字数区间**（取同一份 catalog 载荷里的 `speech_rate_cpm` + `speech_rate_basis`，零额外往返；该字段缺席就明说「用缺省 330 估」；标定方法见 `references/speech-rate.md`）——挑音色的同时也是在挑稿子长度，别让用户回头才发现稿子长了三成。这条是**加项**，MUST NOT 削弱既有的「无试听链接 = 未完成推荐」义务；
4. **BGM 处置（双来源）**：
   - 用户有本地音乐 → 询问是否 `gtrk tool audio_separation` 伴奏分离后取伴奏（缺省建议分离——TTS 配音不与歌曲人声打架）；
   - 用户未提供 → **搜同和素材矩阵**：`gtrk matrix material "<按稿件情绪+地理文化写的检索词>" --scope audio --top-k 5 --diversity --json`
     （检索词口径见公约 §三′：**内容驱动、禁通用词、至少含一个只有这一片才成立的词**；候选
     MUST 给用户挑不许默认 top1；跨片避让由 `audio lay` 记账 + 检索缺省 `--exclude-recent` 自动完成（按成片时长可加 `--min-duration <秒>`）。身份路由与计费口径由零件持有；**版权状态要如实转述**——`is_copyright=true` = 可商用、`false` = 不可商用。矩阵成员档缺省搜全库并逐条给 `copyright_label`；用户**特意说明**只要可商用或商用发布时才加 `--commercial-only` 收紧。`upsell` 是独立顶层字段，不是候选。
     推荐 3-5 首、**每首附试听链接**（结果的 `download_url`）；`audio_type:"pure"` 纯音乐直接用，`"song"` 直接取 `accompaniment_url` 现成伴奏（零处理成本，两档都有）；注意曲长 vs 成片时长（`duration` 字段）：`audio lay` **缺省循环叠满至工程末尾、尾段裁齐**（多 clip 首尾相接，命令会打 INFO 报段数），短曲只是**接缝多一些**、不会铺一半就静音（想少几道接缝，挑曲时加 `--min-duration <秒>`）；要单次铺请显式传 `--no-loop`；
   - **试听链接义务（MUST）**：音色与 BGM 的推荐没有试听链接=未完成推荐。
   - **BGM 落地一步（MUST）**：检索出参只给签名 URL，而 `gtrk audio lay --file` 只收本地路径。拍板后先把选中曲落成本地文件：`audio_type:"song"` 取 `accompaniment_url` 伴奏版，`"pure"` 取 `download_url`。文件名按 `bgm-<曲名>[-伴奏].<扩展名>`，供跨片避让记账使用。
5. **字幕样式**：7 种样式（default/outline/cinema_yellow/immersive_box/wide_spacing/deep_shadow/boxed）× 11 色（雅黑/淡绿/森林绿/湖蓝/道奇蓝/钢蓝/浅粉红/深橙/珊瑚橙/橙红/土豪金）挑选；**用户没选就用 default+雅黑**（不追问不阻塞）。拍板值在 ⑪ `gtrk subtitle lay` 落地，客户端里仍可整轨换样式（悔棋通道）。
6. **B-roll 编排量预估（本地素材路必报）**：本地素材产的 plan 走 `matrix lay` 时缺省即云端编排并按编排量计费（`--arrange local` 不受理）。先拿数再拍板：

   ```bash
   gtrk matrix lay --project "<工程目录>" --arrange-estimate-only --json   # 停在计价确认之前：零云端调用、工程文件零改动
   ```

   把它与 TTS / describe 的预估**同屏**报给用户，一次拿到同意——§五 ⑦ 的 lay 才允许带 `--yes`。**报不出这笔就不许开跑**。

## 五、快速成片编排（打样验证过的真实命令）

> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：文本产物写入 CLI 返回路径或用户显式指定的 `-o, --out`；交付物直接写入工程目录；引用媒体用原路径，不复制到 agent 工作目录；临时文件放系统 temp，用完即删。
> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。

```bash
# ① 理解（二创：转写原片，--json 顺产 transcript.json 备用）
gtrk transcript "<原片>" --lang <zh-CN 普通话 | zh-HK 粤语 | en-US | ja-JP …> --json -o "<工程目录>/transcript/<片名>-transcript.md"
#   ↑ 产物落点：不带 -o 时两个产物都落**源片同目录**（`<名>-transcript.md`；--json 另产 `<名>-transcript.json`，
#     .json 跟随 .md）。缺省本身是在案设计，但二创素材多在用户素材库里 ⇒ SHOULD 用 -o 挪进工程目录（见本节顶部纪律块）
#   ↑ 语种取开工三问的答案，MUST NOT 拿缺省 zh-CN 顶上去 —— **但这条对「非中文」素材才有钱可省**：
#     粤语 SHOULD 如实填 zh-HK（元数据诚实 + 备将来链路切换），当前链路下它与 zh-CN **对粤语无差别** ——
#     CLI 写死 word_level: true（src/commands/transcript.ts:178）⇒ 链路钉在豆包、到不了 Whisper
#     （infra utils/process/media/audio/asr.py:44-49 在 AsrFunc.Whisper 分支里仍把 word_level_handler 钉成豆包）；
#     而豆包字典里 zh-CN 与 zh-HK **都映射空串**（utils/partner/volcengine/doubao_llm_asr.py:36-37）
#     ⇒ 两种写法发出的请求逐字段相同。粤语能识别对，靠的是豆包空串模式自己的方言自适应，与这个参数无关。
#     "zh-HK": "yue" 那条映射真实存在（utils/partner/openai/__init__.py:18），但只在 word_level=false
#     走 Whisper 时生效，CLI 今天走不到那条路。
#   ↑ **MUST NOT 以「粤语语种传错」为由重跑转写**：la 进 ASR 缓存键（asr_result_cache.py:71-75），
#     换码必然 cache miss，白扣一次时长换回逐字段相同的请求与同一份结果。
# 原创场景改跑：gtrk matrix index --dirs "<素材夹>" && gtrk matrix describe --materials ...
#   ↑ **这个 `&&` 现在真的会拦住**：全域零枚举（一个素材都没枚举到）是**硬失败**（退出码 1），
#     `describe` 不会执行 —— 这是改对了：以前 index 报 0/0 也 exit 0，`describe` 会对着空清单空跑一趟。
#     报 0/0 先看两件事：路径里有没有**英文半角逗号**（有就把 --dirs 重复传 `--dirs "A" --dirs "B"`，累加不覆盖）、
#     素材夹里有没有断链。⚠️ 「个别素材处理失败」不算硬失败（那是既有 failed 计数口径，退出码仍 0）。
#   ↑ 原创（自拍素材集）这一档**整夹即该片素材域，传夹正确**，不受 ⑦ 那条「钉单片」铁则约束——
#     那条治的是二创：一个夹里躺着几条互不相干的片，才会互相抢候选

# ②③ 写稿（你执笔，§三规约）→ 检查点①拍板
#   BGM 候选（用户没自带音乐时，检查点①之前搜好一起拍板；试听链接=结果的 download_url）
gtrk matrix material "<情绪+地理文化检索词>" --scope audio --top-k 5 --diversity --json

# ④ 配音（音色 code 用 catalog 的 voice_id；稿子存 txt 传 --text-file）
gtrk tool audio_tts_clone --text-file <稿.txt> --speaker <voice_id> --json

# ④′ 语速回校（零成本自我标定；快速成片照跑不停顿，只汇报）
#   实测挂钟语速 = 稿件字数 ÷ 音频实际时长（时长取 ffprobe duration；字数口径同服务端：Unicode 码点、含标点与英文数字）
#   与写稿时所用的估值比对：**偏差 >15% MUST 在交付汇报里点名**（报「估 X / 实测 Y / 偏 Z%」），
#   并按 references/speech-rate.md 的五项格式追加本片标定记录，供后续估值复核。
#   MUST NOT 自动改稿、MUST NOT 自动重跑 TTS：改稿得从 ④ 重跑（TTS 变=全链时码变，⑤起全部重建）、要重付 TTS 费用，返工与否是用户的决定。

# ⑤ 建工程（画幅按检查点①拍板；产物目录含 gtrk/transcript/audio）
gtrk project init --tts-task <TTS任务id> --canvas 1920x1080 --no-open --json
#   ↑ 产的 transcript 文稿缺省去逗号句号（成片字幕口径）；要**带标点的文稿版本**
#     （回头改稿、转投他处、给人读）加 --keep-punctuation，工程结构与时码不受影响

# ⑥ 拆分：先投影拿句表，再写拆分稿，再落地
gtrk split --project "<工程目录>" --json          # 投影：拿 utterance id/时码/hash
# 你写 split/visual-split.json：beat 全覆盖（配音工程无 A-roll 画面，留隙=黑屏！）、
#   lane 全 FILM_BROLL、base_track="旁白主导"、narrative 用八枚举、
#   字卡挂 aux_layers type:"overlay"（handoff.category:"overlay"+duration_hint，进 dispatch.mg）、
#   看点关键词圈 handoff.anchors（[{keyword,utterance,query}] ≤2 个/beat——地名/奇观/数字头衔类实词，
#   铺轨把锚 query **原始 sim 最高的合格命中**（原始检索相似度，不是 mark/highlight 融合分）
#   钉在关键词说出时刻：听到「野牛高速」的瞬间看到野牛；锚预留优先于普通序贯槽消费，
#   取不到第一名时锚 outcome 如实报名次与去向；圈定指引见 gtrk-splitter）
#   ⚠️ 上面这串是**非穷举**摘录（另含 irreplaceability / rhythm / visual_task / container_stage 四个必填项）：
#   beat 必填字段全表以 gtrk-splitter 的 references/field-schema.md 为准，MUST 照该表写全
gtrk split "<拆分稿>" --project "<工程目录>" --json
#   ↑ 落地后走一遍 §六 末的**字卡自检清单**：数 type:"overlay" 的 aux 条数、核对 --json 回执里
#     queues.mg 的条数是否落在「每片 2-4 颗」

# ⑦ B-roll 三连（describe 给字卡抽帧检查与 mark 加权供料；internal 用户 describe 免费）
# ★ 铁则（口径同 gtrk-narration 与 gtrk-matrix，不许长出第二种说法）：解说链**一稿对一片**——
#   二创场景 --dirs MUST 钉到**这一部片的绝对路径**，**不许传素材夹**。传文件就是把检索域收窄到该素材；同夹多片时一次实测 187 条候选中有 86 条来自邻片（46.0%），不能把邻片结果当作次优解。
gtrk matrix index --dirs "<这一部片的绝对路径>" --json
#   ↑ 二创也要先建索引（原来 index 只挂在原创分支下，于是只能顺手对整夹建、正好把三条片灌进同一个 index.db）；
#     如果整夹已有索引，**不必重建**，检索侧传单片即可收窄（判据是路径前缀，传的就是那一条素材本身）
gtrk matrix --project "<工程目录>" --local --dirs "<这一部片的绝对路径>" --lay 0 --json
gtrk matrix describe --plan "<工程目录>/split/broll-plan.json" --yes --json
#   ↑ describe 结果里的 usable_flags 由你裁定（text_overlay 命中=撞原片字幕区,考虑换段或保留交客户端悔棋）
#   ↑ 同时读 describe 输出的**剔除风险**清单：候选数 ≤1 的 beat 一删就掏空
#     （音频驱动 ⇒ 整段黑屏或跨 beat 借片；口播 ⇒ 露 A-roll）。先补素材再剔，MUST NOT 见 flag 就删。
#     候选稀疏时先补素材再剔除，按 flag 直接删除可能掏空整段
gtrk matrix lay --project "<工程目录>" --mark-weight 0.3 --highlight-weight 0.2 --gap-fill fast --yes --json
#   ↑ --yes 的前提是**编排量预估已在检查点①（§四.6）报过并拿到同意**；MUST NOT 未经同意就带 `--yes`。
#     不带 --yes 且无 TTY 时本步**整轮铺轨中止**、工程零改动（plan 照常可用、可重跑）——
#     未报预估或未取得同意时不要继续执行

# ⑧⑨ 字卡（§六 规约产颗粒 → lint → 铺）
gtrk mg lint "<工程目录>/mg/<composition_id>.html" --dispatch "<工程目录>/split/dispatch.json"
gtrk mg --project "<工程目录>" --json

# ⑩ BGM（音量口径见下；<bgm> 是**本地文件**，检查点①拍板后先落地——URL 传给 --file 必炸）
# BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
# 不得用 download_url 原曲（人声与配音会打架）；"pure" 取 download_url。
# 文件名 bgm-<曲名>[-伴奏].<扩展名>：跨片避让按**标题归一化键**记账（剥 bgm- 前缀与伴奏/instrumental/off-vocal 后缀），乱命名=下一轮 --exclude-recent 失准
# --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

# ⑪ 字幕（样式/颜色 = 检查点①拍板值；用户没选用 default/雅黑；零计费——拆行走云端 subtitle_line_split 0 积分留痕，离线可加 --offline 用本地拆窗、重跑幂等替换）
gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --json

# ⑪′ 精剪包装：见下方引注
```

> **⑪′ 精剪包装**：交棒 `/gtrk-composite` 做**精剪包装**（公约 §三⁵：快速成片 auto ≤ 25% → 逐窗口复核 → 构建机检 → 铺轨烘焙，不停；回执列「做了 / 建议了没做 / 烘焙结果」；逐步推进按合成 skill 两个检查点停；开工时用户说了不要就跳过）。旅拍主画面多是素材本身，按「没有讲者」口径只用 B-roll 与排版。

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

**配方级参数口径**：
- `--mark-weight 0.3`：美观度加权起步值（mark 缺失素材中性不受罚）；
- `--highlight-weight 0.2`：看点加权，配 §三′ 的 rubric——
  **须在 describe 那一步带 `--highlight-rubric @<工程>/highlight-rubric.txt`**，
  不带就是按服务端缺省准则打分，旅拍这一档的奇观地貌/极端天候/规模感全不算数。与 mark 正交——
  mark 判「好不好看」、highlight 判「有没有看点」。两权之和 0.5，语义仍占一半，
  **MUST NOT 加到语义压不住**（那会变成「专挑好看的，不管说的是什么」）。
  ⚠️ 两个权重与 blurry 降权**都依赖 `matrix describe --plan` 跑过**（编排 ⑦ 那一步）；
  没跑就是全部候选中性、排序与不开权重逐字节一致——lay 会就此打告警，看到就说明漏了；
- `--gap-fill fast`：主轨空洞按**五级**依次填——放宽地板取剩余候选 → 段界内延长相邻颗粒 → **跨 beat 借未消费候选** → **次地板补真画面** → 仍不够才落黑片。借来的画面与本段稿子相关性可能较弱，次地板槽可能很短；两者都会在日志里指名报出。CLI 缺省是 solid，本配方须**显式传 fast**；
- 句界吸附（`--cut-align`）默认 0.7，约七成字幕句起点贴近镜头切点，其余有意错开；
- **BGM 音量口径 = -20dB（线性 0.10）**：BGM 作为垫底，`volume` 字段只写线性增益；客户端需要更响时再调整。
- 时间窗（`--source-window`）：二创场景解说序≈素材序时按 beat 对应的原片区间约束检索（可选增强，全库检索在几百场景规模下命中率已够）；
- 素材不二用、候选片段自带纯黑底与空档补黑、层序（common<concept<local，契约=大号在上；旧工程的黑底垫轨在最低号）均由 lay 内建，MUST NOT 绕过。

## 六、MG 轻量字卡规约（旅拍向最小集，不建栏目 skill）

> 本节采用「因势象形、不建栏目 skill」原则：风格锚定本片内容，不强行套用预设模板。原则正本见《成片型图纸公约》§三。

快速成片**禁留白**——字卡按下述规约直接产好叠上，用户不满意在客户端删，别等确认。

- **内容**：地名字卡为主（地标名中文+英文/头衔副标），可加里程/价格数字卡；每片 2-4 颗、挂在地标出场句（拆分稿 aux_layers overlay）；
- **形态**：左下安全区地名条——竖色条装饰+半透明深色衬底圆角条+主标题（60px 级粗体白字）+副标题（28px 级 75% 白）；透明叠加不挡画面主体；
- **动效**：入场滑入淡入约 1.5-2s → **定格驻留到坑位末尾**（gsap-emit v1 铁律⑦：时间线总长≥坑位+0.3s，禁全局渐隐）；
- **工艺**：严格按 `contracts/gsap-emit-v1.md` 颗粒骨架（`<template>` 包裹/1920×1080/`gsap.timeline({paused:true})`/`__timelines` 注册/无随机无时钟/lib.baomitu.com GSAP CDN）；字体用渲染字体注册表在册族（如 `Alibaba PuHuiTi`）；实心衬底写子层不写根（铁律 4）；
- **产前抽帧**（overlay 必做）：对挂点用本地 ffmpeg 抽 1 帧看底轨明暗与主体位置（临时文件落系统 temp 用完即删）；
- 产物存 `<工程目录>/mg/<composition_id>.html`，逐颗 lint 过了再铺。

**字卡自检清单**（形制同 §三「写后自校验清单」）：

- [ ] 拆分稿写完，**数一遍** `aux_layers` 里 `type:"overlay"` 的条数，是否落在**每片 2-4 颗**；
- [ ] 落地后核对 `gtrk split --json` 的 `queues.mg` 条数，与上一条对得上、且仍在 2-4；
- [ ] 不足按地标出场句补挂；超出按「稀缺才有力」裁掉。

> 这是图纸层的审美自检，不是 CLI 通用硬闸：`split` 与 `mg` 负责报告实际条数，是否在 2–4 颗由本垂类图纸裁定。
> 补在缺口上最省，**零代码变更**。⚠️ 反方也如实记：颗数是 `dispatch.mg.length` 一行就能算的机器可判量，
> 若这类漂移反复发生，改上「通用可选入参 + 由图纸传值 + 非致命告警」是正当的。

## 七、增量调整与个性化出路（垂类示例定位）

**本图纸是解说链的垂类示例，承诺面只有快速成片**（检查点①一次拍板后一杆到底；决策前置三条腿照公约执行，单模式不豁免）。交付后对**个别环节**不满意，用下表增量重跑悔棋——改哪步跑哪步，不整链重来：

| 环节 | 暂停点产物 | 调整方式 | 增量重跑 |
|---|---|---|---|
| 写稿 | 解说稿 vN | 用户改意见 → 你改稿 | 改稿后从 ④ 重跑（TTS 变=全链时码变，⑤起全部重建） |
| 拆分 | split/view.json + 拆分稿 | 改 beat 划分/queries | `gtrk split <拆分稿> --project` 重落 |
| B-roll | broll-plan.json | 编辑 plan（删候选/换段/pinned 钉选） | `gtrk matrix lay`（消费 plan **零检索**；⚠️ 本地素材路的**编排仍按编排量计费**，不是零计费——重跑前照 §四.6 再报一次预估） |
| 字卡 | mg/*.html | 改颗粒 HTML | `gtrk mg --project --only <beatId>` 单颗重铺 |
| BGM | audio_track | 换歌/换音量 | `gtrk audio lay` 同文件幂等替换 |
| 字幕 | cve 字幕 lane | 换样式/颜色 | `gtrk subtitle lay --style/--color` 重跑幂等替换（手加 text 不受影响）；逐条微调在客户端 |
| 精剪包装 | `composite/plan.md` + 合成颗粒 | 不要某颗 / 补一段 | 客户端关合成轨可见或删那一颗；补做走 `/gtrk-composite` 指定区间（`plan --range`） |

改口播轨后 matrix/mg 消费侧自带现场重投影，无需回跑 split。

**个性化出路**：对垂类玩法/审美**本身**不满意（想要另一套写稿腔调、字卡风格、节奏观），MUST NOT 在示例图纸上堆个性化补丁——引导用户用 `gtrk-style-maker` 建**他自己的**垂类 skill。示例图纸演示的是链路怎么跑，真正个性化的项目工程归用户自建的 skill 持有；示例对它差着火候是**定位使然**，这句丑话开工时就说。

## 八、交付与出片

- **成片出口 = 客户端**（OpenCut Gitruck Edition「打开工程」选 `gtrk/project.gtrk`）：多轨合成（B-roll+字卡+黑底+双音轨混音）只有客户端出片链完整支持；
- **`gtrk render` 仅是主轨快照预览**（★ 打样误用教训）：只渲一条视频轨、不合成字卡 overlay——可以当粗查混音与 B-roll 落位的预览片，**MUST NOT 当成片交付**；
- **云渲必拒**：含本地 B-roll 的工程提交云渲会被直接拒绝（`local_broll_cloud_render_rejected`）——出片走客户端本地导出或 `gtrk render` 预览，如实告知用户；
- 交付话术：报产物目录+客户端打开指引+各环节计费实耗；候选轨小眼睛切换、字卡可删可改、BGM 音量客户端可终调、字幕客户端可整轨换样式——把悔棋通道讲清楚。
  - 报计费实耗 SHALL 转述 `--json` 的 `credits_estimated`（**实耗口径**，豁免时为 0），MUST NOT 转述 `credits_would_be`（原价）；`exempt_probe:"failed"` 时须注明『身份没探到，此数按非豁免保守估』。

## 九、计费速查

| 环节 | 计费 | 备注 |
|---|---|---|
| transcript 转写 | ASR 按分钟 | 二创场景一次 |
| matrix index（embed） | 会话计量按实际用量 | 同合云内部成员豁免 |
| matrix describe | 1 积分/张 | 内部成员豁免；同帧缓存永不重复计费 |
| **B-roll 云端编排（`matrix lay`，本地素材路）** | 按「**编排量**」计费（服务端复算为准） | 缺省即走云端（`--arrange local` 已不受理）；素材矩阵路的编排在本机跑、不计费。预估用 `--arrange-estimate-only`（§四.6），跑前须已拿到同意 |
| TTS 配音 | 按成本档 1-12 积分/计费分钟（240 字/分钟折算） | **计费分钟按标准语速折算，不等于音频实际时长**；音色 catalog 可查档位；同参重合成走缓存不重复扣费 |
| project init / split / audio lay / subtitle lay | 0 积分 | **`matrix lay` 不在此列**（见上一行的云端编排）；producer 同步口 0 元留痕；beat 分析（--beat-align）走 audio_music_analyze 计费 |
| BGM 矩阵搜索（`gtrk matrix material`） | 公开口 1 积分/次；矩阵成员口 0 积分 | 档位由零件自动路由，命令输出如实报口径与计费 |
| image_move 图片运镜 | 2 积分/张 | 素材夹含图片且被选中上轨时 |

> ★ **脚注（划界）**：表里那个 **240 字/分钟是计费折算常量**，
> **MUST NOT 用于写稿篇幅估算** —— 写稿口径在 §三（挂钟语速，按音色取、缺省 ≈330），两者保守方向相反。
> 本脚注**只划界，不动**该行的积分档位与计量单位（单位口径归 infra `refactor-billing-measure-kchar` 的 CLI 联动件）。

起跑前把预估总消耗报给用户（检查点①一并确认），结束报实耗。
**§一′ 适配闸命中而中止时，已经发生的计费（transcript / index / describe）SHALL 如实报出**——MUST NOT 只报一句「已中止」把账藏起来。

## 十、已知边界与排障

- **闪帧**：VFR 素材的场景切点可能产生闪帧（专项修复中）——用户报闪帧时告知已立案，客户端可手动微调切点避开；
- **拆分注释投影**：客户端暂不显示 beat 注释（调查中）；
- **字幕**：⑪ `gtrk subtitle lay` 已直接上好（7 样式 × 11 色，客户端可整轨换样式、逐条可编辑）；改稿重跑 TTS 后须重跑 subtitle lay（时码变了）；
- describe 的 `text_overlay` 信号命中多为撞上原片烧录字幕区（片头片尾高发）——裁定换段或保留交客户端；
- `matrix lay` 拒铺（`tracks_edited`）不是失败：用户在客户端动过候选轨，plan 照产（`planReusable:true`），提示用户后按其意愿 `--replace-all` 或保留；
- BGM 曲长 < 成片：缺省**循环叠满至工程末尾、尾段裁齐**（多 clip 首尾相接，命令打 INFO 报段数）；要单次铺才传 `--no-loop`。

---

## 改工程：走 `gtrk patch`，不要裸手改 JSON

跑完之后要**微调某个片段**（挪位置 / 改时长 / 切开 / 改音量）时，一律用 `gtrk patch`：

```bash
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`）：改一份不改另一份，客户端优先读 `clip_ed`、后端又不强校验它 ⇒
**没人报错，成片却用了陈旧出点**。`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。

> 参数手册在 `AGENT.md` 的「元素级编辑：`gtrk patch`」一节与 README 命令参考。
> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。