lsamc

kards-env

Fork 0

6.1 KiB

Raw Permalink Blame History

KARDS 引擎API一致性检查报告

1. 概述

本报告分析了KARDS战斗引擎中不同模块和版本之间API接口的一致性问题，并提供修复建议。

2. 主要发现的不一致问题

2.1 引擎类参数不一致

问题描述: 不同引擎版本的构造函数参数不统一

当前引擎BattleEngine:

def __init__(self, player1_name: str, player2_name: str, debug_mode: bool = False)

历史引擎版本:

# GameEngineV2/V3
def __init__(self, player1_id: str, player2_id: str)

# GameEngine
def __init__(self, player1_id: str, player2_id: str)

影响:

测试代码中混用player_id字符串和整数参数
部分测试使用字符串参数调用BattleEngine方法

2.2 部署接口不统一

BattleEngine (当前主引擎):

def deploy_unit_to_support(self, unit: Unit, player_id: int, position: Optional[int] = None)

其他引擎版本存在的接口:

# GameEngineV2
def deploy_unit_to_front(self, unit: Unit, player_id: str)

# GameEngine
def deploy_unit(self, unit: Unit, player_id: str, line_type, position: int)

# test_system.py中发现
engine.deploy_unit(panzer, "Germany", LineType.FRONT, 2)

不一致点:

参数类型：int vs str for player_id
参数顺序和数量不同
不同的方法名称

2.3 移动接口不统一

BattleEngine:

def move_unit(self, unit_id: UUID, target_position: tuple, player_id: int)

其他版本:

# GameEngineV2 
def move_unit_to_front(self, unit_id: UUID)  # 缺少player_id参数

2.4 攻击接口不统一

BattleEngine:

def attack_target(self, attacker_id: UUID, target_id: Union[UUID, str], player_id: int)

其他版本:

# GameEngine
def attack_unit(self, attacker_id: UUID, target_id: UUID)  # 缺少player_id参数

3. 测试代码中的不一致使用

3.1 player_id参数类型混用

发现的问题:

# 正确用法 (BattleEngine)
engine.deploy_unit_to_support(unit, 0)
engine.move_unit(unit.id, (LineType.FRONT, 0), 0)

# 错误用法 - 使用字符串
engine.deploy_unit_to_support(german_inf, "Germany")  # 应该是整数0
engine.move_unit(german_inf.id, (LineType.FRONT, 0), "Germany")  # 应该是整数0

影响文件:

tests/unit/test_battle_engine.py
tests/integration/test_corrected_battlefield.py
tests/integration/test_new_battlefield.py

3.2 不存在的方法调用

发现的过时方法调用:

# 这些方法在当前BattleEngine中不存在
engine.deploy_unit_to_front(german_infantry, "Germany")
engine.move_unit_to_front(sherman.id)
engine.deploy_unit(panzer, "Germany", LineType.FRONT, 2)
engine.attack_unit(p51.id, bf109.id)

4. CommandParser中的接口使用

当前状态: CommandParser正确使用了BattleEngine的API

# command_parser.py - 正确用法
result = self.engine.deploy_unit_to_support(unit, player_id, position)
result = self.engine.move_unit(unit.id, (line_type, target_pos), self.engine.active_player)
result = self.engine.attack_target(attacker.id, target_id, self.engine.active_player)

5. 修复建议

5.1 立即修复项

A. 修复测试代码中的参数类型错误

# 需要修改的文件和模式
# tests/unit/test_battle_engine.py
- engine.move_unit(german_inf.id, (LineType.FRONT, 0), "Germany")
+ engine.move_unit(german_inf.id, (LineType.FRONT, 0), 0)

- engine.attack_target(american_gi.id, german_inf.id, "USA")  
+ engine.attack_target(american_gi.id, german_inf.id, 1)

# 其他相关测试文件类似修改

B. 创建player_id映射函数

# 在测试辅助函数中添加
def get_player_id(player_name: str) -> int:
    """将玩家名称转换为player_id"""
    mapping = {"Germany": 0, "USA": 1}
    return mapping.get(player_name, 0)

5.2 长期规范化建议

A. 统一引擎接口

保持BattleEngine作为主接口
废弃其他引擎版本，移至archive目录
标准化参数类型：使用int作为player_id

B. 接口版本控制

# 为向后兼容添加适配层
class BattleEngine:
    def deploy_unit_to_support(self, unit: Unit, player_id: Union[int, str], position: Optional[int] = None):
        if isinstance(player_id, str):
            # 兼容性转换
            player_id = {"Germany": 0, "USA": 1}.get(player_id, 0)
        # 继续原有逻辑

C. 创建统一的测试基类

class BaseEngineTest:
    def setUp(self):
        self.engine = BattleEngine("Germany", "USA")
        
    def deploy_unit(self, unit: Unit, player_name: str):
        player_id = 0 if player_name == "Germany" else 1
        return self.engine.deploy_unit_to_support(unit, player_id)

6. API验证清单

6.1 核心API一致性检查

BattleEngine: 接口定义明确且一致
CommandParser: 正确使用BattleEngine接口
测试代码: 存在参数类型不匹配问题
历史引擎: 接口不兼容，需要废弃或适配

6.2 参数验证

player_id类型: BattleEngine使用int，与文档一致
返回值格式: 统一使用{"success": bool, ...}格式
错误处理: 统一返回详细错误信息
测试参数: 部分测试使用错误的参数类型

7. 推荐修复优先级

P0 (立即修复)

修复test_battle_engine.py中的参数类型错误
移除对不存在方法的调用

P1 (短期修复)

创建测试辅助函数统一参数转换
更新所有相关测试文件

P2 (长期优化)

清理历史引擎代码
建立API版本控制机制
创建完整的接口测试套件

8. 结论

当前BattleEngine的API接口设计是一致和完整的，主要问题集中在：

测试代码使用了错误的参数类型 (字符串 vs 整数)
历史引擎版本接口不兼容，应该移除或归档
部分测试调用了不存在的方法

通过修复测试代码中的参数错误和移除历史引擎依赖，可以实现完全的API一致性。

总体评估: API设计良好，需要的是测试代码的修正而非接口重构。

6.1 KiB Raw Permalink Blame History Unescape Escape