Руководство пользователя 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

• Выбрать (S)Select (S): выбор существующего элемента или признака для просмотра свойств и дальнейшего действия.select an existing element or feature to inspect its properties or perform another action.
• Создать + формаCreate + shape: сначала выберите назначение — элемент изображения, Область-контейнер, пиксельный/региональный признак, шаблон, сетку или целевую точку, — затем допустимую форму: прямоугольник, эллипс, полигон или лассо. Доступные назначения зависят от режима программы.first choose the intent—an image element, container area, pixel/region feature, pattern, grid or target point—then an allowed shape: rectangle, ellipse, polygon or lasso. Available intents depend on the program mode.
• Переместить (M)Move (M): перемещение выбранного объекта без изменения формы.move the selected object without changing its shape.
• Размер (R)Resize (R): уточнение размеров, вершин или контура существующего прямоугольника, эллипса, полигона или лассо.adjust the size, vertices or outline of an existing rectangle, ellipse, polygon or lasso.
• Иерархия (H)Hierarchy (H): создание parent → child только между двумя elements. Association, flow и logical relation создаются отдельно через Relation Graph или действие Создать связь.create a parent → child relation only between two elements. Association, flow and logical relations are created separately through the Relation Graph or the Create relation action.

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

• Единый выбор intent/shapeUnified intent/shape selection: 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.C, E, P and L select rectangle, ellipse, polygon and lasso for the current intent. Shift+A directly selects a rectangular selection area. Feature shortcuts are X pixel, A region, T pattern, Y target, G region grid, Shift+P polygon and Shift+L lasso; the mode profile may hide a disallowed kind.
• ЖестыGestures: rectangle и ellipse создаются протягиванием; lasso — свободным контуром с удержанием кнопки; polygon — отдельными вершинами и завершается двойным кликом либо кликом по стартовой точке. Незавершённая форма не создаёт canonical object.create rectangles and ellipses by dragging, a lasso by drawing while holding the button, and a polygon by placing vertices; finish a polygon with a double-click or by clicking its starting point. An unfinished shape does not create a canonical object.
• Pan/zoomPan/zoom: средняя кнопка либо Space+перетаскивание левой кнопкой перемещают viewport даже поверх активного инструмента. Колесо меняет zoom; Ctrl+колесо прокручивает. Также доступны Ctrl+=, Ctrl+- и Ctrl+0.the middle button or Space plus a left-button drag pans the viewport even over an active tool. The wheel zooms; Ctrl+wheel scrolls. Ctrl+=, Ctrl+- and Ctrl+0 are also available.

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

• ВыборSelection: Клик на элемент в режиме выделения.Click on element in Select Mode.
• Набор для области на холстеCanvas area set: Ctrl+клик добавляет или убирает элемент/признак из набора, вокруг которого InfoPanel может создать selection area.Ctrl+click adds or removes an element/feature from the set that InfoPanel can wrap in a selection area.
• Множественный выбор в деревеTree multi-select: Ctrl выбирает отдельные строки, Shift — диапазон.Ctrl selects individual rows and Shift selects a range.
• Контекстное менюContext Menu: Правый клик по строке дерева элементов открывает действия: выбрать, скрыть/показать дерево, открыть подменю Модуль, удалить элемент, удалить связи, сделать областью, развернуть или свернуть поддерево.Right-click an element-tree row to select it, hide/show its subtree, delete the element, remove relations, open the Module submenu, convert it to a selection area, or expand/collapse the subtree.
• Видимость дереваTree visibility: Глазик справа от имени элемента временно скрывает или показывает элемент, его потомков и связи на холсте. Скрытые элементы не удаляются из проекта, не выбираются кликом, не становятся родителями новых областей и не принимают новые связи.The eye icon on the right side of an element name temporarily hides or shows that element, its children, and their canvas relations. Hidden elements are not deleted from the project, cannot be clicked, cannot become parents of new areas, and cannot receive new relations.
• Модуль поддереваSubtree module: Меню Модуль создает компактный 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 выполняются на уровне корня проекта, чтобы агент видел зависимости и мог менять другие части проекта.The Module menu creates a compact module.json for the selected tree branch under <project>_artifacts/modules/ plus a generated helper class next to it. The main project remains the source of truth, while the module is used as a small agent or codegen context. A small M badge in the tree row shows that the branch has a module and indicates its state. The same menu can copy an agent-ready context or refresh stale modules. During creation, you can keep refs to shared assets or build a self-contained module folder. The agent task is created next to the module, and Send to Codex writes a request through the existing Codex VS Code bridge. Opening the selected IDE/code tool and Codex sending use the project root so the agent can see dependencies and edit other project areas.
• УдалениеDelete: Выберите element или feature и нажмите Delete. Screph запрашивает подтверждение; object lock, а для element также lock связанных удаляемых объектов, блокирует операцию.select an element or feature and press Delete. Screph asks for confirmation; an object lock, including a lock on related objects removed with an element, blocks the operation.

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

Move/Resize изменяют существующую canonical запись, а не создают копию. Object lock и lock соответствующего canvas layer блокируют жест. Для polygon/path element в режиме R можно перетаскивать вершины; Tab/Shift+Tab меняют активную вершину, стрелки сдвигают её на 1 px, Shift+стрелка — на 5 px, Ctrl+стрелка — на 10 px. Enter вставляет вершину на ближайшее ребро под курсором. Двойной клик по вершине удаляет её, по ребру — вставляет новую.Move/Resize changes an existing canonical record rather than creating a copy. An object lock or the corresponding canvas-layer lock blocks the gesture. For a polygon/path element in R mode, vertices can be dragged; Tab/Shift+Tab changes the active vertex, arrow keys move it by 1 px, Shift+arrow by 5 px and Ctrl+arrow by 10 px. Enter inserts a vertex on the nearest edge under the cursor. Double-click a vertex to delete it or an edge to insert a new one.

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

Признак — канонический объект проекта, а не только рамка на canvas. В зависимости от активного профиля Selector проект может хранить pixel (точка и sampled color), region (геометрия и summary), pattern, region_grid и static_diff. Все эти записи входят в один project history и сохраняются в image_features. Инструмент Y не создаёт отдельный тип: он назначает выбранному geometry-feature target point и сохраняет offset относительно геометрии.A feature is a canonical project object, not only a canvas rectangle. Depending on the active Selector profile, the project can store pixel (a point and sampled color), region (geometry and summary), pattern, region_grid and static_diff. These records belong to one project history and are stored in image_features. The Y tool does not create a separate kind; it assigns a target point to the selected geometry feature and stores its offset from the geometry.

