@gitruck/cli 0.1.0 → 0.2.0

package/AGENT.md

@@ -47,6 +47,12 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 | `-o, --out <dir>` | 自定义产物目录 | `<毛片同目录>/<毛片名>-video-project-<YYMMDD-HHMMSS>` |
 | `-f, --formats <list>` | 三方格式逗号分隔 | `gtrk,jianying,xml` |
 | `--jianying-draft-dir <dir>` | 剪映草稿根目录；传路径或 `auto` | 读 `gtrk init` 配置 / 自动探测 |
+| `--lang <code>` | 语言代码（英文 `en-US`、日文 `ja-JP`…） | `zh-CN` |
+| `--visual-assist` | **视觉兜底**：ASR 漏字时用人脸/说话检测保护 + 重识别（剪不准时开） | 关 |
+| `--no-adaptive-rhythm` | 关闭自适应节奏，改用固定标点停顿表 | 自适应开 |
+| `--render` | 额外渲染成片视频（`outputs` 加 `video`） | 只出工程 |
+| `--crf <n>` / `--codec <c>` | 视频质量 14-28（默认 18，越小越清晰）/ 编码（默认 h264），配 `--render` | — |
+| `--param k=v` / `--params-json '{…}'` | **通用透传**：任意云端参数（标量可重复 / JSON 嵌套），优先级最高 | — |
 | `--reupload` | 强制重新上传，忽略本地上传缓存 | 关 |
 | `--no-open` | 完成后**不**自动打开产物目录 | **默认会自动打开** |
 
@@ -61,6 +67,27 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 - **节奏预设**：`steady` 保留更多停顿（稳）、`concise` 默认精炼、`compact` 最紧凑（压停顿最狠）。
 - **部分格式失败不致命**：CLI 如实回显云端 `errors`（某格式没出来不影响其余）。
 
+**细节微调 —— 按用户诉求因势象形、自由组合**（上表是常用一等 flag；下面是节奏细调 + 完整取值）。你有云端全部参数，按需自由决定用哪些。**唯一要求：名字 / 取值 / 范围照文档用**（别记错拼错）；传越界云端报 `6016` 附原因、照改即可（乱传不产错误成片、只明确报错）。没特别诉求就跑默认。
+
+- **剪不准 / 剪掉真内容 / 有句话没剪进去** → `--visual-assist`：ASR 之外并行跑人脸 + 说话检测，画面在说话却没识别出字的地方**保护不剪**并重识别捞回，捞不回的进 `report.review_points` 复核；引擎挂了只降级不失败、不额外计费、绝不凭空生成。**「剪不准」的兜底。**
+- **节奏散参数**（无一等 flag，走 `--param 键=值` / `--params-json`，单位秒、范围 0–5）：
+  - `punctuation_breaks`：逐标点停顿，键 `，、；：。！？—……` + `paragraph`（段落）。例 `--params-json '{"punctuation_breaks":{"。":0.6,"，":0.3}}'`。
+  - `intra_gap_max`（>此值算气口，默认 0.35）/ `intra_gap_target`（收到多长，默认 0.10）/ `pad_in`(0.05) / `pad_out`(0.08)。例「气口留白多点」`--param pad_out=0.15`。
+  - `render.audio_crossfade_ms`（切点淡化毫秒 0–50、默认 8）等也能透传。
+- **节奏预设完整值**（选最贴内容的、再逐项覆盖；「默认」列 = 不选预设时各标点的默认停顿）：
+
+  | 参数（秒） | steady 稳健 | concise 精练 | compact 紧凑 | 默认 |
+  |---|---|---|---|---|
+  | 适用 | 讲述/教学 | 自媒体中长 | 短视频/广告 | 通用 |
+  | `、`/`，`/`；` | 0.18/0.25/0.36 | 0.12/0.18/0.26 | 0.06/0.08/0.12 | 0.15/0.20/0.30 |
+  | `：`/`—` | 0.45/0.55 | 0.32/0.40 | 0.15/0.18 | 0.35/0.45 |
+  | `。``！`/`？` | 0.55/0.60 | 0.40/0.45 | 0.18/0.20 | 0.45/0.50 |
+  | `……`/`paragraph` | 0.75/1.20 | 0.55/0.90 | 0.25/0.40 | 0.60/1.00 |
+  | `intra_gap_max`/`intra_gap_target` | 0.45/0.15 | 0.35/0.10 | 0.25/0.05 | 0.35/0.10 |
+  | `pad_in`/`pad_out` | 0.05/0.10 | 0.05/0.08 | 0.03/0.05 | 0.05/0.08 |
+
+- 优先级：`--preset` → 一等 flag → 透传（后者覆盖前者）。用户**自己点名**某参数 + 值 → 照他原样透传（CLI 底层支持任意云端参数）。**以上即 agent 需要的全部参数、本文档自足**（`gtrk oralcut --help` 也列全部 flag）；官网的原始 HTTP API 文档是给人看的，agent 不必也无法访问。
+
 ---
 
 ## 3. 产物结构 + 三端打开
@@ -91,19 +118,21 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 4. **要不要自动打开**：默认就开（用户常不知道文件去哪了，别让他找）。只有明确「别打开 / 批处理」才加 `--no-open`。
 5. **剪映装在非标准位置 / 多版本**：若用户没跑过 `gtrk init` 或探测失败，问剪映草稿根目录、传 `--jianying-draft-dir`（或让他先 `gtrk init`）。
 6. **只要某一两端**：用户只要客户端 → `--formats gtrk`；只要剪映 → `--formats jianying`；默认三端全给。
+7. **有具体细节诉求**（剪不准 / 换语言 / 要成片 / 调某个停顿）→ 见上「细节微调」，按需自由取用（`--visual-assist` / `--lang` / `--render` / 散参数）；没特别诉求跑默认即可。
 
-**跑完做一层验证**（别只信"成功"二字、别谎报三端都好）：
+**跑完读 `report`、验证、给用户交代**（`--json` 的 stdout 那行带 `files` / `errors` / **`report`**；别只信"成功"、别谎报三端都好）：
+- **读 `report`（因势象形的另一半）**：`duration_before`→`after`（剪了多少）；`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` / 散参数重跑（同毛片可反复剪对比）。
 - 确认产物目录在、`gtrk/project.gtrk` 非空（>0 字节）；要剪映就确认剪映草稿根里有**同名工程目录** + `draft_meta_info.json`。
