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

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

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

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

• Выбрать (S): выбор существующего элемента или признака для просмотра свойств и дальнейшего действия.
• Создать + форма: сначала выберите назначение — элемент изображения, Область-контейнер, пиксельный/региональный признак, шаблон, сетку или целевую точку, — затем допустимую форму: прямоугольник, эллипс, полигон или лассо. Доступные назначения зависят от режима программы.
• Переместить (M): перемещение выбранного объекта без изменения формы.
• Размер (R): уточнение размеров, вершин или контура существующего прямоугольника, эллипса, полигона или лассо.
• Иерархия (H): создание parent → child только между двумя elements. Association, flow и logical relation создаются отдельно через Relation Graph или действие Создать связь.

Создание формы и навигация

• Единый выбор intent/shape: C, E, P и L выбирают rectangle, ellipse, polygon и lasso для текущего назначения. Shift+A сразу включает прямоугольную selection area. Для feature доступны X pixel, A region, T pattern, Y target, G region grid, Shift+P polygon и Shift+L lasso; mode profile может скрывать недопустимый kind.
• Жесты: rectangle и ellipse создаются протягиванием; lasso — свободным контуром с удержанием кнопки; polygon — отдельными вершинами и завершается двойным кликом либо кликом по стартовой точке. Незавершённая форма не создаёт canonical object.
• Pan/zoom: средняя кнопка либо Space+перетаскивание левой кнопкой перемещают viewport даже поверх активного инструмента. Колесо меняет zoom; Ctrl+колесо прокручивает. Также доступны Ctrl+=, Ctrl+- и Ctrl+0.

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

• Выбор: Клик на элемент в режиме выделения.
• Набор для области на холсте: Ctrl+клик добавляет или убирает элемент/признак из набора, вокруг которого InfoPanel может создать selection area.
• Множественный выбор в дереве: Ctrl выбирает отдельные строки, Shift — диапазон.
• Контекстное меню: Правый клик по строке дерева элементов открывает действия: выбрать, скрыть/показать дерево, открыть подменю Модуль, удалить элемент, удалить связи, сделать областью, развернуть или свернуть поддерево.
• Видимость дерева: Глазик справа от имени элемента временно скрывает или показывает элемент, его потомков и связи на холсте. Скрытые элементы не удаляются из проекта, не выбираются кликом, не становятся родителями новых областей и не принимают новые связи.
• Модуль поддерева: Меню Модуль создает компактный module.json для выбранной ветки дерева в папке <project>_artifacts/modules/ и generated helper-класс рядом с ним. Основной проект остается источником правды, а модуль используется как малый контекст для агента или codegen. Маленький badge M в строке дерева показывает, что у ветки есть модуль и в каком он состоянии. В том же меню можно скопировать готовый контекст для агента или обновить устаревшие модули. При создании можно оставить ссылки на общие assets или собрать self-contained папку модуля. Agent task создается рядом с модулем, а Отправить в Codex пишет request через существующий Codex VS Code bridge. Открытие выбранного IDE/code-tool и отправка в Codex выполняются на уровне корня проекта, чтобы агент видел зависимости и мог менять другие части проекта.
• Удаление: Выберите element или feature и нажмите Delete. Screph запрашивает подтверждение; object lock, а для element также lock связанных удаляемых объектов, блокирует операцию.

Перемещение, вершины и подтверждение geometry

Move/Resize изменяют существующую canonical запись, а не создают копию. Object lock и lock соответствующего canvas layer блокируют жест. Для polygon/path element в режиме R можно перетаскивать вершины; Tab/Shift+Tab меняют активную вершину, стрелки сдвигают её на 1 px, Shift+стрелка — на 5 px, Ctrl+стрелка — на 10 px. Enter вставляет вершину на ближайшее ребро под курсором. Двойной клик по вершине удаляет её, по ребру — вставляет новую.

Жизненный цикл признака

Признак — канонический объект проекта, а не только рамка на canvas. В зависимости от активного профиля Selector проект может хранить pixel (точка и sampled color), region (геометрия и summary), pattern, region_grid и static_diff. Все эти записи входят в один project history и сохраняются в image_features. Инструмент Y не создаёт отдельный тип: он назначает выбранному geometry-feature target point и сохраняет offset относительно геометрии.

