add-icon

向用户的项目添加 Font Awesome 图标。此技能适用于所有 Font Awesome 集成方式，可处理图标名称解析、项目检测和代码生成。

suggest-icon 中引用的脚本相对于 plugins/icons/skills/suggest-icon/。add-icon 中引用的脚本相对于 plugins/icons/skills/add-icon/。请在各自的目录中运行这些脚本。

工具选择

开始时，运行 command -v fa，检查 PATH 中是否有 fa CLI。

fa kit 子命令需要 fa 版本 0.8.0 或更高版本。如果需要使用 fa kit 子命令，建议用户升级 fa，升级说明见：https://docs.fontawesome.com/web/use-with/fa-cli

• 如果找到了 fa： 使用它查找图标并获取 Kit（它会返回结构化 JSON）。对于 Kit 操作（fa kits 和 fa kit），先检查身份验证：运行 fa whoami 查看用户是否已登录。如果已登录，这些操作即可直接使用。如果未登录但设置了 FA_API_TOKEN，也可以使用。如果两者都没有，请告知用户：“你需要登录 Font Awesome CLI 才能执行 Kit 操作。请在单独的终端中运行 fa login，然后回来重试。”如果用户无法登录，则改用 fetch-kit.py。如果项目使用 Kit，fa kit icon --kit-token <TOKEN> <icon> 可以告知特定图标是否包含在 Kit 的子集中，以及该图标支持哪些系列样式——请使用此命令，避免添加 Kit 中不包含的图标（见步骤 3）。
• 如果未找到 fa： 改用下文所述的 Python 脚本。
• 使用 latest-version.py 获取最新版本。

步骤

1. 解析图标名称

首先，确定项目是否使用 Kit 集成 Font Awesome。如果项目中有 .font-awesome.md 文件，请阅读该文件以确定是否使用 Kit。

如果项目使用 Kit

如果项目使用 Kit，则需验证该图标是否存在于相应 Kit 的子集中。这只能通过 fa CLI 完成。如果用户尚未登录，请先提示他们在单独的终端中运行 fa login。

如果无法使用 fa CLI，请告知用户你无法验证该图标是否存在于他们的 Kit 子集中。建议他们安装 fa CLI，使用 fa login 登录，然后重新运行此技能。

要验证 Kit 中是否存在该图标，请运行 fa kit icon --kit-token <TOKEN> <icon>。

如果该图标不存在，请在内部调用 /suggest-icon 技能，并将用户的 icon 参数作为使用场景。如果有推荐，请自动接受排名第一的推荐，无需提示用户确认。

如果 /suggest-icon 没有给出推荐，可能是因为 Kit 的子集中没有与用户查询相似的图标。这种情况下，请使用 fa search --version <version> --query <icon> 在整个 Font Awesome 中（而不只是 Kit 中）搜索相似图标。告知用户他们请求的图标不在 Kit 的子集中，但可以将其添加到 Kit 中：https://fontawesome.com/kits

如果项目未使用 Kit

如果项目未使用 Kit，则需验证图标是否存在：

确定当前使用的 Font Awesome 版本。首先尝试从 .font-awesome.md 中获取版本；否则，使用 latest-version.py 获取最新版本。在以下命令中将此版本用作 <version>。

• fa CLI： 运行 fa icons --version <version> --name <icon>。如果 data.release.icon 不为 null，则表示该图标存在。familyStylesByLicense 字段会显示免费版和 Pro 版的细分情况。
• 回退方式： 运行 ./scripts/icon-exists.py --version <version> --icon-name <icon>。退出码 0 表示图标存在；退出码 1 表示图标不存在。

如果该图标不存在，请在内部调用 /suggest-icon 技能，并将用户的 icon 参数作为使用场景。自动接受排名第一的推荐，并使用该图标名称继续操作。不要要求用户确认——使用可用的图标胜过使用无法正常工作的图标。

2. 确定集成方式

检查项目根目录中是否存在 .font-awesome.md 文件。

如果存在 .font-awesome.md

读取该文件，并使用其中描述的配置。跳过探索，继续执行第 3 步。不过，请记住文件内容——如果后续步骤发现文件中缺失或不完整的信息（例如，新的导入模式、未列出的系列或未记录的包装组件），请在最后更新该文件（参见第 6 步）。

如果不存在 .font-awesome.md

