乔牧图标生成器は何をしますか？

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

何时使用

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

方法选择

当用户希望获得基于 Iconify 风格符号的确定性、矢量友好图标时，或需要快速干净的 SVG 候选时，使用 QM Icon Studio CLI 方法。

当用户明确要求使用 Codex 内置图像生成、希望获得更丰富的 iOS 风格应用图标、要求参考现有图标库，或者需要先有一个精细的位图图标方向再做最终导出时，使用 Codex bitmap reference method。

工作流：QM Icon Studio CLI

使用此路径前请先阅读 references/qm-icon-studio-cli-method.md。

读取项目上下文：README.md、package.json、站点域名、已有的 public/ 或 assets/ 图标、主色 CSS 变量。
提炼一个短英文语义关键词，例如 rocket、globe、code、book、camera、music、money。中文需求可以直接传给 CLI；CLI 会先翻译再搜索 Iconify，必要时你也可以手动改成更准确的英文词。
在项目内创建候选目录，默认使用 design/icon-options/；如果项目已有设计目录，沿用现有结构。
如果当前机器有 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 / 图标参考库路径。

把 contact-sheet.png 或 contact-sheet.svg 展示给用户，并推荐 2 到 3 个最适合项目气质的方向。
如果 --png 因 Playwright 不可用而跳过，继续使用 SVG 输出；不要把“没有 PNG”误判为生成失败。README 或汇报中要展示 contact-sheet.svg、1 到 2 个 option-*.svg，并说明 SVG 是可编辑源文件。
检查 SVG 几何：option-*.svg 必须是严格正方形源图；如果 contact sheet 或 README 图片展示圆角预览，必须用统一 mask 裁剪，不能出现方形源图盖住圆角框后只露出四角弧线。
用户确认后，再把选中的 SVG/PNG 复制到目标项目，或打开 QM Icon Studio 继续导出完整平台资源包。

工作流：Codex Bitmap Reference Method

使用此路径前请先阅读 references/codex-bitmap-reference-method.md。

读取项目上下文：产品名、用途、域名、现有 favicon/app icon、主色、品牌调性、目标平台。
如果用户要参考 Icon Museum，优先使用可用的本机参考库。Joe 的默认路径是 $HOME/Documents/图片参考生成icon/icon-museum/manifest.json 和 icons/；其他机器可使用用户提供的 manifest / 图片目录。按品类、颜色、用途筛出 6 到 12 个参考方向，但不要复制原图、商标、应用名或独特构图。
在项目内创建候选目录，默认 design/<product-slug>-icon-options/，包含 prompts.md、choices.md、候选 PNG、选择稿和导出尺寸。
使用 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.
将内置生图输出从 $CODEX_HOME/generated_images/... 复制到候选目录，命名为 option-01.png 至 option-10.png。保留原始生成文件，不删除。
生成 contact-sheet.png 和 favicon-readability-sheet.png，检查 64px 和 32px 仍可辨认。
用户选中后，运行导出脚本生成 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

把网站入口改为引用真实 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 bitmap reference method 必须避免文字、字母、数字、伪文字、水印、真实商标和对参考图的近似复制。
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 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

公共示例资源

公开 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

添加新的公共示例时，请同时包含视觉证明和过程笔记：候选表、选中的资产、小尺寸可读性测试，以及用于生成的命令或 prompt。

乔牧图标生成器