• ДублироватьDuplicate: контекстное меню создаёт новый ID/display ID и имя с суффиксом copy, сохраняя geometry/summary/параметры, но очищая crop, mask, preview и их asset metadata. Это новый объект, а не ещё одна ссылка на исходный asset.the context menu creates a new ID/display ID and a copy name, retaining geometry/summary/settings but clearing crop, mask, preview and their asset metadata. It is a new object, not another reference to the source asset.
• Сделать шаблономMake pattern: создаёт отдельный pattern из geometry исходного признака, берёт summary из текущего изображения, ставит target в центр и использует начальные параметры similarity 0.8, exact=false, resize 1.0. Нужен реальный источник изображения.creates a separate pattern from the source feature's geometry, samples the summary from the current image, places the target at the center and starts with similarity 0.8, exact=false and resize 1.0. A real source image is required.
• Сетка и производная областьGrid and derived region: Создать сетку из области создаёт новый region_grid с сеткой 3×3 по умолчанию; в свойствах строки и столбцы можно изменить в диапазоне 1…64. Подменю Производная область предлагает расширить, сжать, взять область слева/справа/выше/ниже; размер вводится в пикселях (для grow/inset по умолчанию 16, для соседней области 32), результат ограничивается границами source image.Create grid from area creates a new region_grid with a 3×3 grid by default; rows and columns can be changed from 1 to 64 in the inspector. The Derived region submenu offers grow, inset, left/right/above/below; the amount is entered in pixels (16 by default for grow/inset, 32 for an adjacent region), and the result is clamped to the source-image bounds.
• Static diffStatic diff: пункт появляется, если до открытия контекстного меню был выбран другой feature. Оба признака должны иметь geometry и доступный source image; результат хранит base/compare IDs, combined bbox, changed pixels и diff percent. Порог по умолчанию — 16.the item appears when another feature was selected before the context menu opened. Both features need geometry and an available source image; the result stores the base/compare IDs, a combined bbox, changed pixels and diff percent. The default threshold is 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 активного профиля могут отклонить любую такую мутацию.The feature inspector exposes the name, canonical description, authoring mode, owner, source, geometry/color/target, pattern settings, grid settings, relations, issues, a read-only JSON projection and separate matches. An owner can be manually assigned to the selected element or detached; automatic selection-area membership is a separate mechanism. Changing the target, geometry, source or grid marks existing bitmap assets stale when they exist. The active profile capability and an object lock can reject any such mutation.

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

Selection area — geometry-only контейнер: она может иметь rectangle, ellipse, polygon или lasso geometry и хранит состав элементов/признаков, но не пиксели, crop или image series. Важно: текущая membership-проверка использует bounding rectangle области, а не точное заполнение ellipse/polygon/path. По умолчанию автоматически попадают объекты, чей bounding box полностью находится в этом rectangle. При вложенных областях объект направляется в ближайшую, то есть наименьшую подходящую область.A selection area is a geometry-only container: it may use rectangle, ellipse, polygon or lasso geometry and stores element/feature membership, but no pixels, crop or image series. Importantly, current membership checks use the area's bounding rectangle rather than the exact filled ellipse/polygon/path. By default, objects whose full bounding box is contained by that rectangle are collected automatically. With nested areas, an object is routed to the nearest, smallest matching area.

• СоздатьCreate: нарисуйте назначение Область-контейнер, выберите Сделать областью для обычного элемента без изображений либо соберите элементы/признаки через Ctrl+клик и нажмите Создать область в InfoPanel. Кнопка Область вокруг строит контейнер вокруг выбранного элемента, его потомков и признаков с отступом 8 px.draw with the Container area intent, use Make area on an ordinary image-free element, or collect elements/features with Ctrl+click and press Create area in InfoPanel. Area around wraps the selected element, its descendants and features with 8 px padding.
• Управлять составомManage membership: Обновить состав повторяет автоматический сбор; Привязать... выбирает один содержащийся объект, Привязать все — всех кандидатов, а Отвязать... удаляет объект из текущей области.Refresh membership reruns automatic collection; Attach... selects one contained object, Attach all handles every candidate, and Detach... removes an object from the current area.
• Membership lockMembership lock: фиксирует для конкретного элемента или признака его текущее состояние и запрещает автоматическую перепривязку. Ручное отвязывание включает эту блокировку, ручная привязка снимает её. Это каноническое свойство объекта, отдельное от сохраняемого object lock и session-only блокировки слоя.freezes one element or feature in its current membership state and prevents automatic reassignment. Manual detach enables this lock; manual attach clears it. This is a canonical object property, distinct from a persisted object lock and a session-only layer lock.
• Перемещение и преобразованиеMove and convert: при стандартных настройках перемещение области сдвигает её дочерние элементы и признаки. В обычный удаляет семантику контейнера. Image payload блокирует обратное преобразование; имеющиеся frame bindings сначала снимаются через capture controller, и при ошибке операция отменяется.with default settings, moving an area moves its child elements and features. To ordinary removes container semantics. Image payload blocks conversion in the other direction; existing frame bindings are first released through the capture controller, and a release failure cancels the operation.

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

• ИмяName: Уникальное имя (авто или пользовательское).Unique name (auto or user-defined).
• ТипType: тип из активного каталога разметки выбранного режима программы.a type from the active markup catalog for the selected program mode.
• Координаты и размеры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. Image Inspection and Measurements

Инструменты проверки пикселей находятся во вкладке Изображение InfoPanel, а гистограмма, профиль линии и evidence-сравнение — во вкладке Анализ изображения нижней панели Capture/Images. Они работают с активной canvas presentation и не изменяют исходные пиксели. Pixel-inspection tools are available on InfoPanel's Image tab, while the histogram, line profile and evidence comparison are on the Capture/Images dock's Image Analysis tab. They operate on the active canvas presentation without changing its source pixels.

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

Кнопка раскладки в панели меню создаёт до четырёх областей одного Canvas: A; A/B слева–справа или сверху–снизу; A слева и B/C справа; либо сетку A/B/C/D 2×2. Это не копии проекта: канонические elements, features, relations, selection и project history у всех областей общие. Различаются выбранный visual material и локальные параметры его показа.The layout control in the menu-bar toolbar creates up to four panes of one Canvas: A; A/B side by side or stacked; A on the left with B/C on the right; or a 2×2 A/B/C/D grid. These are not project copies: canonical elements, features, relations, selection and project history are shared by every pane. The selected visual material and its local display settings may differ.

