Руководство пользователя Screph

1. Выделение и Редактирование Элементов

Screph предоставляет инструменты для точного выделения и редактирования элементов интерфейса. Понимание этих инструментов — основа эффективного описания сценариев.

Режимы Работы с Элементами

На Панели Инструментов доступны следующие режимы:

• Режим Выделения (Select Mode): Позволяет выбирать уже существующие элементы на холсте. Кликните на элемент, чтобы выбрать его. Выбранный элемент будет подсвечен, и его свойства отобразятся на Информационной Панели.
• Режим Создания (Create Mode): Предназначен для добавления новых элементов. Кликните и потяните мышь на холсте, чтобы нарисовать прямоугольную область для нового элемента.
• Режим Перемещения (Move Mode): Используется для изменения положения элементов. Выберите элемент, затем зажмите левую кнопку мыши и перетащите его на новое место.
• Режим Изменения Размера (Resize Mode): Позволяет изменять габариты элементов. После выбора элемента потяните за его границы или углы.
• Режим Иерархии (Hierarchy Mode): Служит для установления родительско-дочерних связей. Выберите дочерний элемент, затем кликните на предполагаемый родительский элемент. Это помогает структурировать сложные интерфейсы.

Взаимодействие с Элементами

• Выбор: Просто кликните на элемент в Режиме Выделения.
• Множественный выбор: Удерживайте клавишу Ctrl (или Cmd на macOS) при клике на элементы.
• Контекстное меню: Клик правой кнопкой мыши по элементу (или его записи в иерархии) открывает контекстное меню с дополнительными действиями, такими как удаление, дублирование, изменение свойств.
• Удаление: Выберите элемент и нажмите клавишу Delete или используйте соответствующую опцию в контекстном меню/панели инструментов.

Свойства Элемента

Каждый элемент в Screph обладает набором свойств, которые отображаются и редактируются на Информационной Панели:

• Имя (Name): Уникальное имя элемента (может генерироваться автоматически или задаваться пользователем).
• Тип (Type): Категория элемента (например, "кнопка", "поле ввода"). Может быть полезно для LLM.
• Координаты и Размеры (Geometry): Положение (X, Y) и размеры (ширина, высота) элемента.
• Родитель/Потомки (Hierarchy): Информация о связях с другими элементами.
• Аннотация (Prompt): Текстовое описание или инструкция для LLM.

Советы по Эффективному Выделению

• Используйте масштабирование холста (если доступно) для более точного выделения мелких элементов.
• Называйте элементы осмысленно, чтобы было легче ориентироваться в проекте и для лучшего понимания LLM.
• Регулярно проверяйте иерархию элементов, особенно в сложных интерфейсах.

Освоив эти техники, вы сможете быстро и точно описывать структуру любого приложения для Screph.

2. Аннотации (текст/голос)

Каждому выделенному элементу вы можете добавить текстовое описание или «промпт» для нейросети. Объясните его роль, какие данные он должен содержать, или какое действие с ним нужно совершить (например, «Это кнопка 'Далее', нажми ее после заполнения формы» или «В это поле введи email пользователя»). Для максимального удобства поддерживается голосовой ввод аннотаций!

Контекстные аннотации являются ключевым мостом между визуальным представлением интерфейса и пониманием задачи Большой Языковой Моделью (LLM). Чем точнее и понятнее промпт, тем качественнее будет сгенерированный код.

Возможности аннотирования:

• Текстовый ввод: Классический способ добавления описаний.
• Голосовой ввод: Ускоряет процесс аннотирования, позволяя надиктовывать инструкции.
• Указание действий: Например, "кликнуть", "ввести текст", "выбрать значение из списка".
• Описание данных: Например, "поле для ввода имени пользователя", "сумма заказа".
• Уточнение роли элемента: Например, "кнопка подтверждения", "ссылка на главную страницу".

(В будущем здесь могут быть добавлены примеры хороших и плохих промптов.)

Использование Голосовой Аннотации

Screph поддерживает голосовой ввод для аннотаций. Функция полезна для длинных или сложных инструкций и работает через внешний провайдер или офлайн с локальными моделями Vosk.

Активация и Использование

