# python-game-github

**Repository Path**: bzsometest/python-game-github

## Basic Information

- **Project Name**: python-game-github
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-14
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 五子棋游戏

AI编码工具开发：github-copilot

使用python开发一个五子棋软件，poetry管理依赖

优点：下棋算法更强

## 支持功能

- 电脑下棋：内置多种算法，切换先手为电脑
- 玩法辅助：显示预警信息、支持悔棋

## 运行方式

```bash
poetry run gomoku-gui
```

## 代码目录结构

```
src/gomoku/
├── __init__.py              # 包初始化，导出公共API
│
├── core/                     # 核心游戏逻辑模块
│   ├── __init__.py
│   └── board.py              # 棋盘类，游戏状态管理
│
├── ai/                       # AI算法模块
│   ├── __init__.py
│   ├── base.py               # AI基类
│   ├── factory.py            # AI工厂，创建AI实例
│   ├── simple.py             # 简单启发式AI
│   ├── advanced.py            # 高级AI（优先进攻）
│   ├── pattern.py            # 模式AI（优先围堵）
│   └── master.py             # 大师级AI（平衡攻守）
│
└── ui/                       # 用户界面模块
    ├── __init__.py
    ├── window.py             # 主窗口，UI协调器
    ├── board.py              # 棋盘UI组件
    ├── panel.py              # 控制面板组件
    ├── game_logic.py         # 游戏逻辑控制器
    └── warnings.py           # 警告和建议系统
```

### 模块说明

#### core/ - 核心模块
- **board.py**: 棋盘类，负责游戏状态管理、落子、胜负判断等核心逻辑

#### ai/ - AI算法模块
- **base.py**: AI基类，定义AI接口
- **factory.py**: AI工厂，根据名称创建对应的AI实例
- **simple.py**: 简单启发式AI，基础算法
- **advanced.py**: 高级AI，使用迭代加深和alpha-beta剪枝，优先进攻
- **pattern.py**: 模式AI，优先围堵对手
- **master.py**: 大师级AI，使用TSS、VCF/VCT等高级技术，平衡攻守

#### ui/ - 用户界面模块
- **window.py**: 主窗口类，负责UI布局和组件协调
- **board.py**: 棋盘UI组件，负责棋盘绘制和点击处理
- **panel.py**: 控制面板组件，包含AI选择、游戏控制等
- **game_logic.py**: 游戏逻辑控制器，处理落子、AI移动等游戏流程
- **warnings.py**: 警告和建议系统，检测对手威胁并生成下棋建议

## 算法说明

| 算法名称 | 开发工具 | 进攻 | 围堵 | 特点 | 时间 | 胜率 | 缺点 |
|:--------|:--------|:----|:----|:----|:----|:----|:-----|
| Advanced | github-copilot | 强 | 中 | 优先进攻 | 3-10秒 | 高 | 某些情况下我方已3子时，不围堵而是去形成2个3子；某些情况下不围堵即将4颗棋子，而是去形成无法连成5个的4子 |
| Pattern | cursor | 强 | 强 | 优先围堵 | <1秒 | 高 | 电脑和人同时4子时，电脑不形成5子而是围堵；电脑和人同时3子时，电脑不形成4子而是围堵 |
| Master | cursor | 极强 | 极强 | 平衡攻守，TSS+深度搜索 | 3-5秒 | 中 | 后期能力减弱，都不会围堵 |
| Simple | - | 中 | 中 | 基础启发式 | <1秒 | 极低 | - |
| LLM | - | 中 | 中 | 基于本地GGUF模型智能决策 | 5-15秒 | 中 | 需要安装llama-cpp-python，模型文件较大 |

## LLM AI 使用说明

### 安装依赖

LLM AI 需要 `llama-cpp-python` 库来加载本地 GGUF 模型。

**如果看到警告：`警告: llama-cpp-python未安装`，请按以下步骤安装：**

#### 方法1：使用 Poetry 安装（推荐）

```bash
poetry add llama-cpp-python
```

**注意**：安装可能需要 5-15 分钟，因为需要编译。请耐心等待，不要中断。

#### 方法2：使用 pip 安装

```bash
pip install llama-cpp-python
```

#### 方法3：在 Poetry 环境中安装

```bash
poetry run pip install llama-cpp-python
```

#### 验证安装

安装完成后，运行以下命令验证：

```bash
poetry run python -c "from llama_cpp import Llama; print('✓ 安装成功！')"
```

#### 如果安装失败（Windows）

如果编译失败，可能需要安装 Visual Studio Build Tools，或使用预编译版本：

```bash
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
```

详细安装说明请参考 `安装LLM依赖.md` 文件。

### 模型文件

LLM AI 使用本地 GGUF 模型文件进行决策。默认模型路径为：
```
C:\Users\chao\Downloads\Qwen3-0.6B-Q4_K_M.gguf
```

如果模型文件不存在或路径不同，可以在代码中修改 `src/gomoku/ai/llm.py` 中的 `MODEL_PATH` 变量。

### 工作原理

1. **棋盘状态转换**：将当前棋盘状态转换为文本描述
2. **Prompt构建**：构建包含棋盘状态、历史记录和分析要求的prompt
3. **模型推理**：调用本地GGUF模型进行推理
4. **结果解析**：从模型输出中提取坐标
5. **备用算法**：如果模型不可用或解析失败，使用简单启发式算法

### 注意事项

- 首次加载模型需要一些时间（取决于模型大小和硬件性能）
- 模型推理速度取决于硬件配置（CPU/GPU）
- 如果模型文件不存在或加载失败，会自动回退到简单启发式算法
- 模型输出格式可能不稳定，已实现多种解析策略确保稳定性