436 lines
10 KiB
Markdown
436 lines
10 KiB
Markdown
# WPS Bot Game 🎮
|
||
|
||
基于WPS协作开放平台的自定义机器人游戏系统，支持多种互动小游戏。
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 🎲 骰娘系统
|
||
- 支持基础掷骰（`.r 1d20`）
|
||
- 支持带修正掷骰（`.r 3d6+5`）
|
||
- 自动识别大成功/大失败
|
||
|
||
### ✊ 石头剪刀布
|
||
- 与机器人对战
|
||
- 战绩统计
|
||
- 胜率计算
|
||
|
||
### 🔮 运势占卜
|
||
- 每日运势（同一天结果相同）
|
||
- 塔罗牌占卜
|
||
- 幸运数字和幸运颜色
|
||
|
||
### 🔢 猜数字游戏
|
||
- 1-100范围
|
||
- 10次机会
|
||
- 智能提示系统
|
||
|
||
### 📝 问答游戏
|
||
- 多领域题库
|
||
- 3次答题机会
|
||
- 关键词智能匹配
|
||
|
||
### 🀄 成语接龙
|
||
- 支持多音字和谐音接龙
|
||
- 全局黑名单系统
|
||
- 实时状态显示
|
||
- 参与者统计排行
|
||
- 支持指定下一位接龙者
|
||
|
||
### ⚫ 五子棋
|
||
- 标准15×15棋盘
|
||
- 黑方禁手规则（三三、四四、长连）
|
||
- 多轮对战同时进行
|
||
- 完整的战绩统计
|
||
- 实时棋盘显示
|
||
|
||
### 💎 积分系统
|
||
- 每日签到获得固定积分（10分）
|
||
- 运势占卜随机获得积分（1-20分，30%概率）
|
||
- 个人积分查询和记录
|
||
- 积分排行榜
|
||
- 完整的积分变动记录
|
||
|
||
### ⚗️ 炼金系统
|
||
- 消耗积分进行抽奖（10/20/50积分）
|
||
- 奖品池数学期望略高于消耗积分，对玩家友好
|
||
- 包含大奖（巨额积分）和负面奖励（额外扣分）
|
||
- 完整的炼金记录和统计
|
||
- 支持多种消耗档位的抽奖
|
||
|
||
### 🎁 积分赠送系统
|
||
- 用户间积分赠送功能
|
||
- 支持附赠个性化消息
|
||
- 完整的赠送和接收记录
|
||
- 赠送统计和记录查询
|
||
- 单次最多赠送1000积分
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Python 3.10+
|
||
- 1GB内存 + 单核CPU（推荐配置）
|
||
- Ubuntu Server（推荐）
|
||
|
||
### 安装步骤
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd WPSBotGame
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
# 使用conda环境
|
||
conda activate liubai
|
||
pip install -r requirements.txt
|
||
|
||
# 注意：成语接龙游戏需要pypinyin库进行拼音处理
|
||
```
|
||
|
||
3. **配置Webhook**
|
||
有三种方式配置Webhook URL：
|
||
|
||
#### 方式1：命令行参数（推荐）
|
||
```bash
|
||
# Linux/Mac
|
||
python app.py --webhook-url "https://xz.wps.cn/api/v1/webhook/send?key=your_key"
|
||
|
||
# Windows
|
||
python app.py --webhook-url "https://xz.wps.cn/api/v1/webhook/send?key=your_key"
|
||
```
|
||
|
||
#### 方式2：使用启动脚本
|
||
```bash
|
||
# Linux/Mac
|
||
./start.sh -w "https://xz.wps.cn/api/v1/webhook/send?key=your_key"
|
||
|
||
# Windows
|
||
start.bat -w "https://xz.wps.cn/api/v1/webhook/send?key=your_key"
|
||
```
|
||
|
||
#### 方式3：环境变量
|
||
```bash
|
||
# 复制配置文件模板
|
||
cp config.env.example config.env
|
||
|
||
# 编辑配置文件，填入你的Webhook URL
|
||
nano config.env
|
||
```
|
||
|
||
4. **运行应用**
|
||
```bash
|
||
# 基本启动
|
||
python app.py
|
||
|
||
# 自定义参数启动
|
||
python app.py --webhook-url "your_webhook_url" --port 8080 --log-level debug
|
||
|
||
# 使用启动脚本
|
||
./start.sh -w "your_webhook_url" -p 8080 -l debug
|
||
|
||
# 生产模式（使用uvicorn）
|
||
uvicorn app:app --host 0.0.0.0 --port 8000 --workers 1
|
||
```
|
||
|
||
### 命令行参数说明
|
||
- `--webhook-url, -w`: WPS Webhook URL
|
||
- `--host, -H`: 服务器主机地址 (默认: 0.0.0.0)
|
||
- `--port, -p`: 服务器端口 (默认: 11000)
|
||
- `--workers`: 工作进程数 (默认: 1)
|
||
- `--log-level`: 日志级别 (默认: info)
|
||
|
||
## 📝 配置说明
|
||
|
||
### 环境变量
|
||
|
||
在 `.env` 文件中配置以下参数：
|
||
|
||
```env
|
||
# WPS Webhook配置
|
||
WEBHOOK_URL=https://xz.wps.cn/api/v1/webhook/send?key=YOUR_KEY_HERE
|
||
|
||
# 数据库配置
|
||
DATABASE_PATH=data/bot.db
|
||
|
||
# 系统配置
|
||
MAX_CONCURRENT_REQUESTS=5
|
||
SESSION_TIMEOUT=1800
|
||
MESSAGE_RATE_LIMIT=20
|
||
|
||
# 日志配置
|
||
LOG_LEVEL=INFO
|
||
|
||
# 游戏配置（可选，使用默认值）
|
||
# 成语接龙最大历史显示数量
|
||
IDIOM_MAX_HISTORY_DISPLAY=10
|
||
|
||
# 五子棋最大并发游戏数
|
||
GOMOKU_MAX_CONCURRENT_GAMES=5
|
||
```
|
||
|
||
### WPS机器人配置
|
||
|
||
1. 在WPS群聊中添加webhook机器人
|
||
2. 获取webhook URL（包含key参数）
|
||
3. 配置Callback URL为你的服务器地址：`http://your-server:8000/api/callback`
|
||
4. 验证Callback可用性（WPS会发送GET请求）
|
||
|
||
## 🎮 使用指南
|
||
|
||
### 通用指令
|
||
|
||
- `.help` - 显示帮助信息
|
||
- `.帮助` - 显示帮助信息
|
||
- `.stats` - 查看个人统计
|
||
|
||
### 骰娘指令
|
||
|
||
```
|
||
.r 1d20 # 掷一个20面骰
|
||
.r 3d6 # 掷三个6面骰
|
||
.r 2d10+5 # 掷两个10面骰加5
|
||
.r 1d20-3 # 掷一个20面骰减3
|
||
```
|
||
|
||
### 石头剪刀布
|
||
|
||
```
|
||
.rps 石头 # 出石头
|
||
.rps 剪刀 # 出剪刀
|
||
.rps 布 # 出布
|
||
.rps stats # 查看战绩
|
||
```
|
||
|
||
### 运势占卜
|
||
|
||
```
|
||
.fortune # 今日运势
|
||
.运势 # 今日运势
|
||
.fortune tarot # 塔罗占卜
|
||
```
|
||
|
||
### 猜数字
|
||
|
||
```
|
||
.guess start # 开始游戏
|
||
.guess 50 # 猜数字
|
||
.guess stop # 结束游戏
|
||
```
|
||
|
||
### 问答游戏
|
||
|
||
```
|
||
.quiz # 获取题目
|
||
.quiz 答案 # 回答问题
|
||
```
|
||
|
||
### 成语接龙
|
||
|
||
```
|
||
.idiom start [成语] # 开始游戏（可指定起始成语）
|
||
.idiom [成语] # 接龙
|
||
.idiom [成语] @某人 # 接龙并指定下一位
|
||
.idiom stop # 结束游戏
|
||
.idiom status # 查看游戏状态
|
||
.idiom reject [词语] # 拒绝词语加入黑名单（仅发起人）
|
||
.idiom blacklist # 查看黑名单
|
||
.idiom next @某人 # 指定下一位（仅最后接龙者）
|
||
```
|
||
|
||
### 五子棋
|
||
|
||
```
|
||
.gomoku challenge # 发起挑战
|
||
.gomoku accept # 接受挑战
|
||
.gomoku A1 # 在A1位置落子
|
||
.gomoku show # 显示当前棋盘
|
||
.gomoku resign # 认输
|
||
.gomoku cancel # 取消自己的挑战
|
||
.gomoku list # 列出所有进行中的对战
|
||
.gomoku stats # 查看个人战绩
|
||
```
|
||
|
||
### 积分系统
|
||
|
||
```
|
||
.points # 查看个人积分
|
||
.积分 # 查看个人积分
|
||
.checkin # 每日签到
|
||
.签到 # 每日签到
|
||
.打卡 # 每日签到
|
||
.points leaderboard # 积分排行榜
|
||
```
|
||
|
||
### 炼金系统
|
||
|
||
```
|
||
.alchemy # 消耗10积分进行炼金
|
||
.炼金 # 消耗10积分进行炼金
|
||
.alchemy 20 # 消耗20积分进行炼金
|
||
.alchemy 50 # 消耗50积分进行炼金
|
||
.alchemy stats # 查看炼金统计
|
||
.alchemy records # 查看炼金记录
|
||
```
|
||
|
||
### 积分赠送系统
|
||
|
||
```
|
||
.gift 123 50 生日快乐 # 赠送50积分给用户123，附赠消息
|
||
.赠送 456 100 感谢帮助 # 赠送100积分给用户456，附赠消息
|
||
.送 789 200 # 赠送200积分给用户789
|
||
.gift stats # 查看赠送统计
|
||
.gift sent # 查看发送记录
|
||
.gift received # 查看接收记录
|
||
```
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
WPSBotGame/
|
||
├── app.py # FastAPI主应用
|
||
├── config.py # 配置管理
|
||
├── requirements.txt # Python依赖
|
||
├── env.example # 环境变量模板
|
||
├── core/ # 核心模块
|
||
│ ├── database.py # SQLite数据库
|
||
│ ├── models.py # 数据模型
|
||
│ └── middleware.py # 中间件
|
||
├── routers/ # API路由
|
||
│ ├── callback.py # Callback处理
|
||
│ └── health.py # 健康检查
|
||
├── utils/ # 工具函数
|
||
│ ├── message.py # 消息发送
|
||
│ ├── parser.py # 指令解析
|
||
│ └── rate_limit.py # 限流控制
|
||
├── games/ # 游戏模块
|
||
│ ├── base.py # 游戏基类
|
||
│ ├── dice.py # 骰娘系统
|
||
│ ├── rps.py # 石头剪刀布
|
||
│ ├── fortune.py # 运势占卜
|
||
│ ├── guess.py # 猜数字
|
||
│ ├── quiz.py # 问答游戏
|
||
│ ├── idiom.py # 成语接龙
|
||
│ ├── gomoku.py # 五子棋
|
||
│ ├── gomoku_logic.py # 五子棋逻辑
|
||
│ ├── points.py # 积分系统
|
||
│ ├── alchemy.py # 炼金系统
|
||
│ └── gift.py # 积分赠送系统
|
||
├── data/ # 数据文件
|
||
│ ├── bot.db # SQLite数据库
|
||
│ ├── fortunes.json # 运势数据
|
||
│ ├── quiz.json # 问答题库
|
||
│ └── idiom_blacklist.json # 成语黑名单
|
||
├── deploy/ # 部署配置
|
||
│ ├── install.sh # 安装脚本
|
||
│ ├── manage.sh # 管理脚本
|
||
│ ├── nginx/ # Nginx配置
|
||
│ └── systemd/ # systemd服务配置
|
||
└── Convention/ # 通用工具库
|
||
├── Runtime/ # 运行时工具
|
||
└── Image/ # 图像处理工具
|
||
```
|
||
|
||
## 🔧 部署
|
||
|
||
### 使用systemd（推荐）
|
||
|
||
1. **复制服务配置文件**
|
||
```bash
|
||
sudo cp deploy/systemd/wps-bot.service /etc/systemd/system/
|
||
```
|
||
|
||
2. **修改配置文件**
|
||
```bash
|
||
sudo nano /etc/systemd/system/wps-bot.service
|
||
# 修改WorkingDirectory和ExecStart路径
|
||
```
|
||
|
||
3. **启动服务**
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl start wps-bot
|
||
sudo systemctl enable wps-bot
|
||
sudo systemctl status wps-bot
|
||
```
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 实时查看日志
|
||
sudo journalctl -u wps-bot -f
|
||
|
||
# 查看最近100行
|
||
sudo journalctl -u wps-bot -n 100
|
||
```
|
||
|
||
## 📊 监控
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
### 系统统计
|
||
|
||
```bash
|
||
curl http://localhost:8000/stats
|
||
```
|
||
|
||
返回内存使用、活跃用户数等信息。
|
||
|
||
## 🐛 常见问题
|
||
|
||
### 1. 内存不足
|
||
|
||
**问题**：服务器内存只有1GB
|
||
**解决**：
|
||
- 项目已优化为极低内存占用（~150-200MB）
|
||
- 使用单worker模式
|
||
- 按需加载游戏模块
|
||
- 定期清理过期会话
|
||
|
||
### 2. 消息发送失败
|
||
|
||
**问题**：机器人不回复
|
||
**解决**：
|
||
- 检查Webhook URL是否正确
|
||
- 检查网络连接
|
||
- 查看日志：`journalctl -u wps-bot -f`
|
||
- 确认触发了限流（20条/分钟）
|
||
|
||
### 3. 数据库锁定
|
||
|
||
**问题**：SQLite database is locked
|
||
**解决**：
|
||
- 项目使用自动提交模式，不应出现锁定
|
||
- 如果出现，检查是否有多个进程访问数据库
|
||
|
||
## 📈 性能指标
|
||
|
||
- **内存占用**：150-300MB（包含拼音处理库）
|
||
- **响应时间**：<500ms
|
||
- **并发支持**：5-10个同时请求
|
||
- **用户规模**：50-100个活跃用户
|
||
- **消息限制**：20条/分钟（WPS限制）
|
||
- **支持游戏**：10种游戏类型（骰子、石头剪刀布、运势、猜数字、问答、成语接龙、五子棋、积分系统、炼金系统、积分赠送系统）
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交Issue和Pull Request！
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题，请提交Issue。
|
||
|
||
---
|
||
|
||
Made with ❤️ for WPS Bot Game
|
||
|