FGO-py：自动化游戏操作的架构设计与实践指南

核心架构解析

FGO-py作为Fate/Grand Order的自动化助手工具，采用分层解耦架构设计，通过模块化组件实现游戏操作的自动化执行。核心系统由五大模块构成，各模块通过标准化接口通信，确保功能扩展与环境适配的灵活性。

模块设计与交互流程

• 设备控制层：通过fgoDevice.py实现跨平台设备连接，支持ADB协议与模拟器通信，建立自动化操作的物理通道。
• 图像识别层：基于fgoDetect.py实现游戏场景解析，通过模板匹配技术识别UI元素与战斗状态，为决策提供视觉输入。
• 核心逻辑层：fgoKernel.py作为系统中枢，协调任务调度与状态管理，实现战斗流程的自动化控制。
• 配置管理层：通过fgoConfig.py处理参数加载与优先级排序，支持多环境配置方案的快速切换。
• 用户交互层：提供fgoGui.py图形界面与fgoCli.py命令行接口，满足不同用户的操作习惯需求。

关键技术实现

图像识别引擎采用多尺度模板匹配算法，通过fgoImage目录下的素材资源（如地图、角色卡片）构建特征库，实现场景定位与状态判断。核心代码示例：

# fgoDetect.py 图像匹配实现
import cv2
import numpy as np

class ImageDetector:
    def __init__(self, template_dir):
        self.templates = self._load_templates(template_dir)
        
    def _load_templates(self, dir_path):
        """加载模板库，建立特征索引"""
        templates = {}
        for filename in os.listdir(dir_path):
            if filename.endswith('.png'):
                key = os.path.splitext(filename)[0]
                templates[key] = cv2.imread(os.path.join(dir_path, filename))
        return templates
        
    def match_scene(self, screenshot, threshold=0.85):
        """场景匹配核心算法"""
        for name, template in self.templates.items():
            result = cv2.matchTemplate(screenshot, template, cv2.TM_CCOEFF_NORMED)
            if np.max(result) > threshold:
                return name, np.unravel_index(result.argmax(), result.shape)
        return None, None

常见问题

Q: 不同分辨率设备是否需要单独配置模板？
A: 系统内置多分辨率适配算法，通过图像缩放与特征点归一化处理，可支持主流手机与模拟器分辨率（720p-2K），无需单独配置。

Q: 如何扩展新的游戏场景识别？
A: 只需在fgoImage目录添加对应场景模板图片，并在ImageDetector中注册特征名称，系统会自动加载新模板。

快速启动指南

本指南提供从环境部署到自动化任务执行的完整流程，通过容器化部署与命令行操作实现快速上手。

环境准备与部署

1. 基础环境要求

• Python 3.8+ 运行环境
• ADB工具链（用于设备连接）
• 支持OpenGL的图形环境

2. 项目获取与依赖安装

# 克隆代码仓库
git clone https://gitcode.com/GitHub_Trending/fg/FGO-py
cd FGO-py

# 创建虚拟环境并安装依赖
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. 容器化部署（推荐）

# 构建Docker镜像
cd deploy/Docker
docker-compose build

# 启动服务
docker-compose up -d

首次运行与设备配置

1. 设备连接

# 列出可用设备
adb devices

# 配置设备连接
python fgoCli.py connect --host 127.0.0.1 --port 5555

2. 队伍配置

# 加载预设队伍配置
python fgoCli.py teamup load Kizuna

# 验证队伍配置
python fgoCli.py teamup show

3. 启动自动战斗

# 执行主线任务第一章第一节
python fgoCli.py main --chapter 1 --stage 1

常见问题

Q: 设备连接提示"ADB server didn't ACK"如何解决？
A: 检查ADB服务状态，执行adb kill-server && adb start-server重启服务，确保设备调试模式已开启。

Q: 战斗过程中出现识别错误怎么办？
A: 可通过fgoCli.py debug --save-screenshot保存错误场景截图，提交至项目issue并附上日志文件（位于fgoLog/目录）。

配置参数详解

FGO-py采用三级参数优先级设计（环境变量 > 命令行参数 > 配置文件），支持灵活的任务定制与环境适配。核心配置文件为fgoConfig.py，包含系统参数、战斗策略与识别阈值等关键配置项。

核心配置项解析

1. 系统参数

# fgoConfig.py 系统配置示例
SYSTEM_CONFIG = {
    "device": {
        "timeout": 10,          # 设备连接超时时间(秒)
        "screenshot_quality": 80 # 截图压缩质量(0-100)
    },
    "log": {
        "level": "INFO",        # 日志级别(DEBUG/INFO/WARNING/ERROR)
        "max_size": 1024*1024*5 # 单日志文件大小限制(5MB)
    }
}

2. 战斗策略配置

# fgoTeamup.ini 队伍策略示例
[Kizuna]
team_index: 1                  # 队伍索引
servant_skill: [3,2,1]         # 从者技能释放顺序
master_skill: [True, False, False] # 御主技能启用状态
battle_timeout: 300            # 单场战斗超时时间(秒)

3. 参数优先级规则

• 第一优先级：通过--config命令行参数指定的临时配置
• 第二优先级：FGO_前缀的环境变量（如FGO_DEVICE_TIMEOUT=15）
• 第三优先级：配置文件中的默认值

高级配置技巧

1. 环境变量覆盖示例

# 临时调整战斗超时时间
export FGO_BATTLE_TIMEOUT=600
python fgoCli.py main --chapter 2 --stage 3

2. 多场景配置切换

# 加载QP farming专用配置
python fgoCli.py config load qp_farming.yaml

# 验证当前配置
python fgoCli.py config show

常见问题

Q: 如何配置自动恢复体力功能？
A: 在fgoConfig.py中设置auto_restore_ap: True，并配置ap_item_priority: [3,2,1]（3为圣晶石，2为银苹果，1为金苹果）。

Q: 不同服务器（日服/国际服）需要单独配置吗？
A: 是的，通过--server jp/na/cn命令行参数指定服务器，系统会自动加载对应区域的图像模板与文本识别库。

通过以上架构解析、启动指南与配置详解，可快速掌握FGO-py的核心功能与扩展方法。项目采用模块化设计确保高可维护性，同时提供灵活的配置机制满足不同用户的自动化需求。更多高级功能与API文档可参考doc/目录下的技术手册。