@gitruck/cli 1.0.5 → 1.0.6

package/skills/gtrk-narration/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: gtrk-narration
+description: 通用解说视频创作图纸（解说链正本）——把「一个很长的东西」（旅行素材夹/影视长片/游戏实况/探店与做饭流程记录）提炼梗概、高光与看点，用精简叙述重讲成一条解说成片工程。判据=素材语料自带叙事时序且成片尊重它；声音基座无关（TTS 配音 / 用户自己念的口播毛片皆可，稿可 AI 代写可自备）。当用户想「做影视解说 / 游戏解说 / 探店解说 / 做饭流程解说 / 把这段素材讲成一条片 / 解说视频 / 把这部片子讲一遍」时使用本图纸。旅拍解说（gtrk-travel-recap）是本链先行垂类实例。凡解说类成片，优先用本图纸编排，别直接裸跑零件。
+---
+
+# gtrk-narration（通用解说 · 解说链正本图纸）
+
+把**一个很长的东西**——旅行素材夹、影视长片、游戏实况、探店/做饭流程记录——提炼梗概、高光、看点，用精简叙述重讲成**一条解说成片工程**。
+
+> **定位**：解说链的**正本图纸**（structure 级，不新增命令，只编排零件）。旅拍解说
+> `gtrk-travel-recap` 是先行垂类实例；通用框架层（三段式写稿规约/文风铁律/自校验）
+> 正本在旅拍图纸 §三，双模式与决策前置公约见仓内《成片型图纸公约》。**CLI 是手，你是脑。**
+
+## 一、解说链判据（先想清楚这个再开工）
+
+**解说的充要条件 = 素材语料自带叙事时序，且成片必须尊重它。** 旅行有时间线、电影有剧情线、游戏有进程线、探店/做饭有流程线。
+
+由此推出两条边界：
+
+- **和长剪短的关系**：同一个输入（一个很长的东西）、两种做法——长剪短是**让它自己说**（切原声高光），解说是**你替它说**（提炼后重述）。真实解说片常是两者的混合（见 §四 引用段）。
+- **和通用配音（`gtrk-voiceover`）的关系**：素材没有自己的时间线（科普/情感/盘点，素材只是插画）→ 那是配音链的活，转 `gtrk-voiceover`，MUST NOT 用本图纸硬套时序。
+
+**素材来源边界**：解说的主体画面**只用本地素材**——素材就是被讲的对象本身，平台素材库在主体画面上是范畴错误；平台库最多补空镜/概念镜头作辅料，**缺省不掺、问了才加**。
+
+## 二、输入契约与开工六问
+
+**输入**：本地素材语料（素材夹，或单条长片——影视/游戏实况先建索引拆条）±稿件 ± 用户自己念的口播毛片。**MUST NOT 执行任何网络下载**（版权责任归用户）。
+
+| # | 问 | 怎么取证 | 决定什么 |
+|---|---|---|---|
+| ① | 素材语料形态 | 看目录：素材夹（多条短素材）还是单条长片 | 长片先 `gtrk matrix index` 建索引拆条（场景切分即时序坐标系）；影视类加转写（台词是语义+时序双锚） |
+| ② | 时序档位 | **问用户**：成片要不要按素材自己的顺序讲？ | §三 三档路由（影视缺省最严档，旅拍/游戏/探店缺省软窗档） |
+| ③ | 稿从哪来 | **问用户**：AI 代写 / 你自备稿 | AI 代写走出处共生（§三 甲）；自备稿走出处对齐（§三 乙）。自备稿喂口播对齐（`--script`）前 SHOULD 剥离舞台指示括注（「（停顿两秒）」「（插入某片段）」——没念出的字进终稿只会计入缺失段） |
+| ④ | 声音基座 | **问用户**：TTS 配音（挑音色附试听）/ 你自己念（给口播毛片） | §五 基座路由：TTS 走配音工程；口播毛片先走 `gtrk oralcut` 粗剪（外录先 `gtrk audio align` 对轨） |
+| ⑤ | 要不要引用段 | **问用户**，按题材给建议：影视/游戏强建议开，旅拍/探店可选 | §四；答不要 = 全程零引用动作 |
+| ⑥ | 画幅 | 按投放平台问；素材几何 ffprobe 取证 | 画布；横屏素材硬做竖屏有黑边/裁切，丑话先说 |
+
+> ②③④⑤ MUST 问用户、MUST NOT 代猜；一张表一次问完，不碎问。
+
+## 三、时序铺排三档（本图纸的技术正本）
+
+每段叙述配什么画面，按下面三档路由，**高档优先**：
+
+### 甲 · 锚定直排（出处优先，最高档）
+
+**检索再聪明也是猜，出处不用猜。** 稿段与素材区间的对应关系在写稿阶段就建立：
+
+- **AI 代写稿**（③=代写）：提炼时逐段带出**证据链**——每段稿标注「本段对应素材哪个文件哪个区间」（影视类从台词转写提炼，天然带时码；素材夹类从索引场景描述提炼，带场景座标）。
+- **用户自备稿**（③=自备）：补一步**出处对齐**——拿稿件逐段与素材索引/台词转写做语义对齐，产一张**稿段↔素材区间对照表**（逐段带置信度）。对照表进检查点①给用户过目：高置信段直接用，低置信段标出来请用户指认或改判（同对轨的置信门姿势——机器有把握就不打扰，没把握才请人）。用户也可以在稿里用轻量标记直接指定出处（如「【素材：片段03 2:10-2:40】」），标记段跳过对齐直接采信。
+
+铺轨时出处段**直排**：把对照区间直接写进铺轨 plan（plan 是你可编辑的清单，`gtrk matrix lay` 照单消费），零检索。
+
+> **直写 plan 操作注记（260827 美食批真机标定）**：整份 plan 可以手写——甚至**不依赖本地索引**
+> （4K 长片索引很慢，甲档直排等不起也不必等）。逐 beat 一条 query、逐出处窗一条 result，
+> `segments:[{start,end,best,score}]`（源片秒）。三条铁则：① `best` 是**窗内代表帧时刻**
+> （秒），落窗外会被校验拒；lay 取段大致**以 best 为中心**——想 start 锚定就把 best 设为
+> 「窗起点 + 意图时长/2」；② 预算三量齐足——`per_shot_sec` 按「beat 时长 / 窗数」给、**窗宽 ≥ 份额**（窗宽不足时缺口=份额−窗宽）、且**单窗实际供片有内部上限（实测 ≈12s）**：长 beat 直接把出处区间切成 ≤12s 的子窗批量给（260827 组二实测 199s beat 用 21 个 11s 子窗铺满，宽窗少窗恒留尾洞）；③ 引用段窗与配音时轴**逐秒对齐**（窗起点 = 引用音频对应的
+> 源时刻），铺后按 `clip_st 与 track_st 的差恒等` 复核零漂移；④ **口播基座下 beat 预算按
+> dispatch 的成片轴包络算**——`transcript.json` 的 st/ed 是源时码，且 beat 连续化会把句间
+> 停顿带并入下一 beat，窗预算不给足就出纯黑段（260827 组一实测 7.5s 纯黑，补窗即愈）；
+> ⑤ **盲选窗必跨源镜头切点**（免索引直排的固有代价）：渲后 QC 的 flash/intra_cut 证据可反算
+> 源切点（clip_st + into_clip_sec），把中招窗的起/终点挪到切点外再重铺——260828 美食双片实测
+> 两轮「QC→重铺→复检」把真闪帧 10→3 / 8→2，一轮约去六成，两轮后收益递减即收手如实报账。
+
+### 乙 · 语义 × 时序先验（软窗，中档）
+
+出处缺失的段落走检索，但打分 = **语义分 × 时序先验**：按稿件进度比例映射到素材时长的期望位置，偏离越远先验越低。两条铁则：
+
+- **单调性是不变量，窗宽只是参数**：窗口下界随稿件推进只进不退。违序命中须有显著语义优势才放行。单调性顺手让「素材不二用」成为自然结果。
+- **硬窗只留给剧透敏感档**（影视类 ②=严格按顺序）：窗口成为硬约束，窗外零候选。
+
+落地即旅拍图纸 §五 的 `--source-window`（时间窗约束检索）加上你在 plan 层的排序裁决——先验计算是你的活，CLI 收敛候选。
+
+### 丙 · 纯语义（低档 = 出链）
+
+②答「顺序无所谓」且素材确无时序 → 这片子按判据出解说链，转 `gtrk-voiceover` 纯语义铺排，别硬留。
+
+## 四、叙述段 × 引用段
+
+解说片的声音轨是两种声音交替：**叙述段**（你的配音在讲，画面铺素材）与**引用段**（配音停下，源素材原声原样播几秒——角色亲口说那句台词、主播原声的呐喊、巷口的现场声）。引用段是证据和情绪冲击，转述一百句抵不过原声一句。
+
+- **引用点在写稿时定**：稿件里显式留引用窗口（出处 = 甲档对照表里的区间），MUST NOT 铺轨时临时起意。
+- **切取用流拷贝**（`ffmpeg -c copy`，零重编码）；想让 AI 帮你海选可引用的高光，可先跑一遍 `gtrk long2short` 拿选段清单当候选（可选辅助，明示计费）。
+- **装配**：逐段 TTS + 引用段原声按稿序拼成总音频 → 合成 transcript（各段句级时码换算到拼接轴）→ `gtrk project init --audio <总音频> --transcript <合成转写>` 建工程（自备配音兜底路）；引用段画面 = 该源区间直排上轨。无引用段时装配退化为单条 TTS + `--tts-task` 主路（与旅拍同款）。
+  **主轨无缝铁则（260828 主理人挑刺定案）**：合成 transcript 里引用段 utterance 的 st/ed **MUST 写物理拼接位**（拼接轴上的真实起止），MUST NOT 加 ±0.1s 字幕 pad——dispatch 的 beat 轨窗派生自转写时刻，pad 会在主轨上留 0.1s 缝（三片实测各 4 处）。已有 pad 的存量工程修法：改转写引用句时刻→重导视图→重落拆分（hash 只随文本不失效）→重铺（plan 引用窗随之外扩，Δ=0 不破）→字幕重出。
+- **克制丑话**：引用段是佐料——时长占比失衡会让片子变成搬运，平台判定风险归用户（§八 一并告知）。
+
+## 五、快速成片编排
+
+```bash
+# ① 理解：素材夹/长片建索引（场景切分 = 检索域 + 时序坐标系）；影视类加台词转写
+gtrk matrix index --dirs "<素材语料>" && gtrk matrix describe ...
+gtrk transcript "<长片>" --json            # 影视/游戏类：台词与时码双锚（可选）
+
+# ②③ 写稿（甲档出处共生 / 乙路对照表对齐）→ 检查点①拍板（§六）
+gtrk matrix material "<情绪 题材 检索词>" --scope audio --top-k 5 --json   # BGM 候选附试听
+
+# ④ 声音基座（按开工④路由）
+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；乙档 --source-window + 先验排序）
+gtrk split --project "<工程>" --json && gtrk split "<拆分稿>" --project "<工程>" --json
+gtrk matrix --project "<工程>" --local --dirs "<素材语料>" --lay 0 --json
+gtrk matrix lay --project "<工程>" --mark-weight 0.3 --gap-fill fast --json
+
+# ⑧⑨⑩ 字卡（MG 临场泛化，公约 §三）→ BGM（0.10 垫底、短了自动循环铺满）→ 字幕直出
+# BGM 是带人声歌曲（audio_type:"song"）→ MUST 下载 accompaniment_url 伴奏版上轨，
+# 不得用 download_url 原曲（人声与配音打架，260827 美食批踩坑）
+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`、句界吸附缺省）与旅拍图纸 §五 同源，本图纸引用不复制。
+渲后 QC 铁则照公约 §二′：本地渲缺省质检不许关，QC 结论随交付一句人话分层呈现（致命点名给修法/良性如实登记），粗剪不豁免。
+
+## 六、检查点①（必停一次，计费动作恒在其后）
+
+稿件（含引用窗口标注）+ **出处对照表**（乙路时；低置信段标出）+ 画幅 + 音色（附试听）+ BGM（附试听）+ 字幕样式（不挑走默认）——一屏给齐一次拍板。**未经确认 MUST NOT 发起 TTS/长剪短等计费动作。**
+
+## 七、双模式
+
+| 模式 | 停点 |
+|---|---|
+| **快速成片**（默认） | 开工六问 → 检查点①（必停一次）→ 一杆到底 |
+| **逐步推进** | 每步停等确认（索引结论 / 稿件 / 对照表 / 铺排结果 / 字卡 / BGM / 字幕逐项） |
+
+差别只在停几次；三条腿自检见《成片型图纸公约》§四。
+
+## 八、版权与丑话（跑前说清）
+
+- 影视/游戏素材是第三方版权物：二创合规责任归用户，本图纸只处理用户已合法持有的本地文件，MUST NOT 代下载；
+- 引用段占比与平台二创规则的风险归用户判断，图纸义务是把占比报出来；
+- 长片索引与转写耗时和片长成正比（几十分钟量级），开跑前报预期；
+- 平台素材库不作主体画面（§一），用户明确要求补空镜时才作辅料。
+
+## 九、计费与排错
+
+- 计费大头：TTS（按字数）与可选的 long2short 引用海选（按时长）；实时价格 CLI 自动打印，**原样转述**后再动。
+- 索引/理解/本地检索按矩阵成员口径（多为免费或豁免），以运行时打印为准。
+- 排错：低置信对照段处理见 §三 乙；`6004`/上传类症状以 `gtrk-oralcut`、拼装路以 `gtrk project` 各自口径为准；其余零件症状回各零件 skill，本图纸不搬。

