BongoCat 桌宠完整指南：3 步上手会敲键盘的 Live2D 猫咪

2026/10/29 1:54:13

BongoCat 桌宠完整指南：3 步上手会敲键盘的 Live2D 猫咪

【免费下载链接】BongoCat🐱 BongoCat — A cross-platform interactive desktop pet that brings fun to your desktop!项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat

BongoCat 是一款跨平台（Windows 与 macOS）的 Live2D 桌宠应用，核心代码为 Rust，设置界面基于 GPUI 构建，模型渲染走 Live2D Cubism Core。它适合经常敲代码、写文档、玩手柄的玩家：你按下的每个按键、点下的每个鼠标键、按下的每个手柄键，屏幕上这只猫都会实时做出对应动作。想给桌面加一个不打扰、不联网、可换形象的互动伙伴，从这篇指南开始就够了。

功能一览

输入方式	猫咪响应	适用场景
键盘按键	对应按键的敲击动画	编程、写作、办公
鼠标移动与按键	眼神跟随指针，按键触发对应爪子动作	日常操作、设计工作
游戏手柄按键与摇杆	按键映射的爪击动画	游戏、模拟器

平台范围：首发支持 Windows 10 1903+ 与 macOS 12+，Linux 在 ADR-0006 中明确为首发后的独立评估项。
隐私与资源：完全开源、离线运行、不收集任何用户数据；配置 schema 中overlay段的maximum_fps默认 60，可按机器情况下调。

三步上猫：从零到可用的最短路径

第一步：获取

git clone https://gitcode.com/gh_mirrors/bong/BongoCat

普通用户也可以直接下载 Release 页面对应平台的安装包，无需自行构建。

第二步：基础配置

启动后从系统托盘（状态图标）打开设置窗口，推荐起步值：

不透明度opacity_percent：调到 30~50（合法范围 1~100），既看得见猫，也不挡屏幕内容
圆角corner_radius_percent：设 10~25（合法范围 0~50），窗口边缘更柔和
开机自启动：开启后每次登录自动驻留，macOS 上首次开启会走系统权限流程

缩放scale_percent合法范围 25~400，默认 100，按屏幕大小调整即可。

第三步：启动验证

连续敲几个键、再移动鼠标和点击鼠标键。如果猫的眼睛跟随指针、爪子按按键落下，说明输入链路（捕获 → 状态协调 → 动画）已经跑通，配置完成。

模型怎么选：三种内置模型的适用场景

内置模型位于 resources/models/，在设置窗口的模型库中切换。

你是混合输入用户 → 标准版（standard）：55 个左手键动画，键盘、鼠标、手柄混合输入时不违和，作为默认选择没问题。
你是键盘重度用户 → 键盘版（keyboard）：55 个左手键外加 4 个右手键，每个物理按键都有独立的贴图层，长时间写代码、打字时敲击反馈最完整。
你是手柄玩家 → 手柄版（gamepad）：左右各 6 个按键位对应 ABXY、方向键、肩键与扳机，玩模拟器或接手柄时按键对得上。

进阶：自定义与扩展

如何导入自定义 Live2D 模型

一个可导入的模型文件夹至少包含：

.model3.json模型配置文件
.moc3模型数据文件
.cdi3.json显示信息文件
PNG 纹理图片
可选的.motion3.json（动作）与.exp3.json（表情）文件

在设置窗口的模型导入入口选择该文件夹即可。应用会先做包校验（防止路径穿越、符号链接逃逸，见 crates/bongocat-model/src/package.rs），通过后才复制进本地模型库，导入的模型可以单独重命名或删除。

开发者扩展入口

crates/bongocat-ui/：设置窗口与全部 GPUI 控件，新增界面入口从这里加
crates/bongocat-input/：键盘、鼠标、手柄的输入事件捕获，接入新输入源改这里
crates/bongocat-runtime/：输入状态与动作、参数、动画的协调逻辑，改「按什么出什么动画」在这里
crates/bongocat-plugin-service/：插件以独立 Rust 进程运行，新能力可以做成插件而不是改主程序

性能调优

设置窗口的 Overlay 分组直接编辑以下字段，典型调法：

{ "overlay": { "maximum_fps": 30, "opacity_percent": 40, "scale_percent": 100 } }

maximum_fps合法范围 15~240，默认 60；机器负载高时降到 30 最稳妥。

快速答疑

Q：Linux 能用吗？A：不能。首发平台只有 Windows 与 macOS，Linux 按独立 spike 在首发后评估，不在当前支持矩阵内。

Q：导入的模型提示校验失败？A：多半是引用文件缺失或.model3.json指向了包外路径，补齐纹理与 moc3 文件后重试。

Q：猫咪窗口卡顿怎么办？A：先把maximum_fps降到 30，再适当调低不透明度；两者都在设置窗口即时生效。

Q：支持多显示器吗？A：支持。窗口可以拖到任意屏幕，keep_inside_screen默认开启，防止猫咪被拖出屏幕边界。

资源清单

shared/config/config.schema.json：配置字段的完整契约，每个字段的类型、范围、默认值以它为准
crates/bongocat-platform/：窗口、输入、托盘、开机自启动等系统集成实现，定位平台相关问题时从这里入手
docs/technical-design.md：整体架构与平台分工，理解各 crate 边界之前先读它
CONTRIBUTING.zh-CN.md：贡献指南，提交代码前从这里走流程

参与贡献的入口就一个：按贡献指南提交议题或拉取请求即可。

【免费下载链接】BongoCat🐱 BongoCat — A cross-platform interactive desktop pet that brings fun to your desktop!项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

BongoCat 桌宠完整指南：3 步上手会敲键盘的 Live2D 猫咪