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

1. Выделение и редактирование элементов 1. Selecting and Editing Elements

Screph предоставляет инструменты для точного выделения и редактирования элементов интерфейса. Screph provides flexible tools for precise selection and editing of interface elements.

Режимы работыWorking Modes

• ВыделениеSelect Mode: Выбор существующих элементов на холсте. Кликните на элемент - он подсветится, свойства отобразятся на панели.Select existing elements on canvas. Click on an element - it will be highlighted and properties displayed in the panel.
• СозданиеCreate Mode: Добавление новых элементов. Кликните и потяните для рисования прямоугольной области.Add new elements. Click and drag to draw a rectangular area.
• ПеремещениеMove Mode: Изменение положения. Выберите элемент и перетащите на новое место.Change position. Select element and drag to new location.
• Изменение размераResize Mode: Изменение габаритов. Тяните за границы или углы элемента.Change dimensions. Drag element borders or corners.
• ИерархияHierarchy Mode: Установка родительско-дочерних связей между элементами.Establish parent-child relationships between elements.

ВзаимодействиеInteraction

• ВыборSelection: Клик на элемент в режиме выделения.Click on element in Select Mode.
• Множественный выборMulti-select: Удерживайте Ctrl (Cmd на macOS) при клике.Hold Ctrl (Cmd on macOS) while clicking.
• Контекстное менюContext Menu: Правый клик - удаление, дублирование, изменение свойств.Right-click - delete, duplicate, modify properties.
• УдалениеDelete: Выберите элемент и нажмите Delete.Select element and press Delete.

Свойства элементаElement Properties

• ИмяName: Уникальное имя (авто или пользовательское).Unique name (auto or user-defined).
• ТипType: Категория элемента (кнопка, поле ввода и т.д.).Element category (button, input field, etc.).
• Координаты и размерыCoordinates and Dimensions: Положение (X, Y) и размеры.Position (X, Y) and size.
• ИерархияHierarchy: Информация о связях с другими элементами.Information about relationships with other elements.
• АннотацияAnnotation: Текстовое описание элемента.Text description of the element.

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

Каждому элементу можно добавить текстовое описание или "промпт". Объясните его роль, какие данные он содержит, или какое действие нужно совершить. Поддерживается голосовой ввод! Add text description or "prompt" to each element. Explain its role, what data it should contain, or what action to perform. Voice input is supported!

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

• Текстовый вводText Input: Классический способ добавления описаний.Classic way to add descriptions.
• Голосовой вводVoice Input: Ускоряет процесс - надиктовывайте инструкции.Speeds up the process - dictate instructions.
• Указание действийSpecifying Actions: "кликнуть", "ввести текст", "выбрать из списка"."click", "enter text", "select from list".
• Описание данныхDescribing Data: "поле для email", "сумма заказа"."email field", "order amount".

Голосовая аннотацияVoice Annotation

Screph поддерживает голосовой ввод через внешний провайдер или офлайн с локальными моделями Vosk. Screph supports voice input via external provider or offline with local Vosk models.

1. Выберите элемент для аннотации.Select element for annotation.
2. Активируйте "Голосовая Аннотация" на панели инструментов.Activate "Voice Annotation" in the toolbar.
3. Говорите чётко в микрофон.Speak clearly into the microphone.
4. Нажмите "Стоп" и проверьте распознанный текст.Press "Stop" and review recognized text.

3. Сохранение и загрузка проектов 3. Saving and Loading Projects

Screph позволяет сохранять работу в файлы проектов (.sgaip) и загружать их позже. Screph allows saving work to project files (.sgaip) and loading them later.

СохранениеSaving

• Файл → Сохранить проектFile → Save Project: Перезаписывает существующий файл или создаёт новый. Горячая клавиша: Ctrl+S.Overwrites existing file or creates new. Hotkey: Ctrl+S.
• Файл → Сохранить проект как...File → Save Project As...: Выбор нового имени/места. Горячая клавиша: Ctrl+Shift+S.Choose new name/location. Hotkey: Ctrl+Shift+S.

Что сохраняетсяWhat Gets Saved

• Снимки фона (все изображения серии)Background snapshots (all images in series)
• Элементы с именами, типами, координатамиElements with names, types, coordinates
• Иерархия и связи элементовElement hierarchy and relationships
• АннотацииAnnotations
• Настройки проектаProject settings

ЗагрузкаLoading

Файл → Загрузить проект (Ctrl+O) - выберите файл .sgaip. File → Load Project (Ctrl+O) - select a .sgaip file.

4. Работа с сериями изображений 4. Working with Image Series

Серии изображений для многошаговых сценариев и динамических интерфейсов. Image series for multi-step scenarios and dynamic interfaces.

КонцепцияConcept

