@gitruck/cli 1.3.11 → 1.3.12

package/AGENT.md

@@ -271,6 +271,7 @@ gtrk split <拆分稿.json> --project <目录> --md --json  # ⑤ 校验落地
 - **transcript 缺失**（旧任务）→ 明确报错引导「用新版本重跑 oralcut（恒出工程所需的结构化 transcript）」，不做降级猜测；`gtrk transcript` 只产人读 Markdown，不能替代 split 所需的结构化词表。
 - **只动 `struct_meta.split`**：写回不碰 materials/tracks，配合客户端「保存 → 发起 → 写回 → 重载」闭环（opencut 联动）。
 - **下游消费**：`dispatch.json` 的 `film_broll` 队列 → `gtrk matrix --project <dir>`（B-roll 双口检索 → `split/broll-plan.json` 候选清单;url 24h 过期,重跑即重签）；`mg` 槽位表（去品牌化前 `rrv_mg`）→ `gtrk mg` 铺轨 / real-roam-viz 产颗粒；`ai_drama` 队列 → ai-drama-prompter。
+- **看某个 beat 的现状**：`gtrk matrix status --project <dir> --beat <id>[,<id>…] --json`（不带 `--beat` = 全部 B-roll beat 一行一个概要）。只读、零网络、零写盘，读盘上工程：时间窗（现场重投影，降级时标明原因）、候选池（精简字段、不带下载地址）、plan 里其余候选的条数与前 5、时间窗内各视频轨上的片段与类别、主轨之上的空缺（另列只有黑底补片的区间）、`revision`（可作 `gtrk patch --expected-revision`）、各候选轨剥离判定与整轮重铺会不会被 `tracks_edited` 拒。**精修前先跑它，别去翻 `split/broll-plan.json` 与 `.gtrk`**。beat 不存在 ⇒ `ok:false`、非 0 退出并列出全部已知 beat。
 
 > **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
 
@@ -363,8 +364,13 @@ gtrk patch trim  --project <dir> --clip c2 --out -1s       # 改时长（出点
 gtrk patch split --project <dir> --clip c2 --cut 5.5       # 切成两段
 gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 gtrk patch set   --project <dir> --total max               # 改顶层总长（工程级）
