Automation Runtime 从已审核的 Screph 项目执行准备好的 GUI 工作流。它加载元素和模板，检测视觉或文本状态，等待定义的条件并通过选定的输入后端发送显式命令。
项目 JSON 描述了一个目标及其上下文；它不是一个自动运行的机器人。仅当您启动脚本或自动化管理器命令时才开始执行。目标应用程序必须首先打开、可见并且处于预期的显示配置中。
Settings → Dependencies 下，准备脚本/CV 运行时和 OCR 当涉及文本时，运行时。Settings → 输入仿真 下，选择并测试后端。validate_project(path) 返回 （好的，错误） 对；在不检查结果的情况下调用它是不够的。 load_project(path) 不会自动运行该验证：它读取元素、投影坐标、注册每个的第一个 image_path 元素作为模板，并返回 GuiBotController 以及 GuiElement 的列表。
from automation_runtime import (
load_project,
validate_project,
wait_and_click_image,
wait_until_gone_image,
)
project_path = "projects/my_ui_project.json"
ok, errors = validate_project(project_path)
if not ok:
raise RuntimeError("Project is not runnable:\n" + "\n".join(errors))
bot, elements = load_project(project_path)
target = next(item for item in elements if item.id == "start_button")
if not wait_and_click_image(bot, target.id, timeout=20, desc="Start"):
raise RuntimeError("start_button was not found")
if not wait_until_gone_image(bot, target.id, timeout=10):
raise RuntimeError("Start action did not reach the expected next state")使用稳定的元素 ID 和屏幕匹配通常比固定的绝对点击序列更稳健。模板仍然取决于比例、主题、窗口状态和源图像质量。运行时不会验证可见匹配是否属于预期的进程或窗口。
wait_and_click_image, double_click_image, right_click_image — 查找模板并请求操作；工作流验证后置条件。wait_until_gone_image — 确认超时前状态不存在。find_all_images, wait_for_any_image, wait_for_all_images — 使用列表和替代状态。wait_and_click_text — 等待文本并点击检测到的区域。wait_for_text_change, ensure_text_contains — 验证更改或预期内容。click_in_area, move_to_area, move_to, get_cursor_position.type_text, press_key, press_hotkey, drag_from_to, scroll.retry, take_screenshot 以及诊断和可重复性的操作日志记录。wait_for_all_images 累积在不同轮询时刻找到的模板； true并不能证明它们全部出现在同一帧中。wait_until_gone_image 确认轮询期间缺席，但不需要首先观察到模板。wait_and_click_image 和 wait_and_click_text 首先检测目标，然后再次搜索点击。它们的 true 反映了第一次检测，而当前包装器不检查第二次搜索/点击返回值。使用单独的助手验证预期的后置条件。公共输入助手接收虚拟桌面上的全局物理坐标。项目几何的投影取决于存储的坐标空间：
| Source | 加载器行为 | 它没有证明什么 |
|---|---|---|
screen_physical_px | 接受已全局的边界框。 | 捕获目标不再解析；当指针动作发生时，只有输入防护检查拓扑。 |
screenshot_raw_px + monitor | 通过稳定设备名称查找当前显示器，并将原始屏幕截图缩放到当前矩形。 | 分辨率更改会导致重新缩放，而不需要相同的几何形状。 |
screenshot_raw_px + window | 解析当前的 HWND，检查存储的 PID/类（如果存在）并缩放到当前窗口矩形。 | 不验证前景状态、可见性、遮挡、标题或窗口内容。 |
screenshot_raw_px + region | 使用存储的物理区域矩形并缩放原始坐标。 | 某个区域没有需要重新验证的实时窗口/监视器身份。 |
在输入设置中选择的监视器是单独的指针目标边界，而不是原点偏移。 all 允许任何连接的显示器，但仍拒绝输出外部或虚拟桌面间隙中的点；特定监视器拒绝其矩形之外的点。此检查在实际移动/单击期间运行，可能会拒绝通过 validate_project 的项目。
用户在设置中选择后端。运行时不会默默地切换到另一种输入法。
avrdude写入选定的.hex；这会修改外部设备，而不仅仅是测试连接。Arduino 和 FakerInput 使用相对 HID 增量移动指针。运行时读取系统速度和加速度并发出风险警告；它不会自动更改它们。单独的显式 --apply-recommended CLI 命令会在当前用户的配置文件中保留中性设置，并且本身不会恢复以前的值。始终在真正的工作流之前运行输入测试。
Tesseract 和 ocr.runtime 仅在读取、查找和验证文本时需要。图像匹配、坐标动作和普通文本输入不需要 OCR。如果 OCR 被禁用或损坏，文本帮助程序将返回空/假/无结果以及帮助程序发出的 EVT 进度，而不是切换到图像匹配。
find_text/wait_and_click_text 将查询与一个 OCR 令牌进行比较，因此是一个多词短语不跨相邻标记进行组装。wait_for_text_change 仅在连续三个相同的 OCR 读数后返回新的非空值。ensure_text_contains 将区域的标记连接到字符串中并执行区分大小写的子字符串检查。Automation Manager 将选定的工作流作为子 Python 进程运行，并使用当前 Windows 用户的权限和脚本目录作为其工作目录。运行时向标准输出发出结构化 EVT 事件：当前步骤、进度、屏幕快照、模板和检测到的匹配。界面将它们与执行日志一起显示。
这不是沙箱。该进程继承 Screph 的环境，包括那里可用的凭据，接收 AM_* 变量的参数，并且可以使用用户可用的文件、网络和设备。审核代码、其依赖项、环境以及它在运行之前创建的任何外部进程。
Stop 首先终止直接子进程，等待最多五秒，然后终止该进程。由工作流本身生成的进程可能会继续运行，必须单独检查。ocr.runtime、Tesseract 语言和区域质量。