一款支持 macOS、Windows 和 Linux（X11）的开源跨平台互动桌宠。
Qingxiao Desktop Pet — a cross-platform virtual pet built with Tauri, Rust and Vue.
在 BongoCat 原有键鼠、手柄响应和模型导入能力之上，增加清宵雪碧图模型、模块化宠物动作、主动/被动触发器、右键交互菜单、对白气泡与本地动作语音。
Important
本仓库是开源项目 ayangweb/BongoCat 的修改版（fork），不是原项目的官方发行版。感谢原作者及所有上游贡献者提供的跨平台基础实现。
上图是当前内置的清宵工作形态。人物、古琴和背后双层飘带来自同一套透明 canonical；69 套正式动画只在明确的表情、手袖和特效区域内变化，避免人物位置、尺寸、材质和五官逐帧漂移。她会根据键盘输入弹琴，也会在空闲、特定时间、久别归来或用户主动操作时进入宠物形态并播放不同动作。
清宵的常态保持睁眼；眨眼、打盹、梦境和傲娇闭眼只在对应语义动作中短暂出现。工作待机和宠物待机均采用正常节奏的多帧动画，不会快速闪烁。
- 清宵雪碧图模型：包含 69 套正式动画，覆盖工作、进入宠物、待机、退出、弹琴、摸头、打盹、午休、深夜睡眠、战斗化形、心魔化形、问候、剑气凝心、云珠、扫弦、挥手和傲娇等动作；常驻飘带不会再作为独立图层突然出现或消失。
- 人物状态引擎：播放阶段与人物状态分离；清宵会按空闲时长、本地午休/深夜窗口、动作情绪和形态切换不同循环常态。战斗/心魔形态拥有各自的眨眼、动作和形态过渡雪碧图，临时动作结束后也不会闪回普通人物或旧待机。
- 可插拔动作模组：模型通过
behaviors.pet.modules加载独立module.json；后续角色可以复用同一套运行时，不需要把动作硬编码进页面或菜单。 - 主动互动：右键菜单按“主动动作 → 动作”展示，设置页也可预览同一动作。主动点击会立即播放目标动作，并能打断尚未结束的进入、当前动作或退出动画，不需要重复点击。
- 被动互动：右键菜单按“被动动作 → 触发类型 → 动作”展示；系统也会根据空闲时长、时间窗口、会话启动、久别归来、输入活跃度和持续工作时长自动触发。
- 对白气泡：动作可以携带独立对白；中文优先使用黄凯桦律师手写体，离线时自动回退到系统行楷或楷体，不影响应用运行。
- 本地动作语音：动作可以直接引用模型内的 Wwise Opus
.wem文件，无需离线转码；“动作音效”设置会同时控制 Sprite 与 Live2D 动作声音，新动作、输入打断和模型切换会停止旧语音。 - 键盘气泡限频：按下立即反馈，持续按住时按照模型配置的间隔重复冒泡，松开后立即停止，避免系统自动重复导致刷屏。
- 模型管理与导入：保留并加固 BongoCat 的模型导入、校验、切换和设置链路，失败时不会留下半导入状态。
- 输入链路加固：处理模型切换时仍按住的键、跨设备同名输入、macOS 监听恢复和新款 Mac
Fn键伴生事件等边界情况。
| 类型 | 触发方式 | 示例 |
|---|---|---|
| 主动 | 宠物窗口右键菜单、点击、悬停、抚摸 | 唤她一声、剑气凝心、陪她小憩、傲娇轻哼 |
| 空闲 | 一段时间没有被追踪的键盘、鼠标或手柄活动 | 好奇、打盹、梦境、轻声提醒 |
| 时间 | 本地日期、星期、固定时刻或每日时间窗口 | 早晨问候、午间休息、夜间琴音、节日对白 |
| 会话 | 应用启动或窗口离开后重新可见 | 启动问候、久别归来 |
| 活跃度 | 短时输入爆发或持续工作达到阈值 | 被吓一跳、回应连击、提醒休息 |
所有动作都经过统一的优先级、冷却、打断和生命周期仲裁。主动操作不受被动冷却限制；键盘或手柄输入始终优先于自动宠物动作，不会因为后台触发器抢占正常使用。macOS 输入监听未授权时，被动调度保持关闭，但右键菜单和设置页中的主动动作仍可使用。
请先安装 Rust、Node.js 和 pnpm，并完成 Tauri 2 系统依赖配置。
git clone https://github.com/dream-image/BongoCat.git
cd BongoCat
pnpm install
pnpm tauri dev构建当前平台安装包：
pnpm tauri build如果 Tauri 配置中存在 updater 公钥，正式更新包还需要提供对应的 TAURI_SIGNING_PRIVATE_KEY。仅构建本地未签名安装包时，应根据自己的分发方式关闭 updater artifact 签名要求；不要把私钥写进仓库或提交记录。
清宵模型入口位于：
src-tauri/assets/models/qingxiao/
├── model.json
├── audio/ # 模型共享动作语音，可直接存放受支持的 WEM
├── resources/cover.png
├── sprites/
└── modules/
├── lively/
├── routine/
└── tsundere/
新增模组时应优先使用数据配置：在 modules/<module-id>/module.json 中声明动画、动作和触发器，再由模型的 behaviors.pet.modules 引用。不要在 Vue 页面、TypeScript 菜单或运行时控制器中硬编码某个角色的 action id。
需要持续呈现清醒、困倦、睡眠、情绪或形态时，在 behaviors.pet.stateMachine 声明状态维度、时间/空闲规则和循环 Visual Profile；动作通过可选 stateEffect 更新状态，并可用 stateAnimations 按当前形态选择整套动作资源。没有状态效果的动作会自动回到最新 Profile。
仓库在 .agents/skills/ 中附带了两套面向 Codex 等 AI 工程代理的项目级 Skill。它们会先读取当前代码中的模型契约，再生成可由“设置 → 模型管理 → 导入”加载的完整模型目录。
| Skill | 适用场景 |
|---|---|
$build-bongocat-sprite-model |
根据角色参考图建立基础 Sprite 模型，制作待机、键鼠和变身动画，并完成常驻附件、表情口型和雪碧图稳定性验收。 |
$author-bongocat-action-modules |
为已有 Sprite 模型设计主动、被动、指针、日程、对白和本地语音动作模组，生成右键菜单配置与完整可导入模型包。 |
新角色应先使用 $build-bongocat-sprite-model 建立可正常加载的基础模型，再使用 $author-bongocat-action-modules 扩展宠物行为；已有 Sprite 模型可以直接从第二个 Skill 开始。详细的调用示例、产物边界和验证要求见 项目内置 AI Skills 使用指南。
- 项目内置 AI Skills 使用指南
- 清宵动作模组、触发器与资源约束
- 清宵一体化雪碧图重画与 canonical-first 验收记录
- 宠物人物状态引擎施工与验证记录
- 宠物行为、输入链路与模型切换交接记录
- 上游下载指南
- 贡献指南
本仓库的安装包发布在 dream-image/BongoCat Releases。Windows x64 使用 .exe 安装包；当前 macOS 包由 Apple Silicon 设备构建，仅适用于 arm64 Mac。
当前 macOS 安装包没有 Apple Developer ID 签名和公证，首次打开时 Gatekeeper 可能提示“无法验证开发者”或“BongoCat 已损坏，无法打开”。请只从本仓库 Release 下载，并按以下方式打开：
- 打开
.dmg，将BongoCat.app拖入“应用程序”。 - 在 Finder 的“应用程序”中右键或按住
Control点击BongoCat，选择“打开”。 - 在再次出现的确认窗口中选择“打开”。如果仍被阻止，前往“系统设置 → 隐私与安全性”，找到 BongoCat 的拦截提示并选择“仍要打开”。
Important
如果系统仍提示“文件损坏，无法打开”，请确认应用来自本仓库 Release，然后打开“终端”执行：
xattr -dr com.apple.quarantine /Applications/BongoCat.app执行完成后重新打开 BongoCat。请勿对来源不明的应用执行此命令，也不要全局关闭 Gatekeeper。
应用启动后，键盘监听等功能仍需按照 macOS 提示授予对应的系统权限。
如果只需要上游稳定版本，请前往 ayangweb/BongoCat Releases；上游安装包不包含本仓库新增的清宵动作模组。
本项目基于以下开源工作继续开发：
- 上游项目：ayangweb/BongoCat
- 上游灵感来源：MMmmmoko/Bongo-Cat-Mver
- 桌面框架：Tauri
仓库代码继续遵循 MIT License，原版权声明予以保留。清宵角色形象、远程字体及其他第三方素材可能具有各自的著作权或授权条件；MIT 软件许可证不会自动授予这些第三方素材的商标、角色形象或再分发权，请在发布和商用前分别确认。