# 云顶之弈阵容推荐器

## 项目概述

本项目是一个基于Python的云顶之弈阵容推荐工具，通过Riot官方提供的游戏数据（职业、特质、棋子），实现自动化的阵容分析与推荐。项目具有灵活的评分机制，能够根据用户需求（如指定人口、羁绊、棋子等）智能推荐最优阵容。

## 主要功能

1. **数据提供模块**
   - 从官方接口获取最新游戏数据并支持本地缓存
   - 提供丰富的数据查询API，如获取羁绊下的棋子、棋子的羁绊详情等
   - 高效的数据处理与缓存机制

2. **阵容推荐模块**
   - 根据用户指定的人口、必须羁绊、必选棋子自动生成阵容
   - 支持多种约束条件组合，如指定多个羁绊、多个棋子等
   - 智能选择最佳棋子组合，最大化羁绊效果

3. **阵容评分模块**
   - 综合考虑羁绊数量、等级、棋子费用等因素
   - 可配置的评分权重，支持自定义评分策略
   - 多维度评估阵容强度，提供量化的阵容分析
   - **支持通过外置配置文件为特定羁绊或棋子设置自定义权重**

4. **接口模块**
   - 提供编程接口，方便集成到其他应用中
   - 交互式命令行界面，便于直接使用
   - 支持自定义评分参数

5. **Web界面模块**
   - 基于Flask的Web界面，提供图形化操作体验
   - 可视化显示阵容推荐结果
   - 支持在线调整权重参数与配置

## 环境与依赖

- **Python版本:** Python 3.8+
- **主要依赖:**
  - requests: 用于获取在线数据
  - pandas: 用于数据处理
  - pyyaml: 用于配置文件解析
  - numpy: 用于数值计算
  - flask: 用于Web界面
  - flask-cors: 处理跨域请求
  - waitress: 生产环境Web服务器
  - pytest: 用于单元测试
  - tqdm: 用于进度显示

## 项目安装

1. 克隆项目代码
```bash
git clone https://github.com/username/TFT-Strategist.git
cd TFT-Strategist
```

2. 安装依赖
```bash
pip install -r requirements.txt
```

## 快速开始

### 查看帮助信息

运行以下命令查看主程序的帮助信息：

```bash
python main.py --help
```

输出结果会显示所有可用的子命令和选项。

### Web界面

运行以下命令启动Web界面：

```bash
python main.py web
```

默认情况下，Web服务器将在`http://localhost:5000`上运行。您可以使用以下参数自定义服务器配置：

- `--host`: 指定服务器主机地址，默认为"0.0.0.0"（允许所有网络接口访问）
- `--port`: 指定服务器端口，默认为5000
- `--dev`: 启用开发模式（开启调试功能，自动重载代码）
- `--config`: 指定自定义配置文件路径

例如：
```bash
python main.py web --host 127.0.0.1 --port 8080 --dev
```

Web界面提供以下功能：
- 通过滑动条调整基础权重（羁绊等级权重、羁绊数量权重、棋子费用权重）
- 为每个具体的羁绊和棋子设置自定义权重
- 指定必选羁绊和必选棋子
- 一键生成最佳阵容并可视化显示
- 支持筛选显示已激活的羁绊和棋子

### 数据提供模块演示

运行以下命令启动数据提供模块的演示程序：

```bash
python main.py data
```

演示程序将展示以下功能：
- 加载最新的游戏数据
- 显示当前版本职业、特质和棋子的基本信息
- 提供交互式查询界面，可以查询羁绊的棋子、棋子的羁绊等信息

### 阵容推荐模块演示

运行以下命令启动阵容推荐模块的演示程序：

```bash
python main.py recommend
```

演示程序将提供以下功能：
- 指定人口数量生成最佳阵容
- 指定必选羁绊生成阵容
- 指定必选棋子生成阵容
- 综合多种条件生成最优阵容

### 评分系统演示

运行以下命令启动评分系统的演示程序：

```bash
python main.py scoring
```

演示程序将展示以下功能：
- 使用默认权重进行阵容评分
- 使用配置文件中的自定义权重进行评分
- 通过代码动态设置特定羁绊和棋子的权重
- 比较不同权重设置下的评分差异
- 动态修改配置文件并重新加载

您还可以指定自定义配置文件：

```bash
python main.py scoring --config path/to/custom_config.yaml
```

### 配置管理

