/gbro-collage-broll

name: gbro-collage-broll
description: 将约 5 秒口播文稿、观点句或抽象概念做成高级 editorial halftone paper-collage / 半调纸拼贴 B-roll。用户说“collage b-roll”“纸拼贴 b-roll”“半调拼贴”“拼贴风格配画面”“用这段文稿做拼贴动画”“gbro-collage-broll”，或希望把一句文稿转成拼贴视觉隐喻时，必须使用此 skill。强制采用三阶段审批：先只提视觉隐喻，用户确认后才生成彩色拼贴静帧，静帧再次确认后才默认调用 Gemini Omni Flash 生成首尾帧组装动画。默认视频模型固定为 gemini-omni-flash-preview，不再默认使用 Veo；只有用户明确指定其他模型时才切换。
compatibility: 在 Codex 环境运行（Gate 2 依赖内置 image_gen）。视频生成脚本已随本 skill 自带（scripts/generate_video.py），另需 Python >= 3.10、google-genai >= 2.10.0、已配置的 GEMINI_API_KEY，以及 ffmpeg / ffprobe。首次使用先按「首次使用：环境自检」完成配置。

gbro Collage B-roll

把一句约 5 秒的口播压成一个 sharp visual idea，再做成高级编辑风纸拼贴组装动画。

默认链路：

1. 只设计视觉隐喻，等待用户确认 2. 只生成最终静帧，等待用户确认 3. 自动调用 Gemini Omni Flash 生成视频并完成 QA

这两个确认闸门是工作流的一部分。它们让用户把注意力放在审美和方向上，同时避免错误隐喻或错误静帧直接消耗视频生成成本。

首次使用：环境自检

每次触发本 skill 时，进入 Gate 1 之前先运行自检脚本：

bash <本skill目录>/scripts/check_setup.sh

全部通过则直接开始 Gate 1，不要向用户重复配置信息。任何一项失败时，视为首次使用：不进入 Gate 1，先向用户输出下面的配置指南（只列出缺失项），等用户确认配置完成后重新自检。

配置指南（按缺失项输出）

