@gitruck/cli 1.0.5 → 1.0.7

package/skills/gtrk-narration/SKILL.md

@@ -0,0 +1,249 @@
+---
+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 代猜；一张表一次问完，不碎问。
+
+## 三、时序铺排三档（本图纸的技术正本）
+
+每段叙述配什么画面，按下面三档路由，**高档优先**：
+
+> **⚠️ 甲档的射程已收窄（260828 主理人拍板 adjust-narration-alignment-first）**：
+> **整份手写 plan（免索引直排）降级为「引用段与硬出处段专用」**，叙述段缺省不再走它。
+> 原因是走查实锤——手写 plan 断掉的不止「对齐」，而是**整条质量流水线**：
+>
+> | 信号 | 断在哪 | 后果 |
+> |---|---|---|
+> | `mark` 美观度 | 无检索 plan ⇒ `matrix describe --plan` 无作用对象 | `--mark-weight 0.3` 全部候选中性，30% 权重原样回吐 sim |
+> | `highlight` 看点 | 同上 | 看点排序不生效 |
+> | `blurry` 模糊 | flag 随 describe 注入，同上 | 糊帧与清晰帧同权 |
+> | `motion` 高运动 | 手写 `segments` 不带该字段 | 抖/摇段不降权 |
+> | `cuts` 切点 | 同上 | **端点残片收缩失效 = 闪帧的机制性根因** |
+>
+> 260828 三条美食片实测 `describes` 行数为 **0**——`--mark-weight 0.3` 明明传了，一分没参与。
+> 这也解释了当时「低清 scdet 事后吸附零改善」：那是在成片上补救，根因在 plan 侧信号缺失，补不回来。
+>
+> ⇒ **叙述段缺省走「出处窗内检索」**（见下方「甲′」），既保出处准、又拿回五条信号。
+> 用户坚持免索引时照办，但 **MUST 先把上表的代价说清**——它不是「快一点」，是质量档位下降，
+> 且 MUST 在交付说明里如实登记本片走的是降档路径。
+
+### 甲 · 锚定直排（出处优先，最高档）
+
+**检索再聪明也是猜，出处不用猜。** 稿段与素材区间的对应关系在写稿阶段就建立：
+
+- **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 纯黑，补窗即愈）；
+> ⑤ **beat 粒度＝关键句粒度，按七三开编（主理人原则，260828 双向实证）**。先认清机制：
+> `matrix lay` 在 beat 内按候选分数贪心铺满、**槽序与句序无关**——一个 beat 跨多句时，
+> 只有「领衔句」能拿到为它挑的画面，其余句是跟随。由此定编排法（**顺序不可颠倒**）：
+> **①关键词卡点先行**：先挑出有明确视觉指涉的句子（实体/动作/可拍之物），逐句独立成 beat、
+> 一 beat 一窗，保证「稿说什么就给什么」。**划分判据是「素材里有没有」，不是「句子抽不抽象」**
+> （主理人 260828 定调：卡不到别硬卡，能卡到就不许不卡）——素材里有对应画面的句子 MUST 卡点
+> （哪怕它夹在抽象段里，如「昨天的老汤兑进今天的新汤」有汤锅镜头就必须给汤锅）；素材里
+> 确实没有的才允许降为跟随（「卖过三十年汽车」片里无车、「多线程游戏」无从拍）。判据的
+> 落地取证=渲后 `gtrk qc --alignment`：**卡点句 mismatch MUST 收敛到 0，且每一条 mismatch
+> 都要先问「是我窗选错了，还是素材真没有」**——260828 实测两种错各中一次（「一锅汤卖完打烊」
+> 素材有标牌镜头却被我把窗猜到别处 = 能卡没卡；u0016 老汤该卡却被我编成跟随 = 该严没严）；②**其余填坑**：抽象句、数字句、修辞句、情绪句
+> （日期/克数/"比太阳起得早"/"多线程游戏"）**没有对应画面可给**，合并进相邻关键句的
+> 长镜头当跟随，或用主题相近的群像长镜头覆盖；③**七三开收口**：约 70% 时长逐句对齐、
+> 30% 游离创造自然感——**游离不是妥协是设计**。
+> ⚠️ **反面实证（勿重蹈）**：260828 拉面店做过一版「一句一 beat」100% 逐句对齐，
+> 32 句 32 clip、中位 3.1s 一刀，真闪帧 3→**17**，片子碎成 PPT。**追求 100% 对齐率
+> 就是在毁观感**——对齐质检的靶子是「关键句零 mismatch」，不是「rate 冲 100」。
+> 反向的错也实证过：beat 跨六句共用一窗（B02）会让四五句集体错位，对齐率压到 62%。
+> 两头都是坑，七三开是那条中线。
+> ⑥ **盲选窗必跨源镜头切点**（免索引直排的固有代价）：渲后 QC 的 flash/intra_cut 证据可反算
+> 源切点（clip_st + into_clip_sec），把中招窗的起/终点挪到切点外再重铺——260828 美食双片实测
+> 两轮「QC→重铺→复检」把真闪帧 10→3 / 8→2，一轮约去六成，两轮后收益递减即收手如实报账。
+
+### 甲′ · 出处窗内检索（叙述段缺省路，260828 新增）
+
+**出处准与检索对齐可以兼得**，不必二选一：把出处区间当**检索域**而不是当**答案**。
+
+```bash
+# 卡点句：窗收到出处邻域，让检索在窗内挑最好的那颗（而不是我盲猜一个窗）
+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` 主路（与旅拍同款）。
+  **主轨无缝铁则（260828 主理人挑刺定案）**：合成 transcript 里引用段 utterance 的 st/ed **MUST 写物理拼接位**（拼接轴上的真实起止），MUST NOT 加 ±0.1s 字幕 pad——dispatch 的 beat 轨窗派生自转写时刻，pad 会在主轨上留 0.1s 缝（三片实测各 4 处）。已有 pad 的存量工程修法：改转写引用句时刻→重导视图→重落拆分（hash 只随文本不失效）→重铺（plan 引用窗随之外扩，Δ=0 不破）→字幕重出。
+- **克制丑话**：引用段是佐料——时长占比失衡会让片子变成搬运，平台判定风险归用户（§八 一并告知）。
+
+## 五、快速成片编排
+
+```bash
+# ① 索引前置（第一步就起，不是可选项——它是质量信号的载体，见 §三 代价表）
+#    4K 长片索引慢，未提速期**与写稿/TTS/检查点①并行跑**，别串行干等
+gtrk matrix index --dirs "<素材语料>" &     # 后台起，写稿同时跑
+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）
+gtrk split --project "<工程>" --json && gtrk split "<拆分稿>" --project "<工程>" --json
+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 原曲（人声与配音打架，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`、句界吸附缺省）与旅拍图纸 §五 同源，本图纸引用不复制。
+`--highlight-weight 0.2`（260828 新增）：看点维度与 mark 正交——mark 判「好不好看」、highlight 判
+「有没有看点」（信息量/戏剧性/情绪强度/稀缺性）。看点准则按垂类走 L1 rubric（美食/旅拍图纸各持一份
+**画面投影版**）。两权之和 0.5，语义仍占一半——**MUST NOT 加到语义压不住的程度**，那会变成
+「专挑好看的，不管说的是什么」。
+⚠️ 三个权重（mark/highlight）与 blurry 降权**全都依赖 `matrix describe --plan` 跑过**；
+没跑就是全部候选中性、排序与不开权重逐字节一致。
+质检照公约 §二′「三级收敛前移」（260829 拍板，替代原「渲后必跑」）：**L1 恒开**（零成本结构自检，含闪帧风险不可判的前置声明）；**L2 落轨前**查各 beat 卡点句的画音对齐、没给到就换候选重排（`gtrk matrix lay --arrange-qc`，用户可选、按帧计费、轮数硬上限 2，到限即交付 + 残余如实登记）；**L3 渲后终检改用户可选**——本地渲交付时随渲附带（缺省质检 + `--no-qc` 逃生舱照旧），**不再为质检单独逼渲**（4K AV1 渲一遍太久）。跑过的质检结论一律随交付一句人话分层呈现（致命点名给修法/良性如实登记）。
+
+## 六、检查点①（拍板停一次；铺画面前另有一次用量确认）
+
+> ⟲ **2026-08-31 订正**：本节标题原写「必停一次，计费动作恒在其后」。前半句已不成立——
+> 本地素材的编排自该日起默认走云端并按「编排量」计费，`matrix lay` **跑前会再停一次**报预估。
+> 后半句仍成立（那次确认也在检查点①之后）。
+> **agent 纪律**：无 TTY 时 CLI 问不到人会回落本机编排并打告警——MUST 先把预估用量告诉用户、
+> 拿到同意再带 `--yes` 重跑；MUST NOT 未经同意就带 `--yes`，也 MUST NOT 看到回落告警当没事发生。
+
+稿件（含引用窗口标注）+ **出处对照表**（乙路时；低置信段标出）+ 画幅 + 音色（附试听）+ BGM（附试听）+ 字幕样式（不挑走默认）——一屏给齐一次拍板。**未经确认 MUST NOT 发起 TTS/长剪短等计费动作。**
+
+## 六′、稿句↔镜头对照表（铺轨前必给，260828 新增）
+
+候选选定、**铺轨动作发起之前**，把「哪句配哪个镜头、为什么是它」摊开给用户过目。
+出处对照表回答「这段稿从哪来」，本表回答「这段稿给什么画面」——两张表不互替。
+
+| 句 | 角色 | 稿句 | 镜头（源片@时码） | 卡片描述 | 看点 | 选它的理由 |
+|---|---|---|---|---|---|---|
+| u0007 | **卡点** | 老汤兑进今天的新汤 | 拉面店@412.3–415.8 | 汤锅特写，师傅正在续汤 | 71 | 稿句所指之物在画面正中 |
+| u0008 | 跟随 | 三十年没断过 | ↑ 沿用 | — | — | 抽象句无实指，蹭领衔镜头 |
+| u0012 | **卡点** | 一锅汤卖完就打烊 | 拉面店@262.0–265.4 | 门口「本日完売」标牌 | 88 | 窗内唯一有标牌的镜头 |
+
+三条呈现纪律：① **卡点句与跟随句要标出来**（用户一眼能看出哪些是承诺对齐的、哪些是有意游离）；
+② 附**缩略图**（公约 §二″：给用户眼睛看的，不是给 agent 看的）；③ 「选它的理由」写人话，
+不写分数——`看点 71` 是佐证不是理由。
+
+用户在这里改判的成本最低：他说「u0012 我记得片尾还有个更好的标牌镜头」，此时换窗重检索
+只花几秒；等铺完渲完再改，就是整轮返工。
+
+## 六″、验收判据（260828 拍板升级）
+
+含 B-roll 覆盖的成片，验收 MUST 同时满足两条：
+
+1. **质检观感过**（公约 §二′ 三级：L1 恒开的结构自检无致命项；跑过 L2 的则卡点句零 mismatch——到轮数上限的残余如实登记不算未过；L3 仅在本地渲交付时随渲附带，**不为验收单独逼渲**）；
+2. **`gtrk qc --alignment` 的卡点句 mismatch = 0**。
+
+> ⚠️ **判据是 lead_mismatch 归零，不是全句对齐率冲 100。**
+> 全句率趋近 100% 恰恰意味着 100% 逐句硬切——260828 实证那样做闪帧 3→**17**，片子碎成 PPT。
+> 全句 rate 只作参考量看趋势，**MUST NOT 当达标线**。
+>
+> 每一条 lead mismatch 都先问「**是我窗选错了，还是素材真没有**」：前者换窗重铺，
+> 后者把该句降为跟随并在报账里如实说明——两种处置的代价完全不同，混为一谈会掩盖真问题。
+
+## 七、双模式
+
+| 模式 | 停点 |
+|---|---|
+| **快速成片**（默认） | 开工六问 → 检查点①（必停一次）→ 一杆到底 |
+| **逐步推进** | 每步停等确认（索引结论 / 稿件 / 对照表 / 铺排结果 / 字卡 / 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`，那是给在仓库里开发的人看的，与你无关。）
@@ -99,6 +103,10 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 - **命令失败**（毛片路径错 / 鉴权失败 / 参数越界 6016 等）→ **进程非 0 退出、报错打到 stderr、stdout 无 JSON**。先看退出码，非 0 就把 stderr 的报错如实回给用户、别当成功。
 - 默认会自动打开产物目录（用户能直接看到文件）；纯脚本/无头环境才加 `--no-open`。
 - 云端处理是分钟级，耐心等命令返回。
+- **毛片 > 2 小时跑不了**：CLI 在上传前就会拦下（零抽取、零上传、零扣费），不是跑到一半才失败。
+  遇到超长毛片**先分段再逐段剪**，切段用流拷贝、秒级完成、不重编码：
+  `ffmpeg -ss 0 -t 2400 -i "<毛片>" -c copy "<毛片名>_seg01.mp4"`（2400s = 40 分钟/段）。
+  各段各出一份工程，逐段精修互不影响。
 
 ## 跑完读报告、给用户交代、按需调整（因势象形的另一半）
 
@@ -132,3 +140,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 命令参考。
+> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。