• Дублировать: контекстное меню создаёт новый ID/display ID и имя с суффиксом copy, сохраняя geometry/summary/параметры, но очищая crop, mask, preview и их asset metadata. Это новый объект, а не ещё одна ссылка на исходный asset.
• Сделать шаблоном: создаёт отдельный pattern из geometry исходного признака, берёт summary из текущего изображения, ставит target в центр и использует начальные параметры similarity 0.8, exact=false, resize 1.0. Нужен реальный источник изображения.
• Сетка и производная область: Создать сетку из области создаёт новый region_grid с сеткой 3×3 по умолчанию; в свойствах строки и столбцы можно изменить в диапазоне 1…64. Подменю Производная область предлагает расширить, сжать, взять область слева/справа/выше/ниже; размер вводится в пикселях (для grow/inset по умолчанию 16, для соседней области 32), результат ограничивается границами source image.
• Static diff: пункт появляется, если до открытия контекстного меню был выбран другой feature. Оба признака должны иметь geometry и доступный source image; результат хранит base/compare IDs, combined bbox, changed pixels и diff percent. Порог по умолчанию — 16.

В инспекторе признака доступны имя, canonical description, режим создания, owner, source, geometry/color/target, pattern settings, grid settings, relations, issues, read-only JSON projection и отдельные matches. Owner можно вручную назначить на выбранный element или снять; автоматическая membership selection area остаётся отдельным механизмом. Изменение target, geometry, source или grid помечает уже сохранённые bitmap assets stale, когда они существуют. Object lock и capability активного профиля могут отклонить любую такую мутацию.

Selection area: состав и границы

Selection area — geometry-only контейнер: она может иметь rectangle, ellipse, polygon или lasso geometry и хранит состав элементов/признаков, но не пиксели, crop или image series. Важно: текущая membership-проверка использует bounding rectangle области, а не точное заполнение ellipse/polygon/path. По умолчанию автоматически попадают объекты, чей bounding box полностью находится в этом rectangle. При вложенных областях объект направляется в ближайшую, то есть наименьшую подходящую область.

• Создать: нарисуйте назначение Область-контейнер, выберите Сделать областью для обычного элемента без изображений либо соберите элементы/признаки через Ctrl+клик и нажмите Создать область в InfoPanel. Кнопка Область вокруг строит контейнер вокруг выбранного элемента, его потомков и признаков с отступом 8 px.
• Управлять составом: Обновить состав повторяет автоматический сбор; Привязать... выбирает один содержащийся объект, Привязать все — всех кандидатов, а Отвязать... удаляет объект из текущей области.
• Membership lock: фиксирует для конкретного элемента или признака его текущее состояние и запрещает автоматическую перепривязку. Ручное отвязывание включает эту блокировку, ручная привязка снимает её. Это каноническое свойство объекта, отдельное от сохраняемого object lock и session-only блокировки слоя.
• Перемещение и преобразование: при стандартных настройках перемещение области сдвигает её дочерние элементы и признаки. В обычный удаляет семантику контейнера. Image payload блокирует обратное преобразование; имеющиеся frame bindings сначала снимаются через capture controller, и при ошибке операция отменяется.

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

• Имя: Уникальное имя (авто или пользовательское).
• Тип: тип из активного каталога разметки выбранного режима программы.
• Координаты и размеры: Положение (X, Y) и размеры.
• Иерархия: Информация о связях с другими элементами.
• Аннотация: Текстовое описание элемента.

2. Инспекция изображения и измерения

Инструменты проверки пикселей находятся во вкладке Изображение InfoPanel, а гистограмма, профиль линии и evidence-сравнение — во вкладке Анализ изображения нижней панели Capture/Images. Они работают с активной canvas presentation и не изменяют исходные пиксели.

Представления A/B/C/D

Кнопка раскладки в панели меню создаёт до четырёх областей одного Canvas: A; A/B слева–справа или сверху–снизу; A слева и B/C справа; либо сетку A/B/C/D 2×2. Это не копии проекта: канонические elements, features, relations, selection и project history у всех областей общие. Различаются выбранный visual material и локальные параметры его показа.