+gtrk patch add     --project <dir> --track video:2 --to 263.733 --candidate <clip_id>   # 把候选放上空位
+gtrk patch replace --project <dir> --clip <clip_id> --candidate <clip_id>               # 原地换源
 ```
 
+**精修期把候选放上空位用 `patch add`；空位被黑底补片占着用 `patch replace`**——不要为此整轮 `matrix lay --force-relay`，也不要手改 `.gtrk`。
+先 `gtrk matrix status --project <dir> --beat <id> --json` 看空缺在哪、候选有哪些，再放。
+
 **寻址两条路**（互斥，二选一）：
 
 | | 用法 | 说明 |
@@ -377,7 +383,7 @@ gtrk patch set   --project <dir> --total max               # 改顶层总长（
 
 ⚠️ **空档（gap）不能用 `--clip ""` 寻址** —— 契约允许多个 gap 共享 `clip_id=""`，它不构成地址；用 `--track/--at`。
 
-**四个动作的参数**：
+**元素级动作的参数**：
 
 | 动作 | 参数 | 语义 |
 |---|---|---|
@@ -389,6 +395,10 @@ gtrk patch set   --project <dir> --total max               # 改顶层总长（
 | `set` | `--muted` / `--no-muted` / `--volume <gain>` / `--opaque` | 元素级参数。`--volume` 是**线性增益不是 dB**、须 > 0——`--volume 0` 报 `volume_zero_use_muted`（各消费方把 `volume: 0` 读成原音量），静音用 `--muted`。**轨静音是总开关**：片段所在轨已静音时 `--no-muted` 报 `track_muted_master`（`patch set` 不改轨级参数，请在客户端点开轨喇叭）；`--audio-track` 把原本出声的片段移进静音轨报 `audio_track_target_muted` |
 | | `--audio-fade-in <sec\|Nf>` / `--audio-fade-out <sec\|Nf>` | 音频淡入 / 淡出时长（视频轨原声或音频轨片段；颗粒与空档拒收）。秒或帧、整毫秒；**设 0 即删键**；与另一侧之和**超过片段时长即硬拒**并报本侧最多可设多少（不替你按比例缩）；不接受带符号的相对值。`trim` / `split` 会自动维护淡变（剪短放不下时按比例缩并在回执出 `audio_fade_clamped`） |
 | | `--total <sec\|Nf\|max>` | 顶层总长。**工程级 op，与元素寻址互斥** |
+| `add` | `--track video:<N> --to <sec\|Nf>` + `--candidate <clip_id> [--beat <id>]` 或 `--material <id>`；可选 `--from <sec>` / `--dur <sec\|Nf>` | 把候选或已登记素材放到视频轨的空位上。⚠️ **`add` 用 `--to` 指落点、不收 `--at`**（`--at` 恒为寻址）。候选素材没登记时顺手下载预览、登记（与 `matrix lay` 同一份实现），已登记不重下。缺省时长 = 落点所在空位的长度（出点与右邻起点同一帧，零缝零叠）；入点缺省与客户端拖候选同一取窗。落点与非空档元素重叠即拒 `add_overlap`（挡路的是黑底补片时指路 `replace`），覆盖到的空档让位；源片不够长钳短告警 `add_clamped`、不拉伸；图片候选不收；不建轨、不 ripple。新片段 `<beat>-add-<n>`、不带 `producer` |
+| `replace` | `--clip` 或 `--track video:<N> --at` + `--candidate` / `--material`；可选 `--from` | 原地换源：只换 `material` 与源窗，起点 / 轨 / `clip_id` / 倍速 / 变换 / 填充 / 转场 / 关键帧不动；新素材不够长**如实缩短**（`replace_shortened`），不拉伸；删去 `producer`（下一次 `matrix lay` 把这条轨当你的轨保留）；镜像对不收 |
+
+**`add` / `replace` 的先后**：先按自述值把全部改动算一遍、全档校验（零下载零写），过了才落地，落地完再读工程、写回；`--dry-run` 只做第一步，回执 `would_download` 说真跑会不会下载。回执 op 另带 `source{kind, id, beat, material_id, landed, path}`（`landed`：existing 早已登记 / reused 代理已在盘上 / downloaded 本次下载 / registered 本地素材直引）与 `add` 的 `gaps_consumed`。
 
 **通用**：`--dry-run` 只算不写；`--json` 回执到 stdout（人读日志转 stderr）；
 `--ops <file|->` 批量事务（一次读、全算、全校验、一次写；**任一条失败零写**并报第几条）。

package/CHANGELOG.md

@@ -11,6 +11,27 @@
 
 ## 未发布
 
+## 1.3.12（2026-11-05）
+
+- 新：`gtrk patch add --track video:<N> --to <秒> (--candidate <clip_id> [--beat <id>] | --material <id>) [--from <秒>] [--dur <秒|Nf>]`，把一条 B-roll 候选或已登记素材放到视频轨的空位上：候选先查工程候选池（含邻居）再查 `split/broll-plan.json`，素材还没登记时顺手下载预览到 `assets/broll-preview/` 并登记（与 `gtrk matrix lay` 同一份落地实现，已登记的不重下）——`matrix source-import` 之后一条命令就能上轨。缺省时长取落点所在空位、出点与右邻同一帧；入点缺省与客户端拖候选同一取窗。落点与已有片段重叠即拒并列出挡路片段（黑底补片指路 `patch replace`），覆盖到的空档让位；源片不够长钳短告警、不拉伸；图片候选不收；不建轨、不 ripple。新片段 `<beat>-add-<n>`、不带产出方身份（add-patch-insert-replace）。
+- 新：`gtrk patch replace (--clip <id> | --track video:<N> --at <秒>) (--candidate … | --material …) [--from <秒>]`，原地换源：只换素材与源窗，起点 / 轨 / `clip_id` / 倍速 / 变换 / 填充 / 转场 / 关键帧不动；新素材不够长如实缩短（`replace_shortened`），不拉伸；去掉产出方身份，下一次 `gtrk matrix` 铺轨把这条轨当用户轨保留；镜像对不收（add-patch-insert-replace）。
+- `add` / `replace` 先按自述值把全部改动算一遍、全档校验，过了才下载落地，落地完再读工程写回；`--dry-run` 不下载、不写文件，回执带 `would_download`；`--ops` 条目可用这两个动作，同批先统一落地。回执 op 另带 `source` 与 `gaps_consumed`。预览下载失败零写、非 0（`preview_download_failed`），已落盘的预览留作下次复用（add-patch-insert-replace）。
+- 修：`gtrk patch` 的未知动作报错与 `--ops` 合法动作列表此前漏列 `seal` / `snap`，现在列全（`seal` / `snap` 是轨级动作，只能单发）（add-patch-insert-replace）。
+- 改：`gtrk matrix` 铺轨的候选落地（代理文件名、复用 / 下载、ffprobe 实测、素材条目）抽到 `src/lib/broll-landing.ts`，与 `patch add / replace` 共用；同输入铺轨产物、日志与 `--json` 回执与抽出前逐字节相同（add-patch-insert-replace）。
+- 新：`gtrk matrix status --project <工程目录> [--beat <id>[,<id>…]] [--json]`，一条命令看清某个 beat 的现状：时间窗（现场重投影，降级时标明原因）、候选池（精简字段、不带下载地址，标出预览是否已落地、已用在哪些片段上）、plan 里其余候选的条数与得分最高 5 条、时间窗内各视频轨上的片段与类别、主轨之上的空缺（另列只有黑底补片的区间，短于一帧的缝不算）；不带 `--beat` 时全部 B-roll beat 一行一个概要。顶层给工程 `revision`（可作 `gtrk patch --expected-revision`）、各候选轨剥离判定与整轮重铺会不会被 `tracks_edited` 拒。只读、不联网、不需要 Key、不写任何文件；beat 不存在时退出码 1 并列出全部已知 beat（add-matrix-beat-status）。
+- 新：外网检索授权码。`gtrk matrix --online` 检索和 `gtrk matrix source-import` 导入完成后，CLI 用当前 Key 向服务端取这次检索的授权码，写进每条外网候选（含待核候选）的 `origin.search_grant`，plan、回执与工程都带上；工程交给别的账号后，对方凭它在客户端读候选、确认 B-roll。服务端还不支持（404）、未启用或网络失败时照常完成，只是不带码，终端提示一行（派单多条检索时同一原因只提示一次）。格式不对（不是 `g1.` 加 43 位 base64url）的授权码解析时丢掉，候选照常可用；`gtrk matrix lay` 原样带进工程（link-online-broll-search-grant-cli）。
+- 新：`gtrk matrix grant --project <工程目录或 .gtrk>`，给工程补检索授权码（授权码上线前的老工程也适用）。只为一个码都没有的检索取码，同检索已有码的直接沿用；取不到的（不是当前账号的检索、已删除、服务端不支持）逐个列任务号与原因，候选不动，退出码非 0；输出「补了几个、已有几个、取不到几个」，`--json` 给 `granted` / `existing` / `failed`。工程没有变化时不写盘，有变化时原子写回、只改外网候选的 `origin`（link-online-broll-search-grant-cli）。
+
+- 新：`gtrk cover embed <工作台.html> [--bg-16x9 <图>] [--bg-4x3 <图>] [--bg-3x4 <图>] -o <输出.html>`。封面工作台把背景图按尺寸压成 JPEG（16:9 长边 ≤1280、4:3 ≤1600、3:4 ≤1400）并以 base64 嵌进去，替掉 `/gtrk-cover` 里「临时脚本压缩 + 注入」那一步；纯本地、零计费，压缩结果经管道回内存、不写中间图片。`-o` 必填（可与输入同名），没给图的尺寸占位符保留并提示，工作台超过 600 KB 提示、超过 1 MB 告警（link-in-app-agent-capability-shelf）。
+- 新：`gtrk ai-drama validate <候选分镜稿.md> [...]`。`/gtrk-ai-drama` 落盘前的分镜稿校验收成子命令，判据、输出与退出码与随包的 `scripts/validate-storyboard.mjs` 逐字节一致（脚本再保留一个版本周期）；即剪内置 AI 只许运行 gtrk，这一步此前跑不了（link-in-app-agent-capability-shelf）。
+- 新：`gtrk-cover` / `gtrk-tools` / `gtrk-transcript` / `gtrk-matrix` / `gtrk-ai-drama` / `gtrk-music-visualizer` / `gtrk-ref-reading` 标 `in_app_agent`：即剪内置 AI 每轮常驻这 7 个 skill（加上原来的 4 个共 11 个），客户端输入区「常驻能力」里的封面制作、小工具等入口据此出现；测试闸照常守住「要 agent 执行的命令全是 gtrk」（link-in-app-agent-capability-shelf）。
+
+## 1.3.11（2026-11-04）
+
+> 本段补录于 2026-11-05：1.3.11 于 2026-11-04 从 `7f605ce`（版本号改动未提交的工作区）发出，当时没写版本段，改动留在「未发布」里。
+> 归属按包体抽查：本机装的 1.3.11 `dist/index.js` 里有 `--neighbors`、转场、音频淡变、`volume_zero_use_muted`、`--redraw`，
+> 没有检索授权码、`patch add` 的 `would_download`、分镜稿校验——与「`7f605ce` 之前进仓的归 1.3.11、之后的归 1.3.12」一致。
+
 - 新：工程片段的**转场**（即剪客户端写进 `.gtrk` 的 `transition_in` / `transition_out` / `transition_next`）CLI 全程认得、本期不产出。任何命令都原样带着转场走，新铺的片段不带转场。`gtrk patch split` 入场转场留前段、出场与接下一段的转场归后段（此前两半都复制同一个转场，前段那个立刻悬空、切口凭空多出一个入场）；每次 `gtrk patch`（单发或整个 `--ops` 批）写回前对改动过的轨统一维护：下一段被移走后不再紧邻的「两段之间」转场删除（不改挂到新邻居），剪短后放不下的按帧缩短（先头后尾），回执逐条给 `transition_dropped` / `transition_shortened`；与本次编辑无关的存量转场问题只报不拦。`matrix` / `mg` / `ai-drama` / `pip` / `audio` / `composite lay` 重铺自产轨时，被替换掉的片段若带你在客户端加的转场，日志与 `--json` 回执给出 `replacedTransitionClips`。`gtrk project export` 上行前把工程规整一遍（悬空、越界的删缩并列进 `result.json` 的 `transitions`，盘上工程不动），免得云端整单拒收；云端各格式本期不承接转场，导到剪映 / Pr 里是硬切，回执里的 `transition_not_carried` 逐条打出。`gtrk render` 本期按硬切出片并计 `transition_not_carried`（无转场工程滤镜串逐字节不变）。转场颗粒目录不随 npm 包分发：工程带转场时才从后端拉 `cloud/static/assets/transitions/catalog.json`，缓存在与客户端共用的统一静态资源缓存 `~/.gitruck/cache/transitions/catalog.json`（24 小时一刷）；离线、目录不可用或颗粒不在目录里时转场原样保留，命令照常工作。⚠️ **编辑含转场的工程需本版本及以上**：旧版不报错，但切分会复制转场、移动后留下悬空转场、重铺静默删掉用户的转场、上云被拒收（link-gtrk-clip-transitions）。
 
 - 改：`gtrk mg fetch` 的 MG 区块与文字模板（`--source text`）改走统一静态资源下发，目录格式与本机缓存同即剪客户端共用一套（unify-static-resource-delivery）。

package/README.en.md

@@ -189,6 +189,7 @@ For AI-generated story scenes, connect [Gitruck AI Drama Desk](https://github.co
 | Component | What it does | Output |
 | --- | --- | --- |
 | `gtrk CLI` | Understands the request in your agent, orchestrates workflows and manages `.gtrk` projects | An editable video project |
+| `gtrk ai-drama validate` | Checks a storyboard draft against the workbench parser's contract before import | One result line per draft |
 | `AI Drama Desk` | Imports storyboards, manages characters and styles, generates keyframes / I2V clips and exports a handoff package | A `return-v1` clip package + `manifest` |
 | `gtrk ai-drama lay` | Places exported clips back into the project by beat windows | A dedicated AI video track |
 

package/README.md

@@ -189,6 +189,7 @@ flowchart LR
 | 组件 | 负责什么 | 产物 |
 | --- | --- | --- |
 | `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
+| `gtrk ai-drama validate` | 分镜稿导入工作台前，校验它符合工作台解析器的硬契约 | 每份稿一行校验结果 |
 | `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `manifest` |
 | `gtrk ai-drama lay` | 把工作台导出的片段按 beat 区间铺回工程 | 独立 AI 视频轨 |