Automation Runtime — документация Screph

1. Где начинается исполнение

Project JSON — описание цели и контекста, а не самозапускающийся бот. Исполнение начинается только после запуска скрипта или команды в Automation Manager. Перед этим целевое приложение должно быть открыто, видно и находиться в ожидаемой конфигурации экранов.

Сохраните и проверьте проект в Screph.
В Настройки → Зависимости подготовьте script/CV runtime, а для текста — OCR runtime.
В Настройки → Эмуляция ввода выберите и проверьте backend.
Запустите сценарий сначала на безопасной тестовой цели и следите за шагами/снимками в Automation Manager.

2. Загрузка и проверка проекта

validate_project(path) возвращает пару (ok, errors); одного вызова недостаточно — результат нужно проверить. load_project(path) не запускает эту validation автоматически: он читает элементы, проецирует координаты, регистрирует первый 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")

Использование stable element id и поиска по экрану обычно устойчивее, чем жёсткая последовательность абсолютных кликов. Но шаблоны всё равно зависят от масштаба, темы, состояния окна и качества исходного изображения. Runtime не проверяет, что видимое совпадение принадлежит именно ожидаемому process/window.

3. Основные группы API

Изображения и ожидания

wait_and_click_image, double_click_image, right_click_image — найти шаблон и запросить действие; postcondition проверяет сценарий.
wait_until_gone_image — подтвердить отсутствие состояния до timeout.
find_all_images, wait_for_any_image, wait_for_all_images — работать со списками и альтернативами.

Текст и OCR

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 и action logging для диагностики и повторяемости.

wait_for_all_images накапливает шаблоны, найденные в разные polling-моменты; результат true не доказывает, что все они одновременно присутствовали в одном кадре.
wait_until_gone_image подтверждает отсутствие при проверке, но не требует, чтобы шаблон сначала был увиден.
wait_and_click_image и wait_and_click_text сначала находят цель, затем ищут её ещё раз для клика. Их true отражает первое обнаружение, но текущая wrapper-логика не проверяет return второго поиска/клика. После действия проверяйте ожидаемое состояние отдельным helper.

4. Координаты и выбранный монитор

Публичные input helpers получают глобальные физические координаты виртуального рабочего стола. Проекция project geometry зависит от сохранённого coordinate space:

Source	Что делает loader	Что он не доказывает
`screen_physical_px`	Принимает bounding boxes как уже глобальные.	Capture target не разрешается повторно; topology проверит только input guard в момент pointer action.
`screenshot_raw_px` + monitor	Находит текущий монитор по stable device name и масштабирует raw screenshot в его текущий rect.	Изменение разрешения приводит к rescale, а не к требованию идентичной геометрии.
`screenshot_raw_px` + window	Разрешает текущий HWND, сверяет сохранённые PID/class при их наличии и масштабирует в текущий window rect.	Не проверяет foreground, visibility, occlusion, title или содержимое окна.
`screenshot_raw_px` + region	Использует сохранённый physical rect области и масштабирует raw coordinates.	У области нет live window/monitor identity для повторной проверки.

Выбор monitor в input settings — отдельная граница для pointer target, а не смещение начала координат. Значение all разрешает любой подключённый монитор, но всё равно отклоняет точки вне outputs и в промежутках виртуального desktop; конкретный monitor отклоняет точки вне его rect. Эта проверка выполняется при фактическом move/click и может отклонить проект, который прошёл validate_project.

5. Backend ввода

Выбор выполняется пользователем в настройках. Runtime не переключается незаметно на другой способ ввода.

Arduino Leonardo HID — основной аппаратный режим через управляющий HID-канал и подходящую прошивку. Кнопка прошивки переводит Leonardo/ATmega32U4 в bootloader и записывает выбранный .hex через avrdude; это изменение внешнего устройства, а не connection test.
Legacy Serial — совместимость со старой COM-прошивкой Leonardo.
FakerInput Virtual HID — программная HID-клавиатура и мышь в Windows. Первый выбор режима сразу проверяет SHA256, Authenticode и signer bundled MSI, затем через один UAC-запрос устанавливает системный драйвер; после установки может потребоваться ручная перезагрузка.

Arduino и FakerInput перемещают мышь относительными HID-дельтами. Runtime читает системную скорость/ускорение и предупреждает о риске; он не меняет их автоматически. Отдельная явная CLI-команда --apply-recommended сохраняет нейтральные параметры в профиле текущего пользователя и не восстанавливает прежние значения сама. Обязательно прогоните тест ввода до реального сценария.

UAC, firmware, mouse settings и системные последствия →

6. Когда нужен OCR

Tesseract и ocr.runtime нужны только для операций чтения, поиска и проверки текста. Image matching, координатные действия и обычный ввод текста не требуют OCR. Если OCR отключён или сломан, text helpers возвращают empty/false/none result и EVT progress там, где helper его публикует, а не переключаются на image matching.

find_text/wait_and_click_text сопоставляют query с отдельным OCR token, поэтому фраза из нескольких слов не собирается через соседние tokens.
wait_for_text_change возвращает новое непустое значение только после трёх последовательных одинаковых OCR-readings.
ensure_text_contains объединяет tokens области в строку и проверяет case-sensitive substring.

Проверить runtime-компоненты и способы установки →

7. Automation Manager

Automation Manager запускает выбранный сценарий как дочерний Python-процесс с текущими правами пользователя Windows и рабочим каталогом в папке скрипта. Runtime пишет структурированные EVT-события в stdout: текущий шаг, прогресс, снимок экрана, шаблон и найденное совпадение. Интерфейс показывает их рядом с журналом выполнения.

Это не sandbox. Процесс наследует environment Screph, включая доступные там credentials, получает параметры как AM_* variables и может использовать файлы, сеть и устройства, доступные пользователю. Перед запуском проверяйте не только код, но и его зависимости, environment и создаваемые внешние процессы.

Перед стартом проверьте выбранный скрипт, рабочий каталог и параметры.
Не взаимодействуйте с целевым окном вручную во время координатного сценария.
При расхождении остановите процесс, сохраните журнал/снимок и исправьте проект или precondition; не увеличивайте таймаут вслепую.
Stop сначала завершает прямой дочерний процесс, ждёт до 5 секунд и затем принудительно останавливает именно его. Процессы, которые сценарий запустил сам, могут продолжить работу: проверьте их отдельно.

8. Диагностика

Шаблон не найден: сверьте scale, тему, состояние окна, ROI и threshold.
Текст не найден: проверьте ocr.runtime, язык Tesseract и качество области.
Курсор идёт не туда: проверьте topology мониторов, физические координаты, monitor guard и настройки ускорения Windows.
Ввод не начинается: откройте тест вкладки эмуляции и исправьте выбранный backend; скрытого fallback нет.