page-mascot

Page Mascot 是由开发者 Kamran Ahmed 发起并持续维护的开源交互式网页吉祥物组件与 Agent Skill，核心定位是“为任何 React 页面装上一个会跟着光标转头、被点击时会眨眼反应的 Q 版小角色”——它不满足于做一份简单的静态图标或装饰性图片，而是将52 个预绘制角色、6 种视觉风格、光标追踪机制、点击反应系统、3×3 精灵图零动画库架构、Agent 自动绘图技能等核心能力整合于一套极简的开源工具中，全部配有 npm i page-mascot 一键安装、npx skills add 一行安装 Agent Skill、MIT 开源协议，以及一个可预览全部角色的在线演示页。

一、Page Mascot 是什么

Page Mascot 采用“React 组件 + 精灵图 + Agent 技能”三位一体的极简架构，通过 GitHub 完全开源发布，采用 MIT 许可证。项目由 Kamran Ahmed 发起并持续维护。组件已发布到 npm，可直接通过 npm i page-mascot 安装使用。同时，项目也提供了一套 Agent Skill——安装后，AI 编码代理可以直接理解并执行“把狐狸放到我的页面上”或“画一个巧克力棕色毛皮的水獭”这样的自然语言指令。

Page Mascot 的运作机制与市面常见的“网页装饰元素”或“动画库”有本质区别。它不是一个需要加载动画引擎或逐帧绘制 JavaScript 的复杂系统，而是一套基于精灵图位置切换的零开销交互组件。每个角色本质上就是两个文件——两张 3×3 的精灵图，分别存放九个头部朝向和九种表情。React 组件通过监听指针的角度来选择朝向图中的对应格子，并设有一个死区——当光标靠近角色中心时，头部会稳定下来不再频繁转动。点击时，组件会从反应图中显示一个表情格子，持续半秒。整个切换过程通过移动 background-position 实现，没有逐帧 JavaScript，没有动画库。每个角色就是它的两个文件——没有注册表，组件不需要知道角色的名字。

二、Page Mascot 能做什么

Page Mascot 的核心能力可以精炼地概括为：选、装、追、反、绘，围绕这五大维度提供了从角色选择到自定义绘制的完整路径，覆盖网页交互角色使用的全方位需求，具体包括：

52 个预绘制角色的开箱即用（选） ——不是“只能自己画”，而是“从 52 个已绘制角色中直接挑选”。项目内置了 52 个已完成绘制的角色，分为三大类：动物（熊、兔子、猫、鹿、恐龙、狐狸、青蛙、仓鼠、刺猬、考拉、水獭、猫头鹰、熊猫、企鹅、巴哥犬、浣熊、小熊猫、绵羊、树懒、老虎）、人物（爆炸头、宇航员、光头、芭蕾舞者、胡子、建筑工、鸭舌帽、厨师、眼镜、爷爷、奶奶、戴头巾者、护士、海盗、科学家、锡克教徒、滑板者、巫师）、机器人与物件（发条机器人、CRT 显示器、方块、无人机、齿轮机器人、骑士、灯笼、邮差机器人、收音机、火箭、侦察兵、烤面包机、电视机）。对于个人网站，动物和物件是安全默认选项；人物角色适用于用户想要一个“人”但不是自己的场景。

React 组件一键安装与灵活配置（装） ——不是“需要复杂配置”，而是“一行安装，两个属性即可运行”。组件支持 npm、pnpm、yarn、bun 四种包管理器。核心属性只有两个：directions（朝向图路径）和 reactions（反应图路径）——两者均为必填。其他可选属性包括 size（默认 140px 的正方形）、label（屏幕阅读器名称，默认 'mascot'）和 className。对于非包管理的 React 项目，可以直接将 mascot.tsx 单文件复制到项目中——它只需要 React，使用内联样式。追踪功能在没有精确指针的设备上自动关闭；点击时的挤压效果会尊重 prefers-reduced-motion 偏好。

