@gitruck/cli 1.3.12 → 1.3.14

package/docs/reference.en.md

@@ -232,6 +232,7 @@ This entry exists in the current development workspace. Check `gtrk matrix --hel
 | `--online` | Search external-platform B-roll; supported only for ad-hoc search or dispatch consumption, and mutually exclusive with `--local`. Ad-hoc search requires `--out <result.json>` for results and recovery records; dispatch consumption requires `--project` or `--dispatch`. This submits cloud work, not a purely local operation |
 | `--platforms <list>` | Comma-separated `youtube,vimeo,tiktok,bilibili`; requires `--online`. Defaults to all four registered platforms. Results depend on service and source availability |
 | `--online-session <name>` | Nonempty external-search batch name; requires `--online`. Continue within a batch; changing the name starts a new search and may incur new task charges |
+| `--online-concurrency <n>` | How many external-search needs run at once; requires `--online`. 1–8, default 3. Needs are submitted ahead in dispatch order and still written to the plan in that order; `1` waits for each search before submitting the next |
 
 In dispatch consumption, if a round yields **no layable candidates** while the project already has a `split/broll-plan.json` with candidates (for example the previous cloud or local plan), that plan is not overwritten: this round's plan (with per-request errors and review-only candidates) is saved as `split/broll-plan.online-attempt.json`, the `--json` result carries `plan_kept`, and `planPath` still points at the existing plan. The exit code stays non-zero.
 

package/docs/reference.md

@@ -235,6 +235,7 @@ DO_NOT_TRACK=1 gtrk …   # 业界通用的「不追踪」约定，同样生效
 | `--online` | 检索外部平台 B-roll，仅支持单条 search 或派单消费；与 `--local` 互斥。单条 search 必须给 `--out <结果.json>` 保存结果及断线恢复记录；派单消费需要 `--project` 或 `--dispatch`。这是云端任务，不能按纯本地工具理解 |
 | `--platforms <list>` | 逗号分隔 `youtube,vimeo,tiktok,bilibili`，仅配合 `--online`；不指定时查询已登记的四个平台。实际结果仍取决于服务与来源可访问性 |
 | `--online-session <name>` | 外部检索批次名，仅配合 `--online` 且不可为空；同批次续跑，换名称发起新搜索，可能产生新任务与费用 |
+| `--online-concurrency <n>` | 外部检索同时在跑的需求数，仅配合 `--online`；取 1–8，缺省 3。按派单顺序提前提交、仍按原顺序写进 plan；`1` 为一单跑完再提交下一单 |
 
 派单消费时若这一轮**零可铺候选**而工程里已有带候选的 `split/broll-plan.json`（例如上一轮云端或本地 plan），既有 plan 不会被覆盖：本轮 plan（含逐条报错与待核候选）另存为 `split/broll-plan.online-attempt.json`，`--json` 结果带 `plan_kept`，`planPath` 仍指既有 plan。退出码照旧非 0。
 

package/package.json

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

package/skills/gtrk-matrix/SKILL.md

@@ -124,7 +124,7 @@ gtrk matrix describe --materials <同一素材> --review <工程目录/visual-ov
   gtrk matrix --project <目录> --json                                         # 通用层垫底填空洞
   ```
 - **变奏点**：每层可独立换配方（本地层走 B 先理解再铺）；每层铺完停下让用户看（见「三条业务动线」节）；重铺某层不碰他层。
-- **注意**：概念层重铺请走上面的检索命令（`matrix lay` 从 plan 推导层归属：local→local、云端→common，概念层信息不在 plan 里）。
+- **注意**：每轮检索除主 plan `split/broll-plan.json` 外另存本层快照 `split/broll-plan.<层>.json`（local / online / concept / common）——换层检索会覆盖主 plan，要重铺 / 编辑别的层就用它的快照：`gtrk matrix lay --plan split/broll-plan.concept.json`。概念层 plan 带 `source_layer: "concept"`，`matrix lay` 据此铺进概念层（其余层由 `member_type` 推出）；`gtrk patch --candidate` 与 `matrix status` 也连同快照一起找候选。
 
 ### 配方 F · 图文混排
 