• Выбор и активация: через шестерёнку области можно переименовать её, выбрать Source, рабочий CV-result или diagnostic presentation, режим показа и источник вырезки. Кнопка активации передаёт этой области canvas tools; stale, unmapped и read-only presentation не может стать владельцем редактирования. Такой запрос отклоняется, а если уже активная область стала несовместимой, owner возвращается к A.
• Связанная навигация: linked panes синхронизируют масштаб, центр viewport и canvas-курсор. Область A всегда входит в связанную группу; B/C/D можно отвязать для независимого zoom/pan. Навигация из совместимой read-only области всё ещё может двигать связанную группу, не передавая ей право менять разметку.
• Закрытие и Reset: A закрыть нельзя; B/C/D закрываются явно, и это не удаляет выбранное presentation. Выбор меньшей раскладки не удаляет существующие области автоматически. Общий Reset — более сильное действие: он назначает Source области A, активирует её, закрывает B/C/D и возвращает layout к одной области.

Пиксель, лупа и навигация

• Пиксельный probe: показывает координаты, RGB, HEX, HSV и источник сразу под курсором и отдельно фиксирует стабильное значение после 0,5 секунды. Стабильные поля или весь набор можно скопировать.
• Что измеряется: probe и профиль линии читают точный material-слой активной presentation. Если материал недоступен или его координаты не сопоставлены с canvas, Screph показывает diagnostic и не подменяет его незаметно raw-изображением.
• Лупа: режимы Контекст 31×31, Детали 15×15 и Значения 9×9, с отдельными переключателями сетки, перекрестия и рамок.
• Вид: Fit, масштаб 100%, pixel grid и изменяемый navigator/minimap. Navigator можно включать, менять его размер и использовать для перемещения viewport.

Слои canvas

Панель слоёв управляет шестью фиксированными группами: исходное изображение, CV-наложения, элементы и связи, признаки, preview ассистента и измерения. Для каждой группы доступны видимость, прозрачность, блокировка редактирования и перемещение выше/ниже.

Tone & Profile

• Гистограмма: RGB, отдельные каналы или gray/LUT и уровни служат только для отображения. Это non-destructive display transform, а не изменение material или project image.
• Профиль линии: нарисуйте линию на активной presentation, чтобы получить расстояние, координаты, R/G/B и яркость вдоль неё. Можно держать несколько измерений, выбирать и удалять их, использовать локальные Undo/Redo, копировать текущий профиль как TSV или явно экспортировать CSV.

Compare & Evidence

Read-only панель сопоставляет presentation A с выбранной B, включает Fit all и мерцающее сравнение с шагом 400 мс, а затем показывает Summary, Diagnostics и Provenance. Отчёт привязан к revision source/context: несовпадение помечает evidence как stale. Для registration, stabilization и industrial components используются специализированные inspectors; component-отчёт дополнительно даёт фильтр Accepted/Rejected, таблицу метрик и read-only overlay выбранного компонента.

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

Аннотация — каноническое человекочитаемое описание объекта, а не отдельный prompt-файл. Текстовый и голосовой ввод изменяют одно и то же поле цели и проходят через project history.

Что можно описывать

• Element / feature / feature match: поле description_human в карточке InfoPanel. Голосовая панель записывает transcript сюда же; отдельный параллельный «voice transcript» текущий UI не создаёт.
• Relation edge: описание в edge inspector или диалоге Описание связи. Встроенный voice widget добавляет распознанный текст в draft; canonical edge меняется только после OK.
• Image Series entry: поле annotation отдельной записи. Текст/голос в диалоге коммитятся по OK; Cancel оставляет запись без изменений. Заметка ко всему CV run редактируется отдельно и сейчас является text-only.

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

Выбранный recognizer — локальный Vosk либо явно настроенный Yandex, Google или OpenAI path — используется общим voice widget. Недоступный provider не заменяется другим автоматически.

