nonebot-plugin-dst-qq 0.4.3

基于 NoneBot2 的饥荒管理平台 (DMP) QQ 机器人插件，支持游戏信息查询、命令执行和消息互通功能

nonebot-plugin-dst-qq

基于 NoneBot2 和 Alconna 的饥荒管理平台 (DMP) QQ 机器人插件，支持游戏信息查询、命令执行和消息互通功能。

🚀 快速开始

新用户？ 查看 完整安装指南 (INSTALLATION.md) 立即体验！包含从零开始的详细教程和故障排除。

✨ 功能特性

🎮 核心功能

• 🏠 房间信息 - 综合显示服务器状态、世界信息、玩家列表
• 🌍 世界管理 - 世界状态监控、备份管理、回档重置
• 👥 玩家管理 - 在线玩家列表、管理员列表、封禁白名单
• 💻 系统监控 - CPU/内存使用率、服务器负载状态
• 🔗 服务器浏览 - 官方服务器列表查询和筛选

💬 消息互通

• 双向通信 - QQ消息与游戏内消息实时双向互通
• 智能路由 - 支持私聊/群聊模式，自动消息过滤
• 会话管理 - 多用户独立会话，自动超时清理
• 消息去重 - 防止消息重复发送，优化用户体验

🔍 物品百科

• 智能搜索 - 支持中英文搜索，覆盖2800+饥荒物品
• Wiki截图 - 自动获取物品详情截图，精确展示信息
• 快速响应 - 本地数据库缓存，毫秒级查询速度
• 模糊匹配 - 支持模糊搜索和多结果选择

🛠️ 管理功能

• 命令执行 - 游戏内控制台命令远程执行
• 备份管理 - 自动备份列表和手动备份创建
• 聊天记录 - 游戏内聊天历史查询和统计
• 配置管理 - 动态配置更新，热重载支持

⚡ 性能优化

• 🧠 双层缓存 - 内存+文件缓存，减少70%重复请求
• 🗄️ 连接池 - 统一数据库连接管理，提升30%性能
• 📦 模块化 - 清晰架构设计，代码量减少33%
• 🔄 异步处理 - 全异步设计，支持高并发访问

📦 安装

使用 nb-cli 安装 (推荐)

nb plugin install nonebot-plugin-dst-qq

使用 pip 安装

pip install nonebot-plugin-dst-qq

使用 poetry 安装

poetry add nonebot-plugin-dst-qq

⚙️ 配置

1. 环境变量配置

在 .env 文件中添加：

# OneBot V11 配置 (必需)
ONEBOT_WS_URLS=["ws://your-onebot-server:port"]
ONEBOT_ACCESS_TOKEN="your-access-token"

# 超级用户 (必需)
SUPERUSERS=["your-qq-number"]

# 调试模式 (可选)
DEBUG=true
LOG_LEVEL=DEBUG

2. DMP 配置文件

插件会自动在以下位置创建配置文件：

• config/config/app_config.json - 主配置文件
• nonebot_plugin_dst_qq/app_config.template.json - 配置模板

配置示例：

{
    "dmp_url": "http://your-dmp-server:port/v1",
    "auth": {
        "username": "your-username",
        "password": "your-password"
    },
    "clusters": ["YourClusterName"],
    "cache_settings": {
        "enable_cache": true,
        "cache_ttl": 300
    }
}

🎯 命令使用

基础命令

命令	别名	功能	示例
/房间	room, 状态	综合服务器信息	/房间
/世界	world, worlds	世界状态列表	/世界
/玩家	players, 在线	在线玩家列表	/玩家
/系统	sys, system	系统状态信息	/系统

物品查询

命令	别名	功能	示例
/物品 <关键词>	item, wiki	物品Wiki查询	/物品 大理石
/搜索物品 <关键词>	search	物品搜索列表	/搜索物品 石头
/物品统计	item_stats	物品数据统计	/物品统计

消息互通

命令	别名	功能	示例
/消息互通	bridge, 互通	开启消息互通	/消息互通
/关闭互通	stop_bridge	关闭消息互通	/关闭互通
/互通状态	bridge_status	查看互通状态	/互通状态

服务器管理 (超级用户)

