@gitruck/cli 1.0.5 → 1.0.7

package/skills/gtrk-vlog-docu/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: gtrk-vlog-docu
+description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的载体：用有限的素材，把一个故事、或一个几个思想，串联起来（形散神不散）。表达形态上是「现场同期声 × 后期旁白」双声道交替，区别于纯口播链（单一对镜说）与纯配音链（全片旁白配 B-roll）：同期声片段是内容本体不是配画，旁白只做定调层。当用户想「做一条纪实 vlog / 我拍了一堆素材想做成有深度的 vlog / 探店探险探厂记录 / 日常生活流做成片 / 旅途记录 / 野采野钓记录 / 城市漫游 citywalk / 圣地巡礼 / 取景地探访 / 挑战企划记录」时使用本 skill。凡涉及把带同期声的现场素材做成纪实成片，优先用本 skill 编排 gtrk CLI 全链，不要手搓单命令、别让用户逐步驱动。
+---
+
+# gtrk-vlog-docu（Vlog 纪实类 · 组合成片图纸）
+
+把**一批现场素材**变成**一条纪实成片工程**：素材理解 → 选档写稿 → 检查点①一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端出片。
+
+> **定位**：structure 级组合图纸，不新增命令，只编排既有原子零件。零件参数以各自 skill（`gtrk-transcript` / `gtrk-matrix` / `gtrk-splitter` / `gtrk-mg`）与 `--help` 为准，**本图纸引用不复制**；编排次序、检查点、配方参数以本图纸为准。**CLI 是手，你是脑。**
+>
+> **本体定性（★ 主理人 2026-08-25，最上位的一条，先读懂再动手）**：
+> **纪实 Vlog 是散文的载体——用有限的素材，把一个故事、或一个几个思想，最终串联起来。**
+>
+> 三个推论，构成本图纸的全部决策原点：
+> - **形散神不散**：素材可以跳跃、场景可以断裂、时间可以不连续，但**必须有一根线**。没有那根线的片子叫「相册」不叫作品（样本里质感最低的两条正是「记录了但没串起来」）。
+> - **素材有限是前提不是缺陷**：创作力体现在「用手上这些素材能串出什么」，不是「还差什么素材」。**先看素材里有什么，再决定串什么**——这是散文与说明文的分野。
+> - **先立神，再选材**：写稿的第一步不是排素材顺序，是找到那根线（§3.2）。顺序反了就会写成流水账。
+>
+> **表达形态上的定义性特征**：纪实类是**双声道交替**——现场同期声承载真实感与人格，后期旁白承载知识与升华。**同期声片段是内容本体，不是可替换的配画**。这是它区别于口播链与配音链的根本。
+>
+> ⚠️ **本图纸 v0（2026-08-25）**：类型语法基于 20 条样本片（152 min）全量转写+逐条结构分析，已定稿可用；链路形态已拍板（**C 分段拼接** + **默认保留部分毛边**），但 `gtrk project compose` 命令**尚未实现**（本图纸是长远设想，不追求近期落地）——A/C 档在 compose 落地前不可跑，B 档与「立神+选段+旁白稿」创作件随时可用。细节见 `openspec/.plans/explore-vlog-docu-skill.md` §四之二。用户要做时**MUST**先说明当前状态。
+
+## 一、输入契约与三档识别
+
+用户给**一个素材文件夹**（多个用逗号分隔）：
+
+| 内容 | 必须性 | 说明 |
+|---|---|---|
+| 现场视频素材（含同期声） | **必须** | 一条长素材或几十条碎片皆可；这是内容本体 |
+| 图片素材 | 可选 | 自动运镜成动态上轨 |
+| BGM 音频 | 可选 | 没有走素材矩阵搜索（检查点①） |
+| 文字备忘（txt/md） | 可选 | 行程单、选题笔记，作写稿补充 |
+
+**MUST NOT 执行任何网络下载**：素材从哪来归用户（版权责任边界）。
+
+### 1.1 配比档位识别（本类型独有的第一决策）
+
+先听素材里有没有可用的同期声，再定档——**档位决定写多少稿、TTS 花多少钱、成片什么质感**：
+
+| 档 | 旁白占比 | 判据 | 典型 |
+|---|---|---|---|
+| **A 同期声主导** | 0–10% | 多人在场、有对话有反应、事件自带戏剧性 | 双人探险、挑战企划、野采、探店闲聊 |
+| **B 旁白主导** | 60–100% | 单人、素材多为空镜与地点、信息/考据型 | 攻略、圣地巡礼、废墟考据、风光记录 |
+| **C 三明治换挡** | 旁白定调→同期声主体→旁白升华 | 有观点要表达、事件之上还有一层态度 | 活动纪实+吐槽、旅途+自白 |
+
+**判别动作**：`gtrk transcript` 抽听 1-2 条代表素材——转写出大量口语碎句、语气词、对话接话 → A 档；几乎无人声或只有环境音 → B 档；有对话但用户明显想表达观点 → C 档。**拿不准问用户一句**：「你是想让现场的声音说话，还是你来讲？」
+
+> **C 档是自制片里质感最高的形态**（样本实证）：纪实同期声当前段素材，中后程整段切入议论式旁白，把当天事件升华为观点+私人自白，落一句可摘录的态度句。有条件优先推 C。
+
+## 二、全链总览（快速成片）
+
+```
+① 理解        transcript 抽听定档 + matrix index/describe 建素材索引
+② 立神        ★【多轮对话·必问】与创作者访谈找出那根线，问够为止（§3.2）
+③ 选材串珠    按「神」挑素材、定幕结构（服务于神，不是按时间流水排）
+④ 写稿        只写定调层旁白（§三）→ 稿 + 标题 + HashTag
+⑤ 检查点①    【必停】神 · 配比档 · 稿件 · 画幅 · 音色 · BGM · 字幕样式（§四）
+⑥ 配音        gtrk tool audio_tts_clone（仅旁白段，★ 分段合成）
+⑦ 拼主轨      gtrk project compose（分段清单 → live 段引用原片区间 + narration 段落位）★ 待实现
+⑧ 拆分派单    gtrk split：live 段=A_ROLL/真人出镜|口播继续；narration 段=FILM_BROLL|MG/旁白主导
+⑨ B-roll      matrix --local --dirs → describe → lay（只铺 narration 段空档）
+⑩ 字幕层      吐槽/观察/进度/梗卡进 MG 派单（§六）→ mg lint → mg --project
+⑪ BGM         gtrk audio lay --volume 0.1 --beat-align（-20dB 口径）
+⑫ 字幕        gtrk subtitle lay --style <拍板样式>
+⑬ 交付        客户端打开工程出片
+```
+
+**快速成片的「免打扰」只覆盖 ⑥ 之后的执行环节**：①–⑤ 的立神访谈与检查点①**双模式都必须问**，MUST NOT 因为用户选了快速成片就跳过立神对话自行拍板——那是把创作者的片子做成 agent 的片子。用户要精修按 §七 逐步停。
+
+## 三、写稿规约
+
+### 3.1 通用框架层（原样继承旅拍图纸，勿改）
+
+**结构三段式**：钩子（抓眼球保留存）→ 干货（内容价值）→ 升华（情绪价值）。爆款四属性贯穿：快乐+知识+共鸣+节奏。
+
+**文风铁律**：
+- 禁模板连接词：让我们/首先/然后/最后/此外；
+- 拒翻译腔：短句中文语感，无欧化从句；
+- **禁「否定—转折」对举句式（最高优先级）**：八成的 AI 厌恶感来自这一种句式。禁整个家族：「这不是 X，而是 Y」「与其说是 X，不如说是 Y」「X 不仅仅是 Y，更是 Z」「重要的不是 X，而是 Y」「不是因为 X，而是因为 Y」。识别特征=先立一个没人主张过的靶子再推翻它、用对偶结构制造顿悟感。改法=把后半句直接说出来，删掉假靶子。**能直接陈述的事实，绝不用对举包装**。也适用于标题与 HashTag。
+- **禁幼稚拟声与过度儿化**：换成真实事实——数字与事实比拟声词有力。
+- **风格贴着素材走**：素材什么气质，稿子就什么气质，不加分不减分。
+
+**成片时长 = min(内容支撑, 素材支撑)**；旁白折算约 200–240 字/分钟。
+
+### 3.2 立神：找出那根线（★ 本类型的第一步，先于选材）
+
+纪实 Vlog 是散文的载体——**用有限的素材，把一个故事、或一个几个思想，串联起来**。「神」就是那根线。**没有神的片子是相册，不是作品。**
+
+**★ 立神是多轮访谈，不是单点拍板（主理人 2026-08-25 拍板）**：**神的所有权在创作者**——素材分析只能提名候选，真正的神往往在创作者的经历和冲动里，不问是挖不出来的。本 skill 在成片实战中 SHALL 围绕神与创作者做**多次沟通和确认**，问够为止；快速成片免打扰的射程只覆盖执行环节（⑥以后），**不覆盖立神对话**。
+
+**访谈协议（写稿前必做）**：
+
+第一步，agent 自答素材侧一问：这堆素材里**反复出现的东西**是什么？（一个地方的衰败痕迹、一群人的某种状态、一件事的三次反复）——据此提名 1–3 个候选神。
+
+第二步，向创作者开问（每轮 1–2 个问题，别一次倒完；按回答追问）：
+
+| 问什么 | 挖什么 |
+|---|---|
+| 拍的时候，**什么瞬间让你想按下录制**？ | 那个冲动往往就是神 |
+| 这趟结束后，**你跟朋友聊起它时先说哪件事**？ | 自然叙述里藏着真正的主线 |
+| 如果只能留一句话给观众，**你想说什么**？ | 思想线的候选 |
+| 这趟有没有**什么真话想说**（遗憾/触动/不甘）？ | Resonance 素材，有则必用无则不硬造 |
+| 有没有**不想放进片子的东西**？ | 边界，先问后剪 |
+
+第三步，收敛判据（满足其一即立住）：创作者**用自己的话**说出了神；或对 agent 提名的候选明确说「就是这个」。**agent MUST NOT 单凭素材分析自立神**；创作者的说法与素材分析冲突时，**以创作者为准**（可以提醒「素材可能撑不住这个神」，但决定权不在你）。
+
+**神的确认不止一次**：立神访谈初确认 → 检查点①随稿件终确认（此时创作者看得见神落在稿子上的样子，常会修正）→ 精修中仍可推翻重立（神变 = 稿全变，如实告知代价再动）。
+
+**神的三种类型**（选一，也可故事线套思想线）：
+
+| 类型 | 形态 | 判断标志 | 样本参照 |
+|---|---|---|---|
+| **故事线** | 一件事的发生—进展—结局 | 有开头有结尾，观众想知道「后来呢」 | 挑战企划（100 块能不能回本）、探险（能不能进去、里面有什么） |
+| **思想线** | 一个观念的提出—印证—落定 | 素材是论据，观众记住的是那句话 | 香港那条（华而不实 / 日渐衰落 / 身陷囹圄，三个意象串一个失落）、聚会那条（套路 vs 真诚） |
+| **情绪线** | 一种状态的沉浸—转折—释然 | 说不出道理但看完有感觉 | 归乡（离世—旧物—烟花）、江城夏日（重新点燃热忱） |
+
+**立神后 MUST 一句话写下来**（写进检查点①给用户确认）：
+> 「这条片是关于 ______ 的。」
+
+写不出来 = 神没立住，**MUST NOT 进入写稿**——回去重看素材或问用户。
+
+**形散神不散的操作含义**：
+- **允许**素材跳跃、场景断裂、时间不连续（散文的自由）；
+- **要求**每一段都能回答「它为神做了什么」——是铺垫、是印证、是转折、还是留白？答不上来的段**砍掉**，哪怕画面好看；
+- **素材有限是前提不是缺陷**：不要为「素材不够」而注水或强行拉长。手上有什么，就串什么——这正是本类型的创作力所在。
+
+> ⚠️ **反面案例（样本实证）**：质感最低的两条恰恰是「拍得不差但没串起来」——记录了一天的见闻，每段都成立，合起来没有神。**这是本类型的头号失败模式**，比文笔差、比素材糙都致命。
+
+### 3.3 纪实要素层（本类型专属）
+
+**★ 第一铁律：旁白只写定调层，同期声段不写稿。**
+
+这是新手最易犯的错——把全片写成解说稿，旁白盖住现场声，纪实感当场消失。写稿前先在素材序列上标出哪几段**留给现场**（有对话、有反应、有笑点的），旁白只写：
+
+| 旁白该写的 | 旁白不该写的 |
+|---|---|
+| 开场定调（人物/时间/地点/事件） | 现场正在发生的事（画面已经说了） |
+| 背景知识与硬数据（年份/造价/历史/物种） | 同期声已经讲过的内容（重复=灾难） |
+| 场景转换的过桥句（下一站是哪、为什么去） | 描述画面（「可以看到…」是废话） |
+| 攻略信息件（车程/价格/免费与否/避坑） | 替观众说笑点（笑点归现场） |
+| 结尾升华与态度金句 | 强行煽情（无坦白素材就不做 R） |
+
+**站点模块化循环（可选结构件，不是默认）**：**结构服务于神**——神是「攻略/巡礼」型（信息即价值）时，站点循环是最优结构；神是故事线或情绪线时，**MUST NOT 套站点模板**（会把散文切成说明书）。攻略型每站跑一遍——
+```
+到场定位（口播或旁白一句）→ 背景科普（旁白）→ 现场体验（同期声，让开）→ 攻略数字（旁白/字卡）→ 转场（车程字卡）
+```
+
+**攻略信息件标准化（收藏钩，样本里自制片最大的欠账）**：凡有地点/消费属性，每站必报**车程 + 价格 + 免费与否 + 避坑**，缺一项就少一分收藏价值。数字进字卡比进旁白更好用。
+
+**Resonance 素材优先（有则必用、无则不硬造）**：样本里质感最高的几条全靠**坦白脆弱**（落榜、心碎、没钱、亲人离世）与**集体记忆锚点**（城市旧地标、经典电影、老游戏）建立共鸣。写稿前问用户一句：这趟有没有什么真话想说？有就放进升华段，**没有就老实做知识与快乐，不要编情绪**。
+
+**态度金句是收尾硬指标**：升华段必须落一句**可摘录**的话（能被观众截图、能当评论区引用）。写完自问：这句话单独拎出来，有人愿意转发吗？
+
+### 3.4 写后自校验清单（逐项过，不过重写）
+
+神（第一组，先过这组）：
+- [ ] **神一句话在位**：「这条片是关于 ______ 的」写得出来且用户已确认
+- [ ] **逐段问责**：每段都能回答「为神做了什么」（铺垫/印证/转折/留白），答不上的已砍
+- [ ] **无注水**：没有为凑时长保留的与神无关段
+
+结构与文风：
+- [ ] 三段结构完整、时长在 min 公式内
+- [ ] 禁词零命中、无翻译腔、无幼稚拟声
+- [ ] **「否定—转折」对举句式零命中**（含标题与 HashTag）
+- [ ] 重复字/错字扫描（TTS 会照念）
+- [ ] **旁白零覆盖同期声段**：逐段核对，现场段是否被旁白盖住
+- [ ] **旁白零描述画面**：删掉所有「可以看到」「画面中」
+
+HKRR 四维（缺哪补哪）：
+- [ ] **H 快乐**：现场层有没有笑点/反差/失控瞬间被保住
+- [ ] **K 知识**：定调层有没有硬数据或即兴科普（无 K = 相册式记录）
+- [ ] **R 共鸣**：有没有坦白段或集体记忆锚点（无素材则跳过，不硬造）
+- [ ] **R 节奏**：有没有语音形态换挡、数字进度条、名场面前置、空镜留白
+
+抖音四目标（各至少命中一项）：
+- [ ] **评论**：开放式提问收尾 / 评论区点单机制 / 争议性观察
+- [ ] **收藏**：攻略信息件是否标准化（车程/价格/避坑）
+- [ ] **分享**：态度金句是否可摘录
+- [ ] **关注**：固定自称/口头禅/系列预告/署名卡是否在位
+
+## 四、检查点①（双模式共有，必停）
+
+写完稿**必须停下**，把以下七项一次给用户拍板。**未经确认 MUST NOT 发起 TTS 计费动作**。
+
+1. **神（那根线）· 终确认**：一句话「这条片是关于 ______ 的」+ 神的类型（故事线/思想线/情绪线）。此处是 §3.2 访谈初确认之后的**第二次确认**——创作者此时第一次看见神落在稿子上的样子，**常会修正，这是正常且被鼓励的**。**这是最上位的拍板项：神错了，稿再好也是别人的片**；
+2. **配比档位**（本类型独有）：明确告诉用户你判的是 A/B/C 哪档、旁白占比多少、哪几段留给现场声。**这一项拍错，后面全白跑**；
+3. **旁白稿 + 标题**：正文全文贴给用户（不是给路径），标注每段旁白挂在哪个位置；标题候选列出；
+4. **画幅**：横屏 B 站/西瓜=1920x1080，竖屏抖音=1080x1920。**素材几何与画幅不一致时明确提示**；
+5. **TTS 音色**：拉 catalog（`GET {apiBase}/task/tts/voices`，免鉴权）挑 2–4 个候选，**每个附试听链接**（`audition_url`）。⚠️ 纪实类的旁白与现场同期声会交替出现，**音色应贴近用户本人音色或明显区分**（避免观众困惑「这是谁在说」）——如用户本人出镜说话，优先建议同性别接近音色；
+6. **BGM 处置（双来源）**：用户自带 → 询问是否 `audio_separation` 取伴奏；未提供 → `gtrk matrix material "<按内容情绪写的检索词>" --scope audio --top-k 5 --diversity --json`，推荐 3–5 首**每首附试听链接**（`download_url`），`audio_type:"song"` 取 `accompaniment_url`。⚠️ 纪实类 BGM 要给同期声让路，音量口径同旅拍（-20dB）；
+7. **字幕样式**：7 样式 × 11 色；用户没选用 default+雅黑（不追问不阻塞）。
+
+**试听链接义务（MUST）**：音色与 BGM 的推荐没有试听链接=未完成推荐。
+
+## 五、快速成片编排
+
+> **链路形态已拍板（2026-08-25 主理人）：C 分段拼接**——全片切 N 段，每段声明 `live`（同期声段，引用原片区间，**内容本体**）或 `narration`（旁白段，TTS + B-roll 空档），由 `gtrk project compose` 按序拼主轨。设计草案见探索工件 §四之二。
+>
+> ⚠️ **`gtrk project compose` 尚未实现**（本图纸是长远设想，主理人明示不追求近期落地）。当前可跑的降级通道：**B 档（旁白主导）走配音链**（`project init`，同期声片段当带声 B-roll），命令同旅拍图纸。**A/C 档在 compose 落地前 MUST NOT 假装能跑**——用户要做时如实说明，可先交付「立神+选段+旁白稿」的创作件（§三产物本身就有独立价值）。
+
+```bash
+# ① 理解与定档（抽听 1-2 条代表素材；live 段的 in/out 时码后面全从这份转写里读）
+gtrk transcript "<代表素材>" --lang zh-CN --json
+gtrk matrix index --dirs "<素材夹>" --json          # 建本地索引（素材本体不上传）
+
+# ②③④ 立神 → 选材串珠 → 写稿（你执笔，§三规约）→ 检查点①拍板
+gtrk matrix material "<情绪+题材检索词>" --scope audio --top-k 5 --diversity --json   # BGM 候选
+
+# ⑥ 旁白配音（★ 纪实类分段 TTS，不是全片一条）
+gtrk tool audio_tts_clone --text-file <旁白段1.txt> --speaker <voice_id> --json
+gtrk tool audio_tts_clone --text-file <旁白段2.txt> --speaker <voice_id> --json
+#   ↑ 每段单独合成，compose 按段落位；同参重合成走缓存不重复扣费
+
+# ⑦ 拼主轨（★ 待实现：add-project-compose-command 落地后启用）
+# gtrk project compose --list <分段清单.json> --canvas 1920x1080 --json
+#   分段清单：agent 写语义（live: source+in/out+keep_rough / narration: tts_task），
+#   时间线时码全归 CLI（沿用 split 的「时码归 CLI」纪律）；
+#   live 段引用原片区间零切片零上传；narration 段留空档给 B-roll；
+#   产物含合并 transcript.json（live 句级时码按落位偏移 + TTS segments），下游零改造
+#
+#   ★ 毛边口径（拍板默认）：live 段 keep_rough=true——只剪长静默/明显重来/跑题闲聊，
+#     语气词与自然停顿保留（「嗯…那个…」是真实感的组成部分，MUST NOT 照口播链剪干净）
+
+# ⑧ 拆分派单（★ 本类型的车道映射，词表无需扩展）
+gtrk split --project "<工程目录>" --json          # 投影拿句表
+# 你写 split/visual-split.json：
+#   live 段      → lane:"A_ROLL"，base_track:"真人出镜"（出镜）或 "口播继续"（画面切走声音继续），无 handoff
+#   narration 段 → lane:"FILM_BROLL" 或 "MG"，base_track:"旁白主导"，handoff 按 lane 分型
+#   字幕层/字卡  → aux_layers type:"overlay"（进 dispatch.mg）
+gtrk split "<拆分稿>" --project "<工程目录>" --json
+
+# ⑨ B-roll（★ 只铺 narration 段空档，live 段 MUST NOT 覆盖）
+gtrk matrix --project "<工程目录>" --local --dirs "<素材夹>" --lay 0 --json
+gtrk matrix describe --plan "<工程目录>/split/broll-plan.json" --yes --json
+gtrk matrix lay --project "<工程目录>" --mark-weight 0.3 --gap-fill fast --json
+
+# ⑩ 字幕层字卡（§六 规约）
+gtrk mg lint "<工程目录>/mg/<composition_id>.html" --dispatch "<工程目录>/split/dispatch.json"
+gtrk mg --project "<工程目录>" --json
+
+# ⑪ BGM（-20dB = 线性 0.10）
+gtrk audio lay --project "<工程目录>" --file "<bgm>" --volume 0.1 --beat-align --json
+
+# ⑫ 字幕
+gtrk subtitle lay --project "<工程目录>" --style default --color 雅黑 --json
+```
+
+**配方级参数口径**：
+- **旁白音量 = 1.0（线性），BGM = 0.10（-20dB）**：旁白是主角、BGM 垫底；⚠️ 契约 `volume` 字段**只写线性增益、MUST NOT 写 dB**（客户端面板显示的才是 dB）；
+- **同期声段音量不动**：现场声是内容本体，保持原电平，用户在客户端终调；
+- `--mark-weight 0.3` / `--gap-fill fast` / 句界吸附 0.7：同旅拍图纸口径；
+- 素材不二用、黑片叠底、层序由 lay 内建，MUST NOT 绕过。
+
+## 六、字幕层规约（本类型的第二解说轨）
+
+**样本实证：字幕层不是被动烧字幕，是承载人格与信息的第二条解说轨。** 无语音段全靠它撑（样本里有片子近 2 分钟纯字卡蒙太奇）。四类字卡进 MG 派单：
+
+| 类 | 用途 | 样本形态 | 挂点 |
+|---|---|---|---|
+| **吐槽字幕** | 补心声、造笑点 | 「你怎么一直拍着我」「常规操作~」 | 现场段的反应瞬间 |
+| **观察字卡** | 补信息、点特色 | 「宿舍楼特色：外卖挂铁门」 | 空镜段 |
+| **信息卡** | 攻略数字（收藏钩） | 「田七炖鸡 ¥22」「停车 15 元/3 小时」 | 站点段 |
+| **进度/梗卡** | 节奏引擎、互动钩 | 「挑战完成进度:50% 评论区已追加物品」「没动静啊」 | 幕间黑屏 |
+
+**工艺**：严格按 `contracts/gsap-emit-v1.md` 颗粒骨架（`<template>` 包裹 / `gsap.timeline({paused:true})` / `__timelines` 注册 / 无随机无时钟 / 本地 vendor GSAP）；入场 1–1.5s → 定格驻留到坑位末尾（禁全局渐隐）；**产前对挂点抽 1 帧**看底轨明暗与主体位置。
+
+**快速成片禁留白**：字卡按规约先斩后奏直接产好叠上，用户不满意在客户端删。
+
+## 七、精修模式（逐步推进）
+
+每步完成即停、报告产物、等确认再推进：
+
+| 环节 | 暂停点产物 | 调整方式 | 增量重跑 |
+|---|---|---|---|
+| **立神** | 神一句话 + 类型 + 候选备选 | **随时可推翻重立**（创作者想通了、或看稿后发现不对） | 神变=全变：重走选材→写稿→⑥以后全链；**如实告知代价再动**，别默默重跑 |
+| 定档 | 配比判定 + 现场段清单 | 用户改档 | 从写稿重来（档变=稿全变） |
+| 写稿 | 旁白稿 vN | 用户改意见 | 改稿后从 ④ 重跑（TTS 变=时码变） |
+| 拆分 | split/view.json + 拆分稿 | 改 beat/lane | `gtrk split <稿> --project` 重落 |
+| B-roll | broll-plan.json | 编辑 plan（删/换/pinned） | `gtrk matrix lay`（零检索零计费） |
+| 字卡 | mg/*.html | 改颗粒 HTML | `gtrk mg --project --only <beatId>` |
+| BGM/旁白音 | audio_track | 换文件/音量/offset | `gtrk audio lay` 同源幂等替换 |
+| 字幕 | cve 字幕 lane | 换样式/颜色 | `gtrk subtitle lay` 重跑幂等 |
+
+## 八、交付与出片
+
+- **成片出口 = 客户端**（打开 `gtrk/project.gtrk`）：多轨合成（同期声+旁白+BGM 三源混音、字卡 overlay）只有客户端出片链完整支持；
+- **`gtrk render` 仅主轨快照预览**，不合成 overlay，MUST NOT 当成片交付；
+- **云渲必拒**：含本地素材的工程提交云渲会被拒（`local_broll_cloud_render_rejected`），如实告知；
+- 交付话术：报产物目录 + 客户端打开指引 + 各环节实耗；把悔棋通道讲清楚（候选轨小眼睛、字卡可删、三条音轨音量可终调、字幕可整轨换样式）。**特别提示用户去客户端调三源混音比例**——纪实类的成败很大程度在同期声与旁白的响度平衡上。
+
+## 九、计费速查
+
+| 环节 | 计费 | 备注 |
+|---|---|---|
+| transcript 抽听定档 | ASR 按分钟 | 只听 1-2 条代表素材，不是全量 |
+| matrix index（embed） | 会话计量 | 内部成员豁免 |
+| matrix describe | 1 积分/张 | 内部成员豁免；同帧缓存不重复 |
+| TTS 旁白 | 1–12 积分/计费分钟 | **仅旁白段**，A 档几乎不花钱、B 档接近配音链 |
+| project init / split / audio lay / subtitle lay | 0 积分 | `--beat-align` 走 audio_music_analyze 计费 |
+| BGM 矩阵搜索 | 公开口 1 积分/次；成员口 0 | 命令输出如实报口径 |
+| image_move 图片运镜 | 2 积分/张 | 素材夹含图片且被选中时 |
+
+起跑前报预估总消耗（检查点①一并确认），结束报实耗。
+
+## 十、已知边界与排障
+
+- **`gtrk project compose` 未实现**（形态 C 已拍板、命令待 `add-project-compose-command` 立项）：A/C 档当前不可跑，MUST 如实告知用户；B 档（旁白主导）走配音链今天可跑通；「立神+选段+旁白稿」创作件不依赖 compose，随时可交付；
+- **毛边口径已定（默认保留部分毛边）**：只剪长静默/明显重来/跑题闲聊，语气词与自然停顿保留——MUST NOT 照口播链标准剪干净；
+- **旁白盖住现场声**是本类型第一大事故：铺完先在客户端听一遍交界处；
+- **三源混音**（同期声/旁白/BGM）的响度平衡当前靠客户端手调，无自动 ducking；
+- 闪帧 / 拆分注释客户端不显示 / describe 的 `text_overlay` 撞原片字幕区 / `matrix lay` 拒铺（`tracks_edited`）/ BGM 曲长不足：同旅拍图纸口径。
+
+---
+
+## 改工程：走 `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`），改一份不改另一份 ⇒ 没人报错、成片却用了陈旧出点。`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。

package/skills/gtrk-voiceover/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gtrk-voiceover
+description: 通用配音视频创作图纸（配音链快速成片预设）——写好的稿子（或让 AI 代写）→ 配音 → 自动配画面 → 字卡/BGM/字幕 → 客户端可出片工程。适用素材为叙事服务、无自带时序的题材：知识科普、情感电台、观点输出、带货文案、盘点合集。当用户想「拿这篇稿子出条片 / 帮我写稿配音做成视频 / 科普视频 / 情感文案视频 / 把文字变成视频」时使用本图纸。素材自带时间线的解说类（旅拍/影视/游戏/探店）走 gtrk-narration，别用本图纸硬套。
+---
+
+# gtrk-voiceover（通用配音 · 配音链快速成片预设）
+
+把**一段文字**（你写的或 AI 代写的）变成**一条配好画面的成片工程**：稿 → 检查点①一次拍板 → 配音 → 建工程 → 配画面 → 字卡 → BGM → 字幕 → 客户端出片。
+
+> **定位**：配音链的快速成片预设（structure 级图纸，不新增命令）。**素材为叙事服务**——
+> 画面是插画，纯语义匹配，无时序义务；素材自带时间线的题材（旅拍/影视/游戏/探店）按判据
+> 属解说链，转 `gtrk-narration`。通用框架层（三段式写稿规约/文风铁律/自校验）正本在
+> `gtrk-travel-recap` §三，原样继承；双模式与决策前置见《成片型图纸公约》。**CLI 是手，你是脑。**
+
+## 一、输入契约与开工五问
+
+**输入**：稿件（txt/md，可无——AI 代写）± 本地素材夹 ± BGM 音频。
+
+| # | 问 | 怎么取证 | 决定什么 |
+|---|---|---|---|
+| ① | 稿从哪来 | **问用户**：已有稿 / AI 代写（代写要主题与调性） | 代写按通用框架层三段式 + 文风铁律，写完进检查点① |
+| ② | 画面素材从哪来 | **问用户，MUST NOT 硬塞**：本地素材夹（要路径）/ 平台素材库 / 两者混用 | 配音链里平台库是一等来源（与解说链相反）；本地夹先 `gtrk matrix index` |
+
+> **素材类型口径（公约 §三″）**：配音链虽以平台库为一等来源，检索仍**缺省实拍向**（`--material-class real_shot`，成员口生效）；概念/意象素材只在栏目调性本身是抽象命题时启用，且由栏目配置 `broll.material_class_policy` 持有，MUST NOT 在本图纸写死。
+| ③ | 画幅 | 按投放平台问 | 画布（B 站横屏 / 抖音竖屏） |
+| ④ | 音色 | catalog 语义检索给候选，**附试听链接** | TTS `--speaker` |
+| ⑤ | BGM 与字幕样式 | 自备给文件；没有搜候选附试听；字幕不挑走默认不追问 | `audio lay` / `subtitle lay` 拍板值 |
+
+一张表一次问完；**未经检查点①确认 MUST NOT 发起 TTS 计费动作**。
+
+## 二、快速成片编排
+
+```bash
+# ①② 写稿（三段式通用框架层 + 文风铁律自校验）→ 检查点①拍板
+gtrk matrix material "<情绪 调性 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
+
+# ③ 配音 → 建工程
+gtrk tool audio_tts_clone --text-file <稿.txt> --speaker <voice_id> --json
+gtrk project init --tts-task <TTS任务id> --canvas <WxH> --no-open --json
+
+# ④ 拆分派单 → 配画面（纯语义：平台库走云端检索，本地夹加 --local --dirs）
+gtrk split --project "<工程>" --json && gtrk split "<拆分稿>" --project "<工程>" --json
+gtrk matrix --project "<工程>" [--local --dirs "<素材夹>"] --lay 0 --json
+gtrk matrix describe --plan "<工程>/split/broll-plan.json" --yes --json
+gtrk matrix lay --project "<工程>" --mark-weight 0.3 --gap-fill fast --json
+
+# ⑤⑥⑦ 字卡 → BGM → 字幕
+gtrk mg --project "<工程>" --json
+gtrk audio lay --project "<工程>" --file "<bgm>" --volume 0.1 --beat-align --json
+gtrk subtitle lay --project "<工程>" --style <样式> --color <色> --json
+```
+
+配方口径（mark-weight 0.3 / BGM 0.10 宁低勿高 / gap-fill fast / 句界吸附缺省）与旅拍图纸 §五 同源，引用不复制。派单车道按内容走（FILM_BROLL 为主，可派 MG / AI 再现——AI 再现描述稿走 `/gtrk-ai-drama`，外部平台出片手动回铺）。
+
+## 三、检查点①（必停一次）
+
+稿件全文 + 画幅 + 音色（试听）+ BGM（试听）+ 字幕样式，一屏给齐一次拍板。改稿在这站改到满意——配音之前全部免费。
+
+## 四、MG 风格（公约 §三 执行文本）
+
+有栏目风格 skill 走栏目；没有则按**当下这片的内容**临场泛化一套自洽风格全片贯彻（配色/字体气质/动效克制度与调性绑定），MUST NOT 逐颗粒各自为政，也 MUST NOT 拿固定模板死板套片。
+
+## 五、双模式
+
+| 模式 | 停点 |
+|---|---|
+| **快速成片**（默认） | 开工五问 → 检查点①（必停一次）→ 一杆到底 |
+| **逐步推进** | 每步停等确认（稿 / 拆分稿 / 候选画面 / 字卡 / BGM / 字幕逐项） |
+
+## 六、计费与排错
+
+- 计费大头 = TTS 按字数（跑前实时价格原样转述）；平台库检索/理解按矩阵成员口径，运行时打印为准。
+- 素材夹索引、拆分、铺排、字幕纯本地零计费。
+- 排错回各零件 skill（`gtrk-matrix` / `gtrk-mg` / `gtrk-transcript` / `gtrk project --help`），本图纸不搬；文风与写稿症状按 `gtrk-travel-recap` §三 通用框架层自校验清单处理。