【实战指南】三步掌握FGO-py项目核心架构与自动化脚本开发

一、项目架构全景解析：从文件组织到功能模块

FGO-py作为Fate/Grand Order游戏的自动化助手工具，采用了模块化设计理念，将游戏操作逻辑与界面展示、配置管理等功能解耦。项目整体架构呈现"核心驱动-多端适配-可视化管控"的三层结构，各目录间通过明确的接口交互，形成高效协作的自动化系统。

1.1 核心功能区：FGO-py主目录解析

项目的核心代码与资源集中在FGO-py/目录下，包含实现自动化逻辑的Python模块、图像资源和配置文件：

FGO-py/
├── fgoImage/        # 图像资源库（游戏场景识别模板、UI元素素材）
├── fgoLog/          # 运行日志存储（自动化操作记录、错误追踪）
├── fgoTemp/         # 临时文件区（截图缓存、OCR识别中间结果）
├── fgoWebUI/        # Web管理界面（提供浏览器端操作面板）
├── *.py模块文件     # 核心功能实现（设备连接、战斗逻辑、任务调度等）
└── 配置文件         # 项目参数设置（多语言支持、设备配置等）

📌 关键目录功能解析：

• fgoImage/：存储游戏界面截图模板，用于图像识别定位。典型场景包括：战斗界面按钮识别（如攻击、技能按钮）、地图场景匹配（如副本入口标记）、资源图标检测（如体力值显示）。
• 核心Python模块：fgoDevice.py负责与手机设备通信（支持ADB协议），fgoFarming.py实现战斗自动化逻辑，fgoSchedule.py提供定时任务调度功能，共同构成自动化操作的"大脑"。

图1：游戏地图场景模板（用于副本位置识别与自动导航）

1.2 部署与扩展区：跨环境运行支持

项目通过deploy/目录提供多环境部署方案，包含Docker容器配置、AidLux移动平台适配脚本，以及AzurLaneAutoScript兼容示例：

deploy/
├── AidLux/          # 移动设备部署脚本（适配AidLux系统）
├── AzurLaneAutoScript/  # 跨项目兼容示例（自动化逻辑复用）
└── Docker/          # 容器化配置（包含Dockerfile与docker-compose.yml）

💡 专家提示：对于开发环境，推荐使用Docker部署以避免依赖冲突；生产环境可根据设备类型选择AidLux（移动设备）或原生Python环境（PC端）。容器化部署时，通过-v参数挂载本地配置目录，可实现配置实时更新。

二、核心模块实战指南：从设备连接到战斗自动化

2.1 设备通信模块：fgoDevice.py深度解析

设备通信模块是自动化操作的基础，负责与Android设备建立连接并发送控制指令。以下代码示例展示了通过ADB协议连接设备并执行屏幕点击操作的实现：

import subprocess
import time

class FgoDevice:
    def __init__(self, adb_path="adb", device_id=None):
        """
        初始化设备连接
        :param adb_path: ADB工具路径（默认系统环境变量中的adb）
        :param device_id: 设备ID（多设备时指定，单设备可留空）
        """
        self.adb_path = adb_path
        self.device_id = device_id
        self._connect()  # 初始化时自动连接设备

    def _connect(self):
        """建立ADB连接，检查设备状态"""
        # 检查ADB服务状态
        check_cmd = f"{self.adb_path} devices"
        result = subprocess.run(check_cmd.split(), capture_output=True, text=True)
        
        # 验证设备是否在线
        if self.device_id and self.device_id not in result.stdout:
            raise ConnectionError(f"设备 {self.device_id} 未连接")

    def tap(self, x, y, duration=0.1):
        """
        模拟屏幕点击
        :param x: 点击x坐标（相对屏幕比例，范围0-1）
        :param y: 点击y坐标（相对屏幕比例，范围0-1）
        :param duration: 点击持续时间（秒）
        """
        # 获取屏幕分辨率（实际项目中需缓存此结果）
        size_cmd = f"{self.adb_path} shell wm size"
        size_output = subprocess.check_output(size_cmd.split()).decode()
        width, height = map(int, size_output.split()[-1].split('x'))
        
        # 计算绝对坐标
        abs_x = int(x * width)
        abs_y = int(y * height)
        
        # 发送点击指令
        tap_cmd = f"{self.adb_path} shell input tap {abs_x} {abs_y}"
        subprocess.run(tap_cmd.split())
        time.sleep(duration)  # 等待操作完成

# 使用示例
if __name__ == "__main__":
    device = FgoDevice()  # 初始化设备连接
    device.tap(0.5, 0.8)  # 点击屏幕中间偏下位置（战斗按钮区域）

📌 核心功能点：

• 采用相对坐标系统，适配不同分辨率设备
• 内置设备状态检查，自动处理连接异常
• 支持点击、滑动、输入等基础操作封装

⚠️ 重要提示：使用前需确保ADB环境已配置，设备已开启USB调试模式。多设备场景下必须通过device_id参数指定目标设备。

2.2 战斗自动化模块：fgoFarming.py战斗逻辑实现

战斗模块是项目核心功能，负责解析战斗场景、执行技能释放和卡牌选择策略。以下是副本战斗循环的核心实现：

from fgoDevice import FgoDevice
from fgoDetect import SceneDetector  # 场景识别模块
import time

