Document Illustrator Skill

基於 AI 智能分析的文檔配圖生成工具。無需依賴特定格式，自動理解內容並生成專業配圖。

🎯 核心特點

✨ AI 智能歸納：自動理解文檔內容，智能提取核心主題
🎨 格式無關：支援任何格式的文檔（Markdown、純文字、PDF 等）
📐 靈活比例：支援 16:9（橫屏）和 3:4（豎屏）
🖼️ 封面圖可選：可生成概括全文的封面圖
🎭 三種風格：漸層玻璃卡片、票據風格、向量插畫

🚀 使用方法

直接告訴 Codex

幫我為這個文檔生成配圖：/path/to/document.md

或者：

我想為這篇文章生成一些配圖

📝 完整工作流程

第 1 步：Codex 讀取和理解文檔

當你請求生成配圖時，Codex 會：

使用 Read 工具讀取完整文檔
AI 分析理解文檔內容和結構
識別核心主題和要點

無需擔心文檔格式：

✅ 標準 Markdown（##、###）
✅ 分隔線格式（======、------）
✅ 純文字段落
✅ 任何其他格式

第 2 步：配置選項（3 個問題）

Codex 會詢問你的偏好：

問題 1：圖片比例

請選擇圖片比例：
1. 16:9 (橫屏) - 適合簡報、投影片、橫屏展示
2. 3:4 (豎屏) - 適合社交媒體、手機查看、海報

請選擇 (1/2):

問題 2：封面圖

是否生成封面圖？
封面圖將概括文檔的所有核心資訊，作為系列配圖的引導。

1. 是 - 生成封面圖 + 內容配圖
2. 否 - 僅生成內容配圖

請選擇 (1/2):

問題 3：內容配圖數量

期望生成多少張內容配圖？
建議範圍：3-10 張
根據文檔內容，推薦生成 6 張

請輸入數字：

第 3 步：Codex 歸納內容並展示

根據你指定的數量，Codex 會智能歸納文檔，然後展示給你確認：

📋 內容歸納完成

📄 封面圖內容：（如果選擇生成）
"AI 程式工具概念演化：從 Rules 到 Skills"
- 核心概念：靜態上下文 vs 動態上下文
- 演化路徑：Rules → Commands → MCP → Modes → Skills
- 最佳實踐：簡化為兩個核心工具

📚 內容配圖（共 6 張）：

1. Rules 的誕生與演化
   包含：早期模型幻覺問題、rules 檔案的作用、靜態上下文概念

2. Commands 和工作流打包
   包含：固定工作流的出現、slash command、團隊分享

3. MCP Servers 帶來動態能力
   包含：第三方工具整合、OAuth 認證、上下文膨脹問題

4. Modes 和 Subagents 的登場
   包含：人設提示詞、系統提示詞修改、可靠性設計、Hooks 確定性

5. Skills 統一動態上下文
   包含：Skills 概念、動態載入、程式工具最佳化

6. 最佳實踐與未來展望
   包含：Rules 使用建議、Skills 探索、核心理念總結

✓ 所有內容已覆蓋，無遺漏

確認開始生成配圖嗎？(Y/N)

關鍵保證：

✅ 內容完整：所有重要資訊都會被歸入某張圖片
✅ 邏輯清晰：按照內容的自然邏輯分段
✅ 用戶可控：展示歸納結果，等待用戶確認

第 4 步：生成配圖

確認後，Codex 呼叫 Python 腳本生成圖片：

🖼️  開始生成配圖...

正在生成封面圖...
  ✓ 已儲存: /path/to/document/images/cover.png

正在生成第 1/6 張...
  標題: Rules 的誕生與演化
  ✓ 已儲存: /path/to/document/images/illustration-01.png

正在生成第 2/6 張...
  標題: Commands 和工作流打包
  ✓ 已儲存: /path/to/document/images/illustration-02.png

...

✨ 完成！共生成 7 張配圖（1 張封面 + 6 張內容）

第 5 步：輸出結果

輸出位置：文檔所在目錄下的 images/ 資料夾

/path/to/your/document/
└── images/
    ├── cover.png              # 封面圖（如果選擇生成）
    ├── illustration-01.png    # 第 1 張內容配圖
    ├── illustration-02.png    # 第 2 張內容配圖
    ├── illustration-03.png
    ├── illustration-04.png
    ├── illustration-05.png
    └── illustration-06.png

