@gitruck/cli 1.2.13 → 1.2.15

package/docs/workflow.en.md

@@ -0,0 +1,72 @@
+# From footage to an editable project
+
+[Back to README](../README.en.md) · [Command reference](reference.en.md) · [简体中文](workflow.md)
+
+## Choose an entry point
+
+| Input | Entry point | First deliverable |
+| --- | --- | --- |
+| One or more talking-head recordings, optionally with external audio | `gtrk-talking-head` Skill; `gtrk oralcut` for a rough cut only | Aligned, joined and roughly edited project plus transcript |
+| An existing script | `gtrk-voiceover` Skill | Voiceover, sentence timing and an audio-driven project |
+| Podcast, interview, course or livestream replay | `gtrk-long2short`; `gtrk-live-slicing` Skill for long replays | A separate project for each highlight |
+| Film, gameplay, travel or restaurant footage | `gtrk-narration`, or travel/food presets | A retold script, voiceover and assembled visuals |
+| Location footage with live sound to preserve | `gtrk-vlog-docu` Skill | A documentary project alternating live sound and narration |
+
+The per-source limit for `oralcut` / `long2short` is **2 hours**. Longer sources are rejected before extraction or upload; split long replays first. Tutorials: [talking heads](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) · [voiceover](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) · [long to short](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) · [narrated videos](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre).
+
+## Follow the production order
+
+1. **Set the content and production plan.** Check footage, script, aspect ratio, voice and visual direction. Listen to and adjust a voiceover before building its timeline.
+2. **Create the project and transcript.** Rough-cut, select highlights or build from voiceover. Review pacing and content before packaging.
+3. **Arrange visuals.** Dispatch segments and search platform or local footage. B-roll and AI reenactment clips are both base visuals and can be prepared separately.
+4. **Settle the composition.** Choose candidate tracks in the client and inspect faces, subjects and safe areas. You may explicitly defer missing AI clips, then revisit affected compositions when they return.
+5. **Add motion graphics.** Place titles, diagrams and transparent overlays around the settled footage without obscuring its subjects.
+6. **Music, captions and delivery.** Add captions after the timeline settles, then preview, check and export video or supported editing projects.
+
+Optional stages can be skipped. Quick mode groups key decisions; ask for step-by-step progress when you want to review each stage. Checkpoints and cost confirmations follow the relevant Skill.
+
+## Where to chat and where to edit
+
+Conversations currently happen in your own AI agent; the desktop client has no built-in AI chat. The agent creates or updates `.gtrk` through the CLI. The Windows client opens that same project for preview, selection and refinement.
+
+Give further requests to your agent or make manual changes in the client. Scripts can also render an existing project with `gtrk render`; opening the desktop client is not a prerequisite for every render.
+
+## Deliverables and export boundaries
+
+| Deliverable | How to use it | Boundary |
+| --- | --- | --- |
+| `gtrk/project.gtrk` | Open in the desktop client | Keeps the multitrack structure and supported motion graphics information |
+| Jianying drafts from talking-head / long-to-short cuts | Configure the draft folder during setup; open from Jianying's project list | Requires both fixed filenames, `draft_content.json` and `draft_meta_info.json` |
+| `xml/premiere.xml` from those cuts | Import into Premiere | Describes the corresponding rough cut; it does not promise lossless transfer of every later client effect |
+| Jianying drafts exported by the client | Continue refining a packaged project | Preserves supported tracks and captions; graphics may be baked into video and are no longer editable as the original HTML |
+| MP4 from `gtrk render` | Playback, review or publishing | Composites visible video overlays and graphics; hidden tracks stay out. This command does not export Jianying drafts |
+
+Client-specific elements, complex effects and third-party formats are not universally interchangeable. Check the rendered video for final appearance, and keep `.gtrk` plus its media for further editing.
+
+## Uploads and costs
+
+- **Talking-head and long-to-short project workflows:** originals stay local. Extracted audio is uploaded by default; visual assistance or smart split-screen uses a compressed proxy.
+- **Local B-roll:** original media stays local. Understanding may send sampled frames; cloud arrangement uses structured information and is billed under its own rules.
+- **Individual cloud tools:** upload requirements vary. Cloud video processing may require the video itself.
+- **CLI rendering:** video composition is local. Uncached graphics require cloud rendering with a cost prompt. `--no-particles` skips those graphics while still compositing other visible video overlays.
+- **AI generation:** external model services, separate production desks and your agent follow their own pricing.
+
+Prices and free allowances may change. Check the [billing guide](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd) and runtime pricing.
+
+## Recovery and troubleshooting
+
+| Situation | Action |
+| --- | --- |
+| Skills do not appear | Open a new agent session; use `gtrk skills install` if needed. Not every agent uses a `/` menu |
+| Configuration, connection or runtime problem | Run `gtrk doctor`; check `gtrk deps status` before explicitly installing missing FFmpeg assets |
+| Draft is missing in Jianying | Check the draft root and both fixed filenames listed above |
+| Talking-head task completed, but results are missing | Use the recovery command below, or read `result.json` in the output folder before rerunning a cloud job |
+| A long task timed out | Timeout does not mean cancellation. Keep `task.json` / `result.json` and query or recover by task ID |
+| Upgrade needed | `gtrk upgrade` upgrades the CLI and refreshes Skills; `npm i -g` alone does not refresh agent Skills |
+| An older project has compatibility problems | Check the [CHANGELOG](../CHANGELOG.md) and follow the relevant version instructions |
+
+```bash
+gtrk oralcut-result <taskId> --out <output-directory>
+```
+
+See the [command reference](reference.en.md) for parameters, JSON receipts, billing confirmation and recovery limits.

