@gitruck/cli 1.2.14 → 1.2.15

package/docs/reference.en.md

@@ -177,26 +177,26 @@ You can check the current state any time: the “崩溃自动上报” row in `g
 
 ---
 
-## Command reference
-
-Common entry points: `gtrk oralcut` edits talking heads, `gtrk long2short` selects highlights, `gtrk transcript` transcribes media, and `gtrk project init` builds from voiceover. The per-source limit for `oralcut` / `long2short` is 2 hours; split longer replays first, as described in the [workflow guide](workflow.en.md). Use `gtrk <command> --help` for current options.
-
-### `gtrk long2short` / `gtrk pip` / `gtrk qc` — Additional commands
-
-- `gtrk long2short <input>`: select topics and jump-cut into per-clip gtrk / Jianying / XML projects. `--split-screen` uses a 720p proxy for smart split-screen; `--output-size` selects the aspect ratio; `--subtitle-out` writes captions for each clip. Run landscape and portrait separately; content determines the number of clips. See `gtrk long2short --help` for all options.
-- `gtrk pip lay`: lay a simultaneously recorded screen or second camera against the talking-head cut points. Both sources need shared audio for alignment; low-confidence matches require calibration in the client before resuming. Use `gtrk pip lay --help` for inputs, shapes, positions and offsets.
-- `gtrk qc <video>`: inspect flash frames, black/frozen frames, volume and synchronization. Add `--gtrk` for project context and `--fail-on` for pipeline gating. Findings locate issues; they do not automatically repair the video.
-
-### `gtrk matrix --online` — External-platform search in current source
-
-This entry exists in the current development workspace. Check `gtrk matrix --help` for availability in your installed version; cloud availability must also be confirmed.
-
-| Option | Purpose and boundary |
-| --- | --- |
-| `--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 |
-
+## Command reference
+
+Common entry points: `gtrk oralcut` edits talking heads, `gtrk long2short` selects highlights, `gtrk transcript` transcribes media, and `gtrk project init` builds from voiceover. The per-source limit for `oralcut` / `long2short` is 2 hours; split longer replays first, as described in the [workflow guide](workflow.en.md). Use `gtrk <command> --help` for current options.
+
+### `gtrk long2short` / `gtrk pip` / `gtrk qc` — Additional commands
+
+- `gtrk long2short <input>`: select topics and jump-cut into per-clip gtrk / Jianying / XML projects. `--split-screen` uses a 720p proxy for smart split-screen; `--output-size` selects the aspect ratio; `--subtitle-out` writes captions for each clip. Run landscape and portrait separately; content determines the number of clips. See `gtrk long2short --help` for all options.
+- `gtrk pip lay`: lay a simultaneously recorded screen or second camera against the talking-head cut points. Both sources need shared audio for alignment; low-confidence matches require calibration in the client before resuming. Use `gtrk pip lay --help` for inputs, shapes, positions and offsets.
+- `gtrk qc <video>`: inspect flash frames, black/frozen frames, volume and synchronization. Add `--gtrk` for project context and `--fail-on` for pipeline gating. Findings locate issues; they do not automatically repair the video.
+
+### `gtrk matrix --online` — External-platform search in current source
+
+This entry exists in the current development workspace. Check `gtrk matrix --help` for availability in your installed version; cloud availability must also be confirmed.
+
+| Option | Purpose and boundary |
+| --- | --- |
+| `--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 |
+
 ### `gtrk transcript <local video|voice-over audio>`
 
 Turns a local video or voice-over audio file into a multi-level Markdown transcript. It accepts local file paths only: video is extracted — and audio input transcoded — to 16 kHz mono audio on your machine, and only that derivative is uploaded. The original file is never uploaded, and URLs or platform video downloads are not supported.
@@ -503,8 +503,10 @@ The seven shared video tools — black-border removal, aspect adaptation, stabil
 - `gtrk tool video_canvas_adapt ./clip.mp4 --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --clip-start 12 --clip-end 60 --without-audio [--json]` — video aspect conversion; `--clip-start/--clip-end` are start/end frame numbers, omitted fields use the server defaults, and the canvas mode accepts only `normal`, `rectangle`, `square`.
 - `gtrk tool video_stabilizer ./clip.mp4 --stabilizer-method turbo [--json]` — video stabilization; supports `fast`, `exp` and `turbo`, where `exp` is experimental and you should check the result yourself.
 - `gtrk tool video_vaporwave ./clip.mp4 --vaporwave-filter "灼熱苦夏" [--json]` — add a vaporwave filter using an exact preset name; omitting it explicitly uses `愈漸升溫`.
-- `gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method ffmpeg --purify-roi 0,0.78,1,0.2 [--json]` — clean a video you have the rights to modify; the ROI is a normalized `x,y,w,h` and is only used together with `custom`. `raft` supports videos under 20 minutes, `ffmpeg` has no such limit; restoring occluded content is not promised.
-- `gtrk tool video_purify ./clip.mp4 --purify-scope region --purify-region 0.8,0.02,0.18,0.08,0,5 --purify-region 0.3,0.85,0.4,0.1,120 [--json]` — remove boxes directly; repeat the option for more boxes (up to 16), each optionally followed by `start,end` in seconds (omit `end` to run to the end). No recognition — **everything inside the box is processed, including the main subject**; `ffmpeg` blurs the box while `raft` repaints it, and tighter boxes give better results. `--purify-region` only works with `region`.
+Before video cleanup, ask the user to choose fast FFmpeg blurring (basic results, visible traces possible) or slower RAFT content repair (usually more natural, not guaranteed lossless restoration). There is no default. Replace `<chosen-mode>` with the user-selected `ffmpeg` or `raft`; never switch modes after a failure without their agreement. The top-level `gtrk purify` uses `--purify-func-type`; detection, local editing and empty lists do not require a mode. Unsubmitted legacy journals need an explicit mode on resume; submitted jobs retain their original mode.
+
+- `gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method <chosen-mode> --purify-roi 0,0.78,1,0.2 [--json]` — clean a video you have the rights to modify; the ROI is a normalized `x,y,w,h` and is only used together with `custom`. `raft` supports videos under 20 minutes, `ffmpeg` has no such limit; restoring occluded content is not promised.
+- `gtrk tool video_purify ./clip.mp4 --purify-method <chosen-mode> --purify-scope region --purify-region 0.8,0.02,0.18,0.08,0,5 --purify-region 0.3,0.85,0.4,0.1,120 [--json]` — remove boxes directly; repeat the option for more boxes (up to 16), each optionally followed by `start,end` in seconds (omit `end` to run to the end). No recognition — **everything inside the box is processed, including the main subject**; `ffmpeg` blurs the box while `raft` repaints it, and tighter boxes give better results. `--purify-region` only works with `region`.
 - `gtrk tool video_upscale ./clip.mp4 --upscale-times 3 --upscale-type Anime [--json]` — experimental video upscaling; input up to 60 seconds, neither side may exceed 4000 px after scaling, supports `2`, `3`, `4`× and `Reality`, `Anime`.
 - `gtrk tool video_interpolate ./clip.mp4 --interpolate-multiplier 3 [--json]` — frame interpolation; supports `2`, `3`, `4`×, does not apply the one-minute limit from older docs, and neither side of the source may exceed 4000 px.
 - `gtrk tool video_segment ./clip.mp4 [--detector adaptive] [--threshold 27] [--json]` — mechanical shot segmentation; produces **structured** `result-output.json` (`scene_list` with each range's start/end/duration), not a downloadable file.

package/docs/reference.md

@@ -172,26 +172,26 @@ GITRUCK_CRASH_REPORT=0 gtrk oralcut a.mp4   # 环境变量，临时关一次（
 
 ---
 
-## 命令参考
-
-常用流程入口：`gtrk oralcut` 剪口播、`gtrk long2short` 切高光、`gtrk transcript` 转文字稿、`gtrk project init` 从配音建工程。`oralcut` / `long2short` 单次源片不能超过 2 小时；超长直播先分段，见[工作流指南](workflow.md)。其余命令的最新参数也可用 `gtrk <命令> --help` 查询。
-
-### `gtrk long2short` / `gtrk pip` / `gtrk qc` — 常用补充
-
-- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。完整参数见 `gtrk long2short --help`。
-- `gtrk pip lay`：把同步录制的屏录或第二机位按口播剪点铺成画中画。两源需有可对齐的公共声音；低置信时先在客户端校准，再按提示恢复。运行 `gtrk pip lay --help` 查看输入、形状、位置和偏移参数。
-- `gtrk qc <成片>`：检查闪帧、黑帧、冻结、音量和同步问题；用 `--gtrk` 提供工程上下文，`--fail-on` 控制管线门槛。检查结论供定位问题，不自动替你修片。
-
-### `gtrk matrix --online` — 当前源码的外部平台检索入口
-
-此入口来自当前开发工作区，安装版是否提供以 `gtrk matrix --help` 为准，云端可用性另行确认。
-
-| 参数 | 用途与边界 |
-| --- | --- |
-| `--online` | 检索外部平台 B-roll，仅支持单条 search 或派单消费；与 `--local` 互斥。单条 search 必须给 `--out <结果.json>` 保存结果及断线恢复记录；派单消费需要 `--project` 或 `--dispatch`。这是云端任务，不能按纯本地工具理解 |
-| `--platforms <list>` | 逗号分隔 `youtube,vimeo,tiktok,bilibili`，仅配合 `--online`；不指定时查询已登记的四个平台。实际结果仍取决于服务与来源可访问性 |
-| `--online-session <name>` | 外部检索批次名，仅配合 `--online` 且不可为空；同批次续跑，换名称发起新搜索，可能产生新任务与费用 |
-
+## 命令参考
+
+常用流程入口：`gtrk oralcut` 剪口播、`gtrk long2short` 切高光、`gtrk transcript` 转文字稿、`gtrk project init` 从配音建工程。`oralcut` / `long2short` 单次源片不能超过 2 小时；超长直播先分段，见[工作流指南](workflow.md)。其余命令的最新参数也可用 `gtrk <命令> --help` 查询。
+
+### `gtrk long2short` / `gtrk pip` / `gtrk qc` — 常用补充
+
+- `gtrk long2short <input>`：按话题选段并跳剪，逐 clip 输出 gtrk / 剪映 / XML 工程；`--split-screen` 使用 720p 代理做智能分屏；`--output-size` 选择画幅；`--subtitle-out` 另产逐 clip 字幕。每次只选一种画幅，横竖屏分别运行；成片条数由内容决定。完整参数见 `gtrk long2short --help`。
+- `gtrk pip lay`：把同步录制的屏录或第二机位按口播剪点铺成画中画。两源需有可对齐的公共声音；低置信时先在客户端校准，再按提示恢复。运行 `gtrk pip lay --help` 查看输入、形状、位置和偏移参数。
+- `gtrk qc <成片>`：检查闪帧、黑帧、冻结、音量和同步问题；用 `--gtrk` 提供工程上下文，`--fail-on` 控制管线门槛。检查结论供定位问题，不自动替你修片。
+
+### `gtrk matrix --online` — 当前源码的外部平台检索入口
+
+此入口来自当前开发工作区，安装版是否提供以 `gtrk matrix --help` 为准，云端可用性另行确认。
+
+| 参数 | 用途与边界 |
+| --- | --- |
+| `--online` | 检索外部平台 B-roll，仅支持单条 search 或派单消费；与 `--local` 互斥。单条 search 必须给 `--out <结果.json>` 保存结果及断线恢复记录；派单消费需要 `--project` 或 `--dispatch`。这是云端任务，不能按纯本地工具理解 |
+| `--platforms <list>` | 逗号分隔 `youtube,vimeo,tiktok,bilibili`，仅配合 `--online`；不指定时查询已登记的四个平台。实际结果仍取决于服务与来源可访问性 |
+| `--online-session <name>` | 外部检索批次名，仅配合 `--online` 且不可为空；同批次续跑，换名称发起新搜索，可能产生新任务与费用 |
+
 ### `gtrk transcript <本地视频|配音音频>`
 
 把本地视频或配音音频转为一个多层级的 Markdown 文字稿。只接受本地文件路径：视频在本机抽取、音频在本机转码为 16 kHz 单声道音频，只上传音频衍生物，原文件不会上传，也不支持 URL 或平台视频下载。
@@ -483,7 +483,7 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 | `video_canvas_adapt` | 单条本地视频；可选目标宽高、片段、画布模式和无音轨输出 | 比例适配视频 | 运行前实时查询 | 已上线 |
 | `video_stabilizer` | 单条本地视频；可选 `fast` / `exp` / `turbo` | 防抖视频 | 运行前实时查询 | 已上线 |
 | `video_vaporwave` | 单条本地视频；滤镜使用精确预设名称 | 蒸汽波滤镜视频 | 运行前实时查询 | 已上线 |
-| `video_purify` | 单条本地视频；可选 `full_screen` / `subtitle` / `custom` / `region`、`ffmpeg` / `raft`、归一化 ROI 与可带时间段的区域框（仅处理有权修改的素材） | 一条净化视频 | 运行前实时查询 | 已上线 |
+| `video_purify` | 单条本地视频；单点模式支持 `full_screen` / `subtitle` / `custom` / `region`；Agent 编排请用顶层 `gtrk purify detect/edit/apply`，审阅最终区域后执行 | 一条净化视频，或检测 JSON + 净化视频 | 运行前实时查询 | 已上线 |
 | `video_upscale` | 单条本地视频（**≤1 分钟**）；可选 `2` / `3` / `4` 倍与 `Reality` / `Anime` | 一条超分视频 | 运行前实时查询 | 已上线 |
 | `video_interpolate` | 单条本地视频；可选 `2` / `3` / `4` 倍，不附加 1 分钟限制 | 一条插帧视频 | 运行前实时查询 | 已上线 |
 | `video_segment` | 单条本地视频；可选 `--detector content\|adaptive`、`--threshold` | 分镜区间结构 `result-output.json`（结构化数据，非下载文件） | 运行前实时查询 | 已上线 |
@@ -491,6 +491,7 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 | `video_motion_cut` | 单条本地视频 | 运镜/高光片段结构 `result-output.json`（结构化数据，非下载文件） | 运行前实时查询 | 已上线 |
 | `video_speaker_detect` | 单条本地视频；可选 `--language`/`--max-faces-per-frame`/`--detect-body`/`--track-sample-fps`（重 GPU） | 可见说话人结构 `result-output.json`（时基以服务端输出为准） | 运行前实时查询 | 已上线 |
 | `video_face_track` | 单条本地视频；可选 `--sample-fps`/`--max-faces`/`--min-face-ratio`/`--enable-body-match`/`--similarity-threshold`；`time_ranges` 走 `--params-json`（重 GPU） | 人物 ID/时间段/轨迹结构 `result-output.json`（时基以服务端输出为准） | 运行前实时查询 | 已上线 |
+| `video_character_cut` | 单条本地视频；角色名、身份种子窗；多人时加 `--seed-bbox x,y,w,h`；本地镜头清单 + ≤720p/12fps 代理 | v2 原片半开毫秒时间戳、核心/上下文证据及待复核项，不下载视频 | 运行前实时查询 | v2 重构验证中，未部署 |
 | `audio_tts_clone` | **无文件**：`--text`/`--text-file` 二选一（≤5000 字）+ `--speaker` 必填；可选语言/格式/语速/切分法/字幕/**句间停顿**（`--fragment-interval <秒>`，**仅自训音色**；云引擎音色传了会**报错**而非静默忽略，合法区间由服务端校验并在报错里给出） | 配音音频 wav/mp3（+ 可选字幕）；按文本字符数计费，计量单位与单价以 `gtrk tool list` 实时显示为准 | 运行前实时查询 | 已上线 |
 | `video_ai_subtitle` | 单条视频或音频；`--language <码>` 必填；可选 `--translate-language`、`--need-render`、`--need-pure`、`--subtitle-type`、`--subtitle-color`。默认只传本地抽出的音频（毛片不上传） | `.ass` 字幕 + 可选烧录/去字幕 `.mp4` + `result-output.json`（摘要 + 字级时间轴） | 运行前实时查询 | 已上线 |
 | `subtitle_translate` | 单个**字幕文件** `.ass` / `.srt`；`--language <码>` 与 `--translate-language <码>` **双必填**；可选 `--output-format`、`--line-mode`、`--bilingual`、`--subtitle-type`、`--subtitle-color`、`--canvas <WxH>`。不含语音识别 | 译文字幕 `.ass` 或 `.srt` + `result-output.json`（条数统计 + 降级标记） | 运行前实时查询 | 已上线 |
@@ -526,8 +527,18 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 - `gtrk tool video_canvas_adapt ./clip.mp4 --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --clip-start 12 --clip-end 60 --without-audio [--json]` — 视频比例转换；`--clip-start/--clip-end` 是起止帧序号，省略字段时沿用服务端默认，画布模式只接受 `normal`、`rectangle`、`square`。
 - `gtrk tool video_stabilizer ./clip.mp4 --stabilizer-method turbo [--json]` — 视频防抖；支持 `fast`、`exp`、`turbo`，其中 `exp` 为实验方式，产物观感需自行检查。
 - `gtrk tool video_vaporwave ./clip.mp4 --vaporwave-filter "灼熱苦夏" [--json]` — 使用精确预设名称添加蒸汽波滤镜；省略时显式使用 `愈漸升溫`。
-- `gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method ffmpeg --purify-roi 0,0.78,1,0.2 [--json]` — 净化用户有权修改的视频；ROI 为归一化 `x,y,w,h` 且只和 `custom` 同用。`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用该限制；不承诺还原被遮挡内容。
-- `gtrk tool video_purify ./clip.mp4 --purify-scope region --purify-region 0.8,0.02,0.18,0.08,0,5 --purify-region 0.3,0.85,0.4,0.1,120 [--json]` — 按框直接去除，可重复给多个框（最多 16 个）；框后可带 `start,end`（秒，`end` 省略即到结尾）。不做识别，**框内全部内容都会被处理（包括画面主体）**；`ffmpeg` 在框内做模糊、`raft` 做修复补全，框越小、越贴边效果越好。`--purify-region` 只能和 `region` 同用。
+视频去水印必须先问用户选快速（ffmpeg：基础模糊，可能留痕）还是精细（raft：较慢的内容修复，通常更自然、可接近无痕，不保证无损还原）。没有默认模式；`<用户选定模式>` 必须替换为用户已选择的 ffmpeg 或 raft，失败后不得自行降档。只检测、编辑和空清单不要求选择。旧运行记录尚未建处理任务时，resume 也须补显式模式；已建单继续原任务。
+
+- `gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method <用户选定模式> --purify-roi 0,0.78,1,0.2 [--json]` — 净化用户有权修改的视频；ROI 为归一化 `x,y,w,h` 且只和 `custom` 同用。`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用该限制；不承诺还原被遮挡内容。
+- `gtrk purify detect ./clip.mp4 --out ./purify-work --json` — 只检测，返回待审清单、摘要与代表时间。
+- `gtrk purify edit ./purify-work/detect-xxx-final.json --select-roi 0,0.7,1,0.3 --out ./purify-work/final.json` — 本地筛选；还支持 --delete-id / --watermark-region / --protect-region。
+- `gtrk purify run ./clip.mp4 --purify-func-type <用户选定模式> --detect-scope subtitle --watermark-region 0.8,0.02,0.18,0.08 --json` — 明确范围的自动组合；full_screen 必须显式指定。
+- `gtrk purify ./clip.mp4 --purify-func-type <用户选定模式> --no-detect --watermark-region 0.8,0.02,0.18,0.08,0,5 --out ./purify-work --json` — 只处理给定角标框的前 5 秒，跳过文字检测；省略时间则覆盖全片。框为画面归一化 `x,y,w,h`，每条视频分别定位，不能直接套用另一条视频的选区。
+- `gtrk purify apply ./purify-work/final.json --purify-func-type <用户选定模式> --json` — 最终清单唯一权威；空清单不建单。
+- `gtrk purify resume ./purify-work/run-xxx.json --json` — 恢复已有任务和下载，不重复计费建单。保护区域需新版后端；ffmpeg 为模糊，raft 为内容修复。
+
+上述 `detect-xxx-final.json` 和 `run-xxx.json` 仅示意：实际路径以命令回执中的 `finalRegionsJson` 和 `journal` 为准。检测与处理各建一次任务、分别计费；`edit` 只在本地编辑。用户明确要求直接采用检测结果时可用 `run`，仅按框去角标则用 `--no-detect`。`resume` 用于已有任务或下载中断；云端明确失败时保留任务 ID 排查，不把重复提交当成恢复。
+
 - `gtrk tool video_upscale ./clip.mp4 --upscale-times 3 --upscale-type Anime [--json]` — 实验性视频超分；输入最多 60 秒，放大后任一边不得超过 4000 px，支持 `2`、`3`、`4` 倍和 `Reality`、`Anime`。
 - `gtrk tool video_interpolate ./clip.mp4 --interpolate-multiplier 3 [--json]` — 视频插帧；支持 `2`、`3`、`4` 倍，不套用旧文档中的 1 分钟限制，原视频任一边不得超过 4000 px。
 - `gtrk tool video_segment ./clip.mp4 [--detector adaptive] [--threshold 27] [--json]` — 机械分镜；产**结构化** `result-output.json`（`scene_list` 各段起止/时长），非下载文件。
@@ -552,6 +563,7 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 - `gtrk tool video_split_screen a.mp4 b.mp4 --clips-json '[{"input":0,"begin_time_ms":0,"end_time_ms":5000},{"input":1,"crop":{"x":0.1,"y":0,"width":0.8,"height":1}}]'` — 精确档：按 0 起索引指定每段毫秒区间与归一化裁剪框；同一文件可多条目出多窗口。
 - `gtrk tool video_speaker_detect ./talk.mp4 --language zh-CN` — 检测画面里谁在何时说话，出结构化 JSON（重 GPU）。
 - `gtrk tool video_face_track ./talk.mp4 --params-json '{"time_ranges":[{"begin_time":0,"end_time":30000}]}'` — 人脸追踪/身份聚类，可限定时间段（**单位毫秒**；重 GPU）。
+- `gtrk tool video_character_cut "./movie.mkv" --character "智代" --seed-range "00:12:27.500,00:12:29.500" --json` — 角色 Cut 检索（v2 尚待部署）；全片逐镜头分析，视觉种子确认身份，只上传分析代理。多人种子加 `--seed-bbox "0.445,0.36,0.16,0.5"`。结果 `cuts` 为有视觉证据的镜头及相关上下文，`review_candidates` 为身份未知镜头，`context_review` 为待复核关系；`partial` 必须展示缺口，`identity_unresolved` 要求换种子或框选。稀疏采样仅声明镜头含目标，不代表角色在整个区间逐帧可见。
 - `gtrk tool audio_tts_clone --text "欢迎收听本期节目" --speaker narrator` — 文字转配音音频（音色列表见官网文档）。
 - `gtrk tool audio_tts_clone --text-file 稿子.txt --speaker sweet_female --output-format mp3` — 长文合成，缺省跟随音色调好的语速与切分参数。
 - `gtrk tool mad ./素材 [--bgm 歌.mp3] [--duration 20] [--seed 42] [--technique 技法名,…] [--refresh] [--json]` — 一键剪 MAD：扫素材文件夹 → 选技法 → 单一 `.jsx`（AE 2020+ 跑一遍出母合成成片工程）。`--seed` 可复现；`result.json` 记 seed/数据版本/降级档位/选中技法。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.2.14",
+	"version": "1.2.15",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",
@@ -53,10 +53,11 @@
 	],
 	"scripts": {
 		"gtrk": "bun run src/index.ts",
+		"test:purify": "esbuild src/commands/purify.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/purify-cmd.mjs && node --test test/purify-cmd.test.mjs",
 		"build": "bun build ./src/index.ts --target=node --minify --outfile dist/index.js",
 		"typecheck": "tsc --noEmit",
 		"prepublishOnly": "npm run typecheck && npm test && bun run build",
-		"test": "node scripts/workspace-pollution-gate.mjs --snapshot && esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/log.ts src/lib/read-json.ts src/lib/sidecar-write.ts src/lib/user-config.ts src/lib/enum-catalog.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.ts src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/jianying.ts src/lib/clip-brief.ts src/lib/media.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/column-config.ts src/lib/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.ts src/lib/matrix.ts src/lib/online-broll-client.ts src/lib/online-search-journal.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/local-index.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/project-health.ts src/lib/contact-sheet.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-batch.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/cut-snap.ts src/lib/mg-coverage.ts src/lib/ai-drama-lay.ts src/lib/ai-drama-pack.ts src/lib/desk-locate.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/patch-cmd.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/commands/doctor.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/doctor-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\" && node scripts/workspace-pollution-gate.mjs --verify",
+		"test": "node scripts/workspace-pollution-gate.mjs --snapshot && esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/log.ts src/lib/read-json.ts src/lib/sidecar-write.ts src/lib/user-config.ts src/lib/enum-catalog.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.ts src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/jianying.ts src/lib/clip-brief.ts src/lib/media.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/column-config.ts src/lib/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.ts src/lib/matrix.ts src/lib/online-broll-client.ts src/lib/online-search-journal.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/local-index.ts src/lib/character-input.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/project-health.ts src/lib/contact-sheet.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-batch.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/cut-snap.ts src/lib/mg-coverage.ts src/lib/ai-drama-lay.ts src/lib/ai-drama-pack.ts src/lib/desk-locate.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/patch-cmd.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --external:bun:sqlite --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/commands/doctor.ts --bundle --platform=node --external:bun:sqlite --format=esm --external:commander --outfile=.test-build/doctor-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --external:bun:sqlite --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && esbuild src/commands/purify.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/purify-cmd.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\" && node scripts/workspace-pollution-gate.mjs --verify",
 		"test:linux": "node scripts/test-linux.mjs",
 		"openspec:gate": "node openspec/gate.mjs",
 		"mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs",

package/skills/gtrk-ai-drama/SKILL.md

@@ -3,7 +3,9 @@ name: gtrk-ai-drama
 description: AI 情景动画分镜稿生成器——把成片 SOP 第③步（B-roll 底轨阶段）分到 AI_DRAMA 车道的 beat，逐个产**四段朴素描述（故事背景 / 角色 / 分镜 / 原文文稿）+ 独立视觉基调段 + 时长预算**，中英双版；Markdown 外壳默认严格兼容 gitruck-ai-drama-desk 解析器，可直接导入工作台，也可拿去任意外部 AI 漫剧管线（可灵 / 即梦 / Vidu / Veo / Runway / LTX / 本地开源，或 LibTV / OiiOii / TapNow 这类成片 agent 平台）上手用。创作与出片仍在 skill / 外部工作台；工作台导出的 return-v1 包用 `gtrk ai-drama lay` 确定性回填独立 AI 轨。当用户想「上 AI 情景动画 / 做 AI 分镜 / AI 动画描述 / 把这段做成 AI 视频 / 给这段配 AI 情景动画 / 弗洛伊德这段怎么做视频」时使用本 skill。通用拆镜 craft（蒙太奇段分层 / 四段描述结构 / 中英双语 / 时长预算）由本 skill 自持；栏目视觉 DNA（Style Lock）从栏目配置 style.skills 里 produces==AI_DRAMA 的条目解析注入，绝不硬编某栏目风格。凡把口播派单里 AI_DRAMA 段落转成可出片的描述稿，优先用本 skill，别手搓。
 ---
 
-# AI 情景动画分镜稿生成器（gtrk-ai-drama）
+# AI 情景动画分镜稿生成器（gtrk-ai-drama）
+
+用户要求间隔取关键镜头、剩余由实况补齐时，先读 [稀疏关键场景与角色参考](references/sparse-key-scenes.md)。其短 beat 窗口、时基、逐镜参考和留空规则优先于下文针对连续 AI 段落的时长预算；不转入通篇 AI 图纸。
 
 把口播派单里分到 **`AI_DRAMA` 车道**的 beat，逐个拆成分镜、为每个 beat 产 **四段朴素描述 + 独立视觉基调 + 时长预算**（中英双版），落到 `<project>/ai-drama/<beat_id>.md`，再交棒 AI Drama Desk 或任意外部平台出片；标准工作台导出包由 CLI 自动回填时间线。
 

package/skills/gtrk-ai-drama/references/sparse-key-scenes.md

@@ -0,0 +1,38 @@
+# 稀疏关键场景与角色参考
+
+用户要求“隔一段挑关键场景、其余自己补实况”时使用。它不是通篇 AI 成片图纸，不套用零缝、片头铺满或自动封缝规则。
+
+## 选镜与时基
+
+先通读正文及上下文，再按叙事转折选场景。间隔是密度目标，不是机械切秒。每镜登记原句、源音频起点、母带起点、预计画面时长、人物、年龄阶段、场景与关键道具。母带含 OP/ED 时显式登记正文范围与 offset；用对应音频片段核对，不能把正文从零开始的 ASR 时码直接当母带时码。
+
+一处独立关键场景对应一个短 beat 窗口，窗口只覆盖这条片段的计划时长；不要把直到下一处场景的整个间隔当窗口让末镜吃满。CLI beat 使用 B 开头数字编号；其他展示编号应显式映射，不私改接口。其余时间留给实况，禁止自动 seal、循环或拉伸填满。用户指定只做正文时，OP/ED 不派视觉生成。
+
+## 原作资产与逐镜判断
+
+- 从叙事语义识别人物，不能靠“他、父亲、刀”等关键词自动加入主角。角色随时间改变时分别绑定年龄、发型、服装参考。
+- 实际查看参考图。只带本镜需要的角色；物证或空镜不要夹带多人图作为角色参考。原作 CG 可以锁角色/画风，但画中事件不等于当前镜头事件。
+- 参考路径逐镜登记，禁止按镜号取模轮换 CG。用户指定宿主 Image2 时使用该能力，不擅自换成本地生图或云模型。
+- 图片提示词描述一个明确瞬间；I2V 提示词描述该瞬间里有剧情含义的小动作，以及须保持稳定的脸、手、道具与空间。实际时长、尺寸、帧率以模型配置及成品探测为准，不硬编码样片参数到全部项目。
+
+## 分阶段审阅
+
+已生成、已选中、已审阅、已回轨是不同状态。逐镜看实际输出，记录人物与年龄、场景关系、道具比例、手部接触和微动可行性。审阅记录绑定具体文件与内容哈希；替换图片、分镜或人物设定后重新审阅，不能整批写 accepted 代替目视检查。工具可以强制记录完整，却不能证明记录内容真实。
+
+外部图片通过工作台的 keyframe import 接口进入候选池；角色 refs 上传不是关键帧导入。具体命令见工作台 skill。视频检查至少看首、中、尾及运动过程；仅看抽帧要如实说明，不写成逐帧播放验收。
+
+## 分批回轨
+
+首次按现有 pack/lay 契约回轨；新增 beat 使用：
+
+```sh
+gtrk ai-drama lay --project <工程> --package <新包> --append --json
+```
+
+`--append` 为本次新包新增独立轨，逐对象保留已有轨、素材与手调；拒绝重复 beat，不与 `--replace-all` 同用。需替换已有镜头时，等时长/尺寸/帧率素材用 `swap`；改变时序须重新设计并用 patch 编辑，不以“备份后重铺再猜着恢复”冒充保留手调。媒体由增量路径按 beat 和内容哈希隔离。
+
+执行前查看当前 CLI 的 `ai-drama --help` 是否已有 `--append`。skill 更新不等于已安装二进制更新；旧版本缺参数时使用已核实仓库的源码入口或完成构建，不退回覆盖手调的项目脚本。
+
+阅读 lay 回执的 reprojection：降级使用派单快照时核对它是否属于当前母带。doctor 检查结构与文件存在，不能代替语义审阅；稀疏轨的空档警告不自动触发封缝。
+
+交付明确计划数、已生成数、已审阅数和已回轨数。用户说先看样片时只交付约定样片；其他镜头保持未完成状态，不因有场景表就宣称批量完成。

package/skills/gtrk-tools/SKILL.md

@@ -7,7 +7,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 
 飞书使用教程统一入口：[gtrk CLI 使用教程](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk)。
 
-`gtrk tool <name> [输入...]` 是 gtrk 的**单点能力**族：一个工具 = 单发单收（给一份输入、出一份产物；多文件图片工具的「一份输入」是一组图片路径，顺序即拼装顺序），没有 SOP 次序、没有用户检查点链——与成片管线的车道命令（`oralcut` / `split` / `matrix` / `mg`）是两回事。本 skill 是这个族的**统一调用向导**：认清有哪些工具、按纪律驱动 `gtrk tool` 命令、把产物和计费如实回给用户。
+`gtrk tool <name> [输入...]` 是 gtrk 的**单点能力**族：一个工具 = 单发单收（给一份输入、出一份产物；多文件图片工具的「一份输入」是一组图片路径，顺序即拼装顺序），没有成片 SOP 次序；视频去水印必须先完成下文的用户模式选择——与成片管线的车道命令（`oralcut` / `split` / `matrix` / `mg`）是两回事。本 skill 是这个族的**统一调用向导**：认清有哪些工具、按纪律驱动 `gtrk tool` 命令、把产物和计费如实回给用户。
 
 > **本 skill 已含你需要的全部信息**（工具清单、调用纪律、恢复语义、排错话术）。工具清单以 `gtrk tool list --json` 为**唯一真相**——本文件与它漂移时以命令输出为准并回来修本文件。参数细节以 `gtrk tool --help` 为准。
 
@@ -35,6 +35,7 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `video_split_screen` | 「分屏 / reaction 同框 / 对比视频 / 多画面合成」 | **2~16 段视频**（多 positional，顺序有语义）；精确档 `--clips-json`：条目 `{input:0 起序号, begin_time_ms, end_time_ms, crop 归一化}`（**毫秒时基**、`input` 指第几个输入文件、同文件可多窗口）；可选 `--layout-mode/--layout-id/--seed/--output-ratio/--quality/--fit-mode/--audio-mode/--gap-ratio/--background-color`。**成片时长对齐最短段** | 一条分屏成片视频 | 运行前实时查询 | 已上线 |
 | `video_long2short_pro` | 「长视频剪成多条高光短片 / 一键出成片 / 长剪短精剪 / 播客切片直接出片」 | 单条长视频（**整片上传**，云端要渲成片）；**`--language <码>` 必填**；可选 `--output-language`、`--main-topic`、`--output-size`、`--no-jump-cut`、`--duration-pref`、`--max-clip-sec`、`--split-screen`、`--split-orientation`、`--speed-factor`、`--no-camera-move`、`--no-subtitle`、`--subtitle-translate-language`；润色细颗粒走 `--params-json` | 逐条成片 `clip{i}.mp4` + 人读报告 `clips.md`（含**润色降级明细**）+ `result-output.json` | 运行前实时查询（**约为粗剪两倍**） | 已上线 |
 | `video_face_track` | 「人脸追踪 / 人物出场时间段 / 视频里有哪几个人」 | 单条本地视频；可选 `--sample-fps`、`--max-faces`、`--min-face-ratio`、`--enable-body-match`、`--similarity-threshold`；`time_ranges` 经 `--params-json` 传（**单位毫秒**，如 `{"begin_time":0,"end_time":30000}`）。**重 GPU、按分钟计费较高** | 人物 ID/时间段/轨迹结构 `result-output.json`（时基以服务端输出为准） | 运行前实时查询 | 已上线 |
+| `video_character_cut` | 「角色 Cut / 找出某角色全片片段 / 正反打角色检索」 | 本地视频；`--character`、`--seed-range`，多人时 `--seed-bbox x,y,w,h`；全片镜头清单 + ≤720p/12fps 代理；CPU 解码 + 外部多图理解 | `video_character_cut.v2`：cuts、review_candidates、context_review、unknown_ranges；仅返回原片时间轴。partial 不可声称全片已找全；身份歧义换种子/框选 | 运行前实时查询 | v2 重构验证中，未部署 |
 | `video_ai_subtitle` | 「智能字幕 / 给视频加字幕 / 视频翻译字幕 / 烧录字幕 / 去原字幕」 | 单条视频或音频；**`--language <码>` 必填**；可选 `--translate-language`、`--need-render`（烧录）、`--need-pure`（去原字幕）、`--subtitle-type`、`--subtitle-color`。**默认只上传本地抽出的音频、毛片不出本地**（几何随请求回传，字幕按原片画布出） | `.ass` 字幕文件 + 可选烧录/去字幕 `.mp4` + `result-output.json`（LLM 摘要 + 字级时间轴） | 运行前实时查询 | 已上线 |
 
 > **字幕这两条要提前讲给用户**（`video_ai_subtitle` 专属）：
@@ -158,8 +159,8 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 - 视频比例转换：`gtrk tool video_canvas_adapt ./clip.mp4 --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --clip-start 12 --clip-end 60 --without-audio --json`。`--clip-start/--clip-end` 传起止帧序号；省略选项就沿用服务端默认，需要保留音轨时不要传 `--without-audio`。
 - 视频防抖：`gtrk tool video_stabilizer ./clip.mp4 --stabilizer-method turbo --json`。支持 `fast`、`exp`、`turbo`；未传时由服务端使用 `turbo`，`exp` 只按实验方式转述，不承诺观感。
 - 蒸汽波滤镜：`gtrk tool video_vaporwave ./clip.mp4 --vaporwave-filter "灼熱苦夏" --json`。滤镜名原样精确传递，不翻译、不猜别名；未传时 CLI 明确使用 `愈漸升溫`。
-- 视频净化：`gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method ffmpeg --purify-roi 0,0.78,1,0.2 --json`。ROI 是 `x,y,w,h` 归一化坐标，只能和 `custom` 同用；`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用这个上限。只处理用户有权修改的素材，不宣称能还原被遮挡的原始内容。
-- 按框直接去除：`gtrk tool video_purify ./clip.mp4 --purify-scope region --purify-region 0.8,0.02,0.18,0.08,0,5 --json`（图片把工具换成 `image_purify`、框只写 `x,y,w,h`）。`--purify-region` 可重复，最多 16 个框，视频框后可带 `start,end` 秒。`custom` 只去除框内识别到的文字；`region` 不做识别、**框内全部内容都会被处理（包括画面主体）**——用户要去的是图形台标、半透明图案或只在某段时间出现的角标时选 `region`，并提醒框越小越贴边效果越好。
+- 视频净化：`gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method <用户选定模式> --purify-roi 0,0.78,1,0.2 --json`。ROI 是 `x,y,w,h` 归一化坐标，只能和 `custom` 同用；`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用这个上限。只处理用户有权修改的素材，不宣称能还原被遮挡的原始内容。
+- 按框直接去除：`gtrk tool video_purify ./clip.mp4 --purify-scope region --purify-region 0.8,0.02,0.18,0.08,0,5 --json`（图片把工具换成 `image_purify`、框只写 `x,y,w,h`）。`--purify-region` 可重复，图片最多 16 个框、视频按服务资源限制，视频框后可带 `start,end` 秒。`custom` 只去除框内识别到的文字；`region` 不做识别、**框内全部内容都会被处理（包括画面主体）**——用户要去的是图形台标、半透明图案或只在某段时间出现的角标时选 `region`，并提醒框越小越贴边效果越好。
 - 视频超分：`gtrk tool video_upscale ./clip.mp4 --upscale-times 3 --upscale-type Anime --json`。输入最多 60 秒，放大后任一边超过 4000 px 会由服务端拒绝；这是实验性增强，不能承诺主观画质一定提升。
 - 视频插帧：`gtrk tool video_interpolate ./clip.mp4 --interpolate-multiplier 3 --json`。支持 `2`、`3`、`4`，不套用旧总览里的 1 分钟限制；原视频任一边超过 4000 px 时由服务端拒绝。
 
@@ -176,3 +177,30 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 ## 毕业条款
 
 某个工具若长出复杂度——需要多模式子命令、需要分步用户确认、需要注入栏目风格——它就该从工具族**毕业**成独立命令 / 独立 skill（照成片车道命令的先例）。毕业后旧的 `gtrk tool <名>` 会报错并指路新命令。你只要跟着 `gtrk tool list` 的当前清单走即可。
+
+## 可审阅的视频净化
+
+### 先选模式，再处理（必须）
+
+Agent 在任何去除处理之前 MUST 主动向用户说明两种模式，并等待明确选择：
+
+- **快速去除（ffmpeg）**：速度快，做基础模糊去除，可能留下模糊块或涂抹痕迹，适合更看重速度、能接受基础效果的场景。
+- **精细修复（raft）**：速度慢，做内容修复，通常更自然，合适素材可接近无痕；不保证无损或还原被遮挡的真实细节。
+
+建议问法：「这次要快速还是精细？快速处理更快，但效果基础、可能留模糊痕迹；精细处理更慢，通常更自然、可接近无痕，但不保证所有画面都能完美修复。你选哪一种？」
+
+**没有回答就不开始去除，不替用户默认 ffmpeg，也不默认 raft。** 用户在本次任务已明确选好模式时无需重复询问；批量素材只有在用户明确说明整批沿用该模式时才能统一使用。“直接处理”“无需复核选区”“按检测结果去除”只授权范围，不代表选择了处理模式。只做 detect/edit 可以继续；空清单直接返回原片，不为不发生的处理追问。
+
+用户选定后才把对应值显式传给命令：顶层 `--purify-func-type ffmpeg|raft`，旧工具入口 `--purify-method ffmpeg|raft`。这些参数没有默认值；下面的 `<用户选定模式>` 必须替换为本次选择，不能照示例猜一个。
+
+不确定误检时：先 `gtrk purify detect <视频> --out <工程目录> --json`，消费摘要与代表时间查看原片，再用 `gtrk purify edit <区域文件> --select-roi x,y,w,h --out <最终文件>` 筛选。edit 还支持重复的 --delete-id / --watermark-region / --protect-region。最后 `gtrk purify apply <最终文件> --purify-func-type <用户选定模式> --json`，最终清单不会被重新检测覆盖。
+
+用户明确清理范围时：`gtrk purify run <视频> --detect-scope subtitle --watermark-region x,y,w,h --purify-func-type <用户选定模式> --json`。不得将全屏文字候选默认当成水印；full_screen 需明确选择。图形台标需 Agent 补框。
+
+只处理明确的角标框时：`gtrk purify <视频> --no-detect --watermark-region x,y,w,h[,start[,end]] --purify-func-type <用户选定模式> --out <工程内产物目录> --json`，跳过文字检测。省略时间表示全片；每条视频分别确认角标位置，不复用上一条视频的框。用户已授权采用检测结果时无需再审选区，但仍须完成模式选择。检测和处理分别计费，纯人工框只创建处理任务。
+
+中断后用 `gtrk purify resume <回执中的运行记录> --json`。新记录沿用用户已选模式；旧记录尚未建处理任务且无法确认选择时，先询问用户，再在 resume 补 `--purify-func-type <用户选定模式>`。已建单只能继续查询下载，不能通过 resume 换模式。
+
+**慢速失败、排队或暂不可用时，必须先告知原因及切换快速去除的效果代价，等用户同意后才能另建快速任务；严禁自行手搓本地 ffmpeg 交差。** 长片超出 raft 限制时先说明限制，讨论分段或改模式，不因时长自动降档。交付时写明实际模式与已知效果问题，不把 ffmpeg 结果描述为无痕修复。
+
+完整万级区域保存在文件，勿逐条读进模型上下文。保护框优先于去除框，新处理请求会先检查服务支持 review_protocol=2，否则在上传计费前停止。