面向群聊场景的学习型机器人：会复读、会整活、可管理、可扩展。

牛牛 基于 NoneBot2 与 OneBot v11，数据层支持 MongoDB 或 PostgreSQL；自带运维面板 Pallas-Bot-WebUI。 发版与变更说明见 Releases；若需参考仅 MongoDB 的历史实现，见分支 archive/v2；向 PostgreSQL 迁移可使用 Mongo → PG 迁移脚本。

喜欢牛牛，就给牛牛点个 ⭐ 吧！

📑 目录

• 关于项目
  • 项目特点
• 运维入口
• 快速开始（部署）
  • 部署方式
  • 环境要求
  • 简单部署
• 使用指南
  • 功能列表
  • AI 扩展
• 配置要点
• 文档与链接
• 开发与贡献指南
• 社区与支持
  • QQ 群
  • 打赏
• 致谢
• 许可证

📖 关于项目

牛牛的功能就是废话和复读。可以认为是高级版的复读机。 发现牛牛学了一些不合适的话及时帮忙删除。 大家一起教出更棒更聪明的牛牛！✿✿ヽ(°▽°)ノ✿

✨ 项目特点

• 学习型复读，不依赖硬编码问答库
• 支持跨群语料聚合与全局禁用
• 牛牛玩法：喝酒、轮盘、唱歌、聊天、生图、夺舍；
• 管理能力：黑名单、好友欢迎、好友/入群申请管理
• 数据后端：MongoDB 或 PostgreSQL
• 运维：pallas_webui 控制台、pallas_protocol 协议端管理

🗂️ 运维入口

以下路径中的 HOST、PORT 以 .env 为准（默认常为本机 8088）。

入口	URL 示例
Web 控制台	http://<HOST>:<PORT>/pallas/
协议端管理	http://<HOST>:<PORT>/protocol/console/

• 登录口令：控制台与协议端管理共用；首次启动见 Bot 日志。遗忘后的处理见 FAQ · 部署排障。
• Docker：pallasbot 服务镜像见根目录 docker-compose.yml 的 image；需对齐某次 Release 时请直接改为带 tag 的镜像名（或自建 override 文件）。
• 排障与插件字段：FAQ、协议端（pallas_protocol）、控制台（pallas_webui）。

🚀 快速开始（部署）

📦 部署方式

• 托管实例接入：加入 拉牛牛群 获取可用实例
• 标准部署：按 部署教程 执行完整流程
• 容器化部署：使用 Docker 部署

📋 环境要求

• Python 3.12+
• uv
• MongoDB 或 PostgreSQL（二选一）
• OneBot v11 协议端

⚡ 简单部署

#获取代码
git clone https://github.com/PallasBot/Pallas-Bot.git

#进入目录
cd Pallas-Bot

# 安装依赖
pip install uv          # 安装 uv
uv sync                 # 安装依赖

# 开始运行
uv run nb run

完整部署细节请查看 部署教程 和 Docker 部署。 部署好自己牛牛之后，若将他人账号接为自己的牛牛，请把对方 QQ 写入该牛牛的 admins（号主）；新建牛牛时也可由超管私聊 「创建牛牛」 并在命令里带上号主 QQ，会自动写入 admins。详见 FAQ：如何为牛牛配置号主（admins）。

📚 使用指南

🎮 功能列表

忘记了就用牛牛帮助!

基础功能

• 牛牛帮助:查看牛牛可用插件以及开关状态
• 牛牛喝酒 / 牛牛醒一醒:控制牛牛醉酒与醒酒状态，影响聊天/轮盘/夺舍行为概率。
• 牛牛轮盘:提供踢人/禁言轮盘玩法，支持牛牛救一下与牛牛补一枪。
• 酒后聊天:牛牛醉酒时启用 AI 对话能力，支持 @牛牛 或"牛牛 + 文本"触发。（依赖 AI 服务端）。
• 牛牛唱歌:提供 AI 唱歌、继续唱、点歌、查询歌名支持（依赖 AI 服务端）。
• 牛牛画画：让牛牛AI生图；可附图或回复图作参考
• 牛牛做梦: 让群友的话与牛牛画的画成为漂流瓶，传到牛牛的其他梦里吧!

被动功能

• repeater:牛牛复读的核心组件
• greeting:牛牛群欢迎，处理入群/好友欢迎和部分群通知，支持自定义欢迎消息。
• take_name:自动夺舍，定时随机更换牛牛群名片；醉酒时有概率同步修改被取名群友的名片。

管理功能