• Выбор и активацияSelection and activation: через шестерёнку области можно переименовать её, выбрать Source, рабочий CV-result или diagnostic presentation, режим показа и источник вырезки. Кнопка активации передаёт этой области canvas tools; stale, unmapped и read-only presentation не может стать владельцем редактирования. Такой запрос отклоняется, а если уже активная область стала несовместимой, owner возвращается к A.use a pane's settings button to rename it and select Source, a working CV result or a diagnostic presentation, its display mode and crop source. Activation routes the canvas tools to that pane; a stale, unmapped or read-only presentation cannot own editing. Such an activation request is rejected; if the current active pane becomes incompatible, ownership returns to A.
• Связанная навигацияLinked navigation: linked panes синхронизируют масштаб, центр viewport и canvas-курсор. Область A всегда входит в связанную группу; B/C/D можно отвязать для независимого zoom/pan. Навигация из совместимой read-only области всё ещё может двигать связанную группу, не передавая ей право менять разметку.linked panes synchronize scale, viewport center and the canvas-space cursor. Pane A always belongs to the linked group; B/C/D can be unlinked for independent zoom/pan. Navigation from a compatible read-only pane can still move the linked group without giving it permission to edit markup.
• Закрытие и ResetClose and Reset: A закрыть нельзя; B/C/D закрываются явно, и это не удаляет выбранное presentation. Выбор меньшей раскладки не удаляет существующие области автоматически. Общий Reset — более сильное действие: он назначает Source области A, активирует её, закрывает B/C/D и возвращает layout к одной области.A cannot be closed; B/C/D are closed explicitly, and closing a pane does not delete its selected presentation. Choosing a smaller layout never removes existing panes implicitly. The global Reset is stronger: it assigns Source to A, activates it, closes B/C/D and returns to the single-pane layout.

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

• Пиксельный probePixel probe: показывает координаты, RGB, HEX, HSV и источник сразу под курсором и отдельно фиксирует стабильное значение после 0,5 секунды. Стабильные поля или весь набор можно скопировать.shows coordinates, RGB, HEX, HSV and source immediately under the cursor, then records a stable value after 0.5 seconds. Individual stable fields or the full set can be copied.
• Что измеряетсяWhat is sampled: probe и профиль линии читают точный material-слой активной presentation. Если материал недоступен или его координаты не сопоставлены с canvas, Screph показывает diagnostic и не подменяет его незаметно raw-изображением.the probe and line profile read the exact material layer of the active presentation. If that material is unavailable or not mapped to the canvas, Screph reports a diagnostic instead of silently substituting the raw image.
• ЛупаMagnifier: режимы Контекст 31×31, Детали 15×15 и Значения 9×9, с отдельными переключателями сетки, перекрестия и рамок.Context 31×31, Detail 15×15 and Values 9×9 modes, with independent grid, crosshair and frame toggles.
• ВидView: Fit, масштаб 100%, pixel grid и изменяемый navigator/minimap. Navigator можно включать, менять его размер и использовать для перемещения viewport.Fit, 100% zoom, pixel grid and a resizable navigator/minimap. The navigator can be toggled, resized and used to recenter the viewport.

Слои canvasCanvas layers

Панель слоёв управляет шестью фиксированными группами: исходное изображение, CV-наложения, элементы и связи, признаки, preview ассистента и измерения. Для каждой группы доступны видимость, прозрачность, блокировка редактирования и перемещение выше/ниже.The layer panel controls six fixed groups: source image, CV overlays, elements and relations, features, assistant preview and measurements. Each group has visibility, opacity, edit lock and move-up/down controls.

Tone & ProfileTone & Profile

• ГистограммаHistogram: RGB, отдельные каналы или gray/LUT и уровни служат только для отображения. Это non-destructive display transform, а не изменение material или project image.combined RGB, individual channels or gray/LUT plus levels are display-only. This is a non-destructive display transform, not a change to the material or project image.
• Профиль линииLine profile: нарисуйте линию на активной presentation, чтобы получить расстояние, координаты, R/G/B и яркость вдоль неё. Можно держать несколько измерений, выбирать и удалять их, использовать локальные Undo/Redo, копировать текущий профиль как TSV или явно экспортировать CSV.draw a line on the active presentation to obtain distance, coordinates, R/G/B and luminance along it. Multiple measurements can be selected or deleted, have local Undo/Redo, and the current profile can be copied as TSV or explicitly exported as CSV.

Compare & EvidenceCompare & 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 выбранного компонента.The read-only panel pairs presentation A with a selected B, provides Fit all and 400 ms flicker comparison, then exposes Summary, Diagnostics and Provenance. Reports are bound to source/context revisions, so a mismatch marks evidence stale. Registration, stabilization and industrial components use specialized inspectors; a component report also offers Accepted/Rejected filtering, a metrics table and a read-only overlay for the selected component.

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

Аннотация — каноническое человекочитаемое описание объекта, а не отдельный prompt-файл. Текстовый и голосовой ввод изменяют одно и то же поле цели и проходят через project history.An annotation is a canonical human-readable object description, not a separate prompt file. Text and voice input update the same target field and participate in project history.

Что можно описыватьWhat can be described

• Element / feature / feature match: поле description_human в карточке InfoPanel. Голосовая панель записывает transcript сюда же; отдельный параллельный «voice transcript» текущий UI не создаёт.the description_human field in the InfoPanel card. The voice panel writes its transcript to the same field; the current UI does not create a separate parallel “voice transcript.”
• Relation edge: описание в edge inspector или диалоге Описание связи. Встроенный voice widget добавляет распознанный текст в draft; canonical edge меняется только после OK.the description in the edge inspector or Relation description dialog. Its embedded voice widget appends recognized text to the draft; the canonical edge changes only after OK.
• Image Series entry: поле annotation отдельной записи. Текст/голос в диалоге коммитятся по OK; Cancel оставляет запись без изменений. Заметка ко всему CV run редактируется отдельно и сейчас является text-only.the per-entry annotation field. Text or voice in its dialog commits on OK; Cancel leaves the entry unchanged. The whole CV-run note is edited separately and is currently text-only.

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

Выбранный recognizer — локальный Vosk либо явно настроенный Yandex, Google или OpenAI path — используется общим voice widget. Недоступный provider не заменяется другим автоматически.The selected recognizer—local Vosk or an explicitly configured Yandex, Google or OpenAI path—is used by the shared voice widget. An unavailable provider is not replaced automatically.

