@gitruck/cli 1.3.16 → 1.3.17
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 +40 -10
- package/CHANGELOG.md +1262 -1231
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/assets/composite-kit/kit.css +66 -57
- package/assets/composite-kit/stage.html +164 -18
- package/dist/index.js +653 -343
- package/docs/reference.en.md +866 -852
- package/docs/reference.md +909 -895
- package/docs/workflow.en.md +4 -3
- package/docs/workflow.md +4 -3
- package/package.json +1 -1
- package/skills/gtrk-ai-drama/SKILL.md +7 -7
- package/skills/gtrk-composite/SKILL.md +428 -222
- package/skills/gtrk-composite/references/fullscreen-card-migration.md +99 -0
- package/skills/gtrk-food-recap/SKILL.md +6 -3
- package/skills/gtrk-live-slicing/SKILL.md +9 -6
- package/skills/gtrk-long2short/SKILL.md +3 -2
- package/skills/gtrk-matrix/SKILL.md +9 -9
- package/skills/gtrk-mg/SKILL.md +62 -48
- package/skills/gtrk-music-visualizer/SKILL.md +1 -1
- package/skills/gtrk-narration/SKILL.md +15 -8
- package/skills/gtrk-oralcut/SKILL.md +1 -1
- package/skills/gtrk-splitter/SKILL.md +116 -24
- package/skills/gtrk-splitter/references/example-visual-split.json +34 -13
- package/skills/gtrk-splitter/references/example-visual-split.md +28 -5
- package/skills/gtrk-splitter/references/field-schema.md +88 -3
- package/skills/gtrk-style-maker/SKILL.md +8 -4
- package/skills/gtrk-style-maker/references/seeds/seed-ecom-home-goods.md +2 -2
- package/skills/gtrk-style-maker/references/seeds/seed-psych-humanities.md +1 -1
- package/skills/gtrk-talking-head/SKILL.md +26 -20
- package/skills/gtrk-tools/SKILL.md +1 -1
- package/skills/gtrk-transcript/SKILL.md +1 -1
- package/skills/gtrk-travel-recap/SKILL.md +36 -28
- package/skills/gtrk-vlog-docu/SKILL.md +41 -33
- package/skills/gtrk-voiceover/SKILL.md +19 -11
package/docs/reference.md
CHANGED
|
@@ -1,895 +1,909 @@
|
|
|
1
|
-
# Agent、配置与命令参考
|
|
2
|
-
|
|
3
|
-
`project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080` 在本地组装分段工程，不上传原片、不自动合成声音。清单示例：
|
|
4
|
-
|
|
5
|
-
```json
|
|
6
|
-
{"version":1,"segments":[{"kind":"live","source":"原片.mp4","in":3,"out":11},{"kind":"narration","source":"旁白.wav","transcript":"旁白.json"},{"kind":"image","source":"照片.jpg","duration":4}]}
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
路径相对清单；视频默认保留独立同期声，`keep_audio:false` 关闭；旁白段留同长画面空档。图片段为静帧，运镜先经 `tool image_move` 产视频。文稿用源时基 `utterances:[{st,ed,text}]`；合并文稿逐句绑定素材，供 `split`、`subtitle lay` 随剪辑重投影，切点截断的整句会省略并报告。输出目录必须不存在，已有工程精修走 `patch`，避免覆盖。
|
|
10
|
-
|
|
11
|
-
`matrix describe` 的本地视觉交接：`--prepare <工程内目录>` 生成带时码、源指纹与图片哈希的审阅任务，零豆包调用；当前 Agent 看图填写回执后，以相同 `--materials` 或 `--plan` 参数加 `--review <visual-review.json>` 导入。仅明确标记无法完成并给出原因的条目回退豆包；缺答、素材变化或准则不一致会报错，不自动上云。这个接力由 Agent 完成，不要求用户填表。纯本地完成时无需 API Key，回退豆包时需要云端配置。
|
|
12
|
-
|
|
13
|
-
视频素材概览按场景最多六秒间距覆盖；`describe --materials <视频> --source-window <起秒,止秒>` 在指定窗内按最多两秒间距细查，可与 prepare/review 组合。图片没有源时间窗。`--plan` 保持每候选 best 帧口径，单帧描述不证明整段动作。索引的 stable 长场景同样按六秒单元抽帧，普通长场景仍每两秒；下次显式 index 会更新欠覆盖的旧 stable 素材，并报告新增处理。
|
|
14
|
-
|
|
15
|
-
[返回首页](../README.md) · [工作流](workflow.md) · [English](reference.en.md)
|
|
16
|
-
|
|
17
|
-
## 给 AI Agent 用
|
|
18
|
-
|
|
19
|
-
装好后，在各家 Agent 里一句话就能调用 gtrk 的 skill：
|
|
20
|
-
|
|
21
|
-
| | |
|
|
22
|
-
|:--:|:--:|
|
|
23
|
-
|  |  |
|
|
24
|
-
|  |  |
|
|
25
|
-
|
|
26
|
-
`gtrk install` 会把 20 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-composite`·`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`·`gtrk-ref-reading`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
|
|
27
|
-
|
|
28
|
-
默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
# 自动探测已安装的 Agent（等价核心：npx -y skills add <gtrk包根>/skills -g -y）
|
|
32
|
-
gtrk skills install
|
|
33
|
-
|
|
34
|
-
# 只装指定宿主；这里使用通用 skills CLI 的 Agent ID
|
|
35
|
-
gtrk skills install --agents codex,cursor,gemini-cli,trae-cn
|
|
36
|
-
|
|
37
|
-
# 安装到适配器当前支持的全部 Agent（会创建较多宿主目录）
|
|
38
|
-
gtrk skills install --all
|
|
39
|
-
|
|
40
|
-
# 不使用链接，每个宿主各复制一份
|
|
41
|
-
gtrk skills install --copy
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
> ⚠️ **升级 CLI 不会自动刷新已装的 skill。** `npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，
|
|
45
|
-
> 各 Agent 目录下那份 skill 仍是**上次装进去的快照** —— agent 会照着旧口径干活，**而且不报错**。
|
|
46
|
-
> 刷新走 `gtrk upgrade`（升 CLI + 刷 skill）或单独跑 `gtrk skills install`。
|
|
47
|
-
>
|
|
48
|
-
> 自 **1.1.3** 起这件事有信号了：需要 skill 的命令（`oralcut` / `long2short` / `split` / `matrix` /
|
|
49
|
-
> `mg` / `subtitle` / `project`）在检测到本机 skill 落后时，会往 **stderr** 提示一次并给出修复命令；
|
|
50
|
-
> 一致或判不出时**零输出**。随时自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」；
|
|
51
|
-
> 嫌吵用环境变量 `GTRK_SKILL_FRESHNESS=off` 整块关掉。
|
|
52
|
-
|
|
53
|
-
`--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目录>` 走兼容复制模式。
|
|
54
|
-
|
|
55
|
-
不同 Agent 的**输入 UI 不统一**：Claude 常把 skill 名放进 `/` 补全；Codex 的不同客户端可从 `$`、`/skills` 或 Skills 面板进入；TRAE 以 Skills 设置、显式点名或语义触发为主。因此没看到 Claude 风格的 `/gtrk-*` 下拉，不代表 skill 没安装。新 skill 没出现时，刷新窗口或新开会话。
|
|
56
|
-
|
|
57
|
-
然后直接说「**帮我把这条口播剪一版**」，或在对应 Agent 的 Skills 入口显式选择 `gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](../AGENT.md)。
|
|
58
|
-
|
|
59
|
-
**一条龙都交给 agent**：不止剪口播——接着说「拆个分镜」「铺 B-roll」「铺 MG 颗粒」「渲成片」，agent 会配合各车道生产 skill 调 `gtrk split` / `gtrk matrix` / `gtrk mg` / `gtrk render` 跑完整条 **成片管线**。**你只管对话、敲 CLI 的活交给 agent**——下面的「命令参考」是给 agent 查参数用的，不用你自己去终端敲。
|
|
60
|
-
|
|
61
|
-
### agent 能驱动的能力（skill 驱动命令）
|
|
62
|
-
|
|
63
|
-
**每个功能 = 一个 skill（脑，你触发、懂 SOP 位置与用户交互）驱动一个 gtrk 命令（手，确定性机械活）。** 成片是**有先后的 SOP、每步用户可介入**，不是一次性并行铺完——`/gtrk-X` skill 负责在对的时机、带着你的确认，去跑 `gtrk X`：
|
|
64
|
-
|
|
65
|
-
| SOP | 驱动 skill（你对 agent 说） | 底层命令（agent 跑） | 做什么 |
|
|
66
|
-
|:--:|---|---|---|
|
|
67
|
-
| ① | `/gtrk-oralcut` | `gtrk oralcut` | 智能剪口播 → 客户端/剪映/PR 三方工程 + transcript |
|
|
68
|
-
| ② | `/gtrk-splitter` | `gtrk split` | 拆分派单 → `dispatch.json`（A_ROLL/MG/AI_DRAMA/FILM_BROLL
|
|
69
|
-
| ③ | `/gtrk-matrix` | `gtrk matrix` | **B-roll 底轨·影视/本地素材腿**：铺候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
|
|
70
|
-
| ③ | `/gtrk-ai-drama` | `gtrk ai-drama validate`（校验分镜稿）· `lay` / `pack` / `swap`（回填） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
|
|
71
|
-
| ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent
|
|
72
|
-
| ⑤ |
|
|
73
|
-
| ⑥ | `/gtrk-composite` | `gtrk composite` |
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
| 🧭 | `/gtrk-
|
|
85
|
-
| 🧭 | `/gtrk-
|
|
86
|
-
| 🧭 | `/gtrk-
|
|
87
|
-
| 🧭 | `/gtrk-
|
|
88
|
-
| 🧭 | `/gtrk-
|
|
89
|
-
| 🧭 | `/gtrk-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
>
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
| `
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
✅
|
|
143
|
-
✅
|
|
144
|
-
✅
|
|
145
|
-
✅
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
- `gtrk
|
|
227
|
-
- `gtrk
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
|
235
|
-
|
|
|
236
|
-
| `--
|
|
237
|
-
| `--
|
|
238
|
-
| `--online-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
gtrk transcript "D:/素材/采访视频.mp4"
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
272
|
-
| `
|
|
273
|
-
| `
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
gtrk media tiles "参考片.mp4" --
|
|
278
|
-
gtrk media
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
-
|
|
283
|
-
-
|
|
284
|
-
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
gtrk client
|
|
299
|
-
gtrk client
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
- `
|
|
306
|
-
-
|
|
307
|
-
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
| `-
|
|
315
|
-
| `-
|
|
316
|
-
| `-
|
|
317
|
-
|
|
|
318
|
-
| `--
|
|
319
|
-
| `--
|
|
320
|
-
| `--
|
|
321
|
-
| `--
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
|
337
|
-
| `--
|
|
338
|
-
| `--
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
| `--
|
|
350
|
-
| `--
|
|
351
|
-
| `--
|
|
352
|
-
| `--
|
|
353
|
-
| `--
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
>
|
|
357
|
-
>
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
gtrk patch
|
|
372
|
-
gtrk patch
|
|
373
|
-
gtrk patch
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
|
382
|
-
|
|
383
|
-
| `--
|
|
384
|
-
| `--
|
|
385
|
-
| `--
|
|
386
|
-
|
|
|
387
|
-
| `--
|
|
388
|
-
| `--
|
|
389
|
-
| `--
|
|
390
|
-
| `--
|
|
391
|
-
| `--
|
|
392
|
-
| `--
|
|
393
|
-
| `--
|
|
394
|
-
| `--
|
|
395
|
-
| `--
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
>
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
gtrk matrix source-import
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
gtrk matrix status
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
|
453
|
-
|
|
454
|
-
| `
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
|
468
|
-
|
|
469
|
-
| `--
|
|
470
|
-
| `--
|
|
471
|
-
| `--
|
|
472
|
-
| `--
|
|
473
|
-
| `--
|
|
474
|
-
| `--
|
|
475
|
-
| `--
|
|
476
|
-
| `--
|
|
477
|
-
| `--
|
|
478
|
-
| `--
|
|
479
|
-
| `--
|
|
480
|
-
| `--
|
|
481
|
-
| `--
|
|
482
|
-
| `--
|
|
483
|
-
| `--
|
|
484
|
-
| `--
|
|
485
|
-
| `--
|
|
486
|
-
| `--
|
|
487
|
-
| `--
|
|
488
|
-
| `--
|
|
489
|
-
| `--
|
|
490
|
-
| `--
|
|
491
|
-
| `--
|
|
492
|
-
| `--
|
|
493
|
-
| `--
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
>
|
|
503
|
-
>
|
|
504
|
-
>
|
|
505
|
-
>
|
|
506
|
-
>
|
|
507
|
-
>
|
|
508
|
-
>
|
|
509
|
-
>
|
|
510
|
-
>
|
|
511
|
-
>
|
|
512
|
-
>
|
|
513
|
-
>
|
|
514
|
-
>
|
|
515
|
-
>
|
|
516
|
-
>
|
|
517
|
-
>
|
|
518
|
-
>
|
|
519
|
-
>
|
|
520
|
-
>
|
|
521
|
-
>
|
|
522
|
-
>
|
|
523
|
-
>
|
|
524
|
-
>
|
|
525
|
-
>
|
|
526
|
-
>
|
|
527
|
-
>
|
|
528
|
-
>
|
|
529
|
-
>
|
|
530
|
-
>
|
|
531
|
-
>
|
|
532
|
-
>
|
|
533
|
-
>
|
|
534
|
-
>
|
|
535
|
-
>
|
|
536
|
-
>
|
|
537
|
-
>
|
|
538
|
-
>
|
|
539
|
-
>
|
|
540
|
-
>
|
|
541
|
-
>
|
|
542
|
-
>
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
-
|
|
558
|
-
-
|
|
559
|
-
-
|
|
560
|
-
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
>
|
|
570
|
-
>
|
|
571
|
-
>
|
|
572
|
-
>
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
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
|
-
gtrk composite status
|
|
627
|
-
|
|
628
|
-
gtrk
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
gtrk composite
|
|
632
|
-
gtrk composite
|
|
633
|
-
gtrk composite
|
|
634
|
-
gtrk composite
|
|
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
|
-
`project init`
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
gtrk project
|
|
676
|
-
gtrk project
|
|
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
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
|
746
|
-
|
|
747
|
-
| `
|
|
748
|
-
| `
|
|
749
|
-
| `
|
|
750
|
-
| `
|
|
751
|
-
| `
|
|
752
|
-
| `
|
|
753
|
-
| `
|
|
754
|
-
| `
|
|
755
|
-
| `
|
|
756
|
-
| `
|
|
757
|
-
| `
|
|
758
|
-
| `
|
|
759
|
-
| `
|
|
760
|
-
| `
|
|
761
|
-
| `
|
|
762
|
-
| `
|
|
763
|
-
| `
|
|
764
|
-
| `
|
|
765
|
-
| `
|
|
766
|
-
| `
|
|
767
|
-
| `
|
|
768
|
-
| `
|
|
769
|
-
| `
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
- `gtrk tool
|
|
791
|
-
- `gtrk
|
|
792
|
-
- `gtrk
|
|
793
|
-
- `gtrk
|
|
794
|
-
|
|
795
|
-
- `gtrk
|
|
796
|
-
- `gtrk
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
- `gtrk tool
|
|
801
|
-
- `gtrk tool
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
- `gtrk tool
|
|
805
|
-
- `gtrk
|
|
806
|
-
- `gtrk
|
|
807
|
-
- `gtrk
|
|
808
|
-
-
|
|
809
|
-
- `gtrk
|
|
810
|
-
- `gtrk
|
|
811
|
-
|
|
812
|
-
- `
|
|
813
|
-
|
|
814
|
-
- `gtrk tool
|
|
815
|
-
- `gtrk tool
|
|
816
|
-
- `gtrk tool
|
|
817
|
-
- `gtrk tool
|
|
818
|
-
- `gtrk tool
|
|
819
|
-
- `gtrk tool
|
|
820
|
-
- `gtrk tool
|
|
821
|
-
- `gtrk tool
|
|
822
|
-
- `
|
|
823
|
-
- `gtrk tool
|
|
824
|
-
- `gtrk tool
|
|
825
|
-
- `gtrk tool
|
|
826
|
-
- `gtrk tool
|
|
827
|
-
- `gtrk tool
|
|
828
|
-
- `gtrk tool
|
|
829
|
-
- `gtrk tool
|
|
830
|
-
-
|
|
831
|
-
-
|
|
832
|
-
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
- `gtrk
|
|
890
|
-
- `gtrk
|
|
891
|
-
- `gtrk
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
`gtrk
|
|
1
|
+
# Agent、配置与命令参考
|
|
2
|
+
|
|
3
|
+
`project compose --list <分段清单.json> --out <新工程目录> --canvas 1920x1080` 在本地组装分段工程，不上传原片、不自动合成声音。清单示例：
|
|
4
|
+
|
|
5
|
+
```json
|
|
6
|
+
{"version":1,"segments":[{"kind":"live","source":"原片.mp4","in":3,"out":11},{"kind":"narration","source":"旁白.wav","transcript":"旁白.json"},{"kind":"image","source":"照片.jpg","duration":4}]}
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
路径相对清单；视频默认保留独立同期声，`keep_audio:false` 关闭；旁白段留同长画面空档。图片段为静帧，运镜先经 `tool image_move` 产视频。文稿用源时基 `utterances:[{st,ed,text}]`；合并文稿逐句绑定素材，供 `split`、`subtitle lay` 随剪辑重投影，切点截断的整句会省略并报告。输出目录必须不存在，已有工程精修走 `patch`，避免覆盖。
|
|
10
|
+
|
|
11
|
+
`matrix describe` 的本地视觉交接：`--prepare <工程内目录>` 生成带时码、源指纹与图片哈希的审阅任务，零豆包调用；当前 Agent 看图填写回执后，以相同 `--materials` 或 `--plan` 参数加 `--review <visual-review.json>` 导入。仅明确标记无法完成并给出原因的条目回退豆包；缺答、素材变化或准则不一致会报错，不自动上云。这个接力由 Agent 完成，不要求用户填表。纯本地完成时无需 API Key，回退豆包时需要云端配置。
|
|
12
|
+
|
|
13
|
+
视频素材概览按场景最多六秒间距覆盖；`describe --materials <视频> --source-window <起秒,止秒>` 在指定窗内按最多两秒间距细查，可与 prepare/review 组合。图片没有源时间窗。`--plan` 保持每候选 best 帧口径，单帧描述不证明整段动作。索引的 stable 长场景同样按六秒单元抽帧，普通长场景仍每两秒；下次显式 index 会更新欠覆盖的旧 stable 素材，并报告新增处理。
|
|
14
|
+
|
|
15
|
+
[返回首页](../README.md) · [工作流](workflow.md) · [English](reference.en.md)
|
|
16
|
+
|
|
17
|
+
## 给 AI Agent 用
|
|
18
|
+
|
|
19
|
+
装好后，在各家 Agent 里一句话就能调用 gtrk 的 skill：
|
|
20
|
+
|
|
21
|
+
| | |
|
|
22
|
+
|:--:|:--:|
|
|
23
|
+
|  |  |
|
|
24
|
+
|  |  |
|
|
25
|
+
|
|
26
|
+
`gtrk install` 会把 20 个 CLI 自带 skill（`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-composite`·`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`·`gtrk-ref-reading`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
|
|
27
|
+
|
|
28
|
+
默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# 自动探测已安装的 Agent（等价核心：npx -y skills add <gtrk包根>/skills -g -y）
|
|
32
|
+
gtrk skills install
|
|
33
|
+
|
|
34
|
+
# 只装指定宿主；这里使用通用 skills CLI 的 Agent ID
|
|
35
|
+
gtrk skills install --agents codex,cursor,gemini-cli,trae-cn
|
|
36
|
+
|
|
37
|
+
# 安装到适配器当前支持的全部 Agent（会创建较多宿主目录）
|
|
38
|
+
gtrk skills install --all
|
|
39
|
+
|
|
40
|
+
# 不使用链接，每个宿主各复制一份
|
|
41
|
+
gtrk skills install --copy
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
> ⚠️ **升级 CLI 不会自动刷新已装的 skill。** `npm i -g @gitruck/cli@latest` 只换掉 CLI 包本体，
|
|
45
|
+
> 各 Agent 目录下那份 skill 仍是**上次装进去的快照** —— agent 会照着旧口径干活，**而且不报错**。
|
|
46
|
+
> 刷新走 `gtrk upgrade`（升 CLI + 刷 skill）或单独跑 `gtrk skills install`。
|
|
47
|
+
>
|
|
48
|
+
> 自 **1.1.3** 起这件事有信号了：需要 skill 的命令（`oralcut` / `long2short` / `split` / `matrix` /
|
|
49
|
+
> `mg` / `subtitle` / `project`）在检测到本机 skill 落后时，会往 **stderr** 提示一次并给出修复命令；
|
|
50
|
+
> 一致或判不出时**零输出**。随时自查跑 `gtrk doctor`，里面有一行「Skill 新鲜度」；
|
|
51
|
+
> 嫌吵用环境变量 `GTRK_SKILL_FRESHNESS=off` 整块关掉。
|
|
52
|
+
|
|
53
|
+
`--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目录>` 走兼容复制模式。
|
|
54
|
+
|
|
55
|
+
不同 Agent 的**输入 UI 不统一**：Claude 常把 skill 名放进 `/` 补全；Codex 的不同客户端可从 `$`、`/skills` 或 Skills 面板进入；TRAE 以 Skills 设置、显式点名或语义触发为主。因此没看到 Claude 风格的 `/gtrk-*` 下拉，不代表 skill 没安装。新 skill 没出现时，刷新窗口或新开会话。
|
|
56
|
+
|
|
57
|
+
然后直接说「**帮我把这条口播剪一版**」，或在对应 Agent 的 Skills 入口显式选择 `gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](../AGENT.md)。
|
|
58
|
+
|
|
59
|
+
**一条龙都交给 agent**：不止剪口播——接着说「拆个分镜」「铺 B-roll」「铺 MG 颗粒」「渲成片」，agent 会配合各车道生产 skill 调 `gtrk split` / `gtrk matrix` / `gtrk mg` / `gtrk render` 跑完整条 **成片管线**。**你只管对话、敲 CLI 的活交给 agent**——下面的「命令参考」是给 agent 查参数用的，不用你自己去终端敲。
|
|
60
|
+
|
|
61
|
+
### agent 能驱动的能力（skill 驱动命令）
|
|
62
|
+
|
|
63
|
+
**每个功能 = 一个 skill（脑，你触发、懂 SOP 位置与用户交互）驱动一个 gtrk 命令（手，确定性机械活）。** 成片是**有先后的 SOP、每步用户可介入**，不是一次性并行铺完——`/gtrk-X` skill 负责在对的时机、带着你的确认，去跑 `gtrk X`：
|
|
64
|
+
|
|
65
|
+
| SOP | 驱动 skill（你对 agent 说） | 底层命令（agent 跑） | 做什么 |
|
|
66
|
+
|:--:|---|---|---|
|
|
67
|
+
| ① | `/gtrk-oralcut` | `gtrk oralcut` | 智能剪口播 → 客户端/剪映/PR 三方工程 + transcript |
|
|
68
|
+
| ② | `/gtrk-splitter` | `gtrk split` | 拆分派单 → `dispatch.json`（A_ROLL/MG/AI_DRAMA/FILM_BROLL 四车道 + 交给合成的版式窗口 `layouts`） |
|
|
69
|
+
| ③ | `/gtrk-matrix` | `gtrk matrix` | **B-roll 底轨·影视/本地素材腿**：铺候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
|
|
70
|
+
| ③ | `/gtrk-ai-drama` | `gtrk ai-drama validate`（校验分镜稿）· `lay` / `pack` / `swap`（回填） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
|
|
71
|
+
| ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent 纪律硬门，供合成选片与叠层避让使用 |
|
|
72
|
+
| ⑤ | （无 skill） | `gtrk subtitle lay` | **字幕**：样式取开工 / 检查点拍板值；合成要读字幕输入，所以排在合成之前 |
|
|
73
|
+
| ⑥ | `/gtrk-composite` | `gtrk composite` | **合成层（版）**（字幕之后、`gtrk mg` 之前）：把选定时间窗做成合成颗粒——一段时间内的整个画面由一颗代码颗粒接管（逐句换画面、对照并排、并列卡片、字幕排版），讲者、B-roll 与图片作为槽位画进去；入口四选一（取拆分稿的版式窗口 / 整片铺满 / AI 判定 / 指定区间），候选显示在客户端大纲 CP 行；纯本地零计费。出片时由 `gtrk composite bake` 在本机烘焙成视频（首次需 `gtrk deps install --browser`） |
|
|
74
|
+
| ⑦ | `/gtrk-mg` | `gtrk mg` | **叠层**（合成之后；整段落在合成窗口里的叠层槽位被合成接管，不产不铺；满屏卡已并入合成，旧派单里的满屏槽位照旧做） |
|
|
75
|
+
| — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
|
|
76
|
+
| 🔍 | `/gtrk-ref-reading` | `gtrk transcript` + `gtrk media` | **参考片精读**：别人的一条视频 → 字级转写 + 带台词标签的网格 + 关键动效逐帧 → 按「系统」记每个设计事件对着哪句话，落成 `ANALYSIS.md` / `TIMELINE.md` / `PROGRESS.md`；读完可交 `/gtrk-style-maker` 建栏目。看片命令纯本地零计费（只有转写一步计费），**不在成片 SOP 序列内** |
|
|
77
|
+
| ③′ | 「**屏录画中画**」 | `gtrk pip lay` | 把口播粗剪的切点镜像到同步录的屏录 / 第二机位，铺屏录满幅轨 + 人像画中画副本轨（圆 / 圆角方 / 爱心 / 菱形 / 星形蒙版，可圆角）；纯本地零计费；低置信时产对齐工程让客户端拖齐后 `--resume` |
|
|
78
|
+
| — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4（含 overlay 与 MG 颗粒；颗粒未命中缓存时云渲计费，`--no-particles` 可跳过） |
|
|
79
|
+
| ✂️ | `/gtrk-long2short` | `gtrk long2short` | 长剪短·粗剪：长视频语义选段+跳剪 → 逐 clip 出客户端/剪映/PR 三方工程（毛片不上传），**不在成片 SOP 序列内**、随时可独立用 |
|
|
80
|
+
| 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频/配音音频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |
|
|
81
|
+
| 🧰 | `/gtrk-tools` | `gtrk tool <name>` | 单点工具族（图转运镜 / 图片·视频抠像…）——单发单收，**不在成片 SOP 序列内**、随时可独立用 |
|
|
82
|
+
| 🎵 | `/gtrk-music-visualizer` | `gtrk music-visualizer` | 一首歌 → 频谱可视化成片（模板 + 可选背景/封面 + 配色样式），**不在成片 SOP 序列内**、独立引流用 |
|
|
83
|
+
| 🖼️ | `/gtrk-cover` | `gtrk cover embed`（背景图压缩嵌进工作台，纯本地零计费） | 封面工作台两阶段：设计诊断 + 三尺寸中英双版文生图 Prompt → 用户外部平台抽图 → H5 排字工作台（拖拽/滚轮微调、一键导出多尺寸 PNG）。栏目封面审美经栏目配置 `style.skills`（`produces:"cover"`）注入；**不在成片 SOP 序列内**（投放配套的「第 0 阶段」） |
|
|
84
|
+
| 🧭 | `/gtrk-talking-head` | 编排 `gtrk audio` → `oralcut` → `split` → `matrix` → `subtitle lay` → `composite` → `mg` → `audio lay` | **口播链图纸**：一条或一组真人出镜毛片 → 外录音轨对齐换轨、多段拼接、粗剪、拆分派单、B-roll/MG 字卡、BGM、字幕 → 客户端可出片工程 |
|
|
85
|
+
| 🧭 | `/gtrk-travel-recap` | 编排 `gtrk tool audio_tts_clone` → `project init` → `split` → `matrix` → `subtitle lay` → `composite` → `mg` → `audio lay` | **旅拍解说图纸**：旅拍素材夹 → AI 理解素材、写三段式解说稿、一次确认 → 配音/建工程/拆分/B-roll/字卡/BGM/字幕全自动跑完 → 客户端可出片工程 |
|
|
86
|
+
| 🧭 | `/gtrk-live-slicing` | 编排 `gtrk long2short`（超长回放先分段） | **直播切片图纸**：数小时直播回放 → 分段（服务端 2h 硬闸）→ 选题清单确认 → 一批逐 clip 粗剪工程（gtrk + 剪映 + PR），按画面形态配分屏 |
|
|
87
|
+
| 🧭 | `/gtrk-narration` | 编排 `gtrk transcript` → `project init` → `split` → `matrix` → `subtitle lay` → `composite` → `mg` → `audio lay` | **通用解说图纸（解说链正本）**：素材自带时序的长东西（影视长片/游戏实况/探店记录…）→ 提炼梗概与看点 → 精简叙述重讲成解说成片工程；旅拍解说与美食解说是它的垂类实例 |
|
|
88
|
+
| 🧭 | `/gtrk-voiceover` | 编排 `gtrk tool audio_tts_clone` → `project init` → `split` → `matrix` → `subtitle lay` → `composite` → `mg` → `audio lay` | **配音链快速成片预设**：写好的稿（或 AI 代写）→ 配音 → 自动配画面 → 字卡/BGM/字幕 → 客户端可出片工程；适用科普/情感电台/观点/带货/盘点等无自带时序的题材 |
|
|
89
|
+
| 🧭 | `/gtrk-food-recap` | 沿 `/gtrk-narration` 链路 | **美食解说垂类图纸（解说链示例）**：探店/密着纪实长片或做饭流程记录 → 提炼看点重述成中文美食解说成片工程 |
|
|
90
|
+
| 🧭 | `/gtrk-vlog-docu` | 编排 `gtrk transcript` → `tool audio_tts_clone` → `split` → `matrix` → `subtitle lay` → `composite` → `mg` → `audio lay` | **Vlog 纪实图纸**：一批现场素材 → 素材理解、选档写稿、一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端可出片工程；「现场同期声 × 后期旁白」双声道交替，区别于纯口播链与纯配音链 |
|
|
91
|
+
|
|
92
|
+
> **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑦ 步（B-roll 三源全齐、构图核过、字幕与合成落位之后才铺 MG，被合成接管的槽位不产）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
|
|
93
|
+
> 上面 20 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，`/gtrk-ref-reading` 管参考片精读，五者都不属成片 SOP 序列；`/gtrk-style-maker` 是纯创作 skill（无命令），`/gtrk-ai-drama`·`/gtrk-cover` 以创作为主、只有校验 / 嵌图这类机械段走命令。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
|
|
94
|
+
|
|
95
|
+
**各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 栏目与风格：两层结构
|
|
100
|
+
|
|
101
|
+
> **栏目配置是装修厨房，成片是每天做菜。你不会每做一道菜先重新装修一遍厨房，但每道菜确实都在你装修好的厨房里做。**
|
|
102
|
+
|
|
103
|
+
整个体系分两层，时间尺度完全不同：
|
|
104
|
+
|
|
105
|
+
**【栏目层 · 一次性/低频】= 建栏目（装修厨房）**
|
|
106
|
+
跑 `/gtrk-style-maker`（meta skill），它通过启发式访谈帮你想清楚**你自己的**视觉语法——不预设任何维度：不假设你有叙事结构、有主题系统、视觉分动画/实拍，你的维度和取值全部由你自己定义。产出：
|
|
107
|
+
|
|
108
|
+
- 你自己的可执行 skill 家族（落到当前 Agent 的用户级 skills 目录，黑盒、留本地）
|
|
109
|
+
- 栏目内共享词表（家族各 skill 引用，防多处定义漂移）
|
|
110
|
+
- 栏目配置 `~/.gitruck/columns/<id>.json`（词表 vocab + B-roll 检索偏好 + style 引用清单）
|
|
111
|
+
|
|
112
|
+
**【成片层 · 每片跑】= 做菜（流程形状不变）**
|
|
113
|
+
剪口播 → 拆文稿 → 派单（B-roll 检索 / 动效 / 情景动画）→ 装配 → 渲染。每一步显式消费当前栏目配置：拆文稿按你的词表校验（`--column <id>` 或 config `defaultColumn`），B-roll 检索按你栏目的检索偏好（`broll.column_tag_ids` 栏目标签 / `material_class_policy` / facets），各车道走你自己的生产 skill。
|
|
114
|
+
|
|
115
|
+
**不建栏目？直接用默认"厨房"。** 零配置 = 内置默认栏目，端到端照常跑通，行为与配置化之前逐字节一致——栏目层是可选资产，不是必经关卡。
|
|
116
|
+
|
|
117
|
+
**管线契约**：框架对审美零预设、对管线接口全权威。产物要进渲染管线的 skill 须满足对应契约（见 [`contracts/`](../contracts/README.md)，如 HTML 动画颗粒的 `gsap-emit v1`）；契约只约束机器可判定的管线属性，画面长什么样永远归你。
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 配置
|
|
122
|
+
|
|
123
|
+
`gtrk init` 把配置写到 `~/.gitruck/config.json`（用户级统一目录，config / 缓存 / ffmpeg / 栏目配置全在 `~/.gitruck/`）。读取优先级：**环境变量 / `.env` > `init` 持久配置 > 默认根地址**。
|
|
124
|
+
|
|
125
|
+
| 项 | 来源 | 说明 |
|
|
126
|
+
|---|---|---|
|
|
127
|
+
| `GITRUCK_API_KEY` | env / init | 鉴权 Header `Authorization` 的**裸值**（非 Bearer）。获取：打开 https://cloud.ai-mcn.tv/zh-CN ，点「注册 / 登录」（登录即开通），进入「仪表盘」复制 |
|
|
128
|
+
| `GITRUCK_API_BASE` | env / init | API 根地址，默认 `https://api.ai-mcn.tv:10000` |
|
|
129
|
+
| 剪映草稿目录 | init / 自动探测 / `--jianying-draft-dir` | 决定剪映草稿落哪、能否直接打开 |
|
|
130
|
+
| `defaultColumn` | config.json 手填 | 缺省栏目配置 id（`gtrk split` 未传 `--column` 时用它；再缺省 = 内置默认栏目） |
|
|
131
|
+
| 栏目配置 | `~/.gitruck/columns/<id>.json` | 一栏目一文件；由 `/gtrk-style-maker` 生成登记，也可手写 |
|
|
132
|
+
|
|
133
|
+
非交互配置（脚本 / CI）：
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
gtrk init --api-key <KEY> --jianying-draft-dir auto -y
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
随时 `gtrk doctor` 自检：
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
✅ 运行时：node v24.x
|
|
143
|
+
✅ CLI 版本：v0.3.0（已是最新）
|
|
144
|
+
✅ API Key：已配（gc_xxx…）
|
|
145
|
+
✅ 云端连通 + 鉴权：可达，鉴权通过
|
|
146
|
+
✅ 剪映草稿目录：C:\Users\…\com.lveditor.draft
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### 枚举清单（`--refresh-catalog`）
|
|
150
|
+
|
|
151
|
+
`gtrk doctor` 里有一行「枚举清单」：CLI 从服务端拉一份**对外枚举的全集**（字幕样式与颜色、语种码、
|
|
152
|
+
工程文件格式、节奏预设、任务可用性等），落在 `~/.gitruck/catalog.json`，24 小时自动刷新。
|
|
153
|
+
|
|
154
|
+
有了它，`--subtitle-type` 这类参数传错时**在上传之前**就告诉你，并列出当前可用值；
|
|
155
|
+
服务端新增一种样式，你不必升级 CLI 就能用上。
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
gtrk doctor --refresh-catalog # 立刻重拉（无视 24 小时新鲜期）
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**拉不到清单不影响使用**：CLI 会沿用上一次的快照；完全没有快照时**跳过本地校验、直接提交**，
|
|
162
|
+
由服务端裁决——服务端白名单永远是唯一真相源。要彻底关掉这次拉取，设 `GITRUCK_CATALOG_OFFLINE=1`。
|
|
163
|
+
|
|
164
|
+
### 崩溃报告与关闭方式
|
|
165
|
+
|
|
166
|
+
gtrk 崩溃时（未捕获异常 / 未处理的 Promise 拒绝 / 顶层出口的程序缺陷）会自动上报一条报告，帮我们定位缺陷。**默认开启，首次配置时会告知一次。**
|
|
167
|
+
|
|
168
|
+
**发送的内容只有这些**：错误消息、错误堆栈、来源标识（`cli`）、CLI 版本号、本次累计发生次数，以及（仅当崩溃发生在一个云端任务过程中时）那个任务的 ID。
|
|
169
|
+
|
|
170
|
+
**明确不发送**：素材文件与内容、工程文件与路径列表、你的文稿、API Key（发送前会把 Key 的字面值与形如 `gc_…` 的 token 替换成 `<KEY>`）、设备标识、主机名、环境变量。
|
|
171
|
+
|
|
172
|
+
**只上报「崩溃」，不上报「预期内的失败」**：文件不存在、参数不合法、额度不足、命令用错——这些你看得懂的报错一条都不会发。
|
|
173
|
+
|
|
174
|
+
三种关法（任选其一，都是即时生效）：
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
gtrk init --no-crash-report # 写进配置，永久关
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4 # 环境变量，临时关一次（优先级高于配置）
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
或直接在 `~/.gitruck/config.json` 里写 `"crashReport": false`。
|
|
185
|
+
|
|
186
|
+
当前状态随时可查：`gtrk doctor` 的「崩溃自动上报」一行会写明开 / 关，以及关是被谁关的。关闭后崩溃的呈现与退出码**与开启时完全一致**——它只影响发不发那条报告。
|
|
187
|
+
|
|
188
|
+
### 使用统计与关闭方式
|
|
189
|
+
|
|
190
|
+
gtrk 会发送匿名的使用统计，帮我们知道哪些命令有人用、失败率多少、新版本多久铺开。**默认开启，首次配置时会告知一次**（紧跟崩溃报告那一行）。
|
|
191
|
+
|
|
192
|
+
**每条命令发送的内容只有这些**：命令名（注册名，如 `matrix.search`，不含任何参数）、成功或失败、失败时的错误码或分类（如 `ENOENT`，不含错误消息原文）、耗时所在的区间、调用方类型（终端，或 agent 名称，如 `claude-code`）、CLI 版本、系统与架构、Node 主版本、是否配置了 API Key（只记是 / 否）。
|
|
193
|
+
|
|
194
|
+
**明确不发送**：命令参数与选项值、文件名与路径、素材与工程内容、你的文稿、API Key、错误消息原文、设备标识、主机名、账号信息。统计服务会接触到你的 IP 地址，只用来判断国家或地区，不保存 IP 本身。
|
|
195
|
+
|
|
196
|
+
**不拖慢命令**：命令结束时只往本机 `~/.gitruck/usage-queue.jsonl` 追加一行，由一个后台进程去发，命令照常立即退出。发不出去的留在本机（最多 200 条、7 天），下次再发。
|
|
197
|
+
|
|
198
|
+
**这些情况不发**：从源码运行、跑单元测试、设置了 `CI` 环境变量。
|
|
199
|
+
|
|
200
|
+
四种关法（任选其一，都是即时生效）：
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
gtrk init --no-usage-stats # 写进配置，永久关（同时删掉本机还没发出去的）
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
GITRUCK_USAGE_STATS=0 gtrk patch move … # 环境变量，临时关一次（优先级高于配置）
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
DO_NOT_TRACK=1 gtrk … # 业界通用的「不追踪」约定，同样生效
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
或直接在 `~/.gitruck/config.json` 里写 `"usageAnalytics": false`。
|
|
215
|
+
|
|
216
|
+
当前状态随时可查：`gtrk doctor` 的「使用统计」一行会写明开 / 关、关是被谁关的，以及当前环境发不发。关闭后命令的输出与退出码**与开启时完全一致**。
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## 命令参考
|
|
221
|
+
|
|
222
|
+
常用流程入口：`gtrk oralcut` 剪口播、`gtrk long2short` 切高光、`gtrk transcript` 转文字稿、`gtrk project init` 从配音建工程。`oralcut` / `long2short` 单次源片不能超过 2 小时；超长直播先分段，见[工作流指南](workflow.md)。其余命令的最新参数也可用 `gtrk <命令> --help` 查询。
|
|
223
|
+
|
|
224
|
+
### `gtrk long2short` / `gtrk pip` / `gtrk qc` — 常用补充
|
|
225
|
+
|
|
226
|
+
- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕；`--speed-factor 0.5–2.0` 把整体调速（保音高）写进逐 clip 工程（云端不渲染、不加价）；`--camera-move` 让云端把推 / 拉镜头写成主轨片段的缩放关键帧（客户端与剪映可见可改，本地 `gtrk render` 与 PR 工程不呈现；`clips.md` 标「运镜 N 处」），之后 `gtrk patch` 裁剪 / 切分会同步维护关键帧。产物根另落整片转写 `json/transcript.json`，可对任一 clip 上客户端字幕轨：`gtrk subtitle lay --gtrk <clip 目录>/gtrk/<工程>.gtrk --transcript <产物根>/json/transcript.json --language <源语种>`（`--language` 为云端拆行语种，缺省 zh-CN）。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。抽音频之前打一行实时价格与本次预估（stderr；`--json` 根结果的 `pricing`），长片想先报价就加 `--dry-run`（零抽取、零上传、零计费、不建目录）。完整参数见 `gtrk long2short --help`。
|
|
227
|
+
- `gtrk pip lay`：把同步录制的屏录或第二机位按口播剪点铺成画中画。两源需有可对齐的公共声音；低置信时先在客户端校准，再按提示恢复。运行 `gtrk pip lay --help` 查看输入、形状、位置和偏移参数。
|
|
228
|
+
- `gtrk qc <成片>`：检查闪帧、黑帧、冻结、音量和同步问题；用 `--gtrk` 提供工程上下文，`--fail-on` 控制管线门槛。带 `--gtrk` 时，段内跳切和判为严重的过短镜头会标出所在 beat 与槽位，并列出同一 beat 里还没用上的候选段（取自工程的 `split/broll-plan.json`，按画面稳定程度排序）。检查结论供定位问题，不自动替你修片。
|
|
229
|
+
|
|
230
|
+
### `gtrk matrix --online` — 当前源码的外部平台检索入口
|
|
231
|
+
|
|
232
|
+
此入口来自当前开发工作区，安装版是否提供以 `gtrk matrix --help` 为准，云端可用性另行确认。
|
|
233
|
+
|
|
234
|
+
| 参数 | 用途与边界 |
|
|
235
|
+
| --- | --- |
|
|
236
|
+
| `--online` | 检索外部平台 B-roll，仅支持单条 search 或派单消费；与 `--local` 互斥。单条 search 必须给 `--out <结果.json>` 保存结果及断线恢复记录；派单消费需要 `--project` 或 `--dispatch`。这是云端任务，不能按纯本地工具理解 |
|
|
237
|
+
| `--platforms <list>` | 逗号分隔 `youtube,vimeo,tiktok,bilibili`，仅配合 `--online`；不指定时查询已登记的四个平台。实际结果仍取决于服务与来源可访问性 |
|
|
238
|
+
| `--online-session <name>` | 外部检索批次名，仅配合 `--online` 且不可为空；同批次续跑，换名称发起新搜索，可能产生新任务与费用 |
|
|
239
|
+
| `--online-concurrency <n>` | 外部检索同时在跑的需求数，仅配合 `--online`；取 1–8，缺省 3。按派单顺序提前提交、仍按原顺序写进 plan；`1` 为一单跑完再提交下一单 |
|
|
240
|
+
|
|
241
|
+
派单消费时若这一轮**零可铺候选**而工程里已有带候选的 `split/broll-plan.json`（例如上一轮云端或本地 plan），既有 plan 不会被覆盖：本轮 plan（含逐条报错与待核候选）另存为 `split/broll-plan.online-attempt.json`，`--json` 结果带 `plan_kept`，`planPath` 仍指既有 plan。退出码照旧非 0。
|
|
242
|
+
|
|
243
|
+
### `gtrk transcript <本地视频|配音音频>`
|
|
244
|
+
|
|
245
|
+
把本地视频或配音音频转为一个多层级的 Markdown 文字稿。只接受本地文件路径：视频在本机抽取、音频在本机转码为 16 kHz 单声道音频，只上传音频衍生物，原文件不会上传，也不支持 URL 或平台视频下载。
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
gtrk transcript "D:/素材/采访视频.mp4"
|
|
249
|
+
gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/采访.md" --json
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
缺省只生成 `D:/素材/采访视频-transcript.md`，内容固定为：
|
|
253
|
+
|
|
254
|
+
1. `## 总结`：CLI 先标记为待完成，由 `/gtrk-transcript` 驱动 Agent 阅读全文后生成并写回；
|
|
255
|
+
2. `## 文字记录`：以 `[00:01:23]` 开头的可读段落；
|
|
256
|
+
3. `## 纯文本`：完整识别正文，便于整段复制。
|
|
257
|
+
|
|
258
|
+
实时计费在运行前从官网价格表按 `asr` 查询，CLI 与文档不保存价格数字。`--json` 的 stdout 只输出 `{ok,taskId,fileId,output,transcriptJson,summaryPending}`，其中 `output` 指向这一个 Markdown；`summaryPending:true` 表示 `/gtrk-transcript` 驱动 Agent 还需生成语义总结、原地替换待总结标记，完成后仍只交付同一个文件。
|
|
259
|
+
|
|
260
|
+
> `--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 零额外计费。
|
|
261
|
+
|
|
262
|
+
### `gtrk media <子命令>` — 本地看片（参考片精读取证）
|
|
263
|
+
|
|
264
|
+
按时码或台词看任意本地视频：带台词标签的抽帧网格、逐帧看动效、视觉变化候选。**纯本地、零计费、不联网、不要 API Key**；只读本地文件，不下载链接。由 `/gtrk-ref-reading` 驱动，也可用来复核自家成片。
|
|
265
|
+
|
|
266
|
+
| 子命令 | 做什么 |
|
|
267
|
+
|---|---|
|
|
268
|
+
| `probe <视频 \| 目录>` | 时长、显示尺寸（计入像素宽高比与旋转）、帧率与 VFR、有无音轨。传**目录**时只看这一层（不递归、跳过隐藏文件），挑出音视频（`mp4 mov mkv avi webm m4v mts` / `wav mp3 m4a flac aac ogg opus`）逐个探测、按文件名排序：`{mode:"probe-dir", files:[{path, kind, duration, codec, width?, height?, fps?, hasAudio}], skipped:[{path, reason}], truncated?}`；坏文件进 `skipped` 不中断，超过 200 个只探前 200 个 |
|
|
269
|
+
| `lines <转写稿>` | 逐句 `u<id> 起–止 文本`；`--find <台词>` 列出每处出现与字级起止 |
|
|
270
|
+
| `frames <视频>` | 按 `--at` / `--every` / `--frames` / `--every-frame` 取单帧；带 `--transcript` 或 `--label` 时帧下方加标签 |
|
|
271
|
+
| `tile <视频>` | 一张带标签的网格（≤60 格） |
|
|
272
|
+
| `tiles <视频>` | 分页网格（`--cols × --rows`，缺省 3×3）；`--ranges <json>` 一次看多段；`--every-frame` 每段连续解码、保留每一原始帧 |
|
|
273
|
+
| `boundaries <视频>` | 视觉变化候选（`--rate` 缺省 12、`--threshold` 缺省 0.1、`--min-gap` 合并近邻）；带 `--transcript` 时标注对着哪句话。**是机械证据，不是镜头判定** |
|
|
274
|
+
| `cut <视频>` | 截一段证据片（`.mp4/.mov/.mkv`，重编码）。带 `--copy` 改为**流拷贝**：不重编码、秒级截长毛片（如超 2 小时的毛片分段），起点落在 `--start` 之前最近的关键帧，回执 `seconds` 是实际时长、`note` 注明关键帧对齐；`-o` 须与源片同扩展名，纯音频也收 |
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
gtrk media tiles "参考片.mp4" --frames 48 --cols 6 --rows 4 --cell 320 --transcript "精读/transcript.json" -o "精读/evidence/overview"
|
|
278
|
+
gtrk media tiles "参考片.mp4" --around "买不动" --occurrence 1 --every-frame --cols 6 --rows 4 --transcript "精读/transcript.json" -o "精读/evidence/motion/stamp"
|
|
279
|
+
gtrk media boundaries "参考片.mp4" --rate 4 --threshold 0.12 --transcript "精读/transcript.json" -o "精读/evidence/boundaries.json"
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
- **区间**：`--start/--end`（秒或 `[hh:]mm:ss.mmm`），或 `--around <台词> [--occurrence n] [--padding s]` 按台词定位（须配 `--transcript`；台词多处出现时必须指定第几处，`lines --find` 可先列出）。
|
|
283
|
+
- **转写稿**：`gtrk transcript --json` 的产物（v1，含字级时码）原生可用，也认 `hypit.transcript@1`。转写稿须是这条视频的——时长 / 文件名对不上会在 stderr 告警。
|
|
284
|
+
- **标签**（画面下方，不遮原片字幕与图形）：源片秒 · 时码（逐帧加帧号）· 句号 / 正在读的字与字级起止 / 所在整句（当前字高亮）。无字时写「此刻无字在读」「句间空隙」，不推断静音。标签用 libass 画，ffmpeg 缺 `ass` 滤镜时报错并指向 `gtrk deps install --ffmpeg`。
|
|
285
|
+
- **落点**：`-o` 必填（`frames` 例外：设了 `$GTRK_FRAMES_DIR` 时缺省落其下的新目录），不落当前目录或源片旁；已存在不覆盖，`--force` 只覆盖本命令族的旧产物。`frames` / `tiles` 的产物目录含 `index.json`，逐格记录文件、时间、字与句号。逐帧单次上限 1800 帧。
|
|
286
|
+
|
|
287
|
+
### `gtrk client <子命令>` — 读编辑器里的工程
|
|
288
|
+
|
|
289
|
+
即剪客户端开着这个工程时，经本机通道读**活状态**（选中哪段、播放头、未存盘的改动、编辑器所见的画面）；没开时读工程文件 / 本地渲染出帧。两条路输出同形，`source` 标明走的是哪条。**不依赖客户端**：没装、没开、开的是别的工程，三个子命令照样成功退出。
|
|
290
|
+
|
|
291
|
+
| 子命令 | 做什么 | `--json` 输出 |
|
|
292
|
+
|---|---|---|
|
|
293
|
+
| `state` | 工程摘要：各轨片段与轨上时码、工程时长；主轨（口播所在那条）片段带从 1 开始的 `no`。不输出整份 `.gtrk` | `{source:"client"\|"file", project, duration, tracks:[{track, kind, index, main?, clips:[{no?, clip_id, track_st, track_ed, duration, volume?}]}], selection, playhead, viewport}`；读文件时后三项为 `null` |
|
|
294
|
+
| `segment --no <N>` | 主轨第 N 段的轨上时码与口播文字（按转写句与轨上时码对位，同 `gtrk split` 投影视图口径；被剪掉的句不计入）。越界非 0 退出并说明共几段 | `{source, no, clip_id, track_st, track_ed, text}` |
|
|
295
|
+
| `frame --at <秒>` | 时间线这一刻合成后的一帧（`--width` 缺省 768）。客户端渲染时与编辑器所见一致；本地渲染零计费、不含 MG 颗粒（`note` 注明）。超出工程时长钉到末帧并说明 | `{source:"client"\|"local-render", at, path, width, height, note?}` |
|
|
296
|
+
|
|
297
|
+
```bash
|
|
298
|
+
gtrk client state --project . --json
|
|
299
|
+
gtrk client segment --no 12 --json
|
|
300
|
+
gtrk client frame --at 31.5 --json # 时间线上的 31.5 秒，不是毛片的 31.5 秒
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
> `state` 读到客户端实时状态时另带 `disk`：与盘上工程的对照 `{revision, same_layout, unsaved_changes, track_map:[{client, disk, clips}], disk_only}`。客户端里有没保存的轨道增删时两边轨号会错开（如概念轨在客户端是 `video:2`、盘上是 `video:1`），`gtrk patch` / `gtrk matrix` 改的是盘上工程，**轨号按 `disk` 一侧写**，或先在客户端保存；两边不一致时 stderr 另有一行提示。
|
|
304
|
+
|
|
305
|
+
- `--project` 缺省当前目录（`gtrk/project.gtrk` 或 `project.gtrk`）。
|
|
306
|
+
- `frame` 的图缺省写到 `$GTRK_FRAMES_DIR`，未设时为系统临时目录下 `gtrk-frames/<工程路径哈希>/frame-<秒>.jpg`，**不写进工程目录**（工程会被整体打包带走）；`-o <file.jpg>` 指定落点，已存在须 `--force`。
|
|
307
|
+
- 没走成本机通道时 `--json` 带 `bridge:{tried, reason}`（`no_file` / `not_running` / `not_open` / `protocol_too_new` / `protocol_too_old` / `timeout` / …）便于排障；人读输出首行注明读的是文件还是本地渲染。
|
|
308
|
+
- 本机通道：客户端启动时写 `~/.gitruck/client-bridge.json`（端口、口令、进程号、协议版本），只监听 `127.0.0.1`；CLI 带口令请求、单次 10 秒超时。
|
|
309
|
+
|
|
310
|
+
### `gtrk oralcut <毛片>`
|
|
311
|
+
|
|
312
|
+
| 参数 | 作用 | 缺省 |
|
|
313
|
+
|---|---|---|
|
|
314
|
+
| `-s, --script <file>` | 文字稿 txt（有稿按稿剪、更准） | 探毛片同名 `.txt`；无则无稿智能重建 |
|
|
315
|
+
| `-p, --preset <p>` | 节奏 `steady`\|`concise`\|`compact`（松→紧） | `concise` |
|
|
316
|
+
| `-o, --out <dir>` | 自定义产物目录 | `<毛片名>-video-project-<时间戳>`（同目录同名同秒撞名时追加 `-2`…；剪映草稿文件夹同理） |
|
|
317
|
+
| `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
|
|
318
|
+
| `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
|
|
319
|
+
| `--reupload` | 强制重传，忽略上传缓存 | 关 |
|
|
320
|
+
| `--no-open` | 完成后不自动打开产物目录 | **默认自动打开** |
|
|
321
|
+
| `--json` | 机读：stdout 只输出结果 JSON（给 agent / 脚本） | 关 |
|
|
322
|
+
| `--dry-run` | 只探测并报价（实时价格 + 本次预估），零抽取、零上传、零计费、不建任何目录；`--json` 时 stdout 单行 `{ ok, dry_run:true, source, duration, pricing }` | 关 |
|
|
323
|
+
|
|
324
|
+
`--json` 输出（成功时 stdout 单行）：`{ ok, outDir, files:{gtrk,jianying,xml}, jianyingDraftPath, rendered, report, errors, taskId, fileId, pricing }`；命令失败则进程非 0 退出、报错走 stderr、stdout 无 JSON。
|
|
325
|
+
|
|
326
|
+
> **计费提示**：抽音频之前，CLI 匿名查一次官网实时价格，往 stderr 打一行「计费提示」（单价 + 按原片时长算的本次预估积分，以服务端结算为准）；`--json` 结果的 `pricing` 是同一份数据。查不到时打「实时价格暂不可用，以服务端结算为准」，不阻断。`long2short` 同口径。
|
|
327
|
+
|
|
328
|
+
> 每次跑批都会把这份结果**恒写一份 `result.json` 到产物目录**（不受 `--json` 约束）；提交成功后还会落一份 `task.json` 面包屑。即便 stdout 丢了、或中途崩了，报告与 `taskId` 都在盘上，可用下面的 `oralcut-result` 秒级取回、无需重跑云端。
|
|
329
|
+
|
|
330
|
+
### `gtrk oralcut-result <taskId> --out <目录>`
|
|
331
|
+
|
|
332
|
+
按 `task_id` 从云端取回一个**已完成**任务的报告与三方工程产物（可选本地渲染成片），**跳过预处理 / 上传 / 提交 / 轮询**——报告丢了、或想换台机器再拉一次产物时用它，不重跑云端。
|
|
333
|
+
|
|
334
|
+
| 参数 | 作用 | 缺省 |
|
|
335
|
+
|---|---|---|
|
|
336
|
+
| `-o, --out <dir>` | 产物目录 | **必填**（`--out .` = 当前目录本身） |
|
|
337
|
+
| `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
|
|
338
|
+
| `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
|
|
339
|
+
| `--no-open` / `--json` | 同 `oralcut` | — |
|
|
340
|
+
|
|
341
|
+
> 取结果需用**提交该任务的同一账号** API Key（异账号 / 已删任务报 `TASK_NOT_FOUND`）。报告存于任务记录、长期可取；底层产物文件约 **60 天**后被清理，届时仍能取回报告、但产物下载会 404（命令会提示、并照常落盘报告）。
|
|
342
|
+
|
|
343
|
+
### `gtrk split [拆分稿]` — 视觉拆分派单器
|
|
344
|
+
|
|
345
|
+
成片 × transcript 投影 → beat 分镜。**无 positional = 导出投影视图**（把当前 `.gtrk` 时间线 × transcript 投影成 beat 视图，供拆分/校对，不写回）；**带拆分稿 = 校验落地**（校验拆分稿机器契约 → 投影出 beat 时码 → 原子写回 `struct_meta.split` + 产 `split/dispatch.json` 派单清单，驱动 A_ROLL / MG / AI_DRAMA / FILM_BROLL 四车道）。时码永远归 CLI（拆分稿只描述「哪段做什么」、不写时码）。
|
|
346
|
+
|
|
347
|
+
| 参数 | 作用 | 缺省 |
|
|
348
|
+
|---|---|---|
|
|
349
|
+
| `--project <dir>` | oralcut 产物目录（自动定位 `gtrk/project.gtrk` 与 `transcript/transcript.json`） | — |
|
|
350
|
+
| `--gtrk <path>` / `--transcript <path>` | 显式指定工程 / transcript（非标准布局兜底） | 由 `--project` 推 |
|
|
351
|
+
| `--column <id>` | 栏目配置 id（按你栏目词表校验 lane / category / produces） | config `defaultColumn` → 内置默认栏目 |
|
|
352
|
+
| `--md` | 落地时额外渲染人读稿 `split/visual-split.md`（由 JSON 单向渲染） | 关 |
|
|
353
|
+
| `--words` | 视图模式附字级明细 | 只出句级 |
|
|
354
|
+
| `--json` | 机读：stdout 只输出结果 JSON | 关 |
|
|
355
|
+
|
|
356
|
+
> 落地产物 `dispatch.json` 三队列 → 下游消费：`mg`（MG 颗粒）→ `gtrk mg` 命令、`film_broll` → `gtrk matrix` 命令、`ai_drama` → `/gtrk-ai-drama` skill（产四段描述稿·中英分块，纯创作、无命令）。配套 skill `/gtrk-splitter` 产拆分稿。
|
|
357
|
+
>
|
|
358
|
+
> **版式窗口**：拆分稿可选顶层键 `layouts[]`（`id` / `span` / `visual_job` / `visual_brief` / `slot_hints?`）声明哪些时间窗交给合成；窗口不占车道。写了它，落地另出 `composite` 队列 → `gtrk composite plan --mode split`，`struct_meta.split` 多一份 `layouts` 快照，人读稿多「版式窗口」一节；整段落在窗口里的叠层一律不派（出片时窗口里的颗粒不出画；`beats.skipped[]` 原因 `covered_by_layout`），稿里写了已收回的旧字段只告警、忽略。`layouts` 为空数组时顶层要写 `layout_note`。没有这个键的旧稿行为不变。字段正本 `skills/gtrk-splitter/references/field-schema.md`。
|
|
359
|
+
>
|
|
360
|
+
> **满屏卡**（零槽位版式窗口）：窗口写 `zero_slot: true`（可带 `theme` / `bg`）= 整幅纯排版、没有画面槽位的标题牌 / 章节卡 / 数据卡，由合成以零槽位场景承接、本机烘焙出片；不写 `slot_hints`、不告「短于 5 秒」、不计 25% 密度，窗口底下的 beat 派 `A_ROLL`。旧稿里 `lane: MG` + 满屏类品类（`fullscreen` / `title`，遗留 `mg-fullscreen` / `op-ed-title`）的 beat 落地时自动转成满屏卡（窗口 `L` + beat id，如 `LB07`），不进 `dispatch.mg`；回执列出转换（`--json` 的 `layouts.converted`），派单顶层带 `layouts_declared`（拆分稿没写 `layouts` 时为 `false`：精剪包装先 `--mode split` 再 `--mode auto`）。拆分稿文件不改。
|
|
361
|
+
>
|
|
362
|
+
> **派单条目自带 `span:{from,to}`**（该条目对应的 utterance 区间；`overlay` aux 派生条目写 **aux 自己的** span，可为主 beat span 的子区间）。**`track_st/track_ed` 是投影时刻的快照**——`gtrk mg` / `gtrk matrix` 消费时会**现场重投影**（见下），所以改完口播轨**不必**回来重跑 `gtrk split`，只有拆分稿本身变了才要重跑。
|
|
363
|
+
|
|
364
|
+
### `gtrk patch <move|trim|split|set|add|replace|remove>` — 元素级编辑（改工程唯一入口）
|
|
365
|
+
|
|
366
|
+
改一个 clip / gap / 颗粒的时码或参数。**agent 勿裸手改 `.gtrk` JSON** —— 片段时码是两套并存的
|
|
367
|
+
（`clip_st`+`clip_ed` 与 `clip_st`+`duration`），改一份不改另一份是**静默失败**：客户端优先读 `clip_ed`，
|
|
368
|
+
而后端不强校验它，于是没人报错、成片却用了陈旧出点。本命令负责恒等式同步 + 帧对齐 + 写前全档校验。
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
gtrk patch move --project <dir> --clip c2 --to 5.0
|
|
372
|
+
gtrk patch trim --project <dir> --clip c2 --out -1s
|
|
373
|
+
gtrk patch split --project <dir> --clip c2 --cut 5.5
|
|
374
|
+
gtrk patch set --project <dir> --track audio:1 --at 3.0 --volume 0.5
|
|
375
|
+
gtrk patch add --project <dir> --track video:2 --to 263.733 --candidate <clip_id> # 把候选放上空位
|
|
376
|
+
gtrk patch replace --project <dir> --clip <clip_id> --candidate <clip_id> # 原地换源
|
|
377
|
+
gtrk patch add --project <dir> --track video:5 --to 263.7 --candidate A --to 266.2 --candidate B # 一次放多段
|
|
378
|
+
gtrk patch remove --project <dir> --clip <clip_id> # 删掉一个片段，原位置留空
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
| 参数 | 作用 | 缺省 |
|
|
382
|
+
|---|---|---|
|
|
383
|
+
| `--project <dir>` / `--gtrk <path>` | 工程目录（自动定位 `gtrk/project.gtrk`）或直接给路径 | — |
|
|
384
|
+
| `--clip <clip_id>` | 按 id 寻址。命中 video/audio **镜像对**时视为一个编辑单元 | — |
|
|
385
|
+
| `--track <kind:idx> --at <sec>` | 按位置寻址（`track_st ≤ at < track_ed`）。与 `--clip` 互斥 | — |
|
|
386
|
+
| `--to <sec\|Nf>` | `move` / `add` 的落点（`add` 不收 `--at`：`--at` 在本命令里恒为寻址义） | — |
|
|
387
|
+
| `--candidate <clip_id>` / `--material <id>` | `add` / `replace` 的来源，二选一：B-roll 候选（先查工程候选池含邻居，再查 `split/broll-plan.json`）或 `materials` 里已登记的视频 / 图片素材 | — |
|
|
388
|
+
| `--beat <id>` | 候选所在 beat（同一候选在多个 beat 取窗不同时必给） | — |
|
|
389
|
+
| `--from <sec>` | `add` / `replace` 的源片入点（候选按它自己的源片时间，外网候选自动换成预览文件时间） | 与客户端拖候选上轨同一取窗：以 `seg.best` 居中、钳在素材范围内；素材从 0 |
|
|
390
|
+
| `--dur <sec\|Nf>` | `add` 的时长 | 落点所在空位的长度（到该轨上落点之后第一个元素的起点，出点与它取同一帧号）；后面没有元素时取候选取窗长度 |
|
|
391
|
+
| 重复 `--to` …（`add` 一次放多段） | 每个 `--to` 一段；`--candidate` / `--material` / `--track` / `--beat` / `--from` / `--dur` 各给一次（各段共用）或与 `--to` 一样多次（按顺序配对）。一次准备（同一素材只下载一次）、一次写回；同轨缺省时长下前一段停在后一段起点。次数不齐报 `paired_count_mismatch`，`--candidate` 与 `--material` 混用报 `paired_mixed_source`（混着来写 `--ops`）；某段失败报「第 N 段（第 N 个 --to）」、零写。别的动作重复给这些参数报 `repeat_only_on_add` | — |
|
|
392
|
+
| `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | `trim` 的五种语义（前两个相对、中两个绝对、`--slip` 只换源窗） | — |
|
|
393
|
+
| `--cut <sec\|Nf>` | `split` 的切点。⚠️ 与寻址用的 `--at` 是两个参数 | — |
|
|
394
|
+
| `--muted` / `--no-muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB，须 > 0；`--volume 0` 报 `volume_zero_use_muted`，静音用 `--muted`）。轨静音是总开关：片段所在轨已静音时 `--no-muted` 报 `track_muted_master`，请在客户端点开轨喇叭 | — |
|
|
395
|
+
| `--audio-fade-in <sec\|Nf>` / `--audio-fade-out <sec\|Nf>` | `set`：音频淡入 / 淡出时长（视频轨原声或音频轨片段，颗粒与空档拒收）；秒或帧、整毫秒；设 0 即删键；与另一侧之和超过片段时长即硬拒（不按比例缩）；`trim` / `split` 自动维护淡变 | — |
|
|
396
|
+
| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨；原本出声的片段移进静音轨报 `audio_track_target_muted` | — |
|
|
397
|
+
| `--total <sec\|Nf\|max>` | `set` 的顶层总长（工程级 op，与元素寻址互斥） | — |
|
|
398
|
+
| `--ops <file\|->` | 批量事务：一次读、全算、全校验、一次写；任一条失败**零写** | 关 |
|
|
399
|
+
| `--dry-run` | 只算与校验、不写文件 | 关 |
|
|
400
|
+
| `--json` | 机读回执到 stdout（人读日志转 stderr） | 关 |
|
|
401
|
+
|
|
402
|
+
> 时码字面：秒（`3.5` / `3.5s`）或帧（`105f`）；相对量带正负号（`-1s`）。
|
|
403
|
+
>
|
|
404
|
+
> 回执含 `ops[].resolved` 定位三元组 `{track, clip_id, track_st}` —— 下一轮据它复核「所指是否仍是同一元素」。
|
|
405
|
+
> `preexisting[]` 是**入档既存**的不变量问题（非本次造成，不阻断）；本次改动造成违规则**零写非 0**。
|
|
406
|
+
>
|
|
407
|
+
> ⚠️ 空档（gap）不能用 `--clip ""` 寻址：契约允许多个 gap 共享该取值，它不构成地址；用 `--track/--at`。
|
|
408
|
+
|
|
409
|
+
**`add` / `replace`（精修期放候选上轨、原地换源）**：
|
|
410
|
+
|
|
411
|
+
- 候选的素材还不在 `materials` 里时，顺手把预览下载到 `assets/broll-preview/` 并登记（与 `gtrk matrix lay` 同一份落地实现）；已登记的直接复用、不重下。所以 `matrix source-import` 之后一条 `patch add` 就能上轨。下载失败零写、非 0（`preview_download_failed`：候选地址可能过期，重跑检索 / 导入刷新）；已落盘的预览留作下次复用。
|
|
412
|
+
- `add` 只放已存在的视频轨；落点与非空档元素重叠即拒（`add_overlap`，列出挡路元素；挡路的是黑底补片时指路 `patch replace`）；落点覆盖到的显式空档让位；不 ripple、不新建轨。图片候选不收（上轨要先生成运镜）。源片不够长时钳短并告警 `add_clamped`，不拉伸。新片段 `clip_id` 为 `<beat>-add-<n>`，不带 `producer`，候选来源带纯黑 `background_fill`。
|
|
413
|
+
- `replace` 只换 `material` 与源窗：`clip_id`、所在轨、起点、倍速、变换、填充、转场、关键帧都不动；新素材从入点起不够长时如实缩短（`replace_shortened`），不拉伸、不挪起点；删去 `producer`，下一次 `matrix lay` 把这条轨当用户轨保留；旧素材条目不删。镜像对（视频 + 镜像音频）不收。
|
|
414
|
+
- 候选只在 plan（`split/broll-plan.json` 或分层快照）里、工程候选池没有时，放上轨的同时登记进该 beat 的候选池（层取它所在那份 plan；该 beat 没登记就按 plan 时间窗新建），客户端 B-roll 面板随即可见可换；回执 `source.pooled: {beat, layer}`。已在池里的不重复登记。
|
|
415
|
+
- 先按自述值把全部改动算一遍、全档校验，通过了才落地；`--dry-run` 不下载、不写文件，回执带 `would_download`。回执的 op 另带 `source`（候选 / 素材、`material_id`、`landed`：existing / reused / downloaded / registered）与 `add` 的 `gaps_consumed`。`--ops` 条目同形：`{"action":"add","track":"video:2","to":263.733,"candidate":"…"}`。
|
|
416
|
+
|
|
417
|
+
**`remove`（删片段）**：`gtrk patch remove (--clip <id> | --track video:<N> --at <秒>)` 删掉一个片段（或显式空档），原位置留空——后面的片段不动（B-roll 与口播对齐靠的就是时间位置；要补平用 `patch seal`，要挪用 `patch move`）。镜像对（视频 + 同 id 镜像音频）一起删；beat 轨上的拆分区间不收（`remove_beat_track`）；带别的参数报 `remove_args`。素材登记保留；引用它的转场写回前统一维护（`transition_dropped`）。`--ops` 条目 `{"action":"remove","clip":"…"}`，可与 `add` 同批「删了再放」。
|
|
418
|
+
|
|
419
|
+
**转场字段的保真与维护**（`transition_in` / `transition_out` / `transition_next`；由客户端产生，CLI 本期不产出、无新参数）：
|
|
420
|
+
|
|
421
|
+
- `split`：入场转场留前段，出场转场与接下一段的转场归后段（`to_clip_id` 不变），新切口不带转场。
|
|
422
|
+
- 每次运行（单发或整个 `--ops` 批）写回前对有变化的轨统一维护：悬空的 `transition_next` 删除（不改挂新邻居），放不下的按帧缩短（先头后尾），不足 1 帧删除；回执 `warnings[]` 逐条给 `transition_dropped` / `transition_shortened`。
|
|
423
|
+
- 颗粒目录运行时从 `https://api.ai-mcn.tv:9000/cloud/static/assets/transitions/catalog.json` 拉取，缓存 `~/.gitruck/cache/transitions/catalog.json`（统一静态资源缓存，与客户端共用，24 小时重拉；`composite lay` 只读缓存不联网），不随 npm 包分发；离线、目录不可用或颗粒不在目录里时转场原样保留。
|
|
424
|
+
- 与本次编辑无关的存量转场违例只进 `preexisting`（`transition_invalid`），不阻断。
|
|
425
|
+
- 铺轨命令重铺自产轨时，被替换片段带转场的条数在日志与 `--json` 回执里出 `replacedTransitionClips`，维护的删缩逐条列在 `transitions[]`；`gtrk project export` 上行前对上行体规整（盘上不动，删缩写进 `result.json` 的 `transitions`），云端 `transition_not_carried` 告警逐条打出；`gtrk render` 本期按硬切出片并计 `transition_not_carried`（`format: "cli_render"`）。
|
|
426
|
+
|
|
427
|
+
### `gtrk matrix source-import` — 指定视频链接进入某个 B-roll beat
|
|
428
|
+
|
|
429
|
+
当你已经选定视频链接，不需要关键词检索时，可以把它们直接送进指定 beat：
|
|
430
|
+
|
|
431
|
+
```bash
|
|
432
|
+
gtrk matrix source-import --project <工程目录> --beat B07 --url <视频链接> --url <另一个链接> --json
|
|
433
|
+
gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt --json
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
`--url` 可重复传，`--urls` 是逐行读取的文件；两者可同时使用，合计 1–32 条，支持 YouTube、Vimeo、TikTok、bilibili 的 HTTPS 视频页。带 `--project` 时 CLI 只追加 `struct_meta.broll` 中该 beat 的候选，不改时间线，也不会执行 `matrix lay`；完整任务回执会保存到 `split/.source-import/`。只想让 AI 或其它自动化消费结果时，改用 `--out <result.json>`，省略 `--project/--beat`。
|
|
437
|
+
|
|
438
|
+
每个指定来源生成一个整段低清预览候选，`source-import` 本身不会下载高清原片、不会改时间线，也不会创建 `online_broll_resolve`。候选的时间窗就是该来源已下载预览的完整窗口。客户端对它仍可双击打开 Trim 对话框，但裁剪范围严格限制在该候选来源窗口内；预裁剪会随拖拽进入时间线。用户把候选放入轨道并点击“确认 B-roll”后，客户端才把当前源时间窗口提交给 `online_broll_resolve`，由云端下载高清窗口并置换当前低清素材。`更多外网候选` 只对关键词检索任务分页，不会把指定来源任务重复当作搜索结果。
|
|
439
|
+
|
|
440
|
+
### `gtrk matrix status` — 一条命令看清某个 beat 的现状（只读）
|
|
441
|
+
|
|
442
|
+
```bash
|
|
443
|
+
gtrk matrix status --project <工程目录> --beat B20 --json
|
|
444
|
+
gtrk matrix status --project <工程目录> --beat B20,B21
|
|
445
|
+
gtrk matrix status --project <工程目录> --json # 全部 B-roll beat，一行一个概要
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
只接受 `--project` / `--beat` / `--json`。不调云端、不需要 Key、不写任何文件；读的是盘上工程，不含客户端里未保存的改动（那是 `gtrk client state` 的事）。`--beat` 在这里可以逗号分隔给多个；`matrix source-import` 的 `--beat` 仍只认一个。
|
|
449
|
+
|
|
450
|
+
带 `--beat` 时每个 beat 给出：
|
|
451
|
+
|
|
452
|
+
| 字段 | 内容 |
|
|
453
|
+
|---|---|
|
|
454
|
+
| `window` | 时间窗：现场重投影（与 `gtrk matrix` / `gtrk mg` 同一段代码）；退回派单快照时 `source:"dispatch_snapshot"` 并带 `degraded_reason` |
|
|
455
|
+
| `lane` / `queries` | 车道与派单检索词 |
|
|
456
|
+
| `candidates` | 工程候选池，精简字段：`clip_id`、`type`（online / cloud / local / image）、平台与标题、得分、取窗 `seg`、`review_only`、`preview_landed`（素材已登记且文件在盘上）、`used_by`（已用在哪些片段上）；不带下载地址 |
|
|
457
|
+
| `plan` | `split/broll-plan.json` 里该 beat 的候选总数、不在候选池的条数与得分最高 5 条；没有 plan 时 `present:false` |
|
|
458
|
+
| `clips` | 时间窗内各视频轨上的片段：轨、`clip_id`、素材、起止、`category`（broll / raw / black_fill / user / a_roll）、是否带产出方身份 |
|
|
459
|
+
| `gaps` / `black_only` | 主轨之上没有画面的区间（短于一帧的缝不算）；其中只盖着黑底补片的区间 |
|
|
460
|
+
|
|
461
|
+
不带 `--beat` 时，每个 B-roll beat 一行：时间窗、候选数、plan 候选数、已覆盖秒数、空缺段数与秒数。顶层另给工程 `revision`（可直接作 `gtrk patch --expected-revision`）、`main_track`、全工程视频轨总览 `video_tracks[]`（`{track, track_index, main?, verdict, layer?, clips, hidden?}`，按轨号升序，空轨也列；人读首行「视频轨：…」——`gtrk patch --track` 用这里的轨号）、重投影摘要、各候选轨的剥离判定与 `lay.relay_refused`（现在整轮重铺会不会被 `tracks_edited` 拒）。非 B-roll 车道的 beat 只给时间窗、车道与轨上片段。beat 不存在时 `ok:false`、退出码 1，并列出全部已知 beat。
|
|
462
|
+
|
|
463
|
+
### `gtrk matrix` — B-roll 检索 + 候选铺轨
|
|
464
|
+
|
|
465
|
+
**无 positional = 派单消费**：读 `split/dispatch.json` 的 `film_broll` 队列 → 双口检索 → 产候选清单 `split/broll-plan.json` + 下载 preview 代理、在工程里平铺 N 条候选轨（opencut 打开即可用轨道小眼睛对比挑选）。**`matrix search "<query>"` = 单条 ad-hoc 检索**（不依赖派单）。**`matrix fetch <clip_id...>` = 精剪期拉原片**（脱离工程，见下）。
|
|
466
|
+
|
|
467
|
+
| 参数 | 作用 | 缺省 |
|
|
468
|
+
|---|---|---|
|
|
469
|
+
| `--project <dir>` | oralcut 产物目录（定位 `split/dispatch.json` 与产物落点） | — |
|
|
470
|
+
| `--dispatch <path>` | 显式指定 `dispatch.json` | 由 `--project` 推 |
|
|
471
|
+
| `--column <id>` | 栏目配置 id（按你栏目 B-roll 检索偏好：标签 / material_class / facets） | config `defaultColumn` → 内置默认栏目 |
|
|
472
|
+
| `--lay <n>` | 候选铺轨数：平铺 N 条 B-roll 候选轨（`0` = 只出 plan 不铺轨） | `1` |
|
|
473
|
+
| `--top-k <n>` | 每 query 候选数上限（覆盖派单 shots；服务端上限 50） | 派单值 |
|
|
474
|
+
| `--material-class <c>` | 素材类型 `real_shot` \| `concept`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
|
|
475
|
+
| `--neighbors <n>` | 命中的概念素材带回原片前后各 n 条相邻片段（0–5，仅矩阵成员口）。结果多出 `source_ref`（出处名、序号、原片起止；服务端文档里叫 `source`）与 `neighbors[]`（`offset` / `contiguous` / `hit` 等）。`matrix search` 人读输出按原片顺序列出整段，并给出现成的 `gtrk matrix fetch` 命令；派单检索把邻居写进 plan 与工程，客户端面板里折叠，**不参与自动铺轨**。公开口、`--local`、`--online` 带了会提示已忽略；非法值发请求前报错 | `matrix search` 为 `0`；派单检索为 `2` |
|
|
476
|
+
| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——口播工程里留空处由候选轨**补纯黑片**。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
|
|
477
|
+
| `--black-bed` | 旧形态：铺一条纯黑底垫轨、候选片段不带底板（给不认片段底板的老版客户端过渡用）；`--no-black-bed` 已是缺省（无操作） | 关 |
|
|
478
|
+
| `--force-relay` | 候选轨已被你在客户端编辑过时仍强剥重铺（缺省会拒铺并保留那条轨）——**会删掉已确认原片的 `broll-raw-*` 素材登记、盘上原片成孤儿** | 关 |
|
|
479
|
+
| `--arrange <m>` | **B-roll 编排取数路**，**按素材来源自动定档、一般不用传**：铺你自己电脑里的素材 → `cloud`（编排在云端做，按「编排量」计费，跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 → `local`（编排仍在本机、不计费，逐字不动）。`shadow` 是观测档：本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` 不受理（传了报参数错）；云端拿不到产物时**直接报错**，不会悄悄换算法把活干完 | 按素材来源自动 |
|
|
480
|
+
| `--arrange-qc` | **编排期质检**（缺省关）：落轨**之前**就查每个 beat 的卡点句「画面有没有给到稿子说的东西」，没给到就换候选重排，最多 2 轮，到限即交付并如实登记还差哪几句。全程零渲染——替代「铺完 → 渲 → 看 → 重铺 → 再渲」那两轮。⚠️ 判定走素材理解口、**按帧计费**（每个卡点句 1 帧/轮，命中判定缓存的不重复计费），跑前报预估并征求确认（`--yes` 跳过）。与 `--arrange` 正交：本机档与云端档都能开 | 关 |
|
|
481
|
+
| `--arrange-cost-cap <n>` | 云端编排单次编排量上限：超限服务端**前置拒绝**、零执行零计费（不是跑到一半掐断）。只在 `--arrange shadow\|cloud` 时有意义 | 不限 |
|
|
482
|
+
| `--dump-request <file>` | **排障用**：把**实际上行的**云端编排请求体逐字节写到该文件。服务端**不保存你的 plan**（只留规模摘要），所以出了问题只有这份文件能复现——把它发给我们即可。⚠️ **不能指向工程目录内**（工程会被打包、拷贝、同步出去，而这份文件里有你的 beat 名与检索词）；开 `--arrange-qc` 时每轮各写一份，第 N 轮落在同名加 `.roundN`。机读回执在 `lay.arrange_run.dump_request` | 不写 |
|
|
483
|
+
| `--explain` | **外发调参仪表**：缺省的机读账面只给「留空槽数」`lay.dedup.emptySlots`（够判断素材池是不是不够用），其余调参用的细账（其中多少是窗口精修致空、跳剪避让枯竭放行几次、取用了几个高运动/模糊段）收在本开关后，人读日志同口径。不影响任何决策，工程产物逐字节不变 | 关 |
|
|
484
|
+
| `--query <q>` | `matrix search` 的检索词，可重复给：一次跑完多个角度，结果按 clip 合并（留最高分）、标 `matched_queries`、分数降序，回执多 `queries`。位置参数（整串一个词）在前；外网检索一次只收一个词 | — |
|
|
485
|
+
| `--estimate-only` | `matrix search`：只报这次最多花多少积分、不检索——`--json` 的 `billing_estimate: {credits, basis}`（`credits` 为本次花费上界，按超额价算；算不出为 `null`，如公开口价目表取不到、外网检索单价不在公开价目表里）。成员口 0、公开口按价目表 × 检索词数、`--local` 0。即剪内置 AI 据此对估价不超过 100 积分的命令免确认 | 关 |
|
|
486
|
+
| `--beat <id>` + `--project <dir>`（`matrix search`） | 把检索结果写进这个 beat 的候选池、不铺轨：并进本层快照 `split/broll-plan.<层>.json`（`gtrk patch --candidate` 直接认得），追加进工程候选登记（客户端面板立刻可见；beat 没登记就按派单时间窗新建）。重跑不重复；回执 `pool: {beat, added_to_plan, added_to_pool}`。两个参数要成对给 | — |
|
|
487
|
+
| `--pool-only`（`matrix lay`） | 只把 plan 里还没进工程候选池的候选登记进去：**不铺轨、不下载、不动任何轨**，零网络、不需要 Key（治 `matrix status` 的 `not_in_pool`）。缺省读主 plan 与各层快照（`--plan` 只读那一份），层取各自 plan；配 `--beat <id,…>` 只登记这几个 beat（不在 plan 里报错）；一条都没新增时不写工程。回执 `{pool_only:true, pooled:[{beat, layer, added}]}`。`matrix lay` 的 `--beat` 只配本开关 | 关 |
|
|
488
|
+
| `--arrange-estimate-only` | **只要预估不要执行**：走到云端编排的计价确认那一步就停，报出编排量后**成功**返回（`ok:true` + `estimateOnly:true`——那是「我在做决定」，不是「我拒绝了」），零云端调用、工程文件零改动。机读值在 `lay.arrange.units` / `lay.arrange.scale`。⚠️ 它省的是**云端那一次调用与其计费**（以及其后的候选下载与落轨），不是整条链：编排量的分母本来就要读工程、读 plan、做重投影才算得出。素材矩阵路报 `applicable:false` 而**不是 0**。与 `--yes` 同给时以本开关为准 | 关 |
|
|
489
|
+
| `--cut-align <ratio>` | 句界吸附目标比例 0..1：`0.7` ≈ 约七成字幕句起点恰逢镜头切点、三成有意错开（全对齐反而机械），`0` = 关闭、回旧节奏切槽。⚠️ 句级时码取 `transcript` 现场重投影（与关键词锚同源），**重投影降级时自动回旧行为并告警**——那一轮的吸附比例不作数 | `0.7` |
|
|
490
|
+
| `--gap-fill <mode>` | 音频驱动工程主轨的空洞怎么填：`fast` = **尽量不留黑**（放宽 score 地板从候选池填 → 耗尽则延长相邻颗粒 → 再耗尽跨 beat 借候选 → 短于最小镜头长的残洞也补真画面 → 补不满整段才垫黑片）；`solid` = 一律黑片垫齐（精修时一眼看出「这里没匹配到」）；`none` = 原样留 gap。⚠️ `fast` 借来的画面与本段稿子相关性弱、次地板槽是不到 1.2s 的快切，两者都会在日志里按 `kind` 报成 `borrowed` / `subfloor`——**如实告知，不是缺陷**；`none` 撞上客户端主轨磁吸会把 gap 吸掉，导致其后画面与配音**整体错位** | `solid` |
|
|
491
|
+
| `--highlight-weight <w>` | 仅 `matrix lay`：把「有没有看点」（信息量 / 戏剧性 / 情绪强度 / 稀缺性）融进候选排序，0..1。与 `--mark-weight`（画面好不好看）**正交**，两权之和钳到 1。⚠️ 看点分取 `describe` 的理解缓存，**没跑过 `describe` 就等于没开**——无缓存候选按中性处理，权重回吐给相似度 | `0`（关闭、零回归） |
|
|
492
|
+
| `--decode-path <mode>` | 仅 `matrix index`：场景检测的解码路 `auto` \| `gpu` \| `cpu` \| `full`。`auto` 自动探测硬解并**逐素材降级**（推荐）；`gpu`/`cpu`/`full` 钉死某档且**失败不降级**（对照与排障用）。⚠️ 缺省仍是 `full`（旧行为），要提速得自己传 `auto` | `full` |
|
|
493
|
+
| `--proxy-width <n>` | 仅 `matrix index`：代理解码宽度。⚠️ 再往下保真度明显劣化，**勿随手调小** | `384` |
|
|
494
|
+
| `--proxy-scaler <name>` | 仅 `matrix index`：代理缩放算法。缺省 `neighbor`（点采样不滤波）；需要其它算法时显式传入 | `neighbor` |
|
|
495
|
+
| `--exclude-recent <n>` | 仅 `matrix material --scope audio`：选曲避让最近 n 首用过的 BGM。历史由 `audio lay` 落轨**自动记账**，不用自己维护 | `12` |
|
|
496
|
+
| `--no-exclude-recent` | 关掉上一条的选曲避让，允许复用近期曲目 | 关（缺省避让） |
|
|
497
|
+
| `--out <file>` | ad-hoc 模式结果落文件；`matrix fetch` 原片落盘目录（绝不写剪映草稿目录） | stdout / `./matrix-fetch/` |
|
|
498
|
+
| `--json` | 机读：stdout 只输出结果 JSON | 关 |
|
|
499
|
+
|
|
500
|
+
**`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`、不写剪映草稿目录；在剪映里补的料不回流工程（导出单向）。
|
|
501
|
+
|
|
502
|
+
> **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 退出）。
|
|
503
|
+
>
|
|
504
|
+
> **云端编排（`--arrange`）**：B-roll 的**编排决策**（哪一颗放哪、切多长、从素材的哪一段取）可以交给云端跑。
|
|
505
|
+
> 适用面只有一条：**本地素材上轨铺排**。素材库 / 普通素材 / 概念素材那些的匹配与铺排原来什么样、以后还什么样，
|
|
506
|
+
> 一个字节都不变。
|
|
507
|
+
>
|
|
508
|
+
> **不带这个参数时按素材来源自动定档**：铺你自己电脑里的素材走 `cloud`，铺素材库那些走 `local`。
|
|
509
|
+
> 本地素材的编排算法只在服务端迭代——改进当天生效，你不必升级客户端。
|
|
510
|
+
>
|
|
511
|
+
> ⚠️ **代价先说在前面**：本地素材的编排**只在云端完成**。云端拿不到产物（连不上 / 被拒 /
|
|
512
|
+
> 产物不合规）就**直接报错**，不会悄悄改用另一套算法把活干完——那会给你一份和云端不同的结果
|
|
513
|
+
> 而你并不知情。这条路上 `--arrange local` 不受理（传了会报参数错）。
|
|
514
|
+
>
|
|
515
|
+
> 跑前的用量确认你要是说「不跑」，**这一步就不做**（整轮铺轨中止，工程一个字节没动、plan 照常可用，随时可改主意重跑），
|
|
516
|
+
> 而不是换个便宜办法替你做完。
|
|
517
|
+
>
|
|
518
|
+
> ⚠️ **它不是省钱开关**：用素材矩阵的素材同样要付检索费。**两条路都要花钱，只是花在不同环节**——
|
|
519
|
+
> 自己的素材付编排费，矩阵素材付检索费（矩阵成员的检索是 0）。
|
|
520
|
+
>
|
|
521
|
+
> `shadow` 是观测档：本机照跑照铺轨、云端只跑一遍做对拍（**不切流**，产物仍用本机的），它不受上面那条报错规则影响。
|
|
522
|
+
>
|
|
523
|
+
> 云端两档按新计量维度**编排量**计费——要配画面的段落越多、每段候选素材越多、铺的候选轨越多就越贵。
|
|
524
|
+
> 跑前会报预估并征求确认，`--yes` 跳过、`--arrange-cost-cap` 设本次上限（超限**前置拒绝**，零执行零计费）。
|
|
525
|
+
> 完整计费口径（含既有的额度包 / 余额、阶梯价与免费档）见 **[计费说明](https://hocassian.feishu.cn/docx/DtendXStMogAbJxAOEmcCyC7n3e)**。
|
|
526
|
+
> ⚠️ 预估值只供双端一致性校验，**实际计费恒以服务端复算值为准**；两值不一致时服务端会拒绝执行且不计费。
|
|
527
|
+
> 上行的只有决策要读的字段——素材绝对路径、签名 URL、画面描述文本、派单负词、口播原文整句一律**不出你的机器**。
|
|
528
|
+
>
|
|
529
|
+
> **服务端一行不留**：那份上行的 plan 我们**不保存**（留痕只有规模明细、口径版本与复算金额，
|
|
530
|
+
> 够独立核对一笔账，但翻不出你的素材结构）。代价是**出了问题我们这边没有可复现的东西**——
|
|
531
|
+
> 所以给了 `--dump-request <file>`：它把真上行的那串字节留在**你自己的机器上**，
|
|
532
|
+
> 排障时把那个文件发给我们即可。缺省不写，且**不许写进工程目录**（工程是要被打包拷走的）。
|
|
533
|
+
>
|
|
534
|
+
> 频率上有两层保护，命中都是 **429、零执行零计费**：一层按次数限流；另一层认「同一份 plan
|
|
535
|
+
> 被反复换参数重提」这种形态。传输失败的重试发的是**逐字节相同**的请求体，不会被算进去。
|
|
536
|
+
>
|
|
537
|
+
> 候选的 `preview_url`/`cover_url` **不带签名、不会过期**（本地代理落盘后一律复用）；带签名约 24h 过期的是**原片 `url`**，由客户端「确认原片」链路重签——**不必为「重签」重跑本命令**。
|
|
538
|
+
>
|
|
539
|
+
> **重跑会剥旧重铺，但不碰你改过的轨**：候选轨的身份按「素材前缀 + 上一轮登记指纹」认，不再认轨号（客户端保存会把 overlay 轨整体重编号）。一旦某条候选轨被判定「你编辑过」（改过 clip，或在客户端确认过原片使 material 变成 `broll-raw-*`），本次**整体不铺**：不剥任何轨、不追加新轨、`.gtrk` 逐字节不变，`broll-plan.json` 照常产出，命令给出「哪条轨 / 什么证据 / 下一步」并以非 0 退出码结束（`--json` 出 `{ok:false, refused:[…]}`）。要强行重铺加 `--force-relay`。
|
|
540
|
+
>
|
|
541
|
+
> **机读账面：`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 总数`。
|
|
542
|
+
>
|
|
543
|
+
> **素材落盘自检**：写回工程之后只读检查 `materials[].path` 是否落盘。相对路径以 `.gtrk` 文件所在目录（`<产物目录>/gtrk/`）为基准解析。`--json` 出 `integrity:{ checked, counts, dangling:[…], danglingReferenced, danglingOrphan, external:[…], noPathIds:[…] }`；`dangling` 是登记存在但文件缺失的素材，并标出是否被时间线引用，绝对路径缺失另计 `external`，http(s) 素材只计数且不发网络请求。检查只告知，不改 `ok`、退出码、素材条目或文件；修复悬空引用请在客户端重新确认原片或删除对应 clip。未写回的运行（`--lay 0` / 拒铺 / 工程缺失）不出 `integrity` 字段。
|
|
544
|
+
>
|
|
545
|
+
> **片段底板（缺省）**：每个候选片段自带纯黑底（gtrk 契约 `background_fill`，窄画幅 / 缩小时不露下层口播），每条候选轨在已落成的 beat 包络内把自己的空档补成纯黑片——`--lay 2` 时只留任一条可见也不露口播；音频驱动工程（无口播）不补。`--json` 出 `lay.bed`（`fill`）与 `lay.bed_fill`（补了几段、几秒）。没有任何 B-roll 的纯黑时段记作空洞：`lay.blackBedHoleSec` / `lay.blackBedHoles` 恒出，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时给非致命告警，可调 `--score-floor` 或在客户端补片。补片素材落在 `assets/builtin/solid-000000-<W>x<H>.png` 并幂等复用。短于 1.2s 的空档（片段之间 1–2 帧的缝、锚定镜头前的空档）先在源窗余量内并进相邻片段（不越检索段界、段内切点与黑段），并不掉的才补黑，并在 `lay.flash_gaps.kept` 与告警里逐段点名。
|
|
546
|
+
>
|
|
547
|
+
> **纯黑底垫轨（`--black-bed`，旧形态）**：在候选轨之下、口播主轨之上铺满已落成的 beat 包络，候选片段不带底板；空洞口径与数值同上。老工程里已有的黑底轨在下次缺省重铺时被换成片段底板。
|
|
548
|
+
|
|
549
|
+
**本地素材模式（`matrix index` / `--local`）**：素材不必入云端素材库，用你本地的素材文件夹（视频+图片混合）直接检索铺轨：
|
|
550
|
+
|
|
551
|
+
```bash
|
|
552
|
+
gtrk matrix index --dirs <素材夹或素材文件,...> # ① 免切片建索引：内容指纹增量、断点续传，素材改名/移动不重算
|
|
553
|
+
gtrk matrix --local --dirs <素材夹或素材文件,...> --project <目录> # ② 本地检索铺轨（--lay 0 = 只出 plan 不铺轨；传单个素材文件即把检索域收窄到它）
|
|
554
|
+
gtrk matrix lay --project <目录> [--plan <path>] # ③ 消费（可编辑后的）plan 铺轨，零检索开销
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
- **路径里有英文半角逗号就重复传**：`--dirs` / `--materials` 缺省按半角逗号分隔；路径自带逗号时改成重复传（`--dirs "A" --dirs "B"`，**累加不覆盖**）。整串在盘上存在时会自动不拆，中文全角「，」从不参与拆分。**枚举报 `0/0` 时先看这一条**，其次看素材夹里有没有断链（失效的软链接）。
|
|
558
|
+
- **素材本体永不上云**：只把 512px 抽帧图送同合云自建 embed 端点向量化、即传即弃；产物以绝对路径直引本地原文件（免下载免代理）。索引按实际抽帧张数会话计量（跑前预扣、跑完多退少不补），文本检索零积分。
|
|
559
|
+
- **图片一视同仁**：图片可检索可铺轨；被选中时经云端 `image_move` 转 5 秒运镜视频入轨——**图片本体会上云**（2 积分/张，铺轨前汇总确认；同图同参恒复用不重复扣费）。零图片上云 → `--no-image-broll`。
|
|
560
|
+
- **同素材不二用**：单轮铺轨一个素材单元全局只用一次（本地视频按场景、图片按文件），候选枯竭宁空不重复；`--dedup-scope material` 收严到文件级。
|
|
561
|
+
- **含本地素材的工程不能云渲**：提交会被拒（`local_broll_cloud_render_rejected`）——走客户端本地出片或 `gtrk render`。
|
|
562
|
+
- **可选零件**：`matrix describe --plan <path> [--top-k N]` / `--materials <a,b>` 按需理解候选（VLM 描述/标签/质量分/水印·字幕·黑边·模糊信号，1 积分/张（**异步任务计费**：提交预扣→完成结算，失败自动退款；同合云内部成员豁免，跑时自动探测，`--json` 的 `credits_estimated` 即实耗、`credits_would_be` 为原价）、产物注入 plan 并本地缓存、缓存命中零计费、>20 张确认护栏）。**一条 describe 只代表一段**：`--plan` 形态每个候选只抽 `segments[0]` 的 best 一帧，产物带射程锚点 `describe.at_sec`（素材时基秒），跑完报「理解覆盖率 = 理解帧数 / 被理解候选携带的**段总数**」（`--json` 读 `describe_coverage`）——注入 N 条 ≠ 这 N 条候选都被看过；`--source-window <start,end>` 源时间窗过滤（仅 `--local`，影视解说式「第 N 段解说配影片第 N 段邻域画面」）；`matrix lay --mark-weight <0..1>` 把 describe 的质量分融进候选排序（融合分 = sim×(1-w)+(mark/100)×w，只重排序不改准入，无缓存候选按中性处理）。
|
|
563
|
+
- **看点准则**：`--highlight-rubric <text|@file>`（describe 与 lay 同参，≤2000 字符，`@<路径>` 从文件读）给看点分（`--highlight-weight`）指定**评判基准**——垂类图纸各持一份（美食判分量对比/价格实物，旅拍判奇观地貌/极端天候）。**不传 = 整个字段不上行、服务端走领域无关缺省，与本参数引入前逐字节一致**。看点分按准则分桶缓存：换准则只重打分、客观描述缓存照常复用不被覆盖；`describe --plan` 会把本轮准则的 `rubric_hash` 钉进 plan，`lay` 据此自动取同一个桶（无需重复传参），两者不同源时**硬失败**而不是静默择一。⚠️ 换准则要重新打分就得重新看片（按张计费）——免看片的文本级重打分要等服务端轻通道，现在没有。
|
|
564
|
+
- **宫格理解**：`matrix describe --layout grid` 让服务端把同一 query 的候选（`--materials` 为同一素材）拼成宫格批量理解（每页 ≤9 帧，逐格扫描角标与黑边，模糊由清晰度指标判），**单价仍 1 积分/张**、更快、同样的钱能看更多帧；但 mark / highlight **只在同页内可比**、景别与黑边不如逐张稳，要按 `--mark-weight` / `--highlight-weight` 排序或依赖景别时用缺省逐张。**不传 `--layout` = 逐张，请求体与本参数引入前逐字节一致**。是否真按宫格执行以服务端回执为准（未升级 / 运维停用时如实告知「本轮按逐张」，`--json` 读 `layout_receipt`）；缓存记每帧的产出方式，逐张理解**不复用宫格产物**（会按逐张重理解并单列张数）。
|
|
565
|
+
- **索引参数与量纲**：`--scene-threshold` 调场景切分粒度、`--stability-threshold` 固定机位判稳收敛抽帧、`--rebuild` 强制重建（理解缓存不清）；索引跨机不可移植（键=绝对路径，换机重跑 index 即可）。本地 score 量纲与云端不同（完美命中可低至 ~0.25），`--score-floor` 别按云端直觉调高。
|
|
566
|
+
|
|
567
|
+
**`gtrk matrix material "<词>"`（通用三态素材检索）**：与上面的 B-roll 检索并列的第二条线，出**整条素材**的下载直链（不是段落）——`--scope clip|image|audio`（缺省 `audio`，BGM 主场）、`--commercial-only` 只搜可商用（**按需收紧的显式开关，缺省不带**）、`--min-duration/--max-duration` 按成片时长挑、`--top-k`（缺省 5，服务端上限 50）、`--diversity` 去同质、`--json` 机读、`--out` 落盘。`--scope clip|image` 时另附 **Pexels 补充结果**，单列在 `pexels_results`、不计入候选数（`--no-stock` 关闭）；补充素材直接用 `download_url` 下载（不走 `matrix fetch`），引用时保留摄影师署名与 Pexels 链接。
|
|
568
|
+
|
|
569
|
+
> ⚠️ **`is_copyright` 读作「能不能商用」，不是「有没有被版权保护」**：`true` = **可商用**（自有 ∪ 已授权），`false` = **不可商用**。
|
|
570
|
+
>
|
|
571
|
+
> **`false` 不要读成「无版权、可以随便用」——它恰恰相反。** 决定性反证：他人版权的概念素材入库固定写 `is_copyright=0`；这个字段若真是「是否受版权保护」，那批必须是 1。
|
|
572
|
+
>
|
|
573
|
+
> `is_copyright` 读作「能不能商用」：`true` = 可商用，`false` = 不可商用。`--json` 逐条派生 `copyright_label`（`"可商用"` / `"不可商用"`），它与 `is_copyright` 同向，字段缺席时也缺席；判读使用这两个键，不要从字段名猜语义。
|
|
574
|
+
>
|
|
575
|
+
> 该字段**只有矩阵成员口才有**：公开口没有它不是「不可商用」，而是服务端在源头就只放可商用素材（缺席即无需判，CLI 如实缺省、绝不补假值）。
|
|
576
|
+
>
|
|
577
|
+
> **缺省口径**：矩阵成员档默认搜全库（`copyright_scope=all`，含非商用/概念素材），不会替你收紧；随包 skill 也不应自行剔除 `is_copyright:false`，而应逐条标注版权状态。只要可商用时，显式加 `--commercial-only`。
|
|
578
|
+
|
|
579
|
+
编排配方（纯匹配 / 先理解后铺 / 时间窗 / 素材先行编剧 / 三层层叠）与 plan 编辑口径见随包 skill `/gtrk-matrix`。
|
|
580
|
+
|
|
581
|
+
### `gtrk mg` — MG 动态图颗粒（铺轨 / lint / status / render）
|
|
582
|
+
|
|
583
|
+
消费 `gtrk split` 落地的 `dispatch.mg` 派单，把**你栏目的 MG 生产 skill** 产的 html-particle 颗粒铺进 `.gtrk` 工程的 `beat_track`。六种模式按首个 positional 分派：**无参 = 铺轨**、`mg lint <file>` = 单文件校验、`mg status` = 编排看板、`mg render <file>` = 独立颗粒云渲（脱离工程，精剪补给口）、`mg compile <ir.json>` = 改 IR 重编译文字模板、`mg edit <file> --say` = 自然语言改写文字模板。旧名 `gtrk rrv` 保留为弃用别名（会打提示，建议改用 `gtrk mg`）。
|
|
584
|
+
|
|
585
|
+
| 参数 | 作用 | 缺省 |
|
|
586
|
+
|---|---|---|
|
|
587
|
+
| `--project <dir>` | oralcut / split 产物目录（定位 `split/dispatch.json` 与工程 `.gtrk`） | — |
|
|
588
|
+
| `--dispatch <path>` | 显式指定 `dispatch.json`（非标准布局兜底） | 由 `--project` 推 |
|
|
589
|
+
| `--only <beat>` | 只跑单 beat（收 **beat id** 如 `B12`、非 `composition_id`；主 + 其 `-aux<n>` 叠层颗粒一并选）。**真增量合并**：只重铺命中的那几颗，轨上其余已铺颗粒（连同手调）原样保留 | 全部 |
|
|
590
|
+
| `--lint-only` | 只 lint 校验，不铺轨不写回 | 关 |
|
|
591
|
+
| `--replace-all` | 显式授权**重置整轨**：不走增量保留、整轨剥掉重铺——**会删掉轨上其余已铺颗粒** | 关 |
|
|
592
|
+
| `--duration <sec>` | **render 模式必填**：显式时长锚（秒）——独立模式无坑位包络，它同时是 lint 包络、成片时长与计费时长 | — |
|
|
593
|
+
| `--format <fmt>` | render 模式产物格式：首发仅 `qtrle`（剪映可读透明 MOV；`webm` 剪映不吃、明确拒绝） | `qtrle` |
|
|
594
|
+
| `--out <dir>` | render 模式落盘目录（绝不写剪映草稿目录——拖入剪映由你做） | `./mg-render/<composition_id>/` |
|
|
595
|
+
| `--yes` | render 模式：跳过计费预估确认 | 关 |
|
|
596
|
+
| `--json` | 机读：人读日志转 stderr，stdout 只输出结果 JSON | 关 |
|
|
597
|
+
|
|
598
|
+
- **铺轨**（`gtrk mg --project <dir>`）：读 `dispatch.mg` → 逐 beat 从 `<project>/mg/<composition_id>.html` 取源颗粒 → lint → 铺进 `beat_track`，把 `struct_meta.mg` 原子写回 `.gtrk`（幂等登记自产轨 `lay_tracks`，重铺先剥旧自产物再 append、用户手加轨零连带）。「透明叠加 / 满屏底层」由颗粒 HTML 根 `background` 反推的 `opaque` 决定。lint 按工程 `video_size` 比对颗粒画幅比例，跨比例的颗粒（如竖屏工程里声明 1920×1080 的颗粒）判 `1-canvas-match` 致命、不铺。缺 HTML / lint 失败的 beat 计入 `skipped`、不拦其余。
|
|
599
|
+
- **剥离面 ≠ 「本次铺什么」，也 ≠ 「登记轨全集」**：`--only <beat>` **只剥命中的那几颗**（真增量合并）——轨上其余已铺颗粒的 clip / 素材 / 登记条目**原样保留**，连同用户在 opencut 对它们的手调（保留的是既有 clip 原件，非照登记重建，故透明度 `opaque` 不会丢）；这些保留条目**不重新 lint、不重新复制源 HTML**（工程自包含，`<project>/mg/` 下源文件删了也不影响）。全量重铺仍是「剥净再整轨重建」，**唯一例外**是本次派单里有、却因缺 HTML / lint 未过 / 重投影后零存活而**没铺成**的那几颗——它们上一轮的 clip 保留在轨上（不因为新的做坏了就把旧的也毁掉）；反之**派单里已不存在**的已铺条目仍照剥（计划变更 ≠ 做坏了）。要连其余已铺颗粒一起剥掉重来：`--replace-all` 显式授权。
|
|
600
|
+
- **素材表不囤积**：素材按「自产身份 × 零引用」剥离（自产 = `mg-`/`rrv-` 前缀，或位于 CLI 独占的 `assets/mg/` 且文件名在自产登记里），不依赖客户端可改写的 `html_material` 前缀。`mg-` 素材数与轨上颗粒数保持一致；重复或孤儿条目会清掉。非自产素材、仍被存活 clip 引用的自产素材，以及盘上 `assets/mg/` 的 HTML 副本都不动。
|
|
601
|
+
- **「一条都没定位到」不是清空指令**：`--only` 打空、`dispatch.mg` 为空/缺失、或本次条目全被 skip，**而轨上已有已铺颗粒**时，同样拒绝写回（那是派单或选择器出问题的信号）。确要清空加 `--replace-all`。首次铺轨（轨上本就没有已铺条目）不受此限，照常走完报 `laid=0`。
|
|
602
|
+
- **槽位窗口现场重投影**：铺轨与 lint 之前先用「`transcript` × 当刻 `.gtrk`」重算每条队列条目的 `[track_st, track_ed]`，之后 lint 的坑位包络（铁律⑦）与落轨 clip 时长一律以重算值为准（`--only` 同守；aux 派生颗粒按**自己的** span 重投影，不与主 beat 窗口混同）。`dispatch.mg` 里的时码只是**投影时刻快照**，仅在重投影不可行时兜底——**改完口播轨直接铺即可，不必先重跑 `gtrk split`**。`--json` 恒出 `reprojection:{mode,degraded,reason?,drifted,max_offset,shrunk,dropped}`（`--lint-only` 也有）。重投影后**零存活**的条目 skip 并计入 `skipped`（不复制 HTML、不按快照铺回去）；重投影不可行（transcript 缺失 / 工程定位不到 / 主轨查不到口播素材）→ 降级用快照 + 告警 + `--json` 标注，退出码不变；工程**非 v1** 的既有行为不变（铺轨路径版本门非 0 退出、`--lint-only` 照旧出报告）。铺轨成功会把本次时码来源（`timecode_source` / `reprojected_at`）纯追加登记进 `struct_meta.mg`。
|
|
603
|
+
- **lint**（`gtrk mg lint <颗粒.html> [--dispatch <path>]`）：纯本地静态校验颗粒 HTML 的铁律机器可判定子集（`<template>` 包裹、`data-composition-id` + 根 `data-width` / `data-height`（正整数）、`gsap.timeline({ paused: true })`、`window.__timelines` 注册、无 `Math.random` / `Date.now`、自包含无相对外链、根 `background` 与 `opaque` 自洽…）；给 `--dispatch` 时校验 `composition_id` 命中派单，并按工程 `.gtrk` 的 `video_size` 比对颗粒声明的画幅比例（`1-canvas-match`：跨比例致命，同比例不同尺寸放行，比例差 7% 以内视为同比例——DCI 4K 这类 17:9 工程里的 16:9 颗粒放行、接受 6.7% 横向拉伸；`--project` 同样）；裸 lint 不知道目标工程，只核正整数。任一致命项非 0 退出并逐条报因。
|
|
604
|
+
- **期望 id 一致性**（`1-cid-expect`，**致命**）：HTML 内 `data-composition-id` 必须等于期望 id（铺轨=该条派单的 `composition_id`；`mg lint`=文件名，仅当它命中派单或形如 `…-B<数字>[-aux<n>]` 时比对，`./tmp.html` 这类改过名的副本不比对）。防的是「复制 `<id>.html` 改名时漏改内部 id」——落轨会写出以文件名命名的 clip/material，而文件注册的是另一个 `__timelines` 键、还与同名颗粒抢同一个样式作用域。
|
|
605
|
+
- **铁律⑦ tl 总长估长**（`7-fill-slot` / `7-no-estimate` / `7-infinite-repeat`，**恒非致命、不拦铺轨**）：已知坑位包络时（铺轨逐颗；`mg lint --dispatch` 命中派单条目）对 GSAP 时间线做**静态下界估算**——逐调用降级，能解析的计入（`duration×(repeat+1) + repeatDelay×repeat`，`yoyo` 不加时长），表达式 position / 非字面量 duration 那条**跳过不计**（忽略若干调用仍是合法下界）。估长 < 包络 → 告警；一条都算不出 → 显式提示「无法静态估长，铁律⑦未校验，须真引擎 seek 验收」（**不静默**，「算不出」与「算过且通过」在输出上可区分）；含 `repeat:-1` → 告警「无限循环令总长 Infinity、铁律⑦不可静态验证，请改按坑位算死的有限 repeat」。真判据永远是渲染引擎逐帧，本项只做提醒层。
|
|
606
|
+
- **铁律⑧重复图元合并**（`8-primitive-merge`，**恒非致命、不拦铺轨**）：识别「循环体内创建，或由循环调用具名工厂创建；落到同一父节点；且没有逐元素动画驱动」的可合并 `line` / `rect` / `path` / `polyline` / `polygon` 批次。同一父节点的纯数字循环 trip count 累加后 **≥ 8** 才报数；边界含 `.length` / 具名常量而算不出时仍报「条数未知」，不做常量折叠；逐元素 `gsap.set` / tween 或被 tween 首实参使用的元素数组会被排除。本项只提示「这里有一批可**无损**合并的重复图元，合并后画面逐像素不变」，**不是风险判定**：命中不代表该颗粒会复现缺陷，未命中也不代表安全，真判据仍是真渲染出片抽帧。
|
|
607
|
+
- **回调与 seek 语义**（`x-callback-driven` / `x-engine-api-override` / `x-raf-interval`，**恒非致命、不拦铺轨**）：对齐契约同名一节。引擎定帧 MUST 使用 `seek(t,false)` / `time(t)` / `progress(p)`；颗粒可用时间线回调驱动画面，但不得覆写 `tl.seek` 或替换 `window.__timelines[…]`。三项 lint 只作提醒，不要求作者添加垫片。
|
|
608
|
+
- **status**（`gtrk mg status --project <dir>`）：汇总 MG 流水线——`dispatch.mg` beat 总数 / 已产源 HTML 数 / 已铺进 `.gtrk` 数，并逐 beat 标注（缺 HTML / 已产未铺 / 已铺）。槽位（叠层与满屏同一判据）落轨包络**整段**落在合成窗口里（`struct_meta.composite` 里状态不是 `rejected` / `trimmed` 的窗口，或 `dispatch.composite` 里还没导进合成的版式窗口；不看场景 `takeover`，与出片的覆盖判定同口径）即带 `covered_by: <窗口 id>`，部分重叠不算；顶层另有 `covered`（被接管数）与 `todo`（未产且未被接管数，即要开工的颗数）。`total` / `authored` 语义不变。
|
|
609
|
+
- **被合成接管的槽位**：铺轨跳过它们，回执 `skipped[]` 记 `{ composition_id, reason: "covered_by_composite", window }`，不算失败、不剥离已铺颗粒。没有照铺开关：出片时整段落在有效合成窗口里的颗粒一律不出画，要在合成里强调就写进合成场景。制片顺序上合成（⑥）先于 `gtrk mg`（⑦），叠层只产在窗口以外。
|
|
610
|
+
- **旧派单里的满屏槽位**：满屏卡已并入合成，新派单的 `dispatch.mg` 不再有满屏条目；以前落地的派单里 `category` 为满屏类（`fullscreen` / `title`，遗留 `mg-fullscreen` / `op-ed-title`）的槽位照旧产、铺、云渲出片。`status --json` 顶层 `legacy_fullscreen` = 这类槽位数（有就提示「重跑 `gtrk split` 转成满屏卡，本机烘焙、不计费」）。迁移期保留：重跑拆分后，全量铺轨时派单里有转换窗口（`converted_from` = 该 beat）而满屏卡还没做成合成 ⇒ 旧满屏颗粒 `<slug>-<beat>` 原样保留（回执 `kept_superseded[]`）；对应合成已 `built` 且在轨上 ⇒ 照计划变更剥（回执 `removed_superseded[]`，不计入 `removed`）；`--only` / `--replace-all` 行为不变。`fetch --category fullscreen` / `render` 推断出满屏时回执附 `hint`；`lint` 对没写 `category`、产物却有满屏实心底的派单槽位给非致命 `x-fullscreen-card-hint`。
|
|
611
|
+
- **render**（`gtrk mg render <颗粒.html> --duration <sec> [--out <dir>] [--yes]`）：**脱离工程**把单颗颗粒云渲成剪映可读的 qtrle 透明 alpha MOV（精剪补给口——粗剪导剪映后缺一颗动态图，不回客户端就能补）。链路 = lint 前置（包络 = `--duration`，任一致命项本地拦截、零提交零计费）→ **计费预估确认**（实时查价；CLI 无本地 HTML 渲染引擎，独立颗粒唯一路 = 云渲计费任务，`--yes` 跳过确认）→ 内联提交云端 → `<composition_id>.mov` 落盘 + `task.json`/`result.json` 面包屑（崩溃可凭 task_id 恢复）。**射程**：首发只出 qtrle（`--format webm` 明确拒绝，剪映不吃 VP8-alpha）、颗粒几何须为正整数、`--duration` 必填；MOV 按颗粒声明的 `data-width` / `data-height` 原尺寸出（竖屏 1080×1920 颗粒出 1080×1920 MOV）。产物不进 `.gtrk`、不写剪映草稿目录；qtrle 无损体积偏大，适合秒级颗粒。注意与 `gtrk render`（整片成片渲染）同词不同物。
|
|
612
|
+
- **fetch**（`gtrk mg fetch <检索词|块名> [--top 3] [--all]` / `gtrk mg fetch --pick <块名> --slot <beat> --project <dir>` / `--pick <块名> --as <composition_id> --duration <sec> [--out <dir>]`）：**registry 中性颗粒源**——没建栏目也能出 MG。候选态**离线**（零网络：读本机缓存的目录 `~/.gitruck/cache/mg-registry/catalog.json`，没有就用随包快照；钉死来源 commit）按检索词列 2–3 件（含 compat 标记与海报链接）；取块态先在本地判完参数与落点，再刷新一次目录（统一静态资源下发，24 小时一刷，拉不到用缓存、再用随包），然后按目录里的镜像取块（同合云优先、大陆可达，之后 GitHub raw → jsDelivr fastly → jsDelivr gcore → gh-proxy 回源；每个镜像 8 s，**每份字节都校 sha256 与字节数**，全部失败零落盘；取到的块缓存在 `~/.gitruck/cache/mg-registry/files/`）→ 机械改写八条（`<template>` 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉子层 / GSAP 源换契约 CDN / 字体换运行时镜像可证的 CJK 字体 / 时长贴坑位 / 信箱缩放不拉伸）→ `gtrk mg lint` 致命项不过不落盘 → 落 `<project>/mg/<composition_id>.html`。**骨架不是成品**：返回的 `editable`（文案 / 数值数组 / 色值）MUST 按 beat 与栏目改写后再铺。registry 中性块只有 1920×1080 一种几何（尺寸写死在块里），`--canvas` 给其它画幅拒绝；派单模式下工程 `.gtrk` 的 `video_size` 比例不是 16:9（容差 7%：4K 横屏与 DCI 17:9 照取）在下载前拒、不落盘，竖屏 / 方形工程走 `--source text`（找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示）；`excluded` 件拒取，`review` 件（canvas / 铁律 8 高危形态）可取但须真渲验收。`GITRUCK_MG_REGISTRY_BASE` 设了就只用它当目录与取块的镜像根（`<根>/catalog.json`、`<根>/files/…`，即统一发布的暂存包 / 静态盘布局），不写本机缓存。
|
|
613
|
+
- **fetch --source text**（`gtrk mg fetch --source text <检索词> [--top 3] [--offline]` / `--pick <模板 id> --slot <beat> --project <dir>` / `--pick <模板 id> --as <composition_id> [--out <dir>]`）：**同合云自家的文字特效模板库**——与中性块是两条路。模板是我方 clean-room 重写的**成品**（配色与排版已做过），**不做机械改写、MUST NOT 直接改 HTML**。每颗内嵌产生它的 IR 与双哈希，颗粒因此自带出身证明（三态 `ir` / `detached` / `html`）；手改一个字节就掉成 `detached`，云端改写会拒绝它（`gtrk mg lint` 报非致命的 `x-ir-detached`）。目录从同合云取（统一静态资源下发，缓存在与客户端共用的 `~/.gitruck/cache/text-templates/`，24 小时一刷）：拉到即以远端为准（不比版本号），拉不到用本机缓存、再用随包那份并**明示**（候选态因此永远离线可用；`--offline` 只读本机缓存与随包）；旧缓存 `~/.gitruck/text-templates/` 已废弃、不再读。取块每份字节都校 sha256 与字节数，全部失败零落盘。`GITRUCK_TEXT_TEMPLATE_BASE` 设了就只用它当目录与正文的镜像根（`<根>/catalog.json`、`<根>/files/…`），不写本机缓存。
|
|
614
|
+
**落点与时长由命令钉定**：派单模式的 `composition_id` 取自 `dispatch.mg` 那条（`<工程slug>-<beatId>`，不是 `--slot` 收的 beat id），颗粒内嵌 IR 的 `id` 与 `canvas.duration` 被钉到「期望 id」与「坑位包络 + 0.3s 余量」（铁律⑦，贴模板末尾的层跟着钉），再走 `mg compile` 同一条本地编译链重编——产物仍是 `ir` 态，`1-cid-expect` 天然对得上。独立模式 `--as` 同样改写颗粒内部 id，`--duration` 钉时长；`--slot` 与 `--duration` 互斥。两者都没改、且目标画幅就是模板的 1920×1080 时原字节落盘。
|
|
615
|
+
**画幅**：按目标画幅编（IR 住在 1920 参考系，画幅是编译入参）。派单模式缺省取工程 `.gtrk` 的 `video_size`（显式 `--canvas` 与它不符当场拒；找不到 `.gtrk` 时按 1920×1080 编并提示补 `--canvas`），独立模式取 `--canvas`、不给即 1920×1080；`--json` 带 `canvas` 与 `canvas_from`（`flag` / `project` / `reference`）。
|
|
616
|
+
- **compile**（`gtrk mg compile <ir.json | 颗粒.html> [--canvas <WxH>] [--out <dir>] [--remote]`）：把 IR **确定性编译**成颗粒（**0 积分**）。改字、换色、改字号描边阴影、改时长都走它——改 IR 再编，比手改 HTML 干净，且颗粒保持 `ir` 态（云端还能继续调）。缺省在本地编（零请求、断网可用，与服务端编译器逐字节等价）；`--remote` 改走服务端，留给排查与对拍。给颗粒 HTML = 按它内嵌的 IR 重置回模板。`--canvas` 是目标画幅：不给时重置沿用那颗自己的画幅、`.ir.json` 按 1920×1080；`--remote` 把同一画幅交给服务端，产物画幅与请求不符（旧服务端不认画幅）时不落盘。
|
|
617
|
+
- **edit**（`gtrk mg edit <颗粒.html> --say "<一句话>" [--n 1|3] [--pick <k>] [--yes]`）：自然语言改写文字模板颗粒，经云端模型链出候选。`--n` 只收 1 或 3，**它就是计费单位数**（6 积分/候选，前 200 个之后 8 积分/候选；首次与改写同价、无免费次数）。`detached` / 无内嵌 IR 的颗粒**本地就拒**，不提交云任务、不花钱。候选带 `scope`：`L1` = 在模板可调范围内、`L2` = 越界即新生成（**不是失败**）；服务端说做不到时给一句 `refusal`，命令如实转述并以非 0 退出码区分于网络错误。不给 `--pick` 就只落候选不动原文件；给了才替换并留 `<cid>.bak.html`。
|
|
618
|
+
|
|
619
|
+
`--json` 输出：`{ ok, mode:"lay"|"lint"|"status", … }`（各模式带对应字段，如铺轨的 `laid` / `skipped`、status 的逐 beat 状态）。铺轨模式另带 **`track_total`**（轨上现存已铺数）、**`kept`** / **`kept_ids`**（其中**上轮遗留**、本次没重铺的颗数与 `composition_id` 清单）与 **`removed`**（本次被剥的旧自产颗粒数）——`laid`（本次）、`track_total`（轨上共）与 `kept`（上轮遗留）**要一起读**，恒有 `track_total = laid + kept`；只看 `laid` 会让「铺 1 颗、剥 20 颗」跟「补铺 1 颗」长得一模一样，只看前两个又会漏掉「轨上那几颗不是这一轮的版本」这条代价（`kept_ids` 与 `skipped` 会重叠：这轮没铺成、上一轮那条还在轨上）。非全绿时另带机读 **`reason`**：`skipped`（部分没铺上）/ `empty_queue`（**拒写回**，工程未被改动，另带 `refused:true` 与 `blocked[]`）/ `no_project`（工程缺失未铺轨）。真写回过的运行另带 **`integrity`**（素材落盘自检，与 `gtrk matrix` 同名同形，口径见上节）。
|
|
620
|
+
|
|
621
|
+
> **退出码**：铺轨与 `--lint-only` 的 `ok:false` **一律连带非 0 退出**（含「有 beat 被 skip」这种循环中途的正常态）。agent 别把非 0 读成「命令崩了」——按 `reason` / `skipped` 判断即可。
|
|
622
|
+
|
|
623
|
+
> **aux 叠层颗粒**：`gtrk split` 若在某 beat 的 `aux_layers` 派了 `overlay` 颗粒，会派生 `<beat>-aux<n>` 合成条目进 `dispatch.mg`——`gtrk mg` 一并铺，实现「同段既有底轨主视觉、又叠透明概念图解」。
|
|
624
|
+
> **双读兼容**：`dispatch.mg`（读旧 `rrv_mg`）、源目录 `mg/`（读旧 `rrv/`）、素材前缀 `mg-`（读旧 `rrv-`）——去品牌化前的既有工程零迁移。
|
|
625
|
+
|
|
626
|
+
### `gtrk composite` — 合成层（plan / review / status / scaffold / build / lint / lay / shots / bake / materials）
|
|
627
|
+
|
|
628
|
+
粗剪、B-roll、字幕都定了之后、`gtrk mg` 铺叠层之前，把选定时间窗做成**合成颗粒**：一段时间内的整个画面由一颗代码颗粒接管，讲者、B-roll 与图片作为槽位由客户端画进去。由 `/gtrk-composite` 驱动（含编排规则与两个检查点）；纯本地、零计费。`plan --mode split` 取拆分稿的版式窗口（`dispatch.composite`，按当刻时间线重投影；理由取 `visual_brief`，`slot_hints` 进窗口上下文）——拆分稿带 `layouts` 键的工程用它、不再跑 `auto`；旧拆分稿没有该队列时报错指路。
|
|
629
|
+
|
|
630
|
+
```bash
|
|
631
|
+
gtrk composite plan --project <工程> [--mode split|full|auto|ranges] [--range 11,32 | --range u0004-u0009]... [--density 0.25]
|
|
632
|
+
gtrk composite review --project <工程> [--approve W01,W03] [--reject W02] [--adjust W04=80,90.9] [--add 140,150] [--approve-all] [--no-edge-snap]
|
|
633
|
+
gtrk composite status --project <工程> [--json]
|
|
634
|
+
gtrk composite scaffold --project <工程> [--only W03] [--force]
|
|
635
|
+
gtrk composite shots --project <工程> --material <素材 id 或文件> [--around <秒> --span <秒> | --from <秒> --to <秒>] [--every <秒>]
|
|
636
|
+
gtrk composite build --project <工程> [--only cp-w03] [--theme <css>] [--materials <json>]
|
|
637
|
+
gtrk composite lint --project <工程> [--only cp-w03] [--stills 26,86.6] [--no-browser]
|
|
638
|
+
gtrk composite lay --project <工程> [--only cp-w03] [--dry-run]
|
|
639
|
+
gtrk composite bake --project <工程> [--only cp-w03] [--fps 30] [--workers 4] [--install-browser] [--progress jsonl] [--json]
|
|
640
|
+
gtrk composite bake --input <快照.gtrk> --base <工程 gtrk 目录> [--progress jsonl]
|
|
641
|
+
gtrk composite bake --abi
|
|
642
|
+
gtrk composite materials add <图片> --project <工程> [--from-web-source <来源 id>] [--id <素材 id>] [--json]
|
|
643
|
+
gtrk composite materials list --project <工程> [--json]
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
- `plan`：候选窗口写进 `.gtrk` 的 `struct_meta.composite`（只动这一个键、原子写回；与 `gtrk split` 写 `struct_meta.split` 同一套做法），客户端大纲 CP 行据此画提案块；另出审稿稿 `composite/plan.md`。重跑保留已做的、不再提用户不要的。「建议画面」用到的文字信号（列举 / 对照 / 数字 / 分点）识别中文与英文；其他语种只看 B-roll 密度，审稿稿里写明未识别。各入口定窗口都先吸附句界与帧格，再把两端对齐**换片点**：窗口边外侧的顶层片段若横跨窗口边（窗口里本来就在播），且出窗后 0.6 秒内就换片，就把窗口外扩到那个换片点（迭代到稳定，最多与相邻窗口相接、不越过）；窗口边之后才开始的新片段（例如有意铺的转场）不碰。**短插入先收**：横跨窗口边的顶层片段短于 1 秒、不在口播主轨上、另一头落在窗口里（从窗口里开始、横跨终点；或在窗口里结束、横跨起点）——它是一段独立插入（栏目 OP、转场、卡点短镜），不是窗口里本来就在播的尾巴——窗口收到它的起点（终点）让它完整露出，这一端不再外扩。收与扩逐条写进回执 `edge_snaps`（端、`action`：`shrink` 收 / `extend` 扩、起止、毫秒、帧数、横跨的片段、`reason` 人读原因）、`plan.md` 表头与窗口理由。窗口任一端**越过口播**（终点晚于最后一句口播结束、或起点早于第一句开始）超过 1 秒时，回执 `warnings` 与 `plan.md` 告警：越过几秒、多出的那段盖住的是什么（哪条轨的哪段，纯色垫片点明黑场 / 色底，没有片段写空档），提示确认是有意为之；只告警、不改窗口。
|
|
647
|
+
- `review`：采纳 / 不要 / 调起止 / 补窗口，写回同一个键；后续步骤只处理已采纳的窗口。`--adjust` / `--add` 的区间填时间线秒或句 id，同样吸附句界、帧格与换片点（收或扩，回执 `edge_snaps`），越过口播超过 1 秒同样告警（回执 `warnings`）。`--no-edge-snap`（只配 `--adjust` / `--add`）：给的秒值原样保留（只投影到帧格），不吸附句界、不对齐换片点，回执 `warnings` 写明照常对齐会怎么挪；窗口记 `edge_snap: false`（之后不带开关再调就去掉），`lint` 对它的 `edge-flash` / `edge-insert` 只告警（`particles[].warnings`）。区间里一句口播都没有时报错（句 id 区间照旧取句界）。`--adjust` 对已做（已铺）的窗口也可用、状态仍记已做；窗口已起场景时同步场景规格里的 `window`（回执 `scene_sync`：synced / unchanged / missing / unparsed），之后 `build` → `lint` → `lay`（已铺的颗粒由 lay 替换）。
|
|
648
|
+
- `status`：只读汇总合成进度——各状态窗口数、`pending`（已采纳、还没铺轨的段数）、`pending_cards`（`pending` 里满屏卡的张数，只按窗口的 `zero_slot` 标记数）、已铺数，逐窗口一行（满屏卡带 `zero_slot: true`），起止按 `source_ranges` 投影到当刻时间线（口播被剪掉的窗口起止为空并注明）。没有合成键时全零。
|
|
649
|
+
- **满屏卡（零槽位窗口）**：`plan --mode split` 把拆分稿窗口的 `zero_slot` / `theme` / `bg` / `converted_from` / `covered_overlays` 原样写进窗口、不写 `layout_hint`；派单 `layouts_declared: false` 时回执提示接着 `--mode auto` 补其余窗口（`auto` 的密度预算不扣满屏卡，补出的窗口不与它重叠）。`scaffold` 给满屏卡只写字幕输入 `subs`（工程有讲者轨也不写讲者槽位）、`takeover` 固定字幕 + 叠层、`.bed` 取 `bg`，上下文文件多「满屏卡（零槽位）」一段。`build`：满屏卡场景声明了画面槽位（`ref` / `ref-lane` / `own`）⇒ 告警（回执 `warnings[]`）照常构建；`slots` 为空 ⇒ 照合成颗粒 profile 拒（`$.slots：必须为非空对象`）并提示保留 `subs`。
|
|
650
|
+
- `scaffold`：为已采纳窗口落场景骨架 `composite/scenes/cp-wNN.html` 与上下文 `cp-wNN.context.md`；已有场景不覆盖（`--force` 才重起），上下文照刷新。骨架按窗口形态给带正确契约的起手模板（讲者段 / 素材段 / 满屏卡）：零槽位窗口 ⇒ 满屏卡（只留字幕输入 `subs`，整张卡开窗 0.35 秒内落位）；讲者主轨在窗口里露出过半 ⇒ 讲者段（`frost` / `frost2` / `presenter` 三路同源毛玻璃：`data-filter` 开窗 0.6 秒内起雾、`data-crop` 左裁与框左边像素对齐，半透衬底 `#veil` 用 `mask-image` 羽化）；否则取窗口里露出最久的非主轨 ⇒ 素材段（素材满幅 `ref-lane` + 半透衬底）。三种都把窗口里的口播原句预填成锚点（句 id 即锚点名，关键词从原句逐字取、按 `build` 同一套规则解析过、首句避开窗口起点 0.6 秒余量），分拍走 `A()`；颜色只用主题变量、类名带 `s-` 前缀；竖屏舞台讲者 / 素材在上、板在下。回执 `shapes[]`（`{ id, shape: presenter|broll|card, track, why, anchors }`），上下文文件写明起手模板形态。
|
|
651
|
+
- `--only`（scaffold / build / lint / lay / bake）：窗口 id（`W21`）与颗粒 id（`cp-w21`）都认，大小写不敏感（`w21`、`CP-W21` 同义，序号补到两位）；其余写法按 id 片段匹配。一个都没选中时报错并列出现有的；只选中一部分时其余照做、告警哪几项没选中。
|
|
652
|
+
- `shots`：给选片用——带源时间码的联系表、镜头切点、黑边实测（`data-crop` 取值）；不替你选、不改工程。
|
|
653
|
+
- `build`：场景 → 自包含颗粒 `gtrk/assets/composite/<id>.html`。解析规则与 infra `composite-particle-profile` 逐字节一致（帧格窗口、轨身份、锚点、字幕输入、`inputs_hash`）；风格取 `composite/theme.css`——工具箱缺省变量写在 `:root` 上，theme 写 `:root { … }` 即覆盖（旧写法 `:root, #stage { … }` 照样生效）；工具箱屏上文字类缺省字号 ≥ 32px（出处卡 `.credit` 24px 带深色底条）。锚点关键词照句子原文写：匹配时关键词与句子都忽略空格、标点与大小写，英文按整词（`"cold brew"` 直接写，`tea` 不命中 `teas`）。构建前先按浏览器同一套语法解析场景脚本：语法错就这颗构建失败（`failed[].problems` 写明场景文件第几行；行内 `//` 注释吃掉同一行后面的括号时另报「疑似病因」及其行号），不产颗粒。场景 `window` 越过口播超过 1 秒时告警（回执 `warnings[]`），照常构建。
|
|
654
|
+
- `lint` 的**契约检查**（在渲染静帧之前就报，报文带改法）：`slot-css-ignored`（致命）——`[data-slot]` 元素的内联样式、命中它的样式规则、场景脚本的赋值（含 `wipe()`）或逐帧计算样式里有对视频无效的 CSS（`filter` / `backdrop-filter` / `clip-path` / `mask` / `border-radius` / 带旋转斜切透视的 `transform` / `object-fit` / `mix-blend-mode`），改用 `data-filter` / `data-crop` / `data-shape` / `at()`；`slot-filter-unsupported`（致命）——`data-filter` 不在客户端白名单（`blur(Npx)` / `brightness` / `contrast` / `saturate` / `grayscale`，数字带整数位、至多 5 个；客户端整串丢弃而烘焙照画），标记里写死的静态判、`render` 里动态改的逐帧判；`slot-never-placed`（致命）——规格声明的画面槽位（`ref` / `ref-lane` / `own`）标记里没有元素，或 `render` 里从没 `at()` / `slot()` 放置它；循环里放、拼出来的 id、CSS 定尺寸这类静态认不出的，有浏览器时逐帧兜底（采样帧加逐帧补扫，全程从未出现在舞台上才报），没有浏览器时只告警；`no-anchors`（告警）——窗口里有口播句子，场景既没写锚点也没调用 `A()`，点名写死的分拍秒数；`kit-class-collision`（告警）——风格或场景自定义了与工具箱同名的通用类（`.card` / `.rule` / `.pill` …，不含底色 `.bed` 与字幕 `.cap`、不含改工具箱变体的 `.bed.dark` 这类写法），这些规则一项也没碰工具箱给它的样式，而工具箱给它的背景 / 高度 / 圆角 / 描边 / 阴影在用到它的元素上没被覆盖；`small-text`（告警）——屏上文字字号 < 32px：无浏览器时按样式静态算（没写字号 = 浏览器缺省 16px），有浏览器时按逐帧有效字号（计算字号 × 祖先链缩放，SVG 文字按 viewBox 缩放，取完全显现的各采样帧里的最大值），出处卡 `.credit` 例外。告警进 `particles[].warnings`，不影响退出码。工具箱、出片台与颗粒字节都不改。
|
|
655
|
+
- `lint`：静态校验 + 本机 Chrome / Edge 逐帧排版机检（下层画面的前景描边压上层画面、前景线条穿过画面、画面越出舞台、容器里的元素写了 `left` / `top` 偏移却没定位——`unpositioned-offset`，容器内要写 `position:absolute` 或加 `.abs`）与**帧纯度**机检（同一帧号按「先渲前一帧」「先渲远处一帧」两种顺序各渲一次，元素与槽位几何必须一致——不一致的场景在烘焙段首、预览跳转后会画错），可出静帧。**`--stills` 填时间线秒**（整条片子上的时刻），不是合成窗口内的局部秒（场景里 `t`、`A()` 才是局部秒）；落不进任何合成窗口时报错，列出各窗口的时间线起止，这个值按局部秒能落进窗口时给出对应的时间线秒。浏览器放不了的素材封装（m2ts / mts / ts / avi / mpg / wmv / flv）不交给出片台，静帧里绑它的槽位为空（告警，回执 `stills_skipped_materials`；以烘焙或客户端预览为准）；某张静帧出不来时其余照出（回执 `stills_failed`）。静态部分另查**窗口边闪帧** `edge-flash`（与 `plan` 吸附同一判据，读当前时间线，已铺的颗粒照样查）：横跨窗口边的顶层片段出窗后只露几帧就换片，报哪颗、哪端、哪条轨的哪段、露几帧，给出 `review --adjust Wnn=起,止` 的建议值，计入「有问题」；同一判据下窗口边盖住了一段短插入的开头（结尾）报 `edge-insert`（建议收到短插入的边上），同样计入「有问题」；窗口按 `--no-edge-snap` 原样保留的，这两条只告警；`lay` 前的自检不含这两条。静态部分还按浏览器同一套语法解析颗粒里的场景脚本，语法错报 `script-syntax`（带颗粒 HTML 行号与疑似病因，计入「有问题」，`lay` 前的自检也拦）；逐帧部分颗粒加载时脚本就抛错记 `script-error`（「颗粒加载时场景脚本就报错」，带行号），页面上的 `CP.render` 仍是工具箱缺省的空函数（场景脚本没跑到赋值那一行，或写了空函数）记 `render-missing`，都计入「有问题」；render 在采样帧抛错照旧记 `script-error`（带原文）。场景脚本没跑起来（`script-syntax` / `render-missing`）的颗粒不出静帧，回执 `stills_failed` 写明原因。前景层的空路径（`<path d="">`、没有点的折线）机检时先挪开再查、查完放回，记 `empty-path` 告警（`particles[].warnings`）；工具箱排版自检在某帧报错记 `lint-error`、某颗逐帧机检没跑完记 `lint-aborted`（都带浏览器给的原因，计入「有问题」，不再统一报「颗粒无回应」）。退出码 0 通过 / 1 有问题 / 3 排版未机检（找不到浏览器，可设 `GTRK_CHROME`）。颗粒绑了联网素材（`composite/materials.json` 条目带 `source`）时另核出处卡：每个这样的 `own` 槽位要有 `data-credit-for="<槽位>"` 元素、文字（去首尾空白、连续空白折一）等于条目的 `credit`；缺出处卡 `credit-missing`、文字不一致 `credit-mismatch`、`credit` 与当前 `web/sources.jsonl` 重拼的不一致 `credit-stale`、指向不存在的槽位 `credit-orphan` 均计入「有问题」；有浏览器时另做帧检，槽位可见而出处卡看不见记 `credit-hidden`，只进回执 `particles[].warnings`、不影响退出码。不含联网素材的颗粒结果不变。
|
|
656
|
+
- `materials add <图片>`：把一张图登记成 `own` 素材——只收 `png / jpg / jpeg / webp / gif / bmp / avif` 且 ffprobe 读得出宽高；拷进 `<.gtrk 所在目录>/assets/web/<素材 id>.<小写扩展名>`；原子写入或更新 `composite/materials.json` 一条 `{ id, path, kind: "image", width, height }`（`path` 相对 `.gtrk` 所在目录，别的条目不动）。素材 id 缺省 `web-<来源 id>`（带来源）或 `img-<内容哈希前 8 位>`；同 id 同内容重复登记幂等，同 id 不同图报错（`--id` 另起）。`--from-web-source <来源 id>`：读 `<工程>/web/sources.jsonl`（内置 AI `web_fetch` 落盘的出处，每行 `{id, kind, url, title, site_name, date, fetched_at, path, mime, bytes, sha256}`，同 id 取最后一行，缺 `url` 报错指行），`<图片>` 可省（取来源条目的 `path`，须为 `kind: "image"`）；条目多带 `source`（原样拷 `id / url / title / site_name / date / fetched_at / path / sha256`）与 `credit`（出处卡文字：`site_name｜title`，缺一取一，都缺取 `url` 主机名去 `www.`；不翻译、不截断、不改写），登记的图不是来源原文件（或内容哈希对不上）时记 `derived_from`。`web/` 下的图不带 `--from-web-source` 时告警。一切报错零写入。
|
|
657
|
+
- `materials list`：只读列出同批素材清单的条目、文件在不在、出处与被哪些场景槽位（`<场景 id>:<槽位>`）引用。
|
|
658
|
+
- `lay`：按自产身份幂等铺进 beat 轨最上层、补登记素材、窗口记为已做；过期颗粒拒铺；用户在客户端改过的同 id 颗粒不覆盖。铺之前另跑契约检查三条致命规则的**静态部分**（不起浏览器）：`slot-css-ignored`、标记里写死的 `slot-filter-unsupported`、`slot-never-placed`（标记里没有元素，或脚本里根本没提到它）——拦下时报文与 `lint` 同一句、带改法，不写工程；静态认不出放置的写法（循环、拼接 id、CSS 定尺寸）不拦，回执 `warnings[]` 提示「建议先跑 gtrk composite lint」。
|
|
659
|
+
- `bake`：把已铺的合成颗粒在本机**烘焙成不透明视频**，产物落 `gtrk/assets/composite-bake/<键>.mp4`；输入（槽位画面、字幕、锚点）按**当前时间线**现算。纯本地、零计费。
|
|
660
|
+
- **浏览器**：优先钉定版本的 chrome-headless-shell（确定性出帧、最快）；没有时退回本机 Chrome / Edge（截图模式，更慢、并发降一档）。**不会静默下载**：`gtrk deps install --browser` 或本命令 `--install-browser` 显式授权才装（约 110 MB）。`GTRK_CHROME` 可指定浏览器。
|
|
661
|
+
- **并发**：常驻工作页分段并发，缺省 `min(逻辑核数/3, 6)`，`--workers` 覆盖；分段与顺序烤出的画面逐位相同。
|
|
662
|
+
- **缓存**：键含颗粒、现算输入、素材文件指纹（大小 + 修改时间）、帧率、浏览器版本与编码参数；命中直接复用。改并发不换键。
|
|
663
|
+
- **帧率**：缺省 = 工程帧率；`--fps` 指定（例如导出 30fps）。帧数 = `ceil(窗口 × fps)`，盖满整个窗口。
|
|
664
|
+
- **退出码**：0 全部成功（含命中缓存）/ 1 有颗失败（其余照常，逐颗给原因）/ 2 参数或环境错误 / 130 被取消。
|
|
665
|
+
- **机读**：`--progress jsonl` 逐行输出 `type` 为 `start` / `browser` / `prep` / `progress` / `composite` / `cancelled` / `done` 的事件，相邻两行不超过 1 秒；此模式下**关闭 stdin 即取消**（其它模式不认 stdin）。`--abi` 只输出 `{abi, version, browser, overrides, stage, host_features}`，不读工程：`browser.pinned` 是钉定的渲染组件装没装；`overrides` 是本版能烤出的槽位用户覆盖（`fit` / `framing` / `crop` 裁切 / `box` 画中画窗口大小与位置 / `slip_ms` 引用片段前后挪取帧；`box_px` 表示能烤窗口的像素位移 `dx_px` / `dy_px`），客户端据此判断工程里的调整能否烤出；`stage: "canvas"` 表示能烤任意舞台尺寸（合成舞台随工程画布，竖屏、方形同口径；缺这个字段的老版本只认 1920×1080）；`host_features`：`decor-boxes`（每次 apply 带窗口覆盖）、`slot-dewatermark`（槽位取帧套片段的去字幕 / 水印遮罩；缓存键含实际套上的遮罩）。`--input <快照> --base <目录>`：以快照为时间线来源（客户端交未保存状态用），相对素材路径与产物落点按 `--base` 解析，快照不回写。
|
|
666
|
+
- `gtrk render` / `gtrk project export` 会先烘焙工程里的合成颗粒：烘焙成功的那段以烘焙视频出画（剪映 / Pr 里是该层位上的一段视频），**时段整段落在合成窗口内的 MG / OV 不再预渲、不计费**；烘焙失败（素材丢失、找不到浏览器等）的那颗按粗剪出画并点名原因，不拦导出。
|
|
667
|
+
|
|
668
|
+
### `gtrk project init` / `gtrk audio lay` / `gtrk audio tighten` — 音频驱动工程零件（配音先行）
|
|
669
|
+
|
|
670
|
+
不从口播毛片、而从**一条配音**起盘的工程入口：先有配音（TTS 合成或自己录的），`project init` 建好 `.gtrk` 工程，之后 `gtrk split --project` 投影拆分照常接成片流水线；`audio lay` 则给任意工程补音频轨（BGM/配乐）；`audio tighten` 收紧配音的句间停顿。
|
|
671
|
+
|
|
672
|
+
| 命令 | 作用 |
|
|
673
|
+
|---|---|
|
|
674
|
+
| `gtrk project init --tts-task <task_id>` | **主路**：引用一个已完成的 `audio_tts_clone` 配音任务——服务端直取产物音频与句级时码（零 ASR、零额外计费），音频下载落工程 `audio/` |
|
|
675
|
+
| `gtrk project init --audio <配音> --transcript <transcript.json>` | **兜底路**：自备配音音频 + 句级时码稿成对给（时码稿由 `gtrk transcript <配音音频> --json` 产出；TTS 合成的配音请走主路，别重跑 ASR） |
|
|
676
|
+
| `gtrk audio lay --project <目录> --file <bgm.mp3>` | 往工程追加一条音频轨；**同源幂等替换**（同一来源重跑替换不堆轨、零引用保护剥旧）；`--volume <0..1>`（默认 0.1 垫底音量——契约 volume 只写线性增益、不写 dB；客户端音量面板显示 -20.0，两侧同一标尺；须 > 0——`0` 不会静音、会被拒，静音用 `gtrk patch set --muted`）、`--offset <ms>` 定入点 |
|
|
677
|
+
| `gtrk audio lay … --beat-align` | **高潮点锚定**（`audio_music_analyze`，计费一次）：把 BGM 的情绪峰值 `H`（服务端 `highlight.time`）压到成片高潮点 `A` 上，映射恒为 `轨秒 = A + (BGM 秒 − H)`；**两侧都够长就零平铺**（恰好 1 个 clip），不够长才按小节线平铺补齐、接缝吸附 downbeat（轨的两个硬边界处的截断不吸附）。`A` 取自 `struct_meta.split.beats` 的判据链：升华段 → 容器转折 → 回扣段 → `0.75×全片`兜底，**命中哪一档 CLI 如实报出，兜底档会明示是猜的**。无 Key / 分析失败 / 曲子缺高潮点一律降级为不锚定，命令不失败 |
|
|
678
|
+
| `gtrk audio lay … --beat-align --climax <轨秒>` | 高潮点**逃生门**：一律覆盖上面那条判据链。越界（≤ `--offset` 或 ≥ 工程末尾）或非数**直接报错**，不静默回落 —— 显式给错了值要当场知道。须与 `--beat-align` 同用 |
|
|
679
|
+
| `gtrk audio lay … --no-loop` | 不平铺补齐：开了 `--beat-align` 时只放锚点那一段、头尾留白（**留白秒数如实报出**）；未开 `--beat-align` 时保留单次、不循环叠满至工程末尾 |
|
|
680
|
+
（缺省值见 `gtrk audio tighten --help`，可按题材/音色调整）
|
|
681
|
+
|
|
682
|
+
`project init` 另有 `--canvas <WxH>`（默认 1080x1920）、`-o/--out`、`--reupload`、`--no-open`、`--json`，语义与 `oralcut` 一致；两命令 `--json` 恒出单行结果 JSON（人读日志走 stderr）。
|
|
683
|
+
|
|
684
|
+
### `gtrk project export` — 精修工程导出
|
|
685
|
+
|
|
686
|
+
把已经经过 `matrix lay` / `mg` / `audio lay` 精修的 `.gtrk` 只读导出为剪映、Premiere XML、FCPXML 或 OTIO。源工程不会被改写；缺省产物目录为工程目录下的 `export-<YYMMDD-HHMMSS>/`。
|
|
687
|
+
|
|
688
|
+
```bash
|
|
689
|
+
gtrk project export --project <工程目录>
|
|
690
|
+
gtrk project export --gtrk <工程文件> --formats jianying,xml --out <产物目录>
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
| 参数 | 作用 |
|
|
694
|
+
|---|---|
|
|
695
|
+
| `--project <dir>` / `--gtrk <path>` | 自动定位标准布局的 `gtrk/project.gtrk`，或显式指定工程文件，二选一 |
|
|
696
|
+
| `-f, --formats <list>` | `xml`、`fcpxml`、`otio`、`jianying`、`capcut`、`gtrk`；缺省 `jianying,xml`，也兼容旧细粒度格式名 |
|
|
697
|
+
| `--jianying-draft-dir <dir>` | 剪映/CapCut 草稿根；省略时按用户配置与标准位置探测。草稿落 `<草稿根>/<产物目录名>`，撞名时追加 `-2`… 并提示，原草稿不动 |
|
|
698
|
+
| `--no-particles` | 不预渲 MG 颗粒；结构导出仍继续，结果会记录被跳过的颗粒 |
|
|
699
|
+
| `--particle-concurrency <n>` | 颗粒 qtrle 预渲并发数，1–8，默认 6 |
|
|
700
|
+
|
|
701
|
+
本命令有两个计费面：工程结构导出按次计费；未命中本地 `.tonghe-cache/particles/` 的唯一颗粒按分钟计费。`gtrk project init` 仍是 0 积分，不能把这个结论套到 `export`。颗粒缓存键与客户端逐字节同构，客户端烤过的颗粒可直接复用。
|
|
702
|
+
|
|
703
|
+
颗粒预渲前会先完成 HTML、路径和缓存预检；预检失败不会提交任何云任务。单颗粒渲染或下载失败会记录在 `result.json`，其余格式继续导出。`--json` 输出单行结果 JSON，人读日志走 stderr。
|
|
704
|
+
|
|
705
|
+
**只在客户端出画的东西**（客户端加的文字、贴纸、图形、特效与画布背景）进不了这次导出的工程文件：工程里有它们时提交前提示一次哪几类、各几个；有文字时指向客户端导出剪映草稿（客户端会把文字带成可编辑字幕）。`result.json` 的 `droppedByContract.clientOnly` 记分类计数，`clientVisualElementCount` 为元素个数（此前误按车道数计）。
|
|
706
|
+
|
|
707
|
+
**片段底板**（`background_fill`）：剪映 / CapCut 的最底层轨原生承接；其它轨由云端在该片段之下插一条辅助轨——纯色 = 一段同色纯色图，模糊 = 同一段素材（同一时间段、静音、铺满画布）加剪映「模糊」特效。Pr 工程全部轨同样处理，模糊用高斯模糊；FCPXML / OTIO 只做纯色，模糊降级为纯黑并在日志里点名（素材缺尺寸信息、没法铺满时，剪映 / Pr 也降级）。片段自己就铺满画布时不垫底。纯色图引用产物目录里的 `solid-<rrggbb>-<W>x<H>.png`，命令在写工程文件之前把它们写好——**挪动或删除产物目录会让这些纯色图脱机**。`result.json` 的 `backgroundFill` 记录写出的纯色图与降级告警（工程不带底板时整键缺席）。
|
|
708
|
+
|
|
709
|
+
### `gtrk project background` — 片段底板（模糊底 / 纯色）
|
|
710
|
+
|
|
711
|
+
缺省给**主轨每个视频 / 图片片段**写片段级底板 `background_fill`（gtrk 契约字段）：片段之下、仅在其时长内铺满画布，模糊 = 片段自己画面铺满后的模糊。典型用途是横屏源进竖屏画布时用模糊底替代黑边。客户端可逐片段或多选批量改；从客户端或 `gtrk project export` 导出的剪映草稿原生承接（主轨是最底层轨），Pr 工程用同一素材铺满加高斯模糊，FCPXML / OTIO 降级为纯黑并提示，本地 `gtrk render` 承接。叠加轨片段与空档不写不改，`struct_meta.client_background` 不动（回执点名它是否仍在）。零计费、不访问云端。
|
|
712
|
+
|
|
713
|
+
`--scope canvas` 走旧的画布级写法：只改 `struct_meta.client_background` 一个键（客户端打开即按它呈现画布背景；剪映 / PR 工程与本地渲染不承接）。
|
|
714
|
+
|
|
715
|
+
```bash
|
|
716
|
+
gtrk project background --gtrk <工程文件> --blur
|
|
717
|
+
gtrk project background --project <工程目录> --blur --intensity 300
|
|
718
|
+
gtrk project background --gtrk <工程文件> --color "#1A1A1A"
|
|
719
|
+
gtrk project background --gtrk <工程文件> --clear
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
| 参数 | 作用 |
|
|
723
|
+
|---|---|
|
|
724
|
+
| `--project <dir>` / `--gtrk <path>` | 定位工程，规则同 `project export` |
|
|
725
|
+
| `--blur` | 模糊底：片段自己画面铺满后的模糊（画布级 = 主轨画面的模糊副本） |
|
|
726
|
+
| `--intensity <n>` | 配合 `--blur`，0–1000，缺省 200（逐片段须为整数） |
|
|
727
|
+
| `--color <#RRGGBB>` | 纯色底（六位十六进制） |
|
|
728
|
+
| `--clear` | 去掉底板（逐片段 = 去掉主轨片段的 `background_fill`；画布级 = 删 `client_background`，回到客户端缺省黑底） |
|
|
729
|
+
| `--scope <clips\|canvas>` | 作用面：`clips`（缺省）主轨逐片段；`canvas` 画布级（旧写法） |
|
|
730
|
+
| `--dry-run` | 只校验并回执将写入的值，不写文件 |
|
|
731
|
+
|
|
732
|
+
三种模式恰好选一个。写回走原子替换与内容 revision 守卫，其余内容原样保留；值未变时不写盘。`--json` 回执含写前写后 revision。
|
|
733
|
+
|
|
734
|
+
> **`--beat-align`**：按表格中的高潮点锚定规则工作；显式 `--climax` 会覆盖自动判据。该模式会调用 `audio_music_analyze` 并产生相应计费。
|
|
735
|
+
|
|
736
|
+
|
|
737
|
+
> **`tighten` 该在铺轨之前跑**：它会改配音轨时长，`gtrk split` / `gtrk matrix` 的 beat 时码按当刻工程重投影——先收紧再铺轨，省一次返工。想要合成时就对，自训音色可在 TTS 阶段直接传 `--fragment-interval`（见下节 `audio_tts_clone`）；云引擎音色不支持该参数，才用本命令在合成之后收。
|
|
738
|
+
|
|
739
|
+
### `gtrk tool <name> [输入...]` — 单点工具族
|
|
740
|
+
|
|
741
|
+
单发单收的独立能力，与成片管线的车道命令（`oralcut`/`split`/`matrix`/`mg`）分家。**顶层命令 + 首个 positional 词分派**（不用父子命令）：`gtrk tool <name> [输入...]` 跑工具（多文件图片工具可传多个路径，顺序即拼装顺序），`gtrk tool list` 查全部。一个工具 = 一个薄 descriptor（输入类别 / payload 拼装 / 产物映射 / 计费 / 可用门），共享 runner 跑「校验 → 上传（指纹缓存、≥256MiB 自动分片）→ 提交 → 轮询 → 流式下载落地 → `task.json`/`result.json` 面包屑」——接新工具只加一个 descriptor、不写编排。
|
|
742
|
+
|
|
743
|
+
**产物目录口径**：有输入文件的工具缺省落**输入同目录**下 `<输入名>-<工具名>/`；`input=none` 的工具（如 `audio_tts_clone`）缺省落**当前目录**下 `<工具名>-<时间戳>/`。两者都可用 `--out <dir>` 覆盖。缺省名撞上已有目录时自动带 `-2`/`-3` 序号后缀，同一目录内产物文件撞名时带 taskId 后 6 位后缀——**一律以回执的 `outDir` / `files` 为准，别按名字硬拼**（`--out` 显式落点不派生序号，重跑同一输入是幂等覆盖）。
|
|
744
|
+
|
|
745
|
+
| 工具 | 输入 | 产物 | 计费 | 状态 |
|
|
746
|
+
|---|---|---|---|---|
|
|
747
|
+
| `image_move` | 单张图片；可选 `--motion` 指定 26 种运镜之一 | 运镜视频（几何按原图朝向推导：横 1920×1080 / 竖 1080×1920） | 运行前实时查询 | 已上线 |
|
|
748
|
+
| `image_matting` | 单张图片（带 EXIF 方向的手机照片先按显示方向摆正再上传，原图不动） | 透明背景 png（可 `--param` 请求背景底板） | 运行前实时查询 | 已上线 |
|
|
749
|
+
| `image_blackborder_remove` | 单张本地图片 | 去黑边图片 | 运行前实时查询 | 已上线 |
|
|
750
|
+
| `image_canvas_adapt` | 单张本地图片；可选目标宽高与 `normal` / `rectangle` / `square` | 比例适配图片 | 运行前实时查询 | 已上线 |
|
|
751
|
+
| `image_purify` | 单张本地图片；可选 `full_screen` / `region` 与区域框，可选 `--redraw` 重绘模式（仅处理你有权处理的素材） | 清理水印、Logo 或叠加元素后的净化图片 | 运行前实时查询 | 已上线 |
|
|
752
|
+
| `video_matting` | 单条视频（**≤10 分钟**，原片直传不压代理） | 透明背景 webm | 运行前实时查询 | 已上线 |
|
|
753
|
+
| `video_blackborder_remove` | 单条本地视频 | 去黑边视频 | 运行前实时查询 | 已上线 |
|
|
754
|
+
| `video_canvas_adapt` | 单条本地视频；可选目标宽高、片段、画布模式和无音轨输出 | 比例适配视频 | 运行前实时查询 | 已上线 |
|
|
755
|
+
| `video_stabilizer` | 单条本地视频；可选 `fast` / `exp` / `turbo` | 防抖视频 | 运行前实时查询 | 已上线 |
|
|
756
|
+
| `video_vaporwave` | 单条本地视频；滤镜使用精确预设名称 | 蒸汽波滤镜视频 | 运行前实时查询 | 已上线 |
|
|
757
|
+
| `video_purify` | 单条本地视频；单点模式支持 `full_screen` / `subtitle` / `custom` / `region`；Agent 编排请用顶层 `gtrk purify detect/edit/apply`，审阅最终区域后执行 | 一条净化视频，或检测 JSON + 净化视频 | 运行前实时查询 | 已上线 |
|
|
758
|
+
| `video_upscale` | 单条本地视频（**≤1 分钟**）；可选 `2` / `3` / `4` 倍与 `Reality` / `Anime` | 一条超分视频 | 运行前实时查询 | 已上线 |
|
|
759
|
+
| `video_interpolate` | 单条本地视频；可选 `2` / `3` / `4` 倍，不附加 1 分钟限制 | 一条插帧视频 | 运行前实时查询 | 已上线 |
|
|
760
|
+
| `video_segment` | 单条本地视频；可选 `--detector content\|adaptive`、`--threshold` | 分镜区间结构 `result-output.json`（结构化数据，非下载文件） | 运行前实时查询 | 已上线 |
|
|
761
|
+
| `video_ai_segment` | 单条本地视频；可选 `--segment-mode scene\|shot_type\|narrative\|subject` | 语义分镜结构 `result-output.json`（结构化数据，非下载文件） | 运行前实时查询 | 已上线 |
|
|
762
|
+
| `video_motion_cut` | 单条本地视频 | 运镜/高光片段结构 `result-output.json`（结构化数据，非下载文件） | 运行前实时查询 | 已上线 |
|
|
763
|
+
| `video_speaker_detect` | 单条本地视频；可选 `--language`/`--max-faces-per-frame`/`--detect-body`/`--track-sample-fps`（重 GPU） | 可见说话人结构 `result-output.json`（时基以服务端输出为准） | 运行前实时查询 | 已上线 |
|
|
764
|
+
| `video_face_track` | 单条本地视频；可选 `--sample-fps`/`--max-faces`/`--min-face-ratio`/`--enable-body-match`/`--similarity-threshold`；`time_ranges` 走 `--params-json`（重 GPU） | 人物 ID/时间段/轨迹结构 `result-output.json`（时基以服务端输出为准） | 运行前实时查询 | 已上线 |
|
|
765
|
+
| `video_character_cut` | 单条本地视频；角色名、身份种子窗；多人时加 `--seed-bbox x,y,w,h`；本地镜头清单 + ≤720p/12fps 代理 | v2 原片半开毫秒时间戳、核心/上下文证据及待复核项，不下载视频 | 运行前实时查询 | v2 重构验证中，未部署 |
|
|
766
|
+
| `audio_tts_clone` | **无文件**：`--text`/`--text-file` 二选一（≤5000 字）+ `--speaker` 必填；可选语言/格式/语速/切分法/字幕/**句间停顿**（`--fragment-interval <秒>`，**仅自训音色**；云引擎音色传了会**报错**而非静默忽略，合法区间由服务端校验并在报错里给出） | 配音音频 wav/mp3（+ 可选字幕）；按文本字符数计费，计量单位与单价以 `gtrk tool list` 实时显示为准 | 运行前实时查询 | 已上线 |
|
|
767
|
+
| `video_ai_subtitle` | 单条视频或音频；`--language <码>` 必填；可选 `--translate-language`、`--need-render`、`--need-pure`、`--subtitle-type`、`--subtitle-color`。默认只传本地抽出的音频（毛片不上传） | `.ass` 字幕 + 可选烧录/去字幕 `.mp4` + `result-output.json`（摘要 + 字级时间轴） | 运行前实时查询 | 已上线 |
|
|
768
|
+
| `subtitle_translate` | 单个**字幕文件** `.ass` / `.srt`；`--language <码>` 与 `--translate-language <码>` **双必填**；可选 `--output-format`、`--line-mode`、`--bilingual`、`--subtitle-type`、`--subtitle-color`、`--canvas <WxH>`。不含语音识别 | 译文字幕 `.ass` 或 `.srt` + `result-output.json`（条数统计 + 降级标记） | 运行前实时查询 | 已上线 |
|
|
769
|
+
| `video_translate_dub` | 单条视频或音频（**≤120 分钟**，整片上传）；`--language <源语种>`、`--translate-language <目标语种>`、`--speaker <clone 或音色代号>` **三项必填**；可选 `--ref <参考音频或视频>`（仅 `clone`；克隆别人的声音须先取得本人同意）、`--ref-lang`、`--no-keep-bgm`、`--fit-policy`、`--speed-band <最小,最大>`、`--subtitle-mode`、`--subtitle-type`、`--project-formats <逗号分隔>`（缺省只出 `.gtrk`；要剪映草稿写 `gtrk,jianying`，草稿自动放进剪映草稿目录：同一毛片重跑覆盖上一次的，别的目录下的同名毛片撞上时改落 `…-2`）、`--jianying-draft-dir`；取值以服务端为准。只换音轨、画面保持原样（不做口型同步），长片耗时十几分钟起 | 配音成片 `<输入名>-dub.mp4`（音频输入为 `.mp3`）+ `dub.wav` / `bgm.wav` + 字幕 `.srt` + `transcript.json` + 工程文件按格式分目录（`gtrk/`、`jianying/` …）+ `result-output.json`（配音对齐报告；附带产物缺项时含 `errors`，不判失败） | 运行前实时查询 | 已上线 |
|
|
770
|
+
| `video_long2short_pro` | 单条长视频（整片上传）；`--language <码>` 必填；可选 `--output-language`、`--main-topic`、`--output-size`、`--no-jump-cut`、`--duration-pref`、`--max-clip-sec`、`--split-screen`、`--split-orientation`、`--speed-factor`、`--no-camera-move`、`--no-subtitle`、`--subtitle-translate-language` | 逐条成片 `clip{i}.mp4` + 人读报告 `clips.md`（含润色降级明细） + `result-output.json` | 运行前实时查询 | 已上线 |
|
|
771
|
+
| `audio_separation` | 单条音频；可选 `--mode fast\|turbo` | 人声与伴奏音频（按实际返回可为一项或两项） | 运行前实时查询 | 已上线 |
|
|
772
|
+
| `audio_speaker_split` | 单条音频；可选 `--only-struct` | 各说话人 `.wav` 分轨 + `spoken_list` 时间线（`result-output.json`） | 运行前实时查询 | 已上线 |
|
|
773
|
+
| `audio_stretch` | 单条音频；可选 `--semitones <n>`、`--speed <n>`（>0） | 变调变速音频 | 运行前实时查询 | 已上线 |
|
|
774
|
+
| `audio_noise_reduce` | 单条音频或视频；可选 `--prop-decrease 0..1` | 降噪后的音频 | 运行前实时查询 | 已上线 |
|
|
775
|
+
| `audio_silence_remove` | 单条音频；可选静音阈值与保留时长 | 去静音音频 | 运行前实时查询 | 已上线 |
|
|
776
|
+
| `piano_audio_to_midi` | 单条音频 | MIDI 文件 `.mid` | 运行前实时查询 | 已上线 |
|
|
777
|
+
| `piano_audio_enhance` | 单条音频 | 高质量 WAV + 配套 MIDI（双产物） | 运行前实时查询 | 已上线 |
|
|
778
|
+
| `image_to_square` | 单张图片；可选 `--max-line <px>`（≤20000） | 方形图片 | 运行前实时查询 | 已上线 |
|
|
779
|
+
| `image_to_live` | 单张图片 | 约 4 秒短视频 `.mp4`（无声）；或安卓动态照片 `.jpg` + 附带同一条 `.mp4` | 运行前实时查询 | 已上线 |
|
|
780
|
+
| `image_classic_template` | **多张图片** + `--main-title`（封面模式必填；`--template-mode image` 只要拼图时可省）；可选副标题/模式/比例/质量/数量/版式 | 封面/拼图成品（text/pic/render 三组、可多张） | 运行前实时查询 | 已上线 |
|
|
781
|
+
| `image_vertical_stitch` | **多张图片**（顺序=自上而下拼接顺序） | 一张垂直拼接长图 | 运行前实时查询 | 已上线 |
|
|
782
|
+
| `video_split_screen` | **2~16 段视频**（多 positional）；精确档 `--clips-json`（条目 `{input:0 起序号, begin_time_ms, end_time_ms, crop}`，毫秒时基）；九个可选布局/画幅/音频参数 | 一条分屏成片（成片时长对齐最短段） | 运行前实时查询 | 已上线 |
|
|
783
|
+
| `mad` | 一个素材文件夹（3~10 条视频）+ 可选 `--bgm` | AE 母合成成片工程 `.jsx`（仅支持 AE） | 仅 `--bgm` 触发实时查价 | 已上线 |
|
|
784
|
+
|
|
785
|
+
> 价格以 `gtrk tool list --json` 和执行前 stderr 的匿名实时查询为准，README 不保存价格快照。`video_matting` 上传前 ffprobe 探时长，> 10 分钟直接拒绝（不上传不提交、请先裁剪）。
|
|
786
|
+
> `mad` 是族内首个 **local 型「纯本地工具、可选云端加料」**：无 Key 可跑且不触发计费任务（技法数据经云端 manifest 下发 + `~/.gitruck/mad-cache` 缓存，**首拉联网、缓存后离线可跑**），`--bgm` 卡点才需 Key 并触发一次云端节拍分析；三级降级（有 Key 卡点 / 无 Key 或坏 BGM 固定节奏 / 云端失败降级）全程不崩。仅产 `.jsx`／仅支持 AE。
|
|
787
|
+
|
|
788
|
+
去黑边、比例转换、防抖、蒸汽波、净化、超分、插帧七个公共视频工具只接受服务端当前 `video_ext`：`.mp4`、`.avi`、`.mpg`、`.mov`、`.flv`、`.mxf`、`.mpeg`、`.ogg`、`.3gp`、`.wmv`、`.h264`、`.m4v`、`.ts`；`.mkv` 与 `.webm` 会在本地拒绝。输入必须是本地文件路径，CLI 不负责下载远端视频。
|
|
789
|
+
|
|
790
|
+
- `gtrk tool list [--json]` — 列全部工具（名称/说明/输入/产物/实时价格/状态）；`--json` 出单行机读数组（含动态 `billingHint`/`pricing`）。**无 API Key 也能跑**；价格通过公开接口匿名查询，失败仍列完整清单并标记暂不可用。
|
|
791
|
+
- `gtrk tool image_move ./photo.jpg [--motion zoom_in_center] [--json]` — 图转运镜；产物落 `photo-image_move/`。`--motion` 显式指定运镜方式（26 值：平移 8 `up_to_down`/`down_to_up`/`left_to_right`/`right_to_left` 及四对角线、放大锚点 9 `zoom_in_{up,down,left,right,left_up,right_up,left_down,right_down,center}`、缩小锚点 9 `zoom_out_` 同九方位），未传由云端自动选择；`--param width=1080 --param height=1920` 覆盖推导几何。
|
|
792
|
+
- `gtrk tool image_matting ./portrait.jpg` / `gtrk tool video_matting ./clip.mp4` — 图片/视频抠像。
|
|
793
|
+
- `gtrk tool image_blackborder_remove ./photo.jpg [--json]` — 自动裁去单张图片四周黑边。
|
|
794
|
+
仅接受 `normal`、`rectangle`、`square`
|
|
795
|
+
- `gtrk tool image_purify ./photo.jpg [--json]` — 清理你有权处理的图片中的水印、Logo 或叠加元素。
|
|
796
|
+
- `gtrk tool image_purify ./photo.jpg --purify-scope region --purify-region 0.02,0.02,0.15,0.08 [--json]` — 按框直接去除：不做识别，**框内全部内容都会被处理**；框越小、越贴近要去除的元素效果越好。
|
|
797
|
+
- `gtrk tool image_purify ./photo.jpg --redraw [--json]` — 重绘模式：整张图交给图片编辑模型重新生成，铺满全图的半透明、网格水印也能去掉；与 `--purify-scope region` 同用时只替换框内、框外与原图一致。**单独计价**（运行前报价按重绘档），不设免费次数；图片会发送给中国大陆以外的第三方模型服务处理，细节可能与原图略有不同；内容审核拒绝时任务失败（错误码 6054）、积分退回。也可 `--params-json '{"purify_method":"redraw"}'`。
|
|
798
|
+
- `gtrk tool video_blackborder_remove ./clip.mp4 [--json]` — 自动裁去单条视频四周黑边并保留原音轨。
|
|
799
|
+
- `gtrk tool video_canvas_adapt ./clip.mp4 --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --clip-start 1.5 --clip-end 4 --without-audio [--json]` — 视频比例转换；`--clip-start/--clip-end` 是起止时间（秒，可带小数；`--clip-start` 须小于视频时长，`--clip-end` 须大于 `--clip-start`，超过时长截到结尾），省略字段时沿用服务端默认，画布模式只接受 `normal`、`rectangle`、`square`。
|
|
800
|
+
- `gtrk tool video_stabilizer ./clip.mp4 --stabilizer-method turbo [--json]` — 视频防抖；支持 `fast`、`exp`、`turbo`，其中 `exp` 为实验方式，产物观感需自行检查。
|
|
801
|
+
- `gtrk tool video_vaporwave ./clip.mp4 --vaporwave-filter "灼熱苦夏" [--json]` — 使用精确预设名称添加蒸汽波滤镜；省略时显式使用 `愈漸升溫`。
|
|
802
|
+
视频去水印必须先问用户选快速（ffmpeg：基础模糊，可能留痕）还是精细（raft：较慢的内容修复，通常更自然、可接近无痕，不保证无损还原）。没有默认模式；`<用户选定模式>` 必须替换为用户已选择的 ffmpeg 或 raft，失败后不得自行降档。只检测、编辑和空清单不要求选择。旧运行记录尚未建处理任务时，resume 也须补显式模式；已建单继续原任务。
|
|
803
|
+
|
|
804
|
+
- `gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method <用户选定模式> --purify-roi 0,0.78,1,0.2 [--json]` — 净化用户有权修改的视频；ROI 为归一化 `x,y,w,h` 且只和 `custom` 同用。`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用该限制；不承诺还原被遮挡内容。
|
|
805
|
+
- `gtrk purify detect ./clip.mp4 --out ./purify-work --json` — 只检测，返回待审清单、摘要与代表时间。
|
|
806
|
+
- `gtrk purify edit ./purify-work/detect-xxx-final.json --select-roi 0,0.7,1,0.3 --out ./purify-work/final.json` — 本地筛选；还支持 --delete-id / --watermark-region / --protect-region。
|
|
807
|
+
- `gtrk purify run ./clip.mp4 --purify-func-type <用户选定模式> --detect-scope subtitle --watermark-region 0.8,0.02,0.18,0.08 --json` — 明确范围的自动组合；full_screen 必须显式指定。
|
|
808
|
+
- `gtrk purify ./clip.mp4 --purify-func-type <用户选定模式> --no-detect --watermark-region 0.8,0.02,0.18,0.08,0,5 --out ./purify-work --json` — 只处理给定角标框的前 5 秒，跳过文字检测；省略时间则覆盖全片。框为画面归一化 `x,y,w,h`，每条视频分别定位，不能直接套用另一条视频的选区。
|
|
809
|
+
- `gtrk purify apply ./purify-work/final.json --purify-func-type <用户选定模式> --json` — 最终清单唯一权威；空清单不建单。
|
|
810
|
+
- `gtrk purify resume ./purify-work/run-xxx.json --json` — 恢复已有任务和下载，不重复计费建单。保护区域需新版后端；ffmpeg 为模糊，raft 为内容修复。
|
|
811
|
+
|
|
812
|
+
上述 `detect-xxx-final.json` 和 `run-xxx.json` 仅示意：实际路径以命令回执中的 `finalRegionsJson` 和 `journal` 为准。检测与处理各建一次任务、分别计费；`edit` 只在本地编辑。用户明确要求直接采用检测结果时可用 `run`，仅按框去角标则用 `--no-detect`。`resume` 用于已有任务或下载中断；云端明确失败时保留任务 ID 排查，不把重复提交当成恢复。
|
|
813
|
+
|
|
814
|
+
- `gtrk tool video_upscale ./clip.mp4 --upscale-times 3 --upscale-type Anime [--json]` — 实验性视频超分；输入最多 60 秒，放大后任一边不得超过 4000 px，支持 `2`、`3`、`4` 倍和 `Reality`、`Anime`。
|
|
815
|
+
- `gtrk tool video_interpolate ./clip.mp4 --interpolate-multiplier 3 [--json]` — 视频插帧；支持 `2`、`3`、`4` 倍，不套用旧文档中的 1 分钟限制，原视频任一边不得超过 4000 px。
|
|
816
|
+
- `gtrk tool video_segment ./clip.mp4 [--detector adaptive] [--threshold 27] [--json]` — 机械分镜；产**结构化** `result-output.json`（`scene_list` 各段起止/时长），非下载文件。
|
|
817
|
+
- `gtrk tool video_ai_segment ./clip.mp4 [--segment-mode shot_type] [--json]` — 智能语义分镜；产 `result-output.json`（`categories[].shots[]` 含景别/标签/描述/秒级时码）。
|
|
818
|
+
- `gtrk tool video_motion_cut ./clip.mp4 [--json]` — 运镜/高光片段；产 `result-output.json`（`cut_points[]` 含帧号、秒级时码与运动特征）。
|
|
819
|
+
- `gtrk tool video_ai_subtitle ./clip.mp4 --language zh [--translate-language en] [--need-render] [--subtitle-color 湖蓝]` — 智能字幕：`--language` 必填，产 `.ass` 字幕 + `result-output.json`（LLM 摘要 + 字级时间轴）。**默认只上传本地抽出的音频**（毛片不出本地，几何随请求回传）；`--need-render` 改由**本地 ffmpeg 烧录**（缺 `思源黑体 CN Bold` 直接报错，不用替代字体顶）；`--need-pure` 需要画面，加了会整片上传。`subtitle_type`/`subtitle_color` 枚举与 `content` 详见云端 API 文档，`--params-json '{"content":{...}}'` 可透传。
|
|
820
|
+
- `gtrk tool subtitle_translate ./movie.ass --language zh-CN --translate-language en-US [--bilingual] [--canvas 1080x1920]` — 智能字幕**翻译**：把已有字幕换个语种，**两个语种参数都必填**。**与 `video_ai_subtitle` 的分界是输入形态**：从音视频里认出字幕走 `video_ai_subtitle`，把已有 `.ass`/`.srt` 换语种走本条（不重跑 ASR，也不覆盖已有校对）。`--line-mode keep` 让时码与输入逐条一致（可直接替换原字幕轨），缺省 `resegment` 译文更通顺但会改行数与时码；`.srt` 里没有画布信息，**竖屏务必传 `--canvas`**，否则按横屏折行可能出血。样式类参数仅 `ass` 输出有效，`srt` 输出叠样式会被服务端在扣费前拒。
|
|
821
|
+
- `gtrk tool video_long2short_pro ./talk.mp4 --language zh-CN [--split-screen] [--speed-factor 1.1]` — 长剪短·**精剪**：一键出成片，逐条 `clip{i}.mp4` + 人读报告 `clips.md`（含润色降级明细）。**与 `gtrk long2short`（粗剪）分工**：粗剪出可编辑工程（gtrk/剪映/PR）、毛片不上传、给人再剪；精剪只出成片、整片上传、计费约为粗剪两倍。判断句：剪完还要不要再动？要动走粗剪，不动走精剪。
|
|
822
|
+
- 上面三个是**分析型工具**：产物是结构化数据 `result-output.json`（非下载媒体），`result.json` 的 `resultFile` 指向它、`files` 为空且 `ok=true` 属正常。
|
|
823
|
+
- `gtrk tool audio_separation ./song.mp3 [--mode turbo]` — 人声伴奏分离；`--param need_vocals=false` 等低频字段仍可透传。
|
|
824
|
+
- `gtrk tool audio_speaker_split ./meeting.mp3 [--only-struct]` — 按说话人分轨：默认产各说话人 `.wav` + `result-output.json`（`spoken_list` 时间线）；`--only-struct` 只出结构不切文件。
|
|
825
|
+
- `gtrk tool audio_stretch ./song.mp3 [--semitones -3] [--speed 1.5]` — 变调变速；音高与速度独立，`--speed` 必须 > 0。
|
|
826
|
+
- `gtrk tool audio_noise_reduce ./interview.mp4 [--prop-decrease 0.5]` — 音频或视频均可输入，统一输出降噪音频。
|
|
827
|
+
- `gtrk tool audio_silence_remove ./talk.mp3 [--min-silence-len 800] [--desired-silence-len 200]` — 移除过长静音，只落处理后的音频。
|
|
828
|
+
- `gtrk tool piano_audio_to_midi ./piano.mp3` — 钢琴音频扒谱为 `.mid`。
|
|
829
|
+
- `gtrk tool piano_audio_enhance ./piano.mp3` — 钢琴录音修复增强，产高质量 WAV 主产物 + 配套 MIDI 副产物。
|
|
830
|
+
- `gtrk tool image_to_square ./long.jpg [--max-line 8000]` — 长图转方图；`--max-line` 默认 4000、上限 20000。
|
|
831
|
+
- `gtrk tool image_to_live ./photo.jpg [--output-format motion_photo]` — 让静态照片动起来。缺省产出约 4 秒的 `.mp4` 短视频（无声）；`--output-format motion_photo` 改为直出**安卓动态照片**（单个 `.jpg`，静图末尾内嵌该视频，相册里长按即播），并附带同一条 `.mp4`，两种格式同价。兼容边界：支持该标准的安卓相册可识别并播放；**iOS 不识别**，表现为普通静态图片；少数安卓机型可能只显示静图。
|
|
832
|
+
- `gtrk tool image_classic_template a.jpg b.jpg c.jpg --main-title "新品速览"` — 标题+多图出封面/拼图；`--output-pic-count`/`--output-text-count` 由服务端钳制 ≤20。只要拼图不要标题时加 `--template-mode image`，可不传 `--main-title`。标题含 emoji 等封面字体画不出的字符时，服务端建单前即拒（错误码 6046，不扣费）。
|
|
833
|
+
- `gtrk tool image_vertical_stitch top.png mid.png bottom.png` — 多图按传入顺序竖拼成一张长图。
|
|
834
|
+
- `gtrk tool video_split_screen a.mp4 b.mp4 --output-ratio 16:9` — 简单档：整段视频自动布局分屏（reaction/对比同框）。
|
|
835
|
+
- `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 起索引指定每段毫秒区间与归一化裁剪框；同一文件可多条目出多窗口。
|
|
836
|
+
- `gtrk tool video_speaker_detect ./talk.mp4 --language zh-CN` — 检测画面里谁在何时说话，出结构化 JSON（重 GPU）。
|
|
837
|
+
- `gtrk tool video_face_track ./talk.mp4 --params-json '{"time_ranges":[{"begin_time":0,"end_time":30000}]}'` — 人脸追踪/身份聚类，可限定时间段（**单位毫秒**；重 GPU）。
|
|
838
|
+
- `gtrk tool video_character_cut "./movie.mkv" --character "智代" --seed-range "00:12:27.500,00:12:29.500" --json` — 角色 Cut 检索（v2 尚待部署）；全片逐镜头分析，视觉种子确认身份，只上传分析代理。多人种子加 `--seed-bbox "0.445,0.36,0.16,0.5"`。结果 `cuts` 为有视觉证据的镜头及相关上下文，`review_candidates` 为身份未知镜头，`context_review` 为待复核关系；`partial` 必须展示缺口，`identity_unresolved` 要求换种子或框选。稀疏采样仅声明镜头含目标，不代表角色在整个区间逐帧可见。
|
|
839
|
+
- `gtrk tool audio_tts_clone --text "欢迎收听本期节目" --speaker narrator` — 文字转配音音频（音色列表见官网文档）。
|
|
840
|
+
- `gtrk tool audio_tts_clone --text-file 稿子.txt --speaker sweet_female --output-format mp3` — 长文合成，缺省跟随音色调好的语速与切分参数。
|
|
841
|
+
- `gtrk tool mad ./素材 [--bgm 歌.mp3] [--duration 20] [--seed 42] [--technique 技法名,…] [--refresh] [--json]` — 一键剪 MAD：扫素材文件夹 → 选技法 → 单一 `.jsx`（AE 2020+ 跑一遍出母合成成片工程）。`--seed` 可复现；`result.json` 记 seed/数据版本/降级档位/选中技法。
|
|
842
|
+
- `gtrk tool mad --technique <技法名 | 别名 | pid,…>` — 只用点名的技法出片（不点名则按规则抽样）。名字歧义或不存在时报错列候选、零落盘；点到技法池里没有窗口的技法会说明原因并用剩下的继续。
|
|
843
|
+
- `gtrk tool mad --search <关键词> [--json]` — 只查技法目录不出片：按技法名/别名/类目做包含匹配，列出技法名、类目、`pid`、收录次数与池内窗口数。与 `--technique` 互斥；两者都零计费、不需 API Key。
|
|
844
|
+
- 通用：`--out <dir>` 覆盖产物目录、`--param k=v`（可重复）/`--params-json '<对象>'` 透传云端参数、`--reupload` 忽略上传缓存、`--json` 机读、`--ffmpeg-path <dir>` 指定 ffmpeg 目录。
|
|
845
|
+
- cloud 型工具缺 Key → 报错引导 `gtrk init`。产物下载失败（如链接过期 404）→ `result.json` 记 `errors`、`ok=false`、`task.json` 保留可凭 `taskId` 恢复。
|
|
846
|
+
- 净化、超分、插帧为长耗时 GPU 任务，描述器最多轮询 4 小时。等待超时不代表任务取消；保留 `task.json` / `result.json` 并按 `taskId` 恢复，不要直接重跑造成重复计费。
|
|
847
|
+
|
|
848
|
+
配套 skill `/gtrk-tools`（一个 skill 覆盖整个工具族）。
|
|
849
|
+
|
|
850
|
+
### `gtrk render <工程.gtrk>` — 本地渲染成片
|
|
851
|
+
|
|
852
|
+
```
|
|
853
|
+
gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>]
|
|
854
|
+
[--no-qc] [--no-particles] [--particle-concurrency <n>] [-y|--yes]
|
|
855
|
+
[--no-open] [--json]
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
把 `.gtrk` 当 EDL 用本地 ffmpeg 出成片。**素材一律取本地原片**（`materials[].path`），云端不产成片。
|
|
859
|
+
|
|
860
|
+
**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。合成颗粒先在本机烘焙（见 `gtrk composite bake`，零计费），以烘焙视频叠在原层位；被它整段盖住的 MG 不再云渲。
|
|
861
|
+
|
|
862
|
+
- **可见性只读 `hidden` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
|
|
863
|
+
- **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。
|
|
864
|
+
- overlay 素材本地缺失（如 B-roll 代理没下全）**只降级不阻断**：该 clip 不叠 + 告警，片子照出。
|
|
865
|
+
- **只在客户端出画的东西不进片**：客户端加的文字（含 `gtrk subtitle lay` 铺的字幕）、贴纸、图形、特效，以及画布背景（`gtrk project background --scope canvas`）。工程里有它们时，渲染前提示一次哪几类、各几个，并指向客户端本地导出；不拦、不改渲染。`--json` 结果恒带 `clientOnly`（`text / sticker / graphic / effect / other` 计数与 `background` 布尔，全零也给）。
|
|
866
|
+
|
|
867
|
+
**颗粒那一段有计费**（本命令唯一的云端出口）：
|
|
868
|
+
|
|
869
|
+
| 事 | 口径 |
|
|
870
|
+
|---|---|
|
|
871
|
+
| 为什么要上云 | CLI 无 HTML 渲染引擎，颗粒像素权威在同合云 Hyperframes；上行的只有**颗粒 HTML 文本**，素材本体不上行 |
|
|
872
|
+
| 计量 | **唯一颗粒数 × 未命中缓存数**（`html_render_simple`，按分钟）。同一颗粒在轨上出现 N 次只烤一次 |
|
|
873
|
+
| 缓存 | `<工程目录>/.tonghe-cache/particles/<sha256>.mov`，与**客户端导出剪映**那条链**同键同落点** ⇒ 任一端烤过，另一端直接命中 |
|
|
874
|
+
| 确认 | 有未命中即先出预估（总数 / 唯一 / 未命中 / 计费分钟）并要确认；`--yes` 跳过。**全命中不弹确认**（零计费不该有摩擦） |
|
|
875
|
+
| `--json` | 有未命中且未给 `--yes` ⇒ **硬拒**（机读模式没有 stdin，不静默提交计费任务） |
|
|
876
|
+
| 逃生舱 | `--no-particles` 零计费出无颗粒版；overlay 视频轨**照常合成**（那部分纯本地） |
|
|
877
|
+
| 拒绝确认 | 零云端调用、零文件写入退出 |
|
|
878
|
+
|
|
879
|
+
`--particle-concurrency <n>`（1–8，默认 6）调颗粒云渲并发。
|
|
880
|
+
|
|
881
|
+
`--json` 结果含 `particles: {total,unique,cached,rendered,billedMinutes,skipped[]}` 与
|
|
882
|
+
`overlay: {layers,particles,hiddenSkipped,missingMaterialSkipped,particleUnavailable}`——
|
|
883
|
+
**跳过了什么都有机读通路**，不会出现「铺了 65 颗、成片一颗没有、退出码 0」。
|
|
884
|
+
|
|
885
|
+
渲完自动质检并落 `.qc.json`（`--no-qc` 跳过）；质检结论只呈现、不改渲染退出语义（硬门控走 `gtrk qc --fail-on`）。
|
|
886
|
+
|
|
887
|
+
### 其它
|
|
888
|
+
|
|
889
|
+
- `gtrk install [--api-key … -y --skill-agents codex,cursor --all-agents --copy-skills --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
|
|
890
|
+
- `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
|
|
891
|
+
- `gtrk doctor` — 体检（含 CLI 版本 / 有无新版）。
|
|
892
|
+
- `gtrk cover embed <工作台.html> [--bg-16x9 <图>] [--bg-4x3 <图>] [--bg-3x4 <图>] -o <输出.html>` — 封面工作台嵌背景图：按尺寸把图压成 JPEG（长边 16:9 ≤1280、4:3 ≤1600、3:4 ≤1400），以 base64 换进 `__BG_16_9__` / `__BG_4_3__` / `__BG_3_4__`（`file://` 下导出 PNG 要求内嵌）。`-o` 必填、可与输入同名；没给图的尺寸占位符保留并提示；工作台超过 600 KB 提示、超过 1 MB 告警。纯本地、零计费，不写中间图片。
|
|
893
|
+
- `gtrk ai-drama validate <候选分镜稿.md> [...]` — AI 情景动画分镜稿的生产端硬契约校验（与 `/gtrk-ai-drama` 随包的 `scripts/validate-storyboard.mjs` 同判据、同输出）：每个文件一行 JSON；全过退出 0、有不过退出 1、没给文件退出 2。
|
|
894
|
+
- `gtrk deps status` — 查 ffmpeg/ffprobe、渲染字体与合成烘焙浏览器的**当前来源**（`--ffmpeg-path` / `~/.gitruck` / 系统 / 缺失）、版本、授权与源码地址。
|
|
895
|
+
- `gtrk deps install [--ffmpeg] [--font] [--browser] [--force]` — 从同合云镜像安装运行时资产，**已存在则跳过**。不带开关装 ffmpeg 与字体；`--browser` 另装合成烘焙用的钉定版本 chrome-headless-shell（约 110 MB，落 `~/.gitruck/browsers`，BSD 许可，来源与源码见分发点 `SOURCE.md`），**只在显式点名时装**。
|
|
896
|
+
- **不会静默自动下载**：任何缺失路径只报错并指向本命令（包体 30–90 MB，且分发物涉及授权，须由用户/agent 显式触发）。
|
|
897
|
+
- 下载一律 https + **sha256 强校验**，校验不过即丢弃、不落地；解包调**系统 tar**（Win10+/macOS/Linux 自带），不引第三方解压依赖。
|
|
898
|
+
- 定位优先级不变：`--ffmpeg-path` → `~/.gitruck/ffmpeg` → 系统 PATH。镜像只填中间那一格，**不越过你自己装的 ffmpeg**。
|
|
899
|
+
- 字体走统一静态资源下发的字体目录（`https://api.ai-mcn.tv:9000/cloud/static/assets/fonts/catalog.json`，与客户端同一份）：`--font` 装目录里登记的字幕字体（思源黑体 CN Bold，`sourcehansanscn-bold.otf`），`--font-family <族名…>` 按 `font_id` 或中英族名装整族；每款都校 sha256 与字节数，取不到报错、不落半成品。已装按文件名归一比对（历史命名 `SourceHanSansCN-Bold.otf` 也算），`--force` 才重下并换成目录里的命名。
|
|
900
|
+
- 字体落 `~/.gitruck/fonts`（落点即缓存，不另存一份到 `~/.gitruck/cache/`），烧录时经 ffmpeg `ass` 滤镜的 `fontsdir` 供给——**不装进系统字体表、不写注册表、不要管理员权限**。
|
|
901
|
+
- 分发的 ffmpeg 为 GPLv3 构建，对应源码与二进制同处提供（见分发点 `SOURCE.md`）；**下载不附加任何使用限制**。
|
|
902
|
+
- `gtrk upgrade [--check]` — 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装。
|
|
903
|
+
- `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills 目录>]` — 单独安装/刷新 Agent Skills；缺省由通用适配器与 gtrk 补充层自动检测。
|
|
904
|
+
- `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 步按槽位取用。
|
|
905
|
+
- `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` 即可解析到它。
|
|
906
|
+
|
|
907
|
+
### 视频高光发现（内部验收）
|
|
908
|
+
|
|
909
|
+
`gtrk tool video_highlight <视频> --out <工程目录> [--no-audio] --json`：本地生成448p/4fps分析代理（缺省附单声道低码率原声，`--no-audio` 去声），只上传代理、原片不上传；返回分请求三秒候选。3秒以上、30分钟以内。候选须按制片语义复核；不可跨请求比较分数。服务失败不冒充成功，Vlog可继续Agent素材理解。尚未开放外部收费。
|