gitruck/cli/gtrk-ai-drama

AI 情景动画分镜稿生成器（gtrk-ai-drama）

用户要求间隔取关键镜头、剩余由实况补齐时，先读 稀疏关键场景与角色参考。其短 beat 窗口、时基、逐镜参考和留空规则优先于下文针对连续 AI 段落的时长预算；不转入通篇 AI 图纸。

把口播派单里分到 `AI_DRAMA` 车道的 beat，逐个拆成分镜、为每个 beat 产 四段朴素描述 + 独立视觉基调 + 时长预算（中英双版），落到 <project>/ai-drama/<beat_id>.md，再交棒 AI Drama Desk 或任意外部平台出片；标准工作台导出包由 CLI 自动回填时间线。

脑手分工：本 skill 负责创作（拆镜 + 注入栏目风格 + 管用户交互），外部工作台负责生成；gtrk ai-drama lay 只消费 AI Drama Desk 的 return-v1 导出包，把已经生成好的片段复制进工程并铺到一条独立 AI 视频轨。该命令不生成内容、不调用模型、不计费，也不改既有 A-roll / BGM / 三条 B-roll 候选轨。

为什么是「四段朴素描述」而不是「平台优化提示词」

因为责权利要清：无论用户拿去哪个管线，一致性的可移植载体是角色/场景描述，不是某平台的提示词语法（"assets model-agnostic, prompts model-specific"）。而且下游 agent 成片平台（LibTV / OiiOii / TapNow 等）拿到分镜稿会自己重拆分镜、重写 prompt，角色圣经（三视图）也在那些产品里生成——所以本 skill 不产平台优化提示词、不产角色圣经、不产参考图、不产成片，只产四段可移植描述 + 视觉基调 + 时长，把「怎么出片、怎么保角色一致」交给下游平台。「拼回时间线」不再交给用户手工：AI Drama Desk 的 return-v1 标准包由 gtrk ai-drama lay 确定性回填；其他平台没有标准包时才降级为用户手动回铺。

SOP 定位：第 ③ 步 · B-roll 底轨阶段的 AI 情景片段腿（不是最后）

成片是有序 SOP + 用户检查点，不是并行一把铺。次序：

① oralcut 剪口播 → ② split 视觉拆分派单 → ③ B-roll 底轨全铺齐（matrix 铺影视/本地素材 + 本 skill 产稿→外部出片→`gtrk ai-drama lay` 回填，两条腿同一阶段）→ ④ 全局抽帧检查画面构图（用户确认）→ ⑤ mg 铺 MG（含 ov，最后叠上） → gtrk subtitle lay 上字幕（快速成片模式必做）→ gtrk render 收口

你与 `matrix` 同属第 ③ 步，MUST 在 MG 之前落位。 理由：AI 情景片段属于底轨 B-roll 画面家族，不是叠加层——整条管线里唯一的叠加层是 MG（含 ov）。MG 的排版决策是「因势象形避主体」、依赖底轨的最终画面构图；若你的片段在 MG 之后才回铺，底轨构图就变了，先产的 MG 是对着「还没有 AI 画面的底轨」做的避让，你的片段落位后必然被避让错位、甚至被 MG 盖住画面主体。

⚠️ 工序顺序：AI 情景片段必须先落位；它属于底轨 B-roll，不是最后叠加的图层。之后再做全局构图检查与 MG。

异步等待的口子（你造成的那个）：你产完描述后，用户要去外部平台出片、抽卡可能数天。严格串行会把 ④⑤ 无限期卡住，故约定：进 ⑤ 的硬门是「AI 片段已回铺 ∨ 用户明示先跳过」。走「明示跳过」时，下游 /gtrk-mg MUST 把与你的 beat 相邻/重叠区间的 MG 颗粒标记为「AI 回铺后待复查构图」并在收口时复述——你在交代进度时也要把这个代价说清，让用户知道跳过意味着将来可能返工那几颗。

你的下一步：产完描述 → 用户拿去外部平台出片 → 若拿到 AI Drama Desk return-v1 导出目录，立即用 gtrk ai-drama lay 回填；其他平台没有标准包时才降级为用户手动回铺 → 三源齐了进 ④ 全局抽帧检查画面构图（对最终底轨抽帧、用户确认）→ 过了才交棒 ⑤ /gtrk-mg。MUST NOT 直接从你这里跳到 `render` ——后面还有构图检查与 MG 两步。

