XiaoMate 更新：一只桌宠，同时支持 Live2D 与 VRM/GLB等3D模型

更新周期：2026 年 9 月 26 日

当前版本：v2.0.7

前言

这段时间，XiaoMate 的更新重点只有一个：把桌宠的 3D 能力真正补齐，并让模型切换和动画播放变得稳定。

此前，XiaoMate 已经具备 Live2D 和 VRM 的基础加载能力，但在实际使用中仍然存在一些明显问题：Live2D 与 3D 模型来回切换时容易出现画面残留，播放 VRMA 或 FBX 动画后偶尔会停在 T-pose，模型尺寸和目录配置也缺少统一处理。

经过这几轮重构和修复，现在 XiaoMate 可以在同一个应用中加载并切换：

Live2D 模型
VRM 模型
GLB 模型
GLTF 模型

除了模型能力本身，本次还加入了透明区域点击穿透，将设置界面拆分为独立窗口，并修复了动画缓存、随机播放、默认模型路径和内存增长等问题。

下面是一次完整更新说明。

号外：项目正式更名为 XiaoMate

有朋友提到，Charlotty 这个名字相对偏向女性角色，而 XiaoMate 不限定角色性别：它既可以承载女性角色，也可以承载男性角色或宠物角色，因此项目名称调整为更加中性的 XiaoMate。

改名后的仓库地址如下：

前端仓库（桌面客户端）：https://github.com/oddmeta/xiaomate-desktop
后端仓库：https://github.com/oddmeta/xiaomate

“小美同学”仍然保留为桌宠和快捷方式的名称。

快速开始

本次暂时只提供 Windows 绿色便携包：

前端可前往 XiaoMate Desktop v2.0.7 发布页下载；
后端请前往 XiaoMate 后端仓库获取。

两个都是绿色便携包，解压后，点击目录中的 start.bat 即可运行。

使用前还需要注意：

AI 对话、书签、提醒、自动任务、MCP 技能和通知等在线功能仍然依赖后端；Live2D/3D 模型展示、窗口交互和本地设置不依赖后端。
默认后端地址仅用于演示，服务器配置较低，只建议用于体验界面；运行 Playwright 等复杂任务时大概率会失败。长期使用请自行下载并部署后端，这样数据也可以保存在自己的电脑中。
如果遇到问题，可以添加作者微信：oddmeta；也欢迎关注公众号“奥德元”，一起学习 AI，一起追赶时代。Good good study, day day up。

以下是本次更新的完整列表。

一、重磅升级：Live2D 与 3D 模型同台运行

本次更新的核心，是继续完善 XiaoMate 的双模型架构。

类型	支持格式	动画来源
Live2D	`.model3.json`	模型自带 motion
VRM	`.vrm`	模型动画、VRMA、FBX
glTF	`.glb`、`.gltf`	glTF 内嵌动画或静态展示

1. Live2D 模型

继续使用 PIXI.js 和 Live2D Cubism 4 渲染，支持模型待机动作、点击互动、拖拽和窗口大小调整。

首次启动时，默认加载 Hiyori Live2D 模型：

/models/live2d/Hiyori/Hiyori.model3.json

2. VRM 模型

VRM 模型支持加载模型自身动画，以及项目内置的 VRMA 动画。

同时重新梳理了 FBX 动画的加载与骨骼映射流程，改善了不同来源动画直接作用于 VRM 模型时的姿态问题。

3. GLB 与 GLTF 模型

除 VRM 外，现在也可以直接加载 .glb 和 .gltf 模型。

如果模型文件中包含 glTF 动画，可以直接播放；不包含动画时则作为静态 3D 模型展示。

4. 模型类型自动识别

应用会根据模型扩展名和路径自动选择对应的渲染适配器，不再要求用户手动判断应该使用 Live2D 还是 VRM 加载器。

二、模型切换重构：不再卡住、空白或停留在旧画面

这一版重点处理了 Live2D 与 3D 模型切换时最容易影响体验的几个问题。

1. 模型操作改为顺序执行

此前快速连续切换模型时，新的加载任务可能与旧的销毁、清理任务同时执行，导致状态互相覆盖。

现在模型加载、销毁和类型切换会进入统一队列，按照顺序执行，减少模型切换过程中出现的竞态问题。

2. 自动清理旧画布

Live2D 和 Three.js 使用不同的渲染画布。旧模型销毁不完整时，残留画布可能遮挡新模型，或者把新模型挤出可视区域。

切换模型时，现在会主动清理容器中的旧画布，确保新模型能够正常显示。

3. 修复默认模型路径

统一了开发环境、便携包和安装环境中的模型路径映射。

应用内部使用 /models/... 地址，主进程会自动将其映射到实际的 resources/models 目录。

4. Live2D 与 3D 尺寸同步

切换模型类型后，会按照当前桌宠大小重新加载目标模型，避免 Live2D 使用大尺寸、3D 却使用小尺寸，或者反过来。

5. 自定义模型目录回退

如果配置了自定义模型目录，并且该目录仍然有效，会优先使用自定义目录。

如果目录已被移动或删除，则自动回退到应用自带的 resources/models，避免模型直接无法加载。

三、动画系统更新

1. 修复动画后停在 T-pose

这是本次更新中比较关键的一个问题。

此前，VRM 模型播放 VRMA 或 FBX 动画后，有时会停留在 T-pose，也就是双臂平展的默认姿态。

现在会重新处理动画播放、姿态恢复和后续循环，避免动画结束后模型长期卡在默认姿势。

2. 重构 FBX 与 VRM 骨骼映射

