favicon

根据源图片 $1 生成一套完整的 favicon，并在项目的 HTML 中添加相应的链接标签。

适用场景

• 需要从单张源图片生成一套完整的 favicon。
• 任务包括将资源放置在对应框架的静态目录中，并更新 HTML 链接标签。
• 希望通过一个工作流验证源图片、检测项目类型，并生成正确的 favicon 文件。

前置条件

首先运行以下命令，确认已安装 ImageMagick v7+：

which magick

如果未找到，请停止操作并指导用户安装：

• macOS：brew install imagemagick
• Linux：sudo apt install imagemagick

步骤 1：验证源图片

1. 确认源图片存在于指定路径：$1
2. 检查文件扩展名是否为受支持的格式（PNG、JPG、JPEG、SVG、WEBP、GIF）
3. 如果文件不存在或格式不是有效的图片格式，请报告错误并停止操作

注意源文件是否为 SVG 文件；如果是，还会将其复制为 favicon.svg。

步骤 2：检测项目类型和静态资源目录

检测项目类型，并确定静态资源的存放位置。按以下顺序检查：

框架	检测方式	静态资源目录
Rails	存在 config/routes.rb	public/
Next.js	存在 next.config.*	public/
Gatsby	存在 gatsby-config.*	static/
SvelteKit	存在 svelte.config.*	static/
Astro	存在 astro.config.*	public/
Hugo	存在 hugo.toml，或包含 Hugo 标记的 config.toml	static/
Jekyll	包含 Jekyll 标记的 _config.yml	根目录（与 index.html 相同）
Vite	存在 vite.config.*	public/
Create React App	package.json 中包含 react-scripts 依赖项	public/
Vue CLI	存在 vue.config.*	public/
Angular	存在 angular.json	src/assets/
Eleventy	存在 .eleventy.js 或 eleventy.config.*	检查 _site 输出目录或根目录
静态 HTML	根目录中存在 index.html	与 index.html 相同的目录

重要：如果发现现有 favicon 文件（例如 favicon.ico、apple-touch-icon.png），无论框架检测结果如何，都将这些文件所在的位置用作目标目录。

报告检测到的项目类型以及将要使用的静态资源目录。

不确定时请询问：如果无法百分之百确定静态资源的存放位置（例如项目结构不明确、存在多个可能的位置或使用了不熟悉的框架），请使用 AskUserQuestionTool 确认目标目录后再继续。询问总比将文件放错位置好。

步骤 3：确定应用名称

按以下优先顺序从这些来源获取应用名称：

1. 现有的 site.webmanifest —— 检查检测到的静态资源目录中是否存在清单文件，并提取 name 字段
2. package.json —— 如果存在 name 字段，则提取该字段
3. Rails config/application.rb —— 提取模块名称（例如，module MyApp →“MyApp”）
4. 目录名称 —— 使用当前工作目录名称作为后备值

如果需要，将名称转换为标题格式（例如，“my-app” →“My App”）。

步骤 4：确保静态资源目录存在

检查检测到的静态资源目录是否存在。如果不存在，则创建该目录。

图片和清单文件防护措施

检查源文件的尺寸和内容，而不仅仅是扩展名。渲染不可信的 SVG 时，须限制资源使用，且不得访问外部资源；不要将未经审核的 SVG 复制到公开网站。使用经过审核的正方形画布和内边距，确保保持宽高比的缩放能生成声明的正方形尺寸；检查所有输出。通用缩放图稿并不会自动适用于安全区域：下方清单使用 any。只有在确认设计符合安全区域要求后，才添加单独的 maskable 图标。保留现有清单字段，例如 start_url、scope、id、快捷方式和无关图标，并根据实际部署基础路径调整 URL。请参阅应用图标用途。

步骤 5：生成 Favicon 文件

运行这些 ImageMagick 命令以生成所有 Favicon 文件。将 [STATIC_DIR] 替换为步骤 2 中检测到的静态资源目录。

重要：-background none 标志必须放在输入文件之前，这样才能在渲染 SVG 时正确保留透明度。若将其放在输入文件之后，背景将变成白色。

favicon.ico（多分辨率：16x16、32x32、48x48）

magick -background none "$1" \
  \( -clone 0 -resize 16x16 \) \
  \( -clone 0 -resize 32x32 \) \
  \( -clone 0 -resize 48x48 \) \
  -delete 0 -alpha on \
  [STATIC_DIR]/favicon.ico

