Данные, сохранение и экспортData, saving and exports

Что появляется после сохраненияWhat appears after saving

Video CV: runtime, markup и export — разные данныеVideo CV: runtime, markup and export are different data

Video CV workflow и track apply →Video CV workflow and track apply →

Что находится в canonical projectWhat the canonical project contains

• project_info, coordinate contract и canvas object/layer state;project_info, the coordinate contract and canvas object/layer state;
• context, Capture context, source-image references и timeline selection;context, Capture context, source-image references and timeline selection;
• gui_elements, image features/matches, geometry, annotations, typed edges, regions и markup groups;gui_elements, image features/matches, geometry, annotations, typed edges, regions and markup groups;
• выбранный save profile, registry entries tree modules и ссылка на CV result manifest;the selected save profile, tree-module registry entries and a CV result manifest reference;
• write reports, feature diagnostics, artifact-integrity report и save summary.write reports, feature diagnostics, the artifact-integrity report and save summary.

JSON Schema Draft 2020-12 проверяет структуру при загрузке. Затем artifact validator отдельно проверяет missing files, hashes, абсолютные/выходящие за project root пути, coordinates и consistency. Успешная schema validation сама по себе не доказывает наличие всех файлов.JSON Schema Draft 2020-12 validates structure during loading. The artifact validator then checks missing files, hashes, absolute or escaping paths, coordinates and consistency. Successful schema validation alone does not prove that every file is present.

Как CV result входит в project packageHow a CV result enters the project package

CV runtime, image series и canonical markup — три разные границы. Live preview остаётся в рабочем state. В основной панели ручной Применить обычно сохраняет verified bundle и прикрепляет/заменяет cv_result выбранного элемента; Добавить маску в результаты добавляет отдельную cv_mask entry. Эти image-series mutations входят в undo/redo и помечают проект изменённым, но не создают новую canonical geometry или semantics.The CV runtime, image series and canonical markup are three different boundaries. Live preview remains working state. In the main panel, manual Apply normally stores a verified bundle and attaches or replaces the selected element's cv_result; Add mask to results appends a separate cv_mask entry. These image-series mutations participate in undo/redo and dirty the project, but do not create new canonical geometry or semantics.

• Сохранить создаёт именованный runtime archive под ScrephData/screen_selector/cv/results; это technical/debug history вне project package.Save creates a named runtime archive under ScrephData/screen_selector/cv/results; this is technical/debug history outside the project package.
• При canonical save importer берёт только прикреплённые CV image-series entries, копирует source/recipe/config/metrics/outputs в staging <name>_artifacts и строит project-local result_manifest.json.During canonical save, the importer takes only attached CV image-series entries, copies source/recipe/config/metrics/outputs into staged <name>_artifacts, and builds the project-local result_manifest.json.
• В main JSON хранится ссылка cv_result_manifest_path, а image-series entry остаётся lightweight projection с run/output identity. Manifest публикуется после обязательного artifact write/readback.The main JSON stores cv_result_manifest_path, while the image-series entry remains a lightweight projection with run/output identity. The manifest is published after required artifact write/readback.
• Добавить как элементы или confirmed promotion apply отдельно меняет canonical markup. General/GUI promotion валидирует accepted decision и stale context, строит apply preview/plan и выполняется транзакционно с rollback attempt.Add as elements or confirmed promotion apply separately mutates canonical markup. General/GUI promotion validates the accepted decision and stale context, builds an apply preview/plan, and runs transactionally with a rollback attempt.

Действия CV-панели и их side effects →CV panel actions and their side effects →

Что действительно меняет save profileWhat the save profile actually changes

Project environment выбирает downstream strategy, save scope — каталог назначения, а code-tool switch — best-effort launch/context handoff после записи. Feature output profile имеет более узкую область: Full/Compact/Automation/LLM/Debug, coordinate space, color formats, assets и summary применяются к preview/явной feature projection, но не переписывают canonical representation.The project environment selects a downstream strategy, save scope selects the destination directory, and the code-tool switch controls a best-effort launch/context handoff after writing. The feature-output profile has a narrower scope: Full/Compact/Automation/LLM/Debug, coordinate space, color formats, assets and summary apply to the preview or explicit feature projection, not to the canonical representation.

