app-icon-gen

App Icon Gen

根据 JSON 规范创建可跨平台复用的图标源资源。常规流程是语义化分层创作：使用少量有意义的 SVG／基础形状图层，或有意保持简洁的 PNG 回退图层；创建圆角预览资源、非圆角应用／源资源，以及验证证据。Apple Icon Composer 打包是可选适配器，并非默认约定。

如果 macOS 上本地提供 Icon Composer 随附的 ictool，此技能可以用它导出渲染后的 PNG。它无法证明应用集成情况，也无法证明这些导出的 PNG 文件之外的平台最终渲染效果。

硬性约定

对于每个新建或修复的图标，使用一个生成根目录：面向用户的交付目录。

• target_platforms 是可选元数据。接受用户提供的平台标签，不要推断、扩展或拒绝非 Apple 平台。
• 始终优先交付可复用的 SVG／PNG 源资源。检查这些资源后，询问用户是否需要原生平台导出；没有对应的专用适配器时，不要声称已提供原生 Android、Windows、Web、tvOS 或 visionOS 包。
• 用户通过 Apple 目标（iOS、iPadOS、macOS 或 watchOS）或 Apple deliverable_type 请求打包时，才创建 .icon 包和可选的 apple/ 渲染文件。
• 通过 Apple 适配器收到 watchOS 请求时，需单独检查圆形裁切和 1088px Default 渲染结果。
• 生成前，将当前规范写入 <delivery>/tmp/work/spec.json。
• 存在用户提供的源图像／矢量图，或已选定的生成概念时，仅保留一个可见的源证据文件，路径为 <delivery>/<delivery-name>.origin.png 或 <delivery>/<delivery-name>.origin.svg；未选定的候选项放在 <delivery>/tmp/work/ 下。
• 创建中间产物时，一律放在 <delivery>/tmp/work/ 下，包括遮罩、阈值测试、提取出的前景、描摹候选项、对比图、备注和修复临时文件。
• 使用 author-icon --spec <delivery>/tmp/work/spec.json --out <delivery> 进行生成。
• 重新运行时可以覆盖根目录中的生成文件、layers/、.icon/、apple/ 和 tmp/reports/；必须保留现有的 tmp/work/，但可将 tmp/work/spec.json 替换为当前规范；除非所选源文件发生变化，否则必须保留 .origin.png／.origin.svg。
• 不要先在其他目录生成完整包，再将其整理或复制到交付目录中。
• 不要修改生成的 layers/、.icon/Assets 或 icon.json；应更新规范并重新生成。

常规交付目录结构：

<delivery>/
  <delivery-name>.preview.svg
  <delivery-name>.preview.png
  <delivery-name>.svg
  <delivery-name>.png
  <delivery-name>.origin.png or <delivery-name>.origin.svg  # when source evidence exists
  <Name>.icon/                        # optional Apple adapter
  apple/                              # optional Apple renders
    iOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
    macOS/{Default,Dark,TintedLight,TintedDark,ClearLight,ClearDark}.png
    watchOS/Default.png
  layers/
  tmp/
    reports/
    work/
      spec.json

可见的交付根目录只能包含 .svg、.png、.preview.svg、.preview.png、.origin.png、.origin.svg、.icon、apple/、layers/ 和 tmp/。

工作流

1. 在提问前检查提供的源文件：附件、路径、应用元数据、现有素材、截图、SVG/Logo 文件、.icon 包和项目本地源矢量图。
2. 选择一条路线：源文件转换、生成概念、直接语义创作或现有包优化。仅在已知目标平台时记录目标平台。
3. 只阅读下方与所选路线对应的参考资料。
4. 编写或更新 <delivery>/tmp/work/spec.json；图层按从底到顶的视觉顺序排列。如果存在源文件证据，将选定的源文件或概念复制到 <delivery>/<delivery-name>.origin.png 或 <delivery>/<delivery-name>.origin.svg。
5. 直接生成到交付目录。通用 SVG/PNG 素材始终会写入。如果请求了 Apple 适配器且 Icon Composer.app 的 ictool 可用，还会在 apple/ 下写入 Apple 渲染文件。
6. 运行 verify；如果存在参考图像，则添加 --reference。仅当参考图像的画布、尺寸或蒙版与预览画布不同时，才先对其进行标准化。
7. 以原尺寸和 64px 尺寸检查生成的预览/应用素材，并查看适用的验证证据。如果存在 Apple 适配器，还要检查 .icon/Assets、icon.json 和任何请求的 Apple 渲染文件。需要人工判断时记录 visual-review.json；不要将缺少可选平台导出文件视为一般性失败。
8. 如果验证或检查失败，修复规格，重新生成并再次验证。

从技能目录运行命令，或为 scripts/ 使用绝对 --prefix。Node 包元数据位于 scripts/package.json；不要在技能根目录运行 npm install。

npm --prefix scripts ci

delivery="/absolute/path/to/my-icon"
mkdir -p "$delivery/tmp/work"

npm --prefix scripts run author-icon -- \
  --spec "$delivery/tmp/work/spec.json" \
  --out "$delivery"

npm --prefix scripts run verify -- --out "$delivery"

使用参考图像时：

npm --prefix scripts run verify -- \
  --out "$delivery" \
  --reference "/absolute/path/to/reference.png"

脚本的输入和输出请使用绝对路径。

