@gitruck/cli 1.3.4 → 1.3.5

package/docs/workflow.en.md

@@ -1,72 +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.
+# 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. If the *Link Media* dialog appears, check the *Media Path* column after relinking — Premiere's automatic relink matches by file name and may pick a same-named file from another project |
+| 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

@@ -1,72 +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)。
+# 从素材到可编辑工程
+
+[返回首页](../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 导入 | 是对应粗剪工程，不代表后续所有客户端效果都可无损互转；若弹出「链接媒体」框，链接后在「媒体路径」列核对——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,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.3.4",
+	"version": "1.3.5",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",
@@ -57,7 +57,7 @@
 		"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/project-background.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/clip-speed.ts src/lib/clip-keyframes.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/composite-particle.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": "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/project-background.ts src/lib/client-only-state.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/clip-speed.ts src/lib/clip-keyframes.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/highlight-input.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/composite-particle.ts src/lib/composite-lay.ts src/lib/composite-lint.ts src/lib/composite-browser.ts src/lib/composite-plan.ts src/lib/composite-shots.ts src/lib/composite-resolve.ts src/lib/composite-profile.ts src/lib/composite-scene.ts src/lib/composite-bake-plan.ts src/lib/composite-bake.ts src/lib/composite-export.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/composite.ts --bundle --platform=node --format=esm --external:bun:sqlite --external:commander --outfile=.test-build/composite-cmd.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,9 +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）
-
-用户要求间隔取关键镜头、剩余由实况补齐时，先读 [稀疏关键场景与角色参考](references/sparse-key-scenes.md)。其短 beat 窗口、时基、逐镜参考和留空规则优先于下文针对连续 AI 段落的时长预算；不转入通篇 AI 图纸。
+# 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 自动回填时间线。
 
@@ -24,7 +24,7 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 
 **你与 `matrix` 同属第 ③ 步，MUST 在 MG 之前落位。** 理由：**AI 情景片段属于底轨 B-roll 画面家族，不是叠加层**——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版决策是「因势象形避主体」、**依赖底轨的最终画面构图**；若你的片段在 MG 之后才回铺，底轨构图就变了，先产的 MG 是对着「还没有 AI 画面的底轨」做的避让，你的片段落位后必然被避让错位、甚至被 MG 盖住画面主体。
 
-> ⚠️ **工序顺序**：AI 情景片段必须先落位；它属于底轨 B-roll，不是最后叠加的图层。之后再做全局构图检查与 MG。
+> ⚠️ **工序顺序**：AI 情景片段必须先落位；它属于底轨 B-roll，不是最后叠加的图层。之后再做全局构图检查与 MG。
 
 **异步等待的口子（你造成的那个）**：你产完描述后，用户要去外部平台出片、抽卡可能数天。严格串行会把 ④⑤ 无限期卡住，故约定：进 ⑤ 的硬门是「**AI 片段已回铺 ∨ 用户明示先跳过**」。走「明示跳过」时，下游 `/gtrk-mg` MUST 把与你的 beat 相邻/重叠区间的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述——**你在交代进度时也要把这个代价说清**，让用户知道跳过意味着将来可能返工那几颗。
 
@@ -37,11 +37,11 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 3. **中英双版地位平等，不是主辅。** ①视觉基调、②故事背景、③角色、④分镜四段每一段都给完整的中文版 + 英文版（不是把中文翻一句了事）。中文喂可灵 / 即梦 / Vidu / 通义，英文喂 Veo / Runway / LTX / Luma，用户按目标平台选。**唯独 ⑤ 原文文稿是中文口播原文、不翻译**（它是源真相 + 手动拼接的对位锚，翻译反而失真）。
 4. **内容可移植，Markdown 外壳不可自由改写。** 默认产物 MUST 通过 `gitruck-ai-drama-desk` 的 Markdown 解析契约：标题必须含 `（beat BXX）`；两大块必须叫 `## 一、中文稿…` / `## 二、English Storyboard…`；角色必须用 `#### 角色名（备注）` 标题；中文镜头必须用 `#### 分镜 01 · …`，英文镜头必须用 `#### Shot 01 · …`；元信息必须含 `区间总时长：track_st … → track_ed … ≈ … 秒`。`镜头`、粗体行、项目符号角色、`## 中文` / `## English`、`工程时间位` 都不是等价写法。**人读友好不能牺牲机读契约。**
 
-> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
-> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
+> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
+> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
 > 分镜稿只落**工程目录**（`<project>/ai-drama/<beat_id>.md`）或**用户显式指定处**；
 > **MUST NOT** 把用户媒体（毛片 / 成片 / 预览 / 外部平台出的片段）或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
-> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
+> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
 
 ## 业务分离：栏目 Style Lock 从哪来（关键）
 
@@ -114,7 +114,7 @@ return-v1 标准包由 `gtrk ai-drama lay` 确定性回填；其他平台没有
 
 **Step 4 · 写四段描述（中英分块）**：先出**中文稿**（② 故事背景末句锁调 → ③ 角色结构化 + 禁变项 + 质感落点，复现理论家 pin 复用同段文字 → ④ 分镜每镜前缀复述基调 + 建议秒数 + 对应原文句 + 蒙太奇级意图 → ⑤ 原文文稿中文逐句不翻译），再整块出 **English Storyboard**（① Style Lock + ②③④ 英文原生化，不含 ⑤）。中英**分两大块、不逐段交错**（craft C）。
 
-**Step 5 · 校验后落盘**：先把每个 beat 的候选稿写到系统 temp，运行随 skill 分发的 `scripts/validate-storyboard.mjs <候选稿.md>`；退出码为 0 才写到 `<project>/ai-drama/<beat_id>.md`。失败就按输出逐项修正，MUST NOT 把未通过稿件落进工程。校验器不可用时，至少逐项执行下面「解析器硬契约」与交付前自检。用户直投单段时同样先校验，再落到用户指定的工程路径。临时稿无论成功失败都删掉。
+**Step 5 · 校验后落盘**：先把每个 beat 的候选稿写到系统 temp，运行随 skill 分发的 `scripts/validate-storyboard.mjs <候选稿.md>`；退出码为 0 才写到 `<project>/ai-drama/<beat_id>.md`。失败就按输出逐项修正，MUST NOT 把未通过稿件落进工程。校验器不可用时，至少逐项执行下面「解析器硬契约」与交付前自检。用户直投单段时同样先校验，再落到用户指定的工程路径。临时稿无论成功失败都删掉。
 
 ## 输出契约（落盘 Markdown 结构 · 中英分块）
 
@@ -250,7 +250,7 @@ face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how
 
    命令自己解析 id → 导出包目录，走两条**确定性**路径：① 工作台服务可达就问它；② 服务没起就读 `~/.gitruck/ai-drama-desk.json` 的落脚点。两条都不通会报错并给出路。
 
-   > ⚠️ **拿到 id 之后 MUST NOT 去磁盘上找导出包**（`find` / `ls -R` / 通配一律禁止）。解析不出来就如实报，请用户启动工作台或直接给路径。
+   > ⚠️ **拿到 id 之后 MUST NOT 去磁盘上找导出包**（`find` / `ls -R` / 通配一律禁止）。解析不出来就如实报，请用户启动工作台或直接给路径。
    > 零命中时命令会列出「已查过哪些数据根」：源码部署与打包部署的数据根不同，项目找不到多半是**它在另一个部署里**，不是丢了。
 
    已经手上就有目录路径（或用的是非标准平台）时，仍可用 `--package "<exports/aidrama>"`，两者可混用、按路径去重。
@@ -258,7 +258,7 @@ face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how
    命令会先按当刻口播工程重投影 beat 窗口，再把所有镜头复制到 `<gtrk目录>/assets/ai-drama/<slug>/`，共用一条新的 `video_track`；每个 beat 从起点顺排，最后一镜吸收到 beat 终点。既有 A-roll、BGM 与 B-roll 轨零改动。若已铺 AI 轨被用户手调过，缺省拒绝覆盖；只有用户明确同意丢弃手调时才加 `--replace-all`。
 3. **非标准平台才手动回铺**：外部平台没有 return-v1 清单时，才由用户把片段拖回 opencut 的 **AI_DRAMA 车道**，对齐该 beat 的 `track_st→track_ed`。AI 出片仍是外部异步、用户驱动；未拿到完整片段前要停下等用户，别替他假装出片 / 回轨完成。
 4. **回铺齐 ≠ 收口，还有两步**：你的片段回铺齐只意味着 **③ B-roll 底轨阶段**完成。接着 MUST 走 **④ 全局抽帧检查画面构图**（对三源合并后的最终底轨抽帧，看主体位置 / 安全区 / 画面朝向 / 明暗，**停下等用户确认**）→ 过了才交棒 **⑤ `/gtrk-mg`** 把 MG（含 ov）叠上 → 最后才 `gtrk render` 收口。
-   ⚠️ **MUST NOT 从你这里直接跳到 `render`**；先完成全局构图检查与 MG，再进入字幕和渲染。
+   ⚠️ **MUST NOT 从你这里直接跳到 `render`**；先完成全局构图检查与 MG，再进入字幕和渲染。
 
 > 原则：**agent 替用户跑 CLI / 接力 skill，用户只对话**。但 AI_DRAMA 车道天然有「用户去外部平台出片 + 手动拼回」的手工环节——那部分是外部的手，无法替跑；除此之外的解析、生成、落盘、交代，全由你（脑）一次做完，别让用户自己去拼描述。
 

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

@@ -1,38 +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 检查结构与文件存在，不能代替语义审阅；稀疏轨的空档警告不自动触发封缝。
-
-交付明确计划数、已生成数、已审阅数和已回轨数。用户说先看样片时只交付约定样片；其他镜头保持未完成状态，不因有场景表就宣称批量完成。
+# 稀疏关键场景与角色参考
+
+用户要求“隔一段挑关键场景、其余自己补实况”时使用。它不是通篇 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 检查结构与文件存在，不能代替语义审阅；稀疏轨的空档警告不自动触发封缝。
+
+交付明确计划数、已生成数、已审阅数和已回轨数。用户说先看样片时只交付约定样片；其他镜头保持未完成状态，不因有场景表就宣称批量完成。