Metadata-Version: 2.5
Name: hikarugo-backend
Version: 0.1.2
Summary: HikaruGo (棋魂) - 智能围棋 AI 教学与对弈分析平台后端服务
Project-URL: Homepage, https://github.com/CoCongV/HikaruGo
Project-URL: Repository, https://github.com/CoCongV/HikaruGo
Project-URL: Issues, https://github.com/CoCongV/HikaruGo/issues
Author-email: CoCongV <cong.lv.yx@gmail.com>
License-Expression: MIT
Keywords: ai,baduk,fastapi,go,hikarugo,katago,teaching,weiqi
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: sqlmodel>=0.0.16
Requires-Dist: uvicorn[standard]>=0.28.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# HikaruGo Backend (棋魂后端服务)

[![PyPI version](https://img.shields.io/pypi/v/hikarugo-backend.svg)](https://pypi.org/project/hikarugo-backend/)
[![Python versions](https://img.shields.io/pypi/pyversions/hikarugo-backend.svg)](https://pypi.org/project/hikarugo-backend/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**HikaruGo** 是一款全栈现代化的智能围棋 AI 教学与对弈分析平台。本仓库为 HikaruGo 的后端 API 服务，基于 FastAPI、SQLModel、KataGo 围棋引擎与大语言模型（LLM）构建。

---

## 🌟 核心特性

- **完整的围棋规则核心引擎**：
  - 支持 9路、13路、19路 棋盘。
  - 精确实现气数计算、连通块提子、自杀禁着点、打劫（Ko 规则）以及双 Pass 终局判定与数目胜负结算。
- **KataGo 深度神经网络集成**：
  - 支持多难度 AI 对弈（30级 ~ 9段）。
  - 实时胜率预测、目数差分析与 top-N AI 推荐落子选点。
- **AI 智能围棋导师（Hermes / LLM 互动）**：
  - 基于大模型流式（SSE / WebSocket）问答。
  - 结合 KataGo 局面深度分析数据与 SGF 棋谱上下文，进行专业细致的棋局指导与复盘解答。
- **SGF 棋谱导入与导出**：
  - 标准 SGF 格式解析与生成，支持棋谱复盘与局势复现。
- **RESTful API & WebSocket 实时通信**：
  - 提供用户认证（JWT）、对局管理、落子、观战及实时对局推送。
- **内置 CLI 运维工具**：
  - 提供一键启动服务、管理员账户初始化与权限管理命令行工具。

---

## 📦 安装

推荐使用 `pip` 或 `uv` 进行安装：

```bash
# 使用 pip
pip install hikarugo-backend

# 或使用 uv
uv pip install hikarugo-backend
```

---

## 🚀 快速启动

### 1. 使用命令行启动服务

安装完成后，可直接使用内置 CLI 指令：

```bash
# 默认启动于 0.0.0.0:8000
hikarugo serve

# 自定义端口和热重载
hikarugo serve --host 127.0.0.1 --port 8000 --reload
```

### 2. 创建或设置超级管理员

```bash
hikarugo create-admin --username admin --email admin@example.com
```

### 3. 查看交互式 API 文档

服务启动后，在浏览器中访问：
- **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)
- **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc)

---

## ⚙️ 环境变量配置

支持通过环境变量或项目根目录下的 `.env` 文件进行配置：

| 环境变量 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `DATABASE_URL` | `sqlite:///./data/hikarugo.db` | 数据库连接字符串（支持 SQLite / PostgreSQL / MySQL） |
| `SECRET_KEY` | `hikarugo-dev-secret-key-2026` | JWT 鉴权签名密钥（生产环境请务必修改） |
| `ACCESS_TOKEN_EXPIRE_MINUTES`| `10080` (7天) | 登录 Token 有效期（分钟） |
| `KATAGO_SERVER_URL` | `http://localhost:2718` | KataGo REST 服务端地址 |
| `KATAGO_MAX_VISITS` | `20` | KataGo 计算搜索次数（开发环境建议 20，生产环境可配置为 200~800） |
| `KATAGO_TIMEOUT` | `300` | KataGo 请求超时时间（秒） |
| `CHAT_API_URL` | `""` | LLM 导师 Chat Completions API 地址（兼容 OpenAI 规范） |
| `CHAT_API_KEY` | `""` | LLM 导师 API 访问密钥 |
| `CHAT_API_MODEL` | `mimo-v2.5` | LLM 模型名称 |

---

## 📂 项目结构

```text
backend/
├── app/
│   ├── main.py              # FastAPI 应用实例与路由挂载
│   ├── cli.py               # Click 命令行运维入口 (hikarugo / hikarugo-server)
│   ├── core/                # 核心配置、数据库连接与安全认证 (JWT)
│   ├── models/              # SQLModel 数据模型 (User, Game, Move)
│   ├── routes/              # API 路由 (auth, game, analysis, sgf, ws, users)
│   ├── services/            # 业务服务 (go_engine, katago, hermes)
│   └── utils/               # SGF 棋谱解析等工具类
├── tests/                   # Pytest 单元测试与压测套件
└── pyproject.toml           # 项目元数据与依赖配置
```

---

## 🧪 运行测试

```bash
# 运行单元测试
pytest

# 运行覆盖率测试并生成 HTML 报告
pytest --cov=app --cov-report=html --cov-report=term
```

---

## 📄 开源协议

本项目采用 [MIT License](https://opensource.org/licenses/MIT) 开源授权。
