@gitruck/cli 0.2.1 → 0.2.3

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.
Files changed (6) hide show
  1. package/AGENT.md +45 -11
  2. package/LICENSE +21 -21
  3. package/README.md +192 -154
  4. package/dist/index.js +3495 -157
  5. package/package.json +10 -4
  6. package/skills/gtrk-oralcut/SKILL.md +123 -112
package/AGENT.md CHANGED
@@ -4,8 +4,9 @@
4
4
  再把产物目录 + 三端（客户端 / 剪映 / PR）打开方式回给用户。任何 agent（Claude / Cursor / …）读完
5
5
  这一份就能驱动整条闭环；Claude 的 `/口播剪辑` skill 只是这份 playbook 的薄壳。
6
6
 
7
- > 这条 CLI 做的事：**上传毛片 → 云端智能口播剪辑（video_oral_cut）→ 拉回 gtrk/剪映/PR 三方工程
8
- > 文件 → 三端打开**。云端零改动、纯结构产物，源视频不出本地。
7
+ > 这条 CLI 做的事：**本地抽音频/720p（毛片永不上传）→ 只传抽出物 → 云端智能口播剪辑（video_oral_cut）
8
+ > → 拉回 gtrk/剪映/PR 三方工程文件 →（可选）本地 ffmpeg 渲染成片 → 三端打开**。云端零改动、纯结构产物，
9
+ > 源视频不出本地。结果/报告恒落盘 `result.json`，可按 `task_id` 秒级取回、无需重跑（见 §2.1 / §4）。
9
10
 
10
11
  ---
11
12
 
@@ -29,7 +30,7 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt] # 剪一条；剪完自动
29
30
  4. **跑 `gtrk init` 引导式配置**（对标飞书 lark-cli install，只做一次）：
30
31
  - 填 **API Key**（鉴权 Header `Authorization` 的裸值，非 Bearer）；根地址默认生产、回车即用。
31
32
  - **自动扫描剪映草稿目录**：扫到让你确认；扫不到会**自动打开一张指引图**（剪映 → 全局设置 → 草稿 →「草稿位置」）让你把路径粘过来；可留空跳过。
32
- - 配置写到 `~/.gtrk-cli/config.json`，之后所有命令免重复配置。
33
+ - 配置写到 `~/.gitruck/config.json`，之后所有命令免重复配置。
33
34
  - 环境变量 `GITRUCK_API_KEY` / `GITRUCK_API_BASE` 仍可覆盖（CI / 临时切换）。
34
35
 
35
36
  > agent 自检：没配 Key 时任何命令会明确报「缺 API Key —— 先跑 `gtrk init`」。剪映目录没配只影响剪映直开，不挡 gtrk/PR。