package/docs/workflow.md

@@ -0,0 +1,72 @@
+# 从素材到可编辑工程
+
+[返回首页](../README.md) · [命令参考](reference.md) · [English](workflow.en.md)
+
+## 先选入口
+
+| 输入 | 入口 | 首轮交付 |
+| --- | --- | --- |
+| 真人口播，一条或多条，可带外录音频 | `gtrk-talking-head` Skill；只粗剪用 `gtrk oralcut` | 对轨、拼段、粗剪后的工程与文稿 |
+| 已有文字稿 | `gtrk-voiceover` Skill | 配音、句级时码与音频驱动工程 |
+| 播客、访谈、课程或直播回放 | `gtrk-long2short`；超长直播用 `gtrk-live-slicing` Skill | 每个高光独立的剪辑工程 |
+| 影视、游戏、旅拍或探店素材 | `gtrk-narration`，或旅拍、美食预设 | 提炼后的解说稿、配音与配画面工程 |
+| 保留现场同期声的素材集 | `gtrk-vlog-docu` Skill | 同期声与旁白交替的纪实工程 |
+
+`oralcut` / `long2short` 的单次源片上限为 **2 小时**，超过会在抽取与上传前拒绝；超长回放先分段。完整教程：[口播](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) · [配音](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) · [长剪短](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) · [解说](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre)。
+
+## 按创作顺序推进
+
+1. **确定内容和制作方案。** 核对素材、稿件、画幅、声音和视觉方向。配音先试听调整，满意后再建时间线。
+2. **拿到工程与文稿。** 粗剪、选段或从配音建工程；先检查节奏与内容，再继续包装。
+3. **安排画面。** 分段派单，检索平台或本地素材。B-roll 与 AI 再现片段都属于底层画面，可分别准备。
+4. **确定底层构图。** 在客户端挑选候选轨，检查人脸、主体和安全区。AI 片段未回轨时，可明确先跳过，并在回轨后复查相关构图。
+5. **叠加动效。** 按最终画面安排字卡、图解和透明叠层，避免遮住主体。
+6. **配乐、字幕与交付。** 时间线确定后上字幕，预览、质检、导出成片或支持的剪辑工程。
+
+可选环节可以省略。快速成片会集中确认关键选择；需要逐步看结果时，对 Agent 说“逐步来”。具体检查点与费用确认以对应 Skill 为准。
+
+## 在哪里对话，在哪里编辑
+
+当前在自己的 AI Agent 里对话，客户端没有内置 AI 对话框。Agent 通过 CLI 创建或修改 `.gtrk`；Windows 客户端打开同一工程，供你预览、挑选和精修。
+
+想调整某一步，可以把具体要求交回 Agent；想自己改，可以在客户端操作。自动化或脚本也可用 `gtrk render` 渲染已有工程，无需把“打开客户端”当作每次渲染的前置条件。
+
+## 交付物与导出边界
+
+| 交付物 | 怎么用 | 边界 |
+| --- | --- | --- |
+| `gtrk/project.gtrk` | 客户端打开 | 保存多轨结构与支持的动态图等信息 |
+| 口播／长剪短的剪映草稿 | 安装时配置草稿目录，完成后在剪映项目列表打开 | 草稿目录内需要固定名 `draft_content.json` 和 `draft_meta_info.json` 成对存在 |
+| 口播／长剪短的 `xml/premiere.xml` | 在 Premiere 导入 | 是对应粗剪工程，不代表后续所有客户端效果都可无损互转 |
+| 客户端导出的剪映草稿 | 完整包装后继续精修 | 按当前导出能力保留支持的轨道与字幕；动态图可能烤成视频素材，不能当作原 HTML 继续编辑 |
+| `gtrk render` 输出的 MP4 | 播放、审核、发布 | 合成可见视频叠层与动态图；关闭的轨道不入片。该命令不导出剪映草稿 |
+
+客户端专有元素、复杂效果和第三方工程格式不能笼统视为全部兼容。需要保留最终视觉效果时，检查渲染成片；需要继续编辑时，同时保留 `.gtrk` 与素材。
+
+## 上传与费用
+
+- **口播粗剪、长剪短工程流程：** 原片保留本地，默认上传抽出的音频。视觉辅助或智能分屏改传压缩代理。
+- **本地 B-roll：** 原始素材保留本地；理解可能发送抽帧，云端编排使用结构化信息并按相应规则计费。
+- **单点云端工具：** 上传要求取决于工具，例如云端视频处理可能需要视频本体。
+- **CLI 渲染：** 视频合成在本地；未命中缓存的动态图需云端渲染，先提示费用。`--no-particles` 可跳过动态图，其他可见视频叠层仍正常合成。
+- **AI 生成：** 外部模型服务、独立工作台与 Agent 的费用按各自规则结算。
+
+实际价格和免费额度会变化，查看[计费说明](https://hocassian.feishu.cn/wiki/Iq9NwC3briQ2TJkSrzPcm5Jensd)及运行时查询结果。
+
+## 常用恢复与排障
+
+| 情况 | 处理 |
+| --- | --- |
+| Skills 未出现 | 新开 Agent 会话；必要时 `gtrk skills install`。不同 Agent 的 Skills 入口不一定是 `/` 菜单 |
+| 配置、连接或环境有问题 | `gtrk doctor`；缺 FFmpeg 时先 `gtrk deps status`，再按提示显式安装 |
+| 剪映里没有草稿 | 核对草稿根目录及两个固定文件名，详见上表 |
+| 口播任务已完成，但结果丢失 | 使用下方恢复命令，或读取产物目录中的 `result.json`，不要先重跑云端 |
+| 长任务等待超时 | 超时不等于任务取消；保存 `task.json` / `result.json`，按任务 ID 查询或恢复 |
+| 需要升级 | `gtrk upgrade` 同时升级 CLI、刷新 Skills；仅 `npm i -g` 不会刷新 Agent 中的 Skills |
+| 旧工程有兼容问题 | 先查 [CHANGELOG](../CHANGELOG.md)，按对应版本说明修复 |
+
+```bash
+gtrk oralcut-result <taskId> --out <output-directory>
+```
+
+详细参数、JSON 回执、计费确认和恢复限制见[命令参考](reference.md)。

package/package.json

@@ -1,72 +1,79 @@
-{
-	"name": "@gitruck/cli",
-	"version": "1.2.13",
-	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
-	"license": "MIT",
-	"author": "Gitruck (同合云)",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Gitruck/cli.git"
-	},
-	"homepage": "https://github.com/Gitruck/cli#readme",
-	"bugs": {
-		"url": "https://github.com/Gitruck/cli/issues"
-	},
-	"type": "module",
-	"bin": {
-		"gtrk": "dist/index.js"
-	},
-	"files": [
-		"dist",
-		"assets",
-		"skills",
-		"contracts",
-		"AGENT.md",
-		"README.md",
-		"README.en.md",
-		"LICENSE",
-		"CHANGELOG.md"
-	],
-	"engines": {
-		"node": ">=20.6"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	},
-	"keywords": [
-		"gitruck",
-		"同合云",
-		"video",
-		"oral-cut",
-		"口播剪辑",
-		"cli",
-		"jianying",
-		"剪映",
-		"agent"
-	],
-	"scripts": {
-		"gtrk": "bun run src/index.ts",
-		"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/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:linux": "node scripts/test-linux.mjs",
-		"openspec:gate": "node openspec/gate.mjs",
-		"mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs",
-		"text-template:snapshot": "node scripts/text-template-snapshot.mjs",
-		"text-ir:parity": "node scripts/text-ir-parity.mjs",
-		"text-ir:sync": "node scripts/text-ir-sync.mjs"
-	},
-	"devDependencies": {
-		"@xmldom/xmldom": "^0.9.6",
-		"bun-types": "^1.1.0",
-		"commander": "^12.1.0",
-		"esbuild": "^0.28.1",
-		"typescript": "^5.6.0"
-	},
-	"dependencies": {
-		"hash-wasm": "^4.12.0",
-		"jszip": "^3.10.1"
-	}
-}
+{
+	"name": "@gitruck/cli",
+	"version": "1.2.15",
+	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
+	"license": "MIT",
+	"author": "Gitruck (同合云)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Gitruck/cli.git"
+	},
+	"homepage": "https://github.com/Gitruck/cli#readme",
+	"bugs": {
+		"url": "https://github.com/Gitruck/cli/issues"
+	},
+	"type": "module",
+	"bin": {
+		"gtrk": "dist/index.js"
+	},
+	"files": [
+		"dist",
+		"assets",
+		"skills",
+		"contracts",
+		"AGENT.md",
+		"README.md",
+		"README.en.md",
+		"docs/reference.md",
+		"docs/reference.en.md",
+		"docs/workflow.md",
+		"docs/workflow.en.md",
+		"docs/development.md",
+		"docs/development.en.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"engines": {
+		"node": ">=20.6"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"keywords": [
+		"gitruck",
+		"同合云",
+		"video",
+		"oral-cut",
+		"口播剪辑",
+		"cli",
+		"jianying",
+		"剪映",
+		"agent"
+	],
+	"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/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",
+		"text-template:snapshot": "node scripts/text-template-snapshot.mjs",
+		"text-ir:parity": "node scripts/text-ir-parity.mjs",
+		"text-ir:sync": "node scripts/text-ir-sync.mjs"
+	},
+	"devDependencies": {
+		"@xmldom/xmldom": "^0.9.6",
+		"bun-types": "^1.1.0",
+		"commander": "^12.1.0",
+		"esbuild": "^0.28.1",
+		"typescript": "^5.6.0"
+	},
+	"dependencies": {
+		"hash-wasm": "^4.12.0",
+		"jszip": "^3.10.1"
+	}
+}

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，否则在上传计费前停止。