favicon-96x96.png

magick -background none "$1" -resize 96x96 -alpha on [STATIC_DIR]/favicon-96x96.png

apple-touch-icon.png（180x180）

magick -background none "$1" -resize 180x180 -alpha on [STATIC_DIR]/apple-touch-icon.png

web-app-manifest-192x192.png

magick -background none "$1" -resize 192x192 -alpha on [STATIC_DIR]/web-app-manifest-192x192.png

web-app-manifest-512x512.png

magick -background none "$1" -resize 512x512 -alpha on [STATIC_DIR]/web-app-manifest-512x512.png

favicon.svg（仅当源文件为 SVG 时）

如果源文件的扩展名是 .svg，请复制该文件：

cp "$1" [STATIC_DIR]/favicon.svg

步骤 6：创建/更新 site.webmanifest

使用以下内容创建或更新 [STATIC_DIR]/site.webmanifest（将检测到的应用名称代入）：

{
  "name": "[APP_NAME]",
  "short_name": "[APP_NAME]",
  "icons": [
    {
      "src": "/web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}

如果静态目录中已存在 site.webmanifest，更新 name、short_name 和 icons 数组时，请保留现有的 theme_color、background_color 和 display 值。

步骤 7：更新 HTML/布局文件

根据检测到的项目类型，更新相应文件。根据静态资源目录相对于 Web 根目录的位置调整 href 路径：

• 如果静态文件位于 public/ 或 static/，且从根目录提供服务 → 使用 /favicon.ico
• 如果静态文件位于 src/assets/ → 使用 /assets/favicon.ico
• 如果静态文件与 HTML 位于同一目录 → 使用 ./favicon.ico 或直接使用 favicon.ico

对于 Rails 项目

编辑 app/views/layouts/application.html.erb。找到 <head> 部分，并添加或替换与 Favicon 相关的标签：

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="[APP_NAME]" />
<link rel="manifest" href="/site.webmanifest" />

重要：

• 如果源文件不是 SVG，请省略 <link rel="icon" type="image/svg+xml" href="/favicon.svg" /> 行
• 添加新标签之前，请移除所有现有的 <link rel="icon"、<link rel="shortcut icon"、<link rel="apple-touch-icon" 或 <link rel="manifest" 标签
• 将这些标签放在 <head> 部分靠前的位置，位于 <meta charset> 和 <meta name="viewport">（如果存在）之后

对于 Next.js 项目

编辑检测到的布局文件（app/layout.tsx 或 src/app/layout.tsx）。更新或添加 metadata 导出，以包含图标配置：

export const metadata: Metadata = {
  // ... keep existing metadata fields
  icons: {
    icon: [
      { url: '/favicon.ico' },
      { url: '/favicon-96x96.png', sizes: '96x96', type: 'image/png' },
      { url: '/favicon.svg', type: 'image/svg+xml' },
    ],
    shortcut: '/favicon.ico',
    apple: '/apple-touch-icon.png',
  },
  manifest: '/site.webmanifest',
  appleWebApp: {
    title: '[APP_NAME]',
  },
};

重要：

• 如果源文件不是 SVG，请从图标数组中省略 { url: '/favicon.svg', type: 'image/svg+xml' } 条目
• 如果不存在 metadata 导出，请创建一个仅包含图标相关字段的导出
• 如果已存在 metadata 导出，请将图标配置与现有字段合并

对于静态 HTML 项目

编辑检测到的 index.html 文件。在 <head> 部分添加与 Rails 相同的 HTML。

如果未检测到项目

跳过 HTML 更新，并告知用户需要手动将以下内容添加到 HTML 的 <head> 中：

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="[APP_NAME]" />
<link rel="manifest" href="/site.webmanifest" />

步骤 8：摘要

报告完成情况，包括：

• 检测到的项目类型和框架
• 使用的静态资源目录
• 生成的文件列表
• 清单和 HTML 中使用的应用名称
• 已更新的布局文件（或注明需要手动更新）
• 是否覆盖了任何现有文件

错误处理

• 如果未安装 ImageMagick，请提供安装说明并停止
• 如果源图像不存在，请报告尝试使用的确切路径并停止
• 如果 ImageMagick 命令失败，请报告具体错误消息
• 如果找不到用于更新 HTML 的布局文件，请仍然生成文件，并说明如何手动添加 HTML

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审核的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。