1. Выберите element, feature или feature match. После создания этих объектов Screph сам запрашивает аннотацию; для feature target change это происходит, только если описания ещё нет. Image-series entry, CV save, edge и CV-run note автоматически voice widget не запускают.Select an element, feature or feature match. Screph requests an annotation automatically after creating those objects; a feature target change does so only when no description exists. Image-series entries, CV saves, edges and CV-run notes do not auto-start the voice widget.
2. Для ручного запуска нажмите Голос. аннот.. Виджет открывается с текущим описанием и делает несколько коротких попыток автозапуска записи.For a manual start, press Voice annotation. The widget opens with the current description and makes several short attempts to start recording automatically.
3. Говорите чётко в микрофон; кнопка записи переключает запись и остановку.Speak clearly into the microphone; the record button toggles recording and stopping.
4. Проверьте и при необходимости отредактируйте распознанный текст, затем нажмите Готово или Ctrl+Enter.Review and, if necessary, edit the recognized text, then press Done or Ctrl+Enter.

Escape или крестик закрывает widget без отправки результата. Потеря фокуса во время активной записи/recognition, переход к другой selection operation или запуск следующей voice-сессии могут финализировать текущую; для явной отмены используйте крестик или Escape. В Общие настройки → Режим работы режимы Копировать и скрыть и Копировать, очистить и скрыть пишут transcript только в clipboard и не обновляют объект.Escape or the close button closes the widget without emitting a result. Losing focus during active recording/recognition, moving to another selection operation or starting another voice session may finalize the current session; use the close button or Escape for an explicit cancel. Under General Settings → Operating mode, Copy and hide and Copy, clear and hide write only to the clipboard and do not update the object.

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

По умолчанию 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 или выберите Не запускать семантику для аннотаций.Semantics is enabled by default, voice annotations use fast_skip_non_commands, and a high-confidence rule at or above 0.72 may apply immediately. The ✓/× buttons activate only for an intent actually placed in the review queue. require_confirmation_for_llm confirms an intent already marked requires_review; it does not itself force every LLM result through review. For guaranteed dictation-only behavior, clear Process voice annotations or select Do not run semantics for annotations.

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

Текущий проект — это каталог с каноническим <имя>.json, source images и связанными artifacts. Формат .sgaip больше не используется текущим load/save flow. A current project is a directory containing canonical <name>.json, source images and related artifacts. The current load/save flow no longer uses the .sgaip format.

СохранениеSaving

• Файл → Сохранить проектFile → Save Project: Перезаписывает существующий файл или создаёт новый. Горячая клавиша: Ctrl+S.Overwrites existing file or creates new. Hotkey: Ctrl+S.
• Файл → Настройки сохранения...File → Save Settings... (Ctrl+Shift+S): выбор среды проекта, code tool, post-save действия, места сохранения и профиля feature projection. Кнопки диалога позволяют применить профиль без записи проекта или применить его и сразу сохранить.choose the project environment, code tool, post-save behavior, save location and feature-projection profile. The dialog can apply the profile without writing the project, or apply it and save immediately.

Не путайте этот диалог с legacy-вкладкой Выбор элементов → Файлы и форматы в главном окне Settings: её видимые timestamp, PNG/JPG и JPEG-quality поля сохраняются, но текущий writer проекта их не использует.Do not confuse this dialog with the legacy Element Selection → Files & Formats tab in the main Settings window: its visible timestamp, PNG/JPG and JPEG-quality fields are persisted, but the current project writer does not use them.

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

Доступные результаты сохранения зависят от режима программы. В режиме «Автоматизация GUI» можно выбрать Screph Automate или PyAutoGUI. В режимах «Общий», «Промышленное зрение» и «Автономные беспилотники» доступны соответствующий встроенный Screph CV (OpenCV / NumPy) и вариант «Без инструментов — только проект Screph». IDE и code tool выбираются отдельно и не переключают режим программы. Available save results depend on the program mode. GUI Automation can target Screph Automate or PyAutoGUI. General, Industrial Vision, and Autonomous Unmanned Vehicles provide the corresponding built-in Screph CV (OpenCV / NumPy) environment and the “No tools — Screph project only” option. The IDE or code tool is selected separately and does not switch the program mode.

• В текущий проект перезаписывает существующий current path; если его ещё нет, Screph спрашивает имя и создаёт каталог под default project root.Current project overwrites the existing current path; when no current path exists, Screph asks for a name and creates a directory under the default project root.
• В подпроект всегда спрашивает имя и создаёт каталог внутри текущего project directory; если current project отсутствует, используется default root. Code-tool workspace при этом остаётся корнем родительского проекта.Subproject always asks for a name and creates a directory inside the current project directory; without a current project it uses the default root. The code-tool workspace remains the parent project root.
• Всегда спрашивать показывает имя и, только при существующем current project, выбор подпроекта.Always ask shows a name and, only when a current project exists, a subproject choice.

Список «Будет создано» в диалоге — краткое описание target, а не полный manifest package: он не перечисляет автоматический for_ai_agent, каталог _artifacts и условные timeline/frame-bound sidecars.The dialog's “Will be created” list is a target summary, not a complete package manifest: it omits the automatic for_ai_agent, the _artifacts directory and conditional timeline/frame-bound sidecars.

Полная таблица доступности приведена в разделе «Среды проекта и сохранение». See Project Environments and Saving for the complete availability table.

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

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

После успешного сохранения Screph автоматически создаёт рядом <name>.for_ai_agent.json. Это производная проекция для Screph Code/IDE, а не файл для повторного открытия в Selector. Timeline и frame-bound captures при наличии сохраняются в собственные sidecars; полный состав package описан в справке по данным и экспорту.After a successful save, Screph automatically creates <name>.for_ai_agent.json next to the project. It is a derived projection for Screph Code/IDE, not a file to reopen in Selector. Timeline and frame-bound captures use their own sidecars when present; see the data and export guide for the complete package.

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

Файл → Загрузить проект (Ctrl+O) открывает Менеджер проектов, а не простой file picker. Он рекурсивно рассматривает до 2000 подходящих JSON в выбранном каталоге, пропускает известные служебные файлы/artifact folders и разделяет записи на Проекты, Автосейвы и Проблемные.File → Load Project (Ctrl+O) opens the Project Manager, not a plain file picker. It recursively considers up to 2,000 eligible JSON files under the selected root, skips known service files and artifact directories, and separates entries into Projects, Autosaves and Problems.

