@gitruck/cli 0.1.1 → 0.2.1

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,13 +67,34 @@ 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. 产物结构 + 三端打开
 
 ```
 <毛片名>-video-project-<YYMMDD-HHMMSS>/
-├── gtrk/project.gtrk        → 客户端（opencut-rewrite）：「打开工程」选它
+├── gtrk/project.gtrk        → 客户端（OpenCut Gitruck Edition）：「打开工程」选它
 ├── jianying/                → 剪映：已自动拷进剪映草稿根，剪映里直接见草稿
 │   ├── draft_content.json
 │   └── draft_meta_info.json （仅当探到/指定了剪映草稿目录才有）
@@ -91,19 +118,23 @@ 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`（剪了多少）；`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` / 散参数重跑（同毛片可反复剪对比）。
 - 确认产物目录在、`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. 典型调用
 
+> 下面示例为聚焦某个参数、**省略了 `--json`**；你（agent）实际调用**一律带 `--json`**（见 §4），stdout 才只剩结果 JSON、便于解析。
+
 ```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 +144,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,14 +25,24 @@
 
 ---
 
+## 获取 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 + /gtrk-oralcut skill + 配置（填 API Key、自动扫剪映目录）
-npm i -g @gitruck/cli && gtrk install
-#   或免全局安装直接用：npx @gitruck/cli install
+npm i -g @gitruck/cli@latest && gtrk install
+#   或免全局安装直接用：npx @gitruck/cli@latest install
 
 # 2) 剪一条（剪完自动打开产物目录）
 gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
@@ -97,7 +107,7 @@ 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。
 
 ### 其它
 

package/dist/index.js

@@ -2475,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);
   });
 }
@@ -2509,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
@@ -2526,6 +2562,24 @@ 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;
+    }
+    for (const [k, v] of Object.entries(extraParams)) {
+      const cur = p[k];
+      const bothObj = !!cur && !!v && typeof cur === "object" && typeof v === "object" && !Array.isArray(cur) && !Array.isArray(v);
+      p[k] = bothObj ? { ...cur, ...v } : v;
+    }
     return p;
   };
   log.step("② 提交智能口播剪辑任务…");
@@ -2591,6 +2645,7 @@ async function runOralCut(input, opts) {
       outDir,
       files: byFormat,
       jianyingDraftPath: jianyingDraftPath ?? null,
+      report: result.report ?? null,
       errors,
       taskId,
       fileId: up.fileId

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@gitruck/cli",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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,105 @@ 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` | 一元 flag：传即关闭 · 自适应默认开 | 是否定 flag（不接受 `=值` 赋值）；关了改用固定标点停顿表 |
+| 剪映草稿目录（非标准位置） | `--jianying-draft-dir <目录>`（或 `auto`） | 路径 · 读 init 配置 / 自动探测 | 出剪映可直开草稿需要它 |
+| 工程落盘到别处 | `--out <目录>`（或 `-o`） | 路径 · 缺省 `<毛片同目录>/<毛片名>-video-project-<时间戳>` | 想把产物放指定位置时用 |
+
+**更细的节奏散参数**（无一等 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`=硬切；**需配 `--render`**（属成片音频淡化，不开 --render 云端忽略此字段） |
+
+**节奏预设表 · 完整值**（选最贴内容类型的，再逐项覆盖散参数；「默认」列 = 不选预设时的基线，也即各标点的默认停顿）：
+
+| 参数（秒） | `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` → `duration_after`：剪了多少（如 114.7s → 68.6s）。
+- `script_source` + `final_script`：终稿来源与内容（`script_source`=`user` 用户给稿 / `rebuilt` 智能重建）。**无稿重建（`rebuilt`）时务必把 `final_script` 回给用户核对**——那是机器猜出来的终稿，可能跟本意有出入。
+- `dropped[]`：剔掉了哪些段（元素 `{start,end,asr_text,reason}`，`reason`：`retake` 重读 / `misread` 口误·弃读·终稿外内容）——可挑几条告诉用户「去掉了这些重录 / 口误或非终稿内容」。
+- `coverage`（0–1）：终稿覆盖率。**低于 0.6（附 `low_coverage`）= 文稿与实拍严重不符** → 提醒用户核对文稿、或考虑无稿重跑。
+- `uncovered_script[]`：**文稿里有、实拍没找到的段（漏读）** → 如实告诉用户「『xx』这段没在录像里找到」；疑似是漏识别而非真漏读时，建议加 `--visual-assist` 重跑。
+- `review_points[]`：建议人工复核处（`{time,note}`，识别置信度偏低）。
+- `insufficient_breaks[]`：源素材留白不足、停顿没达到设定值的位置（`{time,want,got}`）——想让停顿更足可调 `--preset`/散参数，但受原素材限制。
+- `rhythm_preset`（实际采用的预设名、无预设为 `null`）/ `adaptive_rhythm`（自适应是否生效；生效时另有 `pause_profile` 说话人停顿画像，调参参照）/ `analysis_degraded`（是否降级到纯机械规则）。
+- 开了 `--visual-assist`：`suspect_omissions` / `stt_recovered`（找回了哪些字）/ `visual_assist_degraded`。
+- `ok`：`true` = 全部格式成功、`errors` 为空；只要有一个格式失败 `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）。