执行探索流程，了解项目如何使用 Font Awesome。使用子 Agent（通过 Agent 工具，并设置 subagent_type: "Explore"）来执行此探索。子 Agent 应按具体程度从高到低搜索以下来源，并以结构化摘要的形式返回发现结果：

1. package.json / lock 文件 — 查找 Font Awesome 软件包：

   • @fortawesome/react-fontawesome → React 组件集成
   • @fortawesome/vue-fontawesome → Vue 组件集成
   • @fortawesome/fontawesome-svg-core → SVG 核心（供 React/Vue 使用）
   • @fortawesome/fontawesome-free 或 @fortawesome/fontawesome-pro → 通用 SVG+JS 或 Web 字体
   • @fortawesome/free-solid-svg-icons、@fortawesome/pro-solid-svg-icons 等 → 单个图标软件包（注明样式和许可证）

2. HTML 文件 / 模板 — 查找：

   • Font Awesome Kit 脚本标签：<script src="https://kit.fontawesome.com/XXXXXX.js"...> → Kit（SVG+JS）。提取 Kit ID（.js 前的令牌）。
   • <link> 标签中的 CDN 链接：cdnjs.cloudflare.com/ajax/libs/font-awesome/ 或 use.fontawesome.com → 通过 CDN 使用 Web Fonts+CSS
   • <i class="fa-solid fa-..."> 或 <i class="fas fa-..."> 使用模式 → 基于类名的集成（Web Fonts+CSS 或 SVG+JS）

3. 源文件中的导入语句 — 搜索：

   • import { FontAwesomeIcon } → React 组件
   • 从 @fortawesome/fontawesome-svg-core 导入 library → library 方式
   • 单个图标导入，例如 import { faCoffee } → 单独导入方式

4. SVG 雪碧图 — 查找 <use href="...sprites/..."> 模式或雪碧图 SVG 文件。

5. Web Components — 查找 <fa-icon> 自定义元素。

6. 其他框架 — 查找 Angular（angular.json、FontAwesomeModule）、Svelte 等。

子 Agent 应返回：已安装的 Font Awesome 软件包（含版本）、找到的 Kit ID、CDN URL、框架集成方式、源文件中观察到的导入模式、许可证（免费版或专业版），以及项目约定（包装组件、默认尺寸等）。

子 Agent 返回结果后，如果找到了 Kit ID，则获取 Kit 详细信息：

• fa CLI： 运行 fa kit show --kit-token <id>。该命令会返回包含 Kit 版本、许可证、技术和可用系列的 JSON。需要用户已登录（fa whoami 返回成功）或设置了 FA_API_TOKEN。如果两者都不满足，请提示用户先在单独的终端中运行 fa login。
• 回退方案： 在 add-icon 技能目录中运行 ./scripts/fetch-kit.py --kit-id <id>，以获取 Kit 版本、许可证、方式和可用系列。

探索完成后，确定：

• 集成方式 — 图标渲染的主要方式
• Kit ID / CDN URL — 如果使用 Kit 或 CDN
• 许可证 — free 或 pro。根据以下信息判断：Kit 配置（通过 fetch-kit.py）、npm 包名（fontawesome-free 与 fontawesome-pro、free-*-svg-icons 与 pro-*-svg-icons），或 CDN URL 模式。
• 默认样式 — 项目中最常用的样式（solid、regular、light、thin、duotone）。如果无法确定，则默认为 solid。
• 默认系列 — 项目中最常用的系列（classic、duotone、sharp、sharp-duotone、chisel、etch、graphite、jelly、jelly-duo、jelly-fill、notdog、notdog-duo、slab、slab-press、thumbprint、utility、utility-duo、utility-fill、whiteboard）。如果无法确定，则默认为 classic。
• 可用系列 — 项目有权使用的系列集合。对于 Kit，使用 fetch-kit.py 的输出。对于 npm，根据已安装的包推断。免费用户只能使用 classic。
• 导入模式 — 对于 JS 框架：每个文件单独导入，或注册到库中
• 版本 — 使用中的 Font Awesome 版本
• 项目约定 — 观察到的包装组件、标准尺寸或模式

将结果写入项目根目录中的 .font-awesome.md。阅读（位于此技能目录 plugins/icons/skills/add-icon/ 中的）font-awesome-md-format.md，了解要使用的模板和格式。

