joeseesun/qiaomu-icon-generator

Qiaomu Icon Generator

使用本機 QM Icon Studio CLI 或 Codex 內建生圖能力，為網站、App、工具或 Skill 生成多套圖示候選，並給使用者一張選擇稿。

Copyright (c) 向陽喬木 X: https://x.com/vista8 GitHub: https://github.com/joeseesun/

使用時機

• 新網站、App、Chrome 擴充功能、Skill、CLI 工具需要 favicon、app icon 或品牌入口圖示。
• 使用者想先看多個方向再選，而不是直接替換生產圖示。
• 專案還沒有完整品牌系統，但已有名稱、網域、用途或一句話描述。

方法選擇

當使用者想要基於 Iconify 風格的符號、確定性且向量友善的圖示，或需要快速乾淨的 SVG 候選時，使用 QM Icon Studio CLI 方法。

當使用者明確要求使用 Codex 內建圖片生成、需要更豐富的 iOS 風格應用程式圖示、要求參考現有圖示庫，或需要經過打磨的點陣圖方向來進行最終匯出時，使用 Codex 點陣參考方法。

工作流程：QM Icon Studio CLI

使用此路徑前，請先閱讀 references/qm-icon-studio-cli-method.md。

1. 讀取專案上下文：README.md、package.json、站點網域、已有 public/ 或 assets/ 圖示、主色 CSS 變數。
2. 提煉一個簡短英文語義關鍵詞，例如 rocket、globe、code、book、camera、music、money。中文需求可以直接傳給 CLI；CLI 會先翻譯再搜尋 Iconify，必要時你也可以手動改成更準確的英文詞。
3. 在專案內建立候選目錄，預設使用 design/icon-options/；如果專案已有設計目錄，沿用現有結構。
4. 如果目前機器有 QM Icon Studio CLI，呼叫：

node "$HOME/Documents/qm-icon-studio/cli/qm-icon-options.mjs" \
  --name "Product Name" \
  --query "rocket" \
  --count 8 \
  --out design/icon-options \
  --png

如果這個本機路徑不存在，使用 Codex 點陣參考方法，或讓使用者提供自己的圖示生成 CLI / 圖示參考庫路徑。

5. 把 contact-sheet.png 或 contact-sheet.svg 展示給使用者，並推薦 2 到 3 個最適合專案氣質的方向。
6. 如果 --png 因 Playwright 不可用而跳過，繼續使用 SVG 輸出；不要把「沒有 PNG」誤判為生成失敗。README 或回報中要展示 contact-sheet.svg、1 到 2 個 option-*.svg，並說明 SVG 是可編輯原始檔。
7. 檢查 SVG 幾何：option-*.svg 必須是嚴格正方形來源圖；如果 contact sheet 或 README 圖片展示圓角預覽，必須用統一 mask 裁剪，不能出現方形來源圖蓋住圓角框後只露出四角弧線。
8. 使用者確認後，再把選中的 SVG/PNG 複製到目標專案，或開啟 QM Icon Studio 繼續匯出完整平台資源包。

工作流程：Codex 點陣參考方法

使用此路徑前，請先閱讀 references/codex-bitmap-reference-method.md。

1. 讀取專案上下文：產品名、用途、網域、現有 favicon/app icon、主色、品牌調性、目標平台。
2. 如果使用者要參考 Icon Museum，優先使用可用的本機參考庫。Joe 的預設路徑是 $HOME/Documents/圖片參考生成icon/icon-museum/manifest.json 和 icons/；其他機器可使用使用者提供的 manifest / 圖片目錄。按品類、顏色、用途篩出 6 到 12 個參考方向，但不要複製原圖、商標、應用名或獨特構圖。
3. 在專案內建立候選目錄，預設 design/<product-slug>-icon-options/，包含 prompts.md、choices.md、候選 PNG、選擇稿和匯出尺寸。
4. 使用 Codex 內建 image_gen，每個候選單獨一次生成。Prompt 必須包含：square app icon, opaque background, no text/letters/numbers/watermark, centered bold symbol, readable at 32px, iOS and web favicon use。
5. 將內建生圖輸出從 $CODEX_HOME/generated_images/... 複製到候選目錄，命名為 option-01.png 至 option-10.png。保留原始生成檔案，不刪除。
6. 生成 contact-sheet.png 和 favicon-readability-sheet.png，檢查 64px 和 32px 仍可辨認。
7. 使用者選中後，執行匯出腳本產生 Web/iOS 素材：

python3 scripts/export_selected_icon.py \
  --source design/qiaomu-music-icon-options/ios-1024/option-05.png \
  --web-out public/icons \
  --web-prefix qiaomu-music-icon \
  --appiconset ios/QiaomuMusic/QiaomuMusic/Assets.xcassets/AppIcon.appiconset

8. 把網站入口改為引用真實 PNG favicon/apple-touch icon；iOS 專案則更新 .appiconset 裡已有尺寸。不要在使用者確認前覆蓋生產圖示。

規則

• 不要在使用者選擇前覆蓋現有生產圖示。
• 不要把純裝飾圖案當成品牌圖示；圖形必須能在 32px favicon 下辨認。
• 優先生成 6 到 12 個候選，少於 4 個不利於比較，多於 12 個會讓選擇變累。
• 候選稿預設保留方形來源圖；iOS、macOS、Windows 等平台圓角和格式留到最終匯出階段處理。
• 如果 PNG 渲染失敗，繼續使用 SVG 候選稿，並說明 Playwright 不可用。
• 如果外部網路不可用，加 --offline 使用內建圖示庫繼續生成候選。
• SVG CLI 候選原始檔必須是正方形；圓角只作為 contact sheet / README 的預覽 mask，不要烘進來源圖，也不要做成半截圓角邊框。
• Codex 點陣參考方法必須避免文字、字母、數字、偽文字、浮水印、真實商標和對參考圖的近似複製。
• Web/iOS 最終素材必須是方形、無透明通道、中心主體有安全邊距；iOS App Store master 使用 1024x1024 PNG。
• 若要替換現有網站或 App 圖示，先確認使用者已選擇候選編號，再匯出並替換。

輸出

QM Icon Studio CLI 候選目錄通常包含：

• option-01.svg 至 option-08.svg
• option-01.png 至 option-08.png，如果 Playwright 可用
• contact-sheet.svg
• contact-sheet.png，如果 Playwright 可用
• choices.md
• qm-icon-options.json

Codex 點陣參考方法候選目錄通常包含：

• option-01.png 至 option-10.png
• ios-1024/
• web-180/
• web-64/
• web-32/
• contact-sheet.png
• favicon-readability-sheet.png
• prompts.md
• choices.md

公開範例素材

公開 README 的主範例應優先使用真實產品案例，而不是只為倉庫本身生成一個 icon。目前推薦範例是喬木音樂網：

• Codex 點陣參考方法：docs/assets/examples/qiaomu-music/codex-bitmap/contact-sheet.png
• 選定最終圖示：docs/assets/examples/qiaomu-music/codex-bitmap/selected-option-05-ios-1024.png
• Favicon 可讀性：docs/assets/examples/qiaomu-music/codex-bitmap/favicon-readability-sheet.png
• SVG CLI 方法：docs/assets/examples/qiaomu-music/svg-cli/contact-sheet.svg
• SVG CLI 預覽：docs/assets/examples/qiaomu-music/svg-cli/svg-cli-preview.png

加入新的公開範例時，請同時包含視覺證明與流程筆記：候選表、選定素材、小尺寸可讀性測試，以及產生該結果所用的命令或 prompt。