1. Выберите element, feature или feature match. После создания этих объектов Screph сам запрашивает аннотацию; для feature target change это происходит, только если описания ещё нет. Image-series entry, CV save, edge и CV-run note автоматически voice widget не запускают.
2. Для ручного запуска нажмите Голос. аннот.. Виджет открывается с текущим описанием и делает несколько коротких попыток автозапуска записи.
3. Говорите чётко в микрофон; кнопка записи переключает запись и остановку.
4. Проверьте и при необходимости отредактируйте распознанный текст, затем нажмите Готово или Ctrl+Enter.

Escape или крестик закрывает widget без отправки результата. Потеря фокуса во время активной записи/recognition, переход к другой selection operation или запуск следующей voice-сессии могут финализировать текущую; для явной отмены используйте крестик или Escape. В Общие настройки → Режим работы режимы Копировать и скрыть и Копировать, очистить и скрыть пишут transcript только в clipboard и не обновляют объект.

Аннотация и semantic-команда

По умолчанию semantics включена, для voice annotations действует fast_skip_non_commands, а high-confidence rule с confidence не ниже 0.72 может примениться сразу. Кнопки ✓/× активируются только для intent, реально поставленного в review queue. Настройка require_confirmation_for_llm подтверждает intent, уже помеченный requires_review; она сама не делает review обязательным для каждого LLM result. Для гарантированно чистой диктовки снимите Обрабатывать voice annotations или выберите Не запускать семантику для аннотаций.

4. Сохранение и загрузка проектов

Текущий проект — это каталог с каноническим <имя>.json, source images и связанными artifacts. Формат .sgaip больше не используется текущим load/save flow.

Сохранение

• Файл → Сохранить проект: Перезаписывает существующий файл или создаёт новый. Горячая клавиша: Ctrl+S.
• Файл → Настройки сохранения... (Ctrl+Shift+S): выбор среды проекта, code tool, post-save действия, места сохранения и профиля feature projection. Кнопки диалога позволяют применить профиль без записи проекта или применить его и сразу сохранить.

Не путайте этот диалог с legacy-вкладкой Выбор элементов → Файлы и форматы в главном окне Settings: её видимые timestamp, PNG/JPG и JPEG-quality поля сохраняются, но текущий writer проекта их не использует.

Среда проекта

Доступные результаты сохранения зависят от режима программы. В режиме «Автоматизация GUI» можно выбрать Screph Automate или PyAutoGUI. В режимах «Общий», «Промышленное зрение» и «Автономные беспилотники» доступны соответствующий встроенный Screph CV (OpenCV / NumPy) и вариант «Без инструментов — только проект Screph». IDE и code tool выбираются отдельно и не переключают режим программы.

• В текущий проект перезаписывает существующий current path; если его ещё нет, Screph спрашивает имя и создаёт каталог под default project root.
• В подпроект всегда спрашивает имя и создаёт каталог внутри текущего project directory; если current project отсутствует, используется default root. Code-tool workspace при этом остаётся корнем родительского проекта.
• Всегда спрашивать показывает имя и, только при существующем current project, выбор подпроекта.

Список «Будет создано» в диалоге — краткое описание target, а не полный manifest package: он не перечисляет автоматический for_ai_agent, каталог _artifacts и условные timeline/frame-bound sidecars.

Полная таблица доступности приведена в разделе «Среды проекта и сохранение».

Что сохраняется

• source images и привязки Capture/timeline;
• elements, features, geometry, annotations, typed relations и markup groups;
• registry entries tree modules, CV result references и выбранный save profile;
• save/load diagnostics и artifact integrity report.

После успешного сохранения Screph автоматически создаёт рядом <name>.for_ai_agent.json. Это производная проекция для Screph Code/IDE, а не файл для повторного открытия в Selector. Timeline и frame-bound captures при наличии сохраняются в собственные sidecars; полный состав package описан в справке по данным и экспорту.

Загрузка и восстановление

Файл → Загрузить проект (Ctrl+O) открывает Менеджер проектов, а не простой file picker. Он рекурсивно рассматривает до 2000 подходящих JSON в выбранном каталоге, пропускает известные служебные файлы/artifact folders и разделяет записи на Проекты, Автосейвы и Проблемные.

