第一次运行
假设你已经完成安装，并且模拟器里装好了游戏、按游戏内设置调整完毕。
1. 打开 WebUI
启动器会直接打开窗口。源码或 Docker 部署则访问：
http://127.0.0.1:25548首次访问如果要求输入密码，说明部署配置里已经设置了 Password，或者监听地址不是回环、程序自动生成了密码。自动生成的密码在项目根目录的 password.txt。
不要裸奔在公网
WebUI 可以启停任务、读取截图、修改配置。监听 0.0.0.0 且没有密码，等于把账号交给整个网络。开放前务必在部署设置里设置强密码。
2. 创建实例
「实例」= 一份独立的用户配置 + 一个调度器进程。默认实例名是 ap，可以创建 ap-2、ap-3 用于多开。
在 WebUI 的实例列表点击新建，选择空白模板或从已有实例复制。复制会连同任务开关和调度时间一起带走。
配置写入 config/<实例名>.json。实例名只允许字母、数字、下划线与短横线，重命名请通过 WebUI 导出再导入，不要直接改文件名。
WebUI 语言与游戏服务器是两件不同的事。前者影响界面文案（zh-CN / en-US / ja-JP / zh-TW），后者在「系统设置 → 模拟器设置 → 游戏服务器」里选择包名。
3. 连接模拟器
进入「系统 → 模拟器设置」：
| 字段 | 填什么 |
|---|---|
| 模拟器 Serial | 模拟器 ADB 地址，例如 127.0.0.1:16384；不确定就填 auto |
| 游戏服务器 | 通常留 auto；多客户端时手动选包名 |
| 游戏内服务器 | 用于维护检测。不知道就选「不使用检测」 |
| 截图方案 | 先留「自动选择最快的」 |
| 控制方案 | 推荐 MaaTouch |
保存后回到总览，点击截图测试。能显示游戏画面就说明 ADB、截图方案、分辨率三项都通了。
auto 不是万能的
同时开着两个模拟器时，auto 无法判断你要控制哪一个。此时必须手填 Serial。查询方法：在模拟器自带 adb 目录执行 adb devices。
画面是黑的 / 截图超时
按顺序排查：
- 模拟器是否真的启动了游戏（不是启动器界面）。
-
adb devices是否能看到设备且状态为device（不是offline/unauthorized）。 - 截图方案换一个再试（例如从
DroidCast_raw换到ADB_nc）。 - 分辨率是否为 1280×720。平板模式或自定义 DPI 会导致识别与截图异常。
4. 跑通第一个任务
不要一上来就开大世界。先用一个短周期、低风险的任务验证整条链路：
在任务列表找到「科研」，打开「启用该功能」。这两个任务不消耗石油、失败代价低，适合验证。
任务的 Scheduler.NextRun 默认是 2020-01-01（即「立即到期」）。启用后如果显示未来时间，清空该字段即可立即运行。
回到总览点击启动。日志会依次出现：加载配置 → 连接设备 → 截图 → 进入科研 → 收取/开始研究 → 安排下次运行。
游戏内科研队列确实发生变化；WebUI 总览的「当前任务」显示该任务；日志结尾出现「任务结束」；下次运行时间被推到合理区间（科研通常是数小时）。
如果日志一直停在「连接设备」
说明调度器进程没拿到设备。检查模拟器是否被其他程序占用 ADB（例如另一个脚本、Android Studio），以及 Serial 是否写错。必要时在「模拟器设置」里开启「在检测不到设备的时候尝试重启 adb」。
5. 部署设置
config/deploy.yaml 控制后端本身的行为，改动通常需要重启：
| 字段 | 默认 | 说明 |
|---|---|---|
WebuiHost | 0.0.0.0 | 监听地址；仅本机用 127.0.0.1 |
WebuiPort | 25548 | WebUI 端口 |
WebuiPassword | 空 | 访问密码；空且监听公网时会自动生成 |
Language | zh-CN | WebUI 语言 |
Theme | default | 亮色 / 深色 |
OcrServerPort | 22268 | 独立 OCR 服务端口 |