• Для выбранного проекта доступны history, graph/tree minimap, counts, tags, notes и diagnostics.The selected project exposes history, a graph/tree minimap, counts, tags, notes and diagnostics.
• Менеджер умеет открыть, дублировать, переименовать, сохранить текущий проект в выбранную запись, восстановить autosave под новым именем и экспортировать карту в GraphML/HTML/JSON.The manager can open, duplicate or rename a project, save the current state to a selected entry, restore an autosave under a new name and export the map as GraphML/HTML/JSON.
• Выбрать файл... позволяет явно указать JSON. Canonical/autosave открывается из Manager только после schema checks и при наличии хотя бы одного element, edge, feature или feature match. Agent export не становится редактируемым проектом: если его ссылка на canonical существует, действие Открыть ведёт к этому canonical-файлу; tree module и произвольный JSON не открываются.Select file... lets you choose a JSON file explicitly. Manager opens a canonical project or autosave only after schema checks and when it contains at least one element, edge, feature or feature match. An agent export does not become an editable project: when its canonical reference exists, Open resolves to that canonical file; tree modules and arbitrary JSON remain non-openable.
• До открытия diagnostics Manager отражают роль JSON, ошибки чтения/schema, missing path и пустой domain; это не свежая полная artifact-integrity проверка. После фактической загрузки InfoPanel показывает текущий domain load report вместе с сохранёнными save reports.Before opening, Manager diagnostics cover the JSON role, read/schema failures, missing paths and an empty domain; this is not a fresh full artifact-integrity scan. After an actual load, InfoPanel shows the current domain load report together with saved save reports.
• При запуске Selector отдельно пытается восстановить autosave_session.json. Этот startup flow принимает elements/edges или один загруженный base image, поэтому autosave только со скриншотом может восстановиться при старте, хотя Manager помечает domain без объектов как неоткрываемый. Capture timeline восстанавливается своим отдельным механизмом.At startup, Selector separately attempts to restore autosave_session.json. This startup flow accepts elements or edges, or a loaded base image alone, so a screenshot-only autosave may recover at startup even though Manager treats an object-free domain as non-openable. The Capture timeline has a separate recovery mechanism.
• Ошибка selector/capture autosave при закрытии требует отдельного решения пользователя. Selector autosave пишется перед закрытием только для dirty project; Capture может сохранить recording frames отдельно.A Selector or Capture autosave failure during close requires an explicit user decision. Selector writes its close autosave only for a dirty project; Capture may persist recording frames separately.

Duplicate/rename применяются только к обычному canonical project, а restore — к autosave. Они работают с каталогом целиком и согласуют primary JSON, timeline и frame-bound sidecar, но не пересобирают agent export и не переносят локальные tags/notes Manager. После операции сохраните проект ещё раз перед handoff.Duplicate and rename apply only to regular canonical projects, while restore applies to an autosave. They operate on the whole directory and align the primary JSON, timeline and frame-bound sidecar, but do not rebuild the agent export or migrate Manager-local tags and notes. Save again before a handoff.

Убрать из истории и Очистить пропавшие меняют только список recent paths; Project Manager не удаляет project files. Tags/notes хранятся отдельно по абсолютному пути и не входят в переносимый package. При создании нового проекта Screph предлагает сохранить текущий, продолжить без сохранения или отменить операцию; существующий timeline можно явно перенести в новый проект.Remove from history and Clear missing only change the recent-path list; Project Manager does not delete project files. Tags and notes are stored separately by absolute path and are not part of the portable package. When creating a new project, Screph offers to save the current one, continue without saving or cancel; the existing timeline can be explicitly carried into the new project.

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

Image Series элемента — набор его сохранённых визуальных состояний и прикреплённых CV outputs. Это не сам Capture timeline: timeline предоставляет source frames, а записи серии входят в canonical element и при сохранении переносят нужные изображения/artifacts в project package.An element's Image Series is its collection of saved visual states and attached CV outputs. It is not the Capture timeline itself: the timeline supplies source frames, while series entries belong to the canonical element and move required images/artifacts into the project package when saved.

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

• Начальный видInitial view: для обычного нового элемента Screph старается создать запись 0 из выбранного crop source — material активной canvas presentation либо явно выбранного canonical source. Если нужный source недоступен, скрытого fallback нет.for a normal new element, Screph attempts to create entry 0 from the selected crop source: the active canvas presentation material or the explicitly selected canonical source. An unavailable source is not silently substituted.
• Добавить текущий вид в сериюAdd current view to series: не делает простой screenshot. Кнопка запускает текущий метод CV через принудительный Apply/Save для выбранного элемента и назначает следующую числовую аннотацию. Поэтому она требует доступной CV-панели и может создать несколько output tiles одного run.does not take a plain screenshot. It runs the current CV method through a forced Apply/Save for the selected element and assigns the next numeric annotation. It therefore requires the CV panel and may create multiple output tiles for one run.
• Карточка runRun card: outputs одного cv_run_id группируются вместе. Двойной клик открывает файл; контекстное меню output позволяет открыть его, сделать mask/grayscale/cutout основным или убрать конкретный output. Если удалён последний output, удаляется и запись серии.outputs sharing a cv_run_id are grouped together. Double-click opens the file; an output's context menu can open it, make mask/grayscale/cutout primary, or remove that output. Removing the final output also removes the series entry.
• Описание и reviewDescription and review: контекстное меню карточки редактирует аннотацию текстом или голосом, заметку всего CV run, открывает Assistant с контекстом записи или удаляет запись. Числовые и автоматически созданные подписи помечаются ! до ручной проверки.the card menu edits its annotation by text or voice, edits the whole CV run note, opens the Assistant with entry context, or deletes the entry. Numeric and automatically generated labels carry a ! marker until manually reviewed.

Серия из рамки и Capture timelineFrame series and Capture timeline

Контекстное меню рамки изображения даёт действия Захватить текущий кадр, Записать серию из рамки/Остановить запись серии и Показать захваченные кадры на таймлайне. Во время записи переход к новому кадру автоматически сохраняет crop рамки; одна рамка не получает повторный capture того же frame index. Рамка должна быть разблокирована, иметь корректную геометрию внутри кадра, а параллельно записывать другую рамку нельзя.An image frame's context menu provides Capture current frame, Record series from frame/Stop series recording, and Show captured frames on timeline. During recording, moving to a new frame automatically stores the frame crop; the same frame index is not captured twice for one image frame. The frame must be unlocked, have valid geometry inside the image, and another frame cannot be recorded concurrently.

