baoyu-article-illustrator

Article Illustrator

分析文章、識別插圖位置，並以「類型 × 風格 × 調色盤」的一致性生成圖片。

User Input Tools

當此 Skill 需要向使用者提問時，請遵循以下工具選擇規則（按優先順序）：

1. 優先使用內建的使用者輸入工具：即當前 Agent 執行階段（runtime）所暴露的工具 — 例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同等工具。
2. 後備方案（Fallback）：若無此類工具，請發送帶有編號的純文字訊息，並要求使用者針對每個問題回覆對應的編號/答案。
3. 批次處理（Batching）：若工具支援單次呼叫提出多個問題，請將所有適用問題合併為單次呼叫；若僅支援單一問題，請按優先順序一次詢問一個。

下方具體的 AskUserQuestion 參照僅為範例 — 在其他執行階段中請替換為當地的同等工具。

Image Generation Tools

當此 Skill 需要繪製圖片時，請按以下順序解析圖片生成後端：

1. 當前請求覆蓋（Current-request override） — 若使用者在當前訊息中指定了特定後端，直接使用該後端。
2. 已儲存的偏好設定（Saved preference） — 若 EXTEND.md 將 preferred_image_backend 設定為當前可用的後端，使用該後端。
3. 自動選擇（Auto-select）（當偏好設定為 auto、未設定，或指定的偏好後端不可用時）：
   • Codex (imagegen) — 首先檢查你可用的 Skill / 工具清單。如果列出了名為 imagegen 的 Skill，說明你正在 Codex 環境中執行，必須使用它：透過 Skill 工具呼叫並傳入 skill: "imagegen"，傳遞已儲存的 prompt 檔案內容（以及依據 Codex imagegen 自身參數要求的輸出路徑與長寬比）。Codex imagegen 是該執行階段官方的點陣圖後端，除非使用者明確指定了不同的 preferred_image_backend，否則其優先級高於任何非原生 Skill（例如 baoyu-image-gen）。
   • 透過 codex exec 的 Codex (codex-imagegen) — 若當前執行階段未暴露原生的 imagegen Skill，但 PATH 中有 codex CLI 且已完成 codex login 登入，請優先透過 baoyu-image-gen --provider codex-cli 路由；若 baoyu-image-gen 不可用，則直接呼叫隨附的封裝指令碼。詳細資訊、參數以及執行階段偵測流程請參閱 references/codex-imagegen.md — 僅在選擇此分支時才載入該檔案。
   • Cursor (GenerateImage) — 若執行階段暴露了原生的 GenerateImage 工具，說明你正在 Cursor 環境中執行，它與 Codex imagegen 一樣優先於任何非原生 Skill。注意兩個硬性限制：(a) 它沒有長寬比參數 — 必須在傳給 description 的 prompt 文字中明確寫出目標長寬比 / 尺寸；(b) 它不接受輸出目錄 — 會儲存至工具管理的預設位置，因此生成後需將檔案複製/移動至 Skill 預期的輸出路徑（例如 outputs/.../NN-xxx.png）。參考圖片置於 reference_image_paths。
   • 其他執行階段原生工具 — 若執行階段暴露了其他原生圖片工具（例如 Hermes image_generate），請以相同方式使用。
   • 否則，若僅安裝了一個非原生後端（例如 baoyu-image-gen），直接使用它。
   • 否則（安裝了多個非原生後端且無原生圖片工具），詢問使用者一次 — 與其他初始問題一併批次詢問。
4. 若無任何可用後端，告知使用者並詢問如何繼續。

⛔ 絕不要用 SVG、HTML、canvas 或其他基於程式碼的算圖方式替代點陣圖生成。 Codex imagegen 自身的說明指出，它應該用於「輸出目標為位圖/點陣圖資產而非專案原生程式碼或向量圖」的場景。若無法透過步驟 3 解析出點陣圖後端，請降級至步驟 4 詢問使用者 — 切勿默默輸出 SVG、撰寫內聯 <svg> 標記或生成 HTML/CSS 藝術作為替代品。即便文章/章節看起來像「圖表/流程圖」，呼叫此規則的消費端 Skill 已經決定了它需要的是點陣圖。

