page-mascot

Mascot

将“在我的页面上放只狐狸”或“给我画只 Q 版水獭”变成可用的 <Mascot />。

每个角色由两张 3×3 精灵图组成：九个头部朝向和九种表情。 组件通过移动 background-position 在两张图之间切换，因此无需逐帧编写 JavaScript，也不需要动画库。一个角色就是它的两个文件——没有注册表， 也不需要任何东西知道它的名字。

选择哪条路线

• 用户指定了角色，或愿意使用已有角色——使用现有角色。无需 Python 或 API 密钥， 可在任何 React 项目中使用。这是最常见的情况。
• 用户想要全新的角色，或想使用自己的形象——绘制新角色，然后 完成放到页面上。

两条路线最终都要放到页面上。不要只交付文件和代码片段就停下。

使用现有角色

1. 挑选。 reference/characters.md 列出了 52 个角色。如果用户没有指定， 就挑选一个适合网站的角色，并说明你选了哪个以及原因。

2. 将两张精灵图下载到项目用于提供静态文件的位置——Next、Vite、CRA 和 Astro 使用 public/，SvelteKit 使用 static/——或者放在组件旁边并导入：

   mkdir -p public/mascots
   curl -fsSL -o public/mascots/fox-directions.webp https://koboyo.com/page-mascot/mascots/fox-directions.webp
   curl -fsSL -o public/mascots/fox-reactions.webp  https://koboyo.com/page-mascot/mascots/fox-reactions.webp
   

3. 放到页面上（见下文）。

放到页面上

安装组件。 根据锁文件使用相应的包管理器： npm i page-mascot、pnpm add page-mascot、yarn add page-mascot 或 bun add page-mascot。如果这不是由包管理器管理的 React 项目，就从这个 SKILL.md 旁边复制 mascot.tsx 到项目中——它只有一个文件，只需要 React， 并使用内联样式。

渲染它：

import { Mascot } from 'page-mascot'

<Mascot
  directions="/mascots/fox-directions.webp"
  reactions="/mascots/fox-reactions.webp"
/>

directions 和 reactions 是两张精灵图的服务路径，也可以是导入的图片。 两者都是必填项。其他属性包括 size（默认值为 140）、label（屏幕阅读器 对它的称呼）和 className。

放到用户指定的位置。 如果用户没有说明，就放在页面顶部——页眉或 主视觉区域、标题上方或旁边。能注视光标的头部在这里效果最好。 编辑实际组件，然后告诉用户你改了什么以及改在了哪里。

绘制新角色

首先，确定绘制方式

每个角色都需要绘制两张图，不同 Agent 是否能自行完成绘制也各不相同。请按以下顺序检查：

1. 你有内置的图像生成工具（Codex 就有）。直接使用它——按照下方的自行绘制操作。先确认它能否返回透明背景，因为这决定了你要发送哪种提示词：如果支持透明背景，就要求使用透明背景并启用该选项；如果不支持，就使用纯色键控背景绘制，之后再移除背景。两种方式都在透明度部分有说明。
2. 已设置 OPENAI_API_KEY。 使用 API 方式，无需任何图像工具——按照通过 API 绘制操作。Claude Code 没有图像工具，因此应使用此方式。generate.py 会通过 API 的 background 参数请求透明背景；如果返回的图像没有 alpha 通道，它会自动改用键控背景方式。
3. 两者都没有。 明确说明绘制需要能生成图像的 Agent 或 OPENAI_API_KEY，并提供两种替代方案：使用五十二个已绘制角色之一（使用已绘制的角色），或使用 reference/prompts.md 中的手动方式，由用户自行将提示词粘贴到聊天界面中。不要尝试通过浏览器驱动网页界面来绕过限制：这种方式取决于页面标记，需要登录会话，而且一组任务还没完成就会遭遇速率限制。

无论使用哪种方式，构建都需要 Python 3：

