FGO-py 项目使用指南：从入门到精通

一、核心功能模块解析

FGO-py采用模块化解耦设计，将系统划分为三大功能区域，每个区域承担特定职责并通过标准化接口交互，确保系统扩展性与维护性。

1.1 核心功能区

功能定位：实现 Fate/Grand Order 自动化操作的核心逻辑，包含游戏场景识别、任务执行和战斗策略。
核心特性：

• 基于图像识别的场景检测系统
• 多策略战斗决策引擎
• 动态任务调度机制 应用场景：自动战斗、素材收集、日常任务执行

图1：FGO-py支持的游戏世界地图，显示可自动探索的区域节点

1.2 辅助工具区

功能定位：提供开发与运维支持的辅助组件，包含日志系统、设备管理和配置解析。
核心特性：

• 分级日志记录与分析
• 多设备适配框架
• 配置热加载机制 应用场景：问题排查、多设备管理、参数调优

1.3 配置管理区

功能定位：集中管理系统配置与资源，实现环境隔离与参数注入。
核心特性：

• 三级配置体系（基础/高级/环境变量）
• 多语言支持
• 资源文件管理 应用场景：环境适配、个性化设置、多语言切换

二、环境配置指南

2.1 准备工作

前置条件：

• Python 3.8+ 运行环境
• Git 版本控制工具
• 依赖管理工具 pip

执行命令：

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

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

预期结果：项目文件下载完成，依赖包安装成功，无错误提示。

⚠️ 警告：确保网络环境稳定，依赖包总大小约 200MB，建议使用国内 PyPI 镜像加速下载。

2.2 环境检查

前置条件：完成基础依赖安装
执行命令：

# 检查Python版本
python --version

# 验证依赖完整性
pip check

预期结果：

• Python 版本显示为 3.8 或更高
• 依赖检查显示 "No broken requirements found"

💡 技巧：使用 pip list | grep -E "opencv-python|numpy|pyautogui" 验证核心依赖是否正确安装。

三、快速上手流程

3.1 配置文件准备

前置条件：完成环境配置
核心操作：

1. 复制默认配置模板

cp FGO-py/fgoTeamup.ini.example FGO-py/fgoTeamup.ini

2. 基础配置项设置（fgoTeamup.ini）：

[General]
# 基础配置 - 优先级：默认值 < 配置文件 < 环境变量
device_type = android  # 设备类型：android/ios/pc
resolution = 1920x1080  # 游戏分辨率
language = zh  # 语言：zh/en/ja

[Advanced]
# 高级参数 - 调整战斗策略
battle_timeout = 300  # 战斗超时时间(秒)
skill_priority = 1,3,2  # 技能释放优先级

3.2 一键启动

前置条件：配置文件准备完成
执行命令：

# 启动GUI界面（推荐新手）
python FGO-py/fgoGui.py

# 或使用命令行模式
python FGO-py/fgoCli.py

预期结果：

• GUI模式：启动图形界面，显示主控制窗口（如图2）
• CLI模式：终端显示欢迎信息和命令提示

图2：FGO-py图形界面，显示任务调度和日志监控面板

3.3 状态验证

前置条件：程序成功启动
核心操作：

1. 在GUI界面点击"设备连接"按钮
2. 观察日志面板输出
3. 验证连接状态指示灯变绿

预期结果：日志显示"设备连接成功"，状态指示变为绿色。

🔍 重点：首次启动需授予程序屏幕捕获和输入控制权限，具体操作因操作系统而异。

四、进阶使用技巧

4.1 三级配置体系详解

FGO-py采用配置注入机制，支持多层次配置覆盖：

1. 基础配置（fgoConfig.py）

   • 系统默认值，包含必要参数
   • 示例：DEFAULT_TIMEOUT = 10

2. 高级参数（fgoTeamup.ini）

   • 用户可修改的配置文件
   • 优先级高于默认值
   • 示例：battle_timeout = 300

3. 环境变量

   • 运行时动态注入的参数
   • 优先级最高，用于临时调整
   • 示例：export FGO_DEBUG=True

💡 技巧：使用环境变量 FGO_CONFIG 指定自定义配置文件路径：

FGO_CONFIG=./my_config.ini python FGO-py/fgo.py

4.2 实用命令示例

示例1：命令行模式快速战斗

# 连接设备并加载队伍配置
python FGO-py/fgoCli.py -c "teamup load Kizuna; connect localhost:5555; main"

示例2：后台运行与日志输出

# 后台运行并将日志写入文件
nohup python FGO-py/fgo.py > fgo_run.log 2>&1 &

示例3：Docker容器化部署

# 使用Docker一键启动
docker run -v $(pwd)/FGO-py:/FGO-py --name fgo-py --rm -it hgjazhgj/fgo-py

图3：FGO-py命令行模式，显示队伍配置与战斗日志

五、常见问题排查

5.1 设备连接失败

错误表现：日志显示"Device not found"
可能原因：

• 设备未开启调试模式
• ADB服务未启动
• 端口被占用

解决方法：

# 检查ADB设备列表
adb devices

# 重启ADB服务
adb kill-server && adb start-server

5.2 图像识别不准确

错误表现：程序无法正确识别游戏界面
可能原因：

• 游戏分辨率与配置不符
• 图像资源文件损坏
• 光照条件影响

解决方法：

1. 确认配置文件中分辨率设置与游戏一致
2. 执行资源校验：python FGO-py/fgoImageListener.py --verify
3. 调整屏幕亮度至50%以上

5.3 战斗策略执行异常

错误表现：技能释放顺序错误或战斗超时
可能原因：

• 队伍配置文件错误
• 技能优先级设置不当
• 网络延迟导致指令丢失

解决方法：

1. 检查fgoTeamup.ini中的技能优先级配置
2. 增加战斗超时时间：config battle_timeout 400
3. 在网络稳定环境下运行

六、总结

FGO-py通过模块化架构和灵活配置系统，为 Fate/Grand Order 玩家提供强大的自动化辅助功能。从基础的日常任务执行到复杂的战斗策略定制，本指南涵盖了从环境搭建到高级应用的全流程。

项目在开源社区中持续活跃，如图4所示，长期保持GitHub Trending榜单前列，其稳定性和扩展性得到广泛验证。

图4：FGO-py项目在GitHub Trending榜单的展示情况

通过掌握本文介绍的配置方法和使用技巧，您可以充分发挥FGO-py的自动化能力，提升游戏体验的同时，深入了解图像识别、自动化脚本开发等技术原理。建议定期查看项目文档以获取最新功能更新和最佳实践指南。