package/skills/gtrk-oralcut/SKILL.md

@@ -5,6 +5,10 @@ description: 智能口播剪辑闭环——把一条口播原视频(毛片)通
 
 # 口播剪辑（gtrk-oralcut）
 
+> **⚠️ 用户要的是「完整包装的成片」而非只剪干净？先去 `/gtrk-talking-head`（口播链图纸）。**
+> 那张图纸把本命令接进全链：外录音轨对轨换声 → 多段拼接 → 本命令粗剪 → 拆分/B-roll/字卡/BGM/字幕 → 客户端出片。
+> 本 skill 是**命令手册**（怎么跑 oralcut），那张是**场景图纸**（怎么串全链），配合用不冲突。
+
 把用户的口播毛片，用 `gtrk` CLI 跑通「**本地抽音频/720p → 只传抽出物（毛片永不上传）** → 云端智能口播剪辑 → 拉回三方工程文件 →（可选）**本地 ffmpeg 渲染成片**」，再把产物目录 + 三端打开方式回给用户。**CLI 是手、你是脑。**
 
 > **本 skill 已含你需要的全部信息**（参数、取值、执行、读报告、排错），照它做即可，不用也无法去查外部文档。（源仓库另有一份更全的工具无关版 `AGENT.md`，那是给在仓库里开发的人看的，与你无关。）
@@ -132,3 +136,21 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 口播工程剪好只是成片一条龙的第一站。确认 `ok=true`、`files.gtrk[0]` 与 transcript 就绪后，**别停下等用户开口**——顺势接力到视觉拆分：触发 `/gtrk-splitter`（把这条工程 + transcript 拆成 beat 级分镜派单，agent 再跑 `gtrk split` 产 `dispatch.json`），驱动后续各车道生产+铺轨。一句话交代即推进：「口播工程已就绪，我接着把它拆成分镜派单」，除非用户表示只要这版剪辑工程、暂不往下。
 
 > 原则：**agent 替用户跑 CLI / 接力 skill，用户只对话**——别让用户自己去终端敲下一条 gtrk 命令。
+
+---
+
+## 改工程：走 `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 命令参考。
+> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。