@gitruck/cli 1.3.0 → 1.3.1

package/docs/reference.en.md

@@ -302,6 +302,19 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 > ⚠️ A gap cannot be addressed with `--clip ""`: the contract lets multiple gaps share that value, so it is
 > not an address. Use `--track/--at` instead.
 
+### `gtrk matrix source-import` — Put selected video URLs into a B-roll beat
+
+When the source videos are already known, send them directly to one beat instead of running keyword search:
+
+```bash
+gtrk matrix source-import --project <project-dir> --beat B07 --url <video-url> --url <another-url> --json
+gtrk matrix source-import --project <project-dir> --beat B07 --urls links.txt --json
+```
+
+Repeat `--url`, or provide one URL per line with `--urls` (1–32 total). Supported pages are HTTPS YouTube, Vimeo, TikTok and bilibili URLs. With `--project`, the CLI only appends candidates to that beat's `struct_meta.broll`; it does not touch the timeline or run `matrix lay`. The complete task receipt is kept under `split/.source-import/`. For an agent or another automation to consume the result without a project, use `--out <result.json>` and omit `--project/--beat`.
+
+Each source becomes one low-resolution full-window preview candidate. `source-import` itself does not download the high-resolution source, change the timeline, or create an `online_broll_resolve` task. The client may still open the Trim dialog by double-clicking it, but the selectable range is strictly bounded by that candidate's source window; the pretrim is carried into the timeline when dragged. After the user places the candidate on a track and clicks “Confirm B-roll”, the client submits the selected source window to `online_broll_resolve`; the cloud downloads that high-resolution window and replaces the low-resolution timeline media. `更多外网候选` / `More external candidates` paginates keyword-search tasks only and never treats manually specified sources as another search page.
+
 ### `gtrk matrix` — B-roll retrieval + candidate track laying
 
 **No positional argument = consume the dispatch**: reads the `film_broll` queue from `split/dispatch.json` → dual-endpoint retrieval → produces the candidate list `split/broll-plan.json`, downloads preview proxies, and lays N candidate tracks in the project (open it in opencut and toggle track visibility to compare and choose). **`matrix search "<query>"` = a one-off ad-hoc search** (independent of any dispatch). **`matrix fetch <clip_id...>` = pull raw footage during the fine cut** (project-independent; see below).
@@ -437,6 +450,27 @@ Project entry points that start from **a voice-over** instead of a talking-head
 
 `project init` also takes `--canvas <WxH>` (default 1080x1920), `-o/--out`, `--reupload`, `--no-open` and `--json` with the same semantics as `oralcut`; with `--json` both commands emit a single-line result JSON on stdout (human logs go to stderr).
 
+### `gtrk project export` — export a refined project
+
+Exports an already refined `.gtrk` project (after `matrix lay` / `mg` / `audio lay`) to Jianying, Premiere XML, FCPXML or OTIO without rewriting the source project. The default output directory is `export-<YYMMDD-HHMMSS>/` under the project directory.
+
+```bash
+gtrk project export --project <project-dir>
+gtrk project export --gtrk <project-file> --formats jianying,xml --out <output-dir>
+```
+
+| Option | Purpose |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | Locate the standard `gtrk/project.gtrk`, or explicitly select a project file; use one of the two |
+| `-f, --formats <list>` | `xml`, `fcpxml`, `otio`, `jianying`, `capcut`, `gtrk`; default `jianying,xml`; legacy fine-grained names are also accepted |
+| `--jianying-draft-dir <dir>` | Jianying/CapCut draft root; when omitted, use user config and standard locations |
+| `--no-particles` | Skip MG particle pre-rendering while continuing structural export; skipped particles are recorded in the result |
+| `--particle-concurrency <n>` | Particle qtrle pre-render concurrency, 1–8, default 6 |
+
+There are two billing surfaces: structural project export is billed per task, while unique particles missing from `.tonghe-cache/particles/` are billed per minute. `gtrk project init` remains zero-credit; that does not apply to `export`. Particle cache keys and the client implementation are byte-compatible, so particles rendered by the client can be reused.
+
+Before particle rendering, the command performs HTML, path and cache preflight; a preflight failure submits no cloud task. A single particle render or download failure is recorded in `result.json` while other formats continue. With `--json`, stdout contains one result JSON line and human logs go to stderr.
+
 > **`--beat-align`**: follows the climax-anchor rule in the table above; an explicit `--climax` overrides the automatic selector. The mode calls `audio_music_analyze` and incurs its listed charge.
 
 

