代码绘制的网页角色引擎Aora Bot：71个角色、16种脸、3种画风的完整指南

Aora Bot 是一个代码绘制的网页角色引擎：不依赖任何雪碧图或 Lottie 动画文件，每个角色的身体都是代码生成的轮廓，每个表情都是几段可插值的曲线笔画，每一帧动画直接写进 SVG 属性。项目提供 71 个角色、16 种脸、44 种动画状态和三种画风，另有 7 个节日主题共 122 个角色，支持 React、Web Component 与头像接口。

什么是"代码绘制"的角色引擎

传统做法是设计师画一张静态图 + 一段 Lottie 动画，角色数量受美术产能限制。Aora Bot 反其道而行：

• 身体：一条闭合轮廓（外加耳朵、叶子、天线等可选配件），注册时自动推导脸部位置、半径、形变参数
• 表情：每个状态由眼型、嘴型、腮红几组数字描述，靠弹簧插值平滑过渡
• 动画：所有连续量都是阻尼弹簧，以固定 120 Hz 子步积分，60 Hz 与 144 Hz 显示器收敛到同一结果

整套引擎分四层，依赖只能向上指：

包	作用
@aora-bot/engine	纯 TypeScript 核心引擎：几何、弹簧积分器、状态机、画风系列、情绪协议。不依赖 React 与 DOM
@aora-bot/element	不依赖 React 的 <aora-bot> Web Component，一行 CDN 脚本即可引入
@aora-bot/react	React 组件层：角色、头像、选择器、HUD、智能体状态等
@aora-bot/surfaces	建立在 React 层之上的产品面：引导页、受限场景、模板发布、占用列表

层间契约与目录约定完整写在 ARCHITECTURE.md，想深入源码前值得先读一遍。

71 个原创角色：阵容是怎么组成的

71 个角色按家族分组：圆滚滚的团子、年糕（mochi 是默认形状），水果、美食、小动物、物件、人物直到煤球，打头的是表情馆延续下来的奶白色小圆球 dot。

每个角色在引擎里就是一份"图纸"，存放在 packages/engine/src/shapes/characters/，按家族一个文件：

• 身体：一条闭合轮廓，稠密轮廓会先采样成 96 点环，再用 Catmull-Rom 样条平滑重建
• 脸的位置：身体质量中心不在包围盒中心时（比如带耳朵的角色），图纸给出脸部应该放哪
• 配件：耳朵、叶子、天线不进主环，换形状时旧配件淡出、新配件淡入，形变过程中不会突然消失

一个很实用的特性：任意字符串都能哈希成稳定的形状与墨色。也就是说，你可以给每个用户分配一个固定角色，而不用存储任何数据——邮箱 [e-mail] 永远是同一个角色。完整的角色清单见 形状阵容。

16 种脸 × 44 种动画状态

16 种脸 = 3 种基础脸 + 13 种手绘脸：

face	画法
cute（默认）	圆点眼、小嘴、粉色腮红，涂在身体上
eyes	两只大眼睛，剩下的交给轮廓
line	眼睛之外加鼻子和嘴，全部同一线宽的笔画
手绘脸 ×13	胶囊眼、浓眉眼、水汪眼、墨镜脸、屏幕脸、符号眼……每种脸在每个画风里都有自己的画法

44 种动画状态分四组（名单见 packages/engine/src/motion/states.ts）：

• 🛌 静息（6 种）：idle、sleeping、drowsy、bored、waking、powering-down
• ⚙️ 处理中（19 种）：thinking、searching、loading、progress、radar、writing 等，覆盖 AI 与工具类的真实工作流
• 💖 情绪（16 种）：happy、excited、celebrate、shy、angry、surprised 等
• 🚨 信号（3 种）：alerting、notifying、refusing

最妙的是 idle：由三个频率互不相关的正弦波驱动，周期永远对不齐，角色在侧边栏里待十分钟也像活的，而不是一段循环 GIF。状态与表情的完整对照见 状态总表 和 五官。

3 种画风：22 种画法一键切换

画风用 styleId 选，每个画风有自己的变体，用 variant 选，且运行中切换不会跳变：

系列	变体
vector	16 种：solid、outline、glass、sticker、paper、soft、riso、pencil、marker、crayon、watercolor、neon、chalk、origami、relief、gothic
pixel	3 种：crisp（实心方块）、dot（圆点 LED）、block（带缝方块）
kaomoji	2 种：plain（纯颜文字）、bubble（衬一块淡墨色胶囊）

