Android 全自动刷机工具

English | 中文

中文

一个通用的 Android 自动刷机框架，支持多设备型号，最小化人工干预，实现从原始系统到完整 Root 环境的一键部署。

✨ 核心特性

多设备支持：通过设备适配器模式支持 Pixel、小米、OPPO 等多种设备
资源共享：通用模块（APatch、LSPosed 等）跨设备复用
全自动化：自动完成刷机、初始化、Root、模块安装全流程
断点续传：支持中断后从检查点继续执行
自动恢复：刷机失败自动恢复到原厂 boot.img

📱 支持的设备

首批支持：

Google Pixel 5 (redfin)

可扩展：通过编写设备适配器支持更多设备

🔧 Root 方案支持

Root 方案	状态	说明
APatch	✅ 已支持	完整支持，包括 boot.img 修补、模块安装
Magisk	🚧 开发中	计划支持
KernelSU	🚧 开发中	计划支持

当前推荐使用 APatch

🚀 快速开始

1. 安装

# 克隆项目
git clone https://github.com/yourusername/android-auto-flash.git
cd android-auto-flash

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

2. 准备资源

# 通用资源（所有设备共享）
resources/common/
├── apks/
│   └── APatch_xxx.apk
├── modules/
│   ├── zip/
│   │   ├── LSPosed-xxx.zip
│   │   └── ZygiskNext-xxx.zip
│   ├── lsp/
│   │   └── BlackDex64.apk
│   └── kpm/
│       └── xxx.kpm
└── tools/
    ├── kptools-msys2-0.12.7.exe
    ├── kpimg-android-0.12.7
    ├── magiskboot.exe
    ├── msys-2.0.dll
    └── msys-z.dll

# 设备特定资源
resources/devices/redfin/TQ3A.230901.001.C2/
├── firmware/
│   ├── boot.img
│   ├── bootloader-xxx.img
│   ├── radio-xxx.img
│   └── image-xxx.zip
└── root/
    └── (修补后的 boot.img 会保存在这里)

3. 配置

编辑 config.yaml：

# 全局配置
adb_path: "adb"
fastboot_path: "fastboot"

# Root 方案（当前仅支持 apatch）
root_method: "apatch"

# 设备配置
devices:
  redfin:
    model: "redfin"
    build_id: "TQ3A.230901.001.C2"
    superkey: "your_superkey_here"
    boot_img_source: "firmware"  # 或 "patched"

4. 运行刷机

# 直接运行，交互式选择设备
python main.py

# 会显示:
# ============================================================
# 检测到以下设备:
# ============================================================
#   [1] 0A281FDD40024G (有检查点: 安装APatch, 已完成 7 步)
#   [2] 13081FDD4002VL
#   [A] 全部设备并发刷机
#   [Q] 退出
# ============================================================
# 请选择设备 (输入序号/A/Q):

使用说明:

输入 1 或 2 刷机单个设备
输入 A 并发刷机所有设备
输入 Q 退出
如果设备有检查点，会自动询问是否恢复

📁 项目结构

android-auto-flash/
├── core/                       # 核心框架
│   ├── device_controller.py    # 设备控制器（ADB/Fastboot 封装）
│   ├── flash_orchestrator.py   # 刷机流程编排器
│   ├── state_machine.py        # 状态机
│   ├── boot_patcher.py         # Boot.img 修补器
│   ├── device_adapter.py       # 设备适配器基类
│   ├── root_adapter.py         # Root 方案适配器
│   ├── resource_manager.py     # 资源管理器
│   ├── config_manager.py       # 配置管理器
│   ├── checkpoint.py           # 检查点管理
│   ├── auto_recovery.py        # 自动恢复
│   ├── error_handler.py        # 错误处理
│   ├── ui_automation.py        # UI 自动化
│   ├── tool_installer.py       # 工具安装器
│   └── ...
├── resources/                  # 资源目录
│   ├── common/                 # 通用资源
│   │   ├── apks/               # APK 文件
│   │   ├── modules/            # 模块文件
│   │   └── tools/              # 修补工具
│   └── devices/                # 设备资源
│       └── redfin/             # Pixel 5
├── tests/                      # 测试文件
│   ├── test_flash.py
│   ├── test_boot_patch.py
│   └── ...
├── docs/                       # 文档
├── examples/                   # 示例代码
├── main.py                     # 主程序入口
├── config.yaml                 # 全局配置
├── requirements.txt            # Python 依赖
├── setup.py                    # 安装脚本
├── pyproject.toml              # 项目配置
└── README.md                   # 本文件

