quickdesign

QuickDesign CLI 技能

这项技能将教会 Claude 如何通过 quickdesign CLI 规划并执行 AI 媒体生成。该 CLI 封装了 QuickDesign 托管的模型（Seedance 2.0 R2V/I2V、Kling、Sora 2、Nano Banana、GPT Image、视频超分），因此 Claude 会话可以直接通过 Bash 生成视频和图像，无需管理 API 密钥、轮询或上传存储。

何时调用

• 口播头像 / UGC 视频——“制作一支 30 秒广告，让这个人说 X”“把这段脚本转换成视频”“创建一段创作者自拍视频”
• 多片段宣传片 / 讲解视频——总口播时长超过 15 秒（单个 Seedance 片段时长上限），或用户希望切换角度 / 逐步调整构图的任何任务
• 图像编辑 / 生成——更改角度、更改状态、白底产品图、生活方式合成图、应用品牌套件风格的创意素材、多产品参考图合成
• 视频超分——将 720p / 1080p 输出提升至 1080p / 4K
• 批量创意素材制作——“对这 5 张产品照片逐一执行此操作”

不要用于：纯文本生成、代码编辑、搜索——这些任务有各自的工具。

基本规则（每次都要先读）

以下规则适用于每次生成。违反任何一条都会产生明显瑕疵。

0. 默认视频模型 = seedance-2.0-r2v，适用于任何 UGC / 口播头像 / 宣传片 / 讲解视频 / 多场景任务，不受时长或片段数量影响。 不要因为脚本“足够短”就降级到 seedance-2.0-i2v——R2V 处理 4-15 秒的单镜头效果不逊于多片段生成，而且从一开始就使用 R2V，可以保留此技能依赖的所有功能（@Image1 引用、多项 --reference-image、--reference-audio 声音连续性）。只有在用户明确选择（“使用 Sora 2”）或注册表中没有 R2V 时，才切换到其他模型。

   ⚠️ “i2v”（图生视频）这个名称容易误导。 R2V 也支持单图转视频流程——只需传入一个 --reference-image。不要因为任务是“图生视频”就选 i2v。类似 “用户想让静态图像动起来 → 图生视频 → 因此选 seedance-2.0-i2v” 的 Agent 推理链，正是这条规则要防止的隐蔽退化。即使只是制作一段没有口播、也不需要多重参考的单香蕉编辑动画，R2V 仍然是默认选择——i2v 没有任何优势，而且会放弃这些功能；如果任务下一轮确实需要它们，就会受到影响。

   参见 models/seedance-2.0-r2v.md。

1. 在提示词中使用 @Image1 / @Audio1 / @Video1 参考标签，并将每张相关照片分别作为参考传入。 nano-banana-2（图像编辑）和 Seedance 2.0 R2V（视频）都支持多个 --reference-image 标志。如果用户上传了从两个角度拍摄的产品照片，就把两张都传入——用文字描述第二张照片是退步。不要用文字重新描述人物、服装或产品；这会与参考图产生冲突并导致偏差。

   ❌ 错误——逐字冗长地重新描述 @Image1：

   Authentic UGC photo of the woman from the reference (long wavy brown
   hair, natural glowy makeup, glossy peach-coral lips, gold hoop earrings,
   pearl choker, soft smile), wearing the beige suede sneakers from the
   second reference, in a cozy minimal bedroom...
   

   Banana 已经能从 @Image1 中看到她的头发 / 妆容 / 嘴唇 / 首饰，也能从 @Image2 中看到运动鞋的颜色 / 轮廓 / 鞋底。重新描述这些内容等于告诉模型“忽略参考图，按这段文字绘制”，会与视觉锚点冲突并导致偏差。

   ✅ 正确——让标签发挥作用，文字只描述新增内容：

   Edit @Image1: change pose to iPhone mirror selfie. Add a white ribbed
   tank top + oversized baggy jeans. Sneakers matching @Image2 visible at
   the bottom of the frame. Keep face, hair, makeup, jewelry, and
   lighting unchanged from @Image1.
   

   参见 references/multi-reference-pattern.md 和 models/ 下对应模型的说明文档。

