Utopai-Research/pai-pro

CLI 形状

标准层级：

node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." [--aspect-ratio 16:9] [--image-size 2K] [--label "..."] [--subtype <character|location|edit|reference|split|storyboard>] [--name "..."] [--role "..."] [--description "..."] [--source-node-id <id>] [--ref-source-id <id> ...]

用于故事板拼贴和视频绑定角色表的 Pro 层级：

node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 [--label "..."] [--subtype <character|location|edit|reference|split|storyboard>] [--name "..."] [--role "..."] [--description "..."] [--source-node-id <id>] [--ref-source-id <id> ...]

Pro 仅接受 --size；无 --aspect-ratio / --image-size。常见尺寸：1024x1024、1280x720、720x1280、1920x1920、2560x1440、1440x2560、3840x2160、2160x3840。

若省略 --label，则默认使用截断的提示词（≤30 字符）；当你有更好的标题时请显式传递。

按 --ref-source-id 顺序使用 @Image1、@Image2……。CLI 为每个引用发射一条 derived 边。

首先使用 mirror_url.js --url <URL> 镜像外部 URL，然后通过 --ref-source-id 传递返回的 node_id。

如果笔记创作了图像，请传递 --source-node-id <note_id>。

不要尝试通过 ASCII 艺术或 Markdown 嵌入来虚构图像——请调用 CLI。

首次使用的图像模式

关于一次性询问流程和各模式价格，请参见项目 PROJECT_AGENT.md 中的“首次使用生成选择”部分。

模式映射：Standard 2K -> generate_image.js --image-size 2K；Pro 2K -> 精确的 Pro 2K；Max quality -> 精确的 Pro 4K。

模式

选择最适合的一个。关于源查找，请遵循项目 PROJECT_AGENT.md 中的“选择上下文”部分；本技能仅拥有图像特定的提示词和 CLI 形状。

角色预检。 首先询问：此角色是否将出现在下游视频中（video、clip、promo、宣传片、短片、连续剧、film、scene、拍片、shot、short film）？

1. 读取 workflow.json 以获取上传的参考图像（subtype:"reference"、metadata.source:"user_upload"、未归档）。
2. 绑定视频 -> 模式 7，而非模式 1。有可用时使用 ≥3 个演员参考；有 0-2 个参考时，生成纯文本的四格角色表。
3. 在触发前宣布一行内容；允许重定向到模式 1。
4. 一次性静态艺术/海报/肖像 -> 模式 1。

此预检不可协商。模式 1 的单张正面肖像为视频模型提供了一个过于狭窄的锚点；身份在镜头间会漂移。直接跳转到模式 1 进行视频工作是最常见的错误。

故事/脚本锚点默认值。 当 script-compose 或 story-to-video-workflow 将分解路由至此：

• 每个重要角色一个基础四格角色表。
• 重要角色变体的额外角色表：年龄、服装/制服/伪装、受伤/肮脏/潮湿/血迹状态、变形或连续性重要的外观。
• 影响镜头的场景的详细位置锚点。
• 同一位置的不同变体，用于构图/比例/时间/天气/光线/装饰/故事状态/特写细节覆盖的变化。
• 在锚点之后优先参考到剪辑。仅在被要求、难以控制或需要诊断时才使用故事板。
• 不要为了预算/速度而放弃材料变体；调用者应首先调整视频分辨率/运行时间。

1. 角色肖像（仅限一次性静态静帧）

触发器：角色肖像/头部特写/英雄/反派/主角仅用于一次性静态静帧。绑定视频 -> 模式 7。

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 9:16 --image-size 2K --subtype character --name "Detective Morris" --role "..." --description "..." — 无引用。角色是身份锚点，而非衍生品。
• 提示词模板：

  [style] character portrait of [NAME], [role]. [age, build, wardrobe, distinguishing features]. Front-facing medium close-up, eye-level, looking directly at camera, neutral expression. Plain neutral background, soft even lighting. No dramatic shadows, no stylized lighting, no side profile, no multiple views.

• 继承项目风格或默认为写实。为未命名角色命名。
• 无边 — 角色是根节点，因此没有 --ref-source-id。

2. 位置建立静帧

触发器：建立/设计/描绘一个位置，或批准 script-compose 的位置提议。

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 16:9 --image-size 2K --subtype location --name "Causeway" --description "..." [--source-node-id <script_or_shot_note_id>] — 无引用。位置是场景锚点，而非衍生品。
• 提示词模板：

  [style] establishing still of [LOCATION NAME]. [visual brief — architecture, lighting, atmosphere]. Wide shot, eye-level, no characters present.

• 保持画面中无人。包括建筑/布局、表面、装饰、时代、天气、时间、光线和故事状态（如相关）。
• 同一位置的不同变体在保持位置身份的同时，改变宽/近景比例、白天/夜晚、天气、装饰、损坏或细节覆盖。
• 默认无引用边。如果位置源自脚本或镜头笔记，请使用 --source-node-id 以便创作边落地。
• 后续： 在最后一个脚本位置之后，推荐下一个参考到剪辑渲染。仅在被请求/需要时才提及故事板。

3. 现有图像的编辑/变体/旋转视图

触发器：对现有图像进行更改/编辑/交换/替换/添加/移除/调整/假设/变体。

• 确定源节点（通常是最近的 image_result，或用户命名的）。获取 source.id 和 source.metadata.aspect_ratio。

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <source ratio> --image-size <source size or 2K> --subtype edit --source-node-id <source.id> --ref-source-id <source.id>。