• Для выбранного проекта доступны history, graph/tree minimap, counts, tags, notes и diagnostics.
• Менеджер умеет открыть, дублировать, переименовать, сохранить текущий проект в выбранную запись, восстановить autosave под новым именем и экспортировать карту в GraphML/HTML/JSON.
• Выбрать файл... позволяет явно указать JSON. Canonical/autosave открывается из Manager только после schema checks и при наличии хотя бы одного element, edge, feature или feature match. Agent export не становится редактируемым проектом: если его ссылка на canonical существует, действие Открыть ведёт к этому canonical-файлу; tree module и произвольный JSON не открываются.
• До открытия diagnostics Manager отражают роль JSON, ошибки чтения/schema, missing path и пустой domain; это не свежая полная artifact-integrity проверка. После фактической загрузки InfoPanel показывает текущий domain load report вместе с сохранёнными save reports.
• При запуске Selector отдельно пытается восстановить autosave_session.json. Этот startup flow принимает elements/edges или один загруженный base image, поэтому autosave только со скриншотом может восстановиться при старте, хотя Manager помечает domain без объектов как неоткрываемый. Capture timeline восстанавливается своим отдельным механизмом.
• Ошибка selector/capture autosave при закрытии требует отдельного решения пользователя. Selector autosave пишется перед закрытием только для dirty project; Capture может сохранить recording frames отдельно.

Duplicate/rename применяются только к обычному canonical project, а restore — к autosave. Они работают с каталогом целиком и согласуют primary JSON, timeline и frame-bound sidecar, но не пересобирают agent export и не переносят локальные tags/notes Manager. После операции сохраните проект ещё раз перед handoff.

Убрать из истории и Очистить пропавшие меняют только список recent paths; Project Manager не удаляет project files. Tags/notes хранятся отдельно по абсолютному пути и не входят в переносимый package. При создании нового проекта Screph предлагает сохранить текущий, продолжить без сохранения или отменить операцию; существующий timeline можно явно перенести в новый проект.

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

Image Series элемента — набор его сохранённых визуальных состояний и прикреплённых CV outputs. Это не сам Capture timeline: timeline предоставляет source frames, а записи серии входят в canonical element и при сохранении переносят нужные изображения/artifacts в project package.

Серия выбранного элемента в InfoPanel

• Начальный вид: для обычного нового элемента Screph старается создать запись 0 из выбранного crop source — material активной canvas presentation либо явно выбранного canonical source. Если нужный source недоступен, скрытого fallback нет.
• Добавить текущий вид в серию: не делает простой screenshot. Кнопка запускает текущий метод CV через принудительный Apply/Save для выбранного элемента и назначает следующую числовую аннотацию. Поэтому она требует доступной CV-панели и может создать несколько output tiles одного run.
• Карточка run: outputs одного cv_run_id группируются вместе. Двойной клик открывает файл; контекстное меню output позволяет открыть его, сделать mask/grayscale/cutout основным или убрать конкретный output. Если удалён последний output, удаляется и запись серии.
• Описание и review: контекстное меню карточки редактирует аннотацию текстом или голосом, заметку всего CV run, открывает Assistant с контекстом записи или удаляет запись. Числовые и автоматически созданные подписи помечаются ! до ручной проверки.

Серия из рамки и Capture timeline

Контекстное меню рамки изображения даёт действия Захватить текущий кадр, Записать серию из рамки/Остановить запись серии и Показать захваченные кадры на таймлайне. Во время записи переход к новому кадру автоматически сохраняет crop рамки; одна рамка не получает повторный capture того же frame index. Рамка должна быть разблокирована, иметь корректную геометрию внутри кадра, а параллельно записывать другую рамку нельзя.

Изменение geometry активной рамки останавливает запись или перезапускает её согласно настройке. Удаление диапазона timeline remap-ит surviving frame bindings, а удаление записи серии сначала очищает её frame-bound binding. Индекс хранится рядом с проектом в <name>.frame-bound-image-series-index.json; сами entry и изображения сохраняются через canonical project и artifacts.

Навигация и монтаж source timeline