四条铁律（先记死）

1. 业务分离：通用 craft 归本 skill，栏目风格从配置解析。 本 skill 只持对任何栏目都通用的拆镜工艺（蒙太奇段分层、四段描述结构、中英双语、时长预算）。栏目专属的视觉 DNA / Style Lock（底色、单点强调色、影视参考锚点、材质、禁令）从有效栏目配置解析注入（见下节），绝不硬编某栏目风格——尤其别把《实在界漫游指南》那套「黑白二元 + 单点朱红」当默认塞给所有人，那是它的栏目资产，该从配置来。未绑 AI_DRAMA 风格资产的栏目 → 用本 skill 的中性默认兜底。
2. 只产描述，不产成片、不产角色圣经、不产参考图。 本 skill 的交付物是四段可移植描述文本。出片（渲染成视频片段）、角色三视图/角色圣经、参考图，全在下游平台或用户手里。不要假装能帮他渲染或建角色资产。
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 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。

分镜稿只落工程目录（<project>/ai-drama/<beat_id>.md）或用户显式指定处；

MUST NOT 把用户媒体（毛片 / 成片 / 预览 / 外部平台出的片段）或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时用原路径引用，不做副本；

临时文件一律放系统 temp 且用完即删。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。

业务分离：栏目 Style Lock 从哪来（关键）

视觉风格不是本 skill 预设的，是从栏目配置里解析出来的。 解析链路（与 gtrk-splitter 的车道→生产 skill 解析同源）：

1. 定位有效栏目：用与该工程 split 时相同的栏目——用户 --column <id> 指定，或本地 config 的 defaultColumn；配置文件在 ~/.gitruck/columns/<id>.json。本 skill 无 gtrk 命令，直接读这个 JSON 文件（同 /gtrk-style-maker 的做法）。
2. 取 AI_DRAMA 生产条目：读 style.skills[]，逐条把 produces 归一（历史别名如 RRV_MG→MG 等按归一规则处理），取 produces == "AI_DRAMA" 的条目。

• 命中 → 拿它的 ref（指向一个 skill 目录/资源）→ 读该 skill 的 Style Lock / 风格资产（通常是它 references/ 下的 style-lock、theme-accent、影视参考锚点等），把其中的底色 / 单点强调色 / 影视参考 / 材质 / 栏目禁令当作本次生成的视觉 DNA，注入 ①视觉基调段与各描述。
• 条目声明 routing:"none" → 跳过（显式管线外）。
• 无 AI_DRAMA 匹配条目 = 该栏目没绑 AI 情景动画风格资产 → 用下面「中性默认」。

1. 注入，不臆造：读到什么风格资产就用什么；没读到就用中性默认，绝不凭栏目名猜风格、绝不套用别的栏目的调性。

举例（仅示意解析机制，非硬编）：real-roam-guide 栏目配置里 style.skills 有一条 {produces:"AI_DRAMA", ref:"…/ai-drama-prompter"} → 解析到它 → 读它的 style-lock（黑白单红那套）注入。换个栏目、换个 ref，注入的就是另一套风格。本 skill 正文里不写死任何一套具体风格。

前置与输入

• 需要一个 split 落地过的工程目录：里面有 split/dispatch.json（gtrk split 产物）。没有 → 先回 /gtrk-splitter 拆分派单。
• 消费 `dispatch.ai_drama[]`：读 <project>/split/dispatch.json 的 ai_drama 数组。每条形如 {beat, narrative?, theme?, emotion_stage?, platform?, shot_count?, track_st, track_ed}：
• narrative / theme / emotion_stage / platform / shot_count 全可选，缺则按文稿内容与位置推断（推断出的值在元信息处标注「推断」）。
• track_st / track_ed = 该 beat 在时间线上的起止秒，给你时长预算（据此定区间总时长、蒙太奇段数、各镜建议秒数；本 skill 不改时码、只读）。
• 也接单段直投：用户直接甩一段文稿 + 「把这段做成 AI 视频」时，无需 dispatch，把这段当一个 beat 走同一套工艺即可（落用户指定处或 <cwd>/ai-drama/<自拟标题>.md）。
• 文稿内容从哪读：dispatch 条目带 beat id，对应文稿去投影视图 / transcript 里按该 beat 的 span 读原文（读懂内容拆镜、并抄进 ⑤ 原文文稿区块）。用户直投时用他给的文本。