@@ -48,10 +49,11 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt] # 剪一条；剪完自动
48
49
  | `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
49
50
  | `--jianying-draft-dir <dir>` | 剪映草稿根目录；传路径或 `auto` | 读 `gtrk init` 配置 / 自动探测 |
50
51
  | `--lang <code>` | 语言代码（英文 `en-US`、日文 `ja-JP`…） | `zh-CN` |
51
- | `--visual-assist` | **视觉兜底**：ASR 漏字时用人脸/说话检测保护 + 重识别（剪不准时开） | 关 |
52
+ | `--visual-assist` | **视觉兜底**：改传 **720p 代理**（非原片）+ 人脸/说话检测保护漏识别段并重识别（剪不准时开） | 关 |
52
53
  | `--no-adaptive-rhythm` | 关闭自适应节奏，改用固定标点停顿表 | 自适应开 |
53
- | `--render` | 额外渲染成片视频（`outputs` 加 `video`） | 只出工程 |
54
- | `--crf <n>` / `--codec <c>` | 视频质量 14-28（默认 18，越小越清晰）/ 编码（默认 h264），配 `--render` | — |
54
+ | `--render` | 额外**本地 ffmpeg** 按 gtrk EDL 渲染成片 mp4（毛片仍不上传、云端不渲染） | 只出工程 |
55
+ | `--crf <n>` / `--codec <c>` | 本地渲染视频质量 14-28（默认 18，越小越清晰）/ 编码（默认 h264），配 `--render` | — |
56
+ | `--ffmpeg-path <dir>` | 指定 ffmpeg/ffprobe 所在目录（本地抽音频/渲染用） | `~/.gitruck/ffmpeg` → 系统 PATH |
55
57
  | `--param k=v` / `--params-json '{…}'` | **通用透传**：任意云端参数（标量可重复 / JSON 嵌套），优先级最高 | — |
56
58
  | `--reupload` | 强制重新上传，忽略本地上传缓存 | 关 |
57
59
  | `--no-open` | 完成后**不**自动打开产物目录 | **默认会自动打开** |
@@ -59,13 +61,19 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt] # 剪一条；剪完自动
59
61
  **关键行为（agent 需知道，不用解释给用户）：**
60
62
 
61
63
  - **上传缓存**：同一毛片（按 `size:mtime` 指纹）二次跑直接复用 `file_id`，跳过整段上传。缓存在
62
- `~/.gtrk-cli/upload-cache.json`。云端 file_id 失效会自动重传兜底。毛片改了但指纹意外没变 → `--reupload`。
64
+ `~/.gitruck/upload-cache.json`。云端 file_id 失效会自动重传兜底。毛片改了但指纹意外没变 → `--reupload`。
65
+ - **大文件分片断点续传**：≥256MiB 自动走分片上传（32MiB/片、3 并发、单片自动重试）。上传中断（断网/
66
+ Ctrl+C/进程崩）→ **重跑同一命令即自动续传**，只补缺片不重来（会话在 `~/.gitruck/upload-sessions.json`）。
67
+ 云端已有同内容文件（未过期）时**秒传**：零字节上传直接拿 file_id。`--reupload` 同时跳过缓存/续传会话/秒传，
68
+ 强制整传。小文件路径与输出契约完全不变。
63
69
  - **剪映草稿自动落位**：探到剪映/CapCut 草稿目录时，下载后自动把草稿拷进
64
70
  `<草稿根>/<毛片名>-video-project-<时间戳>/`（与产物目录同名、含时间戳）→ 剪映项目列表里每次剪辑
65
71
  各为独立条目、不互相覆盖。探不到会警告并提示加 `--jianying-draft-dir`（此时剪映只产 `draft_content.json`、
66
72
  缺 meta、无法直接打开）。
67
73
  - **节奏预设**：`steady` 保留更多停顿（稳）、`concise` 默认精炼、`compact` 最紧凑（压停顿最狠）。
68
74
  - **部分格式失败不致命**：CLI 如实回显云端 `errors`（某格式没出来不影响其余）。
75
+ - **本地预处理 · 只传抽出物**：跑批先本地探几何 + 抽 16k 单声道 mp3（默认）/ 压 720p 代理（`--visual-assist`）；**毛片永不上传**，只传几十 MB 抽出物。抽出物按原片 `size:mtime` 指纹缓存在 `~/.gitruck/audio-cache/`，同毛片重剪免重抽（720p 与 mp3 各缓存各的、互不覆盖）。
76
+ - **结果恒落盘 · 可按 task_id 恢复**：每次跑批恒写 `<产物目录>/result.json`（含完整 `report`，**不受 `--json` 约束**）；submit 一成功就写 `task.json`（含 `taskId`）面包屑，且产物目录**延后到首次写入才建**（提交前失败不留空壳、提交后失败留 `task.json` 可恢复）。→ stdout 丢了 / 中途崩了，报告与 `taskId` 都在盘上，用 `gtrk oralcut-result <taskId>` 秒级取回、**别重跑整条 `oralcut`**（见 §2.1）。
69
77
 
70
78
  **细节微调 —— 按用户诉求因势象形、自由组合**（上表是常用一等 flag；下面是节奏细调 + 完整取值）。你有云端全部参数，按需自由决定用哪些。**唯一要求：名字 / 取值 / 范围照文档用**（别记错拼错）；传越界云端报 `6016` 附原因、照改即可（乱传不产错误成片、只明确报错）。没特别诉求就跑默认。
71
79
 
@@ -88,6 +96,28 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt] # 剪一条；剪完自动
88
96
 
89
97
  - 优先级：`--preset` → 一等 flag → 透传（后者覆盖前者）。用户**自己点名**某参数 + 值 → 照他原样透传（CLI 底层支持任意云端参数）。**以上即 agent 需要的全部参数、本文档自足**（`gtrk oralcut --help` 也列全部 flag）；官网的原始 HTTP API 文档是给人看的，agent 不必也无法访问。
90
98
 
99
+ ### 2.1 取回命令：`gtrk oralcut-result <taskId>`（报告丢了别重跑）
100
+
101
+ 按 `task_id` 从云端取回一个**已完成**任务的报告 + 三方工程产物（可选本地渲染成片），**跳过预处理 / 上传 / 提交 / 轮询**。用在：`--json` 的 stdout 丢了、进程中途崩了、或想换台机器再拉一次产物 —— **不要重跑整条 `gtrk oralcut`**（后端 `get_task_by_id` 幂等，报告本就存着）。`taskId` 从产物目录 `task.json`、上次结果 JSON 或日志里取。
102
+
103
+ | 参数 | 作用 | 缺省 |
104
+ |---|---|---|
105
+ | `<taskId>`（位置参数） | 任务 id | 必填 |
106
+ | `-o, --out <dir>` | 产物目录 | `<当前目录>/<taskId>-video-project-<时间戳>` |
107
+ | `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
108
+ | `--jianying-draft-dir` / `--ffmpeg-path` / `--crf` / `--codec` / `--no-open` / `--json` | 同 `oralcut` | — |
109
+
110
+ - **同账号**：取结果需用**提交该任务的同一账号** API Key；异账号 / 已删任务报 `TASK_NOT_FOUND`（CLI 会提示「须用同账号 key」）。
111
+ - **报告长期可取、产物约 60 天**：报告存于任务记录、长期可取；底层产物文件约 **60 天**后被 GC，届时产物下载 404、命令会提示「已过期」并**照常落盘 / 输出报告**（报告不随文件过期）。
112
+ - **输出契约同 `oralcut --json`**：单行 `{ok,outDir,files,jianyingDraftPath,rendered,report,errors,taskId,fileId}`，恢复场景 `fileId=null`。
113
+
114
+ ```bash
115
+ # 报告丢了、按 task_id 取回（不重跑云端）
116
+ gtrk oralcut-result 88269671080189958 --json
117
+ # 顺带本地重渲成片（原毛片需仍在 gtrk 内嵌路径）
118
+ gtrk oralcut-result 88269671080189958 --render --out "D:/回收/某条"
119
+ ```
120
+
91
121
  ---
