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> ...]

專業層級（適用於分鏡方格和影片角色資料表）：

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> ...]

專業層級僅接受 --size；不支援 --aspect-ratio / --image-size。常用尺寸：1024x1024、1280x720、720x1280、1920x1920、2560x1440、1440x2560、3840x2160、2160x3840。

--label 若省略則預設為截斷的提示詞（≤30 字元）；當你有更好的標題時請明確傳入。

在 --ref-source-id 順序中使用 @Image1、@Image2、……。CLI 會為每個 ref 產生一條 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 -> 專業層級精確 2K；Max quality -> 專業層級精確 4K。

模式

選擇適合的模式。關於來源查詢，請遵循專案 PROJECT_AGENT.md §「選擇上下文」；此技能僅掌管影像特定的提示詞和 CLI 形狀。

角色預檢。 首先詢問：此角色是否會出現在下游影片中（video、clip、promo、宣傳片、短片、連續劇、film、scene、拍片、shot、short film）？

1. 讀取 workflow.json 以取得已上傳的 ref（subtype:"reference"、metadata.source:"user_upload"、未封存）。
2. 影片相關 -> 模式 7，非模式 1。有可用時使用 ≥3 個演員 ref；0-2 個 ref 時，生成純文字四面板資料表。
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 "..." — 無 ref。角色是身分錨點，而非衍生品。
• 提示模板：

  [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>] — 無 ref。地點是設定錨點，而非衍生品。
• 提示模板：

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

• 保持畫面中無角色。必要時包含建築/佈局、表面、佈置、時代、天氣、時間、光線和故事狀態。
• 同一地點變體保留地點身分，同時改變廣角/近距離比例、白天/夜晚、天氣、佈置、損壞或細節覆蓋。
• 預設無 ref 邊。如果地點衍生自腳本或鏡頭筆記，使用 --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.

  ✅ "Change the rain to falling snow. Keep the detective, wardrobe, and camera framing unchanged." ✅ "Render as a full 3D turnaround sheet of the same character. Preserve face, wardrobe, and proportions." ❌ "A detective in a snowy alley at night wearing a trench coat…" — 過度指定，身分漂移。

• 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，除非使用者另有要求）。無 subtype，無 ref。

6. 分鏡方格 — 每個片段 / 鏡頭筆記一個複合圖

觸發條件：分鏡腳本、蒙太奇、網格、鏡頭列表、覆蓋範圍、關鍵影格表、鏡頭規劃、影像預覽。輸出是每個片段/≤15 秒鏡頭筆記一個複合圖，而不是每個面板一個影像。

• 工具/呼叫：每個蒙太奇一次 generate_image_pro.js --size 2560x1440 --subtype storyboard --label "Storyboard — Shot <N>" --source-node-id <shot_note_id>。
• 尺寸：預設 2560x1440；網格形狀是單元格佈局，而非畫布形狀。僅在明確指定肖像/方形/垂直/比例時覆蓋：
  • "2x2 storyboard" → 2560x1440（預設）
  • "2x2 square storyboard" → 1920x1920
  • "2x2 portrait storyboard" → 1440x2560
  • "vertical 2x4 mosaic" → 1440x2560
• 網格/ref：預設 2×2。傳入相關角色/地點 ref（≤32）。在 3×3+ 之前發出警告；推薦較小的資料表。

關於畫布預檢、逐鏡頭筆記迭代邏輯、缺少錨點的提示、逐字提示模板，以及沒有腳本切片時的預設面板覆蓋：請參閱 references/storyboard-mosaic.md。

CLI 設定的節點欄位

• 每個蒙太奇一個 image_result 節點。
• 透過傳遞 --subtype storyboard 設定 data.subtype = "storyboard"。

7. 角色參考資料表 （任何影片相關角色工作的預設 — 不論是否有演員 ref）

對任何將出現在下游影片中的角色主動使用，不論是否有演員 ref。

模式 A — ≥3 個上傳的演員 ref。 將照片作為 --ref-source-id 傳入；如果腳本/鏡頭創作了設計，則添加 --source-node-id <note_id>。

模式 B — 0-2 個 ref / 從頭開始。 省略演員 ref；明確描述年齡/體型/衣櫃/區別特徵。當由筆記創作時添加 --source-node-id <note_id>。

在明確要求時也會觸發：「設計角色資料表 / 多角度生成 / 參考資料表 / 角色設計 for [character]」、「製作一個 4 面板角色設計」、「為下游影片工作生成一個製作參考資料表」。

輸出：一個 正面全身 / 側面全身 / 背面全身 / 特寫半身 資料表，直接作為 --ref-source-id 傳遞給影片。

• 預檢：識別上傳的參考節點（subtype:"reference"，理想上 ≥3 張照片）。在一行中確認 ref 計數。
• 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>] — 專業層級是角色資料表的預設，因為面板佈局、文字抑制和身分一致性是關鍵負載。不要傳遞 --aspect-ratio 或 --image-size。永遠不要使用少於 3 個 ref 觸發模式 A（模型會過度擬合到它僅有的單一角度）。
• 使用 0-2 個演員 ref 時，使用 references/character-sheet.md 中的模式 B 純文字命令：相同的專業命令，但省略所有演員照片的 --ref-source-id；僅在腳本或鏡頭筆記創作設計時包含 --source-node-id。
• 每個基礎角色或素材變體一個呼叫/資料表。在變體之前生成基礎。對於保持身分的變體，將基礎資料表作為 ref 傳入，僅描述持續的衣櫃/狀態變化。
• 將資料表作為 --ref-source-id <sheet_id> 用於下游鏡頭；無需正常裁切。

關於逐字 4 面板提示模板、可選的每個角度裁切和注意事項（無文字規則、照片優先、精確面板數量）：請參閱 references/character-sheet.md。

CLI 設定的節點欄位

• 一個具有 data.subtype = "character" 的 image_result 節點。
• 來自 CLI 旗標的 data.name、data.role、data.description。
• 每個 --ref-source-id 一條 derived 邊（以便資料表與其三角測量自的每張演員照片進行來源連結）。

CLI 回傳後

對於草稿階段的 JSON，一句話包含價格/狀態——請參閱專案 PROJECT_AGENT.md §「草稿閘門」。對於最終結果，請遵循專案手冊的下一步推薦規則。