1. Выберите элемент: Сначала выделите элемент, к которому хотите добавить голосовую аннотацию.
2. Активируйте Голосовую Аннотацию: Нажмите кнопку "Голосовая Аннотация" на Панели Инструментов или используйте соответствующую горячую клавишу. Появится виджет голосовой аннотации.
3. Начните Запись: Нажмите кнопку "Запись" (обычно значок микрофона) в виджете. Говорите четко в микрофон.
4. Остановите Запись: Нажмите кнопку "Стоп" в виджете.
5. Просмотр и Редактирование: Распознанный текст появится в виджете и/или в поле аннотации на Информационной Панели. Вы можете отредактировать его вручную, если необходимо.
6. Сохранение Аннотации: Убедитесь, что аннотация применена к элементу (обычно это происходит автоматически после остановки записи или при потере фокуса с поля редактирования).

Советы для Четкого Распознавания

• Говорите ясно и в умеренном темпе.
• Используйте гарнитуру или качественный микрофон для уменьшения фонового шума.
• Избегайте сложных или неоднозначных фраз, если это возможно.
• Проверяйте распознанный текст и корректируйте ошибки.

Голосовая аннотация — мощный инструмент, который при правильном использовании экономит много времени.

3. Сохранение и Загрузка Проектов

Screph позволяет сохранять вашу работу в файлы проектов и загружать их позже. Это необходимо для работы над сложными сценариями и для обмена проектами.

Сохранение Проекта

Существует два основных способа сохранить проект:

• Файл -> Сохранить проект (Save Project): Если проект уже был сохранен ранее, эта команда перезапишет существующий файл. Если проект новый, будет вызвано диалоговое окно "Сохранить проект как...". Горячая клавиша: Ctrl+S (или Cmd+S).
• Файл -> Сохранить проект как... (Save Project As...): Эта команда всегда открывает диалоговое окно, позволяя указать новое имя файла или местоположение. Используйте это для создания копий проекта или для первого сохранения. Горячая клавиша: Ctrl+Shift+S (или Cmd+Shift+S).

Проекты Screph обычно сохраняются с расширением .sgaip (Screph Project) или аналогичным.

Что Сохраняется в Проекте?

Файл проекта Screph содержит всю необходимую информацию для восстановления вашей рабочей сессии:

• Снимок(ки) Фона: Изображение(я) экрана, на котором производилось выделение. Для проектов с сериями изображений сохраняются все изображения серии.
• Элементы: Все выделенные элементы, их имена, типы, геометрические параметры (координаты и размеры).
• Иерархия Элементов: Родительско-дочерние связи между элементами.
• Аннотации (Промпты): Текстовые и голосовые описания, привязанные к каждому элементу.
• Связи в Графе: Логические связи и последовательности действий, определенные пользователем (если эта функциональность реализована через явное создание графа).
• Настройки Проекта: Некоторые специфичные для проекта настройки, если они есть (например, конфигурация LLM, параметры экспорта).

Загрузка Проекта

Для открытия ранее сохраненного проекта:

• Файл -> Загрузить проект (Load Project): Открывает диалоговое окно для выбора файла проекта (.sgaip). При загрузке нового проекта текущее несохраненное состояние может быть потеряно (обычно приложение предупреждает об этом). Горячая клавиша: Ctrl+O (или Cmd+O).

После загрузки проекта холст, список элементов и их аннотации будут восстановлены до состояния на момент сохранения.

Автосохранение (Autosave)

Screph может включать функцию автосохранения для предотвращения потери данных. Настройки обычно находятся в меню Настройки -> Приложение. Рекомендуется периодически сохранять проект вручную.

Правильное управление сохранением и загрузкой проектов — основа стабильной и продуктивной работы в Screph.

4. Работа с Сериями Изображений

Функция серий изображений в Screph предназначена для работы со сценариями, которые охватывают несколько состояний экрана или шагов в процессе. Полезно для многоэтапных задач и динамических интерфейсов.

Концепция Серии Изображений

Серия изображений — упорядоченный набор снимков экрана или загруженных изображений, представляющих состояния приложения. Можно выделять элементы и добавлять аннотации на каждом изображении; Screph связывает их с соответствующим кадром.

Создание Новой Серии и Управление Изображениями

• Создание Серии: Обычно серия создается автоматически, когда вы начинаете добавлять изображения после первого. Некоторые версии могут иметь явную команду Файл -> Новая серия изображений или аналогичную.
• Добавление Изображений:
  • Захват Экрана: Используйте кнопку "Обновить фон" или "Захватить экран" для добавления текущего состояния экрана как нового изображения в серию.
  • Загрузка из Файла: Используйте Файл -> Добавить изображение в серию... для загрузки графических файлов (PNG, JPG и т.д.).
