WPSBot/README.md

# WPS Bot Game 🎮

基于WPS协作开放平台的自定义机器人游戏系统，支持多种互动小游戏。

## ✨ 功能特性

### 🎲 骰娘系统
- 支持基础掷骰（`.r 1d20`）
- 支持带修正掷骰（`.r 3d6+5`）
- 自动识别大成功/大失败

### ✊ 石头剪刀布
- 与机器人对战
- 战绩统计
- 胜率计算

### 🔮 运势占卜
- 每日运势（同一天结果相同）
- 塔罗牌占卜
- 幸运数字和幸运颜色

### 🔢 猜数字游戏
- 1-100范围
- 10次机会
- 智能提示系统

### 📝 问答游戏
- 多领域题库
- 3次答题机会
- 关键词智能匹配

## 🚀 快速开始

### 环境要求

- 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
```

3. **配置环境变量**
```bash
# 复制配置文件模板
cp env.example .env

# 编辑配置文件，填入你的Webhook URL
nano .env
```

4. **运行应用**
```bash
# 开发模式
python app.py

# 生产模式（使用uvicorn）
uvicorn app:app --host 0.0.0.0 --port 8000 --workers 1
```

## 📝 配置说明

### 环境变量

在 `.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
```

### 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 答案     # 回答问题
```

## 🏗️ 项目结构

```
WPSBotGame/
├── app.py                 # FastAPI主应用
├── config.py              # 配置管理
├── requirements.txt       # Python依赖
├── core/                  # 核心模块
│   ├── database.py       # SQLite数据库
│   ├── models.py         # 数据模型
│   └── middleware.py     # 中间件
├── routers/              # API路由
│   ├── callback.py       # Callback处理
│   └── health.py         # 健康检查
├── utils/                # 工具函数
│   ├── message.py        # 消息发送
│   ├── parser.py         # 指令解析
│   └── rate_limit.py     # 限流控制
├── games/                # 游戏模块
│   ├── dice.py           # 骰娘系统
│   ├── rps.py            # 石头剪刀布
│   ├── fortune.py        # 运势占卜
│   ├── guess.py          # 猜数字
│   └── quiz.py           # 问答游戏
└── data/                 # 数据文件
    ├── bot.db            # SQLite数据库
    ├── fortunes.json     # 运势数据
    └── quiz.json         # 问答题库
```

## 🔧 部署

### 使用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-250MB
- **响应时间**：<500ms
- **并发支持**：5-10个同时请求
- **用户规模**：50-100个活跃用户
- **消息限制**：20条/分钟（WPS限制）

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License

## 📞 联系方式

如有问题，请提交Issue。

---

Made with ❤️ for WPS Bot Game