同一个状态、同一个表情在每个系列里都存在，新增状态时所有系列自动获得；风格参数只影响"画法"不影响模拟——同一个 seed 在不同系列里眨眼时机完全相同。三种画风的细节页：vector、pixel、kaomoji。

7 个节日主题：122 个角色全阵容

七个节日与季节主题各带一套角色、皮肤和签名动作：

• halloween 万圣节 · christmas 圣诞节 · spring-festival 春节
• mid-autumn 中秋 · easter 复活节 · summer 夏日 · valentine 情人节

每个主题都是独立入口（@aora-bot/engine/themes/<id>），用到时才加载，不会增加主包体积。主题角色与主阵容互不干扰，例如中秋有月饼 ma-mooncake 和玉兔 ma-rabbit，夏日有椰子 sm-coconut 和游泳圈 sm-ring。

快速上手：五分钟加一个角色

一键安装

组件层需要 React 19：

pnpm add @aora-bot/react

第一个角色

import { CharacterMark } from '@aora-bot/react';
import '@aora-bot/react/styles.css';

<CharacterMark shape="mochi" state="happy" sizePx={96} />;

三个 prop 承载了绝大部分含义，都有默认值：shape（画哪个角色）、color（配色）、state（在做什么）。想换画风加 styleId、variant、face 即可。

不用 React？一行 script 搞定

<script type="module" src="https://cdn.jsdelivr.net/npm/@aora-bot/element"></script>
<aora-bot character="mochi" state="happy" size="96"></aora-bot>

只要一张静态头像

项目自带免费的头像接口：把地址放进 <img>，同一个 id 永远返回同一个角色，不用安装、不用存储、不用注册，还支持 style、state、size、theme 等查询参数。接口部署在海外，中国大陆暂不可用，用 npm 安装、随项目打包的方式不受影响（详见 头像接口文档）。

想看源码

git clone https://gitcode.com/gh_mirrors/ao/aora-bot

仓库结构：packages/engine/（引擎）、packages/element/（Web Component）、packages/react/（React 组件）、packages/surfaces/（产品面）、docs/（文档站）。

把 AI 智能体的"正在做什么"变成一张脸

这是 Aora Bot 最有想象力的部分：一条任何脚本都能发出的数字协议，把 AI 智能体的工作状态实时映射成角色的脸。

消息形状只有一种，所有传输方式通用（HTTP、stdin、postMessage、服务端事件）：

{ "session_id": "s1", "aoraBotId": "32", "tips": "Editing src/app.ts" }

核心机制在 智能体集成文档，仲裁器按四条规则决定角色显示什么：

1. 优先级：出错和拒绝压倒一切（需要人介入），完成压倒进行中，进行中压倒待机
2. 最短停留：一个状态至少占屏 900 ms，一连串工具事件不会让脸闪烁
3. 事件与条件：完成、出错这类一次性编号从不丢弃，排队播放
4. 过期：沉默两分钟的会话被遗忘，后台任务不会永远钉住角色

@aora-bot/engine/agent 是独立入口，不含 DOM 和动画代码，Node 中继里和浏览器里一样能加载；源码见 agent/（normalize、createArbiter、通道与 Claude Code / Cursor 适配器都在里面）。

选型指南：我该装哪个包？

场景	选择
React 应用（绝大多数情况）	@aora-bot/react（自动带上引擎）
普通网页 / 无框架	@aora-bot/element，或一行 CDN 脚本
Node 脚本、CI、智能体中继	@aora-bot/engine（/agent、/static 入口不依赖 DOM）
引导页、受限场景、模板发布等现成产品面	再加 @aora-bot/surfaces
只想要静态头像图片	直接用头像接口

每个包都有自己的 README：engine、element、react、surfaces。

许可与下一步

Aora Bot 源码公开，按 LICENSE 分级授权：个人、学生与教育机构、非营利组织、开源项目以及 3 人以内的团队可以免费商用（产品公开发布时需注明 "Powered by Aora Bot"）；规模更大的公司须取得商业授权，见 LICENSE-COMMERCIAL.md。

装好包只是开始，建议按顺序看这几篇：

1. 开始使用——第一个角色与常用 prop
2. 性能——如何用共享舞台渲染上百个角色
3. 服务端渲染——Next.js 与静态生成
4. 智能体集成——给 AI 助手做"脸"

从 pnpm add 到角色在页面上晃动，只需要三分钟；而 71 个角色、16 种脸、44 种状态和 22 种画法，够你的界面用很久。