• Навигация по Серии: Используйте кнопки "Следующее изображение" и "Предыдущее изображение" (обычно со стрелками) на Панели Инструментов или в специальной панели управления серией для перемещения между изображениями. Текущий номер изображения и общее количество обычно отображаются.
• Управление Изображениями в Серии:
  • Удаление Изображения: Выберите изображение (убедитесь, что оно текущее на холсте) и используйте команду "Удалить текущее изображение из серии".
  • Изменение Порядка: Некоторые версии могут позволять изменять порядок изображений в серии путем перетаскивания их миниатюр.

Элементы и Аннотации в Контексте Серий

Важно понимать, как элементы и аннотации ведут себя при работе с сериями:

• Привязка к Изображению: Элементы, которые вы выделяете, и аннотации, которые вы добавляете, обычно привязаны к тому изображению серии, которое было активно на холсте в момент их создания.
• "Сквозные" Элементы: Некоторые элементы могут быть помечены как "сквозные" или "глобальные", если они присутствуют на нескольких (или всех) изображениях серии. Механизм их обработки может различаться.
• Копирование Элементов между Изображениями: Может существовать функционал для копирования набора элементов с одного изображения серии на другое, чтобы ускорить разметку похожих экранов.

Сохранение и Загрузка Серий

При сохранении проекта (см. раздел "Сохранение и Загрузка Проектов"), вся серия изображений, включая все снимки, элементы и аннотации, сохраняется в файле проекта.

Работа с сериями изображений открывает возможности для описания сложных, многошаговых взаимодействий с пользовательскими интерфейсами.

5. Создание Структуры Взаимодействий (Визуальный Граф)

Просто выделить элементы недостаточно — нужен контекст. Screph позволяет визуально определять связи и зависимости между элементами, выстраивая их в граф. Это помогает точнее задавать последовательность действий и архитектуру интерфейса.

Граф взаимодействий представляет собой схему, где узлами являются выделенные элементы, а ребрами – логические переходы или зависимости между ними. Например, после нажатия кнопки "Войти" (элемент А) должен появиться "Личный кабинет" (элемент Б).

Преимущества использования графа:

• Контекстуализация: LLM получает не просто набор элементов, а понимание их взаимосвязей.
• Определение последовательности: Четко задается порядок выполнения действий.
• Обработка условий и ветвлений: Возможность описать различные сценарии (например, что делать, если авторизация успешна, а что – если нет).
• Визуализация логики: Пользователь сам видит и контролирует логику будущего скрипта.

(В будущем здесь могут быть добавлены примеры построения графов для различных сценариев.)

6. Магия LLM: Автоматическая Генерация Кода

Screph формирует структурированный набор данных (изображения, выделения, аннотации, граф связей) и воспроизводит (эмулирует) действия пользователя для проверки сценариев.

Далее подготовленные данные экспортируются (например, JSON) для последующей генерации кода пользователем или LLM‑агентом вне Screph.

Особенности генерации кода:

• Поддержка языков: Изначально основной фокус на Python, но архитектура позволяет расширение на другие языки (например, JavaScript для веб-автоматизации).
• Использование библиотек: Генерируемый код может использовать популярные библиотеки для автоматизации GUI (например, `pyautogui`, `Selenium`, `Playwright`).
• Читаемость кода: Мы стремимся к тому, чтобы генерируемый код был понятным и легко модифицируемым.
• Обработка ошибок: По возможности, в код включаются базовые механизмы обработки исключений.

(В будущем здесь могут быть добавлены примеры генерируемого кода для различных задач.)

7. Гибкая Интеграция с IDE

Полученный структурированный набор данных (визуальные объекты, промпты, граф связей) и даже предварительно сгенерированный LLM код легко экспортируются и отправляются в вашу предпочитаемую среду разработки, такую как Cursor или любая другая IDE. Это позволяет разработчикам быстро дорабатывать, отлаживать и интегрировать скрипты в более крупные проекты автоматизации.

Screph не стремится заменить IDE, а дополняет их, предоставляя удобный инструмент для визуального описания и подготовки данных.

Способы интеграции:

• Экспорт данных: Сохранение проекта Screph в формате, который можно импортировать или анализировать в других инструментах.
• Копирование кода: Простой способ скопировать сгенерированный код в буфер обмена и вставить в IDE.
• Плагины для IDE (в планах): В будущем возможна разработка плагинов для популярных IDE для более тесной интеграции.
• Работа с файловой системой: Сгенерированный код сохраняется в виде файлов, которые можно открыть в любой IDE.

(В будущем здесь могут быть добавлены инструкции по интеграции с конкретными IDE.)