🎨 三種風格說明

1. 漸層玻璃卡片風格 (gradient-glass)

特點：

Apple Keynote 風格的極簡主義
玻璃擬態（Glassmorphism）設計
深邃虛空黑或純淨陶瓷白基底
流動的極光漸層色
3D 玻璃物體和發光效果

適用場景：

科技產品介紹
數據分析報告
未來趨勢展望
產品功能示範

2. 票據風格 (ticket)

特點：

數字極簡票券設計
高度對比的黑白配色
類似登機牌、門票的結構
精確的幾何分區
中英混排，多向文字佈局

適用場景：

資訊圖表
統計數據展示
時間線和流程圖
要點總結

3. 向量插畫風格 (vector-illustration)

特點：

扁平化向量插畫
統一粗細的黑色輪廓線
復古柔和的配色
幾何化處理
橫向全景式構圖

適用場景：

故事敘述
概念解釋
教育內容
品牌宣傳

💡 使用範例

範例 1：完整流程

使用者: 幫我為 ~/blog/ai-tools.md 生成配圖，用票據風格

Codex: 好的，讓我先讀取這個文件...
        [讀取文件，分析內容]

        偵測到文檔長度約 3000 字，內容涉及 AI 工具演化。

        請選擇圖片比例：
        1. 16:9 (橫屏)
        2. 3:4 (豎屏)

使用者: 1

Codex: 是否生成封面圖？
        1. 是
        2. 否

使用者: 是

Codex: 期望生成多少張內容配圖？
        建議範圍：3-10 張
        根據文檔內容，推薦生成 5 張

使用者: 5

Codex: [展示歸納的 5 個主題]
        確認開始生成配圖嗎？

使用者: Y

Codex: [呼叫 Python 腳本生成 6 張圖片]
        ✨ 完成！配圖已儲存到 ~/blog/images/

範例 2：純文字文檔

使用者: 為這個純文字筆記生成配圖

Codex: [讀取筆記，即使沒有任何標題也能理解內容]
        [智能識別 3 個核心主題]
        [詢問配置、展示歸納、生成配圖]

範例 3：自訂數量

使用者: 我想要 8 張圖，豎屏的，不要封面

Codex: 好的，16:9 豎屏，不生成封面，8 張內容配圖。
        [將文檔歸納為 8 個主題]
        [展示歸納結果，使用者確認後生成]

🔧 技術細節

圖片規格

以下比例和解析度適用於 Gemini；Nebula image2-4k 僅支援 16:9、3840x2160。使用者選擇 Nebula 時，直接使用 4K；如使用者要求 2K 或豎圖，先說明限制並確定受支援方案。

比例	解析度	適用場景
16:9	2560x1440 (2K)	簡報、橫屏展示
3:4	1920x2560	社交媒體、垂直瀏覽

可選 4K 解析度：

16:9 → 3840x2160
3:4 → 2880x3840

API 呼叫

Gemini 模型：gemini-3-pro-image-preview（腳本當前預設值）
Nebula 模型：gpt-image-2-4k，使用 image2-4k 分組令牌
成本：每張圖片 = 1 次 API 呼叫
速度：取決於後端負載；Nebula 4K 請求超時為 1800 秒

後端選擇與 Nebula 呼叫

nanobanana 分組

使用者指定 nanobanana 時，兩個腳本均傳入 --provider nanobanana。統一 .env 中使用專用 NEBULA_NANOBANANA_API_KEY（nanobanana 分組令牌），不復用 image2-4k 的密鑰。NEBULA_NANOBANANA_MODEL 預設為 gemini-3.1-flash-image，可指定令牌支援的其他模型；ILLUSTRATOR_IMAGE_PROVIDER=nanobanana 可設為預設。單圖、批量均支援 16:9、3:4；可請求 1K、2K、4K，預設 2K，具體支援值及實際像素由所選模型決定，不套用 image2-4k 的 4K 橫圖限制。

