LoL History API

这是一个用于《英雄联盟》战绩查询和数据分析的 Python 项目。它支持 League Client（LCU）、SGP和 HTTP API，并提供 Python SDK、趋势分析、只读分享页面和可选的 AI 教练分析。

当前版本：0.6.1

功能

• 获取玩家信息、段位和最近对局。
• 使用 SQLite 持久化历史战绩。
• 按时间窗口分页获取历史对局并自动去重。
• 支持全部、排位、海克斯大乱斗、斗魂竞技场、普通和其他模式。
• 提供胜率、每日表现、英雄池和位置分布分析。
• 生成无需额外点击的只读分享链接。
• 可选接入 DeepSeek，生成 AI 教练总结和训练计划。
• 提供同步 Python SDK，方便机器人或其他应用调用。

项目结构

lol-history-api/
|-- lol_history_api/
|   |-- api/                    # HTTP routes and validation
|   |-- application/            # Application services and use cases
|   |-- config/                 # Environment variables and defaults
|   |-- domain/                 # Trends, modes, and match analysis
|   |-- infrastructure/         # LCU, SGP, AI, and SQLite
|   |-- sdk/                    # Python SDK
|   `-- web/                    # Dashboard and read-only pages
|-- tests/                      # Automated tests
|-- Scripts/                    # Startup and release scripts
|-- docs/                       # Chinese documentation
|-- .env.example                # Configuration template
|-- pyproject.toml              # Package metadata and CLI entry
|-- start.bat                   # Windows one-click startup
`-- README.md

The project is layered as HTTP API -> application -> domain -> infrastructure for easier parallel development.

环境要求

• Python 3.10 或更高版本。
• Windows 10/11（需要读取本机 League Client 时）。
• League Client 已启动并登录，才能查询真实 LCU 数据。
• Linux 云服务器可以部署 API、Nginx 和分享页面，但不能替代 League Client。

安装

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

环境变量

.env 只保存在本地或服务器安全目录中，禁止提交到 GitHub。

启动

在项目根目录双击 start.bat，或执行：

.\Scripts\start_api.ps1

显式指定监听地址：

.\Scripts\start_api.ps1 `
    -BindAddress 100.107.221.69 `
    -Port 18181

PyPI 安装后：

python -m pip install lol-history-api==0.6.1
lol-history-api

API 接口

GET  /health
GET  /lol/regions
GET  /lol/player
GET  /lol/history
GET  /lol/trends
POST /lol/trends/share
GET  /shared/{share_id}
GET  /ai/status
GET  /lol/coach/ai

趋势查询示例：

GET /lol/trends?game_name=Player&tag_line=1234&region=HN10&days=30&mode=ranked

mode 支持：all、ranked、aram、arena、normal 和 other。

趋势刷新会按页获取历史对局，直到覆盖指定时间窗口或上游没有更多数据，并通过 game_id 自动去重。

Python SDK

from lol_history_api import LoLHistoryClient

client = LoLHistoryClient("http://127.0.0.1:18181", "your-bridge-token")
report = client.trends("Player", "1234", region="HN10", mode="ranked", days=30)
share = client.create_trend_share(
    "Player", "1234", region="HN10", mode="ranked",
    days=30, refresh=True, include_ai=True,
)
print(share["url"])

分享链接是只读快照，打开后直接展示完整报告。

多人协作

推荐分支结构：

main          稳定版本和生产发布
develop       日常集成
feature/*     新功能
fix/*         问题修复
docs/*        文档修改

git checkout develop
git pull
git checkout -b feature/your-feature
python -B -m pytest tests -q
python -B -m compileall -q lol_history_api

GitHub Actions 会自动执行测试。详细规范见 CONTRIBUTING.md。

云服务器部署

建议使用独立目录 /opt/lol-history-api/，不要与 QQBot 共用目录、虚拟环境或数据库。

Nginx :18080
    
127.0.0.1:18181
    
lol-history-api systemd service

服务器上的 .env、Token、AI Key、SSH 私钥和 SQLite 数据库都不进入 Git 仓库。

测试与发布

python -B -m pytest tests -q
python -m build
python -m twine check dist/*

在 .env 中配置 PYPI_TOKEN 后，运行 Scripts/publish_pypi.bat 发布。

安全注意

• 不要提交 .env、SQLite 数据库、日志、构建产物和真实 Token。
• 不要在 Issue、Pull Request 或聊天中发送 AI Key、SSH 私钥和服务器密码。
• 不要让所有开发者共用 root 密码。