🎸 BandoriPet — 把バンドリ角色养在桌面上！

⚠️ 免责声明：本项目仅供学习交流使用。角色模型版权归原作者及版权方所有，请勿用于商业用途。详情见 DISCLAIMER.md。

你是否曾幻想过香澄每天早上对你喊「キラキラドキドキ！」？你是否想在工作摸鱼的时候让友希那在一旁冷冷地盯着你（然后偷偷露出猫耳）？你是否想让爱音在你桌面上炫耀她刚学会的吉他 riff？你是否想把祥子和灯放在同一张桌面上上演属于你的 MyGO×AveMujica 小剧场……

现在，你的梦想实现了！！！

BandoriPet 是一个基于 Live2D Cubism SDK 和 PySide6 的开源桌面宠物项目，支持 51+ 位 BanG Dream! 角色、305+ 套服装，让你的桌面一秒变成 CiRCLE 排练室！

QQ群：1033517952

!Example

✨ 特性

• ⚡ Neocari 原生渲染 — Rust + wgpu，支持模型动作、表情、物理与口型。
• 💬 LLM 角色扮演 + 好感度记忆系统 — 接入大语言模型，每个角色都有专属 System Prompt，支持中日英多语言 + 动作标签。交互越多角色越了解你，好感度影响情绪和回复风格，支持人设方案保存/切换。
• 🎨 像素风桌面宠物 — 也可以切成像素小人的形态，CPU 友好，可爱不减！
• 🎵 节奏蹦迪 — 在“设置 → 显示设置”开启，角色就会跟随 Windows 默认播放设备的音乐像弹簧一样纵向压缩、拉伸，重拍压扁、拉伸回弹带余振；宽度与窗口位置不变，支持 Live2D 和像素模式，拖动时暂停，安静后恢复原比例。默认关闭，无需额外依赖。
• 🌓 Fluent Design 设置面板 — 暗色/亮色主题切换，图形化选角选装界面。支持简中、繁中、英文、日文、葡萄牙语、西班牙语、法语、德语、俄语 i18n 国际化。
• 📌 始终置顶 + 无边框 — 趴在你的窗口上方，赶都赶不走（误）。
• 🔔 系统托盘 — 右键一键切角色 / 开设置 / 优雅退场。
• 🔊 TTS 语音合成 — 接入 Qwen3TTS 后端，角色说话时自动语音播放 + Live2D 口型同步，支持中日英多语言。
• 🎙️ ASR 语音输入 — 支持一键安装本地 faster-whisper 后端，也可接入 OpenAI-compatible 语音识别服务，把麦克风录音转成聊天输入文本，详见 ASR_VOICE_INPUT_GUIDE.md。
• 🔗 聊天软件接入 — 本地 Webhook 端口可接收 QQ/微信/Telegram/Discord 等机器人转发消息，设置页支持复制地址、生成 Token 和一键测试。
• 👥 多角色同时显示 — 不止一个！你想放几个就放几个（只要你 GPU 撑得住）。
• 🤖 MCP + Computer Use 支持 — 通过 MCP 协议集成文件系统操作、浏览器控制等 AI Agent 扩展能力，让角色拥有"手"和"眼睛"。
• 🌐 多 LLM 后端 & 搜索增强 — 支持多组 API 配置切换，多后端同时在线，内置 Bing/Google 等多搜索引擎增强检索。

📦 快速开始

1. 环境要求

• Python 3.10+、Rust stable（构建原生后端）；宠物与预览共用 Neocari，Lua 插件继续使用 LuaJIT 2.1
• Windows、macOS、Linux（宠物窗口使用 X11 / XWayland）
• 支持 Vulkan / DirectX 12 / Metal 的显卡；Qt 设置预览需要 OpenGL 3.3+
• 宠物进程已使用 Neocari + wgpu 原生渲染，通过共享内存与主程序通信。构建、协议和平台范围见 Neocari 后端说明。

2. 克隆仓库

git clone --recurse-submodules https://github.com/HELPMEEADICE/BANDORI-PET-REV.git
cd BANDORI-PET-REV
cargo build --release --manifest-path native/pet_backend/Cargo.toml --locked

3. 下载模型文件（必需！）

💡 推荐：zstd 压缩格式模型包（~900MB，原生后端按服装解压并缓存）

> | 下载渠道 | 链接 |

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

| 🚀 ModelScope | models.zip |

| ☁️ Google Drive | 下载 |

| 🐌 百度网盘 | 下载 提取码：3724 |

🚨 传统 7z 模型包（~4GB，需解压到磁盘）

> | 下载渠道 | 链接 |

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