Изменение geometry активной рамки останавливает запись или перезапускает её согласно настройке. Удаление диапазона timeline remap-ит surviving frame bindings, а удаление записи серии сначала очищает её frame-bound binding. Индекс хранится рядом с проектом в <name>.frame-bound-image-series-index.json; сами entry и изображения сохраняются через canonical project и artifacts.Changing the active frame's geometry stops or restarts recording according to its setting. Deleting a timeline range remaps surviving frame bindings, while deleting a series entry first clears its frame-bound binding. The index lives beside the project as <name>.frame-bound-image-series-index.json; entries and images themselves are saved through the canonical project and its artifacts.

Навигация и монтаж source timelineSource timeline navigation and editing

• Timeline поддерживает first/previous/next/last, playback, speed и loop.The timeline supports first/previous/next/last navigation, playback, speed and loop.
• Для удаления выделите диапазон и выберите Удалить выделенное с таймлайна или нажмите Ctrl+Del. Контекстное меню также убирает клип или очищает timeline; исходные media files не изменяются.To delete content, select a range and choose Delete selection from timeline or press Ctrl+Del. The context menu can also remove a clip or clear the timeline; original media files are unchanged.

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

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

Relation Graph визуализирует типизированные связи между canonical elements/features. Ребро описывает семантическое отношение и его properties; оно не становится кликом, переходом или шагом исполнения автоматически. The Relation Graph visualizes typed links between canonical elements/features. An edge describes a semantic relationship and its properties; it does not automatically become a click, transition or execution step.

Что показывает вкладка GraphWhat the Graph tab shows

• УзлыNodes: elements, selection areas, features и roots tree modules. Status отражает выбранный/скрытый объект, freshness модуля и issues признака.elements, selection areas, features and tree-module roots. Status reflects selection/visibility, module freshness and feature issues.
• ИерархияHierarchy: связи parent → child строятся из canonical parent state и показываются отдельно от произвольных relations.parent → child links are derived from canonical parent state and remain distinct from arbitrary relations.
• ВладениеOwnership: переключает системные owner → feature edges; это визуальная проекция owner_element_id, а не ещё одна редактируемая пользовательская связь.toggles system owner → feature edges; this is a visual projection of owner_element_id, not another editable user relation.
• СвязиRelations: показывает или скрывает пользовательские edges. Клик по узлу выбирает element/feature, клик по ребру открывает его свойства; control видимости у узла скрывает feature или целое element subtree.shows or hides user edges. Clicking a node selects its element/feature, clicking an edge opens its properties, and a node visibility control hides a feature or an entire element subtree.

Создание и редактирование связиCreating and editing a relation

1. Откройте контекстное меню element или feature и выберите Создать связь..., затем вторую конечную точку.Open an element or feature context menu, choose Create relation..., then select the other endpoint.
2. Выберите Ассоциация, Поток или Логическая связь; для пары element → element также доступна Иерархия. Опция Поменять направление меняет source и target до создания.Choose Association, Flow or Logical relation; Hierarchy is also available for an element → element pair. Reverse direction swaps source and target before creation.
3. Выберите edge на canvas или в Graph. Inspector показывает ID/source/target/type, редактируемое описание, read-only JSON properties и позволяет переназначить source либо target на существующий element/feature.Select the edge on the canvas or in Graph. The inspector shows ID/source/target/type, an editable description, read-only JSON properties, and can repoint source or target to an existing element/feature.
4. Контекстное меню edge также меняет тип, редактирует описание с voice input, открывает Assistant по связи или удаляет её.The edge context menu also changes type, edits the description with voice input, opens the Assistant for that relation, or deletes it.

Screph отклоняет self/missing endpoints, duplicate directed pair, hierarchy для feature и hierarchy cycle. Назначение нового parent переносит child из прежнего parent. Feature relations дополнительно зависят от capability FEATURE_RELATE активного режима.Screph rejects self/missing endpoints, a duplicate directed pair, feature hierarchy and hierarchy cycles. Assigning a new parent detaches the child from its previous parent. Feature relations also depend on the active mode's FEATURE_RELATE capability.

Feature matches — не edgesFeature matches are not edges

Блок Совпадения в свойствах feature создаёт match по другому признаку или element, хранит kind, score 0…1, source, bbox/target и описание. Эти записи сохраняются отдельно в canonical feature_matches, но Relation Graph их сейчас не рисует как пользовательские edges.The feature properties' Matches group creates a match from another feature or element and stores kind, score 0…1, source, bbox/target and description. These records persist separately under canonical feature_matches; Relation Graph does not currently render them as user edges.

Последовательность записанных действий хранится в Action Trace, а исполняемая логика — в automation script/runtime. CV Method Graph — третий отдельный граф вычислений.Recorded action order belongs to the Action Trace, while executable logic belongs to an automation script/runtime. The CV Method Graph is a third, separate computation graph.

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

В режиме «Автоматизация GUI» Screph подготавливает структурированный automation-контекст: изображения, выделения, аннотации, граф связей, состояния экрана и экспортируемый project.json. Эти данные можно использовать для эмуляции действий, для встроенного Screph Code и для внешних IDE или агентных инструментов. In GUI Automation mode, 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 Screph Code, and for external IDE or agent workflows.

В остальных режимах сохранение ведёт к каноническому проекту и встроенной CV-среде режима; GUI automation consumers там не предлагаются. In other modes, saving targets the canonical project and the mode's built-in CV environment; GUI automation consumers are not offered there.

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

• Screph Automate: project.json, main.py и runtime guide; явная кнопка Открыть результат открывает Automation Manager.project.json, main.py and a runtime guide; the explicit Open Result button opens Automation Manager.
• PyAutoGUI: project.json, main.py и отдельный guide. Для запуска нужен доступный script.runtime.project.json, main.py and a dedicated guide. Execution requires an available script.runtime.
• После canonical save Screph валидирует coordinate contract, затем подготавливает target-файлы. Ошибка блокирует безопасный automation handoff, но не удаляет уже записанные canonical/agent files.After canonical save, Screph validates the coordinate contract and then prepares target files. An error blocks a safe automation handoff but does not remove canonical/agent files already written.

Code tool после сохранения — best-effort downstream action: при выключенном/недоступном backend или ошибке launch/send уже сохранённый проект не откатывается. Контекстом служит for_ai_agent, если он доступен, иначе canonical JSON; совместимый backend может дополнительно получить generation request.Opening a code tool after save is a best-effort downstream action: a disabled or unavailable backend, or a launch/send failure, does not roll back the saved project. The context is for_ai_agent when available, otherwise canonical JSON; a compatible backend may also receive a generation request.

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

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