• pallas_webui:Web 控制台，提供可视化管理界面（需部署前端，启动时自动下载）。
• pallas_protocol:协议端管理，支持多账号运行、协议端发行包自动下载与状态管理。

群管理员功能

• 管理员可以查看帮助并管理功能开关（按功能名/序号启用或禁用，支持牛牛开启/关闭全部功能）。
• 管理员可以通过牛牛轮盘禁言/踢人控制玩法

号主（admins）功能

• 牛牛重新上号:便捷地重启与登录牛牛实例。
• 设置好友欢迎:自定义牛牛添加好友的欢迎消息。
• 同意好友/入群:管理好友申请与入群邀请，支持审批与自动同意开关。
• 牛牛在吗:查询在线/离线 bot 并支持离线通知。

超管功能

• 创建牛牛:创建新的牛牛实例。
• 牛牛帮助:超管可以查看并管理隐藏的功能（按功能名/序号启用或禁用）。
• 牛牛在吗:查询在线/离线 bot 并支持离线通知（含测试邮件）。

🤖 AI 扩展

部署 Pallas-Bot-AI 并开启对应能力后可用：

展开查看完整功能列表

• [角色名]唱歌 <歌曲名>（指定翻唱，支持 key=N 调整音调）& [角色名]唱歌（播放唱过的歌曲）
• [角色名]继续唱 / [角色名]接着唱（继续上次未完成的歌曲）
• [角色名]什么歌 / [角色名]哪首歌（查询当前播放歌曲名）
• 牛牛点歌 <歌曲名>
• 网易云登录 / 网易云登出
• 酒后聊天（ChatRWKV 模型）
• 酒后聊天内容文本转语音（TTS）

⚙️ 配置要点

以下为启动前最常见的几项；更多键名与默认值以各插件 Pydantic 配置为准，推荐在 Web 控制台 「插件」「通用配置」 中修改（写入根目录 .env），需要离线编辑时可查 插件文档索引。

配置项	默认/示例	说明	必填
HOST / PORT	0.0.0.0 / 8088	Bot HTTP 监听；控制台与协议管理页同源	是
SUPERUSERS	QQ 号列表	超管 QQ	是
DB_BACKEND	mongodb / postgresql	数据后端	是
MONGO_* / PG_*	见根目录 .env 模板	数据库地址与账号（与 DB_BACKEND 对应）	是
ACCESS_TOKEN	空	驱动层 HTTP 鉴权；公网暴露时建议填写	否
PALLAS_PROTOCOL_ENABLED / PALLAS_PROTOCOL_WEBUI_ENABLED	默认开启	协议端插件与管理页	否

控制台与协议管理页为浏览器登录，口令在 data/pallas_console/；说明见 pallas_webui、pallas_protocol，遗忘与排障见 FAQ。

📚 文档与链接

类型	链接
标准部署	docs/Deployment.md
Docker	docs/DockerDeployment.md
常见问题	docs/FAQ.md（学习机制、使用与管理、部署排障）
插件索引	docs/plugins/README.md
协议端 / 控制台	pallas_protocol、pallas_webui
变更记录	GitHub Releases
数据迁移	Mongo → PG 脚本、迁移说明（v3）
历史分支	archive/v2（仅 MongoDB 旧版参考）

💻 开发与贡献指南

欢迎通过 Issues / PR 参与改进。参与前请阅读 贡献指南 与仓库根目录 AGENTS.md（本地安装、Ruff、pytest、提交约定）。

🤝 社区与支持

💬 QQ 群

• 开发者

  • 牛牛听话!

• 拉牛牛

  • 牢牛今天寄了吗
  • 西海福牛养殖基地
  • 牛牛工坊

• 闲聊

  • 泛用型群聊解决方案0.1.0b1
  • 帕拉斯の工坊
  • 西海福牛养殖学院
  • 丽丽玛玛玛?

💝 打赏

请作者喝杯咖啡吧（请备注牛牛项目，感谢你的支持 ✿✿ヽ(°▽°)ノ✿）：

🙏 致谢

• NoneBot2：跨平台 Python 异步聊天机器人框架
• jieba_next：Use Rust to Speed up jieba 高效、现代的中文分词库
• beanie：Asynchronous Python ODM for MongoDB
• NapCat：现代化的基于 NTQQ 的 Bot 协议端实现
• zhenxun_bot：非常可爱的绪山真寻Bot
• Amiya-bot：基于 AmiyaBot 框架的 QQ 聊天机器人
• CustomMarkdownImage：基于pillow的可自定义markdown渲染器

📊 统计

👥 贡献者

感谢各位大佬！

📄 许可证

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0）许可证，详见 LICENSE。