• Canonical JSON всегда сохраняет полный feature payload, summary, связанные assets и geometry в screenshot_raw_px; выбранный output profile записывается как metadata.Canonical JSON always stores the complete feature payload, summary, linked assets and screenshot_raw_px geometry; the chosen output profile is stored as metadata.
• Основной save flow не пишет отдельный feature-projection файл. InfoPanel может построить эту проекцию для preview, а code/external consumer должен запросить её явно.The primary save flow does not write a separate feature-projection file. InfoPanel can build it for preview, and a code or external consumer must request it explicitly.
• «Будет создано» показывает primary JSON и выбранные target script/guide, но не является полным package manifest и не перечисляет automatic agent export, artifacts или условные sidecars.“Will be created” shows the primary JSON and selected target script/guide, but it is not a complete package manifest and omits the automatic agent export, artifacts and conditional sidecars.

Инспекция изображения: project state и временные данныеImage inspection: project state and temporary data

Image Inspection разделяет сохраняемое состояние canvas и временные измерения. Не считайте наличие слоя measurements доказательством, что сами линии входят в project package.Image Inspection separates persisted canvas state from temporary measurements. The presence of a measurements layer does not mean that measurement lines are included in the project package.

• canvas_layer_state в canonical project сохраняет шесть layer IDs, видимость, прозрачность и порядок. Lock туда не входит и при restore сбрасывается.canvas_layer_state in the canonical project stores six layer IDs plus visibility, opacity and order. Locks are excluded and reset on restore.
• Layout A/B/C/D, assignments, display modes, linked panes, выбранная evidence-вкладка и navigator сохраняются отдельно как локальное состояние Selector, а не как переносимая разметка проекта.A/B/C/D layout, assignments, display modes, linked panes, the selected evidence tab and navigator settings are stored separately as local Selector state, not as portable project markup.
• Линии профиля и их local Undo/Redo существуют только в runtime-сессии и очищаются при смене source. Копировать профиль как TSV пишет clipboard, а Экспортировать профиль в CSV создаёт отдельный файл с distance, x/y, RGB, luminance, sampled layer и source reference.Profile lines and their local Undo/Redo exist only for the runtime session and are cleared when the source changes. Copy profile as TSV writes to the clipboard, while Export profile to CSV creates a standalone file with distance, x/y, RGB, luminance, sampled layer and source reference.

Производный for_ai_agent exportDerived for_ai_agent export

<name>.for_ai_agent.json создаётся автоматически из уже записанного canonical package. Он содержит hash исходного project JSON, normalized elements/relations, features и issues, CV summary, asset references, tree-module registry и authoring context. Тяжёлые bodies обычно остаются файлами в project package и представлены ссылками.<name>.for_ai_agent.json is generated automatically from the saved canonical package. It contains the source Project JSON hash, normalized elements/relations, features and issues, a CV summary, asset references, the tree-module registry and authoring context. Heavy bodies normally remain files in the project package and are represented by references.

• Основной save flow использует этот sidecar, когда он доступен; canonical JSON остаётся fallback-контекстом. Project Manager save и некоторые legacy save entrypoints сейчас передают canonical path напрямую.The primary save flow uses this sidecar when available; canonical JSON remains the fallback context. Project Manager save and some legacy save entry points currently pass the canonical path directly.
• Project Manager классифицирует sidecar как agent export и не открывает его в Selector как проект.Project Manager classifies the sidecar as an agent export and does not open it in Selector as a project.
• Assistant action project.export_for_automation требует confirmation и явный output path, но сейчас также пишет роль for_ai_agent с профилем automation_runtime_context, а не отдельный automation_export.The Assistant action project.export_for_automation requires confirmation and an explicit output path, but currently also writes the for_ai_agent role with an automation_runtime_context profile rather than a separate automation_export.

Tree module — компактный срез, а не подпроектA tree module is a compact slice, not a subproject

