create-favicon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

create-favicon

Language: Match the user’s language (中文提问则中文回复).

语言：匹配用户使用的语言（中文提问则中文回复）。

Normative references (read before generating)

规范性参考（生成前请阅读）

```
references/ico-format-and-browser-notes.md
```
— ICO 结构、MIME、尺寸与 Apple Touch Icon 说明。
```
USAGE.md
```
— 输入输出约定与无图门禁话术。

```
references/ico-format-and-browser-notes.md
```
— ICO 结构、MIME、尺寸与 Apple Touch Icon 说明。
```
USAGE.md
```
— 输入输出约定与无图门禁话术。

Step 0 · Mandatory source image gate（必须最先执行）

步骤0 · 强制源图校验（必须最先执行）

DO NOT resize, pack ICO, or write

favicon.ico

until a usable source image is confirmed.

Treat the source as present only if 至少一项成立：

用户在对话中 附加了图片；或
用户给出了 可读的绝对/相对路径，且你能
```
read_file
```
/打开该图像文件；或
用户 明确指定 工作区内某文件为源图（例如
```
@public/logo.png
```
），且该文件为常见栅格/矢量图格式（PNG、JPEG、WebP、GIF、SVG 等）。

IF none of the above applies — including when the user only says “做个 favicon”而未指定用哪张图、也未附加图片：

STOP immediately.
DO NOT invent a placeholder icon, DO NOT pick a random image from the repo, DO NOT run conversion tools.
Reply clearly, e.g. 「请先上传用作 favicon 的源图片，或提供可访问的图片文件路径（如
public/logo.png
），我才能生成
favicon.ico
。」

在确认获取到可用的源图像之前，请勿调整大小、打包ICO或写入

favicon.ico

文件。

仅当至少一项条件成立时，判定源图已提供：

用户在对话中 附加了图片；或
用户给出了 可读的绝对/相对路径，且你可以
```
read_file
```
/打开该图像文件；或
用户 明确指定 工作区内某文件为源图（例如
```
@public/logo.png
```
），且该文件为常见栅格/矢量图格式（PNG、JPEG、WebP、GIF、SVG 等）。

如果以上条件均不成立 —— 包括用户仅说“做个 favicon”而未指定用哪张图、也未附加图片的情况：

立即停止操作。
不要生成占位图标，不要从代码仓库中随机选取图片，不要运行转换工具。
清晰回复用户，例如：「请先上传用作 favicon 的源图片，或提供可访问的图片文件路径（如
public/logo.png
），我才能生成
favicon.ico
。」

Step 1 · Resolve output path

步骤1 · 确定输出路径

Ask or infer where to write
```
favicon.ico
```
(e.g.
```
public/favicon.ico
```
,
```
app/favicon.ico
```
, or site root). Do not overwrite without user confirmation if a file already exists.

询问或推断
```
favicon.ico
```
的写入位置（例如
```
public/favicon.ico
```
、
```
app/favicon.ico
```
或站点根目录）。如果对应路径已存在文件，未经用户确认请勿覆盖。

Step 2 · Generate ICO（不污染用户业务项目）

步骤2 · 生成ICO（不污染用户业务项目）

Goal: only write the user-approved favicon.ico
into their application tree (e.g.

public/favicon.ico

). Do not run

pnpm install

pnpm build

for this CLI in an unrelated app repo root, and do not add

node_modules

, CLI

dist/

, or a copied

tools/create-favicon

tree there unless the user explicitly asks to vendor the tool (then warn about gitignore / lockfiles).

Pick one path in order:

