# 项目名称：云顶之弈阵容推荐器
## 概述
本项目旨在基于 Riot 官方提供的云顶之弈数据（包括职业、特质、棋子信息）实现自动化的阵容推荐。通过一系列可配置的评分机制，项目能够输出一套最优的阵容组合。本 README 将详细介绍项目功能、模块设计、开发环境、使用方法及开发要点，方便后续的代码实现与维护。
---
## 目标功能
1. **数据提供模块**
* 从本地或在线接口获取最新的「职业（job）」「特质（race）」「棋子（chess）」数据。
* 提供统一的查询接口：
* 获取指定羁绊（职业/特质）的所有可用棋子
* 获取某个棋子的所有羁绊
* 获取所有羁绊列表
* 获取某个棋子的详细信息
* 获取某个羁绊的详细信息
* 支持缓存与数据更新，确保系统在多次查询时有较快的响应速度。
2. **阵容推荐模块**
* 根据指定的阵容需求（人口数量、必须包含的羁绊/棋子等）自动生成当前版本云顶之弈中合理的阵容。
* 兼容多羁绊、多棋子等多种复杂输入，生成符合要求的多个可行阵容。
* 将所有候选阵容进行分数计算并择优返回最高得分阵容。
3. **阵容评分模块**
* 提供评分系统，对阵容进行综合打分：
* 考虑羁绊数量及羁绊等级（如：2重装、4重装、6重装等触发效果）。
* 考虑棋子的费用、属性强度、技能等基础输出或耐久能力。
* 提供默认评分权重（例如羁绊优先度、棋子星级、费用等），并允许自定义权重配置（通过配置文件覆盖默认值）。
* 保证评分算法可扩展性，后续可集成更复杂的策略或外部数据（如胜率、大数据统计等）。
4. **接口模块**
* 提供外部可调用的API，接收下列可能的输入条件：
* 指定人口（如 8 人口或 9 人口阵容）。
* 指定必须包含的羁绊（一个或多个）。
* 指定必须包含的棋子（一个或多个）。
* 其它自定义约束条件（如费用上限、指定主C等）。
* 调用数据提供模块和阵容推荐模块完成计算后，将结果（最佳阵容或多套可行阵容）返回给调用方。
---
## 环境和依赖
* **开发语言：** Python 3.8 或更高版本
* **主要依赖库（示例）：**
* `requests`：在线获取官方数据
* `pandas`：数据处理库，用于数据筛选、分析等
* `pyyaml`：配置文件解析库，用于加载自定义权重配置
* 其他依赖请根据实际需求添加
安装依赖示例：
```bash
pip install -r requirements.txt
```
---
## 项目结构
下面是建议的项目目录结构，供参考和进一步修改：
```
.
├── data/
│ ├── job.json # 职业数据（从官方api获取后存放本地）
│ ├── race.json # 特质数据
│ └── chess.json # 棋子数据
├── config/
│ └── score_config.yaml # (可选)自定义评分权重配置文件
├── src/
│ ├── data_provider/
│ │ ├── data_loader.py # 从本地或在线获取数据的逻辑
│ │ └── data_query_api.py # 提供对外的数据查询API
│ ├── recommendation/
│ │ └── composition_recommender.py # 阵容推荐模块核心逻辑
│ ├── scoring/
│ │ └── score_calculator.py # 阵容评分模块
│ └── interface/
│ └── api.py # 对外接口模块
├── tests/
│ ├── test_data_provider.py
│ ├── test_recommendation.py
│ ├── test_scoring.py
│ └── test_api.py
├── README.md
└── requirements.txt
```
各模块功能说明：
1. **`data_loader.py`**
* 负责从本地文件或在线接口获取最新的 job/race/chess 数据。
* 每次启动时更新数据。
* 在线接口：
* `'chess': 'https://game.gtimg.cn/images/lol/act/img/tft/js/chess.js'`
* `'job': 'https://game.gtimg.cn/images/lol/act/img/tft/js/job.js'`
* `'race': 'https://game.gtimg.cn/images/lol/act/img/tft/js/race.js'`
2. **`data_query_api.py`**
* 读取 `data_loader` 载入的数据并对外提供查询功能：
* 获取指定羁绊下的所有棋子
* 获取棋子的所有羁绊
* 获取某个羁绊/棋子的详细信息
* 其它辅助查询方法。
3. **`composition_recommender.py`**
* 接收需求参数（如人口、羁绊、棋子）进行阵容搜索与组合。
* 生成所有可能的组合后，调用 **评分模块** 对组合评分。
* 推荐评分最高的一套或多套阵容输出。
* 推荐逻辑可参考：
* *基于羁绊的优先级：* 每当阵容中某一羁绊人数接近下一等级阈值时，可优先考虑补充同羁绊棋子。
* *基于棋子价值：* 根据棋子费用、技能强度等优先选择高价值棋子，但要平衡费用和羁绊需求。
4. **`score_calculator.py`**
* 根据提供的评分配置（默认或自定义）对给定阵容进行评分：
* *羁绊评分：* 如 2重装、4重装、6重装等带来的收益加分。
* *棋子评分：* 根据费用、技能伤害、攻防属性等进行综合评估。
* *人口/星级加成：* 如果同一个棋子假设有星级等维度，也可作为额外加分点。
* 如果有 `score_config.yaml`，则读取自定义权重覆盖默认值。
* 返回阵容总得分，供推荐模块最终排序使用。
5. **`api.py`**
* 提供对外可调用的API函数或 RESTful 接口：
* 接口示例：
```python
def get_recommended_composition( population=8, required_syns=None, # 必须包含的羁绊 required_champs=None, # 必须包含的棋子 score_config_path=None): """ 外部可调用的主要函数: 1. 从 data_query_api 获取基础数据 2. 调用 composition_recommender 生成所有可行阵容 3. 调用 score_calculator 对阵容评分 4. 返回最优阵容 """ ...
```
---
## 使用说明
1. **获取数据**
* 每次启动时，从官方接口获取数据，存放在内存缓存或本地文件中
* 若数据获取失败，应用退出
* 数据格式：
* job：
* ```json
{
"version": "15.7",
"season": "2025.S14",
"modeId": "1",
"time": "2025-04-01 14:31:07",
"data": [
{
"jobId": "10155",
"name": "超频战士",
"traitId": "10155",
"introduce": "【超频战士】们可以通过该羁绊专有的【超频】属性来给他们的技能提供独特增强。",
"alias": "10155.png",
"level": {
"2": "+1 【超频】属性, 100 生命值",
"3": "+2 【超频】属性, 200 生命值",
"4": "+3 【超频】属性, 350 生命值",
"5": "+4 【超频】属性, 500 生命值"
},
"TFTID": "10155",
"characterid": "TFT14_Supercharge",
"id": "2623",
"imagePath": "https://game.gtimg.cn/images/lol/act/img/tft/classes/10155.png",
"job_color_list": "2:1,3:2,4:3,5:3"
},
{
"jobId": "10157",
"name": "重装战士",
"traitId": "10157",
"introduce": "【重装战士】们在有护盾时获得10%伤害减免。\r\n战斗开始时和50%生命值时：获得一部分最大生命值的护盾值，持续10秒。",
"alias": "10157.png",
"level": {
"2": "16%最大生命值",
"4": "32%最大生命值",
"6": "40%最大生命值；在有护盾时获得16% 伤害减免"
},
"TFTID": "10157",
"characterid": "TFT14_Vanguard",
"id": "2624",
"imagePath": "https://game.gtimg.cn/images/lol/act/img/tft/classes/10157.png",
"job_color_list": "2:1,4:2,6:3"
},
......
```
* chess:
* ```json
{
"version": "15.7",
"season": "2025.S14",
"modeId": "1",
"time": "2025-04-01 14:31:07",
"data": [
{
"raceId": "10153",
"name": "圣灵使者",
"traitId": "10153",
"introduce": "【圣灵使者】弈子会为你的小队提供独特的属性，该加成会随着已登场的【圣灵使者】弈子数量而提升。\r\n【圣灵使者】弈子们获得双倍。",
"alias": "10153.png",
"level": {
"1": "100% 加成。",
"2": "110% 加成。",
"3": "125% 加成。",
"4": "140% 加成。",
"5": "160% 加成。",
"6": "180% 加成。",
"7": "200% 加成。"
},
"TFTID": "10153",
"characterid": "TFT14_Divinicorp",
"id": "2727",
"imagePath": "https://game.gtimg.cn/images/lol/act/img/tft/origins/10153.png",
"race_color_list": "1:1,2:2,3:2,4:3,5:3,6:3,7:4"
},
{
"raceId": "10154",
"name": "街头恶魔",
"traitId": "10154",
"introduce": "在【彩绘格】中的友军将获得生命值、法术强度和攻击力。一些格子是【签名格】并多提供50%此加成。\r\n【街头恶魔】使所有此加成翻倍。",
"alias": "10154.png",
"level": {
"3": "+6% 生命值,6 法术强度,6% 攻击力",
"5": "+10% 生命值,10 法术强度,10% 攻击力",
"7": "+6% 生命值,15 法术强度,15% 攻击力",
"10": "+50% 生命值,50 法术强度,50% 攻击力，尽情绘画！"
},
"TFTID": "10154",
"characterid": "TFT14_StreetDemon",
"id": "2728",
"imagePath": "https://game.gtimg.cn/images/lol/act/img/tft/origins/10154.png",
"race_color_list": "3:1,5:2,7:3,10:4"
},
```
* race:
* ```json
{
"version": "15.7",
"season": "2025.S14",
"modeId": "1",
"time": "2025-04-01 14:31:07",
"data": [
{
"raceId": "10153",
"name": "圣灵使者",
"traitId": "10153",
"introduce": "【圣灵使者】弈子会为你的小队提供独特的属性，该加成会随着已登场的【圣灵使者】弈子数量而提升。\r\n【圣灵使者】弈子们获得双倍。",
"alias": "10153.png",
"level": {
"1": "100% 加成。",
"2": "110% 加成。",
"3": "125% 加成。",
"4": "140% 加成。",
"5": "160% 加成。",
"6": "180% 加成。",
"7": "200% 加成。"
},
"TFTID": "10153",
"characterid": "TFT14_Divinicorp",
"id": "2727",
"imagePath": "https://game.gtimg.cn/images/lol/act/img/tft/origins/10153.png",
"race_color_list": "1:1,2:2,3:2,4:3,5:3,6:3,7:4"
},
{
"raceId": "10154",
"name": "街头恶魔",
"traitId": "10154",
"introduce": "在【彩绘格】中的友军将获得生命值、法术强度和攻击力。一些格子是【签名格】并多提供50%此加成。\r\n【街头恶魔】使所有此加成翻倍。",
"alias": "10154.png",
"level": {
"3": "+6% 生命值,6 法术强度,6% 攻击力",
"5": "+10% 生命值,10 法术强度,10% 攻击力",
"7": "+6% 生命值,15 法术强度,15% 攻击力",
"10": "+50% 生命值,50 法术强度,50% 攻击力，尽情绘画！"
},
"TFTID": "10154",
"characterid": "TFT14_StreetDemon",
"id": "2728",
"imagePath": "https://game.gtimg.cn/images/lol/act/img/tft/origins/10154.png",
"race_color_list": "3:1,5:2,7:3,10:4"
},
```
2. **定制评分**
* 在 `config/score_config.yaml` 文件中写入自定义的评分权重，例如：
```yaml
synergy_weight: base: 1.0 重装战士: 1.2 # 重装战士特殊加成 ...champion_weight: base_price_factor: 0.5 ...
```
* 也可直接在 `score_calculator.py` 模块中写死默认权重，不使用配置文件。
3. **调用推荐接口**
* 在命令行 / 脚本中：
```python
from src.interface.api import get_recommended_compositionbest_comp = get_recommended_composition( population=8, required_syns=['重装战士', '街头恶魔'], required_champs=['布兰德'], score_config_path='config/score_config.yaml')print(best_comp)
```
* 如果实现了网页接口或CLI，可直接通过相应方式进行调用。
4. **扩展性**
* 通过新增或修改数据文件，可无缝整合新版本羁绊、棋子数据。
* 评分系统可根据策略和经验进行不断迭代。
---
## 测试
* 建议使用 `pytest` 或 `unittest` 进行测试：
* `test_data_provider.py`：测试数据加载和查询的正确性。
* `test_recommendation.py`：测试阵容推荐逻辑在各种输入条件下是否能正确生成可行阵容。
* `test_scoring.py`：测试评分结果是否符合预期（含默认权重与自定义权重）。
* `test_api.py`：测试对外接口的可用性和稳定性。
---
## 深度思考与注意事项
1. **数据版本与兼容性**
* 云顶之弈更新频繁，羁绊及棋子经常变动。为保证兼容性和可持续维护，需要在数据模块中预留多版本并行处理或自动更新的机制。
* 可以在数据库或文件系统中记录不同版本的 json 数据，并通过接口指定使用哪个版本。
2. **羁绊冲突与优先级**
* 部分羁绊可能存在冲突（如同时带来的属性相互覆盖）或并不兼容，需要在推荐阵容时自行过滤或降低评分。
* 在评分系统中，应设定羁绊上限规则（如某些羁绊过量堆叠收益递减）。
3. **棋子升星问题**
* 不考虑棋子升星问题
4. **性能**
* 若人口和可选棋子规模较大，暴力穷举组合的时间开销可能很高，需要考虑使用回溯、剪枝、启发式算法、或动态规划方式加速推荐过程。
5. **配置管理**
* 对于多种参数（如羁绊优先级、棋子费用优先级、特定羁绊的特殊加成等），建议使用统一配置文件管理，减少魔法值散落于代码。
* 同时要注意不同格式（JSON/YAML/INI）的使用，保持一致性。
---
## 结语
此项目聚焦于云顶之弈的阵容搭配与推荐，核心思路是利用官方提供的职业（job）、特质（race）及棋子（chess）数据，通过一套灵活可扩展的评分系统，为特定版本提供自动化、高质量的阵容建议。
如需进一步扩展，也可对接大数据平台，采集高分段玩家的对局数据，构建更准确的胜率模型和评分模型，从而不断优化 推荐器 的效果。
若有任何疑问或改进建议，欢迎在项目中提出 Issue 或 Pull Request，让我们一起将该项目做得更完善、易用、智能。祝各位在云顶之弈的旅程中诸神之巅！