| 🚀 ModelScope | models.7z |

| ☁️ Google Drive | 下载 |

| 🐌 百度网盘 | 下载 提取码：3724 |

下载后将 models/ 放入项目根目录。若使用 7z 包，解压后的目录结构应为：

BandoriPet/
├── models/
│   ├── kasumi/
│   ├── yukina/
│   ├── anon/
│   ├── tomorin/
│   └── ...

4. 创建虚拟环境 & 安装依赖

💡 强烈建议在虚拟环境中运行，避免与系统全局 Python 包冲突。

创建虚拟环境：

python -m venv venv

激活虚拟环境：

| 平台 | 命令 | |------|------| | Windows | venv\Scripts\activate | | Linux / macOS | source venv/bin/activate |

激活后终端前面会出现 (venv) 提示符。

Python 包（Windows / Linux）：

pip install -r requirements.txt

Wayland 用户： 原生宠物后端目前使用 XWayland。设置和聊天仍使用 Qt。宠物窗口不再使用旧版 Qt layer-shell 桥；具体要求见 Neocari 后端说明。

第三方依赖（从源码编译时需要）：

mkdir third_party
PyQt-Fluent-Widgets（必须用 PySide6 分支！）
git clone -b PySide6 --single-branch https://github.com/zhiyiYo/PyQt-Fluent-Widgets.git third_party/PyQt-Fluent-Widgets
pip install -e third_party/PyQt-Fluent-Widgets
原生渲染器通过 Git 子模块获取

Python 包（macOS 源码运行）：

macOS 使用 installer/macos/install_source_dependencies.sh 安装依赖并构建原生后端。

5. 启动！

python main.py

🔊 TTS 语音合成（可选）

BandoriPet 支持接入本地 Qwen3TTS 推理后端，让角色用声音回应你，配合 Live2D 实时口型同步。

下载 TTS 后端

| 版本 | 适用场景 | 下载链接 | |------|----------|----------| | 🌟 LoRA 多角色版（推荐） | 基于 1.7b，按角色所属乐队加载对应 LoRA，声线更贴合角色 | ModelScope | | 🐓 1.7b 标准版 | 显卡较好，追求音质 | ModelScope | | 🐣 0.6b 低参数版 | 显卡配置较低，追求速度 | ModelScope |

| 备用渠道 | 链接 | |----------|------| | ☁️ Google Drive（三个版本都有） | 下载 | | 🐌 百度网盘（三个版本都有） | 下载 提取码：3724 |

下载后解压，运行后端 API 服务（默认监听 http://127.0.0.1:9880/），然后在设置面板 → TTS 配置 中开启并调整参数即可。

💡 语音克隆：audio_reference/ 目录下已内置 63 位角色的日文参考音频（含泽海奏多、薇欧拉），TTS 会自动根据当前聊天角色选择对应的声线。

🤖 MCP + Computer Use（可选）

BandoriPet 集成了 MCP（Model Context Protocol） 和 Computer Use 能力，让 LLM 角色可以调用本地工具与你互动。

MCP 服务器

• 文件系统操作 — 角色可以读取/创建项目文件、管理目录
• 计算机操控 — 角色可以操控鼠标键盘、截屏（需要手动授权）
• 可扩展 — 支持加载任意 MCP 服务器

使用方式

在设置面板 → MCP 配置 中启用需要的工具。详细说明见 MCP_COMPUTER_USE_GUIDE.md。

💖 好感度 / 记忆系统

每和一个角色聊天，系统会自动记录好感度、信任、熟悉度和当前心情，让角色的回复风格随关系变化。

聊天命令

| 命令 | 效果 | |------|------| | @状态 | 查看当前角色的好感度、信任、熟悉度和当前心情数值 | | @记忆 | 查看全局用户偏好和当前角色的专属记忆 | | @记住 xxx | 手动让角色记住某件事 | | @忘记 xxx | 删除指定记忆 | | @好感度 80 | 直接设置好感度数值（0-100） | | @信任 70 | 直接设置信任数值（0-100） | | @熟悉度 60 | 直接设置熟悉度数值（0-100） | | @当前心情 75 | 直接设置当前心情数值（0-100） |

以上命令也支持英文别名（@status, @memory, @remember, @forget, @affection, @trust, @familiarity, @setmood）和前导 /（如 /状态）。

自动记忆

角色会自动从聊天中提取你的个人信息（名字、生日、喜好等）并保存。你可以在设置面板 → 好感度/记忆 页面查看和整理所有记录。

🧸 支持的乐队 & 角色

已收录 12 个乐团及其他角色；安装相应 Live2D 模型后可显示角色与服装。已配置 LLM 角色扮演 Prompt 的角色可开启 AI 对话。

