# pgn-tactics-generator

**Repository Path**: darkranger/pgn-tactics-generator

## Basic Information

- **Project Name**: pgn-tactics-generator
- **Description**: https://github.com/vitogit/pgn-tactics-generator.git 二创。更符合中国程序员和国际象棋爱好者使用习惯
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pgn-tactics-generator（中文）
[🏠 首页](README.md) | [🧭 概览](docs/PROJECT_OVERVIEW.md) | [🧪 开发](DEVELOPMENT.md) | [📊 状态](docs/STATUS.md) | [🔌 API](docs/API_APIFIX.md)


## 项目简介
- 从 PGN 对局中自动挖掘战术题（tactics），调用本地 Stockfish 分析，导出到 `tactics.pgn`。
- 支持从 Lichess 下载用户或比赛的对局作为素材。
- 基于开源项目 [Python-Puzzle-Creator](https://github.com/clarkerubber/Python-Puzzle-Creator) 做了改造和增强。

更多详细说明与流程图见：`docs/PROJECT_OVERVIEW.md`；外部 API 使用与 cURL 样例见：`docs/API_APIFIX.md`。

## 安装与环境
- 建议使用 Python 3.10+，并在虚拟环境中安装依赖：
```
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt
```
- 准备 Stockfish：
  - macOS/ARM：运行 `sh build-stockfish.sh`，会在仓库根目录生成可执行 `./stockfish-arm64`；
  - 或自行下载官方二进制，运行时用 `--stockfish /path/to/stockfish` 指定。

## 下载对局（可选）
- 下载 Lichess 用户最近对局（PGN）：
```
python3 download_games.py <Lichess用户名> --max 100 --token <TOKEN>
```
- 下载比赛对局（PGN）：
```
python3 download_tournaments.py <TournamentID1> <TournamentID2>
```
- Lichess Token 生成与使用详见：`docs/API_APIFIX.md`（支持直接复制 cURL 到 Apifox 导入）。

## 生成战术题
- 默认读取 `games.pgn` 并输出到 `tactics.pgn`：
```
python3 main.py --depth 12
```
- 常用参数：
  - `--games`: PGN 文件，默认 `games.pgn`
  - `--depth`: 引擎深度（越大越准但越慢），默认 8
  - `--scanDepth`: 候选扫描深度（不指定则等于 `--depth`）
  - `--solveDepth`: 生成谜题深度（不指定则等于 `--depth`）
  - `--strict`: 是否严格筛选（默认 True；`--strict False` 更容易出题）
  - `--threads` / `--memory`: Stockfish 资源配置
  - `--includeBlunder`: 导出 PGN 是否包含最初的失误一步
    - 一般建议 `--includeBlunder False`，这样“先手为获胜方”，PGN Result 更符合直觉
  - `--stockfish`: 指定 Stockfish 可执行文件路径

示例：
```
python3 main.py --quiet --depth 12 --strict False --threads 2 --memory 1024

# 两阶段示例：扫描 8 层，生成 14 层（提速且稳产，先手即赢家）
python3 main.py --scanDepth 8 --solveDepth 14 --strict False --includeBlunder False
```

## 输出说明
- 生成的 `tactics.pgn` 可直接导入 Lichess Study 或 iChess 等应用练题。
- PGN 的 Result 标签代表“战术题的解题方胜负”，而不是整局对局结果。

## 疑难解答
- 看不见产出：
  - 提高 `--depth`（例如 14 或 16）；
  - 试试 `--strict False` 放宽筛选；
  - 确认 `./stockfish*` 可执行存在（macOS/ARM 推荐本地编译）。
- Stockfish 相关问题：
  - 可直接从官网下载安装：https://stockfishchess.org/download/
  - 我们默认优先使用本地可执行，避免在线下载失败。

## 示例命令
```
python3 main.py --game pgn/1.pgn --scanDepth 8 --solveDepth 14 --strict False --includeBlunder False  --stockfish ./stockfish-arm64 --threads=20 --memory=8192
```

## 进一步阅读
- 开发与测试文档：`DEVELOPMENT.md`
- 项目概要：`docs/PROJECT_OVERVIEW.md`
- 外部 API 与 cURL：`docs/API_APIFIX.md`
 - 项目状态与已修问题：`docs/STATUS.md`

---

[返回顶部](#) | [🏠 首页](README.md) | [🧭 概览](docs/PROJECT_OVERVIEW.md) | [🧪 开发](DEVELOPMENT.md) | [📊 状态](docs/STATUS.md) | [🔌 API](docs/API_APIFIX.md)