Серия - упорядоченный набор снимков, представляющих разные состояния приложения. Элементы и аннотации привязаны к конкретному кадру. A series is an ordered set of screenshots representing different application states. Elements and annotations are bound to specific frames.

УправлениеManagement

• ДобавлениеAdding: вкладка Захват (экран, камера, видеофайл, папка кадров, URL-поток) или Файл → Добавить изображение.the Capture tab (screen, camera, video file, image-sequence folder, URL stream) or File → Add Image.
• НавигацияNavigation: Кнопки "Следующее/Предыдущее изображение"."Next/Previous Image" buttons.
• УдалениеDeletion: "Удалить текущее изображение"."Delete Current Image".

Подробно вкладка Захват описана в отдельном руководстве. The Capture tab is described in detail in the dedicated guide.

5. Граф взаимодействий 5. Interaction Graph

Screph позволяет визуально определять связи и зависимости между элементами, выстраивая граф. Узлы - элементы, рёбра - логические переходы. Screph allows visually defining connections and dependencies between elements, building a graph. Nodes are elements, edges are logical transitions.

ПреимуществаAdvantages

• КонтекстуализацияContextualization: Понимание взаимосвязей элементов.Understanding element relationships.
• ПоследовательностьSequence: Чёткий порядок действий.Clear action order.
• ВетвленияBranching: Описание разных сценариев.Describing different scenarios.
• ВизуализацияVisualization: Контроль логики скрипта.Script logic control.

6. Подготовка данных и эмуляция 6. Data Preparation and Emulation

Screph подготавливает структурированный automation-контекст: изображения, выделения, аннотации, граф связей, состояния экрана и экспортируемый project.json. Эти данные можно использовать для эмуляции действий, для встроенного Codegen и для внешних IDE или агентных инструментов. Screph prepares a structured automation context: images, selections, annotations, relation graphs, screen states, and an exportable project.json. This data can be used for action emulation, for the built-in Codegen, and for external IDE or agent workflows.

ОсобенностиFeatures

• ЯзыкиLanguages: Фокус на Python, расширяемо на другие.Focus on Python, extendable to others.
• БиблиотекиLibraries: pyautogui, Selenium, Playwright.pyautogui, Selenium, Playwright.
• ЧитаемостьReadability: Понятный и модифицируемый код.Clear and modifiable code.

Подробный GUI-сценарий для встроенного Codegen описан ниже в разделах 8-15: запуск, автозапуск при сохранении, передаваемый контекст, Builder, preview правок и восстановление. The detailed GUI flow for the built-in Codegen is documented below in sections 8-15: launch, autostart on save, transferred context, Builder, edit preview, and recovery.

7. Интеграция с IDE 7. IDE Integration

Screph интегрируется с IDE и code tools в двух режимах. Первый режим — встроенный Codegen, который можно открыть вручную или запускать автоматически при сохранении проекта. Второй режим — экспорт проекта, JSON и связанных артефактов во внешние IDE и агентные пайплайны. Screph integrates with IDEs and code tools in two modes. The first mode is the built-in Codegen, which can be opened manually or started automatically when a project is saved. The second mode is exporting the project, JSON, and related artifacts to external IDEs and agent pipelines.

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

• Экспорт данныхExport Data: Сохранение в формате для импорта в другие инструменты.Save in format for import to other tools.
• Копирование кодаCopy Code: Буфер обмена → IDE.Clipboard → IDE.
• Файловая системаFile System: Сохранение в виде файлов.Save as files.

Если вы работаете именно со встроенным Codegen, переходите к разделам 8-15 ниже: там описаны окно Codegen, вкладки Проект и Builder, горячие клавиши, diff preview, Откат, Чекпоинты и настройки. If you are working with the built-in Codegen, continue to sections 8-15 below: they describe the Codegen window, the Project and Builder tabs, shortcuts, diff preview, Undo, Checkpoints, and settings.

8. Codegen GUI: общий контекст и предварительные условия 8. Codegen GUI: General Context and Preconditions

Ниже начинается подробное руководство по встроенному Codegen. Эти разделы раскрывают короткий обзор из предыдущих глав и описывают уже реализованный GUI-поток: выбор backend-а, запуск из Screph, передачу контекста, работу с Builder, preview правок, валидацию и восстановление. The detailed guide to the built-in Codegen starts below. These sections expand the short overview above and describe the currently implemented GUI flow: backend selection, launch from Screph, context transfer, Builder, edit preview, validation, and recovery.

Важно: этот guide относится только к режиму Codegen. В настройках интеграции с кодом нужно выбрать Способ работы с кодом: Codegen. Если выбран другой backend (Trae, PearAI и т.д.), кнопки на панели проекта будут открывать уже другой инструмент. Important: this guide applies only to the Codegen mode. In the code integration settings you need to select Codegen as the active code workflow mode. If another backend is selected (Trae, PearAI, and so on), the project-panel buttons will open a different tool.

