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 步检测到的静态资源目录。

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

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

favicon-96x96.png

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

apple-touch-icon.png（180x180）

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

web-app-manifest-192x192.png

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

web-app-manifest-512x512.png

magick "$1" -resize 512x512 -background none -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