命令	功能	示例
/执行 <命令>	执行游戏内命令	/执行 c_godmode()
/备份	查看备份列表	/备份
/创建备份 [名称]	创建游戏备份	/创建备份 测试备份
/回档 <天数>	世界回档	/回档 1

调试命令

命令	功能	示例
/测试文字	测试消息发送	/测试文字
/调试信息	显示调试信息	/调试信息
/重载配置	重新加载配置	/重载配置

🏗️ 架构设计

模块化结构

nonebot_plugin_dst_qq/
├── database/                 # 🗄️ 数据库模块
│   ├── __init__.py          # 统一接口和兼容层
│   ├── connection.py        # 连接池管理器
│   └── models.py           # 数据模型层
├── plugins/                 # 🔌 核心插件
│   ├── dmp_api.py          # DMP API集成
│   ├── dmp_advanced.py     # DMP高级功能
│   └── message_bridge.py   # 消息互通桥接
├── commands/                # 🎯 命令模块
│   ├── admin_commands.py   # 管理员命令
│   ├── item_commands.py    # 物品查询命令
│   └── server_commands.py  # 服务器命令
├── core/                   # 🧠 核心组件
│   ├── simple_cache.py     # 简化缓存系统
│   ├── message_utils.py    # 消息工具
│   └── server_browser.py   # 服务器浏览器
└── utils/                  # 🛠️ 工具模块
    ├── config.py           # 配置管理
    ├── utils.py            # 通用工具
    └── scheduler.py        # 任务调度

性能特性

• 🚀 异步优先: 全异步设计，支持高并发
• 🧠 智能缓存: LRU算法，内存+文件双层缓存
• 🔗 连接池: 数据库连接复用，减少开销
• 📦 模块化: 按需加载，降低内存占用
• ⚡ 优化算法: 缓存命中率90%+，响应时间<100ms

🔧 高级配置

缓存配置

{
    "cache_settings": {
        "enable_cache": true,
        "memory_cache_size": 1000,
        "file_cache_ttl": 3600,
        "api_cache_ttl": 300
    }
}

数据库配置

{
    "database_settings": {
        "chat_history_days": 30,
        "auto_cleanup": true,
        "backup_enabled": true
    }
}

消息互通配置

{
    "bridge_settings": {
        "message_filter": true,
        "max_message_length": 200,
        "auto_reconnect": true,
        "session_timeout": 1800
    }
}

🐛 故障排除

常见问题

1. 插件无法连接DMP服务器

# 检查配置文件
cat config/config/app_config.json
# 测试网络连通性
curl -X GET "http://your-dmp-server:port/v1/auth/login"

2. 消息互通不工作

# 检查OneBot连接状态
# 确认超级用户配置正确
# 查看日志错误信息

3. 物品查询失败

# 重载物品数据
/重载物品
# 检查数据库文件
ls -la data/database/

日志位置

• NoneBot2日志: 控制台输出
• 插件日志: 使用 LOG_LEVEL=DEBUG 查看详细日志
• 数据库日志: data/database/ 目录

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 创建 Pull Request

开发环境

# 克隆项目
git clone https://github.com/uitok/nonebot-plugin-dst-qq.git
cd nonebot-plugin-dst-qq

# 安装依赖
poetry install
# 或
pip install -r requirements.txt

# 运行测试
pytest tests/

📋 版本历史

查看 CHANGELOG.md 了解详细更新历史。

最新版本 v0.4.0

• 🎯 缓存系统重构，性能提升43.6%
• 🗄️ 数据库架构优化，代码量减少33%
• ✨ 新增物品Wiki查询系统
• 🔧 修复多项关键Bug
• 📦 完整模块化重构

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

• NoneBot2 - 优秀的Python异步机器人框架
• Alconna - 强大的命令解析器
• OneBot - 聊天机器人应用接口标准

📞 联系方式

• 作者: uitok
• 邮箱: [e-mail]
• 项目地址: https://github.com/uitok/nonebot-plugin-dst-qq
• 问题反馈: https://github.com/uitok/nonebot-plugin-dst-qq/issues

---

如果这个项目对你有帮助，欢迎给一个 ⭐ Star！