🐾 小美同学 – 桌面宠物
Catherine 同学提出要做一个桌宠，然后现在 TA 终于来了。这个桌宠的完整功能运行需要一个后端（https://github.com/catherine-wei/learning-ai ），目前使用的是部署在 99 元/年 阿里云服务器上的，但是这个阿里云服务器配置（2H+2G+2M）太差，跑一些基于playwright 的功能经常会失败（比如：小奥收藏，自动填报工时等），因此后面会再把后端再打一个包，让所有的服务都本地化运行，所有的数据不出你的电脑。
今天只是开一个头，后面再来更详尽的补充介绍一个这个项目。
基于 Electron + Live2D + PIXI.js 的智能桌面宠物应用，支持 Live2D 模型展示、AI 对话、任务管理、技能调用等丰富功能。
项目信息
- 代码仓库： https://github.com/oddmeta/charlotty
- 下载地址： https://github.com/oddmeta/charlotty/releases
- 版本：v1.0.5
绿色免安装包：解压缩出来后，点击 start.bat 即可运行。
✨ 核心功能
🎭 Live2D 模型展示
- 支持 Cubism 4 模型的加载与渲染
- 模型点击互动（TapBody 动画）
- 待机动画自动轮播（9种待机动作）
- 可调节模型大小（大/中/小三档）
- 支持自定义模型目录
- 模型自动朝向翻转（走动时）
🖱️ 窗口交互
- 拖拽移动：拖动桌宠窗口移动位置
- 边缘吸附：拖动至屏幕边缘自动隐藏为小标签
- 悬停预览：鼠标悬停隐藏标签展开预览
- 点击菜单：单击桌宠打开圆盘菜单
- 双击聊天：双击桌宠打开对话窗口
- 系统托盘：支持托盘快捷操作
- 单实例锁定：防止同时运行多个桌宠实例
💬 AI 智能对话
- WebSocket 实时通信
- 流式输出响应
- Markdown 格式支持
- 聊天记录保存与加载
- 底部字幕实时显示
- 支持后端地址动态切换与自动重连
🎯 圆盘菜单
单击桌宠展开的环形菜单，包含以下功能：
- 📑 书签收藏：管理收藏的网页链接
- ⏰ 提醒待办：添加和管理提醒事项（支持公历/农历、重复周期）
- 📋 定时任务：创建一次性或循环定时任务
- ⚡ 技能说明：查看和调用 MCP 工具技能
- ⚙️ 设置：打开设置面板
- 🔑 登录：登录认证（根据登录状态动态显示/隐藏）
- 🚪 退出：退出桌面宠物
- 音效反馈：菜单打开、关闭、悬停、点击均有音效提示
🎵 音效系统
- 基于 Web Audio API 生成，无需外部音频文件
- 菜单打开/关闭音效
- 菜单项悬停/点击音效
- 可调节音量和启用/禁用
📋 任务管理
提醒待办
- 多类别管理（工作、生活、学习等）
- 支持公历/农历日期
- 重复周期设置（一次性/每天/每周/每月/每年）
- 提醒内容可自定义
- 编辑和删除提醒
- 下次提醒时间可手动调整
定时任务
- 一次性任务和循环任务
- 多种频率选项（每天/每周/每月/每年）
- 自定义星期、日期、时间
- 时区支持（UTC、中国标准时间、日本时间、纽约时间）
- 重试机制（最大重试次数、重试间隔、超时设置）
- 通知集成（可选通知方式）
- 任务启用/禁用切换
- 编辑任务配置
🔧 MCP 技能系统
- 从后端获取可用技能列表
- 可视化技能展示（图标+描述）
- 支持多种参数格式（args 列表/JSON Schema）
- 工具调用对话框
- 实时显示调用结果
- 支持参数验证和类型检查
⚙️ 设置系统
网络设置
- 后端服务地址配置（默认
https://x.oddmeta.net） - WebSocket 自动重连
外观设置
- 桌宠大小调节（大/中/小）
- 窗口边框显示
- 待机动画间隔和概率
行为设置
- 自动走来走去功能
- 走动参数配置（空闲时间、最大距离、速度）
- 边缘行为配置（无/隐藏/吸附）
- 调试模式开关
模型管理
- 本地模型扫描和切换
- 远程模型下载
- 自定义模型目录设置
音效设置
- 音效启用/禁用
- 音量调节
🚶 自动走动
- 桌宠自动在屏幕范围内随机移动
- 支持模型朝向自动翻转
- 可配置的移动距离和速度
- 闲时自动触发
🔔 通知系统
- Toast 弹窗通知
- 通知队列管理
- 点击标记已读
- 独立通知窗口
- 桌面级通知（系统通知）
- 通知历史记录
🔐 用户认证
- Electron Session Cookie 管理
- 登录窗口自动检测
- WebSocket 认证连接
- 登录状态自动同步（每30秒刷新）
- 登出功能
📁 项目结构
desktop_pet/
├── main.js # Electron 主进程（HTTP 服务器、窗口管理、IPC 通信）
├── preload.js # 预加载脚本（IPC 桥接）
├── pet.js # 渲染进程主入口（模块初始化、事件绑定）
├── index.html # 主页面（UI 结构、圆盘菜单、面板等）
├── toast.html # 通知窗口页面
├── toast-preload.js # 通知窗口预加载脚本
├── package.json # 项目配置和打包设置
├── .env # 环境变量（调试模式等）
├── start.bat # Windows 快速启动脚本
├── start.vbs # Windows 无窗口启动脚本
├── lib/ # 前端模块
│ ├── pet-common.js # 公共工具模块（API 请求、模板管理）
│ ├── pet-core.js # 核心模块（PIXI、模型加载、拖拽）
│ ├── pet-radial-menu.js # 圆盘菜单
│ ├── pet-chat.js # 聊天对话
│ ├── pet-panels.js # 面板系统（收藏、提醒、任务）
│ ├── pet-settings.js # 设置管理
│ ├── pet-wander.js # 走动功能
│ ├── pet-mcp.js # MCP 技能
│ ├── pet-notifications.js # 通知系统
│ ├── pet-sounds.js # 音效系统
│ ├── pixi.min.js # PIXI.js 渲染引擎
│ ├── pixi5.min.js # PIXI.js 5.x 版本
│ ├── live2dcubismcore.min.js # Live2D Core
│ ├── cubism4.min.js # Cubism 4 支持
│ ├── pixi-live2d-display.min.js # Live2D 显示库
│ ├── marked.min.js # Markdown 解析器
│ └── qwebchannel.js # Qt WebChannel 支持
├── models/ # 内置模型
│ ├── Hiyori/ # Hiyori 模型
│ └── Mao/ # Mao 模型
├── resources/ # 资源文件（图标等）
├── electron/ # Electron 运行时（开发环境）
├── tests/ # 测试文件
├── docs/ # 文档
├── obfuscated/ # 混淆后的代码（发布用）
└── release/ # 打包输出目录🚀 快速开始
环境要求
- Node.js 16+
- npm
- Windows 10/11（推荐）/ macOS / Linux
安装依赖
npm install启动应用
方式一：使用 npm
npm start方式二：使用批处理文件（Windows）
start.bat方式三：无控制台窗口启动（Windows）
start.vbs开启调试模式
在 .env 文件中设置：
DEBUG_MODE=1或在环境变量中设置 DEBUG_MODE=1，启动时会自动打开开发者工具。
🔧 配置说明
配置文件路径
C:\Users\[用户名]\AppData\Roaming\[应用名称]\pet-config.json例如：
C:\Users\Administrator\AppData\Roaming\CharlottyMate\pet-config.json配置项说明
配置文件存储了以下设置：
base_url：后端服务地址（默认https://x.oddmeta.net）customModelsDir：用户自定义模型目录路径currentModelPath：当前使用的模型路径pet_size：桌宠大小（large/medium/small）show_border：是否显示窗口边框idle_interval：待机动画间隔（秒）idle_probability：待机动画触发概率（%）wander_enabled：是否启用自动走动wander_idle_timeout：空闲多久后开始走动（秒）wander_max_distance：走动最大距离（像素）wander_speed：走动速度（毫秒）edge_behavior：边缘行为（none/hide/snap）lastPetPosition：上次桌宠位置debug_enabled：是否启用调试模式
Live2D 模型查找顺序
查找模型文件，优先级：
.model3.json（Cubism 4 模型文件）index.jsonmodel.json
模型目录
默认模型目录路径：
/media/live2d/models/模型文件夹结构示例：
models/
└── Hiyori/
├── Hiyori.model3.json # 模型定义文件
├── Hiyori.moc3 # 模型数据
├── Hiyori.cdi3.json # 画布信息
├── Hiyori.physics3.json # 物理引擎
├── Hiyori.pose3.json # 姿势设置
├── Hiyori.userdata3.json # 用户数据
├── Hiyori.2048/ # 纹理贴图
│ ├── texture_00.png
│ └── texture_01.png
└── motions/ # 动作文件
├── Hiyori_m01.motion3.json
└── ...🎮 使用说明
基本操作
| 操作 | 功能 |
|---|---|
| 拖动桌宠 | 移动位置 |
| 单击桌宠 | 打开圆盘菜单 |
| 双击桌宠 | 打开/关闭聊天窗口 |
| 点击模型身体 | 播放互动动画 |
| 拖至屏幕边缘 | 自动隐藏为标签 |
| 悬停隐藏标签 | 展开预览 |
| 点击隐藏标签 | 恢复显示 |
| ESC 键 | 关闭圆盘菜单/面板 |
圆盘菜单操作
| 菜单项 | 功能 |
|---|---|
| 📑 书签收藏 | 添加和管理收藏链接 |
| ⏰ 提醒待办 | 创建和管理提醒 |
| 📋 定时任务 | 设置定时执行的任务 |
| ⚡ 技能说明 | 查看和调用 MCP 技能 |
| ⚙️ 设置 | 打开设置面板 |
| 🔑 登录 | 登录认证（未登录时显示） |
| 🚪 退出 | 退出应用 |
聊天功能
- 双击桌宠 打开聊天窗口
- 在输入框输入文字，按回车或点击发送按钮发送
- 助手回复以流式输出显示，支持 Markdown 格式
- 回复内容同时显示在底部字幕条
- 点击关闭按钮或再次双击关闭聊天窗口
设置面板
设置面板包含以下分类：
- 网络设置：配置后端服务地址
- 外观设置：调整桌宠大小、窗口边框、待机动画
- 行为设置：配置自动走动、边缘行为、调试模式
- 模型管理：扫描、切换、下载模型
- 音效设置：启用/禁用音效，调节音量
🌐 后端服务
本应用需要配合后端服务使用，后端提供以下 API：
- 用户认证：
/admin/login - 聊天对话：
/api/chat/history/ - WebSocket 实时通信：
/ws/ - 书签收藏：
/api/markit/ - 提醒待办：
/api/reminder/ - 定时任务：
/api/schedule/ - MCP 技能：
/admin/api/mcp/list - 模型管理：
/admin/api/live2d/model/ - 通知系统：
/api/notifications/
后端地址可在设置中配置，默认为 https://x.oddmeta.net。
🛠️ 开发说明
技术栈
- Electron 31：跨平台桌面应用框架
- PIXI.js 5：2D 渲染引擎
- Live2D Cubism 4：2D 模型动画
- pixi-live2d-display：PIXI.js 的 Live2D 插件
- marked.js：Markdown 解析器
- Web Audio API：音效生成
- 内置 HTTP Server：主进程静态文件服务
架构设计
┌─────────────────────────────────────────────┐
│ 主进程 (main.js) │
│ - HTTP 服务器（静态文件服务） │
│ - 窗口管理（透明无边框窗口） │
│ - 边缘吸附动画 │
│ - IPC 通信处理 │
│ - Cookie 管理 │
│ - 模型下载与解压 │
│ - Toast 通知窗口 │
│ - 系统托盘 │
│ - 单实例锁定 │
└──────────────────┬──────────────────────────┘
│ IPC
┌──────────────────┴──────────────────────────┐
│ 预加载脚本 (preload.js) │
│ - 安全桥接（contextIsolation） │
│ - window.petAPI 暴露 │
└──────────────────┬──────────────────────────┘
│
┌──────────────────┴──────────────────────────┐
│ 渲染进程 (pet.js) │
│ ┌────────────────────────────────────┐ │
│ │ PetCore (核心) │ │
│ │ - PIXI 初始化 │ │
│ │ - Live2D 模型加载 │ │
│ │ - 拖拽交互 │ │
│ └────────────────────────────────────┘ │
│ ┌────────────────────────────────────┐ │
│ │ 功能模块 │ │
│ │ - PetRadialMenu (圆盘菜单) │ │
│ │ - PetChat (聊天对话) │ │
│ │ - PetPanels (面板系统) │ │
│ │ - PetSettings (设置管理) │ │
│ │ - PetWander (走动功能) │ │
│ │ - PetMCP (技能系统) │ │
│ │ - PetNotifications (通知) │ │
│ │ - PetSounds (音效系统) │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────┘模块说明
| 模块 | 文件 | 职责 |
|---|---|---|
| 核心模块 | pet-core.js | PIXI 初始化、Live2D 模型加载、动画控制、窗口拖拽 |
| 圆盘菜单 | pet-radial-menu.js | 环形菜单的显示、隐藏、事件处理 |
| 聊天对话 | pet-chat.js | WebSocket 通信、消息收发、流式输出、字幕显示 |
| 面板系统 | pet-panels.js | 通用面板、收藏、提醒、任务管理 |
| 设置管理 | pet-settings.js | 设置面板 UI、设置读写 |
| 走动功能 | pet-wander.js | 自动走动、边缘隐藏/恢复 |
| MCP 技能 | pet-mcp.js | 技能列表、工具调用 |
| 通知系统 | pet-notifications.js | 通知接收、Toast 显示 |
| 音效系统 | pet-sounds.js | Web Audio API 音效生成 |
| 公共模块 | pet-common.js | 工具函数、API 请求、模板管理 |
打包构建
项目提供了完整的构建脚本：
一键构建（推荐）
build-release.bat该脚本会：
- 代码混淆处理
- 备份必要文件
- 使用 electron-builder 打包
- 输出到
release/目录
快速构建（仅打包）
quick-build.bat清理构建产物
clean-build.batnpm 脚本
npm run build # 等同于 build-release.bat
npm run pack # electron-builder 打包
npm run obfuscate # 代码混淆
npm run clean # 清理构建产物📝 开发日志
详细的变更记录和技术文档请查看 docs/ 目录：
功能更新
- CHANGELOG_CHAT_UI_V2.md – 聊天界面改版
- CHANGELOG_MARKDOWN_CHAT.md – Markdown 聊天支持
- CHANGELOG_CLICK_MENU.md – 单击菜单功能
- CHANGELOG_DBLCLICK_CHAT.md – 双击聊天功能
- CHANGELOG_HOVER_MENU.md – 悬停菜单设计
- CHANGELOG_RADIAL_MENU.md – 圆盘菜单功能
设计文档
- CHAT_UI_REDESIGN.md – 聊天界面重新设计
- HOVER_MENU_DESIGN.md – 悬停菜单设计
- RADIAL_MENU_README.md – 圆盘菜单说明
- MENU_ACTION_MAPPING.md – 菜单动作映射
构建与修复
- BUILD_GUIDE.md – 构建指南
- QUICK_BUILD.md – 快速构建
- DIRECTORY_STRUCTURE.md – 目录结构说明
- NSIS_CONFIG.md – NSIS 安装程序配置
- ICON_FIX.md – 图标修复
- ENCODING_FIX.md – 编码修复
问题修复
- FIX_CHAT_LAYOUT.md – 聊天布局修复
- FIX_CHAT_UI_VISIBILITY.md – 聊天UI可见性修复
- FIX_DBLCLICK_RACE_CONDITION.md – 双击竞态条件修复
- FIX_RADIAL_CLICK_ISSUE.md – 圆盘点击问题修复
- CONTEXT_MENU_DISABLED.md – 右键菜单禁用说明
- backend_url_fix.md – 后端地址修复
- websocket_auth_fix.md – WebSocket 认证修复
📄 许可证
本项目仅供学习和研究使用。
🤝 贡献
欢迎提交 Issue 和 Pull Request！
📮 联系方式
如有问题或建议，请通过 Issue 反馈。