-- 云端 `errors` 非空 → 如实告知哪个格式失败、原因；必要时按用户意图微调重跑（换 `--preset`、补 `--jianying-draft-dir`、`--reupload`）。
-- 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`）。
+- 云端 `errors` 非空 → 如实告知哪个格式失败、原因。
+- 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`），并**据 `report` 给一句交代**（剪了多久 → 多久、去掉了什么、有无漏读需复核）。
 
 ---
 
 ## 5. 典型调用
 
 ```bash
-# 有稿 + 剪完就看（最常见）
-gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt" --open
+# 有稿 + 剪完就看（最常见；剪完默认自动打开产物目录，无需额外 flag）
+gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt" --json
 
 # 无稿、要最紧凑节奏
 gtrk oralcut "D:/素材/某条.mp4" --preset compact
@@ -113,6 +142,12 @@ gtrk oralcut "D:/素材/某条.mp4" --formats gtrk
 
 # 剪映装在非标准盘符，手动指目录
 gtrk oralcut "D:/素材/某条.mp4" --jianying-draft-dir "F:/JianyingPro/User Data/Projects/com.lveditor.draft"
+
+# 用户抱怨"剪掉了真内容 / 剪不准" → 开视觉兜底重跑
+gtrk oralcut "D:/素材/某条.mp4" --visual-assist
+
+# 细到某标点停顿 + 顺手渲一个成片
+gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":0.6}}' --render --crf 20
 ```
 
 ---

package/README.md

@@ -25,31 +25,36 @@
 
 ---
 