class FgoFarming:
    def __init__(self, device, team_index=0):
        """
        初始化战斗模块
        :param device: FgoDevice实例
        :param team_index: 队伍索引（0-based）
        """
        self.device = device
        self.team_index = team_index
        self.detector = SceneDetector()  # 初始化场景识别器
        self.battle_count = 0  # 战斗计数器

    def start_battle(self, stage_id, max_runs=10):
        """
        开始副本 farming 循环
        :param stage_id: 副本ID（用于导航）
        :param max_runs: 最大战斗次数（防止无限循环）
        """
        self.battle_count = 0
        
        while self.battle_count < max_runs:
            # 1. 导航至目标副本
            if not self._navigate_to_stage(stage_id):
                print(f"无法找到副本 {stage_id}，终止任务")
                break
                
            # 2. 开始战斗
            self._start_combat()
            
            # 3. 执行战斗策略
            self._execute_combat_strategy()
            
            # 4. 处理战斗结果
            self._handle_battle_result()
            
            self.battle_count += 1
            print(f"完成第 {self.battle_count}/{max_runs} 场战斗")

    def _execute_combat_strategy(self):
        """执行战斗策略：技能释放与卡牌选择"""
        # 简化示例：使用默认策略释放技能并选择卡牌
        while self.detector.is_in_combat():
            # 检查是否需要释放技能（实际项目中会有更复杂的逻辑）
            if self.detector.has_skill_available():
                self._use_skills()
            
            # 选择最优卡牌（这里简化为选择前三张）
            self.device.tap(0.2, 0.7)  # 第一张卡
            time.sleep(0.5)
            self.device.tap(0.4, 0.7)  # 第二张卡
            time.sleep(0.5)
            self.device.tap(0.6, 0.7)  # 第三张卡
            
            # 等待回合结束
            time.sleep(5)

# 其他辅助方法实现省略...

💡 专家提示：实际战斗策略可通过配置文件自定义，高级玩家可实现基于角色技能CD、敌方特性的动态决策逻辑。建议结合fgoOcr.py模块识别敌方血量，实现智能集火策略。

三、配置实战教程：从基础设置到高级定制

3.1 核心配置文件解析

项目配置通过fgoConfig.py模块统一管理，支持运行时动态调整参数。以下是关键配置参数的说明：

参数名	类型	推荐值	调整原则	应用场景
adb_path	字符串	"adb"	未配置环境变量时需指定绝对路径	设备连接
combat_timeout	整数	300	根据副本难度调整，高难度本可设为600	战斗超时保护
terminate_later	布尔值	False	True表示体力耗尽后继续等待回复	长时间挂机
stage_priority	列表	[1, 2, 3]	根据掉落需求排序副本ID	多副本轮刷
screenshot_quality	整数	80	范围1-100，低配置设备建议50以下	性能优化

3.2 多环境部署配置

Docker容器化部署

通过deploy/Docker/目录下的配置文件，可快速构建容器化环境：

version: '3'
services:
  fgo-py:
    build: .
    volumes:
      - ./config:/app/config  # 配置文件挂载
      - ./log:/app/fgoLog     # 日志持久化
    devices:
      - /dev/bus/usb:/dev/bus/usb  # 映射USB设备（物理连接时需要）
    environment:
      - ADB_SERVER_SOCKET=tcp:host.docker.internal:5037  # 连接宿主机ADB服务
    restart: unless-stopped

📌 部署步骤：

1. 克隆项目：git clone https://gitcode.com/GitHub_Trending/fg/FGO-py
2. 进入部署目录：cd FGO-py/deploy/Docker
3. 构建镜像：docker-compose build
4. 启动服务：docker-compose up -d

命令行与Web界面双控模式

项目提供两种操作界面，满足不同使用场景需求：

CLI模式：适合服务器或无界面环境，通过命令行指令控制：

图2：命令行模式下的战斗控制与日志输出

Web界面：通过fgoWebUI/提供可视化操作面板，支持任务调度与实时监控：

图3：Web界面的任务调度与日志查看功能

💡 专家提示：Web界面默认监听0.0.0.0:8080，可通过fgoConfig.py中的web_port参数修改端口。生产环境建议配合Nginx反向代理实现HTTPS访问。

3.3 高级配置技巧：自定义战斗策略

通过修改fgoTeamup.ini配置文件，可实现个性化战斗策略。例如，针对特定BOSS的技能释放顺序：

[Team1]
# 队伍1配置
servant1=1001  # 从者ID
servant2=2003  # 从者ID
servant3=3005  # 从者ID
ce1=501        # 概念礼装ID

[Strategy1]
# 回合1策略
turn=1
skill1=1,1     # 从者1使用技能1
skill2=2,3     # 从者2使用技能3
card=1,2,3     # 选择卡牌1、2、3

[Strategy2]
# 回合2策略
turn=2
skill3=3,2     # 从者3使用技能2
card=4,5,6     # 选择卡牌4、5、6

⚠️ 重要提示：修改配置后需重启服务使生效。建议通过fgoWebUI的"策略编辑器"进行可视化配置，避免语法错误。

总结与进阶方向

通过本文的三阶段学习，您已掌握FGO-py项目的架构设计、核心模块实现和配置方法。进阶学习建议：

1. 自定义图像识别：扩展fgoImage/目录下的模板文件，支持新活动副本识别
2. AI战斗策略：结合fgoOcr.py实现敌方状态识别，开发动态决策算法
3. 多设备管理：通过fgoDevice.py扩展，实现多设备并行操作
4. 数据统计分析：利用fgoLog/中的战斗数据，生成掉落率分析报告

项目持续更新中，建议定期通过git pull获取最新功能。遇到问题可查看doc/目录下的详细文档，或提交issue参与社区讨论。