@gitruck/cli 1.2.13 → 1.2.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENT.md +29 -10
- package/CHANGELOG.md +21 -0
- package/README.en.md +208 -807
- package/README.md +208 -826
- package/assets/readme/README.md +9 -0
- package/assets/readme/editable-project.webp +0 -0
- package/assets/readme/narration-tour.webp +0 -0
- package/assets/readme/quick-mode.webp +0 -0
- package/assets/readme/wordmark.svg +6 -0
- package/dist/index.js +257 -256
- package/docs/development.en.md +47 -0
- package/docs/development.md +47 -0
- package/docs/reference.en.md +595 -0
- package/docs/reference.md +629 -0
- package/docs/workflow.en.md +72 -0
- package/docs/workflow.md +72 -0
- package/package.json +79 -72
- package/skills/gtrk-ai-drama/SKILL.md +3 -1
- package/skills/gtrk-ai-drama/references/sparse-key-scenes.md +38 -0
- package/skills/gtrk-tools/SKILL.md +31 -3
package/README.md
CHANGED
|
@@ -1,856 +1,238 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<img src="assets/readme/wordmark.svg" alt="gtrk CLI" width="420">
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<h1>一句句把片子聊出来</h1>
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
>
|
|
9
|
-
> 一条命令，把口播毛片变成可二次精修的剪辑工程。云端做重活，本地只装配，源视频不出本地。
|
|
7
|
+
<p><strong>让你的 AI Agent，把素材做成可以继续精修的视频工程。</strong></p>
|
|
8
|
+
<p>剪口播 · 切高光 · 做解说 · 配画面 · 叠动效 · 上字幕</p>
|
|
10
9
|
|
|
11
|
-
|
|
10
|
+
<p>
|
|
11
|
+
<a href="#demo">观看演示</a> ·
|
|
12
|
+
<a href="#quick-start">快速开始</a> ·
|
|
13
|
+
<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">使用教程</a> ·
|
|
14
|
+
<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
|
|
15
|
+
<a href="docs/development.md">开发文档</a> ·
|
|
16
|
+
<a href="README.en.md">English</a>
|
|
17
|
+
</p>
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
<p>
|
|
20
|
+
<a href="https://www.npmjs.com/package/@gitruck/cli"><img src="https://img.shields.io/npm/v/@gitruck/cli?style=flat-square&color=f43b48" alt="npm 版本"></a>
|
|
21
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A520.6-43853d?style=flat-square" alt="Node.js ≥20.6"></a>
|
|
22
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-f43b48?style=flat-square" alt="MIT"></a>
|
|
23
|
+
<img src="https://img.shields.io/badge/CLI-Windows%20%7C%20macOS%20%7C%20Linux-555?style=flat-square" alt="CLI 支持 Windows、macOS、Linux">
|
|
24
|
+
</p>
|
|
14
25
|
|
|
15
|
-
|
|
26
|
+
<p><a href="https://ai-mcn.tv/gtrk"><strong>产品主页 ↗</strong></a> <a href="https://cloud.ai-mcn.tv/zh-CN/download"><strong>下载客户端 ↗</strong></a> <a href="https://cloud.ai-mcn.tv/zh-CN/dashboard"><strong>获取 API Key ↗</strong></a></p>
|
|
16
27
|
|
|
17
|
-
|
|
28
|
+
</div>
|
|
18
29
|
|
|
19
|
-
|
|
20
|
-
- **云端做重活、本地只装配**：识别、剪辑、对齐都在云端；本地只拿结果，**源视频不出本地**（路径写进工程、本地打开直接认素材）。
|
|
21
|
-
- **为 agent 而生**：配套 skill `gtrk-oralcut`，在 Claude Code / Codex / Cursor / Gemini CLI / TRAE 等 Agent 里一句「帮我剪个口播」就能发起，CLI 是手、agent 是脑。
|
|
22
|
-
- **通用工具箱**：单 binary + 平行子命令——每个 `gtrk <xyz>`（oralcut / split / mg / matrix / render…）都是一个**业务无关的通用驱动器/工具**，成片流程要哪个启哪个、用不到放着；后续可长更多驱动器。对标飞书 `lark-cli`。目前用它做人文社科视频，但设计上不绑任何栏目。
|
|
30
|
+
<!-- 中英双份：修改本页须同步 README.en.md，详细参数维护在 docs/reference*.md。 -->
|
|
23
31
|
|
|
24
|
-
|
|
32
|
+
**gtrk 是为 AI Agent 准备的视频创作 CLI。** 在 Codex、Claude Code、Cursor、TRAE 等支持 Skills 的 Agent 里说需求，Agent 调用 gtrk 完成剪辑与装配，你在客户端里看效果、挑素材、调细节。
|
|
25
33
|
|
|
26
|
-
|
|
27
|
-
|---|---|---|
|
|
28
|
-
| 🎬 | `gtrk oralcut <毛片>` | 智能口播剪辑闭环：一次出 gtrk + 剪映 + PR 三方工程，自动打开 |
|
|
29
|
-
| ✂️ | `gtrk long2short <毛片>` | 长剪短闭环：长视频语义选段+跳剪（可选 720p 代理智能分屏）→ 逐 clip 出 gtrk + 剪映 + PR 三方工程（毛片不上传）。**只要成片、不再二次编辑请走精剪** `gtrk tool video_long2short_pro` |
|
|
30
|
-
| ⏱ | 时长上限 | `oralcut` / `long2short` 的源片 **> 2 小时会在上传前被拦下**（零抽取、零上传、零扣费）。超长源片先分段再逐段跑，建议 40 分钟/段：`ffmpeg -ss 0 -t 2400 -i "<源片>" -c copy "<源片名>_seg01.mp4"`（流拷贝，秒级完成） |
|
|
31
|
-
| 📝 | `gtrk transcript <本地视频\|配音音频>` | 视频/音频转文字稿：原文件不上传，只传本地抽取（音频输入则转码）的 16k 音频衍生物，生成一个含总结、时码记录和纯文本的 Markdown；`--json` 时另产句级时码 `transcript.json`（`gtrk project init` 兜底路输入） |
|
|
32
|
-
| 🎵 | `gtrk music-visualizer <音频>` | 音乐可视化：一首歌 → 频谱可视化成片（`--template` 必填 + 可选背景/封面 + 模板/配色样式），配套 driver skill `gtrk-music-visualizer` |
|
|
33
|
-
| ✂️ | `gtrk split [拆分稿]` | 视觉拆分派单器：成片 × transcript 投影 → beat 分镜校验落地（`struct_meta.split` + `dispatch.json`），驱动四车道派单；`--column <id>` 按栏目词表校验 |
|
|
34
|
-
| ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
|
|
35
|
-
| 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
|
|
36
|
-
| 📦 | `gtrk deps` | 运行时资产：`status` 查 ffmpeg/字体的来源与授权，`install` 从同合云镜像装（**须显式触发，绝不静默自动下载**） |
|
|
37
|
-
| 🤖 | `gtrk skills install` | 通过通用 `skills` 适配器和 gtrk 补充层，把 18 个 CLI 自带 skill 装进本机检测到的主流 Agent；`--all` 可覆盖全部已登记宿主；`gtrk skills recommend --scene <id>` 查第三方 skill 推荐目录（随包快照、不联网、只推荐不打包），`gtrk skills add <owner/repo>` 透传安装并登记进栏目配置 `style.skills` |
|
|
38
|
-
| ⬆️ | `gtrk upgrade` | 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装 |
|
|
39
|
-
| 🎞️ | `gtrk render` | 本地渲染 gtrk 工程（EDL）→ 成片 mp4（需 ffmpeg）；按契约 z 序合成**全部可见叠加层**（B-roll 等 overlay 视频轨 + MG 颗粒，`hidden` 的轨不进片）；输出帧按时间线**累计对齐**（逐段取整误差不累加，画面不会对配音渐进失步）；渲完自动质检并落 `.qc.json`（`--no-qc` 跳过）；画中画 clip 的 `clip_transform`（缩放 / 落位 / 旋转 / 透明）、`border_radius` 圆角与 `clip_mask` 形状蒙版（圆 / 圆角方 / 爱心 / 菱形 / 星形，带羽化）随工程本地合成，与客户端预览观感等价。⚠️ 未命中缓存的 MG 颗粒要云渲**有计费**（先预估要确认；`--no-particles` 零计费出无颗粒版） |
|
|
40
|
-
| 🔬 | `gtrk qc <成片>` | 成片质检：单趟扫全片查闪帧/黑帧/冻结/爆音/静音/音画不同步，带时码定位；`--gtrk <工程>` 开工程感知识别**段内跳切**，`--fail-on error\|warn\|never` 供管线门控 |
|
|
41
|
-
| 🔎 | `gtrk matrix` | B-roll 检索+**候选铺轨**：消费 FILM_BROLL 派单 → 产候选清单 + 下载 preview 代理铺 N 条候选轨（`--lay N` 默认 1，opencut 打开即可用轨道小眼睛对比；`--lay 0` 只出清单）；`matrix search "<词>"` 单条 ad-hoc；`matrix fetch <clip_id...>` 精剪期拉原片（已授予素材免费重签+下载落盘，直接拖进剪映）；**本地素材模式**：`matrix index --dirs <素材夹>` 免切片建索引 → `--local --dirs` 检索铺轨（**素材本体不上云**）→ `matrix lay` 消费（可编辑的）plan；`matrix describe` 按需理解候选 |
|
|
42
|
-
| 🎨 | `gtrk mg` | MG 动态图颗粒铺轨：消费 MG 派单 → 把 html-particle 颗粒（透明叠加 / 满屏底层，由你栏目的 MG 生产 skill 所产）铺进 `.gtrk` 的 beat_track；`mg lint <颗粒.html>` 铁律静态子集校验、`mg status --project <dir>` 编排看板（缺 HTML / 已产未铺 / 已铺）；`mg render <颗粒.html> --duration <sec>` 脱离工程独立云渲单颗颗粒为剪映可读 qtrle 透明 MOV（精剪补给口）；aux 叠层颗粒同段多铺（一 beat 派生主 + `-aux<n>`）。旧名 `gtrk rrv` 保留为弃用别名；`gtrk mg fetch` 从 Hyperframes registry 取中性块骨架（快照随包离线候选、三源取块我方镜像优先、机械改写后过 lint）；`gtrk mg fetch --source text` 取同合云自家的文字特效模板（开箱即成品、不做机械改写），配 `gtrk mg compile`（改 IR 重编译，0 积分）与 `gtrk mg edit --say`（自然语言改写，按候选计费） |
|
|
43
|
-
| 🎙️ | `gtrk project init` | 音频驱动工程起盘：从一条配音建 `.gtrk` 工程——主路 `--tts-task <task_id>` 引用已完成的 TTS 配音任务（直取产物音频+句级时码，零 ASR）；兜底 `--audio`+`--transcript` 自备配音成对给。落好即可 `gtrk split --project` 接成片流水线 |
|
|
44
|
-
| 🎼 | `gtrk audio lay` / `tighten` | 音频轨零件：`lay` 往 `.gtrk` 工程追加一条音频轨（BGM/配乐上轨，同源幂等替换不堆轨）；`--beat-align` 云端分析把 **BGM 的情绪峰值压到成片的高潮点上**，锚点前后按小节线平铺补齐、两侧都够长时零平铺（计费一次；高潮点取自 `split.beats` 的判据链，可用 `--climax <轨秒>` 覆盖；`--no-loop` 只放锚点那一段、头尾留白；无 Key / 失败 / 曲子缺高潮点自动降级为不锚定，命令不失败）。`tighten` 收紧配音的句间停顿（纯本地零计费，只压跨句界的静音、句内换气不动） |
|
|
45
|
-
| 🎯 | `gtrk audio align` | 音画对轨零件（纯本地零计费）：外录音轨（领夹麦/录音笔）与视频互相关测偏移+置信度；高置信直接换轨（视频流零像素改动），低置信产对齐工程交客户端拖齐后 `--resume` 读回；`--offset` 显式偏移直换 |
|
|
46
|
-
| 🧰 | `gtrk tool <name>` | 单点工具族：图转运镜、图片/视频抠像、图片去黑边/比例转换/净化/转方图/LivePhoto、智能拼图封面/拼长图（多图输入）、视频去黑边/比例转换/防抖/蒸汽波滤镜/机械·智能分镜/运镜高光/智能字幕、人声伴奏分离/说话人分轨/变调变速、钢琴转MIDI/修复、音视频降噪、静音移除、MAD 等；`gtrk tool list` 查全部输入/产物/实时价格/状态。单发单收、共享 runner，接新工具只加一个 descriptor |
|
|
47
|
-
| 💬 | `gtrk feedback` | 把用得不顺手的地方反馈给我们：`gtrk feedback "<一句话>" --command <命令名>`。**告知式提交**——助手代提时必须先把要发的内容原样念给你、得到同意后才加 `--disclosed` 重跑；管道/非交互环境下没有这句声明会直接拒发。发送前内容会先做一遍脱敏（本机路径、凭据、邮箱、手机号等按形态替换），你看到的就是将要发出的那一份 |
|
|
48
|
-
| 🚧 | `struct` | （规划中）已有 gtrk 转三方工程 |
|
|
34
|
+
从一条口播、一场访谈、一篇稿子或一组旅拍素材开始。把粗剪、配画面、动态图、配乐和字幕接成工作流，也可以单独调用其中一个工具。**你负责创意和判断，gtrk 负责执行。**
|
|
49
35
|
|
|
50
|
-
|
|
36
|
+
<a id="demo"></a>
|
|
51
37
|
|
|
52
|
-
##
|
|
38
|
+
## 每一步都能改，每一层都在轨上
|
|
53
39
|
|
|
54
|
-
|
|
40
|
+
<a href="https://www.bilibili.com/video/BV1HAec6fELP/"><img src="assets/readme/editable-project.webp" alt="真实客户端工程：画面预览、动态图与多轨时间线，可逐段精修。点击观看流程速览。" width="100%"></a>
|
|
55
41
|
|
|
56
|
-
|
|
57
|
-
2. 进入 **[控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)**，在「API 密钥 / 密钥管理」处生成并复制你的 Key。
|
|
58
|
-
3. 下一步 `gtrk install` 会让你把它粘进去（一次配好、本地长期复用）。
|
|
42
|
+
<p align="center"><strong>在 Agent 里说需求，在客户端里看效果。</strong><br>上图为真实客户端工程。<a href="https://www.bilibili.com/video/BV1HAec6fELP/">▶ 2 分 28 秒，看完整条路</a></p>
|
|
59
43
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
44
|
+
| 先看一次实测 | 再看完整制作 |
|
|
45
|
+
| :---: | :---: |
|
|
46
|
+
| [](https://www.bilibili.com/video/BV1PcYK6kEEL/) | [](https://www.bilibili.com/video/BV1iZYK6YEew/) |
|
|
47
|
+
| **7 分钟快速模式** · 口播、字卡、BGM、字幕 | **35 分钟解说实战** · 看素材、写稿、配音、配画面 |
|
|
63
48
|
|
|
64
|
-
|
|
49
|
+
<a id="quick-start"></a>
|
|
65
50
|
|
|
66
|
-
|
|
51
|
+
## 安装一次，开始对话
|
|
67
52
|
|
|
68
|
-
|
|
69
|
-
# 1) 一条命令装全：命令行 gtrk + /gtrk-oralcut skill + 配置（填 API Key、自动扫剪映目录）
|
|
70
|
-
# 装完新开一个终端敲 gtrk 就有响：安装器会自持一份全局副本，Windows 上还会把它所在目录加进用户 PATH
|
|
71
|
-
npx @gitruck/cli@latest install
|
|
72
|
-
# 等价写法：npm i -g @gitruck/cli@latest && gtrk install
|
|
73
|
-
# 新终端敲不到 gtrk？跑 gtrk doctor 看「命令可达」那一行
|
|
74
|
-
|
|
75
|
-
# 2) 剪一条（剪完自动打开产物目录）
|
|
76
|
-
gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
|
|
77
|
-
|
|
78
|
-
# 或把本地视频转成一个 Markdown 文字稿
|
|
79
|
-
gtrk transcript "D:/素材/采访视频.mp4"
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
> 只想配置、不装 skill：用 `gtrk init`。本地开发：`cd gtrk-cli && bun install && bun run src/index.ts <命令>`。
|
|
83
|
-
|
|
84
|
-
产物目录形如 `<毛片名>-video-project-<YYMMDD-HHMMSS>/`，内含 `gtrk/`、`jianying/`、`xml/` 三端工程。
|
|
85
|
-
|
|
86
|
-
> **重复装不会重复填配置**：`gtrk install` / `gtrk init` 检测到已配好就默认保留、只刷新 skill；想改配置加 `--reconfigure`（Key / 剪映目录也都能回车沿用）。
|
|
87
|
-
|
|
88
|
-
## 操作地图：从零到成片
|
|
89
|
-
|
|
90
|
-
> **你只管对话，敲 CLI 的活交给 agent。** 下面是一条龙的走法——先做什么、后做什么、遇到情况怎么办。
|
|
91
|
-
|
|
92
|
-
**一次性准备（装一次，之后免管）**
|
|
93
|
-
|
|
94
|
-
1. **装 CLI**：`npm i -g @gitruck/cli@latest && gtrk install`（装 gtrk + skill + 填 API Key，一次配好）。
|
|
95
|
-
2. **（可选）建栏目风格**：想要自己的视觉调性 / 词表，对 agent 说「**建我栏目的风格体系**」（`/gtrk-style-maker` 访谈式帮你落成你自己的 skill 家族 + 栏目配置）。**不建就用默认厨房**，端到端照常跑。
|
|
96
|
-
|
|
97
|
-
**每片一条龙（有先后的 SOP，对 agent 说话、每步你可介入——不是一次性并行铺完）**
|
|
98
|
-
|
|
99
|
-
各车道**按次序铺、每步留检查点**：先把 B-roll 底轨三源铺齐（影视素材 / 本地素材 / AI 情景片段）→ 你调好 → 抽帧核一遍画面构图 → 最后才把 MG（含 ov）叠上去。你对话推进每一步，agent 替你跑对应命令。
|
|
100
|
-
|
|
101
|
-
**三种入链，一个汇合点。** 素材长什么样决定你走哪条；拿到「工程 + 文稿」之后，三条链完全一样：
|
|
102
|
-
|
|
103
|
-
```
|
|
104
|
-
① 口播链 你对着镜头讲的一条口播 gtrk oralcut
|
|
105
|
-
短视频口播 / 人文社科杂谈 照稿剪掉重来·口误·长停顿
|
|
106
|
-
↓
|
|
107
|
-
② 配音链 你写的一段稿子 → AI 配音 gtrk project init
|
|
108
|
-
电影解说 / 美食解说 先把配音调舒服，再建工程
|
|
109
|
-
↓
|
|
110
|
-
③ 长剪短 一条几十分钟的长素材 gtrk long2short
|
|
111
|
-
播客·圆桌·脱口秀·访谈·直播回放 挑出值得单发的，逐条出工程
|
|
112
|
-
↓
|
|
113
|
-
══════════ 工程 + 文稿 ══════════ ← 汇合点：往下三条链一样
|
|
114
|
-
↓
|
|
115
|
-
┌───────────────────────┴───────────────────────┐
|
|
116
|
-
│ │
|
|
117
|
-
配画面（可选，次序不能跳） 只想快点出片
|
|
118
|
-
│ │
|
|
119
|
-
gtrk split 把文稿分段派活 │
|
|
120
|
-
↓ │
|
|
121
|
-
gtrk matrix 按文稿铺 B-roll │
|
|
122
|
-
↓ │
|
|
123
|
-
AI 情景动画（可选） 外部平台出片 → 手动回铺 │
|
|
124
|
-
↓ │
|
|
125
|
-
客户端挑选 抽帧核构图 ← 底轨定稿前别往下走 │
|
|
126
|
-
↓ │
|
|
127
|
-
gtrk mg MG 主颗粒 + OV 叠层，最后才叠 │
|
|
128
|
-
↓ │
|
|
129
|
-
gtrk audio lay 全片加 BGM（可选） │
|
|
130
|
-
│ │
|
|
131
|
-
└───────────────────────┬───────────────────────┘
|
|
132
|
-
↓
|
|
133
|
-
客户端：上字幕 → 出片
|
|
134
|
-
（或导出剪映草稿 / PR 工程）
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
**记两件事就够**：① **底下的先铺、盖在上面的最后叠**——B-roll 与 AI 情景动画同属底轨画面（并列的两条腿），动态图（MG 主颗粒 + OV 透明叠层）是唯一的叠加层，底轨没定稿就叠等于白做；② 出片永远在客户端或你自己的剪辑软件里完成，CLI 只负责把料铺进工程。
|
|
138
|
-
|
|
139
|
-
> 三条链各自的完整走法（含每步产物、常见问题）见使用教程的子页：**口播链**（短视频口播 / 人文社科杂谈）· **配音链**（电影解说 / 美食解说）· **长剪短**（播客 / 圆桌 / 脱口秀 / 访谈 / 直播回放）。
|
|
140
|
-
|
|
141
|
-
| 步 | 你对 agent 说 | agent 替你做 | 你可以介入 |
|
|
142
|
-
|:--:|---|---|---|
|
|
143
|
-
| ① | 「帮我把这条口播**剪一版**」 | `/gtrk-oralcut` → `gtrk oralcut` → 三方工程 + transcript | — |
|
|
144
|
-
| ② | 「接着**拆分镜派单**」 | `/gtrk-splitter` → `gtrk split` → `dispatch.json` 四车道 | 核对派单结果 |
|
|
145
|
-
| ③ | 「**铺 B-roll 底轨**」（两条腿同一阶段） | `/gtrk-matrix` → `gtrk matrix` → 影视/本地素材候选轨铺入；`/gtrk-ai-drama`（skill，无命令）→ 四段描述稿（中英分块） | **opencut 里挑选/调整 B-roll**（小眼睛切换对比）；AI 片段去外部平台出片、**手动回铺** |
|
|
146
|
-
| ④ | 「B-roll 齐了，**抽帧看看构图**」 | 对**三源合并后的最终底轨**抽帧（agent 纪律，无专属命令） | **确认构图**（主体位置 / 安全区 / 朝向 / 明暗） |
|
|
147
|
-
| ⑤ | 「构图没问题，**铺 MG**」 | `/gtrk-mg` → `gtrk mg` → MG（含 ov）叠在已定稿的底轨之上 | 精修颗粒（opencut 手调） |
|
|
148
|
-
| ⑥ | 「**出成片**」 | 两条路都行：客户端出片链（多车道合成 + 颗粒云渲 / **导剪映**），或 `gtrk render`（本地叠全部可见叠加层出 mp4，颗粒未命中缓存时计费）；两端共用同一份颗粒缓存 | 客户端里精修定稿 |
|
|
149
|
-
|
|
150
|
-
> **次序有理由**：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版是「因势象形避主体」、**依赖底轨的最终画面构图**，所以三源（影视 / 本地 / AI）必须全落齐、构图核过，才轮到 MG。用不到的车道跳过（`dispatch` 里该队列为空就不铺）。
|
|
151
|
-
>
|
|
152
|
-
> ⚠️ **旧版文档曾写「④ 铺 MG → ⑤ 最后上 AI 情景动画」，理由是「越往后叠得越上层」——那是把「工序次序」误当成了「图层次序」，已于 2026-08-17 纠正。** 若你装的是旧版 skill，`gtrk upgrade` 刷新后才是新序。
|
|
153
|
-
>
|
|
154
|
-
> **AI 出片是异步的**：外部平台抽卡可能数天，严格串行会把 ④⑤ 无限期卡住。故进 ⑤ 的门是「**AI 片段已回铺 ∨ 你明示先跳过**」；走跳过时 agent 会把与 AI 区间相邻/重叠的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述给你。
|
|
155
|
-
>
|
|
156
|
-
> ③④⑤⑥ 都要**回到客户端**挑选 / 精修 / 回铺 / 出片——CLI 把料铺进 `.gtrk`，客户端把 `.gtrk` 出成片。详见下文「**CLI × 客户端**」小节。
|
|
157
|
-
|
|
158
|
-
**遇到情况怎么办**
|
|
159
|
-
|
|
160
|
-
| 情况 | 怎么做（跟 agent 说，或 agent 自动） |
|
|
161
|
-
|---|---|
|
|
162
|
-
| 只想要剪辑工程、暂不做视觉 | 到「剪一版」就停：「先只要剪辑工程」 |
|
|
163
|
-
| 报告丢了 / 换台机器再拉产物 | 「用 taskId 取回上次的」→ `gtrk oralcut-result <taskId> --out <目录>`（跳过重跑云端） |
|
|
164
|
-
| 想在几个 B-roll 候选里挑 | 「B-roll 多铺几条候选」→ `gtrk matrix --lay N`，opencut 里用轨道小眼睛切换对比 |
|
|
165
|
-
| B-roll 填充太差 / 有空槽 | 调 `--score-floor` / `--top-k` 重跑，或「单独搜个词」→ `matrix search "<词>"` 补 |
|
|
166
|
-
| 想用自己的素材铺 B-roll | 「用我本地的素材铺」→ `gtrk matrix index --dirs <素材夹>` 建索引后 `gtrk matrix --local --dirs … --project …`（**素材本体不上云**，详见命令参考 matrix 节） |
|
|
167
|
-
| 画面 / 颗粒要逐帧精修 | opencut 打开工程手调（agent 铺好的是**可编辑工程**，不是死片） |
|
|
168
|
-
| 连不上 / 配置出问题 | 「体检一下」→ `gtrk doctor`（配置 / 云端 / 剪映目录 / 版本一键自检） |
|
|
169
|
-
| 有新版 | 「升级」→ `gtrk upgrade`（升 CLI + 刷 skill，配置保留） |
|
|
170
|
-
|
|
171
|
-
## CLI × 客户端：手脑分工、一份 `.gtrk` 贯穿全程
|
|
172
|
-
|
|
173
|
-
**标准工作流从来不是「只用 CLI」，而是 CLI + 桌面客户端相互配合——客户端是成片流程绕不过去的一环。** 二者分工：
|
|
174
|
-
|
|
175
|
-
- **CLI = 无头装配器（手/机械活）**：把云端剪辑产物、检索到的 B-roll、栏目产的颗粒，确定性地装进工程、原子写回 `.gtrk`（剪口播 / 拆分派单 / 铺 B-roll 候选轨 / 铺 MG 颗粒）。不做审美判断、不出最终成片。
|
|
176
|
-
- **桌面客户端 = 有头工作台（眼/精修活）**：打开**同一份 `.gtrk`**，让你看、挑、逐帧精修、回铺 AI 片段、出片。装法见上一节「升级 → 桌面客户端」的一键脚本（OpenCut Gitruck Edition）。
|
|
177
|
-
|
|
178
|
-
**`.gtrk` 是两者之间的交接介质**——它是同合云的统一工程契约（timeline 真超集 + HTML 颗粒 + `struct_meta`），**CLI 写、客户端读，双向**。所以一条片子是 CLI 与客户端**交替推进**的：
|
|
179
|
-
|
|
180
|
-
```
|
|
181
|
-
CLI 写 .gtrk ─▶ 客户端打开(自动感知外部改动、先存脏改再刷新、不丢稿)
|
|
182
|
-
─▶ 你在客户端挑/调/精修 ─▶ 需要就再喊 agent 让 CLI 写下一轮(铺 MG / 铺 AI…)
|
|
183
|
-
─▶ … 反复 … ─▶ 客户端出片
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
**这几件事只能在客户端做（CLI 给不了）：**
|
|
187
|
-
|
|
188
|
-
| 环节 | 为什么必须在客户端 |
|
|
189
|
-
|---|---|
|
|
190
|
-
| **B-roll 候选挑选** | `gtrk matrix` 铺 N 条候选轨，用轨道**小眼睛**逐条切换对比、选定、删多余——审美取舍只能人在客户端做 |
|
|
191
|
-
| **MG / 颗粒精修** | 客户端里 html-particle **活颗粒透明预览** + Transform/Blending/Effects 参数逐帧微调 |
|
|
192
|
-
| **口播精剪** | 磁性主轨 ripple、手动微调切点 / 停顿 / 分屏 |
|
|
193
|
-
| **AI 情景动画回铺** | 外部平台出的 AI 片段**手动拖进 AI_DRAMA 车道**对齐区间（`/gtrk-ai-drama` 只吐描述稿，片在外部平台出，见 SOP ③——它属底轨阶段，MG 要等它落位后才铺） |
|
|
194
|
-
| **最终出片** | 多车道合成（overlay / MG / particle 云渲叠起来）+ 剪映草稿导出，都在客户端出片链 |
|
|
195
|
-
|
|
196
|
-
> **`gtrk render` 现在会合成叠加层了（1.1.10 起）。** 它按契约 z 序（`track_index` 升序）把**全部可见**的叠加层叠进成片——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 MG 颗粒都在内；在客户端关了「小眼睛」（`hidden`）的轨不进片。
|
|
197
|
-
>
|
|
198
|
-
> **颗粒那一段有计费**：CLI 没有 HTML 渲染引擎，颗粒要送同合云烤成透明 MOV 再本地叠。计量 = **唯一颗粒数 × 未命中缓存数**（按分钟），未命中时会先出预估并要你确认（`--yes` 跳过；`--json` 下必须显式 `--yes`）。**第二次渲染全命中缓存 ⇒ 零计费**；缓存与客户端导出剪映时那份**同键同落点**（`<工程目录>/.tonghe-cache/particles/`），所以客户端烤过的颗粒 CLI 直接命中、反之亦然。不想花钱用 `--no-particles` 出无颗粒版（overlay 视频轨照常合成，那部分零计费、纯本地）。
|
|
199
|
-
>
|
|
200
|
-
> **剪映草稿导出仍在客户端出片链**（`gtrk render` 只出 mp4）。
|
|
201
|
-
|
|
202
|
-
## 升级
|
|
203
|
-
|
|
204
|
-
> **从 1.0.x 升上来的先看这一条**：1.0.8 及更早版本铺出的工程带一处槽位接缝缺陷
|
|
205
|
-
> （主轨 −1 毫秒同轨重叠，`gtrk render` 会硬拒）。**本版修掉了产生它的原因，但修不了已经铺坏的工程**——
|
|
206
|
-
> 手上有旧工程就重跑一次 `gtrk matrix lay --project <目录>`。升级后旧工程仍渲不出，
|
|
207
|
-
> 不是新版没修好，是那份工程还带着旧缺陷。详见 [CHANGELOG](./CHANGELOG.md)。
|
|
208
|
-
|
|
209
|
-
**CLI + skill**（配置原样保留）：
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
gtrk upgrade # 有新版则升到最新 + 刷新 skill
|
|
213
|
-
gtrk upgrade --check # 只看有没有新版，不动手
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
> 用 `npx` 的（没全局装）本就每次拉最新：`npx @gitruck/cli@latest install`。`gtrk doctor` 也会顺带提示「有新版可升级」。
|
|
217
|
-
|
|
218
|
-
**桌面客户端**：重跑一键安装脚本即覆盖装最新版（per-user、免管理员、配置不动）：
|
|
219
|
-
|
|
220
|
-
```powershell
|
|
221
|
-
irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
## 给 AI Agent 用
|
|
225
|
-
|
|
226
|
-
装好后，在各家 Agent 里一句话就能调用 gtrk 的 skill：
|
|
227
|
-
|
|
228
|
-
| | |
|
|
229
|
-
|:--:|:--:|
|
|
230
|
-
|  |  |
|
|
231
|
-
|  |  |
|
|
232
|
-
|
|
233
|
-
`gtrk install` 会把 18 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`·`gtrk-cover`·`gtrk-travel-recap`·`gtrk-live-slicing`·`gtrk-talking-head`·`gtrk-narration`·`gtrk-voiceover`·`gtrk-food-recap`·`gtrk-vlog-docu`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
|
|
234
|
-
|
|
235
|
-
默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
|
|
236
|
-
|
|
237
|
-
```bash
|
|
238
|
-
# 自动探测已安装的 Agent（等价核心：npx -y skills add <gtrk包根>/skills -g -y）
|
|
239
|
-
gtrk skills install
|
|
240
|
-
|
|
241
|
-
# 只装指定宿主；这里使用通用 skills CLI 的 Agent ID
|
|
242
|
-
gtrk skills install --agents codex,cursor,gemini-cli,trae-cn
|
|
243
|
-
|
|
244
|
-
# 安装到适配器当前支持的全部 Agent（会创建较多宿主目录）
|
|
245
|
-
gtrk skills install --all
|
|
246
|
-
|
|
247
|
-
# 不使用链接，每个宿主各复制一份
|
|
248
|
-
gtrk skills install --copy
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
> ⚠️ **升级 CLI 不会自动刷新已装的 skill。** `npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，
|
|
252
|
-
> 各 Agent 目录下那份 skill 仍是**上次装进去的快照** —— agent 会照着旧口径干活，**而且不报错**。
|
|
253
|
-
> 刷新走 `gtrk upgrade`（升 CLI + 刷 skill）或单独跑 `gtrk skills install`。
|
|
254
|
-
>
|
|
255
|
-
> 自 **1.1.3** 起这件事有信号了：需要 skill 的命令（`oralcut` / `long2short` / `split` / `matrix` /
|
|
256
|
-
> `mg` / `subtitle` / `project`）在检测到本机 skill 落后时，会往 **stderr** 提示一次并给出修复命令；
|
|
257
|
-
> 一致或判不出时**零输出**。随时自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」；
|
|
258
|
-
> 嫌吵用环境变量 `GTRK_SKILL_FRESHNESS=off` 整块关掉。
|
|
259
|
-
|
|
260
|
-
`--agents` 接受上游适配器和 gtrk 补充层的 Agent ID。国产 Agent 已覆盖 `trae`、`trae-cn`、`codebuddy`、`qoder`、`qoder-cn`、`qwen-code`、`kimi-code-cli`、`iflow-cli`、`codearts-agent`、`lingma`，并额外补充上游尚未登记的 `workbuddy`、`qoderwork`、`comate`。常见简写 `qwen`、`kimi`、`iflow`、`codearts`、`tongyi-lingma`、`qoder-work`、`baidu-comate` 也会自动映射。以后上游新增 Agent，gtrk 无须发版也能直接使用新 ID；已有脚本若必须写死一个目录，仍可用 `--dir <skills目录>` 走兼容复制模式。
|
|
261
|
-
|
|
262
|
-
不同 Agent 的**输入 UI 不统一**：Claude 常把 skill 名放进 `/` 补全；Codex 的不同客户端可从 `$`、`/skills` 或 Skills 面板进入；TRAE 以 Skills 设置、显式点名或语义触发为主。因此没看到 Claude 风格的 `/gtrk-*` 下拉，不代表 skill 没安装。新 skill 没出现时，刷新窗口或新开会话。
|
|
263
|
-
|
|
264
|
-
然后直接说「**帮我把这条口播剪一版**」，或在对应 Agent 的 Skills 入口显式选择 `gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
|
|
265
|
-
|
|
266
|
-
**一条龙都交给 agent**：不止剪口播——接着说「拆个分镜」「铺 B-roll」「铺 MG 颗粒」「渲成片」，agent 会配合各车道生产 skill 调 `gtrk split` / `gtrk matrix` / `gtrk mg` / `gtrk render` 跑完整条 **成片管线**。**你只管对话、敲 CLI 的活交给 agent**——下面的「命令参考」是给 agent 查参数用的，不用你自己去终端敲。
|
|
267
|
-
|
|
268
|
-
### agent 能驱动的能力（skill 驱动命令）
|
|
269
|
-
|
|
270
|
-
**每个功能 = 一个 skill（脑，你触发、懂 SOP 位置与用户交互）驱动一个 gtrk 命令（手，确定性机械活）。** 成片是**有先后的 SOP、每步用户可介入**，不是一次性并行铺完——`/gtrk-X` skill 负责在对的时机、带着你的确认，去跑 `gtrk X`：
|
|
271
|
-
|
|
272
|
-
| SOP | 驱动 skill（你对 agent 说） | 底层命令（agent 跑） | 做什么 |
|
|
273
|
-
|:--:|---|---|---|
|
|
274
|
-
| ① | `/gtrk-oralcut` | `gtrk oralcut` | 智能剪口播 → 客户端/剪映/PR 三方工程 + transcript |
|
|
275
|
-
| ② | `/gtrk-splitter` | `gtrk split` | 拆分派单 → `dispatch.json`（A_ROLL/MG/AI_DRAMA/FILM_BROLL 四车道） |
|
|
276
|
-
| ③ | `/gtrk-matrix` | `gtrk matrix` | **B-roll 底轨·影视/本地素材腿**：铺候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
|
|
277
|
-
| ③ | `/gtrk-ai-drama` | （无命令，纯创作） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
|
|
278
|
-
| ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent 纪律硬门，供 ⑤ 的排版避让决策使用 |
|
|
279
|
-
| ⑤ | `/gtrk-mg` | `gtrk mg` | **MG（含 ov）最后叠上**（叠在已定稿、构图已核的底轨之上） |
|
|
280
|
-
| — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
|
|
281
|
-
| ③′ | 「**屏录画中画**」 | `gtrk pip lay` | 把口播粗剪的切点镜像到同步录的屏录 / 第二机位，铺屏录满幅轨 + 人像画中画副本轨（圆 / 圆角方 / 爱心 / 菱形 / 星形蒙版，可圆角）；纯本地零计费；低置信时产对齐工程让客户端拖齐后 `--resume` |
|
|
282
|
-
| — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4（含 overlay 与 MG 颗粒；颗粒未命中缓存时云渲计费，`--no-particles` 可跳过） |
|
|
283
|
-
| ✂️ | `/gtrk-long2short` | `gtrk long2short` | 长剪短·粗剪：长视频语义选段+跳剪 → 逐 clip 出客户端/剪映/PR 三方工程（毛片不上传），**不在成片 SOP 序列内**、随时可独立用 |
|
|
284
|
-
| 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频/配音音频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |
|
|
285
|
-
| 🧰 | `/gtrk-tools` | `gtrk tool <name>` | 单点工具族（图转运镜 / 图片·视频抠像…）——单发单收，**不在成片 SOP 序列内**、随时可独立用 |
|
|
286
|
-
| 🎵 | `/gtrk-music-visualizer` | `gtrk music-visualizer` | 一首歌 → 频谱可视化成片（模板 + 可选背景/封面 + 配色样式），**不在成片 SOP 序列内**、独立引流用 |
|
|
287
|
-
| 🖼️ | `/gtrk-cover` | （无命令，纯创作） | 封面工作台两阶段：设计诊断 + 三尺寸中英双版文生图 Prompt → 用户外部平台抽图 → H5 排字工作台（拖拽/滚轮微调、一键导出多尺寸 PNG）。栏目封面审美经栏目配置 `style.skills`（`produces:"cover"`）注入；**不在成片 SOP 序列内**（投放配套的「第 0 阶段」） |
|
|
288
|
-
| 🧭 | `/gtrk-talking-head` | 编排 `gtrk audio` → `oralcut` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **口播链图纸**：一条或一组真人出镜毛片 → 外录音轨对齐换轨、多段拼接、粗剪、拆分派单、B-roll/MG 字卡、BGM、字幕 → 客户端可出片工程 |
|
|
289
|
-
| 🧭 | `/gtrk-travel-recap` | 编排 `gtrk tool audio_tts_clone` → `project init` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **旅拍解说图纸**：旅拍素材夹 → AI 理解素材、写三段式解说稿、一次确认 → 配音/建工程/拆分/B-roll/字卡/BGM/字幕全自动跑完 → 客户端可出片工程 |
|
|
290
|
-
| 🧭 | `/gtrk-live-slicing` | 编排 `gtrk long2short`（超长回放先分段） | **直播切片图纸**：数小时直播回放 → 分段（服务端 2h 硬闸）→ 选题清单确认 → 一批逐 clip 粗剪工程（gtrk + 剪映 + PR），按画面形态配分屏 |
|
|
291
|
-
| 🧭 | `/gtrk-narration` | 编排 `gtrk transcript` → `project init` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **通用解说图纸（解说链正本）**：素材自带时序的长东西（影视长片/游戏实况/探店记录…）→ 提炼梗概与看点 → 精简叙述重讲成解说成片工程；旅拍解说与美食解说是它的垂类实例 |
|
|
292
|
-
| 🧭 | `/gtrk-voiceover` | 编排 `gtrk tool audio_tts_clone` → `project init` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **配音链快速成片预设**：写好的稿（或 AI 代写）→ 配音 → 自动配画面 → 字卡/BGM/字幕 → 客户端可出片工程；适用科普/情感电台/观点/带货/盘点等无自带时序的题材 |
|
|
293
|
-
| 🧭 | `/gtrk-food-recap` | 沿 `/gtrk-narration` 链路 | **美食解说垂类图纸（解说链示例）**：探店/密着纪实长片或做饭流程记录 → 提炼看点重述成中文美食解说成片工程 |
|
|
294
|
-
| 🧭 | `/gtrk-vlog-docu` | 编排 `gtrk transcript` → `tool audio_tts_clone` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **Vlog 纪实图纸**：一批现场素材 → 素材理解、选档写稿、一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端可出片工程；「现场同期声 × 后期旁白」双声道交替，区别于纯口播链与纯配音链 |
|
|
295
|
-
|
|
296
|
-
> **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑤ 步（B-roll 三源全齐、构图核过才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
|
|
297
|
-
> 上面 18 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，四者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
|
|
298
|
-
|
|
299
|
-
**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
## 栏目与风格：两层结构
|
|
304
|
-
|
|
305
|
-
> **栏目配置是装修厨房，成片是每天做菜。你不会每做一道菜先重新装修一遍厨房，但每道菜确实都在你装修好的厨房里做。**
|
|
306
|
-
|
|
307
|
-
整个体系分两层，时间尺度完全不同：
|
|
308
|
-
|
|
309
|
-
**【栏目层 · 一次性/低频】= 建栏目（装修厨房）**
|
|
310
|
-
跑 `/gtrk-style-maker`（meta skill），它通过启发式访谈帮你想清楚**你自己的**视觉语法——不预设任何维度：不假设你有叙事结构、有主题系统、视觉分动画/实拍，你的维度和取值全部由你自己定义。产出：
|
|
311
|
-
|
|
312
|
-
- 你自己的可执行 skill 家族（落到当前 Agent 的用户级 skills 目录，黑盒、留本地）
|
|
313
|
-
- 栏目内共享词表（家族各 skill 引用，防多处定义漂移）
|
|
314
|
-
- 栏目配置 `~/.gitruck/columns/<id>.json`（词表 vocab + B-roll 检索偏好 + style 引用清单）
|
|
315
|
-
|
|
316
|
-
**【成片层 · 每片跑】= 做菜（流程形状不变）**
|
|
317
|
-
剪口播 → 拆文稿 → 派单（B-roll 检索 / 动效 / 情景动画）→ 装配 → 渲染。每一步显式消费当前栏目配置：拆文稿按你的词表校验（`--column <id>` 或 config `defaultColumn`），B-roll 检索按你栏目的检索偏好（`broll.column_tag_ids` 栏目标签 / `material_class_policy` / facets），各车道走你自己的生产 skill。
|
|
318
|
-
|
|
319
|
-
**不建栏目？直接用默认"厨房"。** 零配置 = 内置默认栏目，端到端照常跑通，行为与配置化之前逐字节一致——栏目层是可选资产，不是必经关卡。
|
|
320
|
-
|
|
321
|
-
**管线契约**：框架对审美零预设、对管线接口全权威。产物要进渲染管线的 skill 须满足对应契约（见 [`contracts/`](./contracts/README.md)，如 HTML 动画颗粒的 `gsap-emit v1`）；契约只约束机器可判定的管线属性，画面长什么样永远归你。
|
|
322
|
-
|
|
323
|
-
---
|
|
324
|
-
|
|
325
|
-
## 配置
|
|
326
|
-
|
|
327
|
-
`gtrk init` 把配置写到 `~/.gitruck/config.json`（用户级统一目录，config / 缓存 / ffmpeg / 栏目配置全在 `~/.gitruck/`）。读取优先级：**环境变量 / `.env` > `init` 持久配置 > 默认根地址**。
|
|
328
|
-
|
|
329
|
-
| 项 | 来源 | 说明 |
|
|
330
|
-
|---|---|---|
|
|
331
|
-
| `GITRUCK_API_KEY` | env / init | 鉴权 Header `Authorization` 的**裸值**（非 Bearer） |
|
|
332
|
-
| `GITRUCK_API_BASE` | env / init | API 根地址，默认 `https://api.ai-mcn.tv:10000` |
|
|
333
|
-
| 剪映草稿目录 | init / 自动探测 / `--jianying-draft-dir` | 决定剪映草稿落哪、能否直接打开 |
|
|
334
|
-
| `defaultColumn` | config.json 手填 | 缺省栏目配置 id（`gtrk split` 未传 `--column` 时用它；再缺省 = 内置默认栏目） |
|
|
335
|
-
| 栏目配置 | `~/.gitruck/columns/<id>.json` | 一栏目一文件；由 `/gtrk-style-maker` 生成登记，也可手写 |
|
|
336
|
-
|
|
337
|
-
非交互配置（脚本 / CI）：
|
|
338
|
-
|
|
339
|
-
```bash
|
|
340
|
-
gtrk init --api-key <KEY> --jianying-draft-dir auto -y
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
随时 `gtrk doctor` 自检：
|
|
344
|
-
|
|
345
|
-
```
|
|
346
|
-
✅ 运行时：node v24.x
|
|
347
|
-
✅ CLI 版本：v0.3.0（已是最新）
|
|
348
|
-
✅ API Key：已配（gc_xxx…）
|
|
349
|
-
✅ 云端连通 + 鉴权：可达，鉴权通过
|
|
350
|
-
✅ 剪映草稿目录：C:\Users\…\com.lveditor.draft
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
### 枚举清单（`--refresh-catalog`）
|
|
354
|
-
|
|
355
|
-
`gtrk doctor` 里有一行「枚举清单」：CLI 从服务端拉一份**对外枚举的全集**（字幕样式与颜色、语种码、
|
|
356
|
-
工程文件格式、节奏预设、任务可用性等），落在 `~/.gitruck/catalog.json`，24 小时自动刷新。
|
|
357
|
-
|
|
358
|
-
有了它，`--subtitle-type` 这类参数传错时**在上传之前**就告诉你，并列出当前可用值；
|
|
359
|
-
服务端新增一种样式，你不必升级 CLI 就能用上。
|
|
53
|
+
准备一个支持 Skills、能执行本地命令的 AI Agent，以及 **Node.js ≥ 20.6**。
|
|
360
54
|
|
|
361
55
|
```bash
|
|
362
|
-
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
**拉不到清单不影响使用**：CLI 会沿用上一次的快照；完全没有快照时**跳过本地校验、直接提交**，
|
|
366
|
-
由服务端裁决——服务端白名单永远是唯一真相源。要彻底关掉这次拉取，设 `GITRUCK_CATALOG_OFFLINE=1`。
|
|
367
|
-
|
|
368
|
-
### 崩溃报告与关闭方式
|
|
369
|
-
|
|
370
|
-
gtrk 崩溃时（未捕获异常 / 未处理的 Promise 拒绝 / 顶层出口的程序缺陷）会自动上报一条报告，帮我们定位缺陷。**默认开启，首次配置时会告知一次。**
|
|
371
|
-
|
|
372
|
-
**发送的内容只有这些**：错误消息、错误堆栈、来源标识（`cli`）、CLI 版本号、本次累计发生次数，以及（仅当崩溃发生在一个云端任务过程中时）那个任务的 ID。
|
|
373
|
-
|
|
374
|
-
**明确不发送**：素材文件与内容、工程文件与路径列表、你的文稿、API Key（发送前会把 Key 的字面值与形如 `gc_…` 的 token 替换成 `<KEY>`）、设备标识、主机名、环境变量。
|
|
375
|
-
|
|
376
|
-
**只上报「崩溃」，不上报「预期内的失败」**：文件不存在、参数不合法、额度不足、命令用错——这些你看得懂的报错一条都不会发。
|
|
377
|
-
|
|
378
|
-
三种关法（任选其一，都是即时生效）：
|
|
379
|
-
|
|
380
|
-
```bash
|
|
381
|
-
gtrk init --no-crash-report # 写进配置，永久关
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
```bash
|
|
385
|
-
GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4 # 环境变量，临时关一次（优先级高于配置）
|
|
386
|
-
```
|
|
387
|
-
|
|
388
|
-
或直接在 `~/.gitruck/config.json` 里写 `"crashReport": false`。
|
|
389
|
-
|
|
390
|
-
当前状态随时可查：`gtrk doctor` 的「崩溃自动上报」一行会写明开 / 关，以及关是被谁关的。关闭后崩溃的呈现与退出码**与开启时完全一致**——它只影响发不发那条报告。
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## 命令参考
|
|
395
|
-
|
|
396
|
-
### `gtrk transcript <本地视频|配音音频>`
|
|
397
|
-
|
|
398
|
-
把本地视频或配音音频转为一个多层级的 Markdown 文字稿。只接受本地文件路径：视频在本机抽取、音频在本机转码为 16 kHz 单声道音频，只上传音频衍生物，原文件不会上传，也不支持 URL 或平台视频下载。
|
|
399
|
-
|
|
400
|
-
```bash
|
|
401
|
-
gtrk transcript "D:/素材/采访视频.mp4"
|
|
402
|
-
gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/采访.md" --json
|
|
56
|
+
npx @gitruck/cli@latest install
|
|
403
57
|
```
|
|
404
58
|
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
1. `## 总结`：CLI 先标记为待完成，由 `/gtrk-transcript` 驱动 Agent 阅读全文后生成并写回；
|
|
408
|
-
2. `## 文字记录`：以 `[00:01:23]` 开头的可读段落；
|
|
409
|
-
3. `## 纯文本`：完整识别正文，便于整段复制。
|
|
410
|
-
|
|
411
|
-
实时计费在运行前从官网价格表按 `asr` 查询，CLI 与文档不保存价格数字。`--json` 的 stdout 只输出 `{ok,taskId,fileId,output,transcriptJson,summaryPending}`，其中 `output` 指向这一个 Markdown；`summaryPending:true` 表示 `/gtrk-transcript` 驱动 Agent 还需生成语义总结、原地替换待总结标记，完成后仍只交付同一个文件。
|
|
412
|
-
|
|
413
|
-
> `--json` 时另在源文件旁产一份句级时码 `<名>-transcript.json`（`utterances[]{id,text,st,ed}` + `material_id` + `text_hash` + `duration`，与 `gtrk split` 的 transcript 结构逐字段对齐），可直接被 `gtrk project init --transcript` 兜底路消费。**TTS 合成的配音勿走本零件重跑 ASR**——`gtrk project init --tts-task` 直取服务端句级时码，零 ASR 零额外计费。
|
|
414
|
-
|
|
415
|
-
### `gtrk oralcut <毛片>`
|
|
416
|
-
|
|
417
|
-
| 参数 | 作用 | 缺省 |
|
|
418
|
-
|---|---|---|
|
|
419
|
-
| `-s, --script <file>` | 文字稿 txt（有稿按稿剪、更准） | 探毛片同名 `.txt`；无则无稿智能重建 |
|
|
420
|
-
| `-p, --preset <p>` | 节奏 `steady`\|`concise`\|`compact`（松→紧） | `concise` |
|
|
421
|
-
| `-o, --out <dir>` | 自定义产物目录 | `<毛片名>-video-project-<时间戳>` |
|
|
422
|
-
| `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
|
|
423
|
-
| `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
|
|
424
|
-
| `--reupload` | 强制重传，忽略上传缓存 | 关 |
|
|
425
|
-
| `--no-open` | 完成后不自动打开产物目录 | **默认自动打开** |
|
|
426
|
-
| `--json` | 机读：stdout 只输出结果 JSON（给 agent / 脚本） | 关 |
|
|
59
|
+
安装器会配置 gtrk、安装配套 Skills，并引导填写 API Key。Key 在[同合云控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)获取；调用云端能力需要账户和可用额度。完成后重新打开 Agent 会话，让新 Skills 生效。
|
|
427
60
|
|
|
428
|
-
|
|
61
|
+
把素材文件夹交给 Agent，然后说：
|
|
429
62
|
|
|
430
|
-
>
|
|
63
|
+
> 帮我把「口播.mp4」做成一期视频，文字稿在同目录。先给我看制作方案。
|
|
431
64
|
|
|
432
|
-
|
|
65
|
+
只想先粗剪，也可以说：
|
|
433
66
|
|
|
434
|
-
|
|
67
|
+
> 把这条口播剪一版，去掉重复和长停顿，给我能在剪映里继续改的工程。
|
|
435
68
|
|
|
436
|
-
|
|
437
|
-
|---|---|---|
|
|
438
|
-
| `-o, --out <dir>` | 产物目录 | **必填**（2026-09-08 起无缺省；`--out .` = 当前目录本身） |
|
|
439
|
-
| `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
|
|
440
|
-
| `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
|
|
441
|
-
| `--no-open` / `--json` | 同 `oralcut` | — |
|
|
69
|
+
**Windows 推荐同时安装桌面客户端**，用于预览和精修：[全套安装指南](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [客户端下载](https://cloud.ai-mcn.tv/zh-CN/download)。CLI 支持 Windows、macOS、Linux；桌面客户端目前提供 Windows 版。
|
|
442
70
|
|
|
443
|
-
>
|
|
444
|
-
|
|
445
|
-
### `gtrk split [拆分稿]` — 视觉拆分派单器
|
|
446
|
-
|
|
447
|
-
成片 × transcript 投影 → beat 分镜。**无 positional = 导出投影视图**（把当前 `.gtrk` 时间线 × transcript 投影成 beat 视图，供拆分/校对，不写回）；**带拆分稿 = 校验落地**（校验拆分稿机器契约 → 投影出 beat 时码 → 原子写回 `struct_meta.split` + 产 `split/dispatch.json` 派单清单，驱动 A_ROLL / MG / AI_DRAMA / FILM_BROLL 四车道）。时码永远归 CLI（拆分稿只描述「哪段做什么」、不写时码）。
|
|
448
|
-
|
|
449
|
-
| 参数 | 作用 | 缺省 |
|
|
450
|
-
|---|---|---|
|
|
451
|
-
| `--project <dir>` | oralcut 产物目录（自动定位 `gtrk/project.gtrk` 与 `transcript/transcript.json`） | — |
|
|
452
|
-
| `--gtrk <path>` / `--transcript <path>` | 显式指定工程 / transcript（非标准布局兜底） | 由 `--project` 推 |
|
|
453
|
-
| `--column <id>` | 栏目配置 id（按你栏目词表校验 lane / category / produces） | config `defaultColumn` → 内置默认栏目 |
|
|
454
|
-
| `--md` | 落地时额外渲染人读稿 `split/visual-split.md`（由 JSON 单向渲染） | 关 |
|
|
455
|
-
| `--words` | 视图模式附字级明细 | 只出句级 |
|
|
456
|
-
| `--json` | 机读：stdout 只输出结果 JSON | 关 |
|
|
457
|
-
|
|
458
|
-
> 落地产物 `dispatch.json` 三队列 → 下游消费：`mg`（MG 颗粒）→ `gtrk mg` 命令、`film_broll` → `gtrk matrix` 命令、`ai_drama` → `/gtrk-ai-drama` skill（产四段描述稿·中英分块，纯创作、无命令）。配套 skill `/gtrk-splitter` 产拆分稿。
|
|
459
|
-
>
|
|
460
|
-
> **派单条目自带 `span:{from,to}`**（该条目对应的 utterance 区间；`overlay` aux 派生条目写 **aux 自己的** span，可为主 beat span 的子区间）。**`track_st/track_ed` 是投影时刻的快照**——`gtrk mg` / `gtrk matrix` 消费时会**现场重投影**（见下），所以改完口播轨**不必**回来重跑 `gtrk split`，只有拆分稿本身变了才要重跑。
|
|
461
|
-
|
|
462
|
-
### `gtrk patch <move|trim|split|set>` — 元素级编辑（改工程唯一入口）
|
|
463
|
-
|
|
464
|
-
改一个 clip / gap / 颗粒的时码或参数。**agent 勿裸手改 `.gtrk` JSON** —— 片段时码是两套并存的
|
|
465
|
-
（`clip_st`+`clip_ed` 与 `clip_st`+`duration`），改一份不改另一份是**静默失败**：客户端优先读 `clip_ed`，
|
|
466
|
-
而后端不强校验它，于是没人报错、成片却用了陈旧出点。本命令负责恒等式同步 + 帧对齐 + 写前全档校验。
|
|
467
|
-
|
|
468
|
-
```bash
|
|
469
|
-
gtrk patch move --project <dir> --clip c2 --to 5.0
|
|
470
|
-
gtrk patch trim --project <dir> --clip c2 --out -1s
|
|
471
|
-
gtrk patch split --project <dir> --clip c2 --cut 5.5
|
|
472
|
-
gtrk patch set --project <dir> --track audio:1 --at 3.0 --volume 0.5
|
|
473
|
-
```
|
|
474
|
-
|
|
475
|
-
| 参数 | 作用 | 缺省 |
|
|
476
|
-
|---|---|---|
|
|
477
|
-
| `--project <dir>` / `--gtrk <path>` | 工程目录（自动定位 `gtrk/project.gtrk`）或直接给路径 | — |
|
|
478
|
-
| `--clip <clip_id>` | 按 id 寻址。命中 video/audio **镜像对**时视为一个编辑单元 | — |
|
|
479
|
-
| `--track <kind:idx> --at <sec>` | 按位置寻址（`track_st ≤ at < track_ed`）。与 `--clip` 互斥 | — |
|
|
480
|
-
| `--to <sec\|Nf>` | `move` 的落点 | — |
|
|
481
|
-
| `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | `trim` 的五种语义（前两个相对、中两个绝对、`--slip` 只换源窗） | — |
|
|
482
|
-
| `--cut <sec\|Nf>` | `split` 的切点。⚠️ 与寻址用的 `--at` 是两个参数 | — |
|
|
483
|
-
| `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
|
|
484
|
-
| `--total <sec\|Nf\|max>` | `set` 的顶层总长（工程级 op，与元素寻址互斥） | — |
|
|
485
|
-
| `--ops <file\|->` | 批量事务：一次读、全算、全校验、一次写；任一条失败**零写** | 关 |
|
|
486
|
-
| `--dry-run` | 只算与校验、不写文件 | 关 |
|
|
487
|
-
| `--json` | 机读回执到 stdout（人读日志转 stderr） | 关 |
|
|
488
|
-
|
|
489
|
-
> 时码字面：秒（`3.5` / `3.5s`）或帧（`105f`）；相对量带正负号（`-1s`）。
|
|
490
|
-
>
|
|
491
|
-
> 回执含 `ops[].resolved` 定位三元组 `{track, clip_id, track_st}` —— 下一轮据它复核「所指是否仍是同一元素」。
|
|
492
|
-
> `preexisting[]` 是**入档既存**的不变量问题（非本次造成，不阻断）；本次改动造成违规则**零写非 0**。
|
|
493
|
-
>
|
|
494
|
-
> ⚠️ 空档（gap）不能用 `--clip ""` 寻址：契约允许多个 gap 共享该取值，它不构成地址；用 `--track/--at`。
|
|
495
|
-
|
|
496
|
-
### `gtrk matrix` — B-roll 检索 + 候选铺轨
|
|
497
|
-
|
|
498
|
-
**无 positional = 派单消费**：读 `split/dispatch.json` 的 `film_broll` 队列 → 双口检索 → 产候选清单 `split/broll-plan.json` + 下载 preview 代理、在工程里平铺 N 条候选轨（opencut 打开即可用轨道小眼睛对比挑选）。**`matrix search "<query>"` = 单条 ad-hoc 检索**（不依赖派单）。**`matrix fetch <clip_id...>` = 精剪期拉原片**（脱离工程，见下）。
|
|
499
|
-
|
|
500
|
-
| 参数 | 作用 | 缺省 |
|
|
501
|
-
|---|---|---|
|
|
502
|
-
| `--project <dir>` | oralcut 产物目录（定位 `split/dispatch.json` 与产物落点） | — |
|
|
503
|
-
| `--dispatch <path>` | 显式指定 `dispatch.json` | 由 `--project` 推 |
|
|
504
|
-
| `--column <id>` | 栏目配置 id（按你栏目 B-roll 检索偏好：标签 / material_class / facets） | config `defaultColumn` → 内置默认栏目 |
|
|
505
|
-
| `--lay <n>` | 候选铺轨数：平铺 N 条 B-roll 候选轨（`0` = 只出 plan 不铺轨） | `1` |
|
|
506
|
-
| `--top-k <n>` | 每 query 候选数上限（覆盖派单 shots；服务端上限 50） | 派单值 |
|
|
507
|
-
| `--material-class <c>` | 素材类型 `real_shot` \| `concept`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
|
|
508
|
-
| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——留空处**露黑底垫轨**（默认铺；除非 `--no-black-bed` 才露主轨）。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
|
|
509
|
-
| `--no-black-bed` | 不铺纯黑底垫轨（默认铺一条） | 默认铺 |
|
|
510
|
-
| `--force-relay` | 候选轨已被你在客户端编辑过时仍强剥重铺（缺省会拒铺并保留那条轨）——**会删掉已确认原片的 `broll-raw-*` 素材登记、盘上原片成孤儿** | 关 |
|
|
511
|
-
| `--arrange <m>` | **B-roll 编排取数路**，**按素材来源自动定档、一般不用传**：铺你自己电脑里的素材 → `cloud`（编排在云端做，按「编排量」计费，跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 → `local`（编排仍在本机、不计费，逐字不动）。`shadow` 是观测档：本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` 不受理（传了报参数错）；云端拿不到产物时**直接报错**，不会悄悄换算法把活干完 | 按素材来源自动 |
|
|
512
|
-
| `--arrange-qc` | **编排期质检**（缺省关）：落轨**之前**就查每个 beat 的卡点句「画面有没有给到稿子说的东西」，没给到就换候选重排，最多 2 轮，到限即交付并如实登记还差哪几句。全程零渲染——替代「铺完 → 渲 → 看 → 重铺 → 再渲」那两轮。⚠️ 判定走素材理解口、**按帧计费**（每个卡点句 1 帧/轮，命中判定缓存的不重复计费），跑前报预估并征求确认（`--yes` 跳过）。与 `--arrange` 正交：本机档与云端档都能开 | 关 |
|
|
513
|
-
| `--arrange-cost-cap <n>` | 云端编排单次编排量上限：超限服务端**前置拒绝**、零执行零计费（不是跑到一半掐断）。只在 `--arrange shadow\|cloud` 时有意义 | 不限 |
|
|
514
|
-
| `--dump-request <file>` | **排障用**：把**实际上行的**云端编排请求体逐字节写到该文件。服务端**不保存你的 plan**（只留规模摘要），所以出了问题只有这份文件能复现——把它发给我们即可。⚠️ **不能指向工程目录内**（工程会被打包、拷贝、同步出去，而这份文件里有你的 beat 名与检索词）；开 `--arrange-qc` 时每轮各写一份，第 N 轮落在同名加 `.roundN`。机读回执在 `lay.arrange_run.dump_request` | 不写 |
|
|
515
|
-
| `--explain` | **外发调参仪表**：缺省的机读账面只给「留空槽数」`lay.dedup.emptySlots`（够判断素材池是不是不够用），其余调参用的细账（其中多少是窗口精修致空、跳剪避让枯竭放行几次、取用了几个高运动/模糊段）收在本开关后，人读日志同口径。不影响任何决策，工程产物逐字节不变 | 关 |
|
|
516
|
-
| `--arrange-estimate-only` | **只要预估不要执行**：走到云端编排的计价确认那一步就停，报出编排量后**成功**返回（`ok:true` + `estimateOnly:true`——那是「我在做决定」，不是「我拒绝了」），零云端调用、工程文件零改动。机读值在 `lay.arrange.units` / `lay.arrange.scale`。⚠️ 它省的是**云端那一次调用与其计费**（以及其后的候选下载与落轨），不是整条链：编排量的分母本来就要读工程、读 plan、做重投影才算得出。素材矩阵路报 `applicable:false` 而**不是 0**。与 `--yes` 同给时以本开关为准 | 关 |
|
|
517
|
-
| `--cut-align <ratio>` | 句界吸附目标比例 0..1：`0.7` ≈ 约七成字幕句起点恰逢镜头切点、三成有意错开（全对齐反而机械），`0` = 关闭、回旧节奏切槽。⚠️ 句级时码取 `transcript` 现场重投影（与关键词锚同源），**重投影降级时自动回旧行为并告警**——那一轮的吸附比例不作数 | `0.7` |
|
|
518
|
-
| `--gap-fill <mode>` | 音频驱动工程主轨的空洞怎么填：`fast` = **尽量不留黑**（放宽 score 地板从候选池填 → 耗尽则延长相邻颗粒 → 再耗尽跨 beat 借候选 → 短于最小镜头长的残洞也补真画面 → 补不满整段才垫黑片）；`solid` = 一律黑片垫齐（精修时一眼看出「这里没匹配到」）；`none` = 原样留 gap。⚠️ `fast` 借来的画面与本段稿子相关性弱、次地板槽是不到 1.2s 的快切，两者都会在日志里按 `kind` 报成 `borrowed` / `subfloor`——**如实告知，不是缺陷**；`none` 撞上客户端主轨磁吸会把 gap 吸掉，导致其后画面与配音**整体错位** | `solid` |
|
|
519
|
-
| `--highlight-weight <w>` | 仅 `matrix lay`：把「有没有看点」（信息量 / 戏剧性 / 情绪强度 / 稀缺性）融进候选排序，0..1。与 `--mark-weight`（画面好不好看）**正交**，两权之和钳到 1。⚠️ 看点分取 `describe` 的理解缓存，**没跑过 `describe` 就等于没开**——无缓存候选按中性处理，权重回吐给相似度 | `0`（关闭、零回归） |
|
|
520
|
-
| `--decode-path <mode>` | 仅 `matrix index`：场景检测的解码路 `auto` \| `gpu` \| `cpu` \| `full`。`auto` 自动探测硬解并**逐素材降级**（推荐）；`gpu`/`cpu`/`full` 钉死某档且**失败不降级**（对照与排障用）。⚠️ 缺省仍是 `full`（旧行为），要提速得自己传 `auto` | `full` |
|
|
521
|
-
| `--proxy-width <n>` | 仅 `matrix index`：代理解码宽度。⚠️ 再往下保真度明显劣化，**勿随手调小** | `384` |
|
|
522
|
-
| `--proxy-scaler <name>` | 仅 `matrix index`：代理缩放算法。缺省 `neighbor`（点采样不滤波，实测比 `bicubic` 又快又准）。⚠️ 改它基本只有做对照实验才需要 | `neighbor` |
|
|
523
|
-
| `--exclude-recent <n>` | 仅 `matrix material --scope audio`：选曲避让最近 n 首用过的 BGM。历史由 `audio lay` 落轨**自动记账**，不用自己维护 | `12` |
|
|
524
|
-
| `--no-exclude-recent` | 关掉上一条的选曲避让，允许复用近期曲目 | 关（缺省避让） |
|
|
525
|
-
| `--out <file>` | ad-hoc 模式结果落文件；`matrix fetch` 原片落盘目录（绝不写剪映草稿目录） | stdout / `./matrix-fetch/` |
|
|
526
|
-
| `--json` | 机读：stdout 只输出结果 JSON | 关 |
|
|
527
|
-
|
|
528
|
-
**`matrix fetch <clip_id...>`（精剪期拉原片，脱离工程）**：对**计费检索过**（授予账本命中）的素材按 clip_id 免费重签新鲜下载直链并落盘 `<clip_id>.<ext>`——粗剪导剪映后想补一段 B-roll，不回客户端就能拉到本地直接拖进剪映。动线恒为**两段式**：`matrix search` 挑定 clip_id → `matrix fetch` 拉取（fetch 自身零计费、不发起检索、无确认闸）。**授予持久**：24h 过期签名不构成障碍，三天前 search 出的 clip 照样 fetch。未购项逐条报「未购授予」并给出路（对该词跑一次计费检索即获授予），不连坐其余；单批 ≤500。**首发只覆盖视频 clip 原片**（图片/音频素材重签面未开，进 missing 附提示）。产物不进 `.gtrk`、不写剪映草稿目录；在剪映里补的料不回流工程（导出单向）。
|
|
529
|
-
|
|
530
|
-
> **beat 窗口现场重投影**：派单消费模式在**发起第一次云端检索之前**，用「`transcript` × 当刻 `.gtrk`」重算每个 beat 的 `[track_st, track_ed]`，检索、`broll-plan.json` 与铺轨一律以重算值为准（`--lay 0` 同守；ad-hoc `search` 不受影响）。`dispatch.json` 里的时码只是**投影时刻快照**，仅在重投影不可行时兜底——**所以改完口播轨直接跑本命令即可，不必先重跑 `gtrk split`**。`--json` 恒出 `reprojection:{mode,degraded,reason?,drifted,max_offset,shrunk,dropped}`；重投影后**零存活**的 beat 会被跳过（不为它烧检索配额、也不铺）。重投影不可行（transcript 缺失 / 工程定位不到 / 主轨查不到口播素材）→ **降级用快照 + 告警 + `--json` 标注**，检索与 plan 照产、不硬崩；非 v1 工程的既有行为不变（plan 先落盘、随后版本门非 0 退出）。
|
|
531
|
-
>
|
|
532
|
-
> **云端编排（`--arrange`）**：B-roll 的**编排决策**（哪一颗放哪、切多长、从素材的哪一段取）可以交给云端跑。
|
|
533
|
-
> 适用面只有一条：**本地素材上轨铺排**。素材库 / 普通素材 / 概念素材那些的匹配与铺排原来什么样、以后还什么样，
|
|
534
|
-
> 一个字节都不变。
|
|
535
|
-
>
|
|
536
|
-
> **不带这个参数时按素材来源自动定档**：铺你自己电脑里的素材走 `cloud`，铺素材库那些走 `local`。
|
|
537
|
-
> 本地素材的编排算法只在服务端迭代——改进当天生效，你不必升级客户端。
|
|
538
|
-
>
|
|
539
|
-
> ⚠️ **代价先说在前面**：本地素材的编排**只在云端完成**。云端拿不到产物（连不上 / 被拒 /
|
|
540
|
-
> 产物不合规）就**直接报错**，不会悄悄改用另一套算法把活干完——那会给你一份和云端不同的结果
|
|
541
|
-
> 而你并不知情。这条路上 `--arrange local` 不受理（传了会报参数错）。
|
|
542
|
-
>
|
|
543
|
-
> 跑前的用量确认你要是说「不跑」，**这一步就不做**（整轮铺轨中止，工程一个字节没动、plan 照常可用，随时可改主意重跑），
|
|
544
|
-
> 而不是换个便宜办法替你做完。
|
|
545
|
-
>
|
|
546
|
-
> ⚠️ **它不是省钱开关**：用素材矩阵的素材同样要付检索费。**两条路都要花钱，只是花在不同环节**——
|
|
547
|
-
> 自己的素材付编排费，矩阵素材付检索费（矩阵成员的检索是 0）。
|
|
548
|
-
>
|
|
549
|
-
> `shadow` 是观测档：本机照跑照铺轨、云端只跑一遍做对拍（**不切流**，产物仍用本机的），它不受上面那条报错规则影响。
|
|
550
|
-
>
|
|
551
|
-
> 云端两档按新计量维度**编排量**计费——要配画面的段落越多、每段候选素材越多、铺的候选轨越多就越贵。
|
|
552
|
-
> 跑前会报预估并征求确认，`--yes` 跳过、`--arrange-cost-cap` 设本次上限（超限**前置拒绝**，零执行零计费）。
|
|
553
|
-
> 完整计费口径（含既有的额度包 / 余额、阶梯价与免费档）见 **[计费说明](https://hocassian.feishu.cn/docx/DtendXStMogAbJxAOEmcCyC7n3e)**。
|
|
554
|
-
> ⚠️ 预估值只供双端一致性校验，**实际计费恒以服务端复算值为准**；两值不一致时服务端会拒绝执行且不计费。
|
|
555
|
-
> 上行的只有决策要读的字段——素材绝对路径、签名 URL、画面描述文本、派单负词、口播原文整句一律**不出你的机器**。
|
|
556
|
-
>
|
|
557
|
-
> **服务端一行不留**：那份上行的 plan 我们**不保存**（留痕只有规模明细、口径版本与复算金额，
|
|
558
|
-
> 够独立核对一笔账，但翻不出你的素材结构）。代价是**出了问题我们这边没有可复现的东西**——
|
|
559
|
-
> 所以给了 `--dump-request <file>`：它把真上行的那串字节留在**你自己的机器上**，
|
|
560
|
-
> 排障时把那个文件发给我们即可。缺省不写，且**不许写进工程目录**（工程是要被打包拷走的）。
|
|
561
|
-
>
|
|
562
|
-
> 频率上有两层保护，命中都是 **429、零执行零计费**：一层按次数限流；另一层认「同一份 plan
|
|
563
|
-
> 被反复换参数重提」这种形态。传输失败的重试发的是**逐字节相同**的请求体，不会被算进去。
|
|
564
|
-
>
|
|
565
|
-
> 候选的 `preview_url`/`cover_url` **不带签名、不会过期**（本地代理落盘后一律复用）；带签名约 24h 过期的是**原片 `url`**，由客户端「确认原片」链路重签——**不必为「重签」重跑本命令**。
|
|
566
|
-
>
|
|
567
|
-
> **重跑会剥旧重铺，但不碰你改过的轨**：候选轨的身份按「素材前缀 + 上一轮登记指纹」认，不再认轨号（客户端保存会把 overlay 轨整体重编号）。一旦某条候选轨被判定「你编辑过」（改过 clip，或在客户端确认过原片使 material 变成 `broll-raw-*`），本次**整体不铺**：不剥任何轨、不追加新轨、`.gtrk` 逐字节不变，`broll-plan.json` 照常产出，命令给出「哪条轨 / 什么证据 / 下一步」并以非 0 退出码结束（`--json` 出 `{ok:false, refused:[…]}`）。要强行重铺加 `--force-relay`。
|
|
568
|
-
>
|
|
569
|
-
> **机读账面：`counts.results` 是「去重前」口径**：`--json` 的 `counts.results` 恒是**逐 query 累加的检索响应条数**（既有口径不动）——15 条 query 各命中同一条素材时它就是 15，而 plan 落盘可能只有 8 行、只对应 1 个素材。要判「到底有多少料」读派单消费模式另出的三键：`counts.zero_yield`（**真·零产出**的 query 数，判据取**检索响应**为空，而非事后扫 plan 的 `results: []`——beat 内去重会把命中折进同 beat 的兄弟 query，折叠 ≠ 零产出）、`counts.plan_results`（plan **落盘后**的实际 result 行数，去重后）、`counts.distinct_clips`（plan 内 distinct `clip_id` 数）。这三键**只在派单消费模式**出现，ad-hoc `matrix search` 与 `matrix lay` 的 `counts` 逐字节不变（**缺席 = 没这个概念，不是「测出来是 0」**）。铺轨侧同理另出 `lay.beatsWithCandidates`（有候选的 beat 数）与 `lay.emptyBeats`（**零候选 beat 名单**——整段没有任何可铺的画面），两者恒满足 `beatsWithCandidates + emptyBeats.length = plan 的 beat 总数`。
|
|
570
|
-
>
|
|
571
|
-
> **素材落盘自检**：写回工程之后自动查一遍 `materials[].path` 是不是真的都落盘了（**只读、只报不动**）。相对路径恒以 **`.gtrk` 文件所在目录**（`<产物目录>/gtrk/`）为基准解析。`--json` 出 `integrity:{ checked, counts, dangling:[…], danglingReferenced, danglingOrphan, external:[…], noPathIds:[…] }`——`dangling` 是工程自带素材的**悬空引用**（登记在、文件不在）全量清单，每条标出**是否被时间线引用**及引用位置（被引用 = 那一段没素材可放，比孤儿严重得多）；绝对路径缺失另计 `external`（外接盘没挂载也会这样，不混进主判）；http(s) 素材只计数、**不发网络请求**。**这是告知不是拦阻**：查出悬空不改 `ok`、不改退出码、不删任何素材条目或文件。悬空多半是历史遗留（如客户端「确认原片」下载中断），修法是在客户端重新确认原片或删掉那条 clip。没写回的运行（`--lay 0` / 拒铺 / 工程缺失）**不出 `integrity` 字段**——缺席 = 本次没查，不是「查过且干净」。
|
|
572
|
-
>
|
|
573
|
-
> **纯黑底垫轨**：默认在全部候选轨之下、口播主轨之上垫一条纯黑底轨（`struct_meta.broll.black_track` 记其 `track_index`），按已落成的 beat 包络整条铺满，使 B-roll 期间（含候选轨留空处）不漏出底下的口播画面。**代价是「黑底空洞」**：候选轨没填满的地方就是纯黑压口播，铺轨会把它算出来——`--json` 恒出 `lay.blackBedHoleSec` 与逐段的 `lay.blackBedHoles`，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时另出一条非致命告警（不改退出码、不阻断铺轨），可据此调 `--score-floor`、改用 `--no-black-bed`、或到客户端手动补片。字节落 `assets/builtin/solid-000000-<W>x<H>.png`，与客户端内置纯色素材同 id 命名空间、幂等复用。删候选轨时别误删它；换片请拖到候选轨颗粒上、**别拖到黑底条上**——客户端 0.2.10 起（2026-07-31 发版强更）**拖到黑底条上会被直接拒绝并提示**。若客户端仍是 0.2.10 之前旧版（强更未拉到），旧行为是静默新建一条 video 轨插入、落点在下半区时预览完全看不见（按一次 `Ctrl+Z` 可整条撤销）——先重启客户端吃到强更。不想要黑底加 `--no-black-bed` 重跑即剥净。
|
|
574
|
-
|
|
575
|
-
**本地素材模式（`matrix index` / `--local`）**：素材不必入云端素材库，用你本地的素材文件夹（视频+图片混合）直接检索铺轨：
|
|
71
|
+
<details>
|
|
72
|
+
<summary>直接用命令、检查环境与升级</summary>
|
|
576
73
|
|
|
577
74
|
```bash
|
|
578
|
-
gtrk
|
|
579
|
-
gtrk
|
|
580
|
-
gtrk
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
>
|
|
595
|
-
>
|
|
596
|
-
|
|
597
|
-
>
|
|
598
|
-
>
|
|
599
|
-
>
|
|
600
|
-
>
|
|
601
|
-
>
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
|
694
|
-
|
|
|
695
|
-
|
|
|
696
|
-
|
|
|
697
|
-
|
|
|
698
|
-
|
|
|
699
|
-
|
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
- `gtrk tool audio_speaker_split ./meeting.mp3 [--only-struct]` — 按说话人分轨：默认产各说话人 `.wav` + `result-output.json`（`spoken_list` 时间线）；`--only-struct` 只出结构不切文件。
|
|
743
|
-
- `gtrk tool audio_stretch ./song.mp3 [--semitones -3] [--speed 1.5]` — 变调变速；音高与速度独立，`--speed` 必须 > 0。
|
|
744
|
-
- `gtrk tool audio_noise_reduce ./interview.mp4 [--prop-decrease 0.5]` — 音频或视频均可输入，统一输出降噪音频。
|
|
745
|
-
- `gtrk tool audio_silence_remove ./talk.mp3 [--min-silence-len 800] [--desired-silence-len 200]` — 移除过长静音，只落处理后的音频。
|
|
746
|
-
- `gtrk tool piano_audio_to_midi ./piano.mp3` — 钢琴音频扒谱为 `.mid`。
|
|
747
|
-
- `gtrk tool piano_audio_enhance ./piano.mp3` — 钢琴录音修复增强，产高质量 WAV 主产物 + 配套 MIDI 副产物。
|
|
748
|
-
- `gtrk tool image_to_square ./long.jpg [--max-line 8000]` — 长图转方图；`--max-line` 默认 4000、上限 20000。
|
|
749
|
-
- `gtrk tool image_to_live ./photo.jpg [--output-format motion_photo]` — 让静态照片动起来。缺省产出约 4 秒的 `.mp4` 短视频（无声）；`--output-format motion_photo` 改为直出**安卓动态照片**（单个 `.jpg`，静图末尾内嵌该视频，相册里长按即播），并附带同一条 `.mp4`，两种格式同价。兼容边界：支持该标准的安卓相册可识别并播放；**iOS 不识别**，表现为普通静态图片；少数安卓机型可能只显示静图。
|
|
750
|
-
- `gtrk tool image_classic_template a.jpg b.jpg c.jpg --main-title "新品速览"` — 标题+多图出封面/拼图；`--output-pic-count`/`--output-text-count` 由服务端钳制 ≤20。
|
|
751
|
-
- `gtrk tool image_vertical_stitch top.png mid.png bottom.png` — 多图按传入顺序竖拼成一张长图。
|
|
752
|
-
- `gtrk tool video_split_screen a.mp4 b.mp4 --output-ratio 16:9` — 简单档：整段视频自动布局分屏（reaction/对比同框）。
|
|
753
|
-
- `gtrk tool video_split_screen a.mp4 b.mp4 --clips-json '[{"input":0,"begin_time_ms":0,"end_time_ms":5000},{"input":1,"crop":{"x":0.1,"y":0,"width":0.8,"height":1}}]'` — 精确档：按 0 起索引指定每段毫秒区间与归一化裁剪框；同一文件可多条目出多窗口。
|
|
754
|
-
- `gtrk tool video_speaker_detect ./talk.mp4 --language zh-CN` — 检测画面里谁在何时说话，出结构化 JSON（重 GPU）。
|
|
755
|
-
- `gtrk tool video_face_track ./talk.mp4 --params-json '{"time_ranges":[{"begin_time":0,"end_time":30000}]}'` — 人脸追踪/身份聚类，可限定时间段（**单位毫秒**；重 GPU）。
|
|
756
|
-
- `gtrk tool audio_tts_clone --text "欢迎收听本期节目" --speaker narrator` — 文字转配音音频（音色列表见官网文档）。
|
|
757
|
-
- `gtrk tool audio_tts_clone --text-file 稿子.txt --speaker sweet_female --output-format mp3` — 长文合成，缺省跟随音色调好的语速与切分参数。
|
|
758
|
-
- `gtrk tool mad ./素材 [--bgm 歌.mp3] [--duration 20] [--seed 42] [--technique 技法名,…] [--refresh] [--json]` — 一键剪 MAD：扫素材文件夹 → 选技法 → 单一 `.jsx`（AE 2020+ 跑一遍出母合成成片工程）。`--seed` 可复现；`result.json` 记 seed/数据版本/降级档位/选中技法。
|
|
759
|
-
- `gtrk tool mad --technique <技法名 | 别名 | pid,…>` — 只用点名的技法出片（不点名则按规则抽样）。名字歧义或不存在时报错列候选、零落盘；点到技法池里没有窗口的技法会说明原因并用剩下的继续。
|
|
760
|
-
- `gtrk tool mad --search <关键词> [--json]` — 只查技法目录不出片：按技法名/别名/类目做包含匹配，列出技法名、类目、`pid`、收录次数与池内窗口数。与 `--technique` 互斥；两者都零计费、不需 API Key。
|
|
761
|
-
- 通用：`--out <dir>` 覆盖产物目录、`--param k=v`（可重复）/`--params-json '<对象>'` 透传云端参数、`--reupload` 忽略上传缓存、`--json` 机读、`--ffmpeg-path <dir>` 指定 ffmpeg 目录。
|
|
762
|
-
- cloud 型工具缺 Key → 报错引导 `gtrk init`。产物下载失败（如链接过期 404）→ `result.json` 记 `errors`、`ok=false`、`task.json` 保留可凭 `taskId` 恢复。
|
|
763
|
-
- 净化、超分、插帧为长耗时 GPU 任务，描述器最多轮询 4 小时。等待超时不代表任务取消；保留 `task.json` / `result.json` 并按 `taskId` 恢复，不要直接重跑造成重复计费。
|
|
764
|
-
|
|
765
|
-
配套 skill `/gtrk-tools`（一个 skill 覆盖整个工具族）。
|
|
766
|
-
|
|
767
|
-
### `gtrk render <工程.gtrk>` — 本地渲染成片
|
|
768
|
-
|
|
769
|
-
```
|
|
770
|
-
gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>]
|
|
771
|
-
[--no-qc] [--no-particles] [--particle-concurrency <n>] [-y|--yes]
|
|
772
|
-
[--no-open] [--json]
|
|
773
|
-
```
|
|
774
|
-
|
|
775
|
-
把 `.gtrk` 当 EDL 用本地 ffmpeg 出成片。**素材一律取本地原片**（`materials[].path`），云端不产成片。
|
|
776
|
-
|
|
777
|
-
**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。
|
|
778
|
-
|
|
779
|
-
- **可见性只读 `hidden` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
|
|
780
|
-
- **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。
|
|
781
|
-
- overlay 素材本地缺失（如 B-roll 代理没下全）**只降级不阻断**：该 clip 不叠 + 告警，片子照出。
|
|
782
|
-
|
|
783
|
-
**颗粒那一段有计费**（本命令唯一的云端出口）：
|
|
784
|
-
|
|
785
|
-
| 事 | 口径 |
|
|
786
|
-
|---|---|
|
|
787
|
-
| 为什么要上云 | CLI 无 HTML 渲染引擎，颗粒像素权威在同合云 Hyperframes；上行的只有**颗粒 HTML 文本**，素材本体不上行 |
|
|
788
|
-
| 计量 | **唯一颗粒数 × 未命中缓存数**（`html_render_simple`，按分钟）。同一颗粒在轨上出现 N 次只烤一次 |
|
|
789
|
-
| 缓存 | `<工程目录>/.tonghe-cache/particles/<sha256>.mov`，与**客户端导出剪映**那条链**同键同落点** ⇒ 任一端烤过，另一端直接命中 |
|
|
790
|
-
| 确认 | 有未命中即先出预估（总数 / 唯一 / 未命中 / 计费分钟）并要确认；`--yes` 跳过。**全命中不弹确认**（零计费不该有摩擦） |
|
|
791
|
-
| `--json` | 有未命中且未给 `--yes` ⇒ **硬拒**（机读模式没有 stdin，不静默提交计费任务） |
|
|
792
|
-
| 逃生舱 | `--no-particles` 零计费出无颗粒版；overlay 视频轨**照常合成**（那部分纯本地） |
|
|
793
|
-
| 拒绝确认 | 零云端调用、零文件写入退出 |
|
|
794
|
-
|
|
795
|
-
`--particle-concurrency <n>`（1–8，默认 6）调颗粒云渲并发。
|
|
796
|
-
|
|
797
|
-
`--json` 结果含 `particles: {total,unique,cached,rendered,billedMinutes,skipped[]}` 与
|
|
798
|
-
`overlay: {layers,particles,hiddenSkipped,missingMaterialSkipped,particleUnavailable}`——
|
|
799
|
-
**跳过了什么都有机读通路**，不会出现「铺了 65 颗、成片一颗没有、退出码 0」。
|
|
800
|
-
|
|
801
|
-
渲完自动质检并落 `.qc.json`（`--no-qc` 跳过）；质检结论只呈现、不改渲染退出语义（硬门控走 `gtrk qc --fail-on`）。
|
|
802
|
-
|
|
803
|
-
### 其它
|
|
804
|
-
|
|
805
|
-
- `gtrk install [--api-key … -y --skill-agents codex,cursor --all-agents --copy-skills --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
|
|
806
|
-
- `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
|
|
807
|
-
- `gtrk doctor` — 体检（含 CLI 版本 / 有无新版）。
|
|
808
|
-
- `gtrk deps status` — 查 ffmpeg/ffprobe 与渲染字体的**当前来源**（`--ffmpeg-path` / `~/.gitruck` / 系统 / 缺失）、版本、授权与源码地址。
|
|
809
|
-
- `gtrk deps install [--ffmpeg] [--font] [--force]` — 从同合云镜像安装运行时资产，**已存在则跳过**。
|
|
810
|
-
- **不会静默自动下载**：任何缺失路径只报错并指向本命令（包体 30–90 MB，且分发物涉及授权，须由用户/agent 显式触发）。
|
|
811
|
-
- 下载一律 https + **sha256 强校验**，校验不过即丢弃、不落地；解包调**系统 tar**（Win10+/macOS/Linux 自带），不引第三方解压依赖。
|
|
812
|
-
- 定位优先级不变：`--ffmpeg-path` → `~/.gitruck/ffmpeg` → 系统 PATH。镜像只填中间那一格，**不越过你自己装的 ffmpeg**。
|
|
813
|
-
- 字体落 `~/.gitruck/fonts`，烧录时经 ffmpeg `ass` 滤镜的 `fontsdir` 供给——**不装进系统字体表、不写注册表、不要管理员权限**。
|
|
814
|
-
- 分发的 ffmpeg 为 GPLv3 构建，对应源码与二进制同处提供（见分发点 `SOURCE.md`）；**下载不附加任何使用限制**。
|
|
815
|
-
- `gtrk upgrade [--check]` — 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装。
|
|
816
|
-
- `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills 目录>]` — 单独安装/刷新 Agent Skills；缺省由通用适配器与 gtrk 补充层自动检测。
|
|
817
|
-
- `gtrk skills recommend [--scene <id>] [--json]` — 第三方 skill 推荐目录：不带 `--scene` 列十个场景（hook / mg-explainer / kinetic-text / data-viz / map / ai-drama / collage / caption / principles / technique），带场景按 tier 给条目（用途 / 安装命令 / 许可与依赖 / 登记命令）。**只推荐不打包**：目录随包分发、带快照日期、不联网不留痕；star 与许可以仓库页为准，装不装是你的选择。GPL / AGPL / 非商用 / 无许可证 / 只能经 MCP-SaaS 运行的不入目录。目录也收同合云一方的 MG 排版技法族（`--scene technique`，条目 `origin: first-party`）：技法不当车道生产者，由 agent 在 MG 步按槽位取用。
|
|
818
|
-
- `gtrk skills add <owner/repo> [--skill <name>]... [--produces MG|AI_DRAMA|FILM_BROLL|script|none] [--column <id>] [--agents ...] [--all] [--copy]` — 透传通用 `skills` 适配器安装第三方 skill，成功后把 `{id, ref: "<owner/repo>#<skill>", produces, status: "third-party"}`（一方条目 `status: "first-party"`）**追加**进栏目配置 `style.skills`（同 ref 幂等、失败不登记；`--produces` 缺省取目录值，目录外仓登记为 `routing:"none"`），之后 `gtrk mg` / `/gtrk-ai-drama` 按 `produces` 即可解析到它。
|
|
819
|
-
|
|
820
|
-
---
|
|
821
|
-
|
|
822
|
-
## 工作原理
|
|
823
|
-
|
|
824
|
-
```
|
|
825
|
-
本地 gtrk CLI 同合云 本地三端
|
|
826
|
-
───────────── ───────────── ─────────────
|
|
827
|
-
毛片 ──上传(指纹缓存免重传)──▶ video_oral_cut 智能剪辑 ──产物──▶ 客户端 gtrk/project.gtrk
|
|
828
|
-
(一次出 gtrk/剪映/xml) 剪映 自动落草稿目录
|
|
829
|
-
源路径写进 gtrk materials.path PR/FCP 导入 premiere.xml
|
|
830
|
-
```
|
|
831
|
-
|
|
832
|
-
- **gtrk** 是 timeline 的真超集 + HTML 颗粒，是同合云的统一工程契约；三端从同一份 gtrk 派生、切点一致。
|
|
833
|
-
- 云端**零改动**全用现成 `video_oral_cut`；CLI 只做编排（上传 / 提交 / 轮询 / 拉回 / 落位 / 打开）。
|
|
834
|
-
|
|
835
|
-
## 注意
|
|
836
|
-
|
|
837
|
-
- 剪映 / CapCut 草稿需 `draft_content.json` + `draft_meta_info.json` **成对**（且必须是这两个**精确文件名**，带前缀的扫不到）才被软件识别——要么 `gtrk init` 配好草稿目录、要么 `--jianying-draft-dir` 指定，否则只产 content、需手动导入。拷进草稿根这一跳由 CLI 统一落成固定名（`long2short` 逐 clip 同），产物目录里保留带 clip 前缀的归档原名。
|
|
838
|
-
- 多台机器盘符不同时，配置走 `~/.gitruck/`（用户级；旧 `~/.gtrk-cli` 首次启动自动迁移），产物默认落毛片同目录。
|
|
839
|
-
- 节奏预设强度以云端为准；`--preset` 只选预设、不改源裁剪。
|
|
840
|
-
|
|
841
|
-
---
|
|
842
|
-
|
|
843
|
-
## 结构
|
|
844
|
-
|
|
845
|
-
```
|
|
846
|
-
gtrk-cli/
|
|
847
|
-
├── src/index.ts # commander 入口
|
|
848
|
-
├── src/commands/ # 子命令：install / init / oralcut / long2short / transcript / split / matrix / mg / project / audio / tool / render / doctor / upgrade / skills / …
|
|
849
|
-
├── src/lib/ # cloud / column-config / splitdoc / projection / user-config / jianying / …
|
|
850
|
-
├── skills/ # 打包的框架 skills（18 个，名单 = src/commands/skills.ts 的 SKILL_NAMES）：oralcut / long2short / splitter / matrix / mg / ai-drama / style-maker / transcript / tools / music-visualizer / cover / travel-recap / live-slicing / talking-head / narration / voiceover / food-recap / vlog-docu
|
|
851
|
-
├── contracts/ # 框架契约库正本（gsap-emit v1 + handoff→契约映射表）
|
|
852
|
-
├── assets/ # README 配图（介绍图 / Agent 调用示例 / 剪映草稿目录指引图）
|
|
853
|
-
└── AGENT.md # 可移植 agent playbook（skill 底座）
|
|
854
|
-
```
|
|
855
|
-
|
|
856
|
-
新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
|
|
75
|
+
gtrk oralcut "./talk.mp4" --script "./script.txt"
|
|
76
|
+
gtrk transcript "./interview.mp4"
|
|
77
|
+
gtrk doctor
|
|
78
|
+
gtrk upgrade
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
音视频处理需要 FFmpeg。用 `gtrk deps status` 检查；缺少时按提示显式运行 `gtrk deps install`。已有配置会保留，需要修改时用 `gtrk init --reconfigure`。
|
|
82
|
+
|
|
83
|
+
[完整配置与命令参考](docs/reference.md)
|
|
84
|
+
|
|
85
|
+
</details>
|
|
86
|
+
|
|
87
|
+
## 看看它能做什么
|
|
88
|
+
|
|
89
|
+
下面选用与[产品专页](https://ai-mcn.tv/gtrk)一致的真实案例。点击封面观看成片，口播示例也可打开原片对比。
|
|
90
|
+
|
|
91
|
+
<table>
|
|
92
|
+
<tr>
|
|
93
|
+
<td width="50%" valign="top">
|
|
94
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/oralcut/webm/fishing_after.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/oralcut/fishing_after.webp" alt="器材测评口播成片" width="100%"></a>
|
|
95
|
+
<strong>口播：从毛片到包装成片</strong><br>
|
|
96
|
+
1:04 → 0:48 · 粗剪、结构图解、器材特写、字幕。<br>
|
|
97
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/oralcut/webm/fishing_before.webm">看原片</a> · <a href="https://api.ai-mcn.tv:9000/cloud/static/assets/oralcut/webm/fishing_after.webm">看成片</a> · <a href="https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe">口播教程</a>
|
|
98
|
+
</td>
|
|
99
|
+
<td width="50%" valign="top">
|
|
100
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/l2s/webm/huangqin_talking_demo_1_16_9.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/l2s/huangqin_talking_demo_1_16_9.webp" alt="双人访谈高光短片" width="100%"></a>
|
|
101
|
+
<strong>长剪短：让好话题单独成片</strong><br>
|
|
102
|
+
26:29 访谈中的 45 秒高光 · 横竖屏分别制作。<br>
|
|
103
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/l2s/webm/huangqin_talking_demo_1_16_9.webm">横屏成片</a> · <a href="https://api.ai-mcn.tv:9000/cloud/static/assets/l2s/webm/huangqin_talking_demo_1_9_16.webm">竖屏成片</a> · <a href="https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb">长剪短教程</a>
|
|
104
|
+
</td>
|
|
105
|
+
</tr>
|
|
106
|
+
<tr>
|
|
107
|
+
<td width="50%" valign="top">
|
|
108
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/travel/webm/3.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/narration/travel_3.webp" alt="黄石国家公园旅拍解说" width="100%"></a>
|
|
109
|
+
<strong>旅拍：把一组素材讲成故事</strong><br>
|
|
110
|
+
黄石国家公园 · 3:05 · 素材理解、解说、配音与画面。<br>
|
|
111
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/travel/webm/3.webm">看成片</a> · <a href="https://hocassian.feishu.cn/wiki/CjDPwyLMcimfjDk1c2NcSv3unCf">旅拍教程</a>
|
|
112
|
+
</td>
|
|
113
|
+
<td width="50%" valign="top">
|
|
114
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/food/webm/1.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/narration/food_1.webp" alt="铁板炒肉定食美食解说" width="100%"></a>
|
|
115
|
+
<strong>美食：一家店，一顿饭，一条片子</strong><br>
|
|
116
|
+
铁板炒肉定食 · 2:36 · 提炼看点、保留现场、重述故事。<br>
|
|
117
|
+
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/food/webm/1.webm">看成片</a> · <a href="https://hocassian.feishu.cn/wiki/EbY3wo6YhiABCjkhczRcpixVniQ">美食教程</a>
|
|
118
|
+
</td>
|
|
119
|
+
</tr>
|
|
120
|
+
</table>
|
|
121
|
+
|
|
122
|
+
[更多题材与前后对照 →](https://ai-mcn.tv/gtrk)
|
|
123
|
+
|
|
124
|
+
## 从你的素材开始
|
|
125
|
+
|
|
126
|
+
不用记命令或 Skill 名字，直接描述想做的事。
|
|
127
|
+
|
|
128
|
+
| 你手上有什么 | 对 Agent 说 | 工作流 |
|
|
129
|
+
| --- | --- | --- |
|
|
130
|
+
| 一条或几条口播，可能还有外录音频 | “把这些口播做成一期，剪掉重录，配上字卡和字幕。” | [口播](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) |
|
|
131
|
+
| 一篇已经写好的稿子 | “用这篇稿子做条配音视频，先给我选音色。” | [配音](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) |
|
|
132
|
+
| 播客、课程、访谈或直播回放 | “挑出值得单发的话题，做成几条短片工程。” | [长剪短](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) |
|
|
133
|
+
| 影视、游戏、旅拍或探店素材 | “看完这些素材，提炼看点，写解说并配画面。” | [通用解说](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre) |
|
|
134
|
+
| 录屏和同时录制的人像 | “把录屏合进来，做成讲师画中画。” | [录屏画中画](https://hocassian.feishu.cn/wiki/GO84wbFqOi9W92kzGzpcc3nQnNh) |
|
|
135
|
+
| 一批现场素材，想保留同期声 | “把这批素材做成纪实 Vlog，保留现场声音，再补旁白。” | [Vlog Skill](skills/gtrk-vlog-docu/SKILL.md) |
|
|
136
|
+
|
|
137
|
+
长剪短保留原声高光；解说会提炼素材并重新讲述。具体流程、交付文件和可选环节见[工作流指南](docs/workflow.md)。
|
|
138
|
+
|
|
139
|
+
## 为什么用 gtrk
|
|
140
|
+
|
|
141
|
+
- **在你熟悉的 Agent 里创作。** 配套 Skills 负责组织步骤，CLI 负责执行；也能直接接入脚本和自动化流程。
|
|
142
|
+
- **工程留在手里。** 画面、音频、字幕和动效写进可编辑工程。你可以在客户端继续调整，并按支持范围导出到剪映、Premiere。
|
|
143
|
+
- **用自己的素材，也能找新画面。** 按文稿检索本地素材库或平台素材，将候选铺到时间线上，逐段挑选。
|
|
144
|
+
- **栏目风格可以复用。** 字体、配色、画面语言和创作规则可通过自己的 Skills 与栏目配置延续到下一期。
|
|
145
|
+
|
|
146
|
+
## 一份工程，贯穿全程
|
|
147
|
+
|
|
148
|
+
```mermaid
|
|
149
|
+
flowchart LR
|
|
150
|
+
A["你在 Agent 里说需求"] --> B["gtrk CLI 执行"]
|
|
151
|
+
B <--> C["同合云分析与处理"]
|
|
152
|
+
B --> D["本地 .gtrk 工程"]
|
|
153
|
+
D <--> E["客户端预览与精修"]
|
|
154
|
+
D --> F["CLI 渲染 MP4"]
|
|
155
|
+
E --> G["导出成片 / 支持的剪辑工程"]
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**当前对话入口在你自己的 Agent 中，客户端没有内置 AI 对话框。** Agent 修改工程后，在客户端查看效果、继续精修；也可以用 `gtrk render` 渲染成片。需要云端渲染的动态图会单独计费，缓存可复用。
|
|
159
|
+
|
|
160
|
+
粗剪阶段的三端工程，与完整包装后的导出支持范围不同；[工作流指南](docs/workflow.md)说明每种交付物在哪打开、哪些效果需要渲染。
|
|
161
|
+
|
|
162
|
+
## gtrk + AI Drama Desk：从分镜到可回轨片段
|
|
163
|
+
|
|
164
|
+
如果你的素材不是实拍，而是希望把一份分镜稿变成 AI 情景片段，可以把 [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) 接到同一条工程链里。两者分工很清楚：
|
|
165
|
+
|
|
166
|
+
| 组件 | 负责什么 | 产物 |
|
|
167
|
+
| --- | --- | --- |
|
|
168
|
+
| `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
|
|
169
|
+
| `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `manifest` |
|
|
170
|
+
| `gtrk ai-drama lay` | 把工作台导出的片段按 beat 区间铺回工程 | 独立 AI 视频轨 |
|
|
171
|
+
|
|
172
|
+
典型路径是：
|
|
173
|
+
|
|
174
|
+
```text
|
|
175
|
+
分镜稿 md → AI Drama Desk → 角色参考图 / keyframe / I2V → return-v1 导出包
|
|
176
|
+
↓
|
|
177
|
+
gtrk ai-drama lay → .gtrk 工程 → 客户端精修
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
工作台支持 mock、云端出口和可选的本地 ComfyUI；你可以先零 GPU、零 Key 跑通流程，再按需要启用真实引擎。已有工作台项目时，CLI 只需要 **API 地址 + 项目 ID**，不需要扫描仓库目录：
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
gtrk ai-drama lay --project ./my-video --desk-project <project-id>
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
→ [AI Drama Desk README](https://github.com/Gitruck/ai-drama-desk) · [AI 漫剧教程](https://hocassian.feishu.cn/wiki/FRAKwUvBWib2vrkqZ5XcLDRqnOe) · [命令参考](docs/reference.md#命令参考)
|
|
187
|
+
|
|
188
|
+
## 成片之外，也能只做一件事
|
|
189
|
+
|
|
190
|
+
| 想做什么 | 从这里开始 |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| 抠像、降噪、人声分离、超分、补帧、图片运镜、视频译制 | [单点工具箱](https://hocassian.feishu.cn/wiki/Uh19wAphailtSqkt6jsclW0Rnie) · `gtrk tool list` |
|
|
193
|
+
| 做一套多尺寸封面 | [封面工作流](https://hocassian.feishu.cn/wiki/AD5bwUAHris75vkWl4DcsvPJntb) |
|
|
194
|
+
| 把一首歌做成频谱视频 | [音乐可视化 Skill](skills/gtrk-music-visualizer/SKILL.md) |
|
|
195
|
+
| 给自己的栏目建立视觉风格 | [风格体系 Skill](skills/gtrk-style-maker/SKILL.md) |
|
|
196
|
+
| 接入第三方动画、排版或创作 Skills | [Skill 地图](https://hocassian.feishu.cn/wiki/SxRtwJ0G7inTbQkwckFcZmClnrd) |
|
|
197
|
+
|
|
198
|
+
## 常见问题
|
|
199
|
+
|
|
200
|
+
**需要会写代码吗？**
|
|
201
|
+
|
|
202
|
+
不需要。日常使用可以直接对 Agent 描述需求。安装、配置或费用需要你提供信息时，Agent 会引导你完成。
|
|
203
|
+
|
|
204
|
+
**开源等于所有服务免费吗？**
|
|
205
|
+
|
|
206
|
+
CLI 代码采用 MIT 许可证；同合云能力按对应规则计费，你使用的 Agent 和第三方生成服务也可能单独收费。价格与额度以[控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)和[计费说明](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd)为准。
|
|
207
|
+
|
|
208
|
+
**原始视频会被上传吗？**
|
|
209
|
+
|
|
210
|
+
口播粗剪和长剪短工程流程保留本地原片，默认上传提取的音频；开启视觉辅助或智能分屏时上传压缩代理视频。云端直接处理或渲染的工具可能需要上传视频，按具体工具说明执行。
|
|
211
|
+
|
|
212
|
+
**一定要用 Windows 客户端吗？**
|
|
213
|
+
|
|
214
|
+
CLI 可以跨平台执行。Windows 客户端用于可视化预览与精修；已有工程也可通过 CLI 渲染。剪映、Premiere 的使用取决于对应软件和工程格式的支持情况。
|
|
215
|
+
|
|
216
|
+
**安装后找不到 Skills，或任务出错怎么办？**
|
|
217
|
+
|
|
218
|
+
重新打开 Agent 会话，运行 `gtrk doctor` 检查环境；补装用 `gtrk skills install`。任务已有 ID 时优先恢复结果，避免重新提交云端任务。详见[工作流与排障](docs/workflow.md)。
|
|
219
|
+
|
|
220
|
+
## Star History
|
|
221
|
+
|
|
222
|
+
<a href="https://star-history.com/#Gitruck/cli&Date">
|
|
223
|
+
<picture>
|
|
224
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date&theme=dark" />
|
|
225
|
+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
|
|
226
|
+
<img alt="gtrk CLI Star History" src="https://api.star-history.com/svg?repos=Gitruck/cli&type=Date" />
|
|
227
|
+
</picture>
|
|
228
|
+
</a>
|
|
229
|
+
|
|
230
|
+
## 文档与参与
|
|
231
|
+
|
|
232
|
+
[完整教程](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [工作流](docs/workflow.md) · [命令参考](docs/reference.md) · [开发文档](docs/development.md) · [更新日志](CHANGELOG.md)
|
|
233
|
+
|
|
234
|
+
欢迎通过 [Issues](https://github.com/Gitruck/cli/issues)反馈问题和提出建议，或提交文档、示例与代码改进。商务联系：[business@gitruck.com](mailto:business@gitruck.com)。
|
|
235
|
+
|
|
236
|
+
[MIT 许可证](LICENSE) · [用户协议](https://hocassian.feishu.cn/wiki/T6UywR8b3ik4Mgk7tP9c1b7Kn0b) · [隐私政策](https://hocassian.feishu.cn/wiki/ZLRNwlEhfishYtkosUhcofMYnPf)
|
|
237
|
+
|
|
238
|
+
<p align="center">如果 gtrk 帮你省下了剪辑时间，欢迎点个 Star，让更多创作者找到它。</p>
|