2. 多片段声音连续性 = 使用从第 1 段提取的音频作为 --reference-audio。 先生成第 1 段 → 使用 ffmpeg -vn -acodec libmp3lame 提取音频 → 将该 mp3 作为 --reference-audio 传入第 2 至 N 段。否则每个片段都会使用不同的声音。参见 references/voice-continuity.md。

3. 抑制叠加的背景音乐和烧录字幕——只添加最精简的指令。 在提示词中加入两行简短内容：No music score. 和 No subtitles or on-screen text. 仅此而已。不要逐一列出你想保留的环境音（“街道噪声、咖啡馆交谈声、意式咖啡机声”）——Seedance 会自行生成自然的环境音；过度指定会让音频听起来像是刻意编排的。参见 references/no-music-no-subtitles.md。

4. 如需烧录字幕，请在生成完成后使用 quickdesign video subtitle。 切勿通过提示词让视频模型自行烧录字幕——它们会产生幻觉。专用字幕端点会运行真正的 ASR（ElevenLabs），并渲染准确的卡拉 OK 风格字幕。参见 references/auto-subtitle.md。

5. 确认关卡——即使在自动模式下，也要在消耗额度前暂停。 自动模式可减少低成本、可逆工作（文件编辑、研究、规划）的操作阻力。付费 AI 生成既不是低成本，也不可逆——自动模式不会绕过这些关卡。务必做到：

   • 任何视频生成前都要提供计划摘要（类型 / 模型 / 时长 / 费用 / 脚本）。先展示摘要，然后要么等待用户明确表示“开始”（普通模式），要么立即继续，同时将计划显示在 bash 调用上方，以便用户在费用消耗完成前终止任务（自动模式）。计划必须在 bash 调用之前给出，绝不能在之后。
   • 将 Banana 编辑结果交给 Seedance R2V 前，必须先确认 → 展示编辑结果，等待用户进行视觉确认。Banana 约需 12cr，Seedance 约需 250-500cr；如果自动串联了错误的参考图，消耗的额度会高出 50 倍。自动模式下也不能缩短此确认流程。
   • 关于自动模式下的完整交互规则，请参见 references/confirmation-rules.md。

6. 对于选择类关卡，请使用 AskUserQuestion 工具，而非自由形式的文字。 模型选择器、转场风格、分辨率、批准 / 重新生成 / 取消 Banana 编辑——请调用 AskUserQuestion 并提供结构化选项列表，将你的推荐选项放在首位，并标注 (Recommended)。参见 references/confirmation-rules.md。

7. 如果提供了头像且场景不变，请编辑头像——不要重新生成。 类似合成的 Banana 提示词（“Compose a vertical 9:16 UGC selfie frame...”“Generate a creator-selfie scene...”）会让模型渲染一张受头像启发的新 AI 风格图片，丢失原图的光线、颗粒感和低保真真实感。结果会显得合成，而不像真实创作者编辑过的自拍。使用编辑风格的动词（Edit @Image1: add ...、Take @Image1 as-is and only change ...、Keep every pixel of @Image1 except [region]），不要重复列出参考图中已有的场景元素，并从提示词中删去提升画质的词语（“photo-realistic”“studio quality”“8K”）——它们会触发重新生成。参见 references/avatar-edit-not-regenerate.md。

