@gitruck/cli 1.3.1 → 1.3.4

package/AGENT.md

@@ -39,28 +39,28 @@
   （如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）。
   需要引用媒体时**用原路径引用**，不做副本。
 - 临时文件（抽帧图 / 中间物等）一律放系统 temp 且**用完即删**（含中断 / 失败路径也要清干净）。
-- **交付物 SHALL 直写工程目录，MUST NOT 中转暂存**。
+- **交付物 SHALL 直写工程目录，MUST NOT 中转暂存**。
   产颗粒 / 产工程 / 产派单稿时，**写入路径本身**就必须是工程目录里的最终路径；
   MUST NOT 先写 agent 自有工作目录（会话工作区 / `work/` / 暂存区）再拷进工程。
-  · 中转本身即违规，体积不构成例外（体积不是豁免理由）；抽帧图等不交付的中间物走系统 temp，用完即删。
-  · 交付物没有暂存态，避免工程正本与副本漂移。
+  · 中转本身即违规，体积不构成例外（体积不是豁免理由）；抽帧图等不交付的中间物走系统 temp，用完即删。
+  · 交付物没有暂存态，避免工程正本与副本漂移。
 
-**在 gtrk-cli 仓库自身里跑真机走查时：**
+**在 gtrk-cli 仓库自身里跑真机走查时：**
 
 - **仓根不落任何产物**。工作区一律 `--out .runs/<名字>`；命令回执与日志一律重定向进
   `.runs/_receipts-<日期>/`，例如
   `gtrk audio lay ... > .runs/_receipts-260823/audio-lay-out.json 2> .runs/_receipts-260823/audio-lay-stderr.log`。
 - **MUST NOT** 使用 `> foo-out.json 2> foo-stderr.log` 这类**落在仓根**的重定向，
   也 **MUST NOT** 让 `--out` 缺省落到仓根。
-- 仓根文件可能包含素材绝对路径和本机目录结构；`.gitignore` 只能兜底，第一道闸仍是落点纪律。
+- 仓根文件可能包含素材绝对路径和本机目录结构；`.gitignore` 只能兜底，第一道闸仍是落点纪律。
 
 ---
 
-## 工程文件改动纪律（全局 MUST）
+## 工程文件改动纪律（全局 MUST）
 
 - **agent MUST NOT 裸手改 `.gtrk` JSON。** 元素级编辑（挪位置 / 改时长 / 切开 / 改参数）
   一律走 **`gtrk patch`**。
-- `.gtrk` 一个片段的时码是**两套并存**的
+- `.gtrk` 一个片段的时码是**两套并存**的
   （`clip_st`+`clip_ed` 与 `clip_st`+`duration`）。改 `duration` 不同步 `clip_ed`，
   **客户端 importer 优先读 `clip_ed`**，后端可能不强校验它，导致命令成功但实际出点未变。
 - 另外轨道时基端点要落在 `video_rate` 的帧边界上，浮点秒累加会漂。这两件 `gtrk patch`
@@ -68,7 +68,7 @@
 - **例外只有一个**：铺自产物的那几条既有链路（`gtrk matrix` 铺轨、`gtrk mg` 铺颗粒、
   `gtrk audio` / `gtrk subtitle` 建新轨）—— 它们只动自己新建的东西，不改既有 clip 的时码。
 
-## 标定数据落点纪律（全局 MUST）
+## 标定数据落点纪律（全局 MUST）
 
 **新增**的实测标定数据 MUST 写进对应 change 的 `design.md` 附录，MUST NOT 写进代码注释或
 随包分发的 `skills/*/SKILL.md`。
@@ -83,7 +83,7 @@
      丑话属于「怎么用」，是使用者的决策依据；
   ③ **算法本体**——公式与判定式本身就是代码在做的事，注释是它的可读投影。
 - **代码注释的目标口径**：只讲**是什么 + 怎么用**，不讲**为什么是这个值**。
-- **存量不清洗**：既有注释里的标定数据已经随公开镜像与 npm 发布；删除它们收益有限，且容易损失维护上下文。
+- **存量不清洗**：既有注释里的标定数据已经随公开镜像与 npm 发布；删除它们收益有限，且容易损失维护上下文。
   本纪律**只管新增**。已知的存量标定已在 `tighten-distribution-surface/design.md 附录 A`
   留档（含「改值前必须知道什么」速查表）——**改那些常量前先读它**。
 
@@ -224,7 +224,7 @@ gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时
 | 参数 | 作用 | 缺省 |
 |---|---|---|
 | `<taskId>`（位置参数） | 任务 id | 必填 |