⛔ 絕不要透過在生成的點陣圖上覆蓋繪製來修復算出的文字。 切勿使用 ImageMagick、Pillow、Canvas、SVG、HTML/CSS、OCR 指令碼或任何其他程式化覆蓋層來覆蓋、重寫、擦除、加邊框或替換已生成插圖中的標籤、圖說或任何文字。如果文字錯誤或不清晰，請使用修正後的 prompt 重新生成、重繪為較少或無文字的圖片，或者詢問使用者保留哪一個不完美的候選圖。

將 preferred_image_backend: ask 設定為 ask 會強制每次執行都觸發步驟 3 的詢問，無論當前有哪些可用後端。使用者可透過下方 ## Changing Preferences 章節修改預設後端。

Prompt 檔案硬性要求（Hard requirement）：在呼叫任何後端之前，必須將每張圖片的完整、最終 prompt 寫入 prompts/ 下的獨立檔案中（命名格式：NN-{type}-[slug].md）。後端接收 prompt 檔案（或其內容）；該檔案是可複現性記錄，並且允許你在不重新生成 prompt 的情況下切換後端。

上述具體的工具名稱（imagegen、GenerateImage、image_generate、baoyu-image-gen）皆為範例 — 在相同規則下請替換為當地的同等工具。

Batch Generation Policy

當本次執行的所有 prompt 檔案都已儲存並確認無誤後，預設採用批次生成圖片。

優先順序：

1. 優先使用所選後端的原生批次 / 多任務介面（若存在）。每個任務必須保留其獨立的 prompt 檔案、輸出路徑、長寬比及直接參考圖片。
2. 若不存在原生批次介面，但執行階段可發起平行工具呼叫，則每次最多分發 generation_batch_size 張圖片。預設值：4。使用者在當前訊息中的明確要求（例如 --batch-size 4 或「平行4張一起生成」）會覆蓋 EXTEND.md。
3. 若原生批次和平行工具呼叫皆不可用，則按順序串列生成。

規則：

• 在該批次的所有 prompt 檔案儲存至磁碟之前，絕不開始執行第一批生成。
• 對失敗項目重試一次，且不重新生成已成功的項目。
• 切勿僅為了平行化圖片繪製而使用 Subagent。僅在需要獨立的 prompt 疊代或創意探索時才使用 Subagent。

Confirmation Policy

預設行為：生成前確認。

• 將明確的 Skill 呼叫、檔案路徑、匹配的訊號/預設集以及 EXTEND.md 預設值僅視為建議輸入。它們都不代表授權跳過確認。
• 在使用者完成步驟 3 之前，切勿開始步驟 4 或後續步驟。
• 僅在當前請求明確要求跳過時才跳過確認，例如：「直接生成」、「不用確認」、「跳過確認」、「按預設出圖」或類似表述。
• 如果明確跳過了確認，請在生成前的下一次面向使用者的更新中，說明所採用的類型 / 密度 / 風格 / 調色盤 / 語言 / 後端。

Reference Images

使用者可透過 --ref <files...>、提供檔案路徑或在對話中貼上圖片來提供參考圖片。參考圖可用於引導特定插圖的風格、調色盤、構圖或主體。

完整的偵測、儲存與處理規則請參閱 references/workflow.md（步驟 1.0 儲存至 references/NN-ref-{slug}.{ext}；步驟 5.3 按每張插圖處理 direct | style | palette 的用途）。當所選後端支援批次輸入時，每個 prompt 檔案的 references: frontmatter 中標註為 direct 用途的條目應傳播至其批次載荷（payload）中，以便後端透傳（例如 baoyu-image-gen 支援每個任務傳入 ref）。

Three Dimensions