+## 获取 API Key
+
+CLI 要调用同合云云端能力，需先拿一个 API Key（形如 `gc_xxxxxxxx`）：
+
+1. 打开官网 **[cloud.ai-mcn.tv](https://cloud.ai-mcn.tv)** 并登录 —— **登录即开通**、自带免费测试额度、零门槛。
+2. 进入 **[控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)**，在「API 密钥 / 密钥管理」处生成并复制你的 Key。
+3. 下一步 `gtrk install` 会让你把它粘进去（一次配好、本地长期复用）。
+
+> 快速开始文档：[cloud.ai-mcn.tv/zh-CN/docs/quick-start](https://cloud.ai-mcn.tv/zh-CN/docs/quick-start) · 对接咨询：business@migotimes.com
+
 ## 安装 & 快速上手
 
 需要 Node.js ≥ 20.6（`node -v` 查看）。
 
 ```bash
-# 1) 安装（全局命令 gtrk）
-npm i -g @gitruck/cli
-#   或免安装直接用：npx @gitruck/cli <命令>
+# 1) 一条命令装全：命令行 gtrk + /gtrk-oralcut skill + 配置（填 API Key、自动扫剪映目录）
+npm i -g @gitruck/cli@latest && gtrk install
+#   或免全局安装直接用：npx @gitruck/cli@latest install
 
-# 2) 一次性配置（填 API Key，自动扫剪映草稿目录）
-gtrk init
-
-# 3) 剪一条（剪完自动打开产物目录）
+# 2) 剪一条（剪完自动打开产物目录）
 gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
 ```
 
-> 本地开发：`cd gtrk-cli && bun install && bun run src/index.ts <命令>`。
+> 只想配置、不装 skill：用 `gtrk init`。本地开发：`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
-```
+`gtrk install` 已经把 `/gtrk-oralcut` skill 装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
 
 然后在 Claude Code 里直接说「**帮我把这条口播剪一版**」或打 `/gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
 
@@ -102,13 +107,14 @@ gtrk init --api-key <KEY> --jianying-draft-dir auto -y
 | `--no-open` | 完成后不自动打开产物目录 | **默认自动打开** |
 | `--json` | 机读：stdout 只输出结果 JSON（给 agent / 脚本） | 关 |
 
-`--json` 输出：`{ ok, outDir, files:{gtrk,jianying,xml}, jianyingDraftPath, errors, taskId, fileId }`。
+`--json` 输出（成功时 stdout 单行）：`{ ok, outDir, files:{gtrk,jianying,xml}, jianyingDraftPath, report, errors, taskId, fileId }`；命令失败则进程非 0 退出、报错走 stderr、stdout 无 JSON。
 
 ### 其它
 
-- `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 配置（交互 / 非交互）。
+- `gtrk install [--api-key … -y --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
+- `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
 - `gtrk doctor` — 体检。
-- `gtrk skills install [--dir <skills 目录>]` — 安装 agent skill。
+- `gtrk skills install [--dir <skills 目录>]` — 单独安装 agent skill。
 
 ---
 

package/dist/index.js

@@ -1888,22 +1888,101 @@ var {
   Help
 } = import__.default;
 
+// src/index.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { join as join8 } from "node:path";
+
+// src/lib/paths.ts
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+function packageRoot() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0;i < 8; i++) {
+    if (existsSync(join(dir, "package.json")))
+      return dir;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return dir;
+}
+
+// src/commands/skills.ts
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+import { existsSync as existsSync2, mkdirSync, copyFileSync } from "node:fs";
+
+// src/lib/log.ts
+var c = {
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  cyan: (s) => `\x1B[36m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
+  red: (s) => `\x1B[31m${s}\x1B[0m`
+};
+var humanOut = process.stdout;
+function routeLogsToStderr() {
+  humanOut = process.stderr;
+}
+var line = (s) => humanOut.write(`${s}
+`);
+var log = {
+  step: (msg) => line(c.cyan(msg)),
+  info: (msg) => line(c.dim(`   ${msg}`)),
+  ok: (msg) => line(c.green(`✅ ${msg}`)),
+  warn: (msg) => line(c.yellow(`⚠️  ${msg}`)),
+  err: (msg) => process.stderr.write(`${c.red(`❌ ${msg}`)}
+`),
+  tick: (msg) => humanOut.write(`\r   ${msg}\x1B[K`),
+  tickEnd: () => humanOut.write(`
+`)
+};
+
+// src/commands/skills.ts
+var SKILL_NAME = "gtrk-oralcut";
+var SRC = join2(packageRoot(), "skills", SKILL_NAME, "SKILL.md");
+function installSkill(opts = {}) {
+  if (!existsSync2(SRC)) {
+    log.warn(`找不到打包的 skill 源：${SRC}（跳过 skill 安装，不影响命令行）`);
+    return false;
+  }
+  const dest = join2(opts.dir ?? join2(homedir(), ".claude", "skills"), SKILL_NAME);
+  try {
+    mkdirSync(dest, { recursive: true });
+    copyFileSync(SRC, join2(dest, "SKILL.md"));
+    log.ok(`已安装 /${SKILL_NAME} → ${join2(dest, "SKILL.md")}`);
+    log.info("在 Claude Code 里打 /gtrk-oralcut，或直接说「帮我剪个口播」即可触发（可能需重载会话）。");
+    return true;
+  } catch (e) {
+    log.warn(`skill 安装失败（不影响命令行使用）：${e instanceof Error ? e.message : String(e)}`);
+    return false;
+  }
+}
+function registerSkills(program2) {
+  const skills = program2.command("skills").description("管理 agent skill（安装到 Claude Code）");
+  skills.command("install").description(`把 /${SKILL_NAME} 安装到 ~/.claude/skills（对标飞书 skills add）`).option("--dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").action((opts) => {
+    installSkill({ dir: opts.dir });
+  });
+}
+
 // src/commands/init.ts
-import { join as join4, resolve as resolve2 } from "node:path";
-import { existsSync as existsSync5 } from "node:fs";
+import { join as join5, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
 
 // src/lib/user-config.ts
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync, writeFileSync } from "node:fs";
 var DEFAULT_API_BASE = "https://api.ai-mcn.tv:10000";
-var DIR = join(homedir(), ".gtrk-cli");
-var FILE = join(DIR, "config.json");
+var DIR = join3(homedir2(), ".gtrk-cli");
+var FILE = join3(DIR, "config.json");
 function configPath() {
   return FILE;
 }
 function readUserConfig() {
-  if (!existsSync(FILE))
+  if (!existsSync3(FILE))
     return {};
   try {
     return JSON.parse(readFileSync(FILE, "utf8"));
@@ -1912,29 +1991,29 @@ function readUserConfig() {
   }
 }
 function writeUserConfig(patch) {
-  mkdirSync(DIR, { recursive: true });
+  mkdirSync2(DIR, { recursive: true });
   const merged = { ...readUserConfig(), ...patch };
   writeFileSync(FILE, JSON.stringify(merged, null, 2));
 }
 
 // src/lib/jianying.ts
-import { join as join2, resolve } from "node:path";
-import { existsSync as existsSync2 } from "node:fs";
+import { join as join4, resolve } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
 function probeJianyingDraftDir() {
   const local = process.env.LOCALAPPDATA;
   if (!local)
     return;
   const candidates = [
-    join2(local, "JianyingPro", "User Data", "Projects", "com.lveditor.draft"),
-    join2(local, "CapCut", "User Data", "Projects", "com.lveditor.draft")
+    join4(local, "JianyingPro", "User Data", "Projects", "com.lveditor.draft"),
+    join4(local, "CapCut", "User Data", "Projects", "com.lveditor.draft")
   ];
-  return candidates.find((p) => existsSync2(p));
+  return candidates.find((p) => existsSync4(p));
 }
 function resolveJianyingDraftDir(opt) {
   if (opt && opt !== "auto")
     return resolve(opt);
   const saved = readUserConfig().jianyingDraftDir;
-  if (saved && existsSync2(saved))
+  if (saved && existsSync4(saved))
     return saved;
   return probeJianyingDraftDir();
 }
@@ -1957,27 +2036,10 @@ function launch(cmd) {
   } catch {}
 }
 
-// src/lib/paths.ts
-import { dirname, join as join3 } from "node:path";
-import { fileURLToPath } from "node:url";
-import { existsSync as existsSync3 } from "node:fs";
-function packageRoot() {
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0;i < 8; i++) {
-    if (existsSync3(join3(dir, "package.json")))
-      return dir;
-    const parent = dirname(dir);
-    if (parent === dir)
-      break;
-    dir = parent;
-  }
-  return dir;
-}
-
 // src/lib/prompt.ts
 import { stdin, stdout } from "node:process";
 import { spawnSync } from "node:child_process";
-var c = {
+var c2 = {
   dim: (s) => `\x1B[2m${s}\x1B[0m`,
   cyan: (s) => `\x1B[36m${s}\x1B[0m`
 };
@@ -2002,8 +2064,8 @@ function readClipboard() {
 }
 function ask(message, opts = {}) {
   return new Promise((resolve2) => {
-    const hint = opts.defaultValue ? c.dim(` (${opts.defaultValue})`) : "";
-    stdout.write(`${c.cyan("?")} ${message}${hint} `);
+    const hint = opts.defaultValue ? c2.dim(` (${opts.defaultValue})`) : "";
+    stdout.write(`${c2.cyan("?")} ${message}${hint} `);
     let value = "";
     const echo = (s) => stdout.write(opts.mask ? "•".repeat([...s].length) : s);
     const wasRaw = stdin.isRaw ?? false;
@@ -2060,14 +2122,14 @@ function promptSecret(message) {
   return ask(message, { mask: true });
 }
 async function promptConfirm(message, defaultYes = true) {
-  const a = (await ask(`${message} ${c.dim(defaultYes ? "[Y/n]" : "[y/N]")}`)).trim().toLowerCase();
+  const a = (await ask(`${message} ${c2.dim(defaultYes ? "[Y/n]" : "[y/N]")}`)).trim().toLowerCase();
   if (!a)
     return defaultYes;
   return a === "y" || a === "yes";
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync4 } from "node:fs";
+import { existsSync as existsSync5 } from "node:fs";
 function registerDoctor(program2) {
   program2.command("doctor").description("体检：配置 / 云端连通 / 剪映目录 / 运行时是否就绪").action(async () => {
     await runDoctor();
@@ -2116,7 +2178,7 @@ async function runDoctor() {
   }
   rows.push({ name: "云端连通 + 鉴权", status: apiStatus, detail: apiDetail });
   const draftDir = resolveJianyingDraftDir(undefined);
-  const draftOk = !!draftDir && existsSync4(draftDir);
+  const draftOk = !!draftDir && existsSync5(draftDir);
   rows.push({
     name: "剪映草稿目录",
     status: draftOk ? "ok" : "warn",
@@ -2124,8 +2186,8 @@ async function runDoctor() {
   });
   rows.push({
     name: "配置文件",
-    status: existsSync4(configPath()) ? "ok" : "warn",
-    detail: existsSync4(configPath()) ? configPath() : `未生成 —— 跑 gtrk init（${configPath()}）`
+    status: existsSync5(configPath()) ? "ok" : "warn",
+    detail: existsSync5(configPath()) ? configPath() : `未生成 —— 跑 gtrk init（${configPath()}）`
   });
   console.log(`
 gtrk 体检：
@@ -2143,34 +2205,8 @@ gtrk 体检：
   return !failed;
 }
 
-// src/lib/log.ts
-var c2 = {
-  dim: (s) => `\x1B[2m${s}\x1B[0m`,
-  cyan: (s) => `\x1B[36m${s}\x1B[0m`,
-  green: (s) => `\x1B[32m${s}\x1B[0m`,
-  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
-  red: (s) => `\x1B[31m${s}\x1B[0m`
-};
-var humanOut = process.stdout;
-function routeLogsToStderr() {
-  humanOut = process.stderr;
-}
-var line = (s) => humanOut.write(`${s}
-`);
-var log = {
-  step: (msg) => line(c2.cyan(msg)),
-  info: (msg) => line(c2.dim(`   ${msg}`)),
-  ok: (msg) => line(c2.green(`✅ ${msg}`)),
-  warn: (msg) => line(c2.yellow(`⚠️  ${msg}`)),
-  err: (msg) => process.stderr.write(`${c2.red(`❌ ${msg}`)}
-`),
-  tick: (msg) => humanOut.write(`\r   ${msg}\x1B[K`),
-  tickEnd: () => humanOut.write(`
-`)
-};
-
 // src/commands/init.ts
-var GUIDE_IMAGE = join4(packageRoot(), "assets", "jianying-draft-path.png");
+var GUIDE_IMAGE = join5(packageRoot(), "assets", "jianying-draft-path.png");
 function registerInit(program2) {
   program2.command("init").description("一次性配置：API Key + 剪映草稿目录（之后所有命令免重复配置）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址（缺省用默认生产地址）").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(runInit);
 }
@@ -2205,7 +2241,7 @@ async function runInit(opts) {
     openFile(GUIDE_IMAGE);
     const manual = (await promptText("剪映草稿根目录（…\\com.lveditor.draft），留空跳过：")).trim();
     if (manual) {
-      if (existsSync5(manual))
+      if (existsSync6(manual))
         jianyingDraftDir = resolve2(manual);
       else
         log.warn(`目录不存在，已跳过：${manual}`);
@@ -2254,10 +2290,20 @@ async function runInitNonInteractive(opts) {
   await runDoctor();
 }
 
+// src/commands/install.ts
+function registerInstall(program2) {
+  program2.command("install").description("一条命令装全：安装 /gtrk-oralcut skill + 配置（对标飞书 lark-cli install）").option("--api-key <key>", "非交互：直接指定 API Key").option("--api-base <url>", "非交互：指定 API 根地址").option("--jianying-draft-dir <dir>", "非交互：剪映草稿目录（传 auto 则自动探测）").option("--skills-dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").option("-y, --yes", "非交互：用传入值 + 自动探测，不弹任何提示").action(async (opts) => {
+    log.step("① 安装 agent skill…");
+    installSkill({ dir: opts.skillsDir });
+    log.step("② 配置 + 体检…");
+    await runInit(opts);
+  });
+}
+
 // src/commands/oralcut.ts
-import { resolve as resolve3, join as join6, dirname as dirname2, basename as basename2, extname } from "node:path";
+import { resolve as resolve3, join as join7, dirname as dirname2, basename as basename2, extname } from "node:path";
 import { mkdir as mkdir2, cp, readFile as readFile2 } from "node:fs/promises";
-import { existsSync as existsSync7 } from "node:fs";
+import { existsSync as existsSync8 } from "node:fs";
 
 // src/lib/config.ts
 function loadConfig() {
@@ -2357,18 +2403,18 @@ async function download(url, dest) {
 }
 
 // src/lib/upload-cache.ts
-import { homedir as homedir2 } from "node:os";
-import { join as join5 } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { join as join6 } from "node:path";
 import { stat, mkdir, readFile, writeFile as writeFile2 } from "node:fs/promises";
-import { existsSync as existsSync6 } from "node:fs";
-var CACHE_DIR = join5(homedir2(), ".gtrk-cli");
-var CACHE_FILE = join5(CACHE_DIR, "upload-cache.json");
+import { existsSync as existsSync7 } from "node:fs";
+var CACHE_DIR = join6(homedir3(), ".gtrk-cli");
+var CACHE_FILE = join6(CACHE_DIR, "upload-cache.json");
 async function fingerprint(path) {
   const s = await stat(path);
   return `${s.size}:${Math.round(s.mtimeMs)}`;
 }
 async function load() {
-  if (!existsSync6(CACHE_FILE))
+  if (!existsSync7(CACHE_FILE))
     return {};
   try {
     return JSON.parse(await readFile(CACHE_FILE, "utf8"));
@@ -2429,8 +2475,43 @@ var FORMAT_META = {
   fcpxml: { label: "Final Cut (fcpxml)", openHint: (p) => `Final Cut Pro：导入 ${p}` },
   otio: { label: "OpenTimelineIO", openHint: (p) => `用支持 OTIO 的工具打开 ${p}` }
 };
+var collectParam = (v, acc) => {
+  acc.push(v);
+  return acc;
+};
+function coerceValue(v) {
+  if (v === "true")
+    return true;
+  if (v === "false")
+    return false;
+  if (v.trim() !== "" && !Number.isNaN(Number(v)))
+    return Number(v);
+  return v;
+}
+function parseExtraParams(pairs, jsonStr) {
+  const out = {};
+  for (const pair of pairs) {
+    const i = pair.indexOf("=");
+    if (i < 0)
+      throw new Error(`--param 需要 key=value 格式：「${pair}」`);
+    out[pair.slice(0, i).trim()] = coerceValue(pair.slice(i + 1));
+  }
+  if (jsonStr) {
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonStr);
+    } catch {
+      throw new Error(`--params-json 不是合法 JSON：${jsonStr}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("--params-json 必须是一个 JSON 对象");
+    }
+    Object.assign(out, parsed);
+  }
+  return out;
+}
 function registerOralCut(program2) {
-  program2.command("oralcut <input>").description("智能口播剪辑闭环：上传毛片 → 云端剪辑 → 拉回 gtrk/剪映/PR 工程文件 → 打开").option("-s, --script <file>", "文稿 txt 路径（缺省走无稿智能重建）").option("-p, --preset <preset>", "节奏预设 steady|concise|compact", "concise").option("-o, --out <dir>", "工程产物目录（缺省 = <毛片同目录>/<毛片名>-video-project-<YYMMDD-HHMMSS>）").option("-f, --formats <list>", "三方格式（逗号分隔）", "gtrk,jianying,xml").option("--jianying-draft-dir <dir>", "剪映草稿根目录；传路径或 auto（默认读 gtrk init 配置 / 自动探测）").option("--reupload", "强制重新上传，忽略本地上传缓存（毛片改了但指纹意外没变时用）").option("--no-open", "完成后不自动打开产物目录（默认会自动打开，省得你找文件去哪了）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON（给 agent/脚本解析）").action(async (input, opts) => {
+  program2.command("oralcut <input>").description("智能口播剪辑闭环：上传毛片 → 云端剪辑 → 拉回 gtrk/剪映/PR 工程文件 → 打开").option("-s, --script <file>", "文稿 txt 路径（缺省走无稿智能重建）").option("-p, --preset <preset>", "节奏预设 steady|concise|compact", "concise").option("-o, --out <dir>", "工程产物目录（缺省 = <毛片同目录>/<毛片名>-video-project-<YYMMDD-HHMMSS>）").option("-f, --formats <list>", "三方格式（逗号分隔）", "gtrk,jianying,xml").option("--jianying-draft-dir <dir>", "剪映草稿根目录；传路径或 auto（默认读 gtrk init 配置 / 自动探测）").option("--lang <code>", "语言代码（默认 zh-CN；如 en-US / ja-JP）").option("--visual-assist", "视觉兜底：ASR 漏字时用人脸/说话检测保护并重识别（剪不准/怕剪掉真内容时开）").option("--no-adaptive-rhythm", "关闭自适应节奏（默认开；关了改用固定标点停顿表）").option("--render", "额外渲染成片视频（outputs 加 video）").option("--crf <n>", "视频质量 CRF 14-28（越小越清晰/文件越大，默认 18；需配 --render）").option("--codec <c>", "视频编码（默认 h264；需配 --render）").option("--param <k=v>", "透传任意云端参数（标量、可重复；如 --param intra_gap_max=0.4 --param visual_assist=true）", collectParam, []).option("--params-json <json>", `透传任意云端参数（JSON 对象、支持嵌套；如 '{"punctuation_breaks":{"。":0.3},"render":{"crf":20}}'）`).option("--reupload", "强制重新上传，忽略本地上传缓存（毛片改了但指纹意外没变时用）").option("--no-open", "完成后不自动打开产物目录（默认会自动打开，省得你找文件去哪了）").option("--json", "机读模式：人读日志转 stderr，stdout 只输出结果 JSON（给 agent/脚本解析）").action(async (input, opts) => {
     await runOralCut(input, opts);
   });
 }
@@ -2439,17 +2520,17 @@ async function runOralCut(input, opts) {
     routeLogsToStderr();
   const cfg = loadConfig();
   const inputAbs = resolve3(input);
-  if (!existsSync7(inputAbs))
+  if (!existsSync8(inputAbs))
     throw new Error(`毛片不存在：${inputAbs}`);
   const projName = basename2(inputAbs, extname(inputAbs));
   const formats = opts.formats.split(",").map((s) => s.trim()).filter(Boolean);
   const wantJianying = formats.some((f) => f === "jianying" || f === "capcut");
-  const outDir = resolve3(opts.out ?? join6(dirname2(inputAbs), `${projName}-video-project-${timestamp()}`));
+  const outDir = resolve3(opts.out ?? join7(dirname2(inputAbs), `${projName}-video-project-${timestamp()}`));
   await mkdir2(outDir, { recursive: true });
   let scriptPath = opts.script ? resolve3(opts.script) : undefined;
   if (!scriptPath) {
-    const sibling = join6(dirname2(inputAbs), `${projName}.txt`);
-    if (existsSync7(sibling)) {
+    const sibling = join7(dirname2(inputAbs), `${projName}.txt`);
+    if (existsSync8(sibling)) {
       scriptPath = sibling;
       log.info(`自动识别到同名文稿：${sibling}（按有稿剪辑；不想用就改名或显式 --script）`);
     }
@@ -2463,15 +2544,16 @@ async function runOralCut(input, opts) {
     else
       log.warn("没找到剪映草稿目录（剪映/CapCut 未装在标准位置）→ 将只产 draft_content.json、缺 meta，剪映无法直接打开。可加 --jianying-draft-dir <你的草稿目录> 重跑。");
   }
-  log.step(`▶ 智能口播剪辑：${basename2(inputAbs)}（预设 ${opts.preset}，格式 ${formats.join("/")}）`);
+  log.step(`▶ 智能口播剪辑：${basename2(inputAbs)}（预设 ${opts.preset}${opts.visualAssist ? " · 视觉兜底" : ""}，格式 ${formats.join("/")}）`);
+  const extraParams = parseExtraParams(opts.param, opts.paramsJson);
   log.step("① 上传毛片到云端…");
   let up = await uploadCached(cfg, inputAbs, { force: opts.reupload });
   log.info(up.cached ? `命中上传缓存，复用 file_id = ${up.fileId}（免二次上传）` : `file_id = ${up.fileId}`);
   const buildPayload = (fid) => {
     const p = {
       file_id: fid,
-      la: "zh-CN",
-      outputs: ["project"],
+      la: opts.lang ?? "zh-CN",
+      outputs: opts.render ? ["project", "video"] : ["project"],
       project_formats: formats,
       source_path: inputAbs,
       rhythm_preset: opts.preset
@@ -2480,6 +2562,20 @@ async function runOralCut(input, opts) {
       p.script = script;
     if (draftDir)
       p.struct_meta = { nle_draft_dir: draftDir };
+    if (opts.visualAssist)
+      p.visual_assist = true;
+    if (opts.adaptiveRhythm === false)
+      p.adaptive_rhythm = false;
+    if (opts.render) {
+      const r = {};
+      if (opts.crf != null)
+        r.crf = Number(opts.crf);
+      if (opts.codec)
+        r.codec = opts.codec;
+      if (Object.keys(r).length)
+        p.render = r;
+    }
+    Object.assign(p, extraParams);
     return p;
   };
   log.step("② 提交智能口播剪辑任务…");
@@ -2508,9 +2604,9 @@ async function runOralCut(input, opts) {
   const byFormat = {};
   for (const f of files) {
     const base = baseFormat(f.format);
-    const fmtDir = join6(outDir, base);
+    const fmtDir = join7(outDir, base);
     await mkdir2(fmtDir, { recursive: true });
-    const dest = join6(fmtDir, f.filename);
+    const dest = join7(fmtDir, f.filename);
     await download(f.download_url, dest);
     (byFormat[base] ??= []).push(dest);
     log.info(`${FORMAT_META[base]?.label ?? f.format} ← ${f.filename}`);
@@ -2520,16 +2616,16 @@ async function runOralCut(input, opts) {
   }
   let jianyingDraftPath;
   if (byFormat.jianying && draftDir) {
-    jianyingDraftPath = join6(draftDir, basename2(outDir));
+    jianyingDraftPath = join7(draftDir, basename2(outDir));
     await mkdir2(jianyingDraftPath, { recursive: true });
-    await cp(join6(outDir, "jianying"), jianyingDraftPath, { recursive: true });
+    await cp(join7(outDir, "jianying"), jianyingDraftPath, { recursive: true });
     log.info(`剪映草稿已落到：${jianyingDraftPath}`);
   }
   if (!opts.json) {
     log.step("⑤ 三方打开（产物已就位，按需自取）：");
     for (const base of Object.keys(byFormat)) {
       const meta = FORMAT_META[base];
-      const target = base === "jianying" ? jianyingDraftPath ?? join6(outDir, "jianying") : byFormat[base][0];
+      const target = base === "jianying" ? jianyingDraftPath ?? join7(outDir, "jianying") : byFormat[base][0];
       console.log(`   • ${meta?.label ?? base}：${meta?.openHint(target) ?? target}`);
     }
   }
@@ -2545,6 +2641,7 @@ async function runOralCut(input, opts) {
       outDir,
       files: byFormat,
       jianyingDraftPath: jianyingDraftPath ?? null,
+      report: result.report ?? null,
       errors,
       taskId,
       fileId: up.fileId
@@ -2552,32 +2649,14 @@ async function runOralCut(input, opts) {
   }
 }
 
-// src/commands/skills.ts
-import { homedir as homedir3 } from "node:os";
-import { join as join7 } from "node:path";
-import { existsSync as existsSync8, mkdirSync as mkdirSync2, copyFileSync } from "node:fs";
-var SKILL_NAME = "gtrk-oralcut";
-var SRC = join7(packageRoot(), "skills", SKILL_NAME, "SKILL.md");
-function registerSkills(program2) {
-  const skills = program2.command("skills").description("管理 agent skill（安装到 Claude Code）");
-  skills.command("install").description(`把 /${SKILL_NAME} 安装到 ~/.claude/skills（对标飞书 skills add）`).option("--dir <dir>", "自定义 skills 目录（缺省 ~/.claude/skills）").action((opts) => {
-    if (!existsSync8(SRC))
-      throw new Error(`找不到打包的 skill 源：${SRC}`);
-    const base = opts.dir ?? join7(homedir3(), ".claude", "skills");
-    const dest = join7(base, SKILL_NAME);
-    mkdirSync2(dest, { recursive: true });
-    copyFileSync(SRC, join7(dest, "SKILL.md"));
-    console.log(`✅ 已安装 /${SKILL_NAME} → ${join7(dest, "SKILL.md")}`);
-    console.log("   在 Claude Code 里打 /gtrk-oralcut，或直接说「帮我剪个口播」即可触发（可能需重载会话）。");
-  });
-}
-
 // src/index.ts
 try {
   process.loadEnvFile?.();
 } catch {}
+var { version } = JSON.parse(readFileSync2(join8(packageRoot(), "package.json"), "utf8"));
 var program2 = new Command;
-program2.name("gtrk").description("同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通").version("0.1.0");
+program2.name("gtrk").description("同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通").version(version);
+registerInstall(program2);
 registerInit(program2);
 registerOralCut(program2);
 registerDoctor(program2);

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@gitruck/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
   "license": "MIT",
   "author": "Gitruck (同合云)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gitruck/cli.git"
+  },
+  "homepage": "https://github.com/Gitruck/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Gitruck/cli/issues"
+  },
   "type": "module",
   "bin": {
     "gtrk": "dist/index.js"

package/skills/gtrk-oralcut/SKILL.md

@@ -7,44 +7,102 @@ description: 智能口播剪辑闭环——把一条口播原视频(毛片)通
 
 把用户的口播毛片，用 `gtrk` CLI 跑通「上传 → 云端智能口播剪辑 → 拉回三方工程文件 → 打开」，再把产物目录 + 三端打开方式回给用户。**CLI 是手、你是脑。**
 
-> 权威操作手册见 gtrk-cli 仓库的 `AGENT.md`（更全、工具无关）；本 skill 是它的 Claude 化薄壳，已自带够用的决策与验证逻辑。
+> **本 skill 已含你需要的全部信息**（参数、取值、执行、读报告、排错），照它做即可，不用也无法去查外部文档。（源仓库另有一份更全的工具无关版 `AGENT.md`，那是给在仓库里开发的人看的，与你无关。）
 
-## 前置：CLI 在不在
+## 前置：CLI 装没装 + 体检
 
-先 `gtrk doctor` 体检：
+先跑 `gtrk doctor`（它顺带验证 `gtrk` 命令本身在不在）：
+- **`gtrk` 找不到 / command not found** → CLI 没装 → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
 - 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key + 剪映目录，**交互式、需真终端**，你别替他跑）。
 - 报云端连不上 / 剪映目录没配 → 照提示让用户处理。
 - 全绿就往下走。
 
 ## 把用户的话变成一次调用
 
+> **每次调用都必须带 `--json`**（成功时 stdout 只出一行结果 JSON、人读日志转 stderr），你才能解析结果 + 读报告。不是可选项。
+
 从用户消息里取这几样，缺关键的就问：
 
 1. **毛片路径**（必需）：口播原视频的本地路径。没有就问。
-2. **文稿**：用户给了逐字稿/文字稿 → `--script <稿>`；没给则不传（CLI 会探毛片同名 `.txt`，有就自动按有稿剪、更准；无则云端无稿智能重建）。
-3. **节奏**：用户说「快/紧凑/卡点狠」→ `--preset compact`；「稳/别删太多停顿」→ `--preset steady`；没特别说就默认（不传）。
-4. **只要某端**：只要客户端 → `--formats gtrk`；只要剪映 → `--formats jianying`；默认三端全给。
-
-## 执行（务必带 `--json`，便于你解析与验证）
+2. **文稿**：用户给了逐字稿/文字稿**文件** → `--script <txt文件路径>`（接的是 .txt 文件路径，不是稿子正文）；没给则不传（CLI 会探毛片同名 `.txt`，有就自动按有稿剪、更准；无则云端无稿智能重建）。
+3. **节奏**：用户说「快/紧凑/卡点狠」→ `--preset compact`；「稳/别删太多停顿」→ `--preset steady`；没特别说就不传（CLI 默认 `concise` 精练）。
+4. **只要某端**：只要客户端 → `--formats gtrk`；只要剪映 → `--formats jianying`；只要 PR → `--formats xml`（全部格式见下表、逗号可多选）；默认三端全给（`gtrk,jianying,xml`）。
+
+## 完整参数规格 —— 按用户需求因势象形、自由组合
+
+**你手上有云端全部参数（下表）。按用户的具体诉求自由决定用哪些、怎么配——需要就调、没提就跑默认（默认已是给多数人调好的）。** 只有一条要求：**名字 / 取值 / 范围照下表用**（别记错拼错）；万一传越界，云端会报 `6016` 并附具体原因，照着改即可——乱传不会产出错误成片，只会明确报错。
+
+| 用户想要 | CLI 怎么传 | 取值 · 默认 | 说明 |
+|---|---|---|---|
+| 有稿对齐（更准） | `--script <txt>`（或毛片同名 `.txt` 自动） | 10–50000 字 · 缺省无稿重建 | 有稿逐字对齐质量最佳；无稿智能重建终稿 |
+| 换语种 | `--lang <码>` | `zh-CN`/`en-US`/`ja-JP`… · 默认 `zh-CN` | 不传即 CLI 默认发 `zh-CN`；主推中文，余语种尽力而为 |
+| 产哪些工程格式 | `--formats <逗号列表>` | `xml`/`fcpxml`/`otio`/`jianying`/`capcut`/`gtrk` · CLI 缺省 `gtrk,jianying,xml` | 可多选 |
+| 顺带渲个成片视频 | `--render` | 开关 · 缺省不渲 | 加它则额外出 mp4 成片 |
+| 成片画质 | `--crf <n>`（配 `--render`） | 整数 14–28 · `18` | 越小越清晰 / 越大体积越小 |
+| 成片编码 | `--codec <c>`（配 `--render`） | `h264` · `h264` | 当前仅 h264 |
+| 节奏松紧 | `--preset <名>` | `steady`/`concise`/`compact` · 默认 `concise` | 不传即 CLI 默认发 `concise`（精练）；见下方预设表，铺底后可逐项覆盖 |
+| **剪不准 / 剪掉真内容 / 有话没剪进去** | `--visual-assist` | 开关 · 关 | **视觉找补兜底**：画面说话检测保护疑似漏识别段不被误剪并重识别捞回；不额外计费、绝不凭空生成 |
+| 别随说话人节奏自适应 | `--no-adaptive-rhythm` | 开关 · 自适应默认开 | 关了改用固定标点停顿表 |
+| 剪映草稿目录（非标准位置） | `--jianying-draft-dir <目录>`（或 `auto`） | 路径 · 读 init 配置 / 自动探测 | 出剪映可直开草稿需要它 |
+
+**更细的节奏散参数**（无一等 flag，用 `--param 键=值` 或嵌套 `--params-json`）：
+
+| 参数 | 传法 | 取值 · 默认 | 说明 |
+|---|---|---|---|
+| `punctuation_breaks` | `--params-json '{"punctuation_breaks":{"。":0.6,"，":0.3}}'` | 每标点 0–5 秒 · 见预设表 | 逐标点停顿；键只能是 `，、；：。！？—……` 和 `paragraph`（段落） |
+| `intra_gap_max` | `--param intra_gap_max=0.4` | 0–5 · `0.35` | 句内停顿超此值算气口、触发收紧 |
+| `intra_gap_target` | `--param intra_gap_target=0.05` | 0–5 且 <max · `0.10` | 气口收到的目标秒数 |
+| `pad_in` / `pad_out` | `--param pad_out=0.15` | 0–5 · `0.05` / `0.08` | 保留片段头 / 尾呼吸留白 |
+| `render.audio_crossfade_ms` | `--params-json '{"render":{"audio_crossfade_ms":12}}'` | 0–50 · `8` | 切点淡化毫秒，`0`=硬切 |
+
+**节奏预设表 · 完整值**（选最贴内容类型的，再逐项覆盖散参数；「默认」列 = 不选预设时的基线，也即各标点的默认停顿）：
+
+| 参数（秒） | `steady` 稳健 | `concise` 精练 | `compact` 紧凑 | 默认 |
+|---|---|---|---|---|
+| 适用 | 讲述 / 教学 | 自媒体中长视频 | 短视频 / 广告 | 通用 |
+| `、` / `，` / `；` | 0.18 / 0.25 / 0.36 | 0.12 / 0.18 / 0.26 | 0.06 / 0.08 / 0.12 | 0.15 / 0.20 / 0.30 |
+| `：` / `—` | 0.45 / 0.55 | 0.32 / 0.40 | 0.15 / 0.18 | 0.35 / 0.45 |
+| `。` `！` / `？` | 0.55 / 0.60 | 0.40 / 0.45 | 0.18 / 0.20 | 0.45 / 0.50 |
+| `……` / `paragraph`（段落） | 0.75 / 1.20 | 0.55 / 0.90 | 0.25 / 0.40 | 0.60 / 1.00 |
+| `intra_gap_max` / `intra_gap_target` | 0.45 / 0.15 | 0.35 / 0.10 | 0.25 / 0.05 | 0.35 / 0.10 |
+| `pad_in` / `pad_out` | 0.05 / 0.10 | 0.05 / 0.08 | 0.03 / 0.05 | 0.05 / 0.08 |
+
+> **因势象形举例**：「教学口播、别删太狠、句号后多顿一下」→ `--preset steady --params-json '{"punctuation_breaks":{"。":0.7}}'`；「英文短视频卡点狠、顺便出成片」→ `--lang en-US --preset compact --render`；「上次有句话没剪进去」→ `--visual-assist`。用户**自己点名**某参数+值 → 照他原样 `--param`/`--params-json` 透传（CLI 底层支持任意云端参数）。
+>
+> **以上就是你需要的全部参数——本 skill 自足，别去别处查**（`gtrk oralcut --help` 也随时列全部 flag）。官网另有一份面向开发者的原始 HTTP API 文档，那是给人看的，你不必也无法访问。
+
+## 执行（每次都带 `--json`）
 
 ```bash
-gtrk oralcut "<毛片绝对路径>" [--script "<稿>"] [--preset compact|steady] --json
+gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|concise|compact] [其它参数…] --json
 ```
 
-- `--json`：人读日志走 stderr，**stdout 只有一行结果 JSON**：
-  `{ ok, outDir, files:{gtrk:[],jianying:[],xml:[]}, jianyingDraftPath, errors, taskId, fileId }`
-- 默认会自动打开产物目录文件夹（用户能直接看到文件）；纯批处理才加 `--no-open`。
+- `--json`：人读日志走 stderr，**成功时 stdout 只有一行结果 JSON**：
+  `{ ok, outDir, files:{gtrk:[],jianying:[],xml:[]}, jianyingDraftPath, report, errors, taskId, fileId }`
+- **命令失败**（毛片路径错 / 鉴权失败 / 参数越界 6016 等）→ **进程非 0 退出、报错打到 stderr、stdout 无 JSON**。先看退出码，非 0 就把 stderr 的报错如实回给用户、别当成功。
+- 默认会自动打开产物目录（用户能直接看到文件）；纯脚本/无头环境才加 `--no-open`。
 - 云端处理是分钟级，耐心等命令返回。
 
-## 跑完做一层验证（别只信"成功"二字）
+## 跑完读报告、给用户交代、按需调整（因势象形的另一半）
+
+`--json` 的 stdout 那行带 **`report`**（云端返回的原始剪辑报告对象，字段按需读、个别可能缺，读前判空）——读它，别只回一句"剪好了"：
+
+- `duration_before` → `after`：剪了多少（如 114.7s → 68.6s）。
+- `dropped[]`：剔掉了哪些段（`reason`：`retake` 重读 / `misread` 口误）——可挑几条告诉用户「去掉了这些重录 / 口误」。
+- `coverage`（0–1）：终稿覆盖率。**低于 0.6（附 `low_coverage`）= 文稿与实拍严重不符** → 提醒用户核对文稿、或考虑无稿重跑。
+- `uncovered_script[]`：**文稿里有、实拍没找到的段（漏读）** → 如实告诉用户「『xx』这段没在录像里找到」；疑似是漏识别而非真漏读时，建议加 `--visual-assist` 重跑。
+- `review_points[]`：建议人工复核处（识别置信度偏低）。
+- `adaptive_rhythm` / `analysis_degraded`：自适应是否生效 / 是否降级到机械规则。
+- 开了 `--visual-assist`：`suspect_omissions` / `stt_recovered`（找回了哪些字）/ `visual_assist_degraded`。
+- `ok=false` 或 `errors` 非空：某格式没出来 → 如实说哪个、为什么。
+
+**据此因势象形调整**（同一毛片可反复剪对比）：覆盖率低 / 漏读多 → 开 `--visual-assist` 或核对文稿重跑；节奏不满意 → 调 `--preset` / 散参数重跑；某格式失败 → 补 `--jianying-draft-dir` / `--reupload` 重跑。
 
-解析 stdout 那行 JSON：
-- `ok=false` 或 `errors` 非空 → 如实告诉用户哪个格式没出来、为什么；必要时按用户意图微调重跑（换 `--preset`、补 `--jianying-draft-dir`、加 `--reupload`）。
-- 确认 `files.gtrk[0]` 存在；要剪映就确认 `jianyingDraftPath` 非空。
+跑完确认 `files.gtrk[0]` 在；要剪映确认 `jianyingDraftPath` 非空。
 
 ## 回给用户（三端打开方式）
 
-- **客户端**：opencut-rewrite 里「打开工程」选 `files.gtrk[0]`（…/gtrk/project.gtrk）。
+- **客户端**：在同合云桌面客户端（OpenCut Gitruck Edition）里「打开工程」选 `files.gtrk[0]`（…/gtrk/project.gtrk）。
 - **剪映**：已自动落到剪映草稿目录（`jianyingDraftPath`），开剪映在项目列表里找**同名工程**即可。
 - **PR/FCP**：Premiere 里「文件 > 导入」`files.xml[0]`（…/xml/premiere.xml）。