92
122
 
93
123
  ## 3. 产物结构 + 三端打开
@@ -98,7 +128,10 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt] # 剪一条；剪完自动
98
128
  ├── jianying/ → 剪映：已自动拷进剪映草稿根，剪映里直接见草稿
99
129
  │ ├── draft_content.json
100
130
  │ └── draft_meta_info.json （仅当探到/指定了剪映草稿目录才有）
101
- └── xml/premiere.xml → Premiere Pro：文件 > 导入
131
+ ├── xml/premiere.xml → Premiere Pro：文件 > 导入
132
+ ├── <毛片名>.mp4 → 成片（仅 --render；本地 ffmpeg 按 gtrk EDL 渲染，云端不产成片）
133
+ ├── result.json → 机读结果清单（含完整 report；恒写、不受 --json 约束；可 gtrk oralcut-result 复现）
134
+ └── task.json → 任务面包屑（taskId 等；submit 成功即写，供崩溃后按 task_id 恢复）
102
135
  ```
103
136
 
104
137
  **默认跑完自动打开产物目录文件夹**（`--no-open` 关）——用户常不知道文件落哪，直接帮他打开、自己挑工具。三端切点正确、同源一致（gtrk 是真超集）。
@@ -122,6 +155,7 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt] # 剪一条；剪完自动
122
155
 
123
156
  **跑完读 `report`、验证、给用户交代**（`--json` 的 stdout 那行带 `files` / `errors` / **`report`**；别只信"成功"、别谎报三端都好）：
124
157
  - **读 `report`（因势象形的另一半）**：`duration_before`→`after`（剪了多少）；`script_source`/`final_script`（无稿 `rebuilt` 时把 `final_script` 回给用户核对）；`dropped[]`（剔了哪些、`reason` retake/misread）；`coverage`（<0.6 附 `low_coverage` = 文稿与实拍严重不符）；`uncovered_script[]`（**漏读**：文稿有、实拍没找到 → 如实说，疑似漏识别则建议 `--visual-assist` 重跑）；`review_points[]`（建议复核处）；开了 visual_assist 还有 `suspect_omissions` / `stt_recovered` / `visual_assist_degraded`。**据此因势象形**：覆盖率低 / 漏读多 → 开 `--visual-assist` 或核对文稿重跑；节奏不满意 → 调 `--preset` / 散参数重跑（同毛片可反复剪对比）。
158
+ - **报告也在盘上、丢了能取回**：同一份 `report` 恒写在 `<产物目录>/result.json`（不必依赖 stdout）。万一 stdout 没接住或进程崩了 → 直接读 `result.json`，或 `gtrk oralcut-result <taskId> --json` 按 task_id 重新取回，**不要重跑 `oralcut`**（见 §2.1）。
125
159
  - 确认产物目录在、`gtrk/project.gtrk` 非空（>0 字节）；要剪映就确认剪映草稿根里有**同名工程目录** + `draft_meta_info.json`。
126
160
  - 云端 `errors` 非空 → 如实告知哪个格式失败、原因。
127
161
  - 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`），并**据 `report` 给一句交代**（剪了多久 → 多久、去掉了什么、有无漏读需复核）。
