nonebot-plugin-arkguesser 0.3.2

明日方舟猜干员游戏 - 支持多种游戏模式和题库设置

nonebot-plugin-arkguesser

✨ 明日方舟猜干员游戏 - 支持多种游戏模式和题库设置 ✨

📖 介绍

这是一个基于 NoneBot2 的明日方舟猜干员游戏插件，支持多种游戏模式和题库设置，为群聊和私聊提供有趣的游戏体验。

🎮 游戏特色

• 多种星级范围题库：支持1-6星干员的不同组合
• 大头模式：适合正常游戏体验
• 兔头模式：增加游戏趣味性
• 连战模式：猜对后自动开始下一轮，享受连续游戏乐趣
• 智能题库管理：支持群组和个人设置，优先级明确
• 丰富的干员信息：包含职业、种族、势力、数值等详细属性
• 智能匹配系统：支持干员名称和拼音模糊匹配

🏗️ 技术架构

核心组件

• 游戏引擎 (game.py): 核心游戏逻辑和状态管理
• 题库管理器 (pool_manager.py): 星级范围设置和干员抽取
• 模式管理器 (mode_manager.py): 大头/兔头模式切换
• 连战管理器 (continuous_manager.py): 连战模式控制
• 渲染引擎 (render.py): HTML模板渲染和图片处理
• 配置管理 (config.py): 插件配置和环境变量

技术特性

• 基于 NoneBot2 框架构建
• 使用 Alconna 命令解析器
• 支持多种适配器
• 模块化设计架构
• 本地数据存储管理
• HTML模板渲染系统

💿 安装

使用 nb-cli 安装

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

nb plugin install nonebot-plugin-arkguesser

使用包管理器安装

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

pip

pip install nonebot-plugin-arkguesser

pdm

pdm add nonebot-plugin-arkguesser

poetry

poetry add nonebot-plugin-arkguesser

conda

conda install nonebot-plugin-arkguesser

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

plugins = ["nonebot_plugin_arkguesser"]

📦 依赖要求

必需依赖

• nonebot2 >= 2.4.2 - 机器人框架
• nonebot-plugin-alconna >= 0.59.3 - 命令解析器
• nonebot-plugin-uninfo >= 0.9.0 - 用户信息管理
• nonebot-plugin-htmlrender >= 0.6.6 - HTML渲染
• nonebot-plugin-localstore >= 0.7.4 - 本地数据存储
• pypinyin >= 0.55.0 - 中文拼音支持
• pydantic >= 2.11.7 - 数据验证
• httpx >= 0.24.0 - HTTP客户端
• Pillow >= 9.0.0 - 图像处理
• loguru >= 0.7.0 - 日志记录
• arclet-alconna >= 0.59.3 - Alconna命令解析器核心

⚙️ 配置

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

配置项	必填	默认值	说明
arkguesser_max_attempts	否	10	最大尝试次数
arkguesser_default_rarity_range	否	"6"	默认星级范围
arkguesser_default_mode	否	"大头"	默认游戏模式

🎉 使用

指令表

指令	权限	需要@	范围	说明
arkstart	群员	否	群聊/私聊	开始游戏
结束	群员	否	群聊/私聊	结束游戏
直接输入干员名	群员	否	群聊/私聊	开始猜测

🎮 游戏指令详解

默认情况下本游戏指令无需前置斜杠/

基础游戏

• arkstart - 开始游戏
• 结束 - 结束游戏
• 直接输入干员名即可开始猜测

📚 题库设置

• /arkstart 题库 - 查看题库设置和使用方法
• /arkstart 题库 6 - 设置题库为6星干员
• /arkstart 题库 4-6 - 设置题库为4-6星干员
• /arkstart 题库 查看 - 查看当前题库设置
• /arkstart 题库 重置 - 重置为默认设置

🎭 模式设置

• /arkstart 模式 - 查看模式设置和使用方法
• /arkstart 模式 大头 - 设置为大头模式
• /arkstart 模式 兔头 - 设置为兔头模式
• /arkstart 模式 查看 - 查看当前模式设置
• /arkstart 模式 重置 - 重置为默认模式

🔄 连战模式设置

• /arkstart 连战 - 查看连战模式设置和使用方法
• /arkstart 连战 开启 - 开启连战模式
• /arkstart 连战 关闭 - 关闭连战模式
• /arkstart 连战 查看 - 查看当前连战模式设置
• /arkstart 连战 重置 - 重置为默认连战模式设置

🔄 资源更新设置

• /arkstart 更新 - 查看资源更新系统说明和使用方法
• /arkstart 更新 数据库 - 更新干员数据库（从PRTS Wiki获取最新数据）
• /arkstart 更新 立绘 - 更新所有干员立绘资源
• /arkstart 更新 6星 - 只更新6星干员立绘
• /arkstart 更新 4-6星 - 更新4-6星干员立绘
• /arkstart 更新 全量 - 全量更新（数据库+所有立绘）

⚙️ 群组配置说明

• 群聊设置：对所有群成员生效
• 个人设置：只在私聊中生效
• 优先级：群聊设置 > 个人设置 > 默认设置

💡 使用技巧

1. 题库选择：根据群组水平选择合适的星级范围
2. 模式切换：大头模式适合正常游戏，兔头模式增加趣味性
3. 连战模式：适合活跃的群聊，保持游戏连续性
4. 个人设置：私聊中可以设置个人偏好，不影响群聊

🎯 游戏特性详解

干员信息展示

