# xiangqi

**Repository Path**: games_9/xiangqi

## Basic Information

- **Project Name**: xiangqi
- **Description**: 双人对战象棋游戏
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Games By AI 🤖🎮

使用 AI 辅助编写的游戏代码集合

中国象棋 Web 双人对战平台

基于 Python FastAPI + WebSocket 的实时双人在线中国象棋对战系统。

![象棋棋盘](https://img.shields.io/badge/中国象棋-实时对战-blue)
![Python](https://img.shields.io/badge/Python-3.8+-green)
![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green)

## ✨ 功能特性

- 🎮 **双人在线对战** - WebSocket 实时同步，延迟低
- 🏠 **房间系统** - 创建/加入房间，支持随机匹配
- ♟️ **完整象棋规则** - 支持所有棋子走法验证
- 💬 **实时聊天** - 对战过程中可文字交流
- 📱 **响应式设计** - 支持电脑、平板、手机访问
- 🎨 **精美界面** - Canvas 绘制，传统中式风格

### 数据库

- 对局归档现在使用 PostgreSQL
- 连接配置来自 `.env` 或进程环境变量
- 支持 `SMARTWRITER_DB_URL` / `DATABASE_URL`
- 也可单独配置 `SMARTWRITER_DB_HOST`、`SMARTWRITER_DB_PORT`、`SMARTWRITER_DB_USER`、`SMARTWRITER_DB_PASSWORD`、`SMARTWRITER_DB_NAME`
- 旧的 `xiangqi.db` 仅作为一次性迁移来源

### 日志

- 后端使用标准 `logging` 输出
- 默认写到 stdout/stderr，不单独生成日志文件
- 若通过 `xiangqi.service` 运行，可用 `journalctl -u xiangqi.service -f` 查看实时日志

安装依赖

```bash
cd xiangqi-web
pip3 install -r requirements.txt
```

启动服务

```bash
cd backend
python3 main.py
```

开始游戏

1. 打开浏览器访问 [本地测试](http://localhost:8000)
2. 点击"创建房间"或输入房间号加入
3. 等待对手加入后即可开始对弈

## 🎯 核心功能

### 象棋规则实现

| 棋子 | 走法 | 特殊规则 |
| ------ | ------ | ---------- |
| 将/帅 | 直走一格 | 不出九宫 |
| 士/仕 | 斜走一格 | 不出九宫 |
| 象/相 | 田字格 | 不能过河，不能被塞象眼 |
| 马/傌 | 日字格 | 不能被蹩马腿 |
| 车/俥 | 直线任意格 | 不能越子 |
| 炮/砲 | 直线移动/吃子 | 吃子需隔一子 |
| 兵/卒 | 前进一格，过河可横走 | 不能后退 |

### WebSocket 通信协议

```json
// 客户端 -> 服务端: 走法
{
  "type": "move",
  "from_x": 4,
  "from_y": 6,
  "to_x": 4,
  "to_y": 5
}

// 服务端 -> 客户端: 广播走法
{
  "type": "move_made",
  "player_id": "abc123",
  "move": {"from": [4, 6], "to": [4, 5]},
  "next_turn": "black",
  "is_check": false,
  "board": {...}
}
```

---

## 🔧 扩展开发

### 添加 AI 对战

1. 集成 Pikafish 引擎
2. 创建人机对战房间
3. 引擎通过 UCI 协议通信

### 添加数据库

```python
# 使用 Redis 持久化房间数据
import redis
redis_client = redis.Redis(host='localhost', port=6379)

# 保存房间状态
redis_client.set(f"room:{room_id}", json.dumps(room.to_dict()))
```

### 部署到服务器

```bash
# 使用 Gunicorn + Uvicorn 部署
gunicorn backend.main:app -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 -w 4
```

## 🐛 常见问题

### Q: 棋子走法不合法也能走？

A: 走法验证在服务端进行，前端只负责发送请求。非法走法会收到 `move_error` 响应。

### Q: 如何支持更多同时在线房间？

A: 当前使用内存存储房间数据，生产环境建议使用 Redis 存储房间状态。

### Q: 如何实现断线重连？

A: 已实现自动重连机制，断线后 3 秒内自动尝试重新连接。

---

## 📜 许可证

MIT License - 可自由使用、修改、分发

## 🙏 致谢

- [FastAPI](https://fastapi.tiangolo.com/) - 高性能 Web 框架
- [Pikafish](https://github.com/official-pikafish/Pikafish) - 最强开源象棋引擎 (参考)