Avatar Runtime

核心用法

avatar-runtime 是一套 provider-agnostic 的虚拟人运行时，通过统一 API 控制 Live2D、VRM 3D 及 HeyGen 等云端 avatar。开发者可通过 HTTP REST 接口驱动表情（mouth、eyes）、头部姿态（yaw/pitch/roll）、情绪（valence/arousal）及骨骼动画（VRM-only），并在浏览器中嵌入 AvatarWidget 实现低代码集成。

关键特性：

• 多 provider 支持：内置 mock、Live2D Cubism、VRM（基于 Three.js）、HeyGen streaming、Kusapics 等，切换仅需改环境变量
• 零成本本地 3D：VRM 分支无需 API Key，直接从 VRoid Hub 获取免费模型，本地渲染
• 统一 control 命名空间：face（五官）、emotion（情绪维度）、body（骨骼）、scene（相机/灯光）分域合并，避免全量覆盖
• 浏览器嵌入：单文件 avatar-widget.js，支持 Live2D/VRM/向量回退三种模式，自动轮询状态

快速启动示例：

# VRM 零配置启动
cd packages/avatar-runtime
bash scripts/ensure-default-vrm-sample.sh  # 下载 CC BY 4.0 示例模型
npm run dev:vrm-bridge                     # 资源服务 :3756
AVATAR_PROVIDER=vrm npx avatar-runtime     # 运行时 :3721

显著优点

| 维度 | 评估 |

|------|------|

| **成本** | VRM/mock 完全免费；HeyGen 仅在有需求时付费，且支持 `HEYGEN_STRICT=false` 优雅降级 |

| **灵活性** | 同一套 HTTP API 驱动 2D/3D/云端 avatar，迁移成本低 |

| **控制粒度** | 支持到骨骼级别（VRM）、情绪维度（valence/arousal）、相机 FOV/位置，适合精细动画 |

| **开发体验** | 热重载、mock provider、自动降级策略，本地开发无需网络依赖 |

| **开源合规** | 示例 VRM 模型来自 `@pixiv/three-vrm`（CC BY 4.0），商用友好 |

潜在缺点与局限

• Live2D 授权风险：默认 ensure-default-live2d-sample.sh 下载的 chitose 模型受 Live2D Free Material License 约束，禁止再分发与商用，生产环境必须替换为自有授权模型
• 浏览器性能：VRM 基于 Three.js，移动端或低配置设备可能出现帧率问题；Live2D Cubism Web SDK 需额外加载 vendor 脚本（约 1MB+）
• provider 能力断层：HeyGen 独占 streaming 与 lipSync，VRM 独占 bodyRig/sceneControl，跨 provider 功能需代码分支处理
• API 稳定性：control API 为 v0.2，字段命名（如 valence vs label）尚未完全标准化，升级可能引入 breaking change
• 网络依赖：除 VRM/mock 外，Live2D bridge、HeyGen 均需额外端点或密钥，离线场景受限

适合人群

• AI 陪伴/社交产品：需低成本虚拟形象承载情感交互
• 直播/客服 SaaS：需可嵌入的 talking head，且要求自建渲染链路（隐私合规）
• 虚拟偶像运营：已有 VRM 模型，需程序化驱动表情与动作
• 原型验证团队：mock provider 支持零配置 demo，快速验证交互流程

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 许可证违规（Live2D） | 高 | 误将 `chitose` 部署到生产即构成违约，需法务审核替代模型 |

| 模型文件泄露 | 中 | VRM/Live2D 模型存储于 `assets/` 目录，若静态服务配置不当可被直接下载 |

| 运行时注入 | 中 | 控制 API 接收任意 JSON，需校验 `skeleton` 数值范围防畸形数据导致渲染异常 |

| 依赖供应链 | 低 | `three-vrm`、`live2d-widget-model-*` 等包若被篡改，将影响渲染安全 |

| 降级误导 | 低 | `HEYGEN_STRICT=false` 自动回退 mock，用户可能误以为真机服务正常 |

建议：生产部署前移除所有 sample 脚本，启用 CORS 白名单，并对 /v1/control 增加 JSON Schema 校验。