@gitruck/cli 1.0.5 → 1.0.7

package/skills/gtrk-food-recap/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: gtrk-food-recap
+description: 美食解说垂类图纸（解说链示例）——把探店/密着纪实长片（或自拍探店素材夹）与做饭流程记录，提炼看点后重述成一条中文美食解说成片工程。覆盖两形态：探店·密着（一家店/一顿饭/一个人的故事）与做饭流程解说（步骤线忠实重述）。菜谱知识类内容出局（那是配音链题材，走 gtrk-voiceover）。当用户想「做美食解说 / 探店视频解说 / 密着纪实翻讲 / 把这条做饭视频讲一遍 / 拉面店视频解说」时使用本图纸。链级条款（时序三档/引用段/出处对齐）以 gtrk-narration 为正本。
+---
+
+# gtrk-food-recap（美食解说 · 解说链垂类示例）
+
+把**探店/密着纪实长片**（或自拍探店素材夹）与**做饭流程记录**提炼看点，重述成一条中文美食解说成片工程。
+
+> **定位**：解说链（`gtrk-narration` 正本）的垂类示例，与 `gtrk-travel-recap` 平级。链级条款
+> （时序三档铺排/引用段/出处对齐/开工问询）以正本为准，本图纸只持**美食要素层**。
+> **菜谱知识类**（讲营养学/做法原理、素材只是插画）按判据出链走 `gtrk-voiceover`。
+> **承诺面只有快速成片**（垂类示例单模式，公约 §一 分层）；个性化出路见 §六。**CLI 是手，你是脑。**
+
+## 一、两种形态与输入契约
+
+| 形态 | 输入 | 时序档位（正本 §三） |
+|---|---|---|
+| **探店 · 密着** | 一条纪实长片（二创；带字幕文件的直接当台词锚，无则转写）或自拍探店素材夹 | 软窗档缺省：进店→点单→出品→吃→人的故事，流程线单调、允许蒙太奇跳 |
+| **做饭流程** | 一条做饭记录或素材夹 | 软窗档且**步骤线忠实**：工序 MUST NOT 乱序重排（先炸后腌是事故） |
+
+稿源与声音基座随正本开工问询（AI 代写/自备稿；TTS/自己念）。**MUST NOT 执行任何网络下载**；二创长片是第三方作品——版权与平台二创规则责任归用户，开工先说。
+
+## 二、美食要素层（写稿规约，叠在通用框架层之上）
+
+通用框架层（三段式/文风铁律/自校验）继承 `gtrk-travel-recap` §三 正本，此处只列垂类专属：
+
+- **探店三件套**：场子气质（地段/客群/烟火气）、出品与吃相（招牌菜、分量、上桌节奏）、
+  **人的故事**——密着类的魂在店主/食客身上（几点起床备料、开了多少年、常客是谁），
+  写稿 MUST 给「人」留一段，别写成纯菜品罗列；
+- **感官转译**：口感香气用**具体动作与事实**转译（「700 克米饭压得冒尖」「铁板边缘的油声没停过」），
+  禁拟声堆砌与「入口即化」式空转（文风铁律照打）；
+- **数字如实**：分量/价格/营业时间只用素材里可见可听的，MUST NOT 编造；
+  **时效丑话**：价格与营业信息随拍摄时点变动，成片引用时提醒用户自行核对；
+- **背景检索建议**（旅拍 §三 通用框架层同款，2026-08-28 拍板）：对店名/地段/菜系关键词
+  做一轮背景检索补写稿语料（店家来历、当地饮食脉络），有检索能力就做、没有不强求；
+  检索所得与素材互证后才入稿、档案标注来源；
+- **做饭流程线**：步骤忠实、关键动作给特写位（刀工/火候/翻面）、成品定格收束。
+
+## 二′、L1 看点 rubric · 画面投影版（260828 新增，供 `--highlight-weight` 用）
+
+`highlight` 是**镜头看点分**——服务端 VLM 对着一帧画面打 0–100。喂给它的评分准则
+（`highlight_rubric`）按垂类走，美食这一档取下面这份：
+
+```
+判这一帧对美食短视频有没有「看点」，0-100：
+- 大分量怼脸：食物占画面主体且分量夸张（堆尖的饭、溢出碗沿的面、整条鱼）
+- 夸张数量与价格的实物：成排的锅/几十份摆盘/写着惊人价格的标牌
+- 人山排队：门口长队、满座、等位人群
+- 名场面动作：颠勺起火、切生鱼片、拉面甩水、铁板翻面
+- 反差罕见：凌晨空店、后厨全景、老器物、店主的手
+低分：空镜过渡、无主体的墙面桌面、拍糊的中间帧、纯字幕帧
+```
+
+> **分工注记（MUST 遵守）**：本 rubric 只判**镜头可见之物**。知识侧要素——店家来历、
+> 行业内幕、地域饮食脉络、名人轶事——**不进画面 rubric**，它们归写稿与背景检索（§二 已列）。
+> 把知识侧写进来会让 VLM 对着一碗面找「历史事件」，产出一堆无意义低分并拉偏排序。
+>
+> 两侧的分工是：**画面 rubric 管「这一帧值不值得看」，写稿管「这件事值不值得讲」。**
+
+个性化：不满意这份准则的用户走 `gtrk-style-maker` 建自己的美食 skill，把 rubric 换成自己的口味
+（这正是 rubric 参数化的意义——L1 归垂类图纸持有，不硬编码在服务端）。
+
+## 三、铺排与引用段（引用正本，垂类注记）
+
+- 铺排走正本 §三：有出处直排，无出处软窗（单调先验）；做饭形态窗口更窄（工序容不得远跳）。
+- **引用段强建议开**：吃相原声、后厨煎炒声、店主原话金句——美食片的证据就是声音；
+  装配与克制丑话照正本 §四。
+
+## 四、快速成片编排
+
+命令序照正本 §五（索引/字幕锚 → 写稿+出处 → 检查点① → 基座 → 建工程 → 拆分 → 铺排 →
+字卡 → BGM → 字幕），配方口径（mark-weight 0.3 / BGM 0.10 / gap-fill fast）照旅拍 §五，引用不复制。
+BGM 检索词照公约 §三′ 内容驱动（这家店的气质：地域/年代/客群/烟火感，禁通用词套路；
+候选给用户挑不许默认 top1；跨片避让自动生效）。
+看点加权：`--highlight-weight 0.2` 配 §二′ 的 rubric（**须先 `matrix describe --plan`**，
+否则全部候选中性、权重白传——lay 会就此告警）。
+BGM 选带人声歌曲（`audio_type:"song"`）时 **MUST 下载 `accompaniment_url` 伴奏版上轨**，
+不得直接用 `download_url` 原曲——人声与解说配音打架（260827 真机踩坑）。换已上轨的 BGM 文件时
+注意：`audio lay` 同源幂等按文件路径判定，**换不同文件不会替换旧轨**，须先剥旧 BGM 轨再 lay。
+质检照公约 §二′「三级收敛前移」（260829 拍板，替代原「渲后必跑」）：L1 结构自检恒开（零成本，含**闪帧风险不可判**的前置声明）；L2 画音对齐在**落轨前**跑、`--arrange-qc` 用户可选且按帧计费；L3 渲后终检**不再逼渲**，本来就要本地渲交付时随渲附带。跑过的质检结论一律随交付呈现。
+字卡走 MG 临场泛化（公约 §三）：店名条/菜名条/价格条为主，风格锚在这家店的气质上。
+
+## 五、检查点①（拍板停一次；铺画面前另有一次用量确认）
+
+稿件（含引用窗口）+ 出处对照表（自备稿时）+ 画幅 + 音色（试听）+ BGM（试听）+ 字幕样式，
+一屏一次拍板；**此前零计费动作**（这条仍成立）。
+
+> ⟲ **2026-08-31 订正**：本节原写「必停一次」。本地素材的编排自该日起默认走云端并按
+> 「编排量」计费，`matrix lay` **跑前会再停一次**报预估——那次不是拍板，是花费确认。
+> 详见 `gtrk-narration` 正本 §六 的 agent 纪律（先报用量拿同意，再带 `--yes`）。
+
+## 六、个性化出路（垂类示例定位）
+
+**本图纸是示例**：演示美食解说这条链路怎么跑。交付后对个别环节不满意，按旅拍 §七 增量重跑表
+悔棋（同一套零件同一套姿势）；对垂类玩法/审美**本身**不满意（想要另一种探店腔调、另一套
+视觉气质），MUST NOT 在示例上堆个性化补丁——引导用户用 `gtrk-style-maker` 建他自己的美食
+skill。示例对个性化项目工程差着火候是定位使然，这句丑话开工时就说。
+
+## 七、计费与丑话速查
+
+- 计费大头：台词转写（无字幕文件时）与 TTS；实时价格原样转述后再动；
+- 二创版权、引用段占比、价格时效三句丑话开工说清；
+- 排错回正本与各零件 skill，本图纸不搬。