• Timeline поддерживает first/previous/next/last, playback, speed и loop.
• Для удаления выделите диапазон и выберите Удалить выделенное с таймлайна или нажмите Ctrl+Del. Контекстное меню также убирает клип или очищает timeline; исходные media files не изменяются.

Подробно вкладка Захват описана в отдельном руководстве.

6. Граф связей разметки

Relation Graph визуализирует типизированные связи между canonical elements/features. Ребро описывает семантическое отношение и его properties; оно не становится кликом, переходом или шагом исполнения автоматически.

Что показывает вкладка Graph

• Узлы: elements, selection areas, features и roots tree modules. Status отражает выбранный/скрытый объект, freshness модуля и issues признака.
• Иерархия: связи parent → child строятся из canonical parent state и показываются отдельно от произвольных relations.
• Владение: переключает системные owner → feature edges; это визуальная проекция owner_element_id, а не ещё одна редактируемая пользовательская связь.
• Связи: показывает или скрывает пользовательские edges. Клик по узлу выбирает element/feature, клик по ребру открывает его свойства; control видимости у узла скрывает feature или целое element subtree.

Создание и редактирование связи

1. Откройте контекстное меню element или feature и выберите Создать связь..., затем вторую конечную точку.
2. Выберите Ассоциация, Поток или Логическая связь; для пары element → element также доступна Иерархия. Опция Поменять направление меняет source и target до создания.
3. Выберите edge на canvas или в Graph. Inspector показывает ID/source/target/type, редактируемое описание, read-only JSON properties и позволяет переназначить source либо target на существующий element/feature.
4. Контекстное меню edge также меняет тип, редактирует описание с voice input, открывает Assistant по связи или удаляет её.

Screph отклоняет self/missing endpoints, duplicate directed pair, hierarchy для feature и hierarchy cycle. Назначение нового parent переносит child из прежнего parent. Feature relations дополнительно зависят от capability FEATURE_RELATE активного режима.

Feature matches — не edges

Блок Совпадения в свойствах feature создаёт match по другому признаку или element, хранит kind, score 0…1, source, bbox/target и описание. Эти записи сохраняются отдельно в canonical feature_matches, но Relation Graph их сейчас не рисует как пользовательские edges.

Последовательность записанных действий хранится в Action Trace, а исполняемая логика — в automation script/runtime. CV Method Graph — третий отдельный граф вычислений.

7. Подготовка данных и эмуляция

В режиме «Автоматизация GUI» Screph подготавливает структурированный automation-контекст: изображения, выделения, аннотации, граф связей, состояния экрана и экспортируемый project.json. Эти данные можно использовать для эмуляции действий, для встроенного Screph Code и для внешних IDE или агентных инструментов.

В остальных режимах сохранение ведёт к каноническому проекту и встроенной CV-среде режима; GUI automation consumers там не предлагаются.

Фактические выходы GUI Automation

• Screph Automate: project.json, main.py и runtime guide; явная кнопка Открыть результат открывает Automation Manager.
• PyAutoGUI: project.json, main.py и отдельный guide. Для запуска нужен доступный script.runtime.
• После canonical save Screph валидирует coordinate contract, затем подготавливает target-файлы. Ошибка блокирует безопасный automation handoff, но не удаляет уже записанные canonical/agent files.

Code tool после сохранения — best-effort downstream action: при выключенном/недоступном backend или ошибке launch/send уже сохранённый проект не откатывается. Контекстом служит for_ai_agent, если он доступен, иначе canonical JSON; совместимый backend может дополнительно получить generation request.

Подробный GUI-сценарий для встроенного Screph Code описан ниже в разделах 8-15: запуск, автозапуск при сохранении, передаваемый контекст, Builder, preview правок и восстановление.

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

Screph интегрируется с IDE и code tools в двух режимах. Первый режим — встроенный Screph Code, который можно открыть вручную или запускать автоматически при сохранении проекта. Второй режим — экспорт проекта, JSON и связанных артефактов во внешние IDE и агентные пайплайны.

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

• Экспорт данных: Сохранение в формате для импорта в другие инструменты.
• Копирование кода: Буфер обмена → IDE.
• Файловая система: Сохранение в виде файлов.

