任务：实现系统指令处理模块（commands.py）

任务：实现系统指令处理模块（commands.py）

一、功能概述

在《极妙幻境》游戏中，玩家可以在任何场景下输入系统指令，以查看状态、获取帮助、退出游戏等。你需要实现一个模块 commands.py，负责解析和执行这些系统指令。所有指令的响应输出应为纯文本，供主循环直接显示。

二、模块位置与依赖

• 文件路径：src/game_logic/commands.py
• 依赖模块：
  • morality：需要 get_morality_ratios 函数。
  • llm_hint：需要 get_llm_hint 函数。
  • logging、os、json 等标准库。
• 输入：当前游戏状态字典 game_state，以及可选的 boss_fight 实例（用于 hint 指令）。

三、游戏状态数据结构约定

game_state 字典至少应包含以下字段：

game_state = {
    'layer': int,                # 当前层数
    'round': int,                 # 当前层内轮次
    'good': int,                   # 善值
    'neutral': int,                # 中立值
    'evil': int,                    # 恶值
    'layer_cards': List[Dict],     # 当前层获得的普通牌（每层重置），每个元素格式：{'type': 'good'|'evil'|'neutral', 'name': str, 'description': str}
    'wild_cards': List[Dict],      # 累积的万能牌（跨层），每个元素格式：{'type': 'wild', 'name': str, 'description': str}
    'in_boss_fight': bool,         # 是否在BOSS战中（可选）
}

四、指令列表

指令	可用场景	功能说明
HELP	任意	显示游戏帮助信息（从 texts/help.txt 读取）
PACK	任意	查看当前手牌（包括普通牌和万能牌）
STATUS	任意	查看当前道德比例和主导倾向
HINT	BOSS战中	请求AI队友提示（仅限BOSS战）
QUIT	任意	退出游戏

五、函数设计

5.1 主处理函数

def handle_system_command(
    cmd: str,
    game_state: dict,
    boss_fight: Optional[Any] = None
) -> dict:
    """
    处理系统指令。

    参数:
        cmd: 玩家输入的指令（大写，如 'HELP'）
        game_state: 当前游戏状态字典
        boss_fight: 如果处于BOSS战，传入 BossFight 实例，用于获取 hint 上下文

    返回:
        字典，包含以下字段：
        {
            'output': str,       # 需要显示给玩家的文本
            'should_quit': bool  # 是否应退出游戏（仅 quit 指令时 True）
        }
    """
    cmd = cmd.upper()
    if cmd == 'HELP':
        return handle_help()
    elif cmd == 'PACK':
        return handle_pack(game_state)
    elif cmd == 'STATUS':
        return handle_status(game_state)
    elif cmd == 'HINT':
        return handle_hint(game_state, boss_fight)
    elif cmd == 'QUIT':
        return handle_quit()
    else:
        return {
            'output': f"未知指令：{cmd}。输入 HELP 查看可用指令。",
            'should_quit': False
        }

5.2 各指令处理函数

5.2.1 handle_help()

• 功能：读取 texts/help.txt 文件内容并返回。
• 路径计算：

  PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
  HELP_FILE = os.path.join(PROJECT_ROOT, "texts", "help.txt")
  

• 错误处理：如果文件不存在，记录错误日志并返回 “帮助文件缺失，请联系开发者。”。
• 返回值：{'output': 文件内容或错误信息, 'should_quit': False}。

5.2.2 handle_pack(game_state)

• 功能：显示当前手牌。
• 输入：game_state 中的 layer_cards 和 wild_cards。
• 输出格式示例：

  【当前手牌】
  普通牌（共 X 张）：
    - 善牌：数量 N 张
        • 善心符 - 救助他人所得的善缘之符。
        • 慈悲心 - 一次慈悲之举的见证。
    - 恶牌：数量 M 张
        • 霸气符 - 以强凌弱所得的恶业之符。
    - 中立牌：数量 K 张
        • 观云牌 - 静观其变所得。
  万能牌（共 Y 张）：
    • 追影符 - 幻境中捕捉到的残影，可当作任意牌使用。
  