package/skills/gtrk-live-slicing/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: gtrk-live-slicing
+description: 直播切片图纸——把一场数小时的直播回放，拆成一批可编辑的逐 clip 粗剪工程（gtrk+剪映+PR），交给用户自己挑、自己改、自己出片。含超长源片分段规约（服务端 2h 硬闸 + 60min 轮询墙钟）、选题清单确认停点、按画面形态配分屏、源片贴片如实告知。当用户想「直播切片 / 直播回放切高光 / 把这场直播剪成短视频 / 三小时直播怎么切 / 带货直播剪片段 / 讲座直播出短片 / 录播切片」时使用本 skill。凡涉及把直播回放拆成一批短片工程，优先用本图纸编排，别直接裸跑 long2short（超过 2 小时会被服务端直接拒）。
+---
+
+# gtrk-live-slicing（直播切片 · 组合成片图纸）
+
+把**一场直播回放**（1–4 小时）变成**一批可编辑的逐 clip 粗剪工程**：四问定策略 → 分段 → 逐段选段 → **选题清单必停** → 出工程。
+
+> **定位**：第三张 **structure 级组合图纸**（前两张=`gtrk-travel-recap` 旅拍解说、`gtrk-vlog-docu` Vlog 纪实）。不新增任何命令，只编排既有零件。参数细节以 `gtrk-long2short` 与 `--help` 为准，**本图纸引用不复制**；**编排次序、分段规约、检查点**以本图纸为准。**CLI 是手，你是脑。**
+
+## ⚠️ 定位铁律（先读这条，后面全部服从它）
+
+**本图纸产的是「粗剪工程」，不是成片。**
+
+由此推出一条贯穿全文的边界：**MUST NOT 对源片做任何像素级改动。**
+
+- ❌ 不去水印、❌ 不去烧录贴片、❌ 不做画面清理美化、❌ 不调色不裁切
+- 源片长什么样，切片就长什么样。要不要动那些元素，是**用户在客户端二次编辑时的决定**，不是你的。
+- 分段所需的时间轴裁切**必须用 `ffmpeg -c copy` 流拷贝**（不重编码）——既贯彻本条，也快得多（实测 40 分钟段 **12.5 秒**切完，重编码要几十分钟）。
+
+> **用户只要能直接发的成片、不打算再剪？** 那不是本图纸的活，转 `gtrk tool video_long2short_pro`（精剪，整片上传、云端渲染、计费约两倍）。判断句同 `gtrk-long2short`：**「剪完还要不要再动？」要动 → 留这儿；不动 → 转精剪。**
+
+## 一、输入契约与开工四问
+
+**输入**：一条直播回放的**本地文件**（`.ts` / `.mp4` 等均可）。
+
+**MUST NOT 执行录制或下载**——平台动作与版权责任归用户。用户给什么文件就用什么。
+
+开工前先答四问，答案决定后面全部策略：
+
+| # | 问 | 怎么取证 | 决定什么 |
+|---|---|---|---|
+| ① | 源片总时长与几何 | `ffprobe`（或直接跑一次 `gtrk long2short` 让它打印） | **要不要分段、分几段**（§二） |
+| ② | 画面形态是否单一 | **问用户**——全程主播口播位？还是含实景走播/换机位？ | **哪些段开分屏**（§四） |
+| ③ | 有无烧录贴片 | 抽 2–3 帧看（开头/中段/尾段各一） | **交付时要如实告知什么**（§五） |
+| ④ | 入选切片要不要叠 MG 动画 | **问用户**——缺省不叠（粗剪定位） | **选题清单敲定后是否走 MG 车道**（§七） |
+
+> **②④ MUST 问用户、MUST NOT 代猜。** ②猜错的代价是白跑一轮分屏（几十分钟 + 积分）；
+> ④缺省是**不叠**——用户没要就零 MG 动作，MUST NOT 硬塞。
+> **③ 的取证目的只是「告知」，不是「处置」**——看到贴片不要动手，见定位铁律。
+
+## 二、分段规约（本图纸的骨干）
+
+### 两道闸（都是实测，不是推算）
+
+| | 闸 | 值 | 命中时的表现 |
+|---|---|---|---|
+| **闸一** | 服务端媒体探测层全局业务限制 | **2 小时** | **建单期直接拒**：`6019 媒体时长无效或超过业务限制`。**任务不创建、不计费** |
+| **闸二** | CLI 轮询墙钟 | **60 分钟** | 轮询超时报错（任务在云端照常跑完，可取回） |
+
+**处理耗时 / 源时长比值必须按分屏与否分档**（同为 40 分钟源的实测）：
+
+- **不开分屏**：3.7 分钟 = **0.09×** ⇒ 墙钟几乎不构成约束
+- **开分屏**：21.0 分钟 = **0.53×** ⇒ 分屏是墙钟压力的**主要来源**
+
+⇒ **单段 MUST ≤ 2h（硬拒线），开分屏时 SHOULD ≤ 48min（墙钟线）。**
+
+### 判据与做法
+
+**源片 > 40 分钟即 MUST 分段。** 40 是落在两条线内并留余量的取值。
+
+```bash
+# 段边界优先级：内容自然停顿（长静音/话题转折）> 等分兜底
+# MUST 用 -c copy，MUST NOT 重编码
+ffmpeg -ss 3600 -t 2400 -i "<直播回放>" -c copy "<工作区>/inputs/<名>_seg02_60-100min.mp4"
+```
+
+- 命名带上**源片时间范围**（如 `_60-100min`），后面汇总选题清单时你要靠它把 clip 定位回原片。
+- 有弹幕文件时可用热区微调边界（§六），**但不作为主依据**。
+
+### ⚠️ 两条必须在动手前告诉用户
+
+1. **切段是新文件，工程指向它、不指向原片。** 逐 clip 工程的 `materials[].path` 实指切段（已实测）⇒ **用户删掉切段文件，工程就素材脱机**。让他把 `inputs/` 留着。
+2. **超过 2 小时整条提交会被直接拒**，不是慢、是拒。好消息是零计费（不进队列），但会白抽白传一个大文件——所以先分段。
+
+### 超时兜底
+
+单段仍超墙钟时，**轮询超时属预期不属故障**：
+
+```bash
+gtrk oralcut-result <task_id>   # task_id 在产物根 task.json
+```
+
+服务端按 task_id 取结果**幂等**。**MUST NOT 重跑**——重跑是重复计费。
+
+## 三、双模式（两种都要停）
+
+**为什么直播切片必须停，而口播/TTS 不用？**
+
+口播毛片是用户**已经讲完**的内容、TTS 稿是他**已经认可**的文本——内容选择在进剪辑链之前就完成了，agent 只是执行。而一场数小时直播里「这几十个候选哪些值得做」**尚未发生、本身就是创作决策**。全自动跑完 = 替创作者行使了选题权。
+
+| 模式 | 停点 |
+|---|---|
+| **快速成片** | 四问 + 分段方案确认 → 逐段跑 → **【必停】选题清单** → 确认后一路出工程 |
+| **逐步推进模式** | 上述基础上每步都停（分段方案 / 逐段选段结果 / 逐条工程产物） |
+
+两模式共用同一套分段规约与参数配方，**差别只在停几次，不在停不停**。
+
+### 选题清单长什么样
+
+每段跑完后产物根有 `clips.md`，一张五列表（标题 / 时长 / 评分 / 简介）。**把各段的表合并成一张给用户**，标注每条回溯到原片的大致时间，让他勾。真实样例：
+
+| # | 标题 | 时长 | 评分 |
+|---|---|---|---|
+| clip1 | 别被高认知陷阱害了 | 5:40 | 8.5 |
+| clip2 | 孩子情绪稳定靠父母正反馈 | 3:06 | 8.2 |
+
+**别让用户自己开工程猜**——他要的就是这张表。
+
+## 四、按形态配分屏（不给一刀切默认）
+
+`--split-screen` **只对用户在开工②里确认含多人同框的段开**。
+
+⚠️ **静默面（务必知道）**：段内无多人同框候选时，服务端**静默跳过——不报错、不记 `errors`、不置降级标志**。所以：
+
+> **判断分屏是否真的生效，MUST 看产物证据，MUST NOT 按「没报错」推定。**
+> 证据 = `report.json` 的 `split_manifest` 条数 + 毛片旁 `split_screen/` 目录里的素材（可抽帧看）。
+
+**分屏在子轨、主轨原片可回退**（2026-08-27 起的服务端形态）：分屏素材落在独立子轨上叠放，
+主轨的原片全程完整在场——用户对某段分屏不满意时，在客户端隐藏/删除子轨该段即回退原片，
+零重跑。交付时把这条回退动线告诉用户。⚠️ 连带边界：本地 `gtrk render` 是快照渲染、
+**不合成子轨**——渲出来没有分屏画面；要分屏成片走客户端出片（或剪映导出）。
+
+其余参数配方：
+
+- `--language` **必填**，缺失在上传前就报错（省一次白上传）
+- 竖屏直播源（实测四条靶片全是 9:16）**无需转比例**，`--output-size` 缺省即可
+- `--duration-pref` / `--max-clip-sec` 按投放平台口径给档
+- `--subtitle-out` 产逐 clip **独立 `.srt`**（不烧进画面——符合粗剪工程定位）
+
+> 完整参数表在 `gtrk-long2short`，本节只给直播场景的**配方差异**，不搬手册。
+
+## 五、贴片如实告知（交付项，不是处置项）
+
+直播源片常自带烧录元素。你的义务是**说清楚**，不是动手。
+
+| 类型 | 后果 | 怎么说 |
+|---|---|---|
+| **静态标题贴片**（贯穿全场不变） | 每条切片都带一个**与自己主题无关**的标题 | 举实例给用户看：某条讲 A，画面上却写着 B |
+| **时效信息贴片**（价格 / 截止日期） | 切片再发布时是**过期信息** | 额外点一句，让用户自行判断是否适合再发 |
+| **无叠加** | — | 不必提 |
+
+> 实测参照：一条 3.4 小时讲座直播的标题贴片 **30 秒处与 9878 秒处逐字相同**（全场不变），而同段切出的 clip 主题与它完全无关；一条带货直播的分屏素材里价格贴片「安心退 / 245」原样带出。
+
+**这一节不含任何去除动作。** 用户问「能不能去掉」→ 告诉他这超出本图纸射程，可在客户端二次编辑时自行处理。
+
+## 六、弹幕（可选增强，不是必需输入）
+
+**真实场景绝大多数没有弹幕**——无弹幕是**默认路径，不是降级**。本图纸主干全部步骤在零弹幕下完整可执行。
+
+用户**确实**给了弹幕文件时，可以额外用：
+
+- **格式**：B站式 `.xml` 是 `<d p="秒数,…">用户:文本</d>`，**`p` 首字段即距开播秒数 = 源片时码**；平台导出 `.txt` 通常是时钟列。归一化成「秒 + 文本 + 用户」三元组即可。
+- **两个信号**：**复述密度**（同一句话被多个用户在短窗口内重复——观众自发复述的往往就是金句）、**刷屏密度**（互动符号瞬时峰值）。
+
+### ⚠️ 别高估它：实测弹幕对「选哪些段」几乎没有增量
+
+一次判别性实测（40 分钟段、6 个复述热点、8 条选出的 clip）：
+
+- **6/6 个热点全部落在选出的 clip 内**，而 clip 只占该段 **48%** 的时长
+- 纯随机情况下全中的概率约 1.2% ⇒ **服务端的语义选段本来就和观众投票高度同向**
+
+**结论**：弹幕**验证**了选段是对的，但**没提供选段之外的新信息**——它想告诉你的，LLM 基本已经选出来了。所以：
+
+- ❌ **不要**为了「更准地选段」去要用户补弹幕（没有就没有，主干照跑）
+- ✅ 它真正剩下的价值是 **取候选标题原句**：观众自发复述出来的那句话（如「大脑不接受否定」被 15 人复述），
+  往往比 LLM 生成的标题更有传播力。**有弹幕时，优先把这类原句作为标题候选给用户挑。**
+- ✅ 次要价值：微调段边界（别把一个热区从中间切开）。
+
+### ⚠️ 红线
+
+**弹幕 MUST NOT 当 `--subtitle-file` 喂入。** 那个入口收的是**主播口述的转写**；弹幕是观众文本，喂进去会污染选段依据。
+
+两者都是「带时码的文本文件」、形状极像，极易误用——**看到弹幕文件先想这条**。
+
+> 现实诱因实例：某创作者的弹幕就存在名为「文稿」的目录里——**目录名叫文稿，内容却是弹幕**。别被目录名带偏。
+
+## 七、二次包装（可选；全部不动源片像素）
+
+看板点名的三件，都不碰源片：
+
+- **标题钩子**：文本建议。有弹幕时优先取观众复述的原句。
+- **字幕**：`--subtitle-out` 已产独立 `.srt`，交用户在客户端决定烧不烧。
+- **封面**：走 `/gtrk-cover`（另出图，不改片）。
+
+### MG 动画（仅当开工④用户要了才做）
+
+- **时机**：选题清单敲定**之后**、只对**入选** clip 做——没入选的切片不白做颗粒。
+- **姿势**：逐 clip 走标准成片化车道（`gtrk split` 拆分派单 → 颗粒 → `gtrk mg` 铺轨），
+  素材=该 clip 的粗剪工程与 `.srt`。风格按**内容驱动的临场泛化**横切原则
+  （全部成片型图纸通用）：风格必须有，但不锚定既有风格 skill，按当下内容自由泛化。
+- **红线**：MG 是**叠加层**，照旧不动源片像素；④答「不要」= 全程零 MG 动作。
+
+### B-roll：缺省不掺（明示条款）
+
+直播切片的画面本体就是直播实录，**本图纸缺省不派 FILM_BROLL、不推销 B-roll 填充**
+——开工问询里也刻意没有这一问。用户**主动明确要求**给某条切片补空镜时，按通用
+`gtrk matrix` 车道单独走，不改本图纸主干。
+
+## 八、计费与预算速查（跑前转述给用户）
+
+- 计费基 = **上传物音频流时长**（≈源片时长），**2 积分/分钟**。
+- **分段不改总量**：切段总时长≈原片，所以分不分段花的钱差不多，分段买的是「能跑通」和「粒度更细的选题清单」。
+- 实算示例：40 分钟段 = 80 积分（实测 confirmed）；一场 3.4 小时讲座 ≈ 410 积分。
+- **建单期被拒是零计费的**（如超 2h 硬闸）——试探性提交不会烧钱，但会白传一个大文件。
+- **任务失败会自动退款**（实测失败单的计费记录状态为 `refunded`）⇒ 遇到 §九 那类瞬时故障
+  **放心重跑，不会重复扣费**。跟用户解释时可以直接这么说。
+- 运行时 CLI 自动查实时价格并打印，**把提示原样转述**；长片先向用户确认再跑。
+
+## 九、排错
+
+- **`超过最大重试次数`（本线最常见的失败形态，务必先看这条）** → 这句是**通用兜底文案、不是真因**。
+  实测多次独立观测，真因都是**外部 ASR 供应商的查询接口失败**（不是你的参数错，通常也不是源片格式问题）。
+  - **判据**：失败很快（1–2 分钟内就报，而正常 40 分钟段要跑 4–20 分钟）⇒ 卡在开头的转写阶段。
+  - **处置：先原样重跑一次**。**但要知道重试不保证成功**——实测存在**同一段连续两次都失败**的情况，
+    说明该故障**未必是瞬时的**，可能与具体音频内容相关。
+  - **重试仍失败时，别死磕同一段**：换个切点重切该时段（边界挪几分钟）、或先跑其他段把能出的先出了，
+    把这一段单独挂起问客服/换时间再试。**MUST NOT 反复重跑**——虽然失败会退款，但每次都要等。
+  - **别改参数、别一味切更短**——那会掩盖问题；先确认是不是 ASR 侧的事。
+  - 分段跑的好处在这里体现：**只需处理失败的那一段**，其余段的成果不受影响。
+- **`6019 媒体时长无效或超过业务限制`** → 单次提交超服务端 2 小时硬闸。**分段**，别重试。
+- **轮询超时** → 不是失败，`gtrk oralcut-result <task_id>` 取回（§二）。
+- **分屏没生效但也没报错** → 正常静默面（§四）。按 `split_manifest` 与 `split_screen/` 目录核实；确无多人同框就是没候选，不是 bug。
+- **clips 为空** → 该段没有可成片的高光（纯语义选段），看 `report.json` 摘要给用户解释；直播的垫场/等人段落出现这个属正常。
+- **工程打开缺素材** → 多半是切段文件被移动/删除了（§二 警告）。
+- 其余症状（部分 clip 失败 / 剪映看不到草稿 / 改工程）→ 一律以 `gtrk-long2short` 的排错节与 `gtrk patch` 为准，本图纸不搬。

