Metadata-Version: 2.4
Name: nonebot_plugin_dst_qq
Version: 0.2.2
Summary: 基于 NoneBot2 的饥荒管理平台 (DMP) QQ 机器人插件，支持游戏信息查询、命令执行和消息互通功能
Project-URL: Homepage, https://github.com/nonebot/nonebot-plugin-dst-qq
Project-URL: Repository, https://github.com/nonebot/nonebot-plugin-dst-qq
Project-URL: Documentation, https://github.com/nonebot/nonebot-plugin-dst-qq#readme
Project-URL: Bug Tracker, https://github.com/nonebot/nonebot-plugin-dst-qq/issues
Author-email: uitok <ui_101@qq.com>
License: MIT
License-File: LICENSE
Keywords: dmp,don't starve together,dst,message-exchange,nonebot,nonebot2,plugin,qq-bot,饥荒
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.9
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: nonebot-adapter-onebot>=2.4.0
Requires-Dist: nonebot2>=2.4.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# nonebot-plugin-dst-qq

[![PyPI version](https://badge.fury.io/py/nonebot-plugin-dst-qq.svg)](https://badge.fury.io/py/nonebot-plugin-dst-qq)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![NoneBot2](https://img.shields.io/badge/NoneBot2-2.4.0+-green.svg)](https://v2.nonebot.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## ✨ 功能特性

- 🌍 **世界信息查询** - 获取饥荒世界的基本信息
- 🏠 **房间信息查询** - 查看房间状态和配置
- 💻 **系统信息监控** - 监控服务器系统状态
- 👥 **玩家管理** - 查看在线玩家列表
- 🌐 **集群管理** - 管理多个游戏集群
- ⚡ **命令执行** - 在游戏中执行控制台命令（管理员权限）
- 🔄 **消息互通** - QQ消息与游戏内消息双向互通
- 🔐 **权限控制** - 完善的权限管理系统
- 📊 **实时数据** - 实时获取游戏数据

## 📦 安装

### 使用 nb-cli 安装（推荐）

```bash
nb plugin install nonebot-plugin-dst-qq
```

### 使用 pip 安装

```bash
pip install nonebot-plugin-dst-qq
```

## ⚙️ 配置

### 环境变量配置（必需）

在 `.env` 文件中添加以下配置：

```env
# DMP API配置（必需）
DMP_BASE_URL=http://your-dmp-server:port/v1
DMP_TOKEN=your-jwt-token
DEFAULT_CLUSTER=your-cluster-name
```

### 配置说明

| 配置项 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| `DMP_BASE_URL` | str | ✅ | DMP服务器API地址 |
| `DMP_TOKEN` | str | ✅ | JWT认证令牌 |
| `DEFAULT_CLUSTER` | str | ✅ | 默认集群名称 |

**注意：** 以上所有环境变量都是必需的，未设置会导致插件启动失败。

## 🚀 使用方法

### 基础命令

| 命令 | 别名 | 功能 | 权限 |
|------|------|------|------|
| `/世界` | `/world` | 获取世界信息 | 所有用户 |
| `/房间` | `/room` | 获取房间信息 | 所有用户 |
| `/系统` | `/sys` | 获取系统信息 | 所有用户 |
| `/玩家` | `/players` | 获取在线玩家列表 | 所有用户 |
| `/集群` | `/clusters` | 获取集群列表 | 所有用户 |
| `/菜单` | `/help` | 显示帮助信息 | 所有用户 |

### 消息互通功能

消息互通功能允许QQ用户与游戏内玩家进行实时消息交流。

#### 开启消息互通
```
消息互通
开启互通
start_exchange
```

#### 关闭消息互通
```
关闭互通
stop_exchange
```

#### 查看互通状态
```
互通状态
exchange_status
```

#### 获取最新消息
```
最新消息
latest
get_latest
```

**注意：** 消息互通功能只能在私聊中使用，群聊中会提示用户去私聊使用。

### 管理员命令

| 命令 | 功能 | 权限 |
|------|------|------|
| `/管理命令` | 显示管理员功能菜单 | 超级管理员 |
| `/备份` | 获取备份文件列表 | 超级管理员 |
| `/创建备份` | 手动创建备份 | 超级管理员 |
| `/执行 <世界> <命令>` | 执行游戏命令 | 超级管理员 |
| `/回档 <天数>` | 回档指定天数 (1-5天) | 超级管理员 |
| `/重置世界 [世界名称]` | 重置世界 (默认Master) | 超级管理员 |
| `/聊天历史 [世界名] [行数]` | 获取聊天历史 (默认集群，默认50行) | 超级管理员 |
| `/聊天统计` | 获取聊天历史统计信息 | 超级管理员 |

## 💡 使用示例

### 基础功能示例

#### 查询世界信息
```
用户: /世界
机器人: 🌍 世界信息:
📋 Master:
  • 天数: 15
  • 季节: 秋季
  • 玩家数: 3
  • 温度: 15°C
```

#### 查看在线玩家
```
用户: /玩家
机器人: 👥 在线玩家:
• 玩家1 (ID: 123456) - 在线时长: 2小时
• 玩家2 (ID: 789012) - 在线时长: 1小时30分钟
```

#### 执行游戏命令
```
用户: /执行 World4 c_listallplayers()
机器人: ✅ 命令执行成功: c_listallplayers()
```

### 消息互通示例

#### 开启消息互通
```
用户: 消息互通
机器人: ✅ 消息互通功能已开启！
      您的私聊消息将会发送到游戏中。
      发送「关闭互通」可以关闭此功能。
```

#### 发送消息到游戏
```
用户: 你好，游戏里的朋友们！
机器人: 消息已发送到游戏！
```
游戏内显示：`[QQ] 用户名: 你好，游戏里的朋友们！`

#### 获取最新消息
```
用户: 最新消息
机器人: 🎮 游戏内最新消息 (集群: MyCluster, 世界: World4):
      [02:45:30] 玩家A: 大家好！
      [02:46:15] 玩家B: 欢迎新朋友！
      🟢 玩家C 加入了游戏
```

### 管理员功能示例

#### 创建备份
```
用户: /创建备份
机器人: ✅ 备份创建成功！
      备份文件: backup_2024-01-15_14-30-00.zip
```

#### 回档操作
```
用户: /回档 2
机器人: ✅ 回档成功！
      已回档到2天前的状态
```

#### 重置世界
```
用户: /重置世界
机器人: ⚠️ 确认重置Master世界吗？
      此操作将删除所有游戏数据！
```

## 🔌 API 接口

本插件调用了以下 DMP API 接口：

| 接口 | 方法 | 功能 |
|------|------|------|
| `/home/world_info` | GET | 获取世界信息 |
| `/home/room_info` | GET | 获取房间信息 |
| `/home/sys_info` | GET | 获取系统信息 |
| `/setting/player/list` | GET | 获取玩家列表 |
| `/setting/clusters` | GET | 获取集群列表 |
| `/home/exec` | POST | 执行命令/发送公告 |
| `/logs/log_value` | GET | 获取聊天日志 |

## 🔐 权限控制

- **基础信息查询命令**：所有用户可用
- **消息互通功能**：所有用户可用（仅私聊）
- **管理员功能**：仅超级管理员可用
- **权限验证**：基于 NoneBot2 的权限系统

## 🛠️ 技术特性

### 消息互通技术实现

1. **QQ消息 → 游戏**
   - 用户发送私聊消息
   - 消息存储到数据库
   - 通过API发送到游戏服务器
   - 游戏内显示 `[QQ] 用户名: 消息内容`

2. **游戏消息 → QQ**
   - 定时任务每5秒同步一次
   - 获取所有集群和世界的聊天日志
   - 智能去重，避免重复推送
   - 自动过滤QQ消息和系统公告

### 错误处理

插件包含完善的错误处理机制：

- **API 请求失败**：显示具体错误信息和状态码
- **网络连接异常**：提示网络连接问题
- **参数错误**：显示正确的使用方法
- **权限不足**：提示权限要求
- **超时处理**：自动重试和超时提示

## 🏗️ 项目结构

```
nonebot-plugin-dst-qq/
├── nonebot_plugin_dst_qq/
│   ├── __init__.py          # 插件入口和元数据
│   ├── config.py            # 配置管理
│   ├── database.py          # 数据库操作
│   └── plugins/
│       ├── dmp_api.py       # DMP API 接口
│       ├── dmp_advanced.py  # 高级功能
│       └── message_exchange.py  # 消息互通功能
├── pyproject.toml           # 项目配置
├── README.md               # 项目说明
└── LICENSE                 # 许可证
```

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📝 更新日志

### v0.2.0 (2024-01-XX)

- ✨ 新增消息互通功能
- 🔄 支持QQ与游戏双向消息交流
- ⚡ 实时消息同步（5秒间隔）
- 🛡️ 智能消息去重机制
- 🎯 群聊友好提示

### v0.1.0 (2024-01-XX)

- 🎉 初始版本发布
- ✨ 支持基础的世界信息查询
- ✨ 支持玩家列表查询
- ✨ 支持系统信息查询
- ✨ 支持游戏命令执行
- 🔐 实现权限控制系统
- 🛠️ 完善的错误处理机制

## 🔗 相关链接

- [NoneBot2 官网](https://v2.nonebot.dev/)
- [NoneBot2 商店](https://v2.nonebot.dev/store)
- [NoneBot2 文档](https://v2.nonebot.dev/docs/)
- [OneBot 适配器](https://github.com/nonebot/adapter-onebot)

## ⭐ 支持

如果这个项目对您有帮助，请给我们一个 ⭐ Star！

---

**注意**：使用本插件前请确保您有合法的 DMP 服务器访问权限，并遵守相关服务条款。
