qiaomu-icon-generator

name	qiaomu-icon-generator
description	Generate multiple app, favicon, or website icon candidates with either the local QM Icon Studio CLI or Codex built-in image generation with reference icons, then present a contact sheet so the user can choose. Use when building websites or apps and needing reusable icon options.

Qiaomu Icon Generator

用本机 QM Icon Studio CLI 或 Codex 内置生图能力，为网站、App、工具或 Skill 生成多套图标候选，并给用户一张选择稿。

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

When To Use

• 新网站、App、Chrome 插件、Skill、CLI 工具需要 favicon、app icon 或品牌入口图标。
• 用户想先看多个方向再选，而不是直接替换生产图标。
• 项目还没有完整品牌系统，但已有名称、域名、用途或一句话描述。

Method Choice

Use the QM Icon Studio CLI method when the user wants deterministic, vector-friendly icons based on Iconify-style symbols, or when they need fast clean SVG candidates.

Use the Codex bitmap reference method when the user explicitly asks for Codex built-in image generation, wants richer iOS-style app icons, asks to reference existing icon galleries, or needs a polished raster icon direction before final export.

Workflow: QM Icon Studio CLI

Read references/qm-icon-studio-cli-method.md before using this path.

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 bitmap reference method，或让用户提供自己的图标生成 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 继续导出完整平台资源包。

Workflow: Codex Bitmap Reference Method

Read references/codex-bitmap-reference-method.md before using this path.

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 里已有尺寸。不要在用户确认前覆盖生产图标。

Rules

• 不要在用户选择前覆盖现有生产图标。
• 不要把纯装饰图案当成品牌图标；图形必须能在 32px favicon 下辨认。
• 优先生成 6 到 12 个候选，少于 4 个不利于比较，多于 12 个会让选择变累。
• 候选稿默认保留方形源图；iOS、macOS、Windows 等平台圆角和格式留到最终导出阶段处理。
• 如果 PNG 渲染失败，继续使用 SVG 候选稿，并说明 Playwright 不可用。
• 如果外部网络不可用，加 --offline 使用内置图标库继续生成候选。
• SVG CLI 候选源文件必须是正方形；圆角只作为 contact sheet / README 的预览 mask，不要烘进源图，也不要做成半截圆角边框。
• Codex bitmap reference method 必须避免文字、字母、数字、伪文字、水印、真实商标和对参考图的近似复制。
• Web/iOS 最终资产必须是方形、无透明通道、中心主体有安全边距；iOS App Store master 使用 1024x1024 PNG。
• 若要替换现有网站或 App 图标，先确认用户已选择候选编号，再导出并替换。

Output

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 bitmap reference method 候选目录通常包含：

• 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

Public Example Assets

公开 README 的主示例应优先使用真实产品案例，而不是只为仓库本身生成一个 icon。当前推荐示例是乔木音乐网：

• Codex bitmap reference method: docs/assets/examples/qiaomu-music/codex-bitmap/contact-sheet.png
• Selected final icon: docs/assets/examples/qiaomu-music/codex-bitmap/selected-option-05-ios-1024.png
• Favicon readability: docs/assets/examples/qiaomu-music/codex-bitmap/favicon-readability-sheet.png
• SVG CLI method: docs/assets/examples/qiaomu-music/svg-cli/contact-sheet.svg
• SVG CLI preview: docs/assets/examples/qiaomu-music/svg-cli/svg-cli-preview.png

When adding a new public example, include both visual proof and process notes: candidate sheet, selected asset, small-size readability test, and the command or prompt used to produce it.