运行以下命令管理权重配置：

```bash
python main.py config --show
```

配置管理提供以下功能：
- 显示当前所有权重配置
- 设置特定羁绊的权重
- 设置特定棋子的权重
- 设置基础权重参数

例如：
```bash
# 设置羁绊权重
python main.py config --set-synergy "超频战士" 1.5

# 设置棋子权重
python main.py config --set-chess "厄加特" 1.8

# 设置基础权重参数
python main.py config --set-base "synergy_level_weight" 1.2
```

### 命令行界面

运行以下命令启动交互式命令行界面：

```bash
python main.py cli
```

命令行界面提供以下功能：
- 指定阵容人口和评分参数
- 交互式添加必选羁绊和等级
- 交互式添加必选棋子
- 展示详细的阵容推荐结果，包括棋子信息和激活的羁绊

您还可以使用命令行参数自定义配置：
```bash
python main.py cli --population 8 --results 5 --level-weight 1.2 --count-weight 0.7 --cost-weight 0.2
```

参数说明：
- `--population`：阵容人口数量，范围1-10，默认为9
- `--results`：推荐结果数量，默认为3
- `--level-weight`：羁绊等级权重，默认为1.0
- `--count-weight`：羁绊数量权重，默认为0.5
- `--cost-weight`：棋子费用权重，默认为0.1
- `--config`：指定自定义配置文件路径

## 项目结构

```
TFT-Strategist/
├── data/                      # 数据存储目录
│   ├── chess.json             # 棋子数据
│   ├── job.json               # 职业数据
│   ├── race.json              # 特质数据
│   └── weights_config.yaml    # 自定义权重配置文件
├── src/                       # 源代码
│   ├── data_provider/         # 数据提供模块
│   │   ├── __init__.py
│   │   ├── data_loader.py     # 数据加载器
│   │   └── data_query_api.py  # 数据查询API
│   ├── recommendation/        # 阵容推荐模块
│   │   ├── __init__.py
│   │   └── recommendation_engine.py  # 阵容推荐引擎
│   ├── scoring/               # 阵容评分模块
│   │   ├── __init__.py
│   │   ├── scoring_system.py  # 阵容评分系统
│   │   └── config_loader.py   # 配置加载器
│   ├── interface/             # 接口模块
│   │   ├── __init__.py
│   │   ├── api.py             # 编程接口
│   │   └── cli.py             # 命令行界面
│   ├── config/                # 配置管理模块
│   │   ├── __init__.py
│   │   └── weights_config.py  # 权重配置管理
│   ├── web/                   # Web界面模块
│   │   ├── __init__.py
│   │   ├── app.py             # Flask应用
│   │   ├── static/            # 静态资源
│   │   │   ├── css/           # CSS样式
│   │   │   │   └── style.css
│   │   │   └── js/            # JavaScript脚本
│   │   │       └── main.js
│   │   └── templates/         # HTML模板
│   │       └── index.html
│   ├── __init__.py
│   ├── data_provider_demo.py  # 数据提供模块演示
│   ├── recommendation_demo.py # 阵容推荐模块演示
│   ├── scoring_demo.py        # 评分系统演示
│   └── test_scoring.py        # 评分测试模块
├── tests/                     # 测试代码
│   ├── test_data_provider.py  # 数据提供模块测试
│   ├── test_recommendation.py # 阵容推荐模块测试
│   └── test_interface.py      # 接口模块测试
├── main.py                    # 主程序入口
├── requirements.txt           # 项目依赖
├── test_direct.py             # 直接测试脚本
├── test_recommendation.py     # 阵容推荐测试脚本
├── generate_weights_config.py # 权重配置生成工具
├── get_data.py                # 数据获取工具
└── README.md                  # 项目文档
```

## 数据提供模块详解

数据提供模块是整个阵容推荐系统的基础，负责从官方接口获取最新的游戏数据，并提供丰富的查询功能。

### 主要组件

1. **DataLoader**: 负责数据获取与缓存
   - 支持从本地或网络加载数据
   - 实现数据缓存机制，避免频繁请求
   - 自动处理数据更新

2. **DataQueryAPI**: 提供丰富的数据查询接口
   - 获取所有职业/特质/棋子数据
   - 根据ID或名称查询具体数据
   - 查询羁绊下的棋子、棋子的羁绊
   - 获取羁绊等级信息
   - 查询棋子费用分布