• Codegen работает с сохранённым проектом Screph, его project.json, рабочей папкой и guide-файлом выбранной стратегии сохранения.Codegen works with a saved Screph project, its project.json, the workspace folder, and the guide file for the selected save strategy.
• Внутри Codegen есть собственное окно с редактором кода, вкладкой Артефакты, панелью Проект и панелью Builder.Inside Codegen there is a dedicated window with a code editor, an Artifacts tab, a Project panel, and a Builder panel.
• Для генерации и внесения правок используются те же настройки LLM, что выбраны для Codegen в основном приложении.Generation and editing use the same LLM settings that are configured for Codegen in the main application.

9. Как открыть Codegen и как работает автозапуск 9. How to Open Codegen and How Autostart Works

Ручной запускManual Launch

1. Откройте настройки интеграции с кодом и выберите Способ работы с кодом: Codegen.Open the code integration settings and select Codegen as the code workflow mode.
2. При необходимости задайте базовые параметры Интеграция Codegen: Папка проектов, Выходная папка, Шаблон промпта.If needed, configure the base Codegen integration options: Project folder, Output folder, and Prompt template.
3. На панели проекта используйте кнопку Открыть Codegen.Use the Open Codegen button in the project tools panel.

Автозапуск при сохранении проектаAutostart on Project Save

Чекбокс Автозапуск Codegen сохраняет флаг автозапуска. Если он включён, Screph после сохранения запускает выбранный code tool и сразу передаёт ему контекст проекта. The Autostart Codegen checkbox stores the autostart flag. If it is enabled, Screph launches the selected code tool after save and immediately sends the project context to it.

В текущей реализации это срабатывает после основных сценариев сохранения: сохранение проекта в рабочую папку, сохранение элементов в JSON и быстрое сохранение. In the current implementation this happens after the main save flows: saving a project into the workspace folder, saving elements into JSON, and quick save.

10. Что Screph передаёт в Codegen 10. What Screph Sends to Codegen

Запуск из Screph — это не просто открытие папки проекта. При сохранении формируется отдельный контекстный файл для Codegen, из которого окно заполняет поля и при необходимости сразу стартует build-flow. Launching from Screph is more than just opening the project folder. On save, Screph creates a dedicated context payload for Codegen; the window uses it to fill the fields and optionally starts the build flow immediately.

• project_jsonproject_json: путь к сохранённому JSON проекта.the path to the saved project JSON.
• output_diroutput_dir: рабочая директория проекта для generated files.the project workspace directory for generated files.
• guide_pathguide_path: guide-файл выбранной стратегии сохранения, если он найден.the guide file for the selected save strategy, if one is found.
• ФлагиFlags: include_project_json = true, include_guides = true, auto_generate = true.include_project_json = true, include_guides = true, auto_generate = true.
• Стартовое сообщениеInitial message: Сгенерируй код для проекта.Generate code for the project.

11. Карта окна Codegen и роль Builder 11. Codegen Window Map and the Role of Builder

• Левая колонка — проводник файлов рабочей директории.The left column is the file explorer for the current workspace.
• Центр — toolbar, вкладки Код и Артефакты, progress bar и статус.The center contains the toolbar, the Code and Artifacts tabs, the progress bar, and the status line.
• Правая вкладка Проект хранит пути, чекбоксы Отправлять гайды и Отправлять JSON проекта, а также Откат/Чекпоинты и блок Настройки.The right Project tab stores the paths, the Send guides and Send project JSON checkboxes, plus Undo/Checkpoints and the Settings block.
• Правая вкладка Builder содержит историю сообщений, режимы Gather/Chat/Agent, переключатель Обычный/Максимальный, быстрые действия Пояснить, Починить, Рефактор и поле ввода с drag-and-drop вложений.The right Builder tab contains the message history, the Gather/Chat/Agent modes, the Normal/Maximum context selector, quick actions Explain/Fix/Refactor, and the input field with drag-and-drop attachments.

12. Генерация, обычный Builder-чат и preview правок 12. Generation, Regular Builder Chat, and Edit Preview

Генерация нового кодаGenerating New Code

1. Сохраните проект или откройте Codegen вручную.Save the project or open Codegen manually.
2. Проверьте, что на вкладке Проект заполнены JSON и папка вывода.Verify on the Project tab that the project JSON and output folder are filled in.
3. Введите задачу в поле Builder.Enter the task in the Builder input field.
4. Для запуска build-flow используйте Ctrl+B. При автозапуске после сохранения этот шаг выполняется автоматически.Use Ctrl+B to start the build flow. When opened by autostart after save, this step runs automatically.
5. Дождитесь завершения операции: статус и progress bar обновляются по ходу генерации, а результат обычно открывается как main.py.Wait until the operation completes: the status text and progress bar update during generation, and the result is usually opened as main.py.