告知用户：“我已将项目的 Font Awesome 配置写入 .font-awesome.md。请提交此文件，以便团队成员受益，并加快今后添加图标的速度。”

在写入 .font-awesome.md 之前，不要继续下一步。 后续步骤都依赖此文件。如果发现的信息不足以写出有意义的 .font-awesome.md，请停止并询问用户，澄清其 Font Awesome 配置后再继续。

3. 确定图标样式和系列

样式 — 按以下优先级确定：

1. 如果用户传入了 style 参数，则使用该参数。
2. 否则，使用 .font-awesome.md 中的默认样式。
3. 如果两者都没有，则默认为 solid。

系列 — 按以下优先级确定：

1. 如果用户明确指定了系列，则使用该系列。
2. 否则，使用 .font-awesome.md 中的默认系列。
3. 如果两者都没有，则默认为 classic。

如果 .font-awesome.md 记录了 Kit ID（Kit 令牌），说明项目的图标来自 Kit，而 Kit 只包含 Font Awesome 全部图标的一个子集。不要添加 Kit 未包含的图标——它无法渲染。

根据项目是否使用 Kit，确认所选样式和系列中是否提供该图标：

如果项目使用 Kit

重用步骤 1“解析图标名称”中 fa kit icon --kit-token <TOKEN> <icon> 的输出。当时使用该输出来解析图标名称。此处也可以使用相同的输出来检查所选的系列和样式中是否提供该图标。

如果该图标不在你选择的系列和样式中，但在其他系列和样式中可用，请告知用户，并询问他们是否愿意改用其他可用的系列和样式；否则，告知他们将缺少的图标添加到 Kit 子集中。

如果 Kit 中完全没有该图标，请在生成代码前停止。告知用户该图标不属于其 Kit 子集，并提供两种选择：(a) 在 https://fontawesome.com/kits 将该图标添加到 Kit，然后重新运行；或 (b) 选择 Kit 中可用的替代图标——你可以运行 /suggest-icon（支持 Kit）来查找替代项。不要悄悄添加 Kit 中没有的图标。

要查看 Kit 实际包含的内容，fa kit family-styles --kit-token <TOKEN> 会显示可用的系列和样式，fa kit icons --kit-token <TOKEN> 会列出可用的图标变体，即特定系列和样式中的图标。这两个查询都会分页。

如果项目未使用 Kit

运行 icon-exists.py。其输出会显示可用的系列和样式。如果所需图标在指定样式或系列中不可用，请告知用户并推荐可用的替代选项。此外，请检查所选系列是否在项目的可用系列列表中；如果不在，请向用户发出警告。

4. 生成代码

根据 .font-awesome.md 中的集成方式生成正确的代码。以下是各种集成方式对应的模式。请遵循项目中已有的约定；如果项目已经采用了某种模式，请勿引入新模式。

React（@fortawesome/react-fontawesome）

单独导入（项目采用此模式时优先使用）：

import { faCartShopping } from '@fortawesome/pro-solid-svg-icons'
// or @fortawesome/free-solid-svg-icons for free icons

<FontAwesomeIcon icon={faCartShopping} />

导入名称为图标名称的驼峰形式，并以 fa 为前缀。例如：cart-shopping → faCartShopping。

包名称遵循以下模式：@fortawesome/{free|pro}-{style}-svg-icons。例如：

• @fortawesome/free-solid-svg-icons
• @fortawesome/pro-regular-svg-icons
• @fortawesome/pro-duotone-svg-icons
• @fortawesome/sharp-solid-svg-icons
• @fortawesome/sharp-duotone-svg-icons

Library 方式（项目全局注册图标时使用）：

// In the library setup file:
import { library } from '@fortawesome/fontawesome-svg-core'
import { faCartShopping } from '@fortawesome/pro-solid-svg-icons'
library.add(faCartShopping)

// In components — use string reference:
<FontAwesomeIcon icon="cart-shopping" />
// or with explicit prefix for non-solid styles:
<FontAwesomeIcon icon={['far', 'cart-shopping']} />

样式前缀：fas（solid）、far（regular）、fal（light）、fat（thin）、fad（duotone）、fass（sharp solid）、fasr（sharp regular）、fasl（sharp light）、fast（sharp thin）、fasd（sharp duotone）。

Vue（@fortawesome/vue-fontawesome）