### 使用示例

```python
from src.data_provider import DataQueryAPI

# 初始化API
api = DataQueryAPI()

# 获取所有职业
jobs = api.get_all_jobs()

# 查询特定羁绊的棋子
heavy_warrior = api.get_job_by_name("重装战士")
if heavy_warrior:
    chess_list = api.get_chess_by_job(heavy_warrior['jobId'])
    print(f"重装战士棋子: {[chess['displayName'] for chess in chess_list]}")

# 查询棋子的羁绊
brand = api.get_chess_by_name("布兰德")
if brand:
    synergies = api.get_synergies_of_chess(brand['chessId'])
    print(f"布兰德的羁绊: {[synergy['name'] for synergy in synergies]}")
```

## 阵容推荐模块详解

阵容推荐模块是系统的核心，能够根据用户需求生成最优阵容。

### 主要组件

1. **RecommendationEngine**: 阵容推荐引擎
   - 支持多种约束条件组合（人口、羁绊、棋子）
   - 智能选择最佳棋子组合
   - 内置多种推荐策略

2. **TeamComposition**: 阵容组合类
   - 表示一个完整的云顶之弈阵容
   - 包含棋子列表、羁绊统计等信息
   - 提供阵容分析功能

### 使用示例

```python
from src.data_provider import DataQueryAPI
from src.recommendation import RecommendationEngine
from src.scoring import TeamScorer

# 初始化API和推荐引擎
api = DataQueryAPI()
engine = RecommendationEngine(api=api)

# 指定人口推荐
teams = engine.recommend_team(population=9)

# 指定羁绊推荐
required_synergies = [
    {'name': '刺客', 'level': 4},
    {'name': '忍者', 'level': 1}
]
teams = engine.recommend_team(
    population=8,
    required_synergies=required_synergies
)

# 指定棋子推荐
required_chess = [
    {'name': '阿卡丽'},
    {'name': '劫'}
]
teams = engine.recommend_team(
    population=7,
    required_chess=required_chess
)

# 查看推荐结果
for team in teams:
    print(f"推荐阵容评分: {team.score}")
    print(f"阵容棋子: {[chess['displayName'] for chess in team.chess_list]}")
```

## 阵容评分模块详解

阵容评分模块是系统的核心评估组件，负责为推荐的阵容提供量化的评分指标。

### 主要组件

1. **TeamScorer**: 阵容评分器
   - 综合考虑羁绊数量、等级、棋子费用等因素
   - 支持自定义权重配置
   - 提供灵活的评分API

2. **ScoringConfig**: 评分配置类
   - 定义评分所需的各项权重参数
   - 提供默认配置值
   - 支持通过外部配置文件进行定制

3. **ConfigLoader**: 配置加载器
   - 从YAML或JSON文件加载评分配置
   - 支持热重载配置
   - 提供丰富的配置访问API

### 配置文件详解

系统支持通过YAML配置文件（data/weights_config.yaml）来自定义评分权重：

```yaml
# 基础权重配置
base_weights:
  synergy_level_weight: 1.0   # 羁绊等级权重
  synergy_count_weight: 0.5   # 羁绊数量权重
  chess_cost_weight: 0.1      # 棋子费用权重

# 羁绊权重配置
synergy_weights:
  重装战士: 1.5    # 特定羁绊权重
  魔法师: 1.2
  # 其他羁绊...

# 棋子权重配置
chess_weights:
  亚索: 1.5       # 特定棋子权重
  艾希: 1.2
  # 其他棋子...

# 羁绊等级权重
synergy_level_weights:
  '1': 1.0        # 1级羁绊权重
  '2': 1.2        # 2级羁绊权重
  # 其他等级...

# 棋子费用权重
cost_weights:
  '1': 1.0        # 1费棋子权重
  '2': 1.2        # 2费棋子权重
  # 其他费用...
```

配置文件中的权重设置将直接影响阵容评分结果。权重值越大，对应的因素在评分中的影响越大。

### 使用示例