通用 craft（本 skill 自持，任何栏目通用）

A. 蒙太奇段分层拆镜

1. 1 镜 = 1 情感颗粒：同一个动作不切两镜；情绪转折必须切镜。
2. 每镜 3–8 秒：短于 3 秒观众来不及呼吸；长于 8 秒 AI 视频模型会塌（人物表情 / 手部漂移）。
3. 长文段拆蒙太奇段：一个 AI_DRAMA beat 可能覆盖很长一段文稿、含多个场景/情境。此时先拆蒙太奇段（每段锚一个场景/情境），段内 3–6 镜按情感颗粒切、段间可换场。镜数上限按段级判定，不再因整段总镜数超 6 就回退 splitter——长区间整段做 AI 情景动画是合法创作，不是拆分错误。
4. 切分触发器（任一出现才考虑切）：时间 / 空间改变、主体改变（例：理论家 → 当事人）、抽象概念登场（从「人物戏」切到「象征物戏」）、情绪转折（安静→刺点 / 爆发→凝滞）。不要因一个句号、一个逗号就切。
5. 控整体不控单镜：你对区间总时长负责（各镜建议秒数之和量级贴合 track_st→track_ed），但不必把每一镜的秒数抠死——AI 平台交付本就不保证逐帧准，最终对齐由回填这一步兜：走 gtrk ai-drama lay 时它按窗口顺排、

末镜尽量吸收到 track_ed；素材短于窗口就留空档（MUST NOT 拉伸/循环去填满），没有标准包才由用户手动拼。

B. 视觉基调：独立成段 + 融入各描述（一源多处）

视觉基调既独立成段（作权威源），又融入各描述（防漂）：

• ① 独立段（权威源）：把解析到的栏目 Style Lock 写成完整一段（底色 / 中性调 / 单点强调色 / 材质 / 影视参考 / 禁忌），60–120 字/词，CN + EN。这是权威源，供各分镜复述。
• 融入 ② 故事背景：末句锁整段色调（「整段以……色彩与质感呈现」）。
• 融入 ③ 角色：每角色一句质感落点（他在这套调子里长什么样、那点单点强调色落在哪个道具上——书脊 / 印章 / 丝带 / 封蜡，别做成环境光 / 滤镜 / 背景色）。
• 融入 ④ 分镜：每镜前缀复述一句视觉基调（AI 视频模型健忘，不复述必漂色）。

C. 中英双版结构（中英分离落盘 + EN 的强制调整）

中英分块、不逐段交错：产物分成两大块——先一整块中文稿（元信息 + ①②③④ 中文 + ⑤ 原文文稿），再一整块 English Storyboard（① Style Lock + ②③④ 英文）。这样用户按目标平台整块复制：中文平台（可灵 / 即梦 / Vidu / 通义）拷中文稿、英文平台（Veo / Runway / LTX / Luma）拷英文稿，不用逐行挑出中/英。别在每个小节里 `【中文】…【EN】…` 交错（那样复制粘贴要一句句抠）。

英文块不是直译，要做这些原生化：

• 摄影术语用英文原生词：push-in / dolly-in、pull-back、tilt-up、lateral pan、rack focus、chiaroscuro、key/fill/rim light、practical light；景别 extreme close-up … extreme wide；焦段 35mm anamorphic / 50mm spherical / 85mm portrait。
• 年份用英文格式：Vienna, 1920，不是 1920 年维也纳。
• 人名用英文原名：Sigmund Freud / Lacan，不是拼音。
• 影视参考用英文片名（斜体）。
• ⑤ 原文文稿只在中文稿里、不翻译：逐句列中文口播原文即可，英文块不含它。
• 元信息只写一次（放最前），中英两块不重复；每镜的「建议秒数 / 段 / 场景 / 角色 / 对应原文句」表头行在中/英两块各写各自语言的一份。

D. 时长预算