重新梳理了 FBX 动画从加载、获取骨骼、动作重映射到 Three.js AnimationClip 的完整流程。

新版流程增加了：

FBX 资源缓存
动画剪辑缓存
VRM 骨骼重映射
动画淡入和状态恢复
动画资源销毁与复用

这能减少重复加载和重复创建动画剪辑带来的内存增长。

3. 随机动画不再连续重复

VRM 随机播放动画时，现在会排除刚刚播放过的动画，避免短时间内连续两次抽到相同动作。

4. 3D 光照和阴影优化

调整了 3D 场景主光源的位置和阴影计算，使灯光更靠近模型，阴影范围和视觉层次也更加自然。

相关光源参数目前保留在代码中，但暂时不在设置界面展示。

四、交互升级：透明区域可以点击穿透

新增了桌宠透明区域点击穿透功能。

开启后：

点击桌宠周围的透明区域，会直接操作后方的桌面或其他窗口；
点击模型本身时，仍然可以正常触发模型互动；
桌宠窗口不会因为大面积透明区域而一直挡住其他内容。

这项功能特别适合桌宠长期运行时使用。

五、设置界面改为独立窗口

此前设置内容放在桌宠主界面中，模型较多或设置项较多时，操作空间比较有限。

本次更新将设置界面从主界面中拆分出来，使用独立的 settings.html 窗口。

新的设置窗口包含：

网络：后端服务地址
外观：桌宠大小、窗口边框、待机动画
行为：点击穿透、自动走动
模型：扫描和切换内置模型
边缘：边缘行为
系统：开机自启、调试模式

保存设置后，配置会立即同步到桌宠主窗口，模型、大小、朝向和行为设置无需重启应用即可应用。

六、稳定性与资源管理

1. 内存增长修复

清理了模型切换和动画播放过程中重复创建、未及时释放的对象与缓存，降低长时间运行后的内存增长。

2. 模型资源销毁

在切换 Live2D、VRM、GLB 和 GLTF 模型前，会先停止动画并清理旧模型资源，减少旧场景继续占用 GPU 和内存。

3. WebGL 渲染诊断

补充了 WebGL 上下文和渲染状态诊断。当模型不可见或渲染异常时，日志中会提供更明确的信息，方便继续排查。

七、发布与工程更新

1. 项目品牌更新

应用名称和包信息统一调整为 XiaoMate，并将前后端拆分为两个独立仓库：

桌面客户端：https://github.com/oddmeta/xiaomate-desktop
后端服务：https://github.com/oddmeta/xiaomate

桌面客户端的应用 ID 更新为：

com.oddmeta.xiaomate

“小美同学”作为桌宠和安装快捷方式的名称继续保留。

2. 独立设置页纳入构建

打包脚本现在会复制 settings.html，避免发布包中缺失独立设置页面。

构建流程会同时准备：

主桌宠页面
独立设置页面
通知页面
Live2D 与 Three.js 运行库
业务脚本
模型和动画资源
Electron 运行时

3. README 与技术文档更新

同步更新了项目 README，并补充了以下技术资料：

FBX 动画集成说明
VRM 动画 T-pose 问题修复说明
3D 模型制作和动画接入相关素材

八、完整更新列表

日期	更新内容	用户影响
–	新增透明区域点击穿透	桌宠不再遮挡后方窗口操作
–	统一 Live2D 与 3D 模型尺寸	切换模型后大小保持一致
–	自定义模型目录失效时自动回退	目录被删除后仍可继续启动
–	修复动画和场景内存增长	长时间运行更稳定
–	优化 3D 主光源和阴影	3D 模型显示效果更自然
–	随机动画避免连续重复	随机动作变化更自然
–	调试并重构 FBX 动画流程	为 VRM 播放 FBX 动作打下基础
–	设置界面改为独立窗口	设置空间更大，保存后立即同步
–	修复 VRMA/FBX 动画后的 T-pose	动画结束后不再长期僵在默认姿势
–	调整 3D 光源与阴影实现	提升场景稳定性与视觉效果
–	重构模型操作队列	连续切换模型更加稳定
–	清理模型残留画布	修复旧画面遮挡新模型的问题
–	新增 GLB/GLTF 加载	通用 3D 模型可以直接使用
–	修复默认模型和默认路径	Live2D 默认 Hiyori，3D 默认 CC
–	品牌、版本、构建和文档更新	v2.0.7 便携版发布

九、升级说明

1. 旧版用户

建议先退出旧版 XiaoMate，再解压并运行新版本，避免旧窗口或 Electron 进程占用文件。

2. 自定义模型

自定义模型需要保持完整目录结构，并保留模型依赖的纹理、动作、物理和用户数据文件。

如果自定义目录失效，新版会自动回退到内置模型目录。

3. 在线功能

AI 对话、书签、提醒、自动任务、MCP 和通知仍需要 MetaYay 后端。离线状态下，模型展示、窗口交互和本地设置仍可使用。

4. 当前已知限制

FBX 舞蹈动作目前仍在调试，暂不作为完全稳定的功能；
部分复杂 VRM、GLB 或 GLTF 模型的效果会受模型骨骼、动画命名和文件结构影响；
3D 模型自动走动仍需要针对更多模型继续验证和优化。

XiaoMate — 支持 Live2D 与 3D 模型的 Windows 桌面宠物。

桌面客户端：https://github.com/oddmeta/xiaomate-desktop

后端服务：https://github.com/oddmeta/xiaomate

Windows 前端便携版：https://github.com/oddmeta/xiaomate-desktop/releases/tag/v2.0.7

问题反馈微信：oddmeta

公众号：奥德元

前言