DominikScholz/open-bot-avatar

项目介绍

Open Bot Avatar 把智能体头像定义为一个 0 0 100 100 画布中的 SVG 路径加上眼睛位置，再渲染成有立体感的 SVG 角色。体积由轮廓推断为一组堆叠截面，在 CSS 3D 场景中绘制，需要静态图时则投影成单个 SVG 定义契约、渲染说明。

它提供无依赖的 open-bot-avatar 包，包含浏览器端 mountAvatar 和不需要 DOM 的 SVG 渲染函数。浏览器 编辑器 支持挑选、上色、导入和生成头像，gallery/ 目录存放社区定义 gallery。适合想在智能体聊天界面里加一个小型动画角色的开发者。

快速使用

先安装包：

pnpm add open-bot-avatar

把示例头像挂载到一个正方形元素中：

import { getExample } from "open-bot-avatar";
import { mountAvatar } from "open-bot-avatar/dom";

const avatar = mountAvatar(document.querySelector("#bot")!, {
  definition: getExample("mug")!,
  color: "#ff6a1a",
  followPointer: true,
});

avatar.update({ mood: "happy" });
avatar.destroy();

definition 是必填项；mood 可选 "idle"、"thinking"、"happy"，鼠标/手指跟随默认关闭 挂载选项。不需要 DOM 时，先用 validateAvatar 校验 JSON，再调用 renderAvatarSvg 输出静态 SVG SVG 渲染。

项目没有 React 包，README 给出了用 useEffect 包装 mountAvatar 的组件写法，其他框架可仿照 React 用法。

制作头像

头像定义是 v1 JSON，包含 id、name、body.path 以及眼睛的 x、y、spacing、scale 定义示例。手写定义可用 validateAvatar 校验，返回 { ok: true, value } 或 { ok: false, errors }。

生成新头像时，打开编辑器，在 Generate 下描述形象，把内置系统提示词发给聊天模型或智能体，再把返回的 JSON 粘贴到 Import 制作头像。提示词和技能放在 skills/generate-avatar/ 提示词、技能。

使用约束

构建仓库需要 Node 22.18+ 和 pnpm，测试使用 Vitest 开发说明。mountAvatar 面向浏览器，SVG/frame 系列函数不依赖 DOM。表情和视线只支持上述选项，没有 React 包，框架绑定需从 README 复制。项目以 MIT 许可证发布 许可证。

HotRepo 点评

HotRepo 在 2026-11-03 将该项目收录到 TypeScript 新项目榜，它在约 23 小时的统计窗口内（自 2026-11-02 创建起）获得 102 个 Star 和 13 个 Fork。对一个单用途的小型渲染库来说，首日表现不错，但现有数据只有一个快照，还看不出持续采用情况，也看不出编辑器和画廊长期如何被使用。