favicon

根据 $1 处的源图像生成完整的 favicon 文件集，并在项目的 HTML 中添加相应的链接标签。

前提条件

首先，运行以下命令，确认已安装 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：确保静态资源目录存在

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

步骤 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": "maskable"
    },
    {
      "src": "/web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "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：总结

完成后报告以下内容：

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

错误处理

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