• 提示词作为变换，而非完整的重新描述：

  <concrete change>. Preserve everything else.

  ✅ “将雨改为飘雪。保持侦探、服装和摄影构图不变。” ✅ “将同一角色渲染为完整的 3D 旋转视图角色表。保持面部、服装和比例。” ❌ “深夜小巷里的侦探，穿风衣……” — 过度指定，身份漂移。

• CLI 根据 --ref-source-id 从 <source.id> 发射衍生边。

• 多步骤链每步使用一个边/调用；不要将 A -> C 扁平化。

4. 包含现有角色的场景

触发器：将角色放入场景/镜头 X 和 Y / 位置中的角色动作。

• 确定涉及的每个角色——该人物的任何 image_result（最多 16 个）。收集每个角色的 id。
• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <fit the shot> --image-size 2K --ref-source-id <char1.id> --ref-source-id <char2.id> ...。
• 提示词：完整的场景描述。按角色名称命名每个角色，以便生成器将身份绑定到角色。在提示词中按 --ref-source-id 顺序引用它们为 @Image1、@Image2……。
• 无 --subtype — 场景既不是角色也不是编辑。CLI 为每个 --ref-source-id 发射一条衍生边。

5. 独立静帧

触发器：与现有画布内容无关的新图像（“生成一张黄昏山脉”、“一条黑色小巷——仅场景”）。

• 简单的 node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..."，使用合理默认值（16:9, 2K，除非用户另有要求）。无子类型，无引用。

6. 故事板拼贴 — 每个剪辑/镜头笔记一个合成图像

触发器：故事板、拼贴、网格、镜头列表、覆盖、关键帧表、镜头规划、图像预览。输出是每个剪辑/≤15 秒镜头笔记的一个合成图像，而不是每个面板一个图像。

• 工具/调用：每个拼贴使用一个 generate_image_pro.js --size 2560x1440 --subtype storyboard --label "Storyboard — Shot <N>" --source-node-id <shot_note_id>。
• 尺寸：默认 2560x1440；网格形状是单元格布局，而不是画布形状。仅为显式的肖像/方形/竖版/比例覆盖：
  • “2x2 故事板” → 2560x1440（默认）
  • “2x2 方形故事板” → 1920x1920
  • “2x2 竖版故事板” → 1440x2560
  • “竖版 2x4 拼贴” → 1440x2560
• 网格/引用：默认 2×2。传递相关的角色/位置引用（≤32）。在 3×3+ 之前发出警告；推荐更小的角色表。

关于画布预检、每个镜头笔记的迭代逻辑、缺失锚点提示、逐字提示词模板以及当没有脚本片段时的默认面板覆盖：请参见 references/storyboard-mosaic.md。

CLI 设置的节点字段

• 每个拼贴一个 image_result 节点。
• 通过传递 --subtype storyboard 设置 data.subtype = "storyboard"。

7. 角色参考表 （任何绑定视频的角色工作的默认方式——有或没有演员参考）

对任何将出现在下游视频中的角色主动使用，无论是否有演员参考。

模式 A — ≥3 个上传的演员参考。 将照片作为 --ref-source-id 传递；如果脚本/镜头创作了设计，则添加 --source-node-id <note_id>。

模式 B — 0-2 个参考 / 从头开始。 省略演员参考；显式描述年龄/身材/服装/显著特征。当由笔记创作时，添加 --source-node-id <note_id>。

也响应显式请求：“为 [角色] 设计角色表 / 旋转视图表 / 参考表 / 角色设计”、“制作一个四格角色设计”、“为下游视频工作生成一个制作参考表”。

输出：一个 正面全身/背面全身/正面半身 / 特写半身 角色表，直接作为 --ref-source-id 传递给视频。

• 预检：确定上传的参考节点（subtype:"reference"，理想情况下 ≥3 张照片）。在一行中确认参考数量。
• node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 --subtype character --name "<character_name>" --role "..." --ref-source-id <ref1> --ref-source-id <ref2> --ref-source-id <ref3> [--source-node-id <script_or_shot_note_id>] — Pro 层级是角色表的默认选项，因为面板布局、文字抑制和身份一致性是承重的。不要传递 --aspect-ratio 或 --image-size。永远不要在少于 3 个参考的情况下触发模式 A（模型会过拟合于它拥有的单一角度）。
• 有 0-2 个演员参考时，使用 references/character-sheet.md 中的模式 B 纯文本命令：相同的 pro 命令，但省略所有演员照片 --ref-source-id；仅当脚本或镜头笔记创作了设计时才包含 --source-node-id。
• 每个基础角色或材料变体一个调用/角色表。在变体之前生成基础版本。对于保持身份的变体，传递基础角色表作为引用，并仅描述持久的服装/状态变化。
• 使用角色表作为下游镜头的 --ref-source-id <sheet_id>；无需常规裁剪。

关于逐字四格提示词模板、可选的每个角度裁剪和注意事项（无文字规则、照片优先级、精确面板计数）：请参见 references/character-sheet.md。

CLI 设置的节点字段

• 一个带有 data.subtype = "character" 的 image_result 节点。
• data.name、data.role、data.description 来自 CLI 标志。
• 每个 --ref-source-id 一条 derived 边（因此角色表与它三角测量出的每个演员照片都有来源链接）。

CLI 返回后

对于草稿阶段的 JSON，用一句说明价格/状态——参见项目 PROJECT_AGENT.md 中的“草稿门控”部分。对于最终结果，请遵循项目手册的下一步推荐规则。