Screph интегрируется с IDE и code tools в двух режимах. Первый режим — встроенный Screph Code, который можно открыть вручную или запускать автоматически при сохранении проекта. Второй режим — экспорт проекта, JSON и связанных артефактов во внешние IDE и агентные пайплайны. Screph integrates with IDEs and code tools in two modes. The first mode is the built-in Screph Code, 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.

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

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

Ниже начинается подробное руководство по встроенному Screph Code. Эти разделы раскрывают короткий обзор из предыдущих глав и описывают уже реализованный GUI-поток: выбор backend-а, запуск из Screph, передачу контекста, работу с Builder, preview правок, валидацию и восстановление. The detailed guide to the built-in Screph Code 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 относится только к встроенному редактору Screph Code. В настройках интеграции с кодом нужно выбрать Редактор кода: Screph Code [Встроенный]. Если выбран другой backend (Trae, PearAI и т.д.), кнопки на панели проекта будут открывать уже другой инструмент. Important: this guide applies only to the built-in Screph Code editor. In code-integration settings, select Code editor: Screph Code [Built-in]. If another backend is selected (Trae, PearAI, and so on), the project-panel buttons will open a different tool.

• Screph Code работает с сохранённым проектом Screph, его project.json, рабочей папкой и guide-файлом выбранной стратегии сохранения.Screph Code works with a saved Screph project, its project.json, the workspace folder, and the guide file for the selected save strategy.
• Внутри Screph Code есть собственное окно с редактором кода, вкладкой Артефакты, панелью Проект и панелью Builder.Inside Screph Code there is a dedicated window with a code editor, an Artifacts tab, a Project panel, and a Builder panel.
• Для генерации и внесения правок используются те же настройки LLM, что выбраны для Screph Code в основном приложении.Generation and editing use the same LLM settings that are configured for Screph Code in the main application.
• Окно работает через отдельный процесс Pro Agent и требует доступных codegen.runtime и LLM-профиля роли codegen. Их отсутствие показывается явно.The window runs through a separate Pro Agent process and requires an available codegen.runtime and an LLM profile assigned to the codegen role. Missing dependencies are reported explicitly.

Подготовка runtime и подключений описана в разделах Зависимости и обновления и LLM-подключения.Runtime and connection setup is covered under Dependencies and updates and LLM connections.

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

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

1. Откройте настройки интеграции с кодом и выберите Редактор кода: Screph Code [Встроенный].Open code-integration settings and select Code editor: Screph Code [Built-in].
2. При необходимости задайте базовые параметры Интеграция Screph Code: Папка проектов, Выходная папка, Шаблон промпта.If needed, configure the base Screph Code integration options: Project folder, Output folder, and Prompt template.
3. На панели проекта выберите редактор в выпадающем списке и используйте кнопку Screph Code.On the project panel, select the editor in the dropdown and use the Screph Code button.

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

Чекбокс Автостарт: Screph Code сохраняет флаг post-save handoff. Если он включён, Screph после успешной подготовки target пытается запустить выбранный code tool и передать ему контекст проекта. Недоступный backend или ошибка launch/send не откатывает уже сохранённый проект. The Autostart: Screph Code checkbox stores the post-save handoff flag. When enabled, Screph attempts to launch the selected code tool and send project context after target preparation succeeds. An unavailable backend or launch/send failure does not roll back the saved project.

В текущей реализации main save flow сначала создаёт canonical/agent package, затем проверяет и готовит target и только после этого выполняет best-effort code-tool handoff. Контекстом служит agent export, если он доступен, иначе canonical JSON. In the current implementation, the primary save flow first creates the canonical/agent package, then validates and prepares the target, and only then performs the best-effort code-tool handoff. It uses the agent export as context when available, otherwise canonical JSON.

Это правило относится к основному save flow. Save из Project Manager и некоторые legacy save entrypoints передают canonical project path напрямую, даже если рядом существует for_ai_agent sidecar. Кнопка Открыть редактор только запускает выбранный tool; без post-save handoff она сама не отправляет project context.This rule applies to the primary save flow. Project Manager save and some legacy save entry points pass the canonical project path directly even when a for_ai_agent sidecar exists nearby. The Open editor button only launches the selected tool; without the post-save handoff it does not send project context by itself.

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

Запуск из Screph — это не просто открытие папки проекта. При сохранении формируется отдельный контекстный файл для Screph Code, из которого окно заполняет поля и при необходимости сразу стартует build-flow. Launching from Screph is more than just opening the project folder. On save, Screph creates a dedicated context payload for Screph Code; 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.
• Флаги handoffHandoff 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.

auto_generate — историческое имя поля: текущий consumer помещает стартовое сообщение в Builder и программно вызывает обычное действие Отправить. Отдельной команды Ctrl+B или изолированного generate-only pipeline в текущем окне нет.auto_generate is a historical field name: the current consumer places the initial message in Builder and programmatically invokes the regular Send action. The current window has no separate Ctrl+B command or isolated generate-only pipeline.

12. Карта окна Screph Code и роль Builder 12. Screph Code Window Map and the Role of Builder

• Левая колонка содержит пути JSON/Выход, ручные действия Open/Save/Save As, запуск/стоп/повтор текущего файла, runtime log/diagnostics/export и проводник workspace.The left column contains the JSON/Output paths, manual Open/Save/Save As actions, run/stop/restart for the current file, runtime log/diagnostics/export controls and the workspace explorer.
• Центральная область содержит Monaco и вкладки Код, План, Изменения, Задачи, Исполнение и Материалы. Plan/Tasks отображают agent events, Execution — child-process run, Materials — сохранённые ответы и вспомогательные результаты.The center contains Monaco and the Code, Plan, Changes, Tasks, Execution and Materials tabs. Plan/Tasks surface agent events, Execution reports the child-process run, and Materials stores responses and supporting results.
• Правая колонка Builder показывает LLM status/model, transcript, поле запроса, drag-and-drop attachments, голосовой ввод и кнопку Отправить. Enter отправляет запрос; Shift/Ctrl+Enter оставляют редактирование поля стандартному widget behavior.The right Builder column shows LLM status/model, the transcript, request input, drag-and-drop attachments, voice input and the Send button. Enter sends the request; Shift/Ctrl+Enter are left to the text widget's standard editing behavior.
• Через context menu поля запроса можно вставить ссылку на текущий файл/selection или прикрепить текущий/выбранный project file. Active document, unsaved buffer, selection и attachments передаются как structured context; большие части могут быть усечены по budget и отражены в context chips.The request-field context menu can insert a current-file/selection reference or attach the current/selected project file. The active document, unsaved buffer, selection and attachments are sent as structured context; large parts may be budget-truncated and reported in context chips.