-| `-o, --out <dir>` | 产物目录 | **必填**（无缺省；`--out .` = 当前目录本身） |
+| `-o, --out <dir>` | 产物目录 | **必填**（无缺省；`--out .` = 当前目录本身） |
 | `--render` | 额外本地渲染成片（需原毛片仍在 gtrk 内嵌路径 + ffmpeg） | 关 |
 | `--jianying-draft-dir` / `--ffmpeg-path` / `--crf` / `--codec` / `--no-open` / `--json` | 同 `oralcut` | — |
 
@@ -271,23 +271,23 @@ gtrk split <拆分稿.json> --project <目录> --md --json  # ⑤ 校验落地
 - **只动 `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。
 
-> **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
-
-### 2.2 精修工程导出：`gtrk project export --project <目录>`
-
-口播起盘用 `gtrk project init`，精修收尾用 `gtrk project export`；已经在客户端铺过 B-roll、MG 或 BGM 的 `.gtrk`，直接导出 NLE 工程，**不要重跑 `oralcut`**，否则会丢掉精修并重复计费。
-
-```bash
-gtrk project export --project ./my-video --formats jianying,xml
-gtrk project export --gtrk ./my-video/gtrk/project.gtrk --formats xml --no-open
-```
-
-- 颗粒会随 NLE 工程一起导出：命令会预渲 qtrle；首次导出按分钟计费，客户端已经烤过或第二次导出命中 `.tonghe-cache/particles/` 时复用缓存。
-- 本命令有两个计费面：工程结构按次，颗粒按分钟；这和 `project init` 的 0 积分不是一回事。执行前会分别提示实时价格。
-- 只选择 `gtrk` 时会自动跳过颗粒预渲（gtrk 原生保留 `beat_track`），不要再手动加 `--no-particles`；`--no-particles` 只在明确接受 NLE 导出缺少颗粒时使用。
-- `--json` 只在 stdout 输出一行结果 JSON；产物目录恒写 `result.json`，源 `.gtrk` 只读不改。
-
-### 2.3 视频转文字稿：`gtrk transcript <本地视频>`
+> **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
+
+### 2.2 精修工程导出：`gtrk project export --project <目录>`
+
+口播起盘用 `gtrk project init`，精修收尾用 `gtrk project export`；已经在客户端铺过 B-roll、MG 或 BGM 的 `.gtrk`，直接导出 NLE 工程，**不要重跑 `oralcut`**，否则会丢掉精修并重复计费。
+
+```bash
+gtrk project export --project ./my-video --formats jianying,xml
+gtrk project export --gtrk ./my-video/gtrk/project.gtrk --formats xml --no-open
+```
+
+- 颗粒会随 NLE 工程一起导出：命令会预渲 qtrle；首次导出按分钟计费，客户端已经烤过或第二次导出命中 `.tonghe-cache/particles/` 时复用缓存。
+- 本命令有两个计费面：工程结构按次，颗粒按分钟；这和 `project init` 的 0 积分不是一回事。执行前会分别提示实时价格。
+- 只选择 `gtrk` 时会自动跳过颗粒预渲（gtrk 原生保留 `beat_track`），不要再手动加 `--no-particles`；`--no-particles` 只在明确接受 NLE 导出缺少颗粒时使用。
+- `--json` 只在 stdout 输出一行结果 JSON；产物目录恒写 `result.json`，源 `.gtrk` 只读不改。
+
+### 2.3 视频转文字稿：`gtrk transcript <本地视频>`
 
 这一能力由独立的 `gtrk-transcript` Skill 驱动，不属于 `gtrk-tools` 单点工具族。用户说「视频转文字 / 视频转文字稿 / 提取视频文稿 / 把本地视频整理成妙记式文稿」时，直接运行：
 
@@ -526,7 +526,7 @@ gtrk feedback "<一句话说清哪里不顺手>" --command <命令名> [--catego
 ## 7. 扩展（给改 CLI 的 agent）
 
 新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
-云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`；单发取结果 `getTaskResult`、`pollTask` 复用之）；上传一律走 `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存；≥256MiB 自动分片断点续传，见 `src/lib/chunk-upload.ts`）。本地预处理（探几何 / 抽音频 / 压 720p）在 `src/lib/media.ts`；本地渲染（gtrk EDL → ffmpeg filter_complex）在 `src/lib/render.ts`；三方产物落地 + `result.json` 两段写在 `src/lib/materialize.ts`（`oralcut` 与 `oralcut-result` 共用）。已上线：`oralcut`（云剪）、`oralcut-result`（按 task_id 取回）、`render`（本地渲染 gtrk）、`split`（视觉拆分派单器：`src/lib/projection.ts` 投影纯函数 + `src/lib/splitdoc.ts` 拆分稿校验/落地 + `src/lib/gtrk-writeback.ts` 原子写回 `struct_meta.split`，随包分发 `skills/gtrk-splitter/`）。`matrix`（B-roll 检索：`src/lib/matrix.ts` 双口路由/派单翻译/plan 构建 + `src/commands/matrix.ts`;`matrix search "<词>"` ad-hoc）。写回 `.gtrk` 的命令（`matrix` 铺轨 / `mg` 铺轨）在写回**之后**跑一次**素材落盘自检**（`src/lib/material-integrity.ts`，纯只读、可注入 `exists` 谓词）：遍历 `materials[].path` 确认文件真在盘上，相对路径**恒以 `.gtrk` 所在目录为基准**（历史坑：按工程根解析会全面误报），结果以 `integrity` 字段出 `--json`、以摘要 + 逐条清单出人读日志。**非致命**——查出悬空不改 `ok` / 退出码，也**不删任何素材条目或文件**（预防面在 opencut 客户端侧，本仓只做检测）。规划中：`struct`（已有 gtrk → 三方工程）。
+云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`；单发取结果 `getTaskResult`、`pollTask` 复用之）；上传一律走 `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存；≥256MiB 自动分片断点续传，见 `src/lib/chunk-upload.ts`）。本地预处理（探几何 / 抽音频 / 压 720p）在 `src/lib/media.ts`；本地渲染（gtrk EDL → ffmpeg filter_complex）在 `src/lib/render.ts`；三方产物落地 + `result.json` 两段写在 `src/lib/materialize.ts`（`oralcut` 与 `oralcut-result` 共用）。已上线：`oralcut`（云剪）、`oralcut-result`（按 task_id 取回）、`render`（本地渲染 gtrk）、`split`（视觉拆分派单器：`src/lib/projection.ts` 投影纯函数 + `src/lib/splitdoc.ts` 拆分稿校验/落地 + `src/lib/gtrk-writeback.ts` 原子写回 `struct_meta.split`，随包分发 `skills/gtrk-splitter/`）。`matrix`（B-roll 检索：`src/lib/matrix.ts` 双口路由/派单翻译/plan 构建 + `src/commands/matrix.ts`;`matrix search "<词>"` ad-hoc）。写回 `.gtrk` 的命令（`matrix` 铺轨 / `mg` 铺轨）在写回**之后**跑一次**素材落盘自检**（`src/lib/material-integrity.ts`，纯只读、可注入 `exists` 谓词）：遍历 `materials[].path` 确认文件真在盘上，相对路径**恒以 `.gtrk` 所在目录为基准**（历史坑：按工程根解析会全面误报），结果以 `integrity` 字段出 `--json`、以摘要 + 逐条清单出人读日志。**非致命**——查出悬空不改 `ok` / 退出码，也**不删任何素材条目或文件**（预防面在 opencut 客户端侧，本仓只做检测）。精修工程导出已由 `gtrk project export` 承接（已有 gtrk → 多格式工程），不另设 `struct` 命令。
 
 ### 工具族：接单点云能力 = 加一个 descriptor（不写编排）
 

package/CHANGELOG.md

@@ -9,19 +9,32 @@
 > ⚠️ **`gitHead` 只是旁证**：1.2.7 是从**带未提交改动的工作区**发的——`link-cloud-font-library` 的实现
 > 在 1.2.7 的包体里逐字可见，却要到 2026-09-19 的 `4ee4f74` 才进仓。判版本归属一律以包体为准。
 
-## 未发布
-
-## 1.3.0（2026-09-28）
-
-- 视频去水印不再默认 FFmpeg：Agent 必须在处理前说明快速模糊与慢速内容修复的效果代价，等待用户选模式；`purify run/apply`、人工框和 `tool video_purify` 缺少显式模式时在上传前停止。仅检测、编辑和空清单不受影响；旧记录未建处理单时需补选模式，已建单继续原任务。失败后不得擅自改用快速或本地 FFmpeg。
-
-- `tool --batch` 补齐整批费用预估：标准价/超额价积分与额度包单位数分别汇总，按分钟收费先本地探时长，逐任务取整后求和；跳过项不计费、不探测。价格或计量不可用时明确说明无法预估。
-
-- `ai-drama lay` 成功回轨后提示先显式指定口播音频运行 `patch snap --dry-run` 检查，再执行吸附并用 `patch seal` 补缝；只提示，不自动编辑。
-
-- 清理随包 skills、共享 Agent 规则、GSAP handoff 契约和双语参考文档中的历史叙事；当前执行规则不变，GSAP 证据保留在维护者附录。
-
-## 1.2.13（2026-09-22，AI 漫剧工具批次补记）
+## 未发布
+
+- `long2short --camera-move`：云端按与精剪同一套调度把推 / 拉镜头写成主轨片段的 `clip_keyframes.scale_x / scale_y`，客户端与剪映可见可改；`clips.md` 标「运镜 N 处」，未能加运镜的切片单列；`/gtrk-live-slicing` 开工问询变五问（⑤ 运镜，缺省不加）。需配合服务端 `add-long2short-for-cli-camera-move` 与客户端承接 `clip_keyframes` 的版本。
+- `gtrk patch` 的 trim / split / seal / snap 同步维护 `clip_keyframes`（入点平移、越界截断补插值端点、切分两段各自合法），写前校验拒绝任何非法关键帧并点名 clip 与通道；`audio tighten` 遇带音量关键帧的音频片段拒绝；本地 `gtrk render` 读到关键帧时提示按静态画面出片。
+- `gtrk project background --blur [--intensity n] | --color #RRGGBB | --clear`：写客户端画布背景 `struct_meta.client_background`（零计费、不访问云端），横屏源进竖屏画布时用模糊底替代黑边；`/gtrk-live-slicing` 对横竖互转的入选切片缺省加模糊底。剪映 / PR 与本地 `gtrk render` 不带该设置。
+- `long2short --speed-factor 0.5–2.0`：整体调速（保音高）写进逐 clip 工程，客户端 / 剪映 / PR 都按倍率播放，云端不渲染、不加价；`clips.md` 标注倍率，未能变速的 clip 单列。需配合服务端 `add-long2short-for-cli-speed` 上线。
+- `long2short` 产物根新增整片转写 `json/transcript.json`，可用 `gtrk subtitle lay --gtrk … --transcript …` 给任一 clip 上客户端字幕轨；字幕文件来源时 `clips.md` 提示词级时间为近似值。需配合服务端 `add-long2short-for-cli-transcript` 上线，老服务端下不报错。
+- `subtitle lay --language <code>`：指定云端拆行语种（缺省仍为 zh-CN），非中文源上字幕不再按中文断句。
+- `/gtrk-live-slicing` 选题确认后对入选切片缺省字幕上轨；调速只在用户主动要求时加。
+
+## 1.3.2（2026-10-08）
+
+- 本地视觉理解增加当前 Agent 审阅交接：`matrix describe --prepare/--review`，已完成的本地判断不调用豆包，明确无法完成的条目按需补齐。
+- stable 长场景保留时间覆盖，素材概览同步多点抽帧；支持对指定源时间窗加密理解，检索帧预算避免同一密集素材独占。
+
+## 1.3.0（2026-09-28）
+
+- 视频去水印不再默认 FFmpeg：Agent 必须在处理前说明快速模糊与慢速内容修复的效果代价，等待用户选模式；`purify run/apply`、人工框和 `tool video_purify` 缺少显式模式时在上传前停止。仅检测、编辑和空清单不受影响；旧记录未建处理单时需补选模式，已建单继续原任务。失败后不得擅自改用快速或本地 FFmpeg。
+
+- `tool --batch` 补齐整批费用预估：标准价/超额价积分与额度包单位数分别汇总，按分钟收费先本地探时长，逐任务取整后求和；跳过项不计费、不探测。价格或计量不可用时明确说明无法预估。
+
+- `ai-drama lay` 成功回轨后提示先显式指定口播音频运行 `patch snap --dry-run` 检查，再执行吸附并用 `patch seal` 补缝；只提示，不自动编辑。
+
+- 清理随包 skills、共享 Agent 规则、GSAP handoff 契约和双语参考文档中的历史叙事；当前执行规则不变，GSAP 证据保留在维护者附录。
+
+## 1.2.13（2026-09-22，AI 漫剧工具批次补记）
 
 > npm 发布时点为 2026-09-22 08:26:53 UTC。本节补记这批已实现能力；不表示其全部 OpenSpec 已归档。后续音轨识别、素材内容寻址和镜头锚定仍在独立待办中。