Если вы работаете именно со встроенным Screph Code, переходите к разделам 8-15 ниже: там описаны окно Screph Code, вкладки Проект и Builder, горячие клавиши, diff preview, Откат, Чекпоинты и настройки.

9. Screph Code GUI: общий контекст и предварительные условия

Ниже начинается подробное руководство по встроенному Screph Code. Эти разделы раскрывают короткий обзор из предыдущих глав и описывают уже реализованный GUI-поток: выбор backend-а, запуск из Screph, передачу контекста, работу с Builder, preview правок, валидацию и восстановление.

Важно: этот guide относится только к встроенному редактору Screph Code. В настройках интеграции с кодом нужно выбрать Редактор кода: Screph Code [Встроенный]. Если выбран другой backend (Trae, PearAI и т.д.), кнопки на панели проекта будут открывать уже другой инструмент.

• Screph Code работает с сохранённым проектом Screph, его project.json, рабочей папкой и guide-файлом выбранной стратегии сохранения.
• Внутри Screph Code есть собственное окно с редактором кода, вкладкой Артефакты, панелью Проект и панелью Builder.
• Для генерации и внесения правок используются те же настройки LLM, что выбраны для Screph Code в основном приложении.
• Окно работает через отдельный процесс Pro Agent и требует доступных codegen.runtime и LLM-профиля роли codegen. Их отсутствие показывается явно.

Подготовка runtime и подключений описана в разделах Зависимости и обновления и LLM-подключения.

10. Как открыть Screph Code и как работает автозапуск

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

1. Откройте настройки интеграции с кодом и выберите Редактор кода: Screph Code [Встроенный].
2. При необходимости задайте базовые параметры Интеграция Screph Code: Папка проектов, Выходная папка, Шаблон промпта.
3. На панели проекта выберите редактор в выпадающем списке и используйте кнопку Screph Code.

Автозапуск при сохранении проекта

Чекбокс Автостарт: Screph Code сохраняет флаг post-save handoff. Если он включён, Screph после успешной подготовки target пытается запустить выбранный code tool и передать ему контекст проекта. Недоступный backend или ошибка launch/send не откатывает уже сохранённый проект.

В текущей реализации main save flow сначала создаёт canonical/agent package, затем проверяет и готовит target и только после этого выполняет best-effort code-tool handoff. Контекстом служит agent export, если он доступен, иначе canonical JSON.

Это правило относится к основному save flow. Save из Project Manager и некоторые legacy save entrypoints передают canonical project path напрямую, даже если рядом существует for_ai_agent sidecar. Кнопка Открыть редактор только запускает выбранный tool; без post-save handoff она сама не отправляет project context.

11. Что Screph передаёт в Screph Code

Запуск из Screph — это не просто открытие папки проекта. При сохранении формируется отдельный контекстный файл для Screph Code, из которого окно заполняет поля и при необходимости сразу стартует build-flow.

• project_json: путь к сохранённому JSON проекта.
• output_dir: рабочая директория проекта для generated files.
• guide_path: guide-файл выбранной стратегии сохранения, если он найден.
• Флаги handoff: include_project_json = true, include_guides = true, auto_generate = true.
• Стартовое сообщение: Сгенерируй код для проекта.

auto_generate — историческое имя поля: текущий consumer помещает стартовое сообщение в Builder и программно вызывает обычное действие Отправить. Отдельной команды Ctrl+B или изолированного generate-only pipeline в текущем окне нет.

12. Карта окна Screph Code и роль Builder

• Левая колонка содержит пути JSON/Выход, ручные действия Open/Save/Save As, запуск/стоп/повтор текущего файла, runtime log/diagnostics/export и проводник workspace.
• Центральная область содержит Monaco и вкладки Код, План, Изменения, Задачи, Исполнение и Материалы. Plan/Tasks отображают agent events, Execution — child-process run, Materials — сохранённые ответы и вспомогательные результаты.
• Правая колонка Builder показывает LLM status/model, transcript, поле запроса, drag-and-drop attachments, голосовой ввод и кнопку Отправить. Enter отправляет запрос; Shift/Ctrl+Enter оставляют редактирование поля стандартному widget behavior.
• Через context menu поля запроса можно вставить ссылку на текущий файл/selection или прикрепить текущий/выбранный project file. Active document, unsaved buffer, selection и attachments передаются как structured context; большие части могут быть усечены по budget и отражены в context chips.