```python
from src.scoring import TeamScorer
from src.data_provider import DataQueryAPI
from src.recommendation import RecommendationEngine

# 初始化评分器（自动加载配置文件）
scorer = TeamScorer()

# 或者指定配置文件路径
scorer = TeamScorer(config_path="path/to/custom_config.yaml")

# 动态修改权重
scorer.set_synergy_weight("忍者", 2.0)  # 提高"忍者"羁绊的权重
scorer.set_chess_weight("劫", 1.8)      # 提高"劫"的权重

# 重新加载配置文件
scorer.reload_config()

# 为阵容评分
api = DataQueryAPI()
engine = RecommendationEngine(api)
teams = engine.recommend_team(population=8)

for team in teams:
    score = scorer.score_team(team)
    print(f"阵容评分: {score}")
    print(f"棋子: {[chess['displayName'] for chess in team.chess_list]}")
    print(f"羁绊: {team.synergy_levels}")
```

## 接口模块详解

接口模块提供了便捷的方式与阵容推荐器进行交互，包括编程接口和命令行界面。

### 主要组件

1. **TFTStrategistAPI**: 编程接口类
   - 提供完整的数据查询功能
   - 提供阵容推荐和评分功能
   - 支持自定义评分参数

2. **TFTCommandLine**: 命令行界面类
   - 交互式用户界面
   - 支持添加必选羁绊和棋子
   - 详细展示阵容推荐结果

### 编程接口使用示例

```python
from src.interface import TFTStrategistAPI, get_api

# 使用单例模式获取API实例
api = get_api()

# 或者创建新的API实例
# api = TFTStrategistAPI(use_local_data=True)

# 获取游戏版本
version = api.get_version()
print(f"当前游戏版本: {version}")

# 自定义评分参数
api.customize_scoring(
    synergy_level_weight=1.2,
    synergy_count_weight=0.6,
    chess_cost_weight=0.15
)

# 获取职业和特质信息
jobs = api.get_all_jobs()
races = api.get_all_races()

# 推荐阵容
required_synergies = [{'name': '超频战士', 'level': 3}]
required_chess = [{'name': '薇古丝'}]

teams = api.recommend_team(
    population=8,
    required_synergies=required_synergies,
    required_chess=required_chess,
    max_results=3
)

# 处理推荐结果
for i, team in enumerate(teams, 1):
    print(f"\n推荐阵容 #{i} (评分: {team['score']:.2f})")
    print(f"棋子: {[chess['displayName'] for chess in team['chess_list']]}")
```

### 命令行界面使用

直接通过main.py运行命令行界面：

```bash
python main.py cli [参数]
```

可选参数：
- `--population`: 阵容人口数量，默认为9
- `--results`: 返回结果数量，默认为3
- `--level-weight`: 羁绊等级权重，默认为1.0
- `--count-weight`: 羁绊数量权重，默认为0.5
- `--cost-weight`: 棋子费用权重，默认为0.1

在交互界面中，您可以：
1. 添加必选羁绊并指定等级
2. 添加必选棋子
3. 获取详细的阵容推荐结果

## Web界面模块详解

Web界面模块提供了图形化的用户交互方式，基于Flask框架实现。

### 主要功能

1. **阵容推荐设置**
   - 可视化选择阵容人口
   - 添加/删除必选羁绊和棋子
   - 自定义权重调整

2. **阵容展示**
   - 直观显示推荐阵容棋子和羁绊
   - 支持多种排序和筛选方式
   - 详细的阵容分析数据

3. **配置管理**
   - 在线编辑权重配置
   - 保存和加载配置文件
   - 配置模板管理

### 启动方式

```bash
python main.py web [--host HOST] [--port PORT] [--dev] [--config CONFIG_PATH]
```

## 工具脚本

### generate_weights_config.py

用于生成初始权重配置文件，可根据游戏最新数据自动更新配置。

```bash
python generate_weights_config.py [--output OUTPUT_PATH]
```

### get_data.py

用于从官方接口获取最新游戏数据，支持手动更新。

```bash
python get_data.py [--force]
```

## 开发计划

- [x] 数据提供模块
- [x] 阵容推荐模块
- [x] 阵容评分模块
- [x] 接口模块
- [x] Web界面模块
- [x] 配置管理功能

## 未来展望

- [ ] 优化算法效率，支持更复杂的推荐策略
- [ ] 基于历史数据的胜率分析
- [ ] 支持装备推荐
- [ ] 多语言支持
- [ ] 基于机器学习的个性化推荐
- [ ] 移动端应用开发

## 贡献指南

欢迎贡献代码、报告问题或提出新功能建议！请先fork本仓库，然后提交拉取请求。

## 许可证

MIT

## 联系方式

如有任何问题或建议，请提交issue或联系项目维护者。