• 注意事项：如果某类型牌数量为0，可省略显示。如果所有牌为空，显示“暂无手牌”。
• 返回值：{'output': 格式化后的文本, 'should_quit': False}。

5.2.3 handle_status(game_state)

• 功能：显示道德比例和主导倾向。
• 依赖：需要从 morality 模块导入 get_morality_ratios。
• 计算：

  ratios = get_morality_ratios(game_state['good'], game_state['neutral'], game_state['evil'])
  dominant = ratios['dominant'] if ratios['dominant'] else '无'
  

• 输出格式示例：

  道德状态：
  善：45.5%（点数：45）
  中立：33.3%（点数：33）
  恶：21.2%（点数：21）
  主导倾向：善
  

• 返回值：{'output': 格式化后的文本, 'should_quit': False}。

5.2.4 handle_hint(game_state, boss_fight)

• 功能：在BOSS战中请求AI队友提示。
• 检查：如果 boss_fight 为 None，或 game_state.get('in_boss_fight') 为 False，返回“现在不是战斗时间，无法获取提示。”
• 获取上下文：调用 boss_fight.get_hint_context() 获取上下文字典（格式符合 llm_hint.get_llm_hint 要求）。
• 调用 llm_hint.get_llm_hint，传入上下文。
• 错误处理：如果返回 None，则返回“助手暂时无法提供建议，请稍后再试。”
• 返回值：{'output': 提示文本或错误信息, 'should_quit': False}。

5.2.5 handle_quit()

• 功能：退出游戏。
• 返回值：{'output': '游戏结束。', 'should_quit': True}。

六、帮助文件 texts/help.txt

请在项目根目录下创建 texts/help.txt 文件，内容如下（可包含 TODO 注释供后续优化）：

# TODO: 完善帮助信息，增加更详细的规则说明

【极妙幻境·游戏说明】

你误入极妙幻境，需经历10层幻境考验。每层20轮选择，你的每个决定都会影响道心（善/恶/中立），并积累相应卡牌。当某一倾向比例超过90%时，将触发极端结局。第4、7、10层有BOSS战，用积累的卡牌与心魔对战。

【指令说明】
- A/B/C/D：在普通轮次中选择对应选项。
- HELP：显示本帮助。
- PACK：查看当前手牌。
- STATUS：查看当前道德比例。
- HINT：BOSS战中请求AI队友提示（仅限BOSS战）。
- QUIT：退出游戏。

【BOSS战指令】
- follow <数量> <类型>：跟牌，如“follow 2 good”
- challenge：质疑
- fold：不跟

祝你好运！

七、错误处理与日志

• 在读取文件、调用LLM等可能失败的操作中，使用 try-except 捕获异常，使用 logging 记录错误信息（如 logger.error(...)）。
• 返回给用户的提示应简洁友好，不要暴露技术细节。

八、单元测试建议

创建 tests/test_commands.py，至少覆盖：

1. HELP 指令：模拟文件存在，验证返回内容为文件内容；模拟文件不存在，验证返回错误信息。
2. PACK 指令：构造不同的手牌组合，验证输出格式正确。
3. STATUS 指令：模拟道德值，验证比例计算和输出格式。
4. HINT 指令：模拟 BOSS 战中，mock boss_fight.get_hint_context 和 llm_hint.get_llm_hint，验证正常返回和失败返回。
5. QUIT 指令：验证 should_quit 为 True。
6. 未知指令：验证返回错误提示。

九、提交要求

• 创建 src/game_logic/commands.py 文件，包含上述所有实现。
• 创建 texts/help.txt 文件，包含示例帮助内容。
• 创建 tests/test_commands.py 文件，包含单元测试。
• 代码注释清晰，关键逻辑有说明。
• 确保所有测试通过。

开始实现吧！如有疑问，随时沟通。