@@ -163,12 +197,12 @@ gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":
163
197
  | 云端 errors 含某格式 | 该格式单独失败、其余可用；把 errors 原文回给用户/反馈维护方 |
164
198
  | 同毛片改了内容但产物像旧的 | 指纹意外没变 → 加 `--reupload` 强制重传 |
165
199
  | 任务很久不动 | 轮询有 30min 墙钟上限；超时 CLI 会报，稍后重试或查云端任务 |
200
+ | 结果 JSON / 报告丢了（stdout 没接住、进程崩了） | 别重跑 → 读产物目录 `result.json`，或 `gtrk oralcut-result <taskId> --json` 按 task_id 取回 |
201
+ | 想换机器再拉产物 / 补渲成片 | `gtrk oralcut-result <taskId> [--out <目录>] [--render]`（须同账号 key；产物约 60 天有效，过期仍可取报告） |
166
202
 
167
203
  ---
168
204
 
169
205
  ## 7. 扩展（给改 CLI 的 agent）
170
206
 
171
207
  新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
172
- 云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`）；上传一律走
173
- `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存）。规划中：`render`（云渲）、`struct`（已有 gtrk →
174
- 三方工程）、`matrix`（B-roll 检索）。
208
+ 云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`；单发取结果 `getTaskResult`、`pollTask` 复用之）；上传一律走 `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存；≥256MiB 自动分片断点续传，见 `src/lib/chunk-upload.ts`）。本地预处理（探几何 / 抽音频 / 压 720p）在 `src/lib/media.ts`；本地渲染（gtrk EDL → ffmpeg filter_complex）在 `src/lib/render.ts`；三方产物落地 + `result.json` 两段写在 `src/lib/materialize.ts`（`oralcut` 与 `oralcut-result` 共用）。已上线：`oralcut`（云剪）、`oralcut-result`（按 task_id 取回）、`render`（本地渲染 gtrk）。规划中：`struct`（已有 gtrk → 三方工程）、`matrix`（B-roll 检索）。
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 同合云 (Gitruck)
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 同合云 (Gitruck)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,154 +1,192 @@
1
- # gtrk-cli
2
-
3
- > 同合云成片流水线 CLI —— **agent 驱动云端任务、产物拉回本地、三方工程文件（客户端 / 剪映 / PR）互通**。
4
- >
5
- > 一条命令，把口播毛片变成可二次精修的剪辑工程。云端做重活，本地只装配，源视频不出本地。
6
-
7
- ---
8
-
9
- ## 为什么用 gtrk-cli
10
-
11
- - **一条命令出三方工程**：上传口播毛片 → 云端智能剪辑（剪废话 / 重复 / 长停顿）→ 拉回**客户端（gtrk）+ 剪映 + PR/FCP** 三方工程文件 → 自动打开产物目录。
12
- - **云端做重活、本地只装配**：识别、剪辑、对齐都在云端；本地只拿结果，**源视频不出本地**（路径写进工程、本地打开直接认素材）。
13
- - **为 agent 而生**：配套 skill `/gtrk-oralcut`，在 Claude Code 等工具里一句「帮我剪个口播」就能发起，CLI 是手、agent 是脑。
14
- - **专业可扩展**：单 binary + 子命令（对标飞书 `lark-cli`），后续长出 `render` / `struct` / `matrix` 等命令。
15
-
16
- ## 功能
17
-
18
- | | 命令 | 做什么 |
19
- |---|---|---|
20
- | 🎬 | `gtrk oralcut <毛片>` | 智能口播剪辑闭环：一次出 gtrk + 剪映 + PR 三方工程，自动打开 |
21
- | ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
22
- | 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
23
- | 🤖 | `gtrk skills install` | 把 `/gtrk-oralcut` skill 装进 Claude Code |
24
- | 🚧 | `render` / `struct` / `matrix` | （规划中）云渲染 / 已有 gtrk 转三方工程 / B-roll 检索 |
25
-
26
- ---
27
-
28
- ## 获取 API Key
29
-
30
- CLI 要调用同合云云端能力，需先拿一个 API Key（形如 `gc_xxxxxxxx`）：
31
-
32
- 1. 打开官网 **[cloud.ai-mcn.tv](https://cloud.ai-mcn.tv)** 并登录 —— **登录即开通**、自带免费测试额度、零门槛。
33
- 2. 进入 **[控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)**，在「API 密钥 / 密钥管理」处生成并复制你的 Key。
34
- 3. 下一步 `gtrk install` 会让你把它粘进去（一次配好、本地长期复用）。
35
-
36
- > 快速开始文档：[cloud.ai-mcn.tv/zh-CN/docs/quick-start](https://cloud.ai-mcn.tv/zh-CN/docs/quick-start) · 对接咨询：business@migotimes.com
37
-
38
- ## 安装 & 快速上手
39
-
40
- 需要 Node.js ≥ 20.6（`node -v` 查看）。
41
-
42
- ```bash
43
- # 1) 一条命令装全：命令行 gtrk + /gtrk-oralcut skill + 配置（填 API Key、自动扫剪映目录）
44
- npm i -g @gitruck/cli@latest && gtrk install
45
- # 或免全局安装直接用：npx @gitruck/cli@latest install
46
-
47
- # 2) 剪一条（剪完自动打开产物目录）
48
- gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
49
- ```
50
-
51
- > 只想配置、不装 skill：用 `gtrk init`。本地开发：`cd gtrk-cli && bun install && bun run src/index.ts <命令>`。
52
-
53
- 产物目录形如 `<毛片名>-video-project-<YYMMDD-HHMMSS>/`，内含 `gtrk/`、`jianying/`、`xml/` 三端工程。
54
-
55
- ## 给 AI Agent 用
56
-
57
- `gtrk install` 已经把 `/gtrk-oralcut` skill 装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
58
-
59
- 然后在 Claude Code 里直接说「**帮我把这条口播剪一版**」或打 `/gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
60
-
61
- ### Skills
62
-
63
- | Skill | 触发 | 做什么 |
64
- |---|---|---|
65
- | `/gtrk-oralcut` | 斜杠，或「剪口播 / 智能剪辑 / 去掉废话停顿 / 出剪映草稿」 | 驱动 `oralcut` 闭环：云端剪辑 → 拉回三方工程 → 验证 → 回报三端打开方式 |
66
-
67
- ---
68
-
69
- ## 配置
70
-
71
- `gtrk init` 把配置写到 `~/.gtrk-cli/config.json`。读取优先级：**环境变量 / `.env` > `init` 持久配置 > 默认根地址**。
72
-
73
- | 项 | 来源 | 说明 |
74
- |---|---|---|
75
- | `GITRUCK_API_KEY` | env / init | 鉴权 Header `Authorization` 的**裸值**（非 Bearer） |
76
- | `GITRUCK_API_BASE` | env / init | API 根地址，默认 `https://api.ai-mcn.tv:10000` |
77
- | 剪映草稿目录 | init / 自动探测 / `--jianying-draft-dir` | 决定剪映草稿落哪、能否直接打开 |
78
-
79
- 非交互配置（脚本 / CI）：
80
-
81
- ```bash
82
- gtrk init --api-key <KEY> --jianying-draft-dir auto -y
83
- ```
84
-
85
- 随时 `gtrk doctor` 自检：
86
-
87
- ```
88
- ✅ API Key：已配
89
- ✅ 云端连通：可达（HTTP 404）
90
- ✅ 剪映草稿目录：C:\Users\…\com.lveditor.draft
91
- ```
92
-
93
- ---
94
-
95
- ## 命令参考
96
-
97
- ### `gtrk oralcut <毛片>`
98
-
99
- | 参数 | 作用 | 缺省 |
100
- |---|---|---|
101
- | `-s, --script <file>` | 文字稿 txt（有稿按稿剪、更准） | 探毛片同名 `.txt`；无则无稿智能重建 |
102
- | `-p, --preset <p>` | 节奏 `steady`\|`concise`\|`compact`（松→紧） | `concise` |
103
- | `-o, --out <dir>` | 自定义产物目录 | `<毛片名>-video-project-<时间戳>` |
104
- | `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
105
- | `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
106
- | `--reupload` | 强制重传，忽略上传缓存 | 关 |
107
- | `--no-open` | 完成后不自动打开产物目录 | **默认自动打开** |
108
- | `--json` | 机读：stdout 只输出结果 JSON（给 agent / 脚本） | 关 |
109
-
110
- `--json` 输出（成功时 stdout 单行）：`{ ok, outDir, files:{gtrk,jianying,xml}, jianyingDraftPath, report, errors, taskId, fileId }`；命令失败则进程非 0 退出、报错走 stderr、stdout 无 JSON。
111
-
112
- ### 其它
113
-
114
- - `gtrk install [--api-key … -y --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
115
- - `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
116
- - `gtrk doctor` — 体检。
117
- - `gtrk skills install [--dir <skills 目录>]` — 单独安装 agent skill。
118
-
119
- ---
120
-
121
- ## 工作原理
122
-
123
- ```
124
- 本地 gtrk CLI 同合云 本地三端
125
- ───────────── ───────────── ─────────────
126
- 毛片 ──上传(指纹缓存免重传)──▶ video_oral_cut 智能剪辑 ──产物──▶ 客户端 gtrk/project.gtrk
127
- (一次出 gtrk/剪映/xml) 剪映 自动落草稿目录
128
- 源路径写进 gtrk materials.path PR/FCP 导入 premiere.xml
129
- ```
130
-
131
- - **gtrk** 是 timeline 的真超集 + HTML 颗粒，是同合云的统一工程契约；三端从同一份 gtrk 派生、切点一致。
132
- - 云端**零改动**全用现成 `video_oral_cut`；CLI 只做编排（上传 / 提交 / 轮询 / 拉回 / 落位 / 打开）。
133
-
134
- ## 注意
135
-
136
- - 剪映 / CapCut 草稿需 `draft_content.json` + `draft_meta_info.json` **成对**才被软件识别——要么 `gtrk init` 配好草稿目录、要么 `--jianying-draft-dir` 指定，否则只产 content、需手动导入。
137
- - 多台机器盘符不同时，配置走 `~/.gtrk-cli/`（用户级），产物默认落毛片同目录。
138
- - 节奏预设强度以云端为准；`--preset` 只选预设、不改源裁剪。
139
-
140
- ---
141
-
142
- ## 结构
143
-
144
- ```
145
- gtrk-cli/
146
- ├── src/index.ts # commander 入口
147
- ├── src/commands/ # 子命令：init / oralcut / doctor / skills
148
- ├── src/lib/ # cloud / config / user-config / jianying / open / upload-cache / log
149
- ├── skills/gtrk-oralcut/ # 打包的 agent skill（skills install 装它）
150
- ├── assets/ # 剪映草稿目录指引图
151
- └── AGENT.md # 可移植 agent playbook（skill 底座）
152
- ```
153
-
154
- 新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
1
+ # gtrk-cli
2
+
3
+ > 同合云成片流水线 CLI —— **agent 驱动云端任务、产物拉回本地、三方工程文件（客户端 / 剪映 / PR）互通**。
4
+ >
5
+ > 一条命令，把口播毛片变成可二次精修的剪辑工程。云端做重活，本地只装配，源视频不出本地。
6
+
7
+ ---
8
+
9
+ ## 为什么用 gtrk-cli
10
+
11
+ - **一条命令出三方工程**：上传口播毛片 → 云端智能剪辑（剪废话 / 重复 / 长停顿）→ 拉回**客户端（gtrk）+ 剪映 + PR/FCP** 三方工程文件 → 自动打开产物目录。
12
+ - **云端做重活、本地只装配**：识别、剪辑、对齐都在云端；本地只拿结果，**源视频不出本地**（路径写进工程、本地打开直接认素材）。
13
+ - **为 agent 而生**：配套 skill `/gtrk-oralcut`，在 Claude Code 等工具里一句「帮我剪个口播」就能发起，CLI 是手、agent 是脑。
14
+ - **专业可扩展**：单 binary + 子命令（对标飞书 `lark-cli`），后续长出 `render` / `struct` / `matrix` 等命令。
15
+
16
+ ## 功能
17
+
18
+ | | 命令 | 做什么 |
19
+ |---|---|---|
20
+ | 🎬 | `gtrk oralcut <毛片>` | 智能口播剪辑闭环：一次出 gtrk + 剪映 + PR 三方工程，自动打开 |
21
+ | ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
22
+ | 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
23
+ | 🤖 | `gtrk skills install` | 把 `/gtrk-oralcut` skill 装进 Claude Code |
24
+ | ⬆️ | `gtrk upgrade` | 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装 |
25
+ | 🚧 | `render` / `struct` / `matrix` | （规划中）云渲染 / 已有 gtrk 转三方工程 / B-roll 检索 |
26
+
27
+ ---
28
+
29
+ ## 获取 API Key
30
+
31
+ CLI 要调用同合云云端能力，需先拿一个 API Key（形如 `gc_xxxxxxxx`）：
32
+
33
+ 1. 打开官网 **[cloud.ai-mcn.tv](https://cloud.ai-mcn.tv)** 并登录 —— **登录即开通**、自带免费测试额度、零门槛。
34
+ 2. 进入 **[控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)**，在「API 密钥 / 密钥管理」处生成并复制你的 Key。
35
+ 3. 下一步 `gtrk install` 会让你把它粘进去（一次配好、本地长期复用）。
36
+
37
+ > 快速开始文档：[cloud.ai-mcn.tv/zh-CN/docs/quick-start](https://cloud.ai-mcn.tv/zh-CN/docs/quick-start) · 对接咨询：business@migotimes.com
38
+
39
+ ## 安装 & 快速上手
40
+
41
+ 需要 Node.js ≥ 20.6（`node -v` 查看）。
42
+
43
+ ```bash
44
+ # 1) 一条命令装全：命令行 gtrk + /gtrk-oralcut skill + 配置（填 API Key、自动扫剪映目录）
45
+ npm i -g @gitruck/cli@latest && gtrk install
46
+ # 或免全局安装直接用：npx @gitruck/cli@latest install
47
+
48
+ # 2) 剪一条（剪完自动打开产物目录）
49
+ gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
50
+ ```
51
+
52
+ > 只想配置、不装 skill：用 `gtrk init`。本地开发：`cd gtrk-cli && bun install && bun run src/index.ts <命令>`。
53
+
54
+ 产物目录形如 `<毛片名>-video-project-<YYMMDD-HHMMSS>/`，内含 `gtrk/`、`jianying/`、`xml/` 三端工程。
55
+
56
+ > **重复装不会重复填配置**：`gtrk install` / `gtrk init` 检测到已配好就默认保留、只刷新 skill；想改配置加 `--reconfigure`（Key / 剪映目录也都能回车沿用）。
57
+
58
+ ## 升级
59
+
60
+ **CLI + skill**（配置原样保留）：
61
+
62
+ ```bash
63
+ gtrk upgrade # 有新版则升到最新 + 刷新 skill
64
+ gtrk upgrade --check # 只看有没有新版，不动手
65
+ ```
66
+
67
+ > 用 `npx` 的（没全局装）本就每次拉最新：`npx @gitruck/cli@latest install`。`gtrk doctor` 也会顺带提示「有新版可升级」。
68
+
69
+ **桌面客户端**：重跑一键安装脚本即覆盖装最新版（per-user、免管理员、配置不动）：
70
+
71
+ ```powershell
72
+ irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex
73
+ ```
74
+
75
+ ## 给 AI Agent 用
76
+
77
+ `gtrk install` 已经把 `/gtrk-oralcut` skill 装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
78
+
79
+ 然后在 Claude Code 里直接说「**帮我把这条口播剪一版**」或打 `/gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
80
+
81
+ ### Skills
82
+
83
+ | Skill | 触发 | 做什么 |
84
+ |---|---|---|
85
+ | `/gtrk-oralcut` | 斜杠，或「剪口播 / 智能剪辑 / 去掉废话停顿 / 出剪映草稿」 | 驱动 `oralcut` 闭环：云端剪辑 → 拉回三方工程 → 验证 → 回报三端打开方式 |
86
+
87
+ ---
88
+
89
+ ## 配置
90
+
91
+ `gtrk init` 把配置写到 `~/.gtrk-cli/config.json`。读取优先级：**环境变量 / `.env` > `init` 持久配置 > 默认根地址**。
92
+
93
+ | 项 | 来源 | 说明 |
94
+ |---|---|---|
95
+ | `GITRUCK_API_KEY` | env / init | 鉴权 Header `Authorization` 的**裸值**（非 Bearer） |
96
+ | `GITRUCK_API_BASE` | env / init | API 根地址，默认 `https://api.ai-mcn.tv:10000` |
97
+ | 剪映草稿目录 | init / 自动探测 / `--jianying-draft-dir` | 决定剪映草稿落哪、能否直接打开 |
98
+
99
+ 非交互配置（脚本 / CI）：
100
+
101
+ ```bash
102
+ gtrk init --api-key <KEY> --jianying-draft-dir auto -y
103
+ ```
104
+
105
+ 随时 `gtrk doctor` 自检：
106
+
107
+ ```
108
+ ✅ 运行时：node v24.x
109
+ ✅ CLI 版本：v0.3.0（已是最新）
110
+ ✅ API Key：已配（gc_xxx…）
111
+ ✅ 云端连通 + 鉴权：可达，鉴权通过
112
+ ✅ 剪映草稿目录：C:\Users\…\com.lveditor.draft
113
+ ```
114
+
115
+ ---
116
+
117
+ ## 命令参考
118
+
119
+ ### `gtrk oralcut <毛片>`
120
+
121
+ | 参数 | 作用 | 缺省 |
122
+ |---|---|---|
123
+ | `-s, --script <file>` | 文字稿 txt（有稿按稿剪、更准） | 探毛片同名 `.txt`；无则无稿智能重建 |
124
+ | `-p, --preset <p>` | 节奏 `steady`\|`concise`\|`compact`（松→紧） | `concise` |
125
+ | `-o, --out <dir>` | 自定义产物目录 | `<毛片名>-video-project-<时间戳>` |
126
+ | `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
127
+ | `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
128
+ | `--reupload` | 强制重传，忽略上传缓存 | 关 |
129
+ | `--no-open` | 完成后不自动打开产物目录 | **默认自动打开** |
130
+ | `--json` | 机读：stdout 只输出结果 JSON（给 agent / 脚本） | 关 |
131
+
132
+ `--json` 输出（成功时 stdout 单行）：`{ ok, outDir, files:{gtrk,jianying,xml}, jianyingDraftPath, rendered, report, errors, taskId, fileId }`；命令失败则进程非 0 退出、报错走 stderr、stdout 无 JSON。
133
+
134
+ > 每次跑批都会把这份结果**恒写一份 `result.json` 到产物目录**（不受 `--json` 约束）；提交成功后还会落一份 `task.json` 面包屑。即便 stdout 丢了、或中途崩了，报告与 `taskId` 都在盘上，可用下面的 `oralcut-result` 秒级取回、无需重跑云端。
135
+
136
+ ### `gtrk oralcut-result <taskId>`
137
+
138
+ 按 `task_id` 从云端取回一个**已完成**任务的报告与三方工程产物（可选本地渲染成片），**跳过预处理 / 上传 / 提交 / 轮询**——报告丢了、或想换台机器再拉一次产物时用它，不重跑云端。
139
+
140
+ | 参数 | 作用 | 缺省 |
141
+ |---|---|---|
142
+ | `-o, --out <dir>` | 产物目录 | `<当前目录>/<taskId>-video-project-<时间戳>` |
143
+ | `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
144
+ | `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
145
+ | `--no-open` / `--json` | 同 `oralcut` | — |
146
+
147
+ > 取结果需用**提交该任务的同一账号** API Key（异账号 / 已删任务报 `TASK_NOT_FOUND`）。报告存于任务记录、长期可取；底层产物文件约 **60 天**后被清理，届时仍能取回报告、但产物下载会 404（命令会提示、并照常落盘报告）。
148
+
149
+ ### 其它
150
+
151
+ - `gtrk install [--api-key … -y --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
152
+ - `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
153
+ - `gtrk doctor` — 体检（含 CLI 版本 / 有无新版）。
154
+ - `gtrk upgrade [--check]` — 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装。
155
+ - `gtrk skills install [--dir <skills 目录>]` — 单独安装 agent skill。
156
+
157
+ ---
158
+
159
+ ## 工作原理
160
+
161
+ ```
162
+ 本地 gtrk CLI 同合云 本地三端
163
+ ───────────── ───────────── ─────────────
164
+ 毛片 ──上传(指纹缓存免重传)──▶ video_oral_cut 智能剪辑 ──产物──▶ 客户端 gtrk/project.gtrk
165
+ (一次出 gtrk/剪映/xml) 剪映 自动落草稿目录
166
+ 源路径写进 gtrk materials.path PR/FCP 导入 premiere.xml
167
+ ```
168
+
169
+ - **gtrk** 是 timeline 的真超集 + HTML 颗粒，是同合云的统一工程契约；三端从同一份 gtrk 派生、切点一致。
170
+ - 云端**零改动**全用现成 `video_oral_cut`；CLI 只做编排（上传 / 提交 / 轮询 / 拉回 / 落位 / 打开）。
171
+
172
+ ## 注意
173
+
174
+ - 剪映 / CapCut 草稿需 `draft_content.json` + `draft_meta_info.json` **成对**才被软件识别——要么 `gtrk init` 配好草稿目录、要么 `--jianying-draft-dir` 指定，否则只产 content、需手动导入。
175
+ - 多台机器盘符不同时，配置走 `~/.gtrk-cli/`（用户级），产物默认落毛片同目录。
176
+ - 节奏预设强度以云端为准；`--preset` 只选预设、不改源裁剪。
177
+
178
+ ---
179
+
180
+ ## 结构
181
+
182
+ ```
183
+ gtrk-cli/
184
+ ├── src/index.ts # commander 入口
185
+ ├── src/commands/ # 子命令：install / init / oralcut / doctor / upgrade / skills
186
+ ├── src/lib/ # cloud / config / user-config / jianying / open / upload-cache / log
187
+ ├── skills/gtrk-oralcut/ # 打包的 agent skill（skills install 装它）
188
+ ├── assets/ # 剪映草稿目录指引图
189
+ └── AGENT.md # 可移植 agent playbook（skill 底座）
190
+ ```
191
+
192
+ 新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。