維度	控制內容	範例
Type（類型）	資訊結構	infographic, scene, flowchart, comparison, framework, timeline
Style（風格）	呈現方式	notion, warm, minimal, blueprint, watercolor, elegant
Palette（調色盤）	色彩方案（可選）	macaron, warm, neon — 會覆蓋風格的預設色彩

可自由組合：--type infographic --style vector-illustration --palette macaron

或使用預設集：--preset edu-visual → 將類型 + 風格 + 調色盤整合於單一標籤中。詳見 Style Presets。

Types

類型	最適合用於
infographic	數據、指標、技術內容
scene	敘事、具情感色彩內容
flowchart	流程、工作流
comparison	橫向對比、選項比較
framework	模型、架構圖
timeline	歷史演進、時間軸

Styles

核心風格、完整圖庫及「類型 × 風格」相容性請參閱 references/styles.md。

Workflow

- [ ] 步驟 1：事前檢查（EXTEND.md、參考資料、配置）
- [ ] 步驟 2：分析內容
- [ ] 步驟 3：確認設定（AskUserQuestion）
- [ ] 步驟 4：生成大綱
- [ ] 步驟 5：生成圖片
- [ ] 步驟 6：完成與收尾

Step 1: Pre-check

1.5 載入偏好設定 (EXTEND.md) ⛔ 阻斷性條件

按優先順序檢查 EXTEND.md — 以找到的第一個為準：

優先順序	路徑	作用域
1	.baoyu-skills/baoyu-article-illustrator/EXTEND.md	專案（Project）
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md	使用者家目錄（User home）

結果	採取的動作
已找到	讀取、解析、顯示摘要
未找到	⛔ 執行 first-time-setup

完整流程：references/workflow.md

Step 2: Analyze

分析維度	輸出
內容類型	Technical / Tutorial / Methodology / Narrative
目的	information / visualization / imagination
核心論點	2-5 個主要要點
配圖位置	插圖能帶來增值效果之處

關鍵要點：暗喻/比喻 → 視覺化其底層概念，而非繪製字面意思的具象畫面。

完整流程：references/workflow.md

Step 3: Confirm Settings ⚠️

硬性門檻：依據 Confirmation Policy，本步驟為強制執行 — 在使用者於此處確認（或在當前請求中明確以「直接生成」/ 同等表述跳過）之前，無法開始步驟 4 及後續步驟。

呼叫一次 AskUserQuestion，最多 4 個問題。問題 1-2 為必填。問題 3 為必填（除非已選擇預設集）。

問題	選項
Q1: 預設集或類型	[推薦預設集], [備選預設集], 或手動選擇: infographic, scene, flowchart, comparison, framework, timeline, mixed
Q2: 插圖密度	minimal (1-2張), balanced (3-5張), per-section (推薦), rich (6張以上)
Q3: 風格	[推薦風格], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster, Other — 若已選擇預設集則跳過
Q4: 調色盤	Default (風格預設色彩), macaron, warm, neon — 若預設集已包含調色盤或已設定 preferred_palette 則跳過
Q5: 語言	當文章語言 ≠ EXTEND.md 設定時

完整流程：references/workflow.md

Step 4: Generate Outline

儲存帶有 frontmatter（type, density, style, palette, image_count）及各個條目的 outline.md：

## Illustration 1
**Position**: [章節/段落]
**Purpose**: [為何需要]
**Visual Content**: [畫面內容]
**Filename**: 01-infographic-concept-name.png

完整範本：references/workflow.md

Step 5: Generate Images

⛔ 阻斷性條件：在開始生成任何圖片之前，必須先儲存 Prompt 檔案。 無論選擇哪個後端，這都是硬性要求 — prompt 檔案是可複現性的記錄。

1. 針對每張插圖，依據 references/prompt-construction.md 建立 prompt 檔案
2. 帶有 YAML frontmatter 儲存至 prompts/NN-{type}-{slug}.md
3. Prompt 必須使用特定類型的範本 with st