| 乐队 | 角色 | 服装 | LLM | |------|------|:---:|:---:| | Poppin'Party | 户山香澄 · 花园多惠 · 牛込里美 · 山吹沙绫 · 市谷有咲 | ✅ | ✅ | | Afterglow | 美竹兰 · 青叶摩卡 · 上原绯玛丽 · 宇田川巴 · 羽泽鸫 | ✅ | ✅ | | Pastel\*Palettes | 丸山彩 · 冰川日菜 · 白鹭千圣 · 大和麻弥 · 若宫伊芙 | ✅ | ✅ | | Hello, Happy World! | 弦卷心 · 濑田薰 · 北泽育美 · 松原花音 · 奥泽美咲 | ✅ | ✅ | | Roselia | 凑友希那 · 冰川纱夜 · 今井莉莎 · 宇田川亚子 · 白金燐子 | ✅ | ✅ | | RAISE A SUILEN | LAYER · MASKING · LOCK · PAREO · CHU² | ✅ | ✅ | | Morfonica | 仓田真白 · 桐谷透子 · 广町七深 · 二叶筑紫 · 八潮瑠唯 | ✅ | ✅ | | MyGO!!!!! | 千早爱音 · 高松灯 · 要乐奈 · 椎名立希 · 长崎素世 | ✅ | ✅ | | Ave Mujica | 丰川祥子 · 若叶睦 · 三角初华 · 八幡海铃 · 祐天寺若麦 | ✅ | ✅ | | 梦限大MewType | 仲町阿拉蕾 · 宫永野乃花 · 峰月律 · 藤都子 · 千石由乃 | ✅ | ✅ | | millsage | 汐见萤 · 伊泽枣 · 琴平凪 · 滨崎茉幌 · 和泉朋花 | ✅ | ✅ | | 一家Dumb Rock! | 须贺蕾叶 · 马桥心玖 · 矢仓蓬咲 · 梅里千樱梨 · 四宫宁月 | ✅ | ✅ | | 其他角色 | 纯田真奈 · 户山明日香 等 | ✅ | ✅ |

角色已配置本地角色扮演 Prompt（characters/ 目录）。更多角色的 Prompt 模板见 PROMPT.md，欢迎提交 PR 补全！

🎨 像素宠物 & 角色扮演扩展

pixels/ 目录下目前有有咲和乐奈的像素小人（.webp + 动作帧配置）。

characters/ 目录下有 40+ 位角色的高级 LLM 角色扮演 Prompt（含动作标签和表情系统）。

想要更多像素角色？想要给未配置的角色注入灵魂？

👉 热烈欢迎 PR！ 只要你推的角色还没上，这就是你的回合！🎉

• 像素风格宠物：参考 pixels/ 下的格式添加新角色动作帧即可。
• 高级角色扮演 Prompt：参考 PROMPT.md 和 characters/ 下的现有 Prompt 格式。

🏗️ 从源码打包

本项目使用 cx_Freeze 打包为独立可执行文件：

python setup.py build

构建产物在 BUILD/ 下。注意打包时模型文件不会被打包进去，用户需自行下载放入 models/。

如需生成 Windows 安装包：

python setup.py build_msi

自动构建安装包

Build installers 工作流 支持两种触发方式：

• 发布 GitHub Release（包括预发布版）后自动构建，全部成功后将安装包上传到该 Release。
• 在 Actions → Build installers → Run workflow 中选择分支或标签手动构建；

所有版本号来自 bandori_core/app_info.py 的 APP_VERSION，必须为 主版本.次版本.修订号； Release 标签应为同一版本号或加 v 前缀（例如 v3.2.1）。手动构建使用所选 分支或标签中的版本号，不会自动创建 Release。

| 平台 | x86_64 文件名 | aarch64 文件名 | |---|---|---| | Windows 便携包 | BandoriPet-<版本>-win-x86_64.zip | BandoriPet-<版本>-win-arm64.zip | | Windows MSI | BandoriPet-<版本>-win-x86_64.msi | BandoriPet-<版本>-win-arm64.msi | | Windows Inno Setup 6 | BandoriPet-<版本>-win-x86_64-setup.exe | BandoriPet-<版本>-win-arm64-setup.exe | | Linux | BandoriPet-<版本>-linux-x86_64.{AppImage,deb,rpm,tar.gz} | BandoriPet-<版本>-linux-aarch64.{AppImage,deb,rpm,tar.gz} | | macOS | BandoriPet-<版本>-macos-x86_64.{dmg,zip} | BandoriPet-<版本>-macos-arm64.{dmg,zip} |