1. **GEMINI_API_KEY 未设置** 到 [Google AI Studio](https://aistudio.google.com/apikey) 创建 API key，然后写入 shell 配置：

   echo 'export GEMINI_API_KEY="你的key"' >> ~/.zshrc && source ~/.zshrc

注意：视频生成按量计费，由这个 key 对应的 Google 账号承担。

2. **ffmpeg / ffprobe 缺失** macOS：`brew install ffmpeg`；Debian/Ubuntu：`sudo apt install ffmpeg`。

3. **Python 环境缺失或版本过旧**（需要 >= 3.10） macOS：`brew install python3`；或从 python.org 安装。

4. **共享 venv 未创建**（google-genai >= 2.10.0） 征得用户同意后自动创建，无需用户手动操作：

   python3 -m venv ~/hyperframes-projects/.omni-venv
   ~/hyperframes-projects/.omni-venv/bin/python -m pip install --upgrade "google-genai>=2.10.0" "httpx[socks]"

5. **不在 Codex 环境 / 没有内置 image_gen** Gate 2 的静帧生成依赖 Codex 内置 `image_gen` 工具。在其他 agent 环境下运行时，向用户说明需要自行提供等效的图片生成方式（或手动提供静帧图片后从 Gate 2 确认继续）。

强制审批协议

Gate 1：隐喻确认

收到文稿后，先提视觉隐喻，不生成图片、不生成视频、不调用任何视频模型。

向用户交付每条的：

• 核心意思
• 情绪
• 一句话视觉命题
• 3–6 个关键物件
• 建议底色与局部点色
• 预期组装顺序

然后明确停下，等待用户回复“可以”“通过”“全部通过”或给出逐条修改意见。

如果用户只确认部分编号，只让通过的条目进入 Gate 2；未通过条目继续修改隐喻。

Gate 2：静帧确认

隐喻确认后，才写 visual spec 和 imagegen prompt，并用 Codex `imagegen` 生成最终静帧。

把原图保存到项目目录，生成带编号的静帧 contact sheet，向用户展示并再次停下。此阶段仍然不调用 Omni Flash，也不生成视频。

如果用户只确认部分静帧，只让通过的条目进入 Gate 3；需要修改的静帧先重生并重新确认。

Gate 3：视频生成

静帧确认后，不再询问使用哪个视频模型，直接使用本 skill 自带的 `scripts/generate_video.py`，默认调用：

gemini-omni-flash-preview

只有用户明确指定其他视频模型时，才覆盖这个默认值。不要自动调用 Veo，也不要把模型选择再抛给用户。

成功标准

• 一句话只表达一个清晰隐喻
• 同一批画面有统一设计语言，但不强制全部蓝底
• 背景是强烈、平坦、均匀的色场，可按语意变化
• 主体以黑白 halftone photographic cut-outs 为骨架
• 关键卡片、按钮、胶片、规则册等允许使用红、黄、青、橙、紫、奶油白等彩色纸张
• 所有纸片有清晰裁切边、奶油白 keyline、低透明度柔和阴影和纸张颗粒
• 动作是 assemble-from-empty，而不是轻微漂移、晃动或慢 zoom
• 无字幕、无口播全文、无 logo、无水印、无 UI
• 默认交付 9:16、5 秒、720×1280、24fps、无声 MP4

什么时候不要用

• 需要精确控制图层、遮挡、镜头穿越或可编辑时间线：改用分层动画工具（如 HyperFrames 类 HTML 渲染视频方案）
• 只需要视频提示词，不需要生成成片：直接写 prompt 即可，不用走本流程
• 需要真实人物产品广告或口播演员：不要走本拼贴流程
• 用户明确要可逐层修改的透明素材：本 skill 默认不拆透明图层

默认项目目录

使用北京时间 `Asia/Shanghai` 命名：

~/hyperframes-projects/YYYY-MM-DD-collage-broll-标题/

批量项目推荐结构：

<project>/
├── brief.md
├── visual-spec.json
├── imagegen-prompts.md
├── omni-jobs.json
├── gate2-qa.md
├── gate3-qa.md
├── still-contact-sheet.jpg
├── omni-contact-sheet-all.jpg
├── video-first-frame-all.jpg
├── end-frame-comparison-all.jpg
├── 01-概念名/
│   ├── omni-prompt.txt
│   ├── frames/
│   │   ├── last-frame-original.png
│   │   ├── first-frame.png
│   │   └── last-frame.png
│   └── omni/run-v01/
│       ├── final-5s.mp4
│       ├── final-5s-noaudio.mp4
│       ├── contact-sheet.jpg
│       ├── video-last-frame.jpg
│       └── end-frame-comparison.jpg
└── 02-概念名/...

Phase 1：设计视觉隐喻

先把文稿压成一个视觉命题。

提取：

• 核心意思：观众最终要看懂什么
• 情绪：冷静、惊讶、紧迫、豁然开朗、荒诞、反讽
• 动作动词：打开、连接、漏掉、装订、归档、点亮、压缩、分叉、组装
• 可视化隐喻：机器、时钟、胶片、档案柜、控制台、规则册、漏斗、轨道、棋子

不要把文稿逐字放进画面。默认一条文稿只做一个隐喻，控制在 3–6 个关键物件；元素过多会让语意变弱，也会让 Omni 组装不稳定。

批量隐喻优先形成前后叙事：例如先表现手工消耗与经验流失，再表现规范沉淀与人机分工。

Gate 1 输出示例

1. 核心意思：经验每次都在重复消耗
   视觉隐喻：熟练剪辑师围着巨大的胶片时钟逐帧裁切，时钟走完一圈却只得到一小段成片
   关键物件：胶片时钟、剪辑师、剪刀、短胶片
   色彩：焦橙底，奶油白与浅青点色
   组装顺序：时钟 → 人物与剪刀 → 胶片 → 最终短输出

输出后停下等待确认。

Phase 2：生成彩色拼贴静帧

隐喻确认后，先写自包含的 `visual-spec.json`，再写 imagegen prompt。

Visual spec

{
  "script_meaning": "",
  "visual_metaphor": "",
  "style_signature": "flat bold color field, mixed black-and-white halftone cut-outs and colored cardstock accents, crisp cut edges, cream keylines, soft paper shadows, editorial paper collage",
  "aspect_ratio": "9:16",
  "color_field": {
    "background_hex": "",
    "accent_colors": [],
    "paper_grain": "fine uncoated-paper fiber"
  },
  "elements": [
    {
      "what": "",
      "role": "",
      "motion": "",
      "placement": ""
    }
  ],
  "composition": {
    "layout": "",
    "negative_space": "",
    "final_frame": ""
  },
  "motion_plan": "structure first, subject or cards second, action and result last",
  "avoid": "typography, readable letters, numerals, logos, watermark, UI, subtitles, glossy 3D, photoreal environment"
}

色彩规则

不要把 cobalt blue 当成唯一默认值。根据语意挑选强色场，并在一批作品中保持“同设计语言、不同底色”：

• 焦橙 / 红：时间消耗、劳动、紧迫
• 芥末黄：工具、警示、经验漏失
• 墨绿：认知、审美、系统重置
• 深紫：规范、沉淀、长期记忆
• 青绿：判断、协作、自动执行

主体可以黑白半调为主，但局部彩色纸张必须服务信息层级，不要为了彩色而彩色。

Imagegen prompt 模板

使用 Codex 内置 `image_gen` 工具（如有本地 `imagegen` skill 则一并遵守）：

Use case: ads-marketing
Asset type: final still frame for a 9:16 image-to-video B-roll clip
Primary request: Create a finished editorial paper-collage image expressing [一句话视觉命题].
Scene/backdrop: perfectly flat [颜色] paper field [hex] with subtle uncoated paper fiber.
Style/medium: premium editorial stop-motion paper collage; black-and-white halftone photographic cut-outs mixed with selective [点色] colored cardstock.
Composition/framing: vertical 9:16 locked poster frame; central subject within the middle 70 percent; generous clean color-field negative space; 3–6 large separable paper groups for later assemble-from-empty animation.
Materials/textures: visible printed halftone dots, crisp machine-cut edges, thin warm-cream paper keylines, soft low-o