光标追踪与点击反应机制（追/反） ——不是“随机动画”，而是“有逻辑的交互反馈”。角色通过计算指针角度来选择朝向图中的格子。死区设计确保当光标靠近角色中心时头部稳定下来，不会出现“抖动”感。点击时，组件显示反应图中的一个表情格子，持续半秒后恢复。这种“追踪+反应”的组合，让角色从“静态装饰”升级为“有生命感的交互伙伴”。

六种视觉风格的灵活切换（绘） ——不是“一种画风走到底”，而是“同一角色支持六种绘制风格”。每个角色都可以在 colour（默认）、ink、sketch、riso、paper、pixel 六种风格中绘制。只有渲染方式改变，对齐保持不变——因为构图、比例、复用身体和边距在所有风格中共享，风格无法破坏对齐。狐狸目前已经绘制了全部六种风格（fox-ink、fox-sketch、fox-riso、fox-paper、fox-pixel）。

Agent Skill 自动绘制新角色（绘） ——不是“只能从 52 个中选”，而是“让 AI 代理帮你画一个全新的”。安装技能后（npx skills add nilbuild/page-mascot --skill page-mascot --global --yes），用户可以对代理说出像 /page-mascot a chibi otter with chocolate-brown fur 或 /page-mascot make one that looks like me [attach a photo] 这样的指令。代理会自动绘制九方向和九表情，构建为两张对齐的精灵图，检查角色在两张图之间不会跳动，并将组件放到用户的页面上。绘制需要图像工具——Codex 自带图像生成能力；Claude Code 通过 OpenAI 图像 API（需设置 OPENAI_API_KEY）实现。

三、Page Mascot 适合谁用

Page Mascot 的内容设计使其适配各类希望通过一个轻量交互元素提升网页个性与体验的开发者与创作者，核心聚焦那些“想让个人网站或产品页面多一点温度、多一点‘活人感’”，希望从“静态装饰”升级为“有生命感的交互角色”的人群，主要涵盖以下几类：

个人网站与作品集创作者——希望自己的个人主页或作品集有一点点“不一样”的东西。Page Mascot 的 52 个角色和六种风格，让创作者可以挑选一个与个人风格匹配的角色放在页头或 Hero 区域——这正是“一个会看光标的小脑袋读起来最舒服的位置”。

独立开发者与 SaaS 产品团队——希望在产品页面中增加一个轻量的交互元素，让产品“有性格”。Page Mascot 的组件极其轻量——没有动画库、没有逐帧 JavaScript——不会影响页面性能。

AI 编码代理的重度使用者——已经在用 Claude Code、Codex 等 Agent 进行日常开发。Page Mascot 的 Agent Skill 让“在对话中给页面加一个角色”成为原生体验，甚至可以基于用户照片绘制一个“像自己”的角色。

React 生态开发者——项目完全基于 React，可以直接集成到 Next.js、Vite、CRA、Astro、SvelteKit 等主流框架中。对于非包管理的 React 项目，单文件复制即可使用。

希望从“装饰性图标”升级为“有生命感的交互角色”的设计师——不满足于使用静态 SVG 或 GIF，希望页面元素能够对用户行为做出反应。Page Mascot 的光标追踪和点击反应机制，提供了一种“活着的”视觉反馈。

四、Page Mascot 的应用场景是什么

基于其内容设计与定位，Page Mascot 的应用场景主要围绕个人网站个性化、产品页面交互增强、AI 代理自动网页定制和快速原型验证，覆盖从个人创作到团队产品的多个场景，具体包括：

个人网站与作品集个性化场景——开发者在个人网站页头放一个跟着光标转头的狐狸或猫头鹰。访客移动鼠标时角色会转头看向光标，点击时角色会眨眼或做出反应——这是“一个会看光标的小脑袋读起来最舒服的位置”。

产品页面与品牌形象增强场景——SaaS 产品在登录页或仪表盘页面放置一个与品牌调性匹配的角色。Page Mascot 的六种风格（colour、ink、sketch、riso、paper、pixel）让团队可以根据品牌视觉语言选择最合适的风格。