author-icon 不会替换它不拥有的非空目录。它只会刷新上一次样式报告中经过验证的 generated_files 所有权清单所列的叶文件；如果该清单与从安全报告推导出的文件集合不一致，则会安全地拒绝操作。只有在生成的目录变为空目录后才会将其删除；即使其他文件位于 layers/、.icon/ 或 apple/ 中，也会予以保留。只有在工作流之外自行检查过后，才清理不属于本工具的目录。

验证证据阶梯

不要仅凭并排对比和平均差值来修复或切换路线。应根据故障类型选择证据，并在更改规范前使用这些证据：

• 整体图标相似度：先查看 reference-side-by-side.png，检查整体风格、比例、视觉分量和明显偏差。
• 几何形状、位置、比例和图层对齐：在判断前景偏移、过小／过大或形状错误之前，先查看 reference-overlay.png。
• 颜色、背景、辉光、阴影、抗锯齿和材质偏差：在更改填充或添加／移除材质之前，查看 reference-diff.png 和验证器诊断信息。
• 圆角应用遮罩／边框偏差：将 frame_or_rounded_mask_residual_dominated 视为边框归一化证据，而非前景形状故障；修复图形标记前先检查内部差异图。
• 严重的局部不匹配：读取 local_sample_gate、local_samples 和 tile_heatmap；将热点转化为具体的修复假设，而不是把它们视为另一个分数。
• 平滑的符号图形、吉祥物、环形图案、飘带和品牌风格轮廓：当视觉错误不明确时，结合叠加图／差异图与 bbox／质心或 shape-facts 检查。
• 简单的 SVG 基本图形：修复受影响图层后运行 geometry-audit；数值通过并不意味着曲线不抖动、切线不合理或路径没有噪点。
• PNG 回退：检查隔离的 PNG 资源和 png_layer_hygiene；仅仅在参考图均值上表现良好还不够。

参考驱动型工作的修复顺序：先处理几何形状／位置，再处理比例，然后处理颜色／背景，最后处理渲染器／材质差异。只有在相关 SVG 路线已通过叠加图／差异图／局部诊断或隔离资源检查证明失败后，才选择 PNG 回退；对于可干净分离的轮廓，相关 SVG 路线还包括组件级描摹 SVG，然后才是 PNG 回退。

参考资料路由

• references/source-requirements.md：来源出处、身份风险、来源分类、背景路线和 PNG 回退风险。
• references/concept-prompts.md：不存在源图稿，需要生成图像或直接创作概念。
• references/semantic-icon-design.md：无参考图像生成与直接语义创作共用的 JSON 设计约定。
• references/style-directions.md：适用于 semantic_icon_design 的 SVG 可转换风格方向。
• references/semantic-authoring.md：JSON 规范结构、semantic_review、source_analysis、图层顺序、文本和 PNG 回退决策。
• references/cookbook.md：路线不明确，或图标属于已知类别，例如几何标记、字形、文本、材质参考或重叠板片。
• references/icon-composer.md：.icon 结构、填充格式、Icon Composer 材质边界、资源格式和 icon.json。
• references/verification.md：验证器行为、参考图比较、视觉审核辅助文件、批次摘要和审核门槛。
• references/optimization-methods.md：几何润色、位图提取、形状诊断、局部修复或前景清理。
• references/failure-modes.md：PNG 脏边、语义错误、预览／填充偏差、源矢量需求、路径修复或误导性的数值通过结果。
• references/golden-examples.md：小型的已知良好规范和反模式。
• examples/semantic-image-prompts/README.md：无参考图像提示词示例索引；选择风格方向后，只读取匹配的示例文件。

完成门槛

仅当所有适用的检查均通过时，才算完成：

• 必需的根目录资源、layers/、tmp/reports/style-report.json 和 tmp/work/spec.json 均存在。只有在请求了 Apple 适配器时，.icon/ 和 apple/ 才会存在。
• 当源图、参考图或生成图中的概念促成了该包时，交付根目录中存在 <delivery-name>.origin.png 或 <delivery-name>.origin.svg，且未导入 .icon/Assets。
• 预览 SVG/PNG 是圆角的本地视觉契约；根目录 SVG/PNG 是未经圆角处理的应用/源画布。
• 如果请求了 Apple 适配器，其中应包含整洁的 .icon/Assets，而不是单个扁平化的应用图标；除非接受的方案是有文档记录的 PNG 回退方案。
• svg_material_warnings 和包中的 warnings 均为空。每个 png_layer_hygiene 条目都通过边缘/残留检查；合法且整洁的 PNG 资源可以使此数组非空。
• 对于参考图匹配，已生成并检查并排对比图、叠加图和差异图；已使用叠加图/差异图/本地诊断来论证任何修复或方案变更；平均差值、visual_delta_gate 和 local_sample_gate 均达到方案目标，或已记录接受的语义权衡。
• .icon/Assets 中没有重复的纯色背景；没有将仅用于预览的轮廓、辉光、斜面、阴影、高光、边框或遮罩伪影作为源素材导入。

除非用户明确要求，否则不要将完成范围扩大到 Icon Composer 导入、应用集成、发布或平台专用的最终渲染。

最终回复必须包含交付路径、通用源资源、用户提供时的目标平台元数据、可选适配器输出、适用时的源证据，以及实际检查过的预览/资源。对于未安装的适配器不支持的原生导出，在声称或尝试之前必须先询问。