谁是卧底 pallas-plugin-who-is-spy
提供开房、述词、匿名投票与复盘的群内卧底玩法。
安装方式
需已安装 Pallas-Bot ≥ 4.0。
推荐直接在控制台插件商店安装，或在本体项目中执行：
uv run pallas ext install pallas-plugin-who-is-spy
也可单独安装本包：
uv pip install pallas-plugin-who-is-spy
开发联调：clone 本仓库后 uv pip install -e .（pyproject.toml 可配置本体 path 依赖）。
多进程分片
Pallas-Bot 支持单进程，也支持 hub + 多个 worker 的多进程部署。启用分片时：
- hub 与每个 worker 须安装相同版本的本扩展包；
- 各进程共享同一路径的
data/（注册表、协调状态、WebUI 落盘等）； - 同群房间互斥与主持牛路由依赖 Redis 协调层。
本插件通过本体分片协调模块（如 spy_activity）与共享 data/ 保持一致；未安装扩展时不影响 core 插件运行。
详见：多进程分片 · 架构说明
怎么使用
群内谁是卧底：开房、自由讨论、房主发起投票、私聊匿名投票，直至一方阵营获胜。
用户命令
| 口令 / 触发 | 场景 | 说明 |
|---|---|---|
牛牛卧底 |
群内 | 开房 |
牛牛加入 / 牛牛退出 |
群内 | 筹备阶段进出 |
牛牛发身份 [潜藏人数] [白板] [暗牌|明牌] |
群内 | 房主开局并下发词语 |
@牛牛 + 描述 |
群内 | 讨论阶段记为述词 |
牛牛投票 |
群内 | 房主提前开始投票（先发复盘） |
私聊回复数字序号或 0 |
私聊 | 投票（0=弃权；私聊含本轮述词总结） |
牛牛局势 / 牛牛结束 |
群内 | 察看局势、结束房间 |
命令权限
| 命令 ID | 默认等级 |
|---|---|
who_is_spy.open |
所有人 |
who_is_spy.join |
所有人 |
who_is_spy.start |
所有人（含牛牛投票） |
who_is_spy.status |
所有人 |
who_is_spy.end |
所有人 |
详细用法、限制条件和可用范围以帮助为主。
配置项
| 键 | 默认 | 说明 |
|---|---|---|
spy_min_players |
4 | 最少开局人数 |
spy_max_players |
12 | 房间上限 |
spy_default_undercovers |
1 | 默认卧底数 |
spy_default_blanks |
0 | 默认白板数（无词，不计入胜负比较） |
spy_show_role_default |
false | 私聊是否附带身份（false=暗牌，只发词） |
spy_word_avoid_recent |
10 | 同群最近 N 局词对不重复，0 关闭 |
spy_auto_vote_when_all_spoken |
true | 全员 @牛牛 述词后自动投票 |
spy_speak_max_len |
120 | 复盘单条述词最大字数 |
spy_room_cleanup_sec |
600 | 局结束后空房清理秒数 |
spy_email_fallback |
true | 私聊失败时改发玩家 QQ 邮箱 |
字段以本仓库 config.py 为准；WebUI 插件 → 牛牛卧底 修改。
私聊与邮箱：发词/投票说明优先好友私聊；失败时尝试带 group_id 的临时会话；非好友须先私聊牛牛任意消息一次后牛牛才能回信。仍失败且 spy_email_fallback=true 时，复用 bot_status 的 SMTP 向 {QQ号}@qq.com 发信。
词库内置 resource/who_is_spy/undercover_words.json；运行期使用 data/who_is_spy/undercover_words.json（首次启动从 resource 复制，之后启动自动合并 resource 新增词对）。编辑 JSON 后重启 Bot 生效。
排障
| 现象 | 处理 |
|---|---|
| 收不到词语/投票私聊 | 非好友先私聊牛牛任意消息一次；或加好友；或查 QQ 邮箱；确认 bot_status SMTP 已配置 |
| 私聊「你的词：」后无字 | 非白板玩法，属投递失败；先私聊牛牛一次、加好友、查邮箱或看开局提示里的未达名单 |
| 本群已有房间 | 分片下同群互斥；「牛牛结束」或等局后自动清理 |
| @牛牛 述词无回复 | 分片多牛须 @ 本局主持牛（发「词已私聊」的那只）；述词优先于 Ollama；协调层未同步时主持牛内存局仍可述词 |
| 词库为空 | 检查 data/who_is_spy/undercover_words.json 或内置 resource/who_is_spy/ |
实现
源码位置：src/pallas_plugin_who_is_spy/
实现要点：
- 围绕开房、发词、述词、投票与复盘构成完整回合流程。
- 私聊失败时可按配置回退到邮箱投递。
- 分片模式下同群互斥和主持牛路由依赖协调层维持一致。
相关链接
| 说明 | 链接 |
|---|---|
| 谁是卧底 · 用户文档 | 文档站 · who_is_spy |
| 插件开发入门 | develop/plugin/getting-started |
| 多进程分片 | architecture/bot-process-sharding |
1 maintainer
Metadata
1 maintainer
Release files for pallas-plugin-who-is-spy 4.0.17
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pallas_plugin_who_is_spy-4.0.17.tar.gz | 2.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pallas_plugin_who_is_spy-4.0.17-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.9 MB
Release files / pallas_plugin_who_is_spy-4.0.17.tar.gz
| Download URL | pallas_plugin_who_is_spy-4.0.17.tar.gz |
|---|---|
| Size | 2.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
646baa1da50a391594e1059ef57728f7769d20ca38c64ab9711358fb4ac15fff
|
|
BLAKE2b-256 checksum How to use checksums |
147ed39299fc0b125efaa74856f4fb0803c62fe2c0f44ebdd9c9030f516a5ae1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.
Transparency logRelease files / pallas_plugin_who_is_spy-4.0.17-py3-none-any.whl
| Download URL | pallas_plugin_who_is_spy-4.0.17-py3-none-any.whl |
|---|---|
| Size | 53.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fc139acfcbba7692597b3e4b2d8ad676f0b6e532bcdb666ff91634eaef09d2a9
|
|
BLAKE2b-256 checksum How to use checksums |
5976ddc1ae891dd05ad2c141fe3247d6811ec325c53b90d6519742648fa2a776
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.
Transparency log