python3 -c "import PIL, numpy, scipy" 2>&1

如果失败：pip install -r <skill-dir>/scripts/requirements.txt。请停止并说明情况，不要尝试绕过。

下文中的 <skill-dir> 均指存放此 SKILL.md 的文件夹——该技能通常安装在项目之外，因此请使用其完整路径。所有命令都必须从项目根目录运行：脚本会从 characters/<name>/ 读取源图，并将构建好的图集写入当前目录下的 public/mascots/。如果 public/ 不是此项目提供静态文件的位置，请传入 --dest static/mascots（或相应目录）。

通过 API 绘制

一条命令即可生成、筛选、构建、验证并重试：

python3 <skill-dir>/scripts/mascot.py fox --describe "a chibi fox with warm orange fur, a cream muzzle and dark ear tips"

添加 --style riso 可使用不同风格；添加 --reference ~/photo.jpg 可重新绘制某个人物。--only reactions 只会重新绘制表情图，并保留动作图。如果模型没有返回 alpha 通道，脚本会在纯色键控背景上重新绘制该图，然后移除背景，这会额外消耗一次图像生成；使用 --key green 可从一开始就强制采用此方式。除了上述软件包，还需要 pip install openai。图像模型在 generate.py 中固定；设置 MASCOT_IMAGE_MODEL 可使用其他模型。

自行绘制

1. 绘制动作图。 使用你的图像生成工具，将角色描述替换到 reference/prompts.md 中的 DIRECTIONS 提示词里。如果工具无法返回透明背景，就改用该提示词的键控背景版本，并关闭相应选项——参见下方的透明度，两张图都使用相同版本。将图像保存到 characters/<name>/directions.png。

2. 绘制表情图。 使用 EXPRESSIONS 提示词，并将刚绘制的动作图作为参考图像传入。将图像保存到 characters/<name>/reactions.png。

3. 构建并验证。

python3 <skill-dir>/scripts/mascot.py <name> --skip-generate

4. 按照结果处理。 操作要么完成并告知你角色已就绪，要么指出两张图中哪张有问题。重新绘制有问题的那张图，然后再次运行第 3 步。最多尝试两次；之后请修改角色描述——再继续下去，问题就出在图稿上，而不是构建过程。

请自行运行命令，不要把命令打印出来让用户复制。

检查头部转向是否正确

这些脚本会测量所有内容，但不会检查角色实际看向哪个方向。 交付角色前，裁剪方向图中的 left 单元格（中间行，第一列）和 right 单元格（中间行，第三列），并检查它们：左侧的角色必须朝向画面左侧。

有时返回的图像会是镜像的，在所有检查中都得分完美，但角色却背对着页面上的光标。不要重新生成——美术本身没问题，只是单元格顺序错了。reference/design-rules.md 中的三行列交换代码可以修正它。

透明度是最容易出问题的地方

图集最终必须是带有真实 Alpha 通道的 PNG，而提示词无法让你得到这样的图像。透明度是图像调用的设置——OpenAI API 中的 background: "transparent"，或内置工具中的等效选项——并不是模型会因为收到文字要求就自动实现的功能。在 gpt-image-2.5 上对十五张图集进行测量后发现：设置该选项时，无论提示词是否提到透明度，每张图集都带有真实 Alpha 通道；不设置时，每张图集都是不透明的，角色背后还绘制了灰白棋盘格。即使提示词用大写字母要求“PNG WITH A REAL ALPHA CHANNEL... not white”也一样。模型无法输出 Alpha 通道时，就会绘制代表它的图案。

因此有两种提示词，你该用哪一种取决于工具，而不是角色：

• 工具可以返回透明背景。 设置该选项，并按原样使用 reference/prompts.md 中的提示词。