8. 对于 UGC 视频，要明确询问用户选择说话还是静音——不要擅自决定。 “UGC video”含义模糊：它既可以是口播创作者片段（由脚本驱动，包含语音和口型同步），也可以是仅有动作的片段（OOTD 展示、B-roll、后期添加文字叠层的动画静帧）。这两种都是合理的创作形式。Agent 不得擅自选择其中一种：

   • 明显倾向于口播（直接执行）：用户写了“talking-avatar”“creator says”“voiceover”“explainer”“ad with script”，或自行提供了脚本。编写脚本 → 将其放入计划摘要 → 使用 generate_audio: true 并在提示词中内嵌引用的台词进行生成。
   • 明显倾向于静音（直接执行）：用户写了“OOTD reveal”“motion only”“no audio”“B-roll”“Pinterest aesthetic”，或想要静态图片动画短片。
   • “UGC video” / “promo video” / “ad video”等含义不明确——请调用 AskUserQuestion，提供两个选项：口播（附带一条 4-8 个单词的初稿钩子）或静音 + 后期文字叠层。根据用户的需求简述推荐更合适的选项。不要默认选择。 选择 SPOKEN 时：如果提示词中没有带引号的台词，绝不要开始生成。如果用户没有提供台词，就起草 4-12s 的对话，使其符合需求，将其呈现在计划摘要中，然后再继续。使用通用动作提示词且不包含带引号的台词，会生成无声视频或模型胡乱念出的音素——浪费额度。

   字数与时长的换算方法见 references/script-and-duration.md。

9. 多片段计划在第 1 段后必须暂停，等待用户确认画面——用户确认第 1 段效果正确之前，不要并行生成第 2..N 段。 为保持声音连贯性，后续每个片段都会通过 --reference-audio 使用第 1 段的音频。如果第 1 段的声音、虚拟形象身份、单词发音或品牌调性构图有误，并行生成的第 2..N 段都会继承这些缺陷。一个 4 段计划每段约需 250cr，总计约 1000cr；如果第 1 段有问题却自动并行生成，就会白白浪费约 750cr。

   流程如下：

   1. 呈现计划摘要 → 用户批准（规则 5）。
   2. 仅渲染第 1 段。
   3. 在聊天中呈现第 1 段的视频 URL + 调用 AskUserQuestion 并提供以下选项：
      • 效果不错——渲染第 2..N 段 （如果第 1 段效果理想，建议选择）
      • 重新渲染第 1 段（调整提示词 / 参考素材 / 时长）
      • 取消多片段计划
   4. 只有用户选择“效果不错”后 → 才使用提取出的音频并行生成第 2..N 段。

   自动模式下，此检查步骤不会缩短生成耗时。无论用户愿意等待多久，第 1 段至第 N 段的花费倍数都相同。规范的多片段流程见 pipelines/ugc-video.md。

10. 保持摄像机不动。除非用户明确要求，否则不要改变角度 / 构图。 纪录片风格的 UGC（街头采访、厨房演示、创始人第一视角、客户证言、Vlog 风格）应当呈现为摄像机位置连续不变，而非多角度剪辑序列。默认设置：所有片段保持相同构图（例如，平视中景）、相同距离，虚拟形象的位置大致相同。片段之间的“过渡”应由虚拟形象的手势 / 台词 / 细微表情来实现，而不是切换角度。

    ❌ 错误的默认设置（静默退化——会产生“摄影指导安排的镜头”之感，破坏 UGC 的真实感）：

    • 第 1 段为中景 → 第 2 段为过肩镜头 → 第 3 段为特写
    • “缓慢推近说话者”
    • “在包袱处切至产品特写”
    • 每个 nano-banana-2 片段都使用同一个人的不同角度参考图

    ✅ 正确的默认设置（保留 UGC 的真实感）：

    • 所有片段使用相同的源画面或几乎相同的角度 / 光线。片段之间只改变虚拟形象的手部位置、视线或表情。

    只有在用户明确要求时才切换到多角度：“每个片段交替使用不同角度”“在开场钩子处电影感地切至特写”“加入产品的过肩镜头”“影棚风格的多机位 UGC”。不确定时，通过 AskUserQuestion 询问：固定摄像机（纪录片风格 UGC 推荐）/ 多角度（电影感剪辑）。

    关于静态构图与描述的摄像机运动，相关规则见 references/first-frame-not-camera-motion.md。