• 元信息给区间总时长：track_ed - track_st，据此定蒙太奇段数与建议分镜数。
• ④ 每镜给建议秒数：各镜秒数之和量级贴合区间总时长。
• 定位：意图值，不是精确交付保证。多数平台由参数控时且不保证逐帧精确（各平台 fps 也不一），提示里写死秒数无用；把时长放元信息 + 每镜建议秒数，最终对齐在用户手动拼接那一步完成。
• 时码只读不改：本 skill 不写回 dispatch / struct_meta，只读 track_st/track_ed。

工作流

Step 1 · 通读该 beat 文稿：判有无历史/时代锚点（年份 / 地点 / 人物 / 事件）、主体是谁、情感落点在哪、叙事功能与阶段。dispatch 缺的参数在此推断并标注「推断」。

Step 2 · 拆蒙太奇段与镜：按 craft A 判是否长文段需分蒙太奇段，段内按情感颗粒切镜，定各段镜数（文稿长度 × track 时长双校准）。

Step 3 · 锁风格：按「业务分离」节解析栏目 Style Lock（读配置 → 取 produces==AI_DRAMA 条目 → 读其风格资产）；无则取中性默认。组装成 60–120 字/词的 CN + EN 双语 ①视觉基调段。

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 把未通过稿件落进工程。校验器不可用时，至少逐项执行下面「解析器硬契约」与交付前自检。用户直投单段时同样先校验，再落到用户指定的工程路径。临时稿无论成功失败都删掉。

输出契约（落盘 Markdown 结构 · 中英分块）

顶部放一次责权利声明 + 元信息（不分语言）；然后 `## 一、中文稿` 一整块、`## 二、English Storyboard` 一整块，用户整块复制。

解析器硬契约（默认必须满足）

下列是 gitruck-ai-drama-desk 的机器接口，不是排版建议：

• H1 标题含半角或全角括号包住的 beat <beat_id>，例如 （beat B03）。
• 元信息使用同一行：- 区间总时长：track_st 37.685 → track_ed 65.665 ≈ 27.980 秒；不要拆成「工程时间位」和「目标时长」。
• 中文与英文块标题分别以 ## 一、中文稿、## 二、English Storyboard 开头；不要简写。否则英文 ①–④ 会被当成中文段并覆盖前面的中文段。
• ③ 内每个角色都用 #### <角色名>（<备注>） 开头，描述写在下一段；不要把角色写成 - 男性：…… 项目符号。
• ④ 中文镜头头必须匹配 #### 分镜 <数字> · <标题> ｜建议 ≈<秒数>s ｜段：… ｜场景：… ｜角色：… ｜对应原文：…；英文镜头头必须匹配 #### Shot <数字> · <title> ｜≈<seconds>s ｜segment: … ｜scene: … ｜cast: … ｜source lines: …。必须用 Markdown 四级标题，中文关键词是「分镜」而不是「镜头」。
• 每镜标题后的首个非空正文必须以 〔本镜视觉基调〕 开头，解析器据此填 stylePrefix；不要写成 - 视觉基调前缀：…… 普通项目符号。① 的负面词必须单独使用 > 禁忌：…，英文用 > Avoid: …，否则会被吞进 Style Lock 正文而不是负面字段。
• 蒙太奇分段只写进镜头头的 ｜段：… / ｜segment: … 字段；④ 内不要另插 #### 蒙太奇段… / #### Montage… 标题，解析器会把它吞进前一镜描述。
• 中英文镜头序号一一对应；至少一镜；每镜建议秒数写在头部字段，不要藏在正文项目符号里。

校验命令（从本 SKILL.md 所在目录解析相对路径）：

bun scripts/validate-storyboard.mjs <候选稿.md>

通过时输出单行 JSON 并退出 0；不通过时逐条列出违约项并退出非零。它校验的是生产端硬契约；工作台仍是最终权威，仓库可用时可再用其 server/lib/parse.ts 做回归。

# AI 情景动画分镜稿 · [自动标题]（beat <beat_id>）
 
> [责权利声明：本稿只描述意图与时长；角色一致性依赖下游角色资产机制；出片/拼回在用户手里]
 