13. Builder-запрос, запись workspace и запуск файла 13. Builder Requests, Workspace Writes and File Execution

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

1. Сохраните проект или откройте Screph Code вручную.Save the project or open Screph Code manually.
2. Проверьте пути JSON и Выход, выбранную модель и workspace. При post-save handoff они заполняются из context payload.Check the JSON and Output paths, selected model and workspace. A post-save handoff fills them from the context payload.
3. Введите конкретную задачу, при необходимости приложите файлы или ссылку на current file/selection, затем нажмите Отправить или Enter.Enter a concrete task, optionally attach files or a current-file/selection reference, then choose Send or press Enter.
4. Следите за Plan/Tasks и transcript. Stop просит текущую OpenHands conversation остановиться, но уже выполненные workspace writes автоматически не откатывает.Follow Plan/Tasks and the transcript. Stop asks the current OpenHands conversation to stop, but it does not automatically roll back workspace writes that already occurred.
5. После ответа обновите/проверьте затронутые файлы в explorer и diff через Git или другой внешний инструмент. Финальный текст агента сам по себе не является доказательством того, какие файлы изменены.After the response, refresh and inspect affected files in the explorer and use Git or another external diff tool. The agent's final text is not proof of which files changed.

Что означает ответ BuilderWhat a Builder Response Means

Текущий Builder всегда создаёт request с mode=agent. Он может только ответить текстом, но также может вызвать write-capable workspace tools. Поэтому Отправить — не read-only chat action. Write tools ограничивают путь выбранным workspace, однако отдельного confirmation на каждую операцию нет. The current Builder always creates a request with mode=agent. It may answer with text only, but it can also call write-capable workspace tools. Therefore Send is not a read-only chat action. Write tools constrain paths to the selected workspace, but there is no separate confirmation for every operation.

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

Monaco buffer сохраняется только кнопками Save/Save As. Кнопка Run — отдельное явное действие: она выполняет выбранный script в child process после доступного preflight, а Stop/Repeat управляют этим запуском. Это не Automation Runtime и не автоматическое исполнение сразу после ответа Builder.The Monaco buffer is persisted only with Save/Save As. Run is a separate explicit action: it executes the selected script in a child process after the available preflight, while Stop/Restart control that run. This is not Automation Runtime and it does not execute code automatically after a Builder response.

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

• Builder settings dialog сейчас содержит назначение LLM/model, default project/output paths и dependency actions для Python/PyAutoGUI. Старые prompt-template, validation/style и Gather/Chat/Agent controls в текущей surface отсутствуют.The current Builder settings dialog contains the LLM/model assignment, default project/output paths and dependency actions for Python/PyAutoGUI. The old prompt-template, validation/style and Gather/Chat/Agent controls are not part of the current surface.
• Plan и Tasks — проекция OpenHands events, а не список подтверждений. Changes показывает только записи, которые были явно добавлены соответствующим producer; он не перехватывает автоматически каждую workspace write.Plan and Tasks project OpenHands events; they are not an approval queue. Changes shows only records explicitly added by a matching producer; it does not automatically intercept every workspace write.
• Кнопки Откат/Чекпоинты зависят от in-memory EditHistory. Текущий основной Builder Send path не регистрирует в ней прямые screph_file edits, поэтому эти кнопки не заменяют Git, backup или проверку файлов на диске.Undo/Checkpoints depend on the in-memory EditHistory. The current primary Builder Send path does not register direct screph_file edits there, so these controls do not replace Git, a backup or disk-level file inspection.
• Materials хранит большие Builder responses и вспомогательные artifacts локального workspace state. Открытие материала в Code загружает текст в editor buffer; для записи всё равно нужен Save/Save As.Materials stores large Builder responses and supporting artifacts in local workspace state. Opening a material in Code loads text into the editor buffer; Save/Save As is still required to persist it.

15. Ошибки, предупреждения и восстановление 15. 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.
• Если context budget сокращает history/retrieval, Builder показывает context/prompt chips с dropped/truncated state. Это означает неполный контекст, а не ошибку модели.If the context budget trims history or retrieval, Builder shows context/prompt chips with dropped/truncated state. This means the context is incomplete; it is not a model error.
• Если OpenHands завершил текстовый ответ, это не гарантирует создание нужного файла. Проверьте workspace и ожидаемый target вручную.An OpenHands text response does not guarantee that the required file was created. Inspect the workspace and expected target manually.
• Stop переводит request в cancelled state, но не является rollback уже выполненных tool calls. При нежелательной записи восстанавливайте файл через Git/backup или screph_file undo_edit только пока соответствующий tool-session ещё хранит свой in-memory undo stack.Stop moves the request to a cancelled state but does not roll back completed tool calls. Recover an unwanted write through Git/a backup, or through screph_file undo_edit only while that tool session still retains its in-memory undo stack.
• Run preflight и child-process execution имеют собственные diagnostics/log/export. Ошибка запущенного script не откатывает code files и не означает crash основного Screph process.Run preflight and child-process execution have their own diagnostics/log/export. A script failure does not roll back code files and does not imply a crash of the main Screph process.

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

• До отправки запроса создайте Git commit/branch или backup workspace, особенно при post-save autostart.Create a Git commit/branch or workspace backup before sending a request, especially with post-save autostart.
• Формулируйте scope явно: целевой файл, допустимые соседние файлы, нужная проверка и запрет на запуск, если он не требуется.State the scope explicitly: target file, allowed adjacent files, required verification and a no-run constraint when execution is unnecessary.
• Используйте attachment или current-file/selection reference для точного контекста; не полагайтесь на то, что агент сам выберет нужный файл из большого workspace.Use an attachment or current-file/selection reference for precise context; do not assume the agent will select the right file in a large workspace.
• После Builder проверяйте git diff, новые/удалённые files и содержимое ожидаемого target, затем запускайте script отдельной кнопкой Run или в Automation Runtime.After Builder, inspect git diff, new/deleted files and the expected target contents, then execute the script separately with Run or in Automation Runtime.
• Сохраняйте canonical project перед handoff: так primary save flow сможет передать актуальный for_ai_agent projection и CV recipe references.Save the canonical project before handoff so the primary save flow can pass an up-to-date for_ai_agent projection and CV recipe references.