package/skills/gtrk-long2short/SKILL.md

@@ -9,6 +9,11 @@ description: 长剪短闭环——把一条长视频（课程/直播/播客/访
 
 > 与智能剪口播（gtrk-oralcut）同一心智模型；差异是**一次任务出 N 条短片**，各自一份工程组落 `clip{i}/` 子目录。
 
+> **⚠️ 源片是「直播回放」？先去 `/gtrk-live-slicing`。** 直播回放有本 skill 不处理的场景约束：
+> **单次提交超 2 小时会被服务端直接拒**（`6019`，必须先分段）、选题必须经用户确认再出工程、
+> 按画面形态分段配分屏、源片自带的烧录贴片如实告知不动它。那张图纸编排完这些，
+> 最终仍然回到本 skill 的命令上——**它是场景图纸，这里是链路手册，配合用不冲突。**
+
 > **⚠️ 先确认用户要工程还是要成片。** 本 skill 是**粗剪**——出的是**可编辑工程**（gtrk + 剪映 + PR），
 > 给人二次精修用，毛片不上传。如果用户只要**能直接发布的成片**、不打算再剪，那该走**精剪**：
 > `gtrk tool video_long2short_pro`（走 `/gtrk-tools`，整片上传、云端渲染、计费约为粗剪两倍）。