与 React 类似，但使用 Vue 组件语法：

<font-awesome-icon :icon="['fas', 'cart-shopping']" />

导入遵循与 React 相同的包名称和命名约定。

SVG+JS Kit（<script src="https://kit.fontawesome.com/...">）

<i class="fa-solid fa-cart-shopping"></i>

类名模式取决于系列：

• classic（默认，无需系列前缀）：fa-{style} fa-{icon-name}
  • <i class="fa-solid fa-cart-shopping"></i>
• sharp：fa-sharp fa-{style} fa-{icon-name}
  • <i class="fa-sharp fa-regular fa-cart-shopping"></i>
• sharp-duotone：fa-sharp-duotone fa-{style} fa-{icon-name}
  • <i class="fa-sharp-duotone fa-solid fa-cart-shopping"></i>
• duotone：fa-duotone fa-{style} fa-{icon-name}
  • <i class="fa-duotone fa-solid fa-cart-shopping"></i>
• 其他 FA7 系列（chisel、etch、graphite、jelly、jelly-duo、jelly-fill、notdog、notdog-duo、slab、slab-press、thumbprint、utility、utility-duo、utility-fill、whiteboard）：fa-{family} fa-{style} fa-{icon-name}
  • <i class="fa-slab fa-solid fa-cart-shopping"></i>
  • <i class="fa-jelly fa-regular fa-cart-shopping"></i>

无需导入；Kit 会负责加载。

Web Fonts+CSS（CDN 或 npm）

类名语法与 SVG+JS Kit 相同：

<i class="fa-solid fa-cart-shopping"></i>

系列前缀的用法相同（例如，fa-sharp fa-solid fa-cart-shopping）。请确保已加载相应的 CSS 文件（all.css 或单独的样式表）。

SVG Sprites

<svg class="icon">
  <use href="/path/to/sprites/solid.svg#cart-shopping"></use>
</svg>

使用项目其他位置采用的 sprite 路径。

Angular

<fa-icon [icon]="faCartShopping"></fa-icon>

并在组件的 TypeScript 文件中进行相应导入。

Web Components（<fa-icon>）

<fa-icon class="fa-solid fa-cart-shopping"></fa-icon>

重要：裸 SVG 标记

绝不可依据自身知识或训练数据生成 Font Awesome SVG 标记（原始 <svg> 元素）。 如果用户需要裸 SVG 输出（例如，将图标内联为 <svg> 元素），必须使用 fa CLI 从 Font Awesome API 获取：

fa icons --version <version> --name <icon> --svg-format html

--svg-format 标志接受 html、data 或 icon-definition。用户必须先登录（fa whoami），或设置 FA_API_TOKEN。如果两者都未满足，请先提示用户在单独的终端中运行 fa login。

不要近似、重构或猜测 SVG 路径数据。Font Awesome API 始终是权威来源。

5. 插入或展示

如果用户提供了 location 参数：

在代码中找到指定位置。在那里插入图标代码，并在文件顶部添加任何必要的导入语句。遵循项目现有的格式和放置规范。

如果未提供位置：

在带有相应语言标记的围栏代码块中展示代码片段。如果需要导入语句，请单独展示，以便用户了解每段代码应放在哪里。

输出示例：

添加以下导入语句（如果尚未添加）：

import { faCartShopping } from '@fortawesome/pro-solid-svg-icons'

然后使用该组件：

<FontAwesomeIcon icon={faCartShopping} />

6. Pro 图标提示

如果该图标仅限 Pro 使用，且项目使用的是免费版（根据 .font-awesome.md 中的许可字段或发现的程序包判断），请提醒用户：

注意：cart-shopping 需要 Font Awesome Pro 订阅。你的项目似乎正在使用 Font Awesome Free。

7. 根据需要更新 .font-awesome.md

检查本次运行中发现的信息是否有任何内容尚未记入 .font-awesome.md。例如，以下信息可能不完整：

• 使用了新的导入模式，但 Import Pattern 中尚未记录
• 遇到了尚未列入 Families 的系列或样式
• 观察到尚未记录在 Conventions 中的包装组件或项目规范
• 版本、许可或集成方式发生了变化

如果有任何信息缺失或过时，请更新 .font-awesome.md，保持原有格式，只补充缺失内容。不要重写已经准确的部分。请告知用户更新了哪些内容，以便他们提交更改。