🔧 高级功能

自动检查点恢复

刷机过程中每个状态自动保存检查点
中断后重新运行会自动询问是否恢复
检查点文件: logs/checkpoint_{设备序列号}.json

并发刷机

选择 A 可以同时刷机所有连接的设备
每个设备独立线程，互不干扰
自动从各自的检查点恢复

资源管理

工具自动管理通用资源和设备特定资源：

通用资源：resources/common/ - 所有设备共享
设备资源：resources/devices/{model}/ - 设备专用
优先级：设备特定 > 通用

自动恢复

刷入修补后的 boot.img 失败时，工具会自动：

检测设备启动超时
刷回原厂 boot.img
验证设备恢复正常

Boot.img 修补

工具内置 Windows 平台的 boot.img 修补功能：

自动检测 KernelPatch 版本
支持嵌入 KPM 模块
APatch 兼容的日志格式
自动处理 MSYS2 依赖

📚 文档

⚠️ 注意事项

数据备份：刷机会清空所有用户数据，请提前备份
Bootloader 解锁：刷机前必须解锁 Bootloader
电量要求：设备电量至少 30%
USB 连接：使用原装数据线，确保连接稳定
风险提示：刷机有变砖风险，请谨慎操作
Root 方案：当前仅支持 APatch，Magisk/KernelSU 正在开发中

🛠️ 开发

安装开发依赖

pip install -e ".[dev]"

代码质量检查

# 格式化代码
black core/ tests/ *.py

# 检查代码风格
flake8 core/ tests/ *.py

# 类型检查
mypy core/

# 排序导入
isort core/ tests/ *.py

运行测试

# 运行所有测试
pytest tests/

# 运行特定测试
pytest tests/test_device_controller.py

# 查看覆盖率
pytest --cov=core tests/

🤝 贡献

欢迎贡献代码、报告 Bug 或提出建议！

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'feat: Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

📄 许可证

MIT License

English

A universal Android auto-flashing framework that supports multiple device models, minimizes manual intervention, and enables one-click deployment from stock system to full Root environment.

✨ Key Features

Multi-Device Support: Supports Pixel, Xiaomi, OPPO and more via device adapter pattern
Resource Sharing: Common modules (APatch, LSPosed, etc.) shared across devices
Full Automation: Auto-complete flashing, initialization, Root, and module installation
Resume Support: Continue from checkpoint after interruption
Auto Recovery: Automatically recover to stock boot.img on failure

📱 Supported Devices

Initial Support:

Google Pixel 5 (redfin)

Extensible: Support more devices by writing device adapters

🔧 Root Method Support

Root Method	Status	Notes
APatch	✅ Supported	Full support including boot.img patching and module installation
Magisk	🚧 In Development	Planned
KernelSU	🚧 In Development	Planned

Currently recommend using APatch

🚀 Quick Start

1. Installation

# Clone the project
git clone https://github.com/yourusername/android-auto-flash.git
cd android-auto-flash

# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

2. Prepare Resources

See Chinese section for resource structure.

3. Configuration

Edit config.yaml:

# Global config
adb_path: "adb"
fastboot_path: "fastboot"

# Root method (currently only apatch is supported)
root_method: "apatch"

# Device config
devices:
  redfin:
    model: "redfin"
    build_id: "TQ3A.230901.001.C2"
    superkey: "your_superkey_here"
    boot_img_source: "firmware"  # or "patched"

4. Run Flashing

# Single device
python main.py flash --device redfin

# Boot-only (keep data)
python main.py flash --device redfin --boot-only

# Resume from checkpoint
python main.py flash --device redfin --resume

# Dry run (no actual operations)
python main.py flash --device redfin --dry-run

📄 License

MIT License

Created with ❤️ for Android enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
core		core
resources		resources
tests		tests
.flake8		.flake8
.gitignore		.gitignore
README.md		README.md
config.yaml		config.yaml
main.py		main.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

CrackerCat/auto-flash

Folders and files

Latest commit

History

Repository files navigation