• 基础属性：名称、星级、职业、子职业
• 背景信息：种族、性别、出身地、势力
• 战斗属性：攻击、防御、生命值、法抗、攻击间隔、费用
• 部署信息：部署位置、标签

智能匹配系统

• 精确匹配：完全匹配干员名称
• 模糊匹配：支持部分名称匹配
• 拼音匹配：支持拼音输入和匹配
• 容错处理：自动处理常见输入错误

题库管理

• 星级范围：支持1-6星的任意组合
• 动态调整：实时修改题库范围
• 数据统计：显示当前题库干员数量
• 持久化存储：设置自动保存和恢复

🚀 特性

• ✅ 支持多种星级范围题库（1-6星）
• ✅ 大头模式和兔头模式切换
• ✅ 连战模式自动下一轮
• ✅ 群组和个人设置分离
• ✅ 智能优先级管理
• ✅ 完整的指令系统
• ✅ 美观的游戏界面
• ✅ 丰富的干员信息展示
• ✅ 智能名称匹配系统
• ✅ 本地数据持久化
• ✅ 模块化架构设计

📁 项目结构

nonebot-plugin-arkguesser/                    # 项目根目录
├── nonebot_plugin_arkguesser/               # 插件包目录
│   ├── __init__.py                          # 插件入口和主要逻辑
│   ├── game_tools/                          # 游戏工具模块
│   │   ├── __init__.py                      # 游戏工具模块入口
│   │   ├── game.py                          # 游戏核心引擎
│   │   ├── pool_manager.py                  # 题库管理器（动态统计星级数量）
│   │   ├── mode_manager.py                  # 模式管理器
│   │   ├── continuous_manager.py            # 连战模式管理器
│   │   ├── render.py                        # 渲染引擎
│   │   └── config.py                        # 配置管理
│   ├── resource_tools/                      # 资源工具模块
│   │   ├── __init__.py                      # 资源工具模块入口
│   │   ├── illustration_config.py           # 立绘配置管理
│   │   ├── illustration_downloader_v2.py    # 立绘下载器V2
│   │   ├── update_simple.py                 # 简化资源更新工具
│   │   └── run_illustration_download.py     # 立绘下载执行脚本
│   └── resources/                           # 资源文件目录
│       ├── images/                          # 图片资源目录
│       │   └── xlpj/                       # 特殊图片资源
│       └── templates/                       # HTML模板目录
│           ├── guess.html                   # 猜测结果模板
│           ├── correct.html                 # 正确答案模板
│           ├── guess_rabbit.html            # 兔头模式猜测模板
│           └── correct_rabbit.html          # 兔头模式答案模板
├── pyproject.toml                           # 项目配置文件
├── requirements.txt                          # 依赖列表
├── README.md                                # 项目说明文档
├── .gitignore                               # Git忽略文件配置
└── MANIFEST.in                              # 分发包文件清单

📝 更新日志

v0.3.0 🆕

• 🔄 题库星级统计改为动态读取 characters.csv，移除固定估算
• 🔁 数据更新后自动刷新星级统计缓存
• 🧭 兼容 nonebot_plugin_localstore 数据目录路径读取
• 🐞 修复了少量bug，新增了大量ai代码

v0.2.0

• 🏗️ 架构重构：将游戏逻辑和资源工具分离到独立模块
• 📁 模块化设计：新增 game_tools/ 和 resource_tools/ 模块
• 🔧 代码优化：重构代码结构，提升可维护性和扩展性
• 📦 资源管理：新增立绘资源自动更新和管理工具
• 🚀 性能提升：优化模块导入和资源加载机制
• 🎯 功能增强：改进游戏逻辑和用户体验
• 📚 文档完善：更新项目结构和说明文档

v0.1.4

• 🎉 移除部分答辩代码增加大量答辩代码
• 🎮 完整的明日方舟猜干员游戏功能
• 📚 支持多种星级范围题库设置
• 🎭 大头和兔头模式切换
• 🔄 连战模式支持
• ⚙️ 群组和个人配置管理
• 🏗️ 模块化架构设计
• 🎨 HTML模板渲染系统
• 💾 本地数据持久化存储

v0.1.1

• 🔧 修复缺失的pypinyin依赖问题
• 📦 完善项目依赖配置
• 🚀 提升插件加载稳定性

v0.1.0

• 🎉 初始版本发布
• 🎮 基础猜干员游戏功能
• 🎭 大头和兔头模式
• 🔄 连战模式支持
• ⚙️ 题库和模式设置
• 👥 群组和个人配置

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置

1. 克隆项目仓库
2. 安装依赖：pip install -r requirements.txt
3. 运行测试：python -m pytest

贡献指南

• 遵循 PEP 8 代码规范
• 添加适当的注释和文档
• 确保所有测试通过
• 提交前运行代码格式化

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

• 因作者编程水平较差，许多代码使用了Cursor，所以你可能会看到大量ai代码
• FrostN0v0 - 感谢提供技术指导和建议
• NoneBot2 - 优秀的机器人框架
• nonebot-plugin-alconna - 强大的指令解析器
• nonebot-plugin-htmlrender - 美观的渲染器
• nonebot-plugin-mhguesser - 原项目灵感来源
• ArknightsGameData - 明日方舟游戏数据
• Arknights_guessr - 部分数据来源
• arknights-toolkit - 明日方舟相关功能整合库
• PRTS Wiki - 明日方舟游戏资料百科

📞 联系方式

• 项目主页：GitHub
• 问题反馈：Issues
• 讨论交流：Discussions