六个目标分别在对应架构的 GitHub 托管 Runner 上原生构建，使用 Python 3.13。 构建工具、Qt 和LuaJIT 插件运行时版本固定在 installer/build-constraints.txt，第三方源码版本 固定在工作流中；Windows 显式安装 Inno Setup 6.7.3。

Linux 包基于 Ubuntu 24.04 构建，需要 glibc 2.39+ 和 OpenGL/音频系统库； DEB、RPM 会声明依赖，AppImage、tarball 用户需自行安装相应系统库。 从 Actions 下载 AppImage 后，先执行 chmod +x BandoriPet-*.AppImage 再运行。 Linux 原生 Wayland 桥及桌面伴侣仍需按 Wayland 指南 从源码安装。macOS 复用现有 ad-hoc 签名及首次打开辅助文件。 所有安装包均不含模型和用户数据，模型需另行下载。

持续集成与本地检查

CI 工作流 在每次 push、Pull Request 及手动触发时运行：

• Python 3.10–3.14：编译检查所有 Git 跟踪的 .py 文件，包含测试和安装脚本。
• Ruff：检查语法、非法控制流和未定义名称等基础问题，规则见 ruff.toml。
• LuaJIT：检查 Lua 插件示例语法。
• 校验所有 Git 跟踪的 JSON 资源、插件清单及 Bash、PowerShell、JavaScript

• Linux、Windows / Python 3.12：安装运行依赖，使用 Qt offscreen 模式运行完整

测试任务会自动检出固定版本的 Live2D 与 PySide6 Fluent Widgets 源码；更新 这些第三方依赖时，请同步调整工作流内的 ref。语法检查只检查本仓库跟踪的 文件，不会扫描本机虚拟环境、模型或第三方目录。

按照上文准备第三方源码后，可在虚拟环境中运行：

python -m pip install -r requirements.txt -r requirements-dev.txt
python -m ruff check .

Linux / macOS：

QT_QPA_PLATFORM=offscreen python -m pytest tests -q

Windows PowerShell：

$env:QT_QPA_PLATFORM = "offscreen"
python -m pytest tests -q

自动更新发布约定

设置页的「关于」中带有检查更新入口。不同运行方式会自动走对应的更新路径：

| 运行方式 | 更新方式 | |----------|----------| | git clone 后运行源码 | git fetch 检查上游，点击更新后执行 git pull --ff-only；仅在依赖清单变化时安装 requirements.txt | | 便携版 exe | 从 GitHub Release 下载最新 .zip 或 .7z，关闭程序后覆盖当前目录并重启 | | Inno Setup EXE 安装包 | 从 GitHub Release 下载最新 .exe，校验安装结果后重启 | | MSI 安装包 | 从 GitHub Release 下载最新 .msi，启动安装器完成升级 | | macOS App | 按 CPU 架构下载 .dmg 或 .zip，替换当前 .app、重新签名并重启 |

发布新版本时请同步修改 bandori_core/app_info.py 中的 APP_VERSION，并在 GitHub Release 上传匹配当前平台的资产，例如：

BandoriPet-3.0.1-WIN-AMD64.zip
BandoriPet-3.0.1-WIN-AMD64.7z
BandoriPet-3.0.1-WIN-AMD64.msi
BandoriPet-3.0.1-winamd64-setup.exe
BandoriPet-3.0.1-macos-arm64.dmg
BandoriPet-3.0.1-macos-x86_64.dmg

Release 标签必须高于旧版 APP_VERSION；不要只替换同一版本 Release 的资产，否则已安装客户端会判定为无更新。

如果你要从自己的仓库发布更新，请把 bandori_core/app_info.py 里的 APP_REPOSITORY 改成发布 Release 的仓库名。

🛠️ 技术栈

| 技术 | 用途 | |------|------| | PySide6 | Qt for Python 主框架 | | lupa | LuaJIT 插件运行时 | | PyQt-Fluent-Widgets | Win11 风格 Fluent Design 组件库 | | PyOpenGL | OpenGL 渲染后端 | | cx_Freeze | 打包为独立 exe | | OpenAI / MCP SDK | LLM API 接入 & MCP 协议扩展 | | sounddevice / soundfile | TTS 语音合成播放 |

📄 许可

本项目代码基于 GPLv3 开源。

角色模型、贴图、动作等资源文件版权归原版权方所有，请勿用于商业用途。

🙏 致谢

• Live2D Cubism SDK
• PyQt-Fluent-Widgets
• 所有为 BanG Dream! 角色模型做出贡献的同人作者们 💙

⭐ Star History