Gtrk Long2short

---
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`，整片上传、云端渲染、计费约为粗剪两倍）。
> 判断句：**「剪完还要不要再动？」要动 → 留在这儿；不动 → 转精剪。** 选错一次要白花积分重来。

> **⚠️ 开工再问一句：素材是不是多人同框（对谈 / 访谈 / 多人直播）？** 与 `/gtrk-tools` 精剪同一问、同一措辞，
> 和上一问**一起问、一次答完**，MUST NOT 代猜。
> 答「是」⇒ 带 `--split-screen`，**并在同一句里告知**：本地会改传一份压过的 720p 代理（否则只传抽出的音频、
> 毛片不出本地），处理时间明显变长；分屏素材落毛片旁 `split_screen/`。
> 答「否 / 不确定」⇒ 不带（「不确定」按「否」）。分屏是点缀：单段最长 8 秒、每条最多 3 处，落在子轨、
> 不合心意在客户端隐藏该段即回退原片。

## 前置：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` | 字幕保留全部标点。缺省按统一口径去标点：逗号句号→空格、`？！` 等保留 |
| `--speed-factor <n>` | 整体调速 `0.5–2.0`（保音高）。倍率**写进逐 clip 工程**（每个片段带 `speed`），客户端 / 剪映 / PR 都按倍率播放、可在客户端改回；云端不渲染、不加价。**只在用户主动要求时加**；更高倍率请在客户端对具体片段拖边变速 |
| `--camera-move` | 运镜：云端按与精剪同一套调度给主轨片段写推 / 拉镜头关键帧（概率抽取、推拉交替、幅度克制），零渲染、不加价。客户端与剪映可见可改；本地 `gtrk render` 与 PR 工程不呈现。**缺省不加**，直播切片图纸开工会问；细项走 `--params-json` |
| `--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}`。同一毛片重跑照旧覆盖这一组；别的目录下的同名毛片撞上时整组改落 `<产物根名>-2_clip{i}` 并提示，原草稿不动 |
| `-o/--out`、`--no-open`、`--json`、`--reupload`、`--param/--params-json` | 与 oralcut 同口径 |

## 计费与跑前须知（每次都转述给用户）

- **合成包装问一次**（公约 §三⁵）：「出来的切片要不要做合成包装？」**缺省不做**；答要则跑完后对每条 clip 做（见「产物」末条），并在这次一起问烘焙浏览器装不装（`gtrk composite bake --abi` 报没装时）。

- 按**上传物音频时长**计费（≈原片时长）。**长片先报价、等用户确认再跑**：同一条命令加 `--dry-run --json`，只探测并报价（零抽取、零上传、零计费、不建目录），把 stdout 那行 `pricing` 里的单价与预估**原样转述**；别自己报数字、别引用旧价。
- 正式运行时 CLI 在抽音频之前查一次实时价格，往 stderr 打一行「计费提示」（单价 + 本次预估），`--json` 根结果的 `pricing` 也有；查不到时是「实时价格暂不可用，以服务端结算为准」，照实转述。
- **源片 > 2 小时跑不了**：CLI 在上传前就会拦下（零抽取、零上传、零扣费），不是跑到一半才失败。
  遇到超长源片（直播回放常见）**先分段再逐段跑**，建议 **40 分钟/段**——
  切段用流拷贝、秒级完成、不重编码：`ffmpeg -ss 0 -t 2400 -i "<源片>" -c copy "<源片名>_seg01.mp4"`。
  各段产出的 clip 事后汇总成一张选题清单即可。**分段是常态动作，不是降级方案**。
- 云端处理时长随片长涨（ASR+选段），CLI 轮询墙钟 60 分钟；超时不丢——产物根 `task.json` 里有 `task_id` 可恢复。
  40 分钟/段是稳妥起步值；若分屏段仍接近墙钟上限，再继续缩短分段。

## 产物（跑完把这些讲给用户）

