BANDORI PET REV AI Agent

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

<p align="center"> <a href="https://github.com/HELPMEEADICE/BANDORI-PET-REV"><img alt="GitHub Repo" src="https://img.shields.io/badge/GitHub-BANDORI--PET--REV-ff69b4?logo=github"></a> <a href="https://github.com/HELPMEEADICE/BANDORI-PET-REV/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/HELPMEEADICE/BANDORI-PET-REV?color=blue"></a> <a href="https://github.com/HELPMEEADICE/BANDORI-PET-REV/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/HELPMEEADICE/BANDORI-PET-REV?color=yellow"></a> <a href="https://github.com/HELPMEEADICE/BANDORI-PET-REV/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/HELPMEEADICE/BANDORI-PET-REV?color=orange"></a> <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white"></a> <a href="https://www.rust-lang.org/"><img alt="Rust 1.87+" src="https://img.shields.io/badge/Rust-1.87%2B-DEA584?logo=rust&logoColor=white"></a> <a href="https://www.qt.io/qt-for-python"><img alt="PySide6" src="https://img.shields.io/badge/GUI-PySide6-41CD52?logo=qt&logoColor=white"></a> <a href="https://wgpu.rs/"><img alt="wgpu" src="https://img.shields.io/badge/Renderer-wgpu-4B8BBE"></a> <a href="#1-环境要求"><img alt="Platforms: Windows, macOS and Linux" src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-6A5ACD"></a> <a href="https://www.live2d.com/"><img alt="Live2D" src="https://img.shields.io/badge/Live2D-Cubism%20v2-EE82EE?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMSAxNy45M2MtMy45NS0uNDktNy0zLjg1LTctNy45M3MzLjA1LTcuNDQgNy03LjkzdjE1Ljg2em0yLTE1Ljg2YzMuOTUuNDkgNyAzLjg1IDcgNy45M3MtMy4wNSA3LjQ0LTcgNy45M1Y0LjA3eiIvPjwvc3ZnPg=="></a> <a href="https://github.com/HELPMEEADICE/BANDORI-PET-REV"><img alt="Last Commit" src="https://img.shields.io/github/last-commit/HELPMEEADICE/BANDORI-PET-REV?color=green"></a> </p>

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

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

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

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

QQ群：1033517952

---

✨ 特性

• ⚡ Neocari 原生渲染 — Rust + wgpu，支持模型动作、表情、物理与口型。
• 🧍 VRM 3D 桌宠 — Rust + wgpu 正面正交渲染，支持 MToon、VRMA 动作，以及头发、裙摆和衣饰的弹簧骨骼物理；可直接导入 .vrm。详见 VRM 使用说明。
• 💬 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）
• Windows 宠物窗口需要 DirectX 12（支持软件适配器）；Linux 使用 Vulkan，macOS 使用 Metal
• 宠物进程已使用 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 -p bandori-pet-native -p pet-assets --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
python tools/build_ipc.py

tools/build_ipc.py 为当前 Python 和 CPU 架构显式构建 Rust IPC 扩展。更新 IPC 源码后需重新运行；模块导入不会触发编译，缺少扩展会明确报错。协议、生命周期、测试与基准见 Rust IPC 说明。

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 格式。

只要你也推 XX，我们就是异父异母的亲兄弟姐妹！🥹

---

🏗️ 从源码打包

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

python setup.py build

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

如需生成 Windows 安装包：

python setup.py build_msi

自动构建安装包

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

• 发布 GitHub Release（包括预发布版）后自动构建，全部成功后将安装包上传到该 Release。
• 在 Actions → Build installers → Run workflow 中选择分支或标签手动构建； 完成后在该次运行底部 Artifacts 按原始文件名分别下载所需安装包，例如 BandoriPet-<版本>-win-x86_64.zip、BandoriPet-<版本>-win-x86_64.msi 和 BandoriPet-<版本>-win-x86_64-setup.exe 是三个独立文件。全部 18 个安装包均 单独上传，不再按架构合并压缩；SHA256SUMS.txt 也可独立下载。产物保留 30 天。

所有版本号来自 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 脚本语法，并用 actionlint 校验工作流。
• Linux、Windows / Python 3.12：安装运行依赖，使用 Qt offscreen 模式运行完整 pytest 测试集，并保存 JUnit XML 报告 14 天。

测试任务会自动检出固定版本的 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

---

<p align="center"><strong>キラキラドキドキ！～ ✨</strong></p>