HikaruGo Backend (棋魂后端服务)

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 进行安装：

# 使用 pip
pip install hikarugo-backend

# 或使用 uv
uv pip install hikarugo-backend

🚀 快速启动

1. 使用命令行启动服务

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

# 默认启动于 0.0.0.0:8000
hikarugo serve

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

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

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

3. 查看交互式 API 文档

服务启动后，在浏览器中访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

⚙️ 环境变量配置

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

📂 项目结构

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           # 项目元数据与依赖配置

🧪 运行测试

# 运行单元测试
pytest

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

📄 开源协议

本项目采用 MIT License 开源授权。