@@ -54,7 +59,12 @@ gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-o
 ## 计费与跑前须知（每次都转述给用户）
 
 - 运行时 CLI 自动查询实时价格并在跑前打印——**把计费提示原样转述**；按**上传物音频时长**计费（≈原片时长），**长片先向用户确认再跑**。
+- **源片 > 2 小时跑不了**：CLI 在上传前就会拦下（零抽取、零上传、零扣费），不是跑到一半才失败。
+  遇到超长源片（直播回放常见）**先分段再逐段跑**，建议 **40 分钟/段**——
+  切段用流拷贝、秒级完成、不重编码：`ffmpeg -ss 0 -t 2400 -i "<源片>" -c copy "<源片名>_seg01.mp4"`。
+  各段产出的 clip 事后汇总成一张选题清单即可。**分段是常态动作，不是降级方案**。
 - 云端处理时长随片长涨（ASR+选段），CLI 轮询墙钟 60 分钟；超时不丢——产物根 `task.json` 里有 `task_id` 可恢复。
+  这也是 40 分钟/段的由来：墙钟 60min ÷ 开分屏实测耗时比上界 1.25× ≈ 48min，取 40 留余量。
 
 ## 产物（跑完把这些讲给用户）
 
@@ -69,3 +79,21 @@ gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-o
 - **轮询超时/进程中断**：凭产物根 `task.json` 的 `task_id` 查询云端状态；任务在云端照常跑完，稍后可重取。
 - **clips 为空**：说明内容里没有可成片的高光段（纯语义选段），把 `report.json` 摘要给用户看原因。
 - **剪映里看不到草稿**：先看草稿目录里的**文件名**——必须是 `draft_content.json` + `draft_meta_info.json`，缺一件或带前缀剪映都不显示；`result.json` 里该 clip 的 `jianyingDraftPath` 为 `null` 即是此症。
+
+---
+
+## 改工程：走 `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 命令参考。
+> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。