11. 检查用户提供的所有参考素材——对于 UGC，仅有产品素材是不够的。 如果需求是“为这个产品制作 UGC 视频”，而用户只提供了产品照片，就必须在生成前暂停。Seedance R2V 需要以下内容的锚定参考：产品、虚拟形象 / 创作者（面容、体型、气质），以及场景 / 地点（厨房、浴室、健身房、人行道）。文字可以详细描述产品，但如果只用文字描述虚拟形象，Seedance 就会凭空生成一个外表泛泛的人物——通常是 20 多岁、带有合成感的白人女性——场景也会像库存 B-roll，而不像品牌自身的世界。最终效果达不到“看起来不像是制作出来的”这一标准。 生成前，检查用户提供的媒体：

    • 产品图片 — 几乎总会提供。通过 --reference-image 传入，并使用提示词标签 @Image1。
    • 头像 / 创作者图片 — 如果用户提供了图片，通过单独的 --reference-image 传入，并标记为 @Image2。如果用户没有提供，生成前调用 AskUserQuestion：上传创作者头像 / 从 QuickDesign 头像库（5,000+ 张肖像）中选择 / 根据文字描述创作者后继续（存在合成感风险）。 如果用户只提供了简短描述，建议选择“从头像库中选择”。
    • 场景 / 地点图片 — 如果用户要拍摄“厨房场景”“浴室镜前自拍”“办公室桌面视角”等，询问他们是否有实际房间的参考照片。如果提供了，通过 @Image3 传入。

    Seedance R2V 调用应如下所示：

    quickdesign video generate --provider seedance \
      --reference-image product.jpg \
      --reference-image avatar.jpg \
      --reference-image scene.jpg \
      --aspect-ratio 9:16 --duration 12 --resolution 1080p \
      -p '@Image2 in @Image3, holds @Image1 toward camera. She says: "..." No music score. No subtitles or on-screen text.' \
      -o seg1.mp4 --wait
    

    @Image1/@Image2/@Image3 标签是关键；文字描述只需说明动作和引号中的台词。参见 references/multi-reference-pattern.md。

决策树——先打开哪份文档

按任务类型：

请求	从这里开始
UGC / 对话头像 / 宣传片 / 讲解视频 / 多片段广告	pipelines/ugc-video.md → models/seedance-2.0-r2v.md
图像编辑（角度、状态、多产品构图）	models/nano-banana-2.md → references/multi-reference-pattern.md
电影感单镜头、以音频质量为重点（4/8/12s）	models/sora2-i2v.md（仅限用户明确选择使用）
低预算循环视频 / 无对白 B-roll	models/kling-3-pro.md
最终视频分辨率过低	models/topaz-video-upscale.md（拼接后运行）
为现有视频添加字幕	references/auto-subtitle.md
Spy Brands 库中没有该品牌 / 搜索结果为 0	references/spybrands-add-on-miss.md
用户正在使用 claude.ai（网页），并询问 QuickDesign	references/connecting-claude-ai-via-mcp.md
将设计发布到 Meta 作为广告 / 分析自己的 Meta 广告表现	references/deploy-meta.md

按任务阶段：

阶段	阅读
规划：脚本 / 时长计算、叙事节拍	references/script-and-duration.md、references/narrative-arc.md
预检：注册表中哪些模型可用	quickdesign video models、quickdesign cost --category video
各片段的参考素材选择	references/multi-reference-pattern.md、references/narrative-arc.md
生成：所选模型的提示词框架和注意事项	models/<slug>.md
质量门槛：香蕉解剖结构检查、计划摘要审批	references/confirmation-rules.md
后期处理：字幕、升频	references/auto-subtitle.md、models/topaz-video-upscale.md

运行时发现

模型注册表由数据库驱动，并会随时间变化（新增提供商、弃用版本、重新定价的档位）。不要硬编码对模型的假设——在从备选项中做选择时，先查询注册表。

quickdesign video models                            # active video models
quickdesign image models                            # active image-edit models
quickdesign cost                                    # all models, grouped by category
quickdesign cost --category video
quickdesign cost <slug> -d <duration> -r <resolution>   # exact compute for one model + params

当有新模型比当前默认模型更适合时，在 models/<slug>.md 中新增文件（复制任意现有模型卡的格式）；如果该模型成为新的通用默认模型，则更新首要规则 #0 / 决策树。

快速入门——常用命令

# Auth (one-time, browser flow)
quickdesign auth login

