nonebot-plugin-dst-qq

🎮 功能丰富的饥荒管理平台 (DMP) QQ 机器人插件，基于 NoneBot2 和 Alconna 构建，提供服务器管理、消息互通、物品百科等全方位功能。

🚀 快速开始

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

✨ 功能特性

🎮 核心功能

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

💬 消息互通

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

🔍 物品百科

智能搜索 - 支持中英文搜索，覆盖2863个饥荒物品（包含角色）
Wiki截图 - Selenium自动截图，精准捕获Wiki正文内容
分离截图 - 信息栏和正文内容分开截图，查看更清晰
自适应大小 - 智能计算截图尺寸，避免内容截断
快速响应 - 双层缓存系统，毫秒级查询速度
模糊匹配 - 支持模糊搜索和多结果选择
内容优化 - 自动隐藏导航栏、侧边栏等无关元素

🛠️ 管理功能

集群管理 - 动态集群切换和状态监控
缓存管理 - 智能缓存统计和清理功能
服务器浏览 - 查询DST官方服务器列表
配置管理 - 动态配置更新，热重载支持
调试工具 - 完整的调试和监控命令集

⚡ 性能优化

🧠 双层缓存 - 内存+文件缓存，减少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 文件中添加：

# NoneBot 驱动组合 (必须包含 httpx，确保支持 WS 客户端)
DRIVER="~fastapi[websockets]+~httpx"

# 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 配置文件

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

默认主配置：~/.local/share/nonebot/plugin/nonebot_plugin_dst_qq/config/app_config.json
- macOS: ~/Library/Application Support/nonebot/plugin/nonebot_plugin_dst_qq/config/app_config.json
- Windows: %APPDATA%\nonebot\plugin\nonebot_plugin_dst_qq\config\app_config.json
模板文件：nonebot_plugin_dst_qq/app_config.template.json
兼容路径：config/app_config.json（如旧版本已存在，仍会被自动读取）