統一 .env 使用 ILLUSTRATOR_SINGLE_RATIO 設定單圖預設比例， ILLUSTRATOR_BATCH_RATIO 設定批量預設比例，ILLUSTRATOR_RESOLUTION 設定預設請求解析度。兩個入口均支援 --ratio、--resolution 覆蓋配置。不配置或值為空時，比例為 16:9，解析度使用後端預設值（Gemini/nanobanana 為 2K，image2-4k 為 4K）。這些設定適用於所有後端；與後端限制衝突時，請求前報錯，須調整配置或明確覆蓋。

python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "主題" --content "配圖內容" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py article.md --provider nanobanana --style ticket --level h2 --resolution 2K

呼叫 Gemini 原生 POST /v1beta/models/{model}:generateContent，從 inlineData 解碼並驗證圖片，不持久化完整 Base64 回應。不需要 Google SDK。當前接入僅支援文字生圖；超時後不自動重發收費任務。詳見 README.md 和官方介面說明。

原有 image2-4k 分組

兩個腳本支援 --provider gemini|nebula。不指定時讀取 ILLUSTRATOR_IMAGE_PROVIDER，未配置時使用 Gemini。使用者明確指定 Nebula 時，傳入 --provider nebula；不要改用其他服務。在統一路徑 ~/.agents/skills/document-illustrator/.env 配置 NEBULA_API_KEY，或使用同名環境變數；令牌須屬於 image2-4k 分組。 Nebula 無需 Gemini 密鑰或 Google SDK，仍需要 Pillow 和 python-dotenv。

python -X utf8 scripts/generate_single_image.py --provider nebula --title "主題" --content "已確認的配圖內容" --style-file styles/ticket.md --output output/image-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py article.md --provider nebula --style ticket --level h2 --resolution 4K

腳本呼叫 POST https://img-api.apinebula.ai/v1/images/generations，固定使用 gpt-image-2-4k、3840x2160、quality=high、response_format=url。優先讀取 URL，相容 Base64；儲存前驗證真實像素，將服務端 JPEG 轉為本地副檔名對應的格式。介面回應儲存為 <圖片檔案名>.response.json，下載失敗時先復用其中的暫存連結恢復下載。 POST 超時後任務狀態可能未知，不自動重發；先確認服務端狀態，避免重複計費。 HTTP 403 或連線尚未建立時會嘗試 http://127.0.0.1:81 代理。當前僅接入文字生圖；參考圖編輯未實作。

完整配置說明與離線測試命令見 README.md，介面參數以官方文件為依據。

環境需求

必需：

pip install google-genai pillow python-dotenv

API 密鑰：

Codex、Claude 等所有 Agent 統一讀取 ~/.agents/skills/document-illustrator/.env
Windows 對應 %USERPROFILE%\.agents\skills\document-illustrator\.env
僅載入該檔案，其值覆蓋同名環境變數；檔案不存在時僅使用現有環境變數，不搜尋其他位置
Gemini 使用 GEMINI_API_KEY，Nebula 使用 NEBULA_API_KEY
nanobanana 分組使用 NEBULA_NANOBANANA_API_KEY；模型配置見上方分組說明

📊 內容歸納原則

Claude 歸納內容時遵循以下原則：

1. 完整性優先

✅ 所有重要資訊都會被包含
✅ 不會遺漏關鍵概念
✅ 保留原文的核心觀點

2. 邏輯清晰

按照內容的自然邏輯分段
相關內容歸為一組
保持敘述的連貫性

3. 平衡分配

每張圖片包含相似的資訊量
避免某張過於擁擠或空洞
根據內容重要性調整

4. 用戶可控

展示歸納結果給用戶確認
用戶可以要求調整
確認後才開始生成

🐛 故障排除

問題 1：API 密鑰錯誤

錯誤資訊：

Error: Invalid API key

解決方案：

檢查 .env 中對應後端的 GEMINI_API_KEY 或 NEBULA_API_KEY；Nebula 同時檢查令牌分組
確保 API 密鑰有效且未過期
獲取新密鑰：https://makersuite.google.com/app/apikey

問題 2：內容歸納不理想

問題：歸納的主題不符合預期

解決方案：

在歸納展示階段，告訴 Codex 你的期望
Codex 會重新歸納並調整
確認滿意後再開始生成

問題 3：圖片生成失敗

可能原因：

網路連線問題
API 配額用盡
內容過長超過限制

解決方案：

檢查網路連線
檢查 API 配額
嘗試增加圖片數量（分散內容）

💰 成本估算

圖片數量	API 呼叫次數	預估成本
無封面 + 3 張	3 次	低
有封面 + 5 張	6 次	中
有封面 + 10 張	11 次	較高

建議：

短文檔（<1000字）：3-5 張
中等文檔（1000-3000字）：5-7 張
長文檔（>3000字）：8-10 張

📚 最佳實踐

1. 合理選擇圖片數量

太少：

每張圖片資訊量過大
不容易理解和記憶

太多：

內容分散
增加成本和生成時間

2. 根據用途選擇比例

16:9 適合：

PPT 演示
網站橫幅
影片封面
部落格配圖（桌面端）

3:4 適合：

社交媒體（Instagram、小紅書）
行動端文章
海報設計
垂直影片

3. 封面圖的使用

建議生成封面圖的場景：

系列文章（作為統一引導）
社交分享（作為預覽圖）
文檔首頁（概括全文）

可以不生成的場景：

僅內部使用
圖片數量已足夠
希望降低成本

4. 風格選擇建議

技術文檔 → 漸層玻璃卡片風格 數據報告 → 票據風格 教程故事 → 向量插畫風格 產品介紹 → 漸層玻璃卡片風格

🔄 工作原理

傳統方式（已廢棄）

[程式碼] 讀取文檔 → 識別 ## ### 標題 → 機械切分
       ↓
    依賴特定格式
    容易遺漏內容
    不夠智能

新方式（當前實現）

[Claude] 讀取文檔 → AI 理解內容 → 智能歸納主題
         ↓
      格式無關
      內容完整
      用戶可控

核心區別：

❌ 舊方式：依賴程式碼解析，只能處理標準格式
✅ 新方式：AI 理解內容，任何格式都能處理

🎯 與其他工具的對比

功能	Document Illustrator	傳統 PPT 工具	AI 圖片生成器
理解文檔內容	✅ AI 智能理解	❌ 需要手動	❌ 需要手動輸入
格式依賴	✅ 格式無關	❌ 依賴特定格式	✅ 無依賴
內容完整性	✅ 自動驗證	⚠️ 手動確保	❌ 無法保證
批量生成	✅ 一次生成多張	❌ 逐張製作	⚠️ 需要多次輸入
風格一致性	✅ 自動保持	⚠️ 手動調整	⚠️ 需要重複提示詞

📞 獲取幫助

如有問題或建議：

直接在 Codex 中詢問
檢查 Skill 目錄：~/.agents/skills/document-illustrator

讓 AI 幫你理解和歸納內容，生成專業配圖！ ✨

在你喜歡的 AI 中提問

說明文件

Document Illustrator Skill

🎯 核心特點

🚀 使用方法

直接告訴 Codex

📝 完整工作流程

第 1 步：Codex 讀取和理解文檔

第 2 步：配置選項（3 個問題）

問題 1：圖片比例

問題 2：封面圖

問題 3：內容配圖數量

第 3 步：Codex 歸納內容並展示

第 4 步：生成配圖

第 5 步：輸出結果

🎨 三種風格說明

1. 漸層玻璃卡片風格 (gradient-glass)

2. 票據風格 (ticket)

3. 向量插畫風格 (vector-illustration)

💡 使用範例

範例 1：完整流程

範例 2：純文字文檔

範例 3：自訂數量

🔧 技術細節

圖片規格

API 呼叫

後端選擇與 Nebula 呼叫

nanobanana 分組

原有 image2-4k 分組

環境需求

📊 內容歸納原則

1. 完整性優先

2. 邏輯清晰

3. 平衡分配

4. 用戶可控

🐛 故障排除

問題 1：API 密鑰錯誤

問題 2：內容歸納不理想

問題 3：圖片生成失敗

💰 成本估算

📚 最佳實踐

1. 合理選擇圖片數量

2. 根據用途選擇比例

3. 封面圖的使用

4. 風格選擇建議

🔄 工作原理

傳統方式（已廢棄）

新方式（當前實現）

🎯 與其他工具的對比

📞 獲取幫助

相關技能

steipete/songsee

affaan-m/frontend-design

mattpocock/improve-codebase-architecture

lobehub/add-provider-doc

addyosmani/browser-testing-with-devtools

bytedance/chart-visualization