@gitruck/cli 0.2.0 → 0.2.1

package/AGENT.md

@@ -69,7 +69,7 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 
 **细节微调 —— 按用户诉求因势象形、自由组合**（上表是常用一等 flag；下面是节奏细调 + 完整取值）。你有云端全部参数，按需自由决定用哪些。**唯一要求：名字 / 取值 / 范围照文档用**（别记错拼错）；传越界云端报 `6016` 附原因、照改即可（乱传不产错误成片、只明确报错）。没特别诉求就跑默认。
 
-- **剪不准 / 剪掉真内容 / 有句话没剪进去** → `--visual-assist`：ASR 之外并行跑人脸 + 说话检测，画面在说话却没识别出字的地方**保护不剪**并重识别捞回，捞不回的进 `report.review_points` 复核；引擎挂了只降级不失败、不额外计费、绝不凭空生成。**「剪不准」的兜底。**
+- **剪不准 / 剪掉真内容 / 有句话没剪进去** → `--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`。
@@ -94,7 +94,7 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 
 ```
 <毛片名>-video-project-<YYMMDD-HHMMSS>/
-├── gtrk/project.gtrk        → 客户端（opencut-rewrite）：「打开工程」选它
+├── gtrk/project.gtrk        → 客户端（OpenCut Gitruck Edition）：「打开工程」选它
 ├── jianying/                → 剪映：已自动拷进剪映草稿根，剪映里直接见草稿
 │   ├── draft_content.json
 │   └── draft_meta_info.json （仅当探到/指定了剪映草稿目录才有）
@@ -121,7 +121,7 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 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` / 散参数重跑（同毛片可反复剪对比）。
+- **读 `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` 非空 → 如实告知哪个格式失败、原因。
 - 然后**回给用户**：产物目录路径 + 三端各自怎么打开（客户端选 `gtrk/project.gtrk`、剪映已在项目列表、PR 导入 `xml/premiere.xml`），并**据 `report` 给一句交代**（剪了多久 → 多久、去掉了什么、有无漏读需复核）。
@@ -130,6 +130,8 @@ gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动
 
 ## 5. 典型调用
 
+> 下面示例为聚焦某个参数、**省略了 `--json`**；你（agent）实际调用**一律带 `--json`**（见 §4），stdout 才只剩结果 JSON、便于解析。
+
 ```bash
 # 有稿 + 剪完就看（最常见；剪完默认自动打开产物目录，无需额外 flag）
 gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt" --json

package/dist/index.js

@@ -2575,7 +2575,11 @@ async function runOralCut(input, opts) {
       if (Object.keys(r).length)
         p.render = r;
     }
-    Object.assign(p, extraParams);
+    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("② 提交智能口播剪辑任务…");

package/package.json

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

package/skills/gtrk-oralcut/SKILL.md

@@ -41,9 +41,10 @@ description: 智能口播剪辑闭环——把一条口播原视频(毛片)通
 | 成片画质 | `--crf <n>`（配 `--render`） | 整数 14–28 · `18` | 越小越清晰 / 越大体积越小 |
 | 成片编码 | `--codec <c>`（配 `--render`） | `h264` · `h264` | 当前仅 h264 |
 | 节奏松紧 | `--preset <名>` | `steady`/`concise`/`compact` · 默认 `concise` | 不传即 CLI 默认发 `concise`（精练）；见下方预设表，铺底后可逐项覆盖 |
-| **剪不准 / 剪掉真内容 / 有话没剪进去** | `--visual-assist` | 开关 · 关 | **视觉找补兜底**：画面说话检测保护疑似漏识别段不被误剪并重识别捞回；不额外计费、绝不凭空生成 |
-| 别随说话人节奏自适应 | `--no-adaptive-rhythm` | 开关 · 自适应默认开 | 关了改用固定标点停顿表 |
+| **剪不准 / 剪掉真内容 / 有话没剪进去** | `--visual-assist` | 开关 · 关 | **视觉找补兜底**：画面说话检测保护疑似漏识别段不被误剪并重识别捞回（需说话人面部基本可见）；会增加处理耗时（与主识别并行、约两者较大值），但不额外计费、绝不凭空生成 |
+| 别随说话人节奏自适应 | `--no-adaptive-rhythm` | 一元 flag：传即关闭 · 自适应默认开 | 是否定 flag（不接受 `=值` 赋值）；关了改用固定标点停顿表 |
 | 剪映草稿目录（非标准位置） | `--jianying-draft-dir <目录>`（或 `auto`） | 路径 · 读 init 配置 / 自动探测 | 出剪映可直开草稿需要它 |
+| 工程落盘到别处 | `--out <目录>`（或 `-o`） | 路径 · 缺省 `<毛片同目录>/<毛片名>-video-project-<时间戳>` | 想把产物放指定位置时用 |
 
 **更细的节奏散参数**（无一等 flag，用 `--param 键=值` 或嵌套 `--params-json`）：
 
@@ -53,7 +54,7 @@ description: 智能口播剪辑闭环——把一条口播原视频(毛片)通
 | `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.audio_crossfade_ms` | `--params-json '{"render":{"audio_crossfade_ms":12}}'` | 0–50 · `8` | 切点淡化毫秒，`0`=硬切；**需配 `--render`**（属成片音频淡化，不开 --render 云端忽略此字段） |
 
 **节奏预设表 · 完整值**（选最贴内容类型的，再逐项覆盖散参数；「默认」列 = 不选预设时的基线，也即各标点的默认停顿）：
 
@@ -87,14 +88,16 @@ gtrk oralcut "<毛片绝对路径>" [--script "<txt路径>"] [--preset steady|co
 
 `--json` 的 stdout 那行带 **`report`**（云端返回的原始剪辑报告对象，字段按需读、个别可能缺，读前判空）——读它，别只回一句"剪好了"：
 
-- `duration_before` → `after`：剪了多少（如 114.7s → 68.6s）。
-- `dropped[]`：剔掉了哪些段（`reason`：`retake` 重读 / `misread` 口误）——可挑几条告诉用户「去掉了这些重录 / 口误」。
+- `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[]`：建议人工复核处（识别置信度偏低）。
-- `adaptive_rhythm` / `analysis_degraded`：自适应是否生效 / 是否降级到机械规则。
+- `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=false` 或 `errors` 非空：某格式没出来 → 如实说哪个、为什么。
+- `ok`：`true` = 全部格式成功、`errors` 为空；只要有一个格式失败 `ok` 即 `false` 且 `errors` 非空（其余格式仍可用）→ 如实说哪个格式没出来、为什么，别谎报三端都好。
 
 **据此因势象形调整**（同一毛片可反复剪对比）：覆盖率低 / 漏读多 → 开 `--visual-assist` 或核对文稿重跑；节奏不满意 → 调 `--preset` / 散参数重跑；某格式失败 → 补 `--jianying-draft-dir` / `--reupload` 重跑。