配置示例：

  "dmp": {
    "base_url": "http://your-dmp-server:8080/v1",
    "token": "your-dmp-token-here",
    "timeout": 10.0,
    "max_retries": 3,
    "retry_delay": 1.0,
    "auto_discover_clusters": true,
    "cluster_cache_ttl": 300

🎯 命令使用

基础命令

命令	别名	功能	示例
`/房间`	`room`, `状态`	综合服务器信息	`/房间`
`/世界`	`world`, `worlds`	世界状态列表	`/世界`
`/玩家`	`players`, `在线`	在线玩家列表	`/玩家`
`/系统`	`sys`, `system`	系统状态信息	`/系统`
`/查房 [<关键词>]`	`服务器列表`, `server_list`	查询官方服务器	`/查房 PVP`
`/集群状态`	`cluster`, `集群列表`	查看集群信息	`/集群状态`

物品查询

命令	别名	功能	示例
`/物品 <关键词>`	`查物品`, `item`, `wiki`, `查`	物品Wiki截图查询	`/查大理石`
`/物品分离 <关键词>`	`分离物品`, `物品详情`, `详细物品`	分离截图信息栏和正文	`/物品分离大理石`
`/搜索物品 <关键词>`	`search`, `搜物品`	物品搜索列表	`/搜索物品石头`
`/物品统计`	`item_stats`, `物品数量`	物品数据统计	`/物品统计`
`/重载物品`	`reload_items`	重载物品数据(管理员)	`/重载物品`

消息互通

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

📝 功能示例

Wiki截图查询

输入：

/物品 大理石

机器人会：

🔍 搜索匹配的物品
🖼️ 自动截取Wiki页面正文内容
📷 返回高质量截图图片

服务器浏览

输入：

/查房 PVP

显示结果：

🏠 找到5个服务器 (搜索: PVP)

1. [PVP] Klei Official Server
   模式: Survival | 玩家: 12/16 | 地区: 亚太
   季节: 夏天 15天 | 密码: 无

2. [PVP Arena] Combat Zone  
   模式: Endless | 玩家: 8/20 | 地区: 美洲
   季节: 秋天 3天 | 密码: 无

...

集群管理

输入：

/集群状态

显示结果：

📊 集群状态概览

✅ 当前集群: Master
📊 可用集群: Master, Caves
🔍 最后检查: 2分钟前

集群详情:
• Master: 正常运行 | 5个世界
• Caves: 正常运行 | 2个世界

管理员命令

命令	功能	示例
`/缓存状态`	显示缓存统计信息	`/缓存状态`
`/清理缓存`	清空所有缓存	`/清理缓存`
`/切换集群 <名称>`	切换操作集群	`/切换集群 Master`
`/重载配置`	重新加载配置	`/重载配置`

调试命令

命令	功能	示例
`/测试文字`	测试消息发送	`/测试文字`
`/调试信息`	显示调试信息	`/调试信息`
`/版本信息`	显示版本信息	`/版本信息`

🏗️ 架构设计

模块化结构

nonebot_plugin_dst_qq/
├── __init__.py              # 🚀 插件入口和生命周期管理
├── database/                # 🗄️ 数据库模块
│   ├── __init__.py          # 统一接口和兼容层
│   ├── connection.py        # 连接池管理器
│   └── models.py           # 数据模型层
├── plugins/                 # 🔌 核心插件
│   ├── dmp_api.py          # DMP API集成
│   ├── dmp_advanced.py     # DMP高级功能
│   └── message_bridge.py   # 消息互通桥接
├── 命令模块/                # 🎯 命令处理器
│   ├── admin_commands.py   # 管理员命令
│   ├── cluster_commands.py # 集群管理命令
│   ├── debug_commands.py   # 调试命令
│   ├── item_commands.py    # 物品查询命令
│   └── server_commands.py  # 服务器命令
├── 核心组件/               # 🧠 核心功能组件
│   ├── simple_cache.py     # 简化缓存系统
│   ├── message_utils.py    # 消息工具
│   ├── server_browser.py   # 服务器浏览器
│   ├── cluster_manager.py  # 集群管理器
│   └── wiki_screenshot.py  # Wiki截图系统
└── 工具模块/              # 🛠️ 通用工具
    ├── config.py           # 配置管理
    ├── utils.py            # 通用工具
    ├── scheduler.py        # 任务调度
    └── item_data.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服务器

# 找到实际的配置文件路径
python - <<'PY'
from nonebot_plugin_localstore import get_plugin_config_dir
print(get_plugin_config_dir() / "app_config.json")
PY
# 查看配置内容
cat ~/.local/share/nonebot/plugin/nonebot_plugin_dst_qq/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/ 目录

🤝 贡献指南

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

Fork 项目
创建功能分支: git checkout -b feature/amazing-feature
提交更改: git commit -m 'Add amazing feature'
推送分支: git push origin feature/amazing-feature
创建 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 了解详细更新历史。

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

DMP饥荒管理面板 - 完善的饥荒管理平台
NoneBot2 - 优秀的Python异步机器人框架
Alconna - 强大的命令解析器
OneBot - 聊天机器人应用接口标准

📞 联系方式

作者: uitok
邮箱: ui_101@qq.com
项目地址: https://github.com/uitok/nonebot-plugin-dst-qq
问题反馈: https://github.com/uitok/nonebot-plugin-dst-qq/issues

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

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github/workflows		.github/workflows
config		config
nonebot_plugin_dst_qq		nonebot_plugin_dst_qq
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
UPGRADE_SUMMARY.md		UPGRADE_SUMMARY.md
pyproject.toml		pyproject.toml
物品名对照v5.0.txt		物品名对照v5.0.txt

Folders and files

Latest commit

History

Repository files navigation

nonebot-plugin-dst-qq

🚀 快速开始

✨ 功能特性

🎮 核心功能

💬 消息互通

🔍 物品百科

🛠️ 管理功能

⚡ 性能优化

📦 安装

使用 nb-cli 安装 (推荐)

使用 pip 安装

使用 poetry 安装

⚙️ 配置

1. 环境变量配置

2. DMP 配置文件

🎯 命令使用

基础命令

物品查询

消息互通

📝 功能示例

Wiki截图查询

服务器浏览

集群管理

管理员命令

调试命令

🏗️ 架构设计

模块化结构

性能特性

🔧 高级配置

缓存配置

数据库配置

消息互通配置

🐛 故障排除

常见问题

日志位置

🤝 贡献指南

开发环境

📋 版本历史

最新版本 v0.4.5

📄 许可证

🙏 致谢

📞 联系方式

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages