robot-heads - 为 React 应用绘制会表达状态的 3D 机器人头像

robot-heads 是一个面向 React 的机器人头像组件库。它要解决的问题很具体：当 AI agent 在后台思考、检索、说话或出错时，界面上往往只有一个转圈图标或一行文字，用户很难一眼看出它此刻在做什么。robot-heads 把这些状态映射成一颗会动、会变脸的 3D 机器人头像——屏幕上的 LED 矩阵显示不同的眼睛与嘴型，头部姿态、天线灯和整体动作也随之改变。它适合正在做对话式界面、agent 控制台、语音助手或任何需要「让机器有个表情」的前端项目，尤其适合不想引入 WebGL 或重型 3D 依赖的团队。

维护者与状态

项目由 fayazara 维护，仓库创建于 2026-10-09，最后提交时间为 2026-10-10，属于非常年轻的项目。截至 2026-11-06，仓库获得 446 个星标。事实表显示该项目尚无正式 release，也就是说目前没有打出版本号的发行包，使用者需要直接依赖仓库代码或 npm 上的当前发布状态自行确认。许可证为 MIT。

从时间线看，创建与最后提交只相隔一天，说明它更像是一次集中完成的首发，而非长期迭代的产物。对采用者而言，这意味着 API 仍可能变动，遇到问题时也缺少历史版本可回退。

主要能力

以下能力均来自项目自述（README），未经独立验证。

• 九种状态表情。项目导出了 robotHeadStates 列表，包含 idle、thinking、searching、listening、speaking、working、happy、error、sleeping。每种状态有各自的屏幕表情、动作和天线灯颜色：thinking 是半睁眼向上看加三个脉动点、琥珀色灯脉动；searching 是眼睛乱转加扫描光束、青色信标；listening 是警觉眼神配实时均衡器、稳定绿灯；speaking 是随话语开合的嘴；error 是红色 X 眼加摇头；sleeping 是闭眼、飘起的 z 和熄灭的灯。切换状态时会播放短暂的故障闪烁与交叉淡入。
• 四种外形。同一个头部有四种轮廓——经典电视（默认）、舷窗、平顶螺母等，统一导出为 robotHeadShapes。据项目说明，每种外形都保留相同的屏幕、耳朵、天线、螺丝和背板，运动方式也一致。
• 纯 2D canvas 绘制。README 称它不使用 WebGL，也没有运行时依赖。头部是按真实几何构建的：带卷边的外壳、车削出的旋钮耳朵和天线环，每帧做姿态旋转、投影、背面剔除，再用一套小型影棚光照模型着色，包括主光、补光、天空穹顶、柔光箱、菲涅尔清漆反射和冷色轮廓光。
• 交互与可访问性。默认开启 interactive 时，头和眼睛会跟随附近的指针，点击会让它跳起并转一圈、露出开心表情。canvas 带有 role="img" 和形如「Robot, thinking」的 aria-label，可自行覆盖。
• 性能与动效降级。项目自述称页面上所有头像共享一个动画循环，标签页隐藏时循环休眠，同形状同尺寸的头像共享烘焙纹理。在 prefers-reduced-motion: reduce 或传入 paused 时，改为绘制该状态的静止姿态。
• 尺寸与布局。size 定义的是机器人本体所占的方形盒子，跳跃、天线辉光和地面阴影会溢出盒子但不占布局空间，行为类似 CSS 的 box-shadow；只有盒子本身接收点击。小尺寸头像可传 antenna={false} 去掉天线杆与灯，让头部占据更多空间。

使用入口

仓库地址：fayazara/robot-heads。在线演示站点：robot-heads playground。

据 README，安装方式为：

npm install robot-heads

React 18 或更高版本是 peer 依赖。最小用法是引入 RobotHead 组件并传入 status：

import { RobotHead } from 'robot-heads';

function Agent({ status }: { status: 'idle' | 'thinking' | 'speaking' }) {
  return <RobotHead status={status} />;
}

除 status 外，className、style、onClick、aria-label 等属性会透传到元素上，ref 指向内部的 canvas。仓库本身是 pnpm workspace：库在根目录，playground 在 site/，是一个由 Cloudflare Worker 托管的 Vite React 应用，并直接运行库的源码，因此改动会热更新。常用脚本包括 pnpm run dev（启动 playground）、pnpm run build（构建库到 dist/）、pnpm run typecheck 和 pnpm run deploy。

许可与限制

项目采用 MIT 许可证，README 中标注版权归 Fayaz Ahmed。需要注意，playground 使用的 Open Runde 字体由 Laurids Kern 以 SIL Open Font License 1.1 授权，且该字体不包含在 npm 包内，若要把演示站点的排版一并复用，需单独处理字体授权。

已知限制方面，README 明确提到：动画溢出盒子，若父容器设置了 overflow: hidden，跳跃动作会被裁掉；antenna={false} 只适合小尺寸头像，因为去掉天线后方形、圆形和六边形会变大，而宽矩形受宽度限制不再增长。此外，项目尚无正式 release，创建至今仅一天提交记录，API 稳定性与长期维护情况都需要使用者自行评估。项目自述的能力与性能描述均来自维护者，本站未做实际运行验证。