# Image edit — angle change / state change / multi-ref product composition
quickdesign image generate \
  --model nano-banana-2 \
  --reference-image ~/path/to/avatar.jpg \
  --reference-image ~/path/to/product.jpg \
  --aspect-ratio 9:16 --resolution 2K \
  -p "@Image1 holds a product matching @Image2 exactly. ..." \
  -o ~/output.png --wait

# Single Seedance R2V (≤15s spoken script — still R2V, not i2v)
quickdesign video generate \
  --provider seedance \
  --reference-image ~/path/to/source.png \
  --aspect-ratio 9:16 --duration 12 --resolution 1080p \
  -o ~/output.mp4 --wait \
  -p '@Image1 in the same setting. <action>. He/She says: "..." No music score. No subtitles or on-screen text. Vertical 9:16 format.'

# Multi-segment Seedance R2V with voice continuity
# 1) Generate Seg 1 (sequential, native audio)
quickdesign video generate --provider seedance --reference-image seg1.png \
  --duration 12 --aspect-ratio 9:16 --resolution 1080p \
  -p '...' -o seg1.mp4 --wait
# 2) Extract Seg 1 audio
ffmpeg -y -i seg1.mp4 -vn -acodec libmp3lame -q:a 2 seg1-audio.mp3
# 3) Segs 2..N in parallel, each with --reference-audio
quickdesign video generate --provider seedance \
  --reference-image seg2.png --reference-audio seg1-audio.mp3 \
  --duration 12 --aspect-ratio 9:16 --resolution 1080p \
  -p '...' -o seg2.mp4 --wait &
# 4) Concat (mux-only, no quality loss)
printf "file 'seg1.mp4'\nfile 'seg2.mp4'\n" > /tmp/concat.txt
ffmpeg -y -f concat -safe 0 -i /tmp/concat.txt -c copy final.mp4

# Auto-subtitle (karaoke style, post-generation)
quickdesign video subtitle ./final.mp4 \
  --style tiktok --language en \
  -o ./final-subbed.mp4 --wait

文件索引

SKILL.md                           ← you are here: cardinal rules + decision tree + nav
references/                        ← model-agnostic concepts (read for principles)
   confirmation-rules.md           ← gates, AskUserQuestion convention, anatomy self-check
   multi-reference-pattern.md      ← @Image1/@Image2/@Image3 multi-ref usage
   avatar-edit-not-regenerate.md   ← edit-style verbs, don't compose-regen the avatar
   spybrands-add-on-miss.md        ← when `spy brands --search` returns 0: confirm + resolve FB page + `spy add`
   connecting-claude-ai-via-mcp.md ← claude.ai (web) users: how to connect via MCP, what's available vs. CLI-only
   deploy-meta.md                  ← `meta` commands: publish designs as PAUSED Meta ads + insights/report/radar analytics
   voice-continuity.md             ← --reference-audio across multi-segment
   no-music-no-subtitles.md        ← minimal music + subtitle suppression
   auto-subtitle.md                ← post-generation captions (real ASR, not model-burned)
   narrative-arc.md                ← per-segment reference decision tree
   script-and-duration.md          ← word count → segment math, gender-neutral defaults
   first-frame-not-camera-motion.md ← why "static hold" / "slowly zooms" cause defects
   brand-and-moderation.md         ← brand-kit conventions, content moderation
pipelines/                         ← multi-step workflows (model-agnostic where possible)
   ugc-video.md                    ← canonical multi-segment talking-avatar method
models/                            ← per-model reference cards (gotchas + prompt skeletons)
   seedance-2.0-r2v.md             ← DEFAULT for UGC / promo / talking-avatar
   seedance-2.0-i2v.md             ← niche; explicit user opt-in only
   nano-banana-2.md                ← default for image edit + multi-ref product composition
   sora2-i2v.md                    ← cinematic single-shot, opt-in
   kling-3-pro.md                  ← budget alternative for non-spoken b-roll
   topaz-video-upscale.md          ← post-pipeline upscale

用户提出具体需求时，直接跳转到 models/ 或 pipelines/ 中的相关文件。上述首要规则是唯一应始终保留在活动上下文中的内容。