## 元信息
- 区间总时长：track_st→track_ed ≈ X 秒
- 建议分镜数：N 镜（含 M 个蒙太奇段）
- 复现角色：<角色名>（栏目级·pin 复用 / 本片新建）…
- 叙事功能 / 情感阶段：xxx（用户指定 / 推断）
- 目标平台：xxx（缺省 = 通用）
 
======================================================================
## 一、中文稿（喂可灵 / 即梦 / Vidu / 通义）
======================================================================
 
### ① 视觉基调（Style Lock）
> 权威源，供各分镜前缀复述。来源：<解析到的 ref skill> / 中性默认
[底色 / 中性调 / 单点强调色 / 材质 / 影视参考，60–120 字]
> 禁忌：[通用 AI slop 兜底 + 栏目专属禁令]
 
### ② 故事背景描述
[时代 / 地点 / 世界观 / 场景。末句锁调：整段以……色彩与质感呈现。]
 
### ③ 角色描述
#### <角色名>（栏目级·pin / 本片新建）
脸型 / 发型 / 瞳色 / 服装 / 标志物 + 禁变项（不留长发、不换西装…）+ 一句质感落点。
 
### ④ 分镜描述
#### 分镜 01 · [标题] ｜建议 ≈Xs ｜段：<蒙太奇段名> ｜场景：xxx ｜角色：xxx ｜对应原文：第 a–b 句
〔视觉基调前缀复述一句〕+ 主体在做什么具体动作 + 蒙太奇级镜头意图（不逐帧硬控）。
#### 分镜 02 · …
 
### ⑤ 原文文稿（本区间口播原文，不翻译）
1. [第一句中文原文]
2. [第二句中文原文]
…
 
======================================================================
## 二、English Storyboard (for Veo / Runway / LTX / Luma)
======================================================================
 
### ① Visual Tone (Style Lock)
> Authoritative source; restated as a prefix in every shot. Source: <resolved ref skill> / neutral default
[palette / neutrals / single accent / texture / film references]
> Avoid: [generic AI slop floor + column-specific bans]
 
### ② Background
[era / place / world / setting. Closing line locks palette & texture.]
 
### ③ Characters
#### <name> (column-pinned / new to this film)
face / hair / eyes / wardrobe / signature prop + do-not-change + one line on how they render in the tone.
 
### ④ Shots
#### Shot 01 · [title] ｜≈Xs ｜segment: <montage segment> ｜scene: xxx ｜cast: xxx ｜source lines: a–b
〔restate style prefix〕+ subject's concrete action + shot intent (montage-level, not frame-locked).
#### Shot 02 · …

⑤ 原文文稿只在中文稿里；English 块到 ④ Shots 为止。

中性默认（未绑 AI_DRAMA 风格资产时）

栏目配置里没有 produces==AI_DRAMA 的条目时，别停、别硬套别的栏目，用这套克制、通用、不特化任何栏目的兜底写 ①视觉基调段：

中性 Style Lock：影视级自然主义画面，真实可信的光源（窗光 / 实用光 / 自然天光，不炫技），克制稳定的镜头语言（固定或缓慢推拉摇，无手持抖动 / 无广告级动态运镜 / 无无人机炫技），近单色到低饱和的克制调色（不追 HDR、不追霓虹），胶片颗粒质感。忌塑料 3D 渲染、忌动漫二次元、忌过度戏剧化打光。

EN: Cinematic naturalism, believable practical light sources (window / practical / natural daylight, no showing off), restrained stable camera language (locked or slow dolly/pan/tilt, no handheld shake, no ad-grade dynamic moves, no drone stunts), near-monochrome to low-saturation restrained grade (no HDR, no neon), visible film grain. Avoid plastic 3D render, anime, and over-dramatic lighting.

中性默认下不设单点强调色 / 不指定影视导演锚点（那些是栏目资产）。用完顺带提醒用户：想要这条栏目有自己的 AI 情景动画视觉 DNA，去 `/gtrk-style-maker` 沉淀一套 AI_DRAMA 风格资产并登记进 `style.skills`，之后每次生成都会自动注入。分镜稿与提示词层也可查推荐目录（公约 §三‴）：gtrk skills recommend --scene ai-drama，装完用 gtrk skills add <owner/repo> 登记；本 skill 正文不点名任何仓。