package/docs/reference.md

@@ -292,6 +292,19 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 >
 > ⚠️ 空档（gap）不能用 `--clip ""` 寻址：契约允许多个 gap 共享该取值，它不构成地址；用 `--track/--at`。
 
+### `gtrk matrix source-import` — 指定视频链接进入某个 B-roll beat
+
+当你已经选定视频链接，不需要关键词检索时，可以把它们直接送进指定 beat：
+
+```bash
+gtrk matrix source-import --project <工程目录> --beat B07 --url <视频链接> --url <另一个链接> --json
+gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt --json
+```
+
+`--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`。
+
+每个指定来源生成一个整段低清预览候选，`source-import` 本身不会下载高清原片、不会改时间线，也不会创建 `online_broll_resolve`。候选的时间窗就是该来源已下载预览的完整窗口。客户端对它仍可双击打开 Trim 对话框，但裁剪范围严格限制在该候选来源窗口内；预裁剪会随拖拽进入时间线。用户把候选放入轨道并点击“确认 B-roll”后，客户端才把当前源时间窗口提交给 `online_broll_resolve`，由云端下载高清窗口并置换当前低清素材。`更多外网候选` 只对关键词检索任务分页，不会把指定来源任务重复当作搜索结果。
+
 ### `gtrk matrix` — B-roll 检索 + 候选铺轨
 
 **无 positional = 派单消费**：读 `split/dispatch.json` 的 `film_broll` 队列 → 双口检索 → 产候选清单 `split/broll-plan.json` + 下载 preview 代理、在工程里平铺 N 条候选轨（opencut 打开即可用轨道小眼睛对比挑选）。**`matrix search "<query>"` = 单条 ad-hoc 检索**（不依赖派单）。**`matrix fetch <clip_id...>` = 精剪期拉原片**（脱离工程，见下）。
@@ -460,6 +473,27 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 
 `project init` 另有 `--canvas <WxH>`（默认 1080x1920）、`-o/--out`、`--reupload`、`--no-open`、`--json`，语义与 `oralcut` 一致；两命令 `--json` 恒出单行结果 JSON（人读日志走 stderr）。
 
+### `gtrk project export` — 精修工程导出
+
+把已经经过 `matrix lay` / `mg` / `audio lay` 精修的 `.gtrk` 只读导出为剪映、Premiere XML、FCPXML 或 OTIO。源工程不会被改写；缺省产物目录为工程目录下的 `export-<YYMMDD-HHMMSS>/`。
+
+```bash
+gtrk project export --project <工程目录>
+gtrk project export --gtrk <工程文件> --formats jianying,xml --out <产物目录>
+```
+
+| 参数 | 作用 |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | 自动定位标准布局的 `gtrk/project.gtrk`，或显式指定工程文件，二选一 |
+| `-f, --formats <list>` | `xml`、`fcpxml`、`otio`、`jianying`、`capcut`、`gtrk`；缺省 `jianying,xml`，也兼容旧细粒度格式名 |
+| `--jianying-draft-dir <dir>` | 剪映/CapCut 草稿根；省略时按用户配置与标准位置探测 |
+| `--no-particles` | 不预渲 MG 颗粒；结构导出仍继续，结果会记录被跳过的颗粒 |
+| `--particle-concurrency <n>` | 颗粒 qtrle 预渲并发数，1–8，默认 6 |
+
+本命令有两个计费面：工程结构导出按次计费；未命中本地 `.tonghe-cache/particles/` 的唯一颗粒按分钟计费。`gtrk project init` 仍是 0 积分，不能把这个结论套到 `export`。颗粒缓存键与客户端逐字节同构，客户端烤过的颗粒可直接复用。
+
+颗粒预渲前会先完成 HTML、路径和缓存预检；预检失败不会提交任何云任务。单颗粒渲染或下载失败会记录在 `result.json`，其余格式继续导出。`--json` 输出单行结果 JSON，人读日志走 stderr。
+
 > **`--beat-align`**：按表格中的高潮点锚定规则工作；显式 `--climax` 会覆盖自动判据。该模式会调用 `audio_music_analyze` 并产生相应计费。
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.3.0",
+	"version": "1.3.1",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",