This skills monorepo checkout — If the workspace is (or you can resolve) the repo that already contains
```
tools/create-favicon/package.json
```
(e.g. stark-skills
):
```
cd <absolute-path-to>/tools/create-favicon && pnpm install && pnpm build
```
then run node
with absolute
```
--input
```
and
```
--output
```
(output may point into the user’s app directory).
Disposable build in OS temp — If the user’s open project is only their site/app and does not ship this CLI: clone or copy only
```
tools/create-favicon
```
(and needed files) under $TMPDIR
/
```
%TEMP%
```
/
```
mktemp -d
```
, run
```
pnpm install && pnpm build
```
there, then:
```
node dist/cli.js --input "<absolute source image>" --output "<absolute path in user app>/favicon.ico"
```
Remove the temp tree when done (keep the ICO).
Published runner (if documented) — If this CLI is published as an npx <package>
or global binary in project docs, prefer it so the user’s app directory does not gain a local
```
node_modules
```
for this workflow.
Non-Node fallback — ImageMagick / magick
or another approach that satisfies ICO + three PNG payloads without leaving Node build artifacts in the user’s app; see
```
USAGE.md
```
.

bash

undefined

目标：仅将用户确认的**

favicon.ico

写入其应用目录结构中（例如
public/favicon.ico
）。不要在无关的应用仓库根目录下为运行本CLI执行
pnpm install
/
pnpm build
命令，也不要**在该目录下新增

node_modules

、CLI

dist/

目录或复制的

tools/create-favicon

目录树，除非用户明确要求引入该工具（此时需要提示用户注意gitignore/锁文件的相关问题）。

请按优先级选择一种执行路径：

本技能的monorepo工作区 —— 如果当前工作区是（或你可以定位到）已经包含
```
tools/create-favicon/package.json
```
的仓库（例如 stark-skills
）：
```
cd <absolute-path-to>/tools/create-favicon && pnpm install && pnpm build
```
然后运行**
```
node
```
**命令，传入绝对路径的
```
--input
```
和
```
--output
```
参数（输出路径可以指向用户的应用目录）。
操作系统临时目录下的一次性构建 —— 如果用户打开的项目仅为其站点/应用，且未内置本CLI：仅将
```
tools/create-favicon
```
（及所需文件）克隆或复制到**
```
$TMPDIR
```
** /
```
%TEMP%
```
/
```
mktemp -d
```
目录下，在该目录下执行
```
pnpm install && pnpm build
```
，然后运行：
```
node dist/cli.js --input "<absolute source image>" --output "<absolute path in user app>/favicon.ico"
```
操作完成后删除临时目录（保留生成的ICO文件）。
已发布的运行器（如有文档说明） —— 如果本CLI已作为**
```
npx <package>
```
**或项目文档中说明的全局二进制包发布，优先使用该方式，避免用户的应用目录下因本次操作生成本地
```
node_modules
```
。
非Node fallback方案 —— 使用ImageMagick / **
```
magick
```
**或其他满足「ICO容器内嵌三个PNG资源」要求的方案，且不会在用户应用中留下Node构建产物，详见
```
USAGE.md
```
。

bash

undefined

Example after building CLI in monorepo or temp dir — always use absolute paths.

在monorepo或临时目录构建CLI后的示例 —— 始终使用绝对路径。

Default: --fit contain（整图可见，非方形时透明或白边，不默认裁切）

默认: --fit contain（整图可见，非方形时透明或白边，不默认裁切）

node dist/cli.js --input "<absolute-path-to-source.png>" --output "<absolute-path-to-user-app>/public/favicon.ico"

Only if the user explicitly wants 铺满/裁剪去留白（需确认可能裁掉边缘）:

仅当用户明确要求铺满/裁剪去留白（需确认可能裁掉边缘）时使用:

node dist/cli.js --input "..." --output "..." --fit cover


**Framing（构图）**

- **默认 `contain`**：等比缩放，**整张源图都保留在方形内**，居中；有 alpha 的源图留白为**透明**；无 alpha（如 JPEG）留白为**白色**（要透明边请用 PNG/SVG）。**禁止**在用户未要求时用 `cover` 把图裁成「另一张」。
- **`--fit cover`**：**仅当**用户明确说不要留白、要填满、裁剪铺满等，并**提示可能裁边**后，再传入 CLI 或等效流程。

**Multi-size / scaling（多尺寸与画质）**