Обычный Builder-чатRegular Builder Chat

Enter и кнопка Отправить запускают обычный запрос в Builder-чат. Это удобно для анализа, пояснений и получения patch-ответов без немедленного build-flow. Enter and the Send button start a regular Builder chat request. This is useful for analysis, explanations, and receiving patch-style answers without starting the build flow immediately.

Preview правокEdit Preview

1. Откройте существующий файл или сначала сгенерируйте его.Open an existing file or generate it first.
2. Опишите изменение в поле Builder.Describe the change in the Builder input.
3. Используйте Ctrl+E для preview правок.Use Ctrl+E to request an edit preview.
4. Просмотрите unified diff и выберите ✅ Применить или Отменить.Review the unified diff and choose ✅ Apply or Cancel.

13. Режимы Builder, настройки и история правок 13. Builder Modes, Settings, and Edit History

• Gather — сбор контекста; Chat — диалог и анализ; Agent — основной режим для генерации и patch-flow.Gather is for gathering context; Chat is for dialogue and analysis; Agent is the main mode for generation and patch flows.
• Контекст: файл и Контекст: выделение управляют тем, что будет добавлено в запрос.Context: file and Context: selection control what gets added to the request.
• Обычный и Максимальный влияют на объём упаковки контекста.Normal and Maximum affect how much context gets packed into the request.
• Шаблоны промпта: basic_automation, advanced_automation, test_generation, optimization.Prompt templates: basic_automation, advanced_automation, test_generation, and optimization.
• Валидация: включение проверки, strict mode, auto-fix и максимальная длина строки.Validation: enabling checks, strict mode, auto-fix, and maximum line length.
• Стиль кода: type hints, docstrings, стиль docstring и black-formatting.Code style: type hints, docstrings, docstring style, and black formatting.
• Параметры генерации: image search, error handling, logging, examples и режим токенов.Generation parameters: image search, error handling, logging, examples, and token mode.
• Пути и зависимости: папка проектов, папка вывода, проверка зависимостей, установка Python/PyAutoGUI, выбор модели для Codegen.Paths and dependencies: project folder, output folder, dependency checks, installing Python/PyAutoGUI, and choosing the model for Codegen.
• Откат и Чекпоинты возвращают applied-правки и открывают историю изменений.Undo and Checkpoints restore applied changes and open the edit history.

14. Ошибки, предупреждения и восстановление 14. Errors, Warnings, and Recovery

• До запуска возможны типовые проблемы: не выбран JSON, не выбрана папка вывода, пустое поле Builder, недоступный LLM.Typical pre-run problems include: missing project JSON, no output folder, an empty Builder input, or an unavailable LLM.
• Если включён чекбокс Отправлять JSON проекта, а файл слишком большой, интерфейс предупреждает о риске переполнения контекста модели.If Send project JSON is enabled and the file is too large, the UI warns about model-context overflow risk.
• При ошибке валидации доступен диалог с тремя вариантами: Принять как есть, Повторить генерацию, Отменить.On validation failure, a dialog offers three choices: Accept as Is, Retry Generation, and Cancel.
• Если preview правок не принят, изменения не записываются на диск. Если правка уже применена, используйте Откат или Чекпоинты.If the edit preview is not accepted, the changes are not written to disk. If a change has already been applied, use Undo or Checkpoints.
• При отмене активной задачи статус переходит в Отменено пользователем.When an active task is cancelled, the status becomes Cancelled by user.

15. Практические советы по Codegen 15. Practical Codegen Tips

• Используйте Agent как основной режим для генерации и patch-flow, а Chat/Gather — для анализа и объяснений.Use Agent as the primary mode for generation and patch flows, and use Chat or Gather for analysis and explanations.
• Оставляйте Отправлять гайды включённым, если хотите, чтобы модель учитывала guide-файл выбранной стратегии сохранения.Keep Send guides enabled if you want the model to take the selected save-strategy guide file into account.
• Отключайте Отправлять JSON проекта, если проект очень большой и вам нужен только контекст открытого файла или выделения.Disable Send project JSON if the project is very large and you only need the current-file or selection context.
• Для первичной генерации используйте Ctrl+B, а для точечных изменений — Ctrl+E и preview через diff.Use Ctrl+B for the initial generation and Ctrl+E with diff preview for targeted changes.
• Сохраняйте проект перед запуском Codegen: так окно получает готовый project.json, рабочую папку и, при необходимости, автогенерацию.Save the project before launching Codegen: this gives the window a ready project.json, the workspace folder, and optional autogeneration.