13. Builder-запрос, запись workspace и запуск файла

Отправка задачи Builder

1. Сохраните проект или откройте Screph Code вручную.
2. Проверьте пути JSON и Выход, выбранную модель и workspace. При post-save handoff они заполняются из context payload.
3. Введите конкретную задачу, при необходимости приложите файлы или ссылку на current file/selection, затем нажмите Отправить или Enter.
4. Следите за Plan/Tasks и transcript. Stop просит текущую OpenHands conversation остановиться, но уже выполненные workspace writes автоматически не откатывает.
5. После ответа обновите/проверьте затронутые файлы в explorer и diff через Git или другой внешний инструмент. Финальный текст агента сам по себе не является доказательством того, какие файлы изменены.

Что означает ответ Builder

Текущий Builder всегда создаёт request с mode=agent. Он может только ответить текстом, но также может вызвать write-capable workspace tools. Поэтому Отправить — не read-only chat action. Write tools ограничивают путь выбранным workspace, однако отдельного confirmation на каждую операцию нет.

Ручное редактирование и выполнение

Monaco buffer сохраняется только кнопками Save/Save As. Кнопка Run — отдельное явное действие: она выполняет выбранный script в child process после доступного preflight, а Stop/Repeat управляют этим запуском. Это не Automation Runtime и не автоматическое исполнение сразу после ответа Builder.

14. Настройки, вкладки и история

• Builder settings dialog сейчас содержит назначение LLM/model, default project/output paths и dependency actions для Python/PyAutoGUI. Старые prompt-template, validation/style и Gather/Chat/Agent controls в текущей surface отсутствуют.
• Plan и Tasks — проекция OpenHands events, а не список подтверждений. Changes показывает только записи, которые были явно добавлены соответствующим producer; он не перехватывает автоматически каждую workspace write.
• Кнопки Откат/Чекпоинты зависят от in-memory EditHistory. Текущий основной Builder Send path не регистрирует в ней прямые screph_file edits, поэтому эти кнопки не заменяют Git, backup или проверку файлов на диске.
• Materials хранит большие Builder responses и вспомогательные artifacts локального workspace state. Открытие материала в Code загружает текст в editor buffer; для записи всё равно нужен Save/Save As.

15. Ошибки, предупреждения и восстановление

• До запуска возможны типовые проблемы: не выбран JSON, не выбрана папка вывода, пустое поле Builder, недоступный LLM.
• Если context budget сокращает history/retrieval, Builder показывает context/prompt chips с dropped/truncated state. Это означает неполный контекст, а не ошибку модели.
• Если OpenHands завершил текстовый ответ, это не гарантирует создание нужного файла. Проверьте workspace и ожидаемый target вручную.
• Stop переводит request в cancelled state, но не является rollback уже выполненных tool calls. При нежелательной записи восстанавливайте файл через Git/backup или screph_file undo_edit только пока соответствующий tool-session ещё хранит свой in-memory undo stack.
• Run preflight и child-process execution имеют собственные diagnostics/log/export. Ошибка запущенного script не откатывает code files и не означает crash основного Screph process.

16. Практические советы по Screph Code

• До отправки запроса создайте Git commit/branch или backup workspace, особенно при post-save autostart.
• Формулируйте scope явно: целевой файл, допустимые соседние файлы, нужная проверка и запрет на запуск, если он не требуется.
• Используйте attachment или current-file/selection reference для точного контекста; не полагайтесь на то, что агент сам выберет нужный файл из большого workspace.
• После Builder проверяйте git diff, новые/удалённые files и содержимое ожидаемого target, затем запускайте script отдельной кнопкой Run или в Automation Runtime.
• Сохраняйте canonical project перед handoff: так primary save flow сможет передать актуальный for_ai_agent projection и CV recipe references.