- **32 / 48 / 180** 共用 **同一套** `fit`、居中、留白规则；只是像素变多/变少，**不要**让某一档单独换裁切方式。
- 参考 CLI 使用 **Lanczos（lanczos3）** 缩放；若 stderr 出现 **过小位图源** 警告，提醒用户换 **更高分辨率** 或 **SVG**。

The CLI writes a single `favicon.ico` containing **three** embedded **PNG** blobs at **32×32**, **48×48**, and **180×180** (ICO container per Windows icon layout; see references).

**Fallback** — if every CLI path fails:

- Use step **4** or stop and explain what is missing (network for clone, Node, `sharp`, or ImageMagick).

---

node dist/cli.js --input "..." --output "..." --fit cover


**构图**

- **默认使用`contain`模式**：等比缩放，**整张源图都保留在方形画布内**，居中对齐；带alpha通道的源图留白为**透明**；无alpha通道的源图（如JPEG）留白为**白色**（需要透明边请使用PNG/SVG格式）。**禁止**在用户未要求的情况下使用`cover`模式将图片裁切为「另一张图」。
- **`--fit cover`模式**：**仅当**用户明确表示不需要留白、要填满画布、裁剪铺满等需求，且**提示用户可能会裁掉边缘内容**后，再传入CLI或等效流程中使用。

**多尺寸/缩放规则**

- **32 / 48 / 180**三个尺寸共用**同一套**`fit`、居中、留白规则；仅像素大小不同，**不要**为某一个尺寸单独更换裁切方式。
- 参考CLI使用**Lanczos（lanczos3）**算法进行缩放；如果stderr出现**源图分辨率过低**的警告，提醒用户更换**更高分辨率**的图片或**SVG**格式图片。

CLI会生成单个`favicon.ico`文件，内部包含**三个**嵌入的**PNG**资源，分辨率分别为**32×32**、**48×48**和**180×180**（ICO容器符合Windows图标布局规范，详见参考文档）。

**兜底方案** —— 如果所有CLI路径都执行失败：

- 使用步骤4的方案，或停止操作并向用户说明缺失的依赖（克隆所需的网络、Node、`sharp`或ImageMagick）。

---

Step 3 · Quick verification

步骤3 · 快速校验

Confirm file size is non-zero and magic
```
00 00 01 00
```
at offset 0 (ICO), image count
```
03 00
```
at offset 4.
Optionally decode each embedded PNG signature
```
89 50 4E 47
```
at offsets listed in directory entries.

确认文件大小非零，偏移量0处的魔术头为
```
00 00 01 00
```
（ICO格式标识），偏移量4处的图像计数为
```
03 00
```
。
可选操作：校验目录项中列出的偏移量位置的每个嵌入PNG的签名为
```
89 50 4E 47
```
。

Step 4 · Tell the user

步骤4 · 告知用户结果

Output path, the three embedded sizes, framing used（
```
contain
```
= 整图可见 /
```
cover
```
= 可能裁边）, that all three sizes share the same composition（仅分辨率不同）, and high-quality (Lanczos) resize unless another tool path was used. If
```
cover
```
was used, do not imply the icon is pixel-identical to the uncropped source. If a small-source warning appeared, relay it. Mention that iOS 主屏幕 常用独立
```
apple-touch-icon.png
```
；详见
```
references/ico-format-and-browser-notes.md
```
。

说明输出路径、嵌入的三个尺寸、使用的构图模式（
```
contain
```
= 整图可见 /
```
cover
```
= 可能裁边）、三个尺寸仅分辨率不同、构图完全一致，以及使用了高质量Lanczos缩放（如果使用了其他工具则说明对应缩放方式）。如果使用了
```
cover
```
模式，不要暗示生成的图标和未裁剪的源图像素完全一致。如果出现了源图过小的警告，也需要告知用户。可提示iOS主屏幕通常使用独立的
```
apple-touch-icon.png
```
，详见
```
references/ico-format-and-browser-notes.md
```
。