- 产物根 `<毛片名>-long2short/`：`report.json`（选段报告）+ `result.json` + 逐 clip 子目录 `clip0/ clip1/ …`（各含 `gtrk/` 客户端工程、`jianying/` 草稿、`xml/` PR 工程；开了 `--subtitle-out` 另有 `srt/clip{i}.srt` 单语字幕）。
  打开 PR 工程时的重链提醒照 `gtrk-oralcut`「回给用户（三端打开方式）」PR/FCP 条，引用不复制。
- 产物根 `json/transcript.json`：**整片**源时基转写（一份服务全部 clip）。要给某条 clip 上客户端字幕轨（可换样式、可整轨删、不烧进画面）：
  `gtrk subtitle lay --gtrk <产物根>/clip{i}/gtrk/clip{i}_project.gtrk --transcript <产物根>/json/transcript.json --language <源语种>`
  （clip 工程文件名以 `clip{i}/gtrk/` 下实际文件为准）。上完字幕的是**客户端工程**；云端早先产出的剪映 / PR 工程不含这条字幕轨，要带字幕的剪映草稿请从客户端导出。老服务端没有这份文件时，CLI 会提示「无法自动上字幕」。
- 横屏源进竖屏画布（缺省 9:16）时工程上下是黑边；要模糊底：`gtrk project background --gtrk <产物根>/clip{i}/gtrk/clip{i}_project.gtrk --blur`——给该 clip **主轨每个片段**写模糊底（片段级底板），客户端里可逐片段或多选批量改成黑底 / 纯色；从客户端导出的剪映草稿带模糊底、Pr 工程降级为纯黑、本地 `gtrk render` 带模糊底；云端随长剪短产出的剪映 / PR 工程生成在它之前、不带。零计费。只想要旧的整片画布设置：加 `--scope canvas`。
- 用了 `--camera-move` 时：`clips.md` 每条时长后标「运镜 N 处」（0 处属正常）；若有 clip 未能加运镜，`clips.md` 会单列「未能加运镜的切片」；告诉用户运镜在客户端 / 剪映里看，本地渲染与 PR 看不到。之后用 `gtrk patch` 裁剪 / 切分带运镜的片段，关键帧会跟着调整。
- 用了 `--speed-factor` 时：`clips.md` 的时长是**变速后**的时长并标注倍率；若有 clip 未能变速，`clips.md` 会单列「未能变速的切片」，如实告诉用户。
- **合成包装**（跑前答了要才做）：对每条 clip 交棒 `/gtrk-composite` 做**精剪包装**（公约 §三⁵：快速成片 auto ≤ 25% → 逐窗口复核 → 构建机检 → 铺轨烘焙，不停；回执列「做了 / 建议了没做 / 烘焙结果」；逐步推进按合成 skill 两个检查点停；开工时用户说了不要就跳过）；参数同上面字幕那条：`--gtrk <产物根>/clip{i}/gtrk/clip{i}_project.gtrk --transcript <产物根>/json/transcript.json`。
- **先看 `clips.md`**（产物根，人读总览）：一张表列全部切片的标题/时长/评分/一句话简介 —— 用它给用户复述「出了哪几条、各讲什么、建议先精修哪条」，别让用户自己开工程猜。逐条的入选理由、跳剪说明、高光词在 `clip{i}/clip.md`。
- 开了 `--split-screen` 时：**分屏素材落在毛片旁的 `split_screen/` 子目录**（工程素材路径指向那里，别移动/删除，移动了工程会缺素材）——这点要提前告知用户。
- 剪映草稿已拷入草稿根（给了 `--jianying-draft-dir` 时），剪映里直接可见 `<产物根名>_clip{i}`；CLI 提示「剪映草稿组……已被占用，本次改落……-2」时，告诉用户这一组叫 `<产物根名>-2_clip{i}`（另一条同名毛片的草稿原样保留），以 `result.json` 里各 clip 的 `jianyingDraftPath` 为准。**判据**：草稿目录里必须是 `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 命令参考。
> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。