AI 代理自动网页定制场景——用户对 Claude Code 说“把狐狸放到我的页面上”或“画一个巧克力棕色毛皮的水獭”，Agent 自动完成角色选择、文件下载、组件安装和渲染。这种“对话即定制”的能力，让网页个性化从“手动配置”升级为“自然语言驱动”。

基于照片的个人化角色生成场景——用户上传自己的照片，Agent 通过 REFERENCE 提示词将其重绘为一个 Q 版角色。这种“让自己出现在页面上”的能力，为个人网站和社交场景提供了一种新颖的表达方式。

快速原型与创意验证场景——设计师或开发者想快速验证“页面加一个交互角色”的效果是否合适。Page Mascot 的 npm 安装和单文件复制两种路径，让验证可以在几分钟内完成。

五、Page Mascot 为什么值得关注

Page Mascot 之所以值得关注，核心在于它将“网页交互角色从复杂的动画库或高成本的定制绘制，降维为两个精灵图 + 一个轻量 React 组件 + 一个 Agent 技能”，并具备“52 角色 × 6 风格、零动画库架构、Agent 自动绘制、MIT 开源”的独特价值，具体体现在以下几点：

从“动画库依赖”到“背景图切换”的极致轻量化。大多数网页交互动画依赖动画库或逐帧 JavaScript。Page Mascot 的切换机制极其简单——移动 background-position。没有动画库，没有逐帧 JavaScript，没有性能开销。这种“用最少的代码做最多的事”的设计哲学，是 Page Mascot 区别于所有动画方案最核心的价值。

从“静态装饰”到“有生命感的交互”的体验升级。大多数网页上的角色是静态的图标或预录的 GIF。Page Mascot 的角色会跟着光标转头，会在被点击时做出反应。这种“它在看我”的微妙交互，让网页从“一张纸”变成了“一个有生命感的房间”。

从“52 个预设”到“Agent 自动绘制”的能力扩展。Page Mascot 提供了 52 个预绘制角色供直接使用，但它更大的价值在于Agent 可以绘制全新的角色。用户可以描述想要的角色（“一个巧克力棕色毛皮的水獭”），甚至上传自己的照片，Agent 自动完成九方向九表情的绘制、两张精灵图的对齐构建和组件的渲染。这种“从选角色到画角色”的跃迁，让 Page Mascot 从“素材库”升级为“角色生成器”。

“每个角色就是两个文件”的极简架构。Page Mascot 没有角色注册表，没有配置文件，没有复杂的路由逻辑。一个角色就是两张 WebP 图片。组件只需要知道这两个文件的路径。这种“文件即角色”的极简设计，让添加、删除、替换角色变得极其简单——你甚至不需要“配置”任何东西。

六种风格的对齐保证。同一角色的六种风格（colour、ink、sketch、riso、paper、pixel）共享构图、比例、复用身体和边距——只有渲染方式改变，对齐保持不变。这意味着你可以放心地切换风格，而不用担心角色在不同风格之间“跳来跳去”。

Agent Skill 原生支持。Page Mascot 不是“需要手动集成”的组件，而是Agent 原生支持的技能。安装技能后，Claude Code 或 Codex 可以理解“把狐狸放到我的页面上”或“画一个像我的角色”这样的自然语言指令，并自动完成全部工作。

现实挑战与生态成熟度。Page Mascot 并非没有短板。首先，组件仅支持 React——Vue、Svelte、Solid 等框架的开发者需要自行移植。其次，绘制新角色需要图像工具——Codex 自带图像生成能力，Claude Code 需要设置 OPENAI_API_KEY，没有图像工具的用户只能从 52 个预绘制角色中选择。再次，项目非常年轻——仓库创建于 2026 年 9 月，首次提交在 2026 年 9 月 14 日，最新提交在 9 月 15 日，生态和文档仍在快速完善中。最后，“绘制”的可靠性依赖于图像生成模型的稳定性——提示词工程和精灵图对齐验证已经做了大量工作，但生成式模型固有的不确定性仍可能导致需要重绘。