В дереве элементов откройте Модуль → Создать модуль из поддерева.... Screph сохраняет <name>_artifacts/modules/<slug>/module.json, Python helper-класс и README, а в canonical project — только registry entry и freshness/hash сведения.In the element tree, open Module → Create module from subtree.... Screph writes <name>_artifacts/modules/<slug>/module.json, a Python helper class and a README, while the canonical project stores only the registry entry and freshness/hash information.

• refs_only оставляет ссылки на project assets; self_contained копирует используемые файлы в папку модуля и записывает SHA-256.refs_only keeps project-asset references; self_contained copies used files into the module directory and records SHA-256.
• Модуль включает внутренние relations и отдельные boundary refs к объектам вне выбранной ветки.The module includes internal relations and separate boundary references to objects outside the selected branch.
• После изменения ветки badge может показать stale state; используйте Обновить модуль или Обновить устаревшие модули.After the branch changes, the badge may show a stale state; use Update module or Update stale modules.

Что получает Automation RuntimeWhat Automation Runtime consumes

Текущий Python runtime загружает canonical project и читает gui_elements; for_ai_agent не является его прямым input contract. Save target режима GUI Automation может дополнительно подготовить:The current Python runtime loads the canonical project and reads gui_elements; for_ai_agent is not its direct input contract. A GUI Automation save target may additionally prepare:

Canonical/agent package записывается до automation coordinate validation и target preparation. Поэтому failure на этих стадиях не откатывает уже созданные project files и может оставить частично подготовленный guide/script; current project path и clean state при этом не обновляются. После исправления причины повторите сохранение.The canonical/agent package is written before automation coordinate validation and target preparation. A failure at those stages therefore does not roll back project files already created and may leave a partially prepared guide or script; the current project path and clean state are not updated. Save again after correcting the cause.

Screph CV не материализует особый CV workspace artifact: он использует тот же basic canonical writer, что и «только проект». Разница — только в явном действии Открыть результат, которое переводит в существующую внутреннюю CV-вкладку вместо открытия project directory.Screph CV does not materialize a special CV-workspace artifact: it uses the same basic canonical writer as “project only.” The difference is only the explicit Open Result action, which switches to the existing internal CV tab instead of opening the project directory.

Загрузка проекта, координаты и input backends →Project loading, coordinates and input backends →

Схема на диске не всегда означает пользовательский exportA schema on disk does not always mean a user-facing export

Формальные схемы существуют для canonical project, for_ai_agent, tree module, CV result manifest, feature, automation_export и llm_export. Текущие materialized user paths прямо создают canonical/agent/tree outputs и CV/feature data; automation_export и llm_export пока являются contract surfaces для adapters/tests и не имеют отдельного пользовательского writer в основном save flow.Formal schemas exist for the canonical project, for_ai_agent, tree module, CV result manifest, feature, automation_export and llm_export. Current materialized user paths directly produce canonical/agent/tree outputs and CV/feature data; automation_export and llm_export are currently contract surfaces for adapters/tests and have no separate user-facing writer in the primary save flow.

Кроме formal schemas, Capture, timeline, diagnostics и Action CV используют versioned runtime JSON roles без отдельного файла JSON Schema для каждого sidecar. Проверяйте json_role и обе формы version, а не только расширение .json.In addition to formal schemas, Capture, timeline, diagnostics and Action CV use versioned runtime JSON roles without a separate JSON Schema file for every sidecar. Check json_role and both version forms rather than relying on the .json extension.

Project Manager, перенос и восстановлениеProject Manager, moving and recovery

Ctrl+O открывает Project Manager с вкладками Проекты, Автосейвы и Проблемные. Он различает canonical project, agent export, tree module, неизвестный и повреждённый JSON.Ctrl+O opens Project Manager with Projects, Autosaves and Problems tabs. It distinguishes canonical projects, agent exports, tree modules, unknown JSON and damaged JSON.