@@ -168,7 +168,7 @@ gtrk matrix describe --materials <同一素材> --review <工程目录/visual-ov
 | 每段多给几个候选 | `--top-k <n>` | 整数 · 派单 `shots` 值（服务端上限 50） | 每 query 候选数上限 |
 | 指定素材类型 | `--material-class <c>` | `real_shot` \| `concept` · 栏目策略 | 仅 internal 矩阵成员口 |
 | 命中镜头带上原片前后镜头 | `--neighbors <n>` | 0–5 整数 · `matrix search` 为 0、派单检索为 2 | 仅 internal 矩阵成员口的概念素材；每侧 n 条，**不参与自动铺轨**（见配方 G）；非法值发请求前就报错 |
-| 填充门槛 | `--score-floor <f>` | 浮点 0–1 · `0.2` | 低于不采纳、槽位留空——口播工程里留空处由候选轨补纯黑片；调完必看空洞告警 |
+| 填充门槛 | `--score-floor <f>` | 浮点 0–1 · `0.2` | 卡的是**片段分**（plan 里 `segments[].score`），**不是**每条候选的 `score`——检索结果的整条分与片段分出自不同模型、差得远（整条 0.35、片段 0.19 很常见）。低于不采纳、槽位留空——口播工程里留空处由候选轨补纯黑片；调完必看空洞告警。铺轨告警「整条分过了地板、片段分全低于它」（`lay.floor_hidden`）= 被地板藏起来的候选：按报出的片段分调低地板，或钉选那条 |
 | 切点对齐字幕句 | `--cut-align <r>` | 浮点 0–1 · `0.7`（`0`=关闭） | 三七开拍板：约七成字幕句起点恰逢镜头切点、三成有意错开；句级时码取 transcript 重投影（降级自动回旧节奏并告警）；开启时结果 JSON `lay.cut_align` 报实测比例 |
 | 主轨空洞填充 | `--gap-fill <m>` | `fast` \| `solid`（默认）\| `none` | **仅音频驱动工程主轨**（口播工程不适用零回归）：fast=放宽地板随便填候选→延长相邻颗粒→**跨 beat 借候选**→**次地板补真画面**→仍不够才黑片；借来的画面与本段稿子相关性弱、次地板槽是不到 1.2s 的快切，两者都会在日志里**指名报出**（`kind` 为 `borrowed` / `subfloor`）——那是如实告知，**不是缺陷，别当 bug 上报**；solid=黑片垫齐（精修一眼看出没匹配到）；none=留 gap（客户端主轨磁吸会吸除 gap 致画面与配音错位，慎用）；生效时结果 JSON `lay.gap_fill` 报明细 |
 | 编排交给云端跑 | `--arrange <m>` | **按素材来源自动定档，一般不用传** | 铺**自己电脑里的素材**→`cloud`（编排在服务端，按编排量计费）；铺**素材矩阵的素材**→`local`（编排仍在本机、不计费，逐字不动）。`shadow`=本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` **不受理**；云端拿不到产物时**直接报错**，不会换算法把活干完。⚠️ **它不是省钱开关**——矩阵素材要付检索费，两条路都花钱、只是花在不同环节，MUST NOT 对用户说「用本地就不花钱」 |
@@ -476,7 +476,9 @@ gtrk matrix --project "<split 产物目录>" [--lay N] [--score-floor F] [--top-
 | 某候选非用不可 | 编辑 plan：该 result 标 `pinned:true` → `matrix lay`。钉选是落位保证（免负词/地板/不二用抢占/紧邻避让），`lay.pinned.yielded` 非空说明确实钉多了在打架，名单逐段指名 |
 | 想定先后顺序 / 想钉准轨上位置 | 钉选管不了第几槽（它只把整条 result 排到最前）。同分的段按数组顺序落槽，要调先后就调 `results` / `segments` 的数组顺序；要钉准轨上位置用 `arrange_mode:"direct"` + `direct_slots`（引用段、硬出处段的本职）；出片 QC 换段照「出片 QC 交回来的换段」第 4 步 |
 | **出现空档补黑 / 黑底空洞告警** | 不是故障：照 `lay.blackBedHoles` 逐段报给用户，出路=调低 `--score-floor` / opencut 手动补片 / 动线②云端垫底 |
+| **外网检索太慢** | 缺省已同时跑 3 单（`--online-concurrency <n>`，1–8；plan 与日志仍按派单顺序，进度日志带 beat 名）；服务端排队明显时调低，`1` = 一单跑完再提交下一单 |
 | **`--online` 结果带 `plan_kept`** | 外网这轮零可铺候选，**既有 plan 没被覆盖**（`planPath` 仍是上一轮的，可直接 `matrix lay`）；本轮逐条报错与待核候选在 `plan_kept.online_attempt_path`，照它说明失败原因 |
+| **外网「0 条自动候选，另有 N 条待人工确认」**（`counts.review_only` > 0） | 不是失败、也**不要重跑**（同参重跑结果不变，换描述 = 新建计费任务）：需求里写了地点 / 事件 / 年份 / 素材类型这类硬条件，服务端在画面上核实不了，整批进了 plan 的 `queries[].online.review_candidates`（铺轨后也进客户端候选池）。你按标题 / 片段裁定，把贴题的条目**原样搬**进同一 query 的 `results`（可加 `pinned:true`）后 `gtrk matrix lay --plan <plan>`。硬条件只写真正非满足不可的；只是偏好（「最好是日本的」）写进 `intent` / `visual_description` |
 | 每段候选太少不够挑 | `--top-k` 调大重跑 |
 | 某段有空槽 / 想补特定意象 | `gtrk matrix search "<英文长句场景描述>" --project <目录> --json` 单条补检；影视解说类补检记得带 `--source-window` 保时序 |
 | **精修某个 beat / 用户指着某个空位** | 先 `gtrk matrix status --project . --beat <id> --json` 看现状（时间窗、候选池、轨上片段、空缺），再决定补候选还是直接放上轨；**不要**去翻 `split/broll-plan.json` 和 `.gtrk`（见「精修某个 beat 前」节） |
@@ -605,7 +607,7 @@ gtrk patch replace --project <dir> --clip <clip_id> --candidate <clip_id> --json
 
 - `add`：用 `--to` 指落点（不收 `--at`）；时长缺省 = 这个空位的长度，出点贴右邻；候选还没落地会顺手下载预览、登记素材。落点被占就拒（列出挡路片段），被黑底补片占着就改用 `replace`。
 - `replace`：起点、轨、`clip_id` 不动，只换素材与源窗；新素材不够长会**如实缩短**、不拉伸——回执出 `replace_shortened` 时把前后时长告诉用户。
-- 精修期**不要**整轮 `matrix lay` 或 `--force-relay`：`add` / `replace` 放上去的片段不带产出方身份，下一次铺轨会把那条轨当用户轨保留，不会把你的精修剥掉。
+- 精修期**不要**整轮 `matrix lay` 或 `--force-relay`：`add` / `replace` 放上去的片段带 patch 自己的产出方身份，所在候选轨判「已编辑」——**同一层**再铺会被拒（`tracks_edited`，工程零改动；不剥你的精修、也不另起一条），**别的层**照常铺、这条轨随层带保留。确要丢掉精修重铺本层才加 `--force-relay`，先问用户。
 
 `gtrk matrix` 铺的片段 `clip_id` 形如 `B05-local-broll-0-3`（beat-来源层-broll-轨内序-槽序；补黑片为 `-bedfill-`），
 各层互不撞名，`--clip` 可直接寻址。