@gitruck/cli 0.1.0

package/AGENT.md

@@ -0,0 +1,137 @@
+# gtrk-cli · Agent Playbook
+
+给 **agent** 看的操作手册：把用户「想剪一条口播」的自然语言需求，落成对 `gtrk` CLI 的一次调用，
+再把产物目录 + 三端（客户端 / 剪映 / PR）打开方式回给用户。任何 agent（Claude / Cursor / …）读完
+这一份就能驱动整条闭环；Claude 的 `/口播剪辑` skill 只是这份 playbook 的薄壳。
+
+> 这条 CLI 做的事：**上传毛片 → 云端智能口播剪辑（video_oral_cut）→ 拉回 gtrk/剪映/PR 三方工程
+> 文件 → 三端打开**。云端零改动、纯结构产物，源视频不出本地。
+
+---
+
+## 0. 一句话流程
+
+```
+gtrk init                                    # 一次性配置（API Key + 剪映目录）
+gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动打开产物目录
+```
+
+跑完得到一个产物目录：`<毛片同目录>/<毛片名>-video-project-<YYMMDD-HHMMSS>/`，里面按格式分子目录，
+三端各自打开即可。
+
+---
+
+## 1. 一次性准备（只做一次）
+
+1. **装 bun**（运行时）：https://bun.sh 。
+2. **拿到 CLI**：进入 `gtrk-cli/` 仓库，`bun install`。
+3. **调用方式**（二选一）：仓库内 `bun run src/index.ts <命令> …`；或 `bun link` 后全局 `gtrk <命令> …`（本文档统一写 `gtrk`）。
+4. **跑 `gtrk init` 引导式配置**（对标飞书 lark-cli install，只做一次）：
+   - 填 **API Key**（鉴权 Header `Authorization` 的裸值，非 Bearer）；根地址默认生产、回车即用。
+   - **自动扫描剪映草稿目录**：扫到让你确认；扫不到会**自动打开一张指引图**（剪映 → 全局设置 → 草稿 →「草稿位置」）让你把路径粘过来；可留空跳过。
+   - 配置写到 `~/.gtrk-cli/config.json`，之后所有命令免重复配置。
+   - 环境变量 `GITRUCK_API_KEY` / `GITRUCK_API_BASE` 仍可覆盖（CI / 临时切换）。
+
+> agent 自检：没配 Key 时任何命令会明确报「缺 API Key —— 先跑 `gtrk init`」。剪映目录没配只影响剪映直开，不挡 gtrk/PR。
+> `init` 是**人手一次性**交互配置（会弹提示）；agent 日常只跑非交互的 `oralcut`。
+
+---
+
+## 2. 核心命令：`gtrk oralcut <毛片>`
+
+| 参数 | 作用 | 缺省 |
+|---|---|---|
+| `<毛片>`（位置参数） | 本地口播原视频路径 | 必填 |
+| `-s, --script <file>` | 文字稿 txt 路径（**有稿**：按稿对齐裁剪） | 不传 = **无稿智能重建** |
+| `-p, --preset <preset>` | 节奏预设 `steady`\|`concise`\|`compact`（松→紧） | `concise` |
+| `-o, --out <dir>` | 自定义产物目录 | `<毛片同目录>/<毛片名>-video-project-<YYMMDD-HHMMSS>` |
+| `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
+| `--jianying-draft-dir <dir>` | 剪映草稿根目录；传路径或 `auto` | 读 `gtrk init` 配置 / 自动探测 |
+| `--reupload` | 强制重新上传，忽略本地上传缓存 | 关 |
+| `--no-open` | 完成后**不**自动打开产物目录 | **默认会自动打开** |
+
+**关键行为（agent 需知道，不用解释给用户）：**
+
+- **上传缓存**：同一毛片（按 `size:mtime` 指纹）二次跑直接复用 `file_id`，跳过整段上传。缓存在
+  `~/.gtrk-cli/upload-cache.json`。云端 file_id 失效会自动重传兜底。毛片改了但指纹意外没变 → `--reupload`。
+- **剪映草稿自动落位**：探到剪映/CapCut 草稿目录时，下载后自动把草稿拷进
+  `<草稿根>/<毛片名>-video-project-<时间戳>/`（与产物目录同名、含时间戳）→ 剪映项目列表里每次剪辑
+  各为独立条目、不互相覆盖。探不到会警告并提示加 `--jianying-draft-dir`（此时剪映只产 `draft_content.json`、
+  缺 meta、无法直接打开）。
+- **节奏预设**：`steady` 保留更多停顿（稳）、`concise` 默认精炼、`compact` 最紧凑（压停顿最狠）。
+- **部分格式失败不致命**：CLI 如实回显云端 `errors`（某格式没出来不影响其余）。
+
+---
+
+## 3. 产物结构 + 三端打开
+
+```
+<毛片名>-video-project-<YYMMDD-HHMMSS>/
+├── gtrk/project.gtrk        → 客户端（opencut-rewrite）：「打开工程」选它
+├── jianying/                → 剪映：已自动拷进剪映草稿根，剪映里直接见草稿
+│   ├── draft_content.json
+│   └── draft_meta_info.json （仅当探到/指定了剪映草稿目录才有）
+└── xml/premiere.xml         → Premiere Pro：文件 > 导入
+```
+
+**默认跑完自动打开产物目录文件夹**（`--no-open` 关）——用户常不知道文件落哪，直接帮他打开、自己挑工具。三端切点正确、同源一致（gtrk 是真超集）。
+
+---
+
+## 4. Agent 决策清单（自然语言 → 参数）
+
+把用户的话映射到一次调用，按这几条判断：
+
+1. **毛片路径**：用户给的视频文件绝对路径 → 位置参数。缺则先问。
+2. **有稿 / 无稿**：
+   - 用户给了文字稿/逐字稿文件 → `--script <该文件>`（按稿剪，最准）。
+   - 没稿 → 不传 `--script`，走云端无稿智能重建（CLI 默认）。
+3. **节奏**：用户说「快/紧凑/卡点狠」→ `--preset compact`；「稳一点/别删太多停顿」→ `steady`；
+   没特别要求 → 默认 `concise`，不用传。
+4. **要不要自动打开**：默认就开（用户常不知道文件去哪了，别让他找）。只有明确「别打开 / 批处理」才加 `--no-open`。
+5. **剪映装在非标准位置 / 多版本**：若用户没跑过 `gtrk init` 或探测失败，问剪映草稿根目录、传 `--jianying-draft-dir`（或让他先 `gtrk init`）。
+6. **只要某一两端**：用户只要客户端 → `--formats gtrk`；只要剪映 → `--formats jianying`；默认三端全给。
+
+**跑完做一层验证**（别只信"成功"二字、别谎报三端都好）：
+- 确认产物目录在、`gtrk/project.gtrk` 非空（>0 字节）；要剪映就确认剪映草稿根里有**同名工程目录** + `draft_meta_info.json`。
+- 云端 `errors` 非空 → 如实告知哪个格式失败、原因；必要时按用户意图微调重跑（换 `--preset`、补 `--jianying-draft-dir`、`--reupload`）。
+- 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`）。
+
+---
+
+## 5. 典型调用
+
+```bash
+# 有稿 + 剪完就看（最常见）
+gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt" --open
+
+# 无稿、要最紧凑节奏
+gtrk oralcut "D:/素材/某条.mp4" --preset compact
+
+# 只要客户端工程，不碰剪映/PR
+gtrk oralcut "D:/素材/某条.mp4" --formats gtrk
+
+# 剪映装在非标准盘符，手动指目录
+gtrk oralcut "D:/素材/某条.mp4" --jianying-draft-dir "F:/JianyingPro/User Data/Projects/com.lveditor.draft"
+```
+
+---
+
+## 6. 排错
+
+| 现象 | 处置 |
+|---|---|
+| `缺 API Key —— 先跑 gtrk init` | 没配过 → 跑 `gtrk init`（或设环境变量 `GITRUCK_API_KEY`） |
+| 剪映警告「没找到草稿目录」 | 剪映/CapCut 没装在标准位置 → 加 `--jianying-draft-dir <你的草稿根>` 重跑 |
+| 云端 errors 含某格式 | 该格式单独失败、其余可用；把 errors 原文回给用户/反馈维护方 |
+| 同毛片改了内容但产物像旧的 | 指纹意外没变 → 加 `--reupload` 强制重传 |
+| 任务很久不动 | 轮询有 30min 墙钟上限；超时 CLI 会报，稍后重试或查云端任务 |
+
+---
+
+## 7. 扩展（给改 CLI 的 agent）
+
+新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
+云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`）；上传一律走
+`src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存）。规划中：`render`（云渲）、`struct`（已有 gtrk →
+三方工程）、`matrix`（B-roll 检索）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 同合云 (Gitruck)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# gtrk-cli
+
+> 同合云成片流水线 CLI —— **agent 驱动云端任务、产物拉回本地、三方工程文件（客户端 / 剪映 / PR）互通**。
+>
+> 一条命令，把口播毛片变成可二次精修的剪辑工程。云端做重活，本地只装配，源视频不出本地。
+
+---
+
+## 为什么用 gtrk-cli
+
+- **一条命令出三方工程**：上传口播毛片 → 云端智能剪辑（剪废话 / 重复 / 长停顿）→ 拉回**客户端（gtrk）+ 剪映 + PR/FCP** 三方工程文件 → 自动打开产物目录。
+- **云端做重活、本地只装配**：识别、剪辑、对齐都在云端；本地只拿结果，**源视频不出本地**（路径写进工程、本地打开直接认素材）。
+- **为 agent 而生**：配套 skill `/gtrk-oralcut`，在 Claude Code 等工具里一句「帮我剪个口播」就能发起，CLI 是手、agent 是脑。
+- **专业可扩展**：单 binary + 子命令（对标飞书 `lark-cli`），后续长出 `render` / `struct` / `matrix` 等命令。
+
+## 功能
+
+| | 命令 | 做什么 |
+|---|---|---|
+| 🎬 | `gtrk oralcut <毛片>` | 智能口播剪辑闭环：一次出 gtrk + 剪映 + PR 三方工程，自动打开 |
+| ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
+| 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
+| 🤖 | `gtrk skills install` | 把 `/gtrk-oralcut` skill 装进 Claude Code |
+| 🚧 | `render` / `struct` / `matrix` | （规划中）云渲染 / 已有 gtrk 转三方工程 / B-roll 检索 |
+
+---
+
+## 安装 & 快速上手
+
+需要 Node.js ≥ 20.6（`node -v` 查看）。
+
+```bash
+# 1) 安装（全局命令 gtrk）
+npm i -g @gitruck/cli
+#   或免安装直接用：npx @gitruck/cli <命令>
+
+# 2) 一次性配置（填 API Key，自动扫剪映草稿目录）
+gtrk init
+
+# 3) 剪一条（剪完自动打开产物目录）
+gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
+```
+
+> 本地开发：`cd gtrk-cli && bun install && bun run src/index.ts <命令>`。
+
+产物目录形如 `<毛片名>-video-project-<YYMMDD-HHMMSS>/`，内含 `gtrk/`、`jianying/`、`xml/` 三端工程。
+
+## 给 AI Agent 用
+
+```bash
+gtrk skills install      # 把 /gtrk-oralcut 装进 ~/.claude/skills
+```
+
+然后在 Claude Code 里直接说「**帮我把这条口播剪一版**」或打 `/gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
+
+### Skills
+
+| Skill | 触发 | 做什么 |
+|---|---|---|
+| `/gtrk-oralcut` | 斜杠，或「剪口播 / 智能剪辑 / 去掉废话停顿 / 出剪映草稿」 | 驱动 `oralcut` 闭环：云端剪辑 → 拉回三方工程 → 验证 → 回报三端打开方式 |
+
+---
+
+## 配置
+
+`gtrk init` 把配置写到 `~/.gtrk-cli/config.json`。读取优先级：**环境变量 / `.env` > `init` 持久配置 > 默认根地址**。
+
+| 项 | 来源 | 说明 |
+|---|---|---|
+| `GITRUCK_API_KEY` | env / init | 鉴权 Header `Authorization` 的**裸值**（非 Bearer） |
+| `GITRUCK_API_BASE` | env / init | API 根地址，默认 `https://api.ai-mcn.tv:10000` |
+| 剪映草稿目录 | init / 自动探测 / `--jianying-draft-dir` | 决定剪映草稿落哪、能否直接打开 |
+
+非交互配置（脚本 / CI）：
+
+```bash
+gtrk init --api-key <KEY> --jianying-draft-dir auto -y
+```
+
+随时 `gtrk doctor` 自检：
+
+```
+✅ API Key：已配
+✅ 云端连通：可达（HTTP 404）
+✅ 剪映草稿目录：C:\Users\…\com.lveditor.draft
+```
+
+---
+
+## 命令参考
+
+### `gtrk oralcut <毛片>`
+
+| 参数 | 作用 | 缺省 |
+|---|---|---|
+| `-s, --script <file>` | 文字稿 txt（有稿按稿剪、更准） | 探毛片同名 `.txt`；无则无稿智能重建 |
+| `-p, --preset <p>` | 节奏 `steady`\|`concise`\|`compact`（松→紧） | `concise` |
+| `-o, --out <dir>` | 自定义产物目录 | `<毛片名>-video-project-<时间戳>` |
+| `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
+| `--jianying-draft-dir <dir>` | 剪映草稿根目录（或 `auto`） | 读 init 配置 / 自动探测 |
+| `--reupload` | 强制重传，忽略上传缓存 | 关 |
+| `--no-open` | 完成后不自动打开产物目录 | **默认自动打开** |
+| `--json` | 机读：stdout 只输出结果 JSON（给 agent / 脚本） | 关 |
+
+`--json` 输出：`{ ok, outDir, files:{gtrk,jianying,xml}, jianyingDraftPath, errors, taskId, fileId }`。
+
+### 其它
+
+- `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 配置（交互 / 非交互）。
+- `gtrk doctor` — 体检。
+- `gtrk skills install [--dir <skills 目录>]` — 安装 agent skill。
+
+---
+
+## 工作原理
+
+```
+本地 gtrk CLI                          同合云                         本地三端
+─────────────                      ─────────────                  ─────────────
+毛片 ──上传(指纹缓存免重传)──▶  video_oral_cut 智能剪辑  ──产物──▶  客户端 gtrk/project.gtrk
+                                  (一次出 gtrk/剪映/xml)            剪映  自动落草稿目录
+源路径写进 gtrk materials.path                                     PR/FCP  导入 premiere.xml
+```
+
+- **gtrk** 是 timeline 的真超集 + HTML 颗粒，是同合云的统一工程契约；三端从同一份 gtrk 派生、切点一致。
+- 云端**零改动**全用现成 `video_oral_cut`；CLI 只做编排（上传 / 提交 / 轮询 / 拉回 / 落位 / 打开）。
+
+## 注意
+
+- 剪映 / CapCut 草稿需 `draft_content.json` + `draft_meta_info.json` **成对**才被软件识别——要么 `gtrk init` 配好草稿目录、要么 `--jianying-draft-dir` 指定，否则只产 content、需手动导入。
+- 多台机器盘符不同时，配置走 `~/.gtrk-cli/`（用户级），产物默认落毛片同目录。
+- 节奏预设强度以云端为准；`--preset` 只选预设、不改源裁剪。
+
+---
+
+## 结构
+
+```
+gtrk-cli/
+├── src/index.ts              # commander 入口
+├── src/commands/             # 子命令：init / oralcut / doctor / skills
+├── src/lib/                  # cloud / config / user-config / jianying / open / upload-cache / log
+├── skills/gtrk-oralcut/      # 打包的 agent skill（skills install 装它）
+├── assets/                   # 剪映草稿目录指引图
+└── AGENT.md                  # 可移植 agent playbook（skill 底座）
+```
+
+新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。