• Duplicate/rename/restore работают с папкой проекта и обновляют имя primary JSON, timeline state и frame-bound index.Duplicate/rename/restore operate on the project directory and update the primary JSON name, timeline state and frame-bound index.
• После rename или duplicate сохраните проект ещё раз перед agent/code handoff: это пересоберёт for_ai_agent с текущим basename и SHA.After a rename or duplicate, save the project again before agent/code handoff; this rebuilds for_ai_agent with the current basename and SHA.
• GraphML, interactive HTML и project-graph JSON из Manager — визуализации карты проектов/модулей, а не canonical project и не automation script. GraphML требует networkx.GraphML, interactive HTML and project-graph JSON exported by Manager visualize the project/module map; they are not the canonical project or an automation script. GraphML requires networkx.
• Agent export показывается как проблемная/производная запись, но при существующей ссылке Открыть ведёт к связанному canonical project. Tree module и произвольный JSON не становятся проектом.An agent export appears as a problem/derived entry, but when its reference exists, Open resolves to the linked canonical project. A tree module or arbitrary JSON does not become a project.
• Manager считает canonical/autosave открываемым только при ненулевом domain count; screenshot-only autosave имеет отдельный startup recovery path.Manager considers a canonical project or autosave openable only with a non-zero domain count; a screenshot-only autosave has a separate startup recovery path.

Manager не удаляет project directory. Убрать из истории и Очистить пропавшие меняют только ScrephData/local_state/selector_project_history.json. Tags/notes находятся в отдельном path-keyed selector_project_metadata.json, не входят в package и не мигрируют при duplicate/rename или ручном переносе.Manager does not delete a project directory. Remove from history and Clear missing only change ScrephData/local_state/selector_project_history.json. Tags and notes live in a separate path-keyed selector_project_metadata.json; they are outside the package and do not migrate during duplicate, rename or a manual move.

Предварительные diagnostics Manager покрывают JSON decoding/role, canonical schema, kind-specific feature schema, missing path и empty domain. Полный свежий artifact scan перед открытием Manager не выполняет; после загрузки InfoPanel объединяет текущий domain load report и сохранённые save diagnostics.Manager's pre-open diagnostics cover JSON decoding and role, the canonical schema, kind-specific feature schemas, missing paths and an empty domain. Manager does not run a fresh full artifact scan before opening; after load, InfoPanel combines the current domain load report with saved save diagnostics.

Crash reports, autosave и diagnostics →Crash reports, autosave and diagnostics →

Безопасный порядок handoffSafe handoff sequence

1. Проверьте разметку и явно примените нужные CV candidates.Review markup and explicitly apply the required CV candidates.
2. Сохраните canonical project и убедитесь, что save diagnostics не показывают failure.Save the canonical project and ensure save diagnostics report no failure.
3. Выберите consumer: runtime target, Screph Code/IDE, tree module или собственный adapter.Choose the consumer: a runtime target, Screph Code/IDE, a tree module or your own adapter.
4. Передавайте только package files и assets, которые нужны этому consumer.Hand off only the package files and assets required by that consumer.
5. Перед исполнением automation проверьте package diagnostics, затем явно обработайте (ok, errors) от validate_project; load_project не делает это автоматически.Before automation execution, review package diagnostics and then explicitly handle the (ok, errors) returned by validate_project; load_project does not do this automatically.
6. Проверьте target window, coordinate projection, выбранный input monitor/backend и отдельную postcondition после каждого input action.Verify the target window, coordinate projection, selected input monitor/backend and a separate postcondition after each input action.

ПриватностьPrivacy

Локальное сохранение не загружает package автоматически. Но canonical/agent JSON может содержать annotations, OCR text, window/capture context и ссылки на sensitive images. Перед cloud LLM, speech, support upload или передачей папки другому человеку проверьте не только JSON, но и _artifacts, timeline sources, guides и generated scripts.Local saving does not upload the package automatically. However, canonical/agent JSON may contain annotations, OCR text, window/capture context and references to sensitive images. Before using a cloud LLM, speech service, support upload or sharing the directory, inspect not only JSON but also _artifacts, timeline sources, guides and generated scripts.

Project-local Assistant mirror может содержать prompts, ответы, paths и action metadata; global 180-day cleanup его не удаляет. Полная карта storage и cleanup приведена в справке по локальным данным.The project-local Assistant mirror may contain prompts, responses, paths and action metadata; global 180-day cleanup does not remove it. See the local-data guide for the complete storage and cleanup map.