nonebot-plugin-who-is-spy 0.0.4

一款适用于QQ群的谁是卧底小游戏插件

nonebot-plugin-who-is-spy

✨ 一个谁是卧底小游戏插件 ✨

一个基于 NoneBot2 的群聊游戏插件 —— 谁是卧底
支持 群聊轮流发言 + 私聊匿名投票，带有胜场统计、排行榜、胜率榜等功能。

📖 介绍

nonebot-plugin-who-is-spy 是一个基于 NoneBot2 开发的多人群聊游戏插件，复刻了经典的 谁是卧底 桌游玩法。
它支持在 QQ 群里发起游戏，玩家轮流发言，通过私聊匿名投票淘汰嫌疑人，直到一方胜利。

特点：

• 规则完整：平民、卧底、白板三种身份，还原线下游戏体验
• 私聊投票：保护投票隐私，避免被针对
• 自动化流程：发言、投票、淘汰、胜负判定全程自动进行
• 数据统计：记录胜场、参与次数，支持排行榜与胜率榜
• 可定制化：词库、玩家人数、白板开关、身份提示等均可配置

💿 安装

使用 nb-cli 安装

在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装

nb plugin install nonebot-plugin-who-is-spy

使用包管理器安装

在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令

pip

pip install nonebot-plugin-who-is-spy

pdm

pdm add nonebot-plugin-who-is-spy

poetry

poetry add nonebot-plugin-who-is-spy

conda

conda install nonebot-plugin-who-is-spy

打开 nonebot2 项目根目录下的 pyproject.toml 文件, 在 [tool.nonebot] 部分追加写入

plugins = ["nonebot_plugin_template"]

⚙️ 配置

在 nonebot2 项目的.env文件中添加下表中的必填配置

配置项	必填	默认值	说明
spy_min_players	否	4	最少人数
spy_max_players	否	12	最大人数
spy_default_undercovers	否	1	默认卧底人数
spy_allow_blank	否	True	是否允许白板
spy_show_role_default	否	False	发词时是否显示身份

📂 词库

插件的词库文件使用 JSON 格式，存放在：

template/undercover_words.json

文件内容是一个二维数组，每一项是一个词对，格式为：

[
  ["平民词", "卧底词"],
  ["苹果", "香蕉"],
  ["猫", "狗"],
  ["飞机", "火车"]
]

运行 nb localstore 来获取数据路径，将词库文件放在 Data Dir 下名为 nonebot_plugin_who_is_spy 的文件夹内。

例如Windows下，使用 "C:\Users\***\AppData\Local\nonebot2\nonebot_plugin_who_is_spy\undercover_words.json" 作为词库路径

🎉 使用

指令

• 在群内发送 卧底帮助 即可获取帮助

🎮 谁是卧底 - 群聊版玩法说明
——————————
【开局】
卧底开局 [卧底人数] [blank]  → 创建房间（可选参数：卧底人数，blank=有白板）
加入   → 进入房间
发身份 → 房主开始游戏并私聊词语

【发言阶段】
- 系统会在群里公布发言顺序
- 轮到谁，谁直接在群里说一句描述
- 每人一句话，依次发完自动进入投票

【投票阶段（私聊进行）】
- 机器人私聊存活玩家投票序号列表
- 私聊直接回复数字：0=弃权，数字=投票对象

【胜负判定】
- 卧底全出局 → 平民胜利
- 卧底数≥平民数 → 卧底胜利

【常用指令】
状态   → 查看当前局势和投票序号
复盘   → 查看上一局记录
结束卧底 → 强制结束当前局
身份提示 开/关 → 设置私聊是否提示身份
卧底帮助 → 查看本说明
胜率榜 / 我的胜率 → 查看胜率 

效果图