• 工具无法返回透明背景。 此时绝不能要求透明度，因为这会引来棋盘格——棋盘格无法补救，它的方格会延伸到角色边缘之下。改为发送提示词的色键变体（reference/prompts.md 中的 Drawing without transparency）：它要求使用纯绿色背景，完全不提透明度。然后移除绿色：

  python3 <skill-dir>/scripts/key.py characters/<name>/directions.png --in-place
  

  mascot.py 检测到图集使用纯色键颜色背景时会自动处理，因此通常只需运行构建流程即可。

两边都考虑并不可行。提示词既要求透明度，又补充“如果无法实现就用绿色”，结果仍然会得到棋盘格。两种提示词互为替代，绝不能合并使用。

screen.py 会标明你遇到的是哪种情况：

输出内容	实际情况	应采取的操作
alpha: ok	带有真实 Alpha 通道	无需处理
alpha: MISSING (solid #02F902 background -- key.py can remove it)	绘制在色键颜色背景上	抠除色键，或让 mascot.py 处理
alpha: MISSING (painted checkerboard, 32px squares -- redraw)	要求透明度，但工具无法实现	使用适合该工具的提示词重新绘制
alpha: MISSING (opaque background)	图像被扁平化到白色背景或场景中	重新绘制；无法抠除任何内容

最后两种情况无法修复。白色背景不能用作色键，因为角色自身的米色和白色区域也会一并被抠除。这也是为什么色键颜色要用饱和绿色，而绝不能用白色、灰色或黑色。

编写描述

这决定了结果的好坏，所以请花一句话描述，而不是直接照搬用户的用词。“狐狸”不如“一只可爱的 Q 版狐狸，长着暖橙色的毛、奶油色的口鼻部和深色的耳尖”效果好。用一句话说清颜色和两三个显著特征。

避免以下情况，因为它们都会破坏这种效果所依赖的对齐：

• 披散在肩上的长发。 把头发扎起来或藏在帽子下面。每张图的画法都会不同，点击时吉祥物就会晃动。这是最常见的问题，远超其他情况。
• 任何比头部更宽的东西——比如大翅膀、宽大的头饰。它们会被单元格边缘裁掉。
• 手持道具。 手杖、马克杯、乐器等。画面只展示头部和肩部。

不错的示例：a chibi robot with a mint-green boxy head and a single wide visor screen、a chibi grandmother with silver hair in a neat bun and round gold spectacles。

使用其他风格绘制

有六种风格可选：colour（默认）、ink、sketch、riso、paper 和 pixel。 它们只会改变角色的绘制方式——画面取景、比例、复用的身体和边距都是共用的，因此风格不会破坏对齐。

reference/prompts.md 中有每种风格对应的段落。将该段落替换到这个角色的两个提示词中，并在 EXPRESSIONS 提示词中再次注明风格，以免第二张图又回到默认风格。通过 API 调用时，它是一个标志：

python3 <skill-dir>/scripts/mascot.py fox --style riso --describe "a chibi fox with orange fur"

同一个角色的两张图必须使用相同风格。reference/prompts.md 底部列出了 ink、sketch 和 pixel 的注意事项——使用这三种风格前请先阅读。

使用用户自己的图片

流程相同，但在步骤 1 中，将用户的图片和 reference/prompts.md 中的 REFERENCE 提示词一起传给图像工具。它会按照流水线所需的风格，将用户的角色重新绘制成动作方向图。步骤 2 及之后的流程不变。

完成之后

生成的图集会保存到 public/mascots/<name>-{directions,reactions}.webp（或 --dest 指定的位置）。 源图会保留在 characters/<name>/ 中，方便之后重新构建角色而无需重新绘制；请告知用户这一点，并由用户决定是否保留或删除这些图片。

然后将它放到页面上。

批量制作

一次制作一个，并在过程中汇报进度。

深入了解

reference/design-rules.md 解释了每条美术规则的原因、各种失败情况的表现，以及两张图如何匹配。如果角色出现脚本提示未涵盖的问题，请阅读此文档。