suggest-icon

Font Awesome 图标的固有知识有助于快速做出初步判断，但可能因版本不同而不准确。为提供可靠答案，请综合多种信息来源。

以下所有脚本均相对于此技能目录（plugins/icons/skills/suggest-icon/）。请从该目录运行这些脚本。

工具选择

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

fa kit 子命令要求 fa 版本为 0.8.0 或更高版本。如果需要使用 fa kit 子命令，请建议用户升级 fa，并参考此处的说明：https://docs.fontawesome.com/web/use-with/fa-cli

• 如果找到 fa： 使用它查找和搜索图标（它会返回结构化 JSON）。如果项目配置了 Kit（请参阅下文“遵循已配置的 Kit”），也使用 fa search --kit-token <TOKEN> 仅搜索 Kit 中可用的图标，并使用 fa kit icon 确认指定图标是否包含在其中。对于 fa kit ... 操作，请先检查身份验证（fa whoami 或 FA_API_TOKEN）；如果无法进行身份验证，请改用不限定范围的搜索，并提醒用户无法验证 Kit 的覆盖范围。
• 如果未找到 fa： 改用下文介绍的 Python 脚本。Kit 感知搜索需要 fa CLI；没有它，就无法将建议限定在 Kit 的子集中——请提醒用户，你的建议可能包含其 Kit 中没有的图标。
• 使用 latest-version.py 获取最新版本。

遵循已配置的 Kit

如果项目中有 .font-awesome.md 文件，且其中包含 Kit ID（即 Kit 令牌），那么用户使用的图标来自该 Kit，而 Kit 只包含全部 Font Awesome 图标中的一个子集。不要建议 Kit 中不包含的图标——推荐 Kit 中没有的图标会导致显示异常，无法渲染。

如果存在 Kit 令牌，请将每项建议都限定在该 Kit 中：

• 使用 fa search --kit-token <TOKEN> --query <your-guess> 搜索，而不是使用 fa search --version <version> ...。此命令仅返回 Kit 中实际可用的图标，最多不超过 Kit 的子集范围，因此返回的每个结果都可以放心推荐。
• 在给出首选建议之前，使用 fa kit icon --kit-token <TOKEN> <icon> 确认该图标。此命令会告知该图标是否在 Kit 中，以及它包含哪些系列样式。
• 如果你最想推荐的图标不在 Kit 中，请明确说明，并改为推荐 Kit 中最接近的替代图标；同时告知用户，可在 https://fontawesome.com/kits 将缺失的图标添加到 Kit 中（添加后即可使用）。

如果不存在 .font-awesome.md，或者文件中没有记录 Kit，则可照常从完整图标集中进行建议。

步骤

1. 确定版本。 如果用户指定了 Font Awesome 版本，就使用该版本。否则，使用最新版本（参见上文“工具选择”）。后续所有步骤都使用确定的版本。

   还要检查项目根目录中是否有 .font-awesome.md 文件。如果其中记录了 Kit ID（Kit 令牌），请记下它 — 你将把搜索和建议限定在该 Kit 范围内（参见上文“遵循已配置的 Kit”）。

2. 先做初步判断。 根据你的知识，选择你认为最符合用例参数的图标名称。

3. 验证图标是否存在。

   • fa CLI： 运行 fa icons --version <version> --name <your-guess>。如果 data.release.icon 不为 null，则图标存在。familyStylesByLicense 字段显示免费版和专业版的分类。
   • 备用方式： 运行 ./scripts/icon-exists.py --version <version> --icon-name <your-guess>。退出代码 0 表示图标存在；退出代码 1 表示图标不存在。

   如果已配置 Kit 令牌， 还要通过 fa kit icon --kit-token <TOKEN> <your-guess> 确认图标是否属于该 Kit。图标可能存在于 Font Awesome 中，但不在该 Kit 的子集中 — 如果图标不在 Kit 中，就不要直接推荐（参见步骤 5）。

4. 搜索替代方案。 无论初步判断的图标是否存在，都要进行搜索 — 搜索往往能找到更具体或更合适的图标，而这些图标可能是你自己想不到的。

   • 已配置 Kit（fa CLI）： 运行 fa search --kit-token <TOKEN> --query <your-guess> --page-size 10。此命令只返回 Kit 中可用的图标，因此每个结果都可以放心推荐。只要存在 Kit 令牌，就优先使用此方式。
   • 未配置 Kit（fa CLI）： 运行 fa search --version <version> --query <your-guess> --page-size 10。结果位于 data.searchPaginated.icons[]，每个结果都包含 id、label、unicode 和 familyStylesByLicense。
   • 备用方式： 运行 ./scripts/search.py --version <version> --query <your-guess>，通过 Font Awesome GraphQL API 查找相关图标。（此方式无法将搜索范围限定在 Kit 的子集中。）

5. 提供推荐。 选择最匹配的图标作为首选推荐；如果搜索发现了其他合适的选项，也要一并列出。如果已配置 Kit，所有推荐的图标都必须包含在该 Kit 中；如果最符合概念的图标不在 Kit 中，就推荐 Kit 中最接近的替代图标，并说明可以在 https://fontawesome.com/kits 将缺少的图标添加到 Kit。使用类似以下示例的 Markdown 表格：

   图标	样式系列	可用性
   mug-saucer	classic, sharp, duotone, sharp-duotone	免费

   如果图标仅限专业版使用，请注明需要 Font Awesome 订阅：

   图标	样式系列	可用性
   album-collection	classic, sharp, duotone, sharp-duotone	专业版（需要订阅）

6. 绝不提供未经处理的 SVG 标记。 如果用户要求图标的原始 <svg> 输出，不要凭自己的知识生成。应引导用户使用 /add-icon，通过 fa icons --svg-format 从 Font Awesome API 获取权威的 SVG 标记。

7. 询问是否添加图标。 提供推荐后，询问用户：“你希望我将此图标添加到你的代码中吗？”如果用户同意或提供了位置，就使用推荐的图标名称（以及用户提供的位置）调用 /add-icon。