@gitruck/cli 1.0.5 → 1.0.6

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

@@ -1,71 +1,94 @@
----
-name: gtrk-long2short
-description: 长剪短闭环——把一条长视频（课程/直播/播客/访谈毛片）通过同合云选段跳剪成多条高光短片工程，一次产出逐 clip 的 gtrk+剪映+PR 三方工程（可选智能分屏）。当用户想「长剪短 / 长视频切高光 / 直播切片 / 课程切短视频 / 播客出短片 / 两小时的课切成几条精华」时使用本 skill。凡涉及把长视频拆成多条可精修的短片工程，优先用本 skill 驱动 gtrk CLI 的 `long2short` 命令，不要手搓 ffmpeg、不要人工挑时间码。
----
-
-# 长剪短（gtrk-long2short）
-
-把用户的一条长视频，用 `gtrk` CLI 跑通「**本地抽音频/720p 代理（毛片永不上传）** → 云端语义选段+跳剪（可选分屏）→ 逐 clip 拉回 gtrk/剪映/PR 三方工程」，再把产物目录回给用户。**CLI 是手、你是脑。**
-
-> 与智能剪口播（gtrk-oralcut）同一心智模型；差异是**一次任务出 N 条短片**，各自一份工程组落 `clip{i}/` 子目录。
-
-> **⚠️ 先确认用户要工程还是要成片。** 本 skill 是**粗剪**——出的是**可编辑工程**（gtrk + 剪映 + PR），
-> 给人二次精修用，毛片不上传。如果用户只要**能直接发布的成片**、不打算再剪，那该走**精剪**：
-> `gtrk tool video_long2short_pro`（走 `/gtrk-tools`，整片上传、云端渲染、计费约为粗剪两倍）。
-> 判断句：**「剪完还要不要再动？」要动 → 留在这儿；不动 → 转精剪。** 选错一次要白花积分重来。
-
-## 前置：CLI 装没装 + 体检
-
-先跑 `gtrk doctor`：
-- **`gtrk` 找不到** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
-- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（交互式、需真终端，你别替他跑）。
-- 全绿就往下走。
-
-## 一条命令
-
-```bash
-gtrk long2short "D:/毛片/课程.mp4" --language zh-CN --json
-```
-
-对谈/多人同框想要分屏：
-
-```bash
-gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-orientation tb --json
-```
-
-## 参数表
-
-| 参数 | 说明 |
-|---|---|
-| `--language <code>` | **必填**，源语种（如 zh-CN；取值以服务端支持列表为准，传错服务端会报枚举） |
-| `--split-screen` | 开启智能分屏：本地改传 **720p 代理**（否则只抽音频）；云端检测多人同框段并烤 720p 分屏素材 |
-| `--split-orientation <o>` | 分屏方向 `auto|lr|tb`（缺省 auto=按内容可复现随机） |
-| `--main-topic <text>` | 主题引导，影响选段偏好 |
-| `--duration-pref <p>` / `--max-clip-sec <n>` | 成片时长偏好 / 单条上限秒。**成片条数由内容语义决定，不能指定条数** |
-| `--no-jump-cut` | 关闭跳剪（默认开：片内去水词冗余，只删不重排） |
-| `--subtitle-file <path>` | **现成单语字幕**（.srt/.ass）作转写来源，替代云端 ASR（用户手里有片源字幕/人工校对稿时用，省一次识别）。切点精度降为**字幕行边界**；双语/多层 .ass 会被拒；与 stt 类参数互斥 |
-| `--subtitle-out` | 逐 clip 另产**单语 .srt 字幕**（按目标画布档位智能拆行：横屏约 20 字/行、竖屏约 13 字/行），落 `clip{i}/srt/` |
-| `--keep-punctuation` | 字幕保留全部标点。缺省按统一口径去标点：逗号句号→空格、`？！` 等保留 |
-| `--output-size <s>` | 画布 `9:16|16:9|1:1` 或 `WxH`（缺省 9:16 竖版） |
-| `-f, --formats <list>` | 三方格式，缺省 `gtrk,jianying,xml`（云端逐 clip 直产；gtrk 恒有） |
-| `--jianying-draft-dir <dir>` | 剪映草稿根（或 `auto`）；各 clip 草稿落 `<草稿根>/<产物根名>_clip{i}` |
-| `-o/--out`、`--no-open`、`--json`、`--reupload`、`--param/--params-json` | 与 oralcut 同口径 |
-
-## 计费与跑前须知（每次都转述给用户）
-
-- 运行时 CLI 自动查询实时价格并在跑前打印——**把计费提示原样转述**；按**上传物音频时长**计费（≈原片时长），**长片先向用户确认再跑**。
-- 云端处理时长随片长涨（ASR+选段），CLI 轮询墙钟 60 分钟；超时不丢——产物根 `task.json` 里有 `task_id` 可恢复。
-
-## 产物（跑完把这些讲给用户）
-
-- 产物根 `<毛片名>-long2short/`：`report.json`（选段报告）+ `result.json` + 逐 clip 子目录 `clip0/ clip1/ …`（各含 `gtrk/` 客户端工程、`jianying/` 草稿、`xml/` PR 工程；开了 `--subtitle-out` 另有 `srt/clip{i}.srt` 单语字幕）。
-- **先看 `clips.md`**（产物根，人读总览）：一张表列全部切片的标题/时长/评分/一句话简介 —— 用它给用户复述「出了哪几条、各讲什么、建议先精修哪条」，别让用户自己开工程猜。逐条的入选理由、跳剪说明、高光词在 `clip{i}/clip.md`。
-- 开了 `--split-screen` 时：**分屏素材落在毛片旁的 `split_screen/` 子目录**（工程素材路径指向那里，别移动/删除，移动了工程会缺素材）——这点要提前告知用户。
-- 剪映草稿已拷入草稿根（给了 `--jianying-draft-dir` 时），剪映里直接可见 `<产物根名>_clip{i}`。**判据**：草稿目录里必须是 `draft_content.json` + `draft_meta_info.json` 两个精确文件名（云端产物侧的 `clip{i}_` 前缀在拷进草稿根这一跳被剥掉，产物目录 `clip{i}/jianying/` 里保留带前缀的归档原名）。CLI 日志按实际齐全条数报「N/M 条两件套齐全」，不齐的记进 `result.json` 的 `errors`、该 clip 的 `jianyingDraftPath` 为 `null`。
-
-## 排错
-
-- **部分 clip 失败 / 个别分屏素材 404**：单点失败不连坐，`result.json` 的 `errors` 有明细；把失败项如实告诉用户，其余产物照常可用。
-- **轮询超时/进程中断**：凭产物根 `task.json` 的 `task_id` 查询云端状态；任务在云端照常跑完，稍后可重取。
-- **clips 为空**：说明内容里没有可成片的高光段（纯语义选段），把 `report.json` 摘要给用户看原因。
-- **剪映里看不到草稿**：先看草稿目录里的**文件名**——必须是 `draft_content.json` + `draft_meta_info.json`，缺一件或带前缀剪映都不显示；`result.json` 里该 clip 的 `jianyingDraftPath` 为 `null` 即是此症。
+---
+name: gtrk-long2short
+description: 长剪短闭环——把一条长视频（课程/直播/播客/访谈毛片）通过同合云选段跳剪成多条高光短片工程，一次产出逐 clip 的 gtrk+剪映+PR 三方工程（可选智能分屏）。当用户想「长剪短 / 长视频切高光 / 直播切片 / 课程切短视频 / 播客出短片 / 两小时的课切成几条精华」时使用本 skill。凡涉及把长视频拆成多条可精修的短片工程，优先用本 skill 驱动 gtrk CLI 的 `long2short` 命令，不要手搓 ffmpeg、不要人工挑时间码。
+---
+
+# 长剪短（gtrk-long2short）
+
+把用户的一条长视频，用 `gtrk` CLI 跑通「**本地抽音频/720p 代理（毛片永不上传）** → 云端语义选段+跳剪（可选分屏）→ 逐 clip 拉回 gtrk/剪映/PR 三方工程」，再把产物目录回给用户。**CLI 是手、你是脑。**
+
+> 与智能剪口播（gtrk-oralcut）同一心智模型；差异是**一次任务出 N 条短片**，各自一份工程组落 `clip{i}/` 子目录。
+
+> **⚠️ 源片是「直播回放」？先去 `/gtrk-live-slicing`。** 直播回放有本 skill 不处理的场景约束：
+> **单次提交超 2 小时会被服务端直接拒**（`6019`，必须先分段）、选题必须经用户确认再出工程、
+> 按画面形态分段配分屏、源片自带的烧录贴片如实告知不动它。那张图纸编排完这些，
+> 最终仍然回到本 skill 的命令上——**它是场景图纸，这里是链路手册，配合用不冲突。**
+
+> **⚠️ 先确认用户要工程还是要成片。** 本 skill 是**粗剪**——出的是**可编辑工程**（gtrk + 剪映 + PR），
+> 给人二次精修用，毛片不上传。如果用户只要**能直接发布的成片**、不打算再剪，那该走**精剪**：
+> `gtrk tool video_long2short_pro`（走 `/gtrk-tools`，整片上传、云端渲染、计费约为粗剪两倍）。
+> 判断句：**「剪完还要不要再动？」要动 → 留在这儿；不动 → 转精剪。** 选错一次要白花积分重来。
+
+## 前置：CLI 装没装 + 体检
+
+先跑 `gtrk doctor`：
+- **`gtrk` 找不到** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
+- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（交互式、需真终端，你别替他跑）。
+- 全绿就往下走。
+
+## 一条命令
+
+```bash
+gtrk long2short "D:/毛片/课程.mp4" --language zh-CN --json
+```
+
+对谈/多人同框想要分屏：
+
+```bash
+gtrk long2short "D:/毛片/对谈.mp4" --language zh-CN --split-screen --split-orientation tb --json
+```
+
+## 参数表
+
+| 参数 | 说明 |
+|---|---|
+| `--language <code>` | **必填**，源语种（如 zh-CN；取值以服务端支持列表为准，传错服务端会报枚举） |
+| `--split-screen` | 开启智能分屏：本地改传 **720p 代理**（否则只抽音频）；云端检测多人同框段并烤 720p 分屏素材 |
+| `--split-orientation <o>` | 分屏方向 `auto|lr|tb`（缺省 auto=按内容可复现随机） |
+| `--main-topic <text>` | 主题引导，影响选段偏好 |
+| `--duration-pref <p>` / `--max-clip-sec <n>` | 成片时长偏好 / 单条上限秒。**成片条数由内容语义决定，不能指定条数** |
+| `--no-jump-cut` | 关闭跳剪（默认开：片内去水词冗余，只删不重排） |
+| `--subtitle-file <path>` | **现成单语字幕**（.srt/.ass）作转写来源，替代云端 ASR（用户手里有片源字幕/人工校对稿时用，省一次识别）。切点精度降为**字幕行边界**；双语/多层 .ass 会被拒；与 stt 类参数互斥 |
+| `--subtitle-out` | 逐 clip 另产**单语 .srt 字幕**（按目标画布档位智能拆行：横屏约 20 字/行、竖屏约 13 字/行），落 `clip{i}/srt/` |
+| `--keep-punctuation` | 字幕保留全部标点。缺省按统一口径去标点：逗号句号→空格、`？！` 等保留 |
+| `--output-size <s>` | 画布 `9:16|16:9|1:1` 或 `WxH`（缺省 9:16 竖版） |
+| `-f, --formats <list>` | 三方格式，缺省 `gtrk,jianying,xml`（云端逐 clip 直产；gtrk 恒有） |
+| `--jianying-draft-dir <dir>` | 剪映草稿根（或 `auto`）；各 clip 草稿落 `<草稿根>/<产物根名>_clip{i}` |
+| `-o/--out`、`--no-open`、`--json`、`--reupload`、`--param/--params-json` | 与 oralcut 同口径 |
+
+## 计费与跑前须知（每次都转述给用户）
+
+- 运行时 CLI 自动查询实时价格并在跑前打印——**把计费提示原样转述**；按**上传物音频时长**计费（≈原片时长），**长片先向用户确认再跑**。
+- 云端处理时长随片长涨（ASR+选段），CLI 轮询墙钟 60 分钟；超时不丢——产物根 `task.json` 里有 `task_id` 可恢复。
+
+## 产物（跑完把这些讲给用户）
+
+- 产物根 `<毛片名>-long2short/`：`report.json`（选段报告）+ `result.json` + 逐 clip 子目录 `clip0/ clip1/ …`（各含 `gtrk/` 客户端工程、`jianying/` 草稿、`xml/` PR 工程；开了 `--subtitle-out` 另有 `srt/clip{i}.srt` 单语字幕）。
+- **先看 `clips.md`**（产物根，人读总览）：一张表列全部切片的标题/时长/评分/一句话简介 —— 用它给用户复述「出了哪几条、各讲什么、建议先精修哪条」，别让用户自己开工程猜。逐条的入选理由、跳剪说明、高光词在 `clip{i}/clip.md`。
+- 开了 `--split-screen` 时：**分屏素材落在毛片旁的 `split_screen/` 子目录**（工程素材路径指向那里，别移动/删除，移动了工程会缺素材）——这点要提前告知用户。
+- 剪映草稿已拷入草稿根（给了 `--jianying-draft-dir` 时），剪映里直接可见 `<产物根名>_clip{i}`。**判据**：草稿目录里必须是 `draft_content.json` + `draft_meta_info.json` 两个精确文件名（云端产物侧的 `clip{i}_` 前缀在拷进草稿根这一跳被剥掉，产物目录 `clip{i}/jianying/` 里保留带前缀的归档原名）。CLI 日志按实际齐全条数报「N/M 条两件套齐全」，不齐的记进 `result.json` 的 `errors`、该 clip 的 `jianyingDraftPath` 为 `null`。
+
+## 排错
+
+- **部分 clip 失败 / 个别分屏素材 404**：单点失败不连坐，`result.json` 的 `errors` 有明细；把失败项如实告诉用户，其余产物照常可用。
+- **轮询超时/进程中断**：凭产物根 `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 命令参考。
+> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。