Сборка, установка и обслуживание

Как собрать и поставить платформу, где лежат её данные и журналы, как проверить экземпляр, сделать резервную копию и обновиться.

1 Общие сведения о программе

1.1 Условия работы

Платформа работает в Ubuntu внутри WSL2. Мастерская — программа Windows 11 на системном WebView2, её запускает функция ui. Если WSL не позволяет запускать программы Windows (например, в обычном Linux), экземпляр работает без мастерской.

Экземпляр работает, пока работает виртуальная машина WSL:

• Долгий прогон. Спящий режим Windows и команда wsl --shutdown прерывают прогон; прогон продолжается с контрольной точки. Имеются сведения, что экземпляры WSL приостанавливаются при простое даже с таймаутом -1.
• Большие данные. Их следует хранить на диске Linux: файлы Windows через /mnt/c читаются заметно медленнее.

1.2 Необходимые средства

Работа проверена на следующей конфигурации:

• WSL2, Linux x86_64;
• Python 3.11 или новее;
• uv 0.12 или новее — им платформа ставит окружения Python процессов;
• Rust 1.98.0 из rust-toolchain.toml.

Необходимы:

• Cargo с компонентами rustfmt и clippy;
• make — короткие команды сборки и проверок;
• Linux в WSL2 — для сокета и запуска OS-процессов;
• Windows 11 с WebView2 (он уже есть в системе) — для мастерской; установка в Windows не требуется.

Права администратора WSL2 для сборки и запуска не требуются. Реальные пароли и ключи к сервисам в проект не записываются.

2 Структура программы

Человек ставит платформу установщиком Windows (раздел 2.1). make pack собирает поставку — готовую к распаковке папку dist/ogas/, которую установщик кладёт в Linux:

ogas/
  ogas
  ogas.cmd
  ogas.desktop
  LICENSE                       лицензия платформы, AGPL-3.0-or-later
  NOTICE                        что под какой лицензией
  THIRD-PARTY-NOTICES.txt       чужие пакеты и шрифт с текстами их лицензий
  assets/ogas-mark.svg
  bin/
    ogas-core
    ogas-graph
    ogas-canvas
    ogas-modules
    ogas-settings
    ogas-i18n
    ogas-observe
    ogas-sources
    ogas-profile
    ogas-ui
    ogas-gate
    ogas-assistant
    ogas-window.exe   мастерская (если собрана `make window`)
    ogas-start.exe    запускатель для ярлыков Windows: платформа без окна консоли (собирается с мастерской)
  core/kernel/locales/          слова ядра
  functions/
    <id>/function.json          описание функции (Форматы файлов, раздел 3)
    <id>/…/locales/             её словари
  sdk/                           общий код модулей (SDK) без своих проверок, со своей лицензией Apache-2.0
  data/
    config/
    processes/                  пусто: процессы — работа человека
    runs/
    logs/
    run/

Ядро и функции — отдельные исполняемые файлы из одного набора пакетов Cargo; код функций в ядро не встраивается. Поставка собирается выпускной сборкой (--release): движок в ней примерно в десять раз быстрее отладочной; отладочная сборка target/debug — для работы над платформой. Поставка — только платформа: модули и процессы человека, его настройки, раскладка окон и прогоны в неё не попадают, а тестовые модули остаются при проверках. Обёртка ogas передаёт --data-dir data относительно корня пакета; пути в data/functions.json указывают на bin/ogas-*. Без описания хоть одной функции из реестра make pack поставку не собирает: ядро такую функцию всё равно не запустило бы. Программы поставки собираются отдельно, в target/pack, с заменой путей сборки (--remap-path-prefix): домашняя папка, папка проекта, каталог зависимостей Cargo и набор инструментов становятся /home, /ogas, /cargo и /rustup, поэтому имя собравшего в программы не попадает; make window собирает окно с той же заменой. Программу, в которой остался путь этой машины, make pack не берёт и называет её.

make pack
./dist/ogas/ogas doctor
./dist/ogas/ogas start

2.1 Установщик Windows

make installer собирает dist/ogas-setup-<версия>.exe — установщик, как у обычной программы Windows (installer/ogas.nsi, NSIS, 64 бита). Нужны makensis (пакет nsis Ubuntu; без прав администратора его распаковывают apt download и dpkg -x и называют переменными MAKENSIS и NSISDIR) и uv для Linux x86_64 (по умолчанию тот, что в PATH; переменная UV_PROGRAM).

Платформа живёт в WSL, и ставится она туда. Установка идёт в три этапа, каждый своим рядом экранов — проверка, вопросы, сводка «что будет сделано», исполнение с журналом внизу окна, итог; следующий этап начинается сам. Тихих шагов нет: до нажатия кнопки ничего не запускается — проверки этапа 1 и этапа 3 идут по кнопке «Проверить», версия WSL, обновления Linux и пакеты — каждая по своей кнопке, и каждая команда с её ответом видна на странице; шаги установки пишут в журнал, что делают, прежде чем делать. Каждый этап — отдельный запуск того же установщика (/stage=N); ответы переходят от этапа к этапу через его запись в реестре, кроме пароля — он живёт только в памяти этапа 1.

1) WSL и Linux. Проверка Windows, виртуализации и WSL: виртуализация не видна — объяснение, как включить её в BIOS, и вопрос, продолжать ли (Windows не всегда её показывает); нет WSL — она ставится (wsl --install --no-distribution), а после перезагрузки этап 1 продолжается сам; WSL ставит новые Linux на WSL 1 по умолчанию — это сказано и переключается на WSL 2. Linux для платформы: имеющийся годный (Ubuntu или Debian, не Docker; учётная запись в нём остаётся как есть; Linux на WSL 1 показан с пометкой и при выборе — после предупреждения — переводится на WSL 2: платформа живёт только на WSL 2) или свой «OGAS» — Ubuntu 26.04 LTS обычной командой WSL (wsl --install -d Ubuntu-26.04 --name OGAS --location <место>\OGAS-linux --version 2 --no-launch) на выбранном диске и в папке, с разреженным диском и учётной записью, имя и пароль которой человек задаёт тут же. Во время установки пароль не спрашивается — всё делается от root через WSL; потом его спрашивает sudo, как обычно. В Linux пароль уходит в окружении одной команды и не пишется ни в журнал, ни в командную строку, ни на диск. Потом — обновления: версия WSL рядом с последней вышедшей (её установщик узнаёт со страницы выпусков WSL на GitHub) и сколько пакетов выбранного Linux можно обновить; стоит самое новое — так и сказано: «последняя версия», нет — предлагается обновить (wsl --update --web-download, пакеты — apt-get upgrade с сохранением файлов настроек человека). Обновление WSL останавливает все запущенные Linux, поэтому без отметки человека установщик его не делает — кроме старой WSL, встроенной в Windows, без которой свой «OGAS» не поставить; пакеты своего «OGAS» отмечены сразу, Linux человека — нет. Сам Linux человека установщик не перезапускает. 2) Пакеты Linux. Группы пакетов из installer/packages.json: что каждая даёт, зачем, сколько займёт и стоит ли уже — это установщик узнаёт у самого Linux; видна ли видеокарта NVIDIA (её драйвер ставится в Windows). Основа — Python, окружения, загрузки с проверкой, uv, systemd — ставится всегда, остальное человек отмечает; пакетов, которых в этом Linux нет, установщик не ставит и называет их. В Linux человека в wsl.conf добавляется только systemd=true, если его нет; сам Linux не перезапускается.

Группы пакетов (installer/packages.json):

3) O.G.A.S. Если она уже стоит: обновить (по умолчанию); переустановить начисто в то же место — окружения и кэш уходят, данные остаются, а с галкой «и удалить мои программы, модули и нейросети» уходят и они (резервная копия остаётся); изменить набор пакетов (этап 2); для своего «OGAS» — стереть его и поставить заново: копия данных уходит в Windows, установка начинается с этапа 1, данные возвращаются на этапе 3. Если не стоит — папка в Linux, по умолчанию ~/ogas. Потом ярлык «O.G.A.S.» в «Пуске» и на рабочем столе, строка среди программ Windows и «Запустить O.G.A.S.».

Внутри Linux всё делает installer/setup.sh от root, по действию за запуск: account, survey, packages, install, update, reinstall, backup-out; перед изменениями — проверки, весь вывод — ещё и в setup.log. Запуск без /stage начинает с этапа 3, если O.G.A.S. уже стоит, и с этапа 1 иначе. В Windows остаются только деинсталлятор, значок ярлыка, журнал и запускатель ярлыков ogas-start.exe в %LOCALAPPDATA%\OGAS (ярлык запускает платформу через него, без окна консоли): для своего Linux — в выбранном месте, для имеющегося — в %LOCALAPPDATA%\OGAS. Удаление спрашивает о данных и по умолчанию оставляет их: свой «OGAS» с «Да» удаляется целиком, в имеющемся Linux с «Да» удаляется только папка платформы — сам Linux, пакеты и systemd остаются.

Подписи сертификатом кода у установщика нет: Windows при первом запуске может предупредить о неизвестном издателе. Установщик — 64-битная программа и запускает wsl.exe прямо, без оболочки cmd: Защитник Windows останавливает неподписанные программы, которые выключают перенаправление системной папки или ведут команды через оболочку (Behavior:Win32/DefenseEvasion).

make source собирает архив исходников версии dist/ogas-<версия>-source.tar.gz — всё, что git держит в HEAD, кроме рабочих набросков автора: AGPL требует давать исходники вместе с программой.

3 Настройка программы

3.1 Подготовка Rust

Версия Rust закреплена в rust-toolchain.toml (1.98.0); сборка на других версиях не гарантируется. Точные версии зависимостей записаны в Cargo.lock в исходниках, сборки и проверки идут с флагом --locked.

Если в корне проекта есть .cargo/bin/cargo, Makefile использует его. Иначе cargo должен быть в PATH. Обёртка ./ogas сама добавляет в PATH папки .cargo/bin проекта и ~/.cargo/bin: ярлык Windows запускает её без профиля входа, и иначе cargo не был бы найден. Из исходников ./ogas собирает платформу без сети (--offline): всё нужное для сборки должно уже быть на машине. Если чего-то нет, обёртка отказывает и называет команду make build, которая скачивает пакеты; сама обёртка в сеть не обращается и Rust не устанавливает.

rustc --version
cargo --version

3.2 Проверка Python

python3 --version
python3 -m json.tool sdk/tests/doubles/echo/manifest.json

В modules/ лежат только модули человека; общий код модулей — OGAS SDK — лежит в sdk/. Тестовые модули OGAS SDK обходятся стандартной библиотекой Python. Если модулю нужны зависимости, его непустой requirements.txt сам не ставится: нужна команда module.install. Общий код обмена — sdk/python/ogas_runtime.py; в PYTHONPATH модуля только его папка и sdk/python.

3.3 Сборка и проверка

make build
make lint
make test
make doctor
make pack

3.4 Мастерская

Мастерская — программа Windows из functions/ui/window (Tauri 2). Её собирают непосредственно в WSL, без инструментов Windows и без прав администратора:

make window

Результат — functions/ui/window/target/x86_64-pc-windows-msvc/release/ogas-window.exe (около 3,7 МБ); функция ui находит его сама. make pack помещает его в dist/ogas/bin/. Если программа лежит в другом месте, путь к ней задаёт настройка ui.window.exe — так, как этот путь видит WSL, например /mnt/e/Concept/ogas-window.exe.

Для сборки окна однократно устанавливаются:

• поддержку цели x86_64-pc-windows-msvc: библиотеку rust-std той же версии Rust с static.rust-lang.org; контрольная сумма сверяется с описанием выпуска, установка — install.sh --prefix=<папка Rust>;
• cargo install --locked cargo-xwin — он скачивает библиотеки Microsoft для сборки под Windows в ~/.cache/cargo-xwin (около 1,1 ГБ); загрузка означает согласие с лицензией Microsoft;
• llvm-rc, clang-cl, lld-link, llvm-lib: пакеты Ubuntu llvm-21, libllvm21, clang-21, libclang-cpp21, libclang-common-21-dev, lld-21, liblld-21 через apt download + dpkg -x в ~/.local/llvm-21-root, обёртки с этими именами в ~/.local/bin;
• во время сборки в PATH должны быть ~/.local/bin, папка cargo и ~/.cargo/bin.

Страница окна (functions/ui/window/ui/) — HTML, CSS и модули JavaScript без Node и сборщика: после правки страницы достаточно make window.

3.5 Данные

Реестр функций — core/data/functions.json, пути в нём указывают на target/debug/ogas-*; описание каждой функции лежит в её папке, functions/<id>/function.json. Если файла по пути нет, ядро ищет файл с тем же именем рядом с собой. make pack переписывает пути на bin/ogas-* в dist/ogas/data/functions.json.

Процессы человека — core/data/processes/<id>/; в git их нет, как и личных настроек.

Прогон процесса на своей папке данных:

./target/debug/ogas-core run --data-dir core/data --process ID

3.6 Настройки

Файлы настроек лежат в data/config/ (core.json, system.json, user.json) и в папке каждого процесса (settings.json). Какой файл за что отвечает, в каком порядке они читаются и перечень ключей — Настройки.

Поставка приносит core.json и system.json пустыми: умолчания хранятся в схемах. user.json — выбор человека, который здесь работает; его нет ни в репозитории, ни в поставке, и создаётся он при первом изменении в окне настроек. Так же создаётся layout.json — раскладка окон мастерской: файл появляется при первом перемещении окна. При переносе экземпляра на другую машину оба файла переезжают вместе с data/config/.

Неподходящее значение платформа сама не исправляет: новое значение записывается только после проверки по схеме, и записывается целиком. Если core.json или system.json не разбирается, ядро не запускается и называет файл и номер строки.

3.7 Python-модули

• Окружение. У рабочего процесса одно окружение Python на все его модули: data/processes/<id>/.venv (Модули, раздел 5). Его делает uv: одинаковые файлы пакетов разных процессов лежат на диске один раз, в общем кэше data/cache/uv/, а окружения ссылаются на них. Программу uv называет настройка modules.uv; без неё установка отказывает module_uv_not_found. Поставить uv можно командой python3 -m pip install --user uv или установщиком с сайта uv.
• Установка. Зависимости устанавливаются только явной командой — в мастерской или ogas-core install --process ID. Запуск модуля не скачивает и не устанавливает пакеты. Доступ к сети во время установки и источник пакетов обеспечивает пользователь.
• Интерпретатор берётся первым подходящим из списка modules.python_candidates.
• Версии. Фактически установленные версии записаны в requirements.freeze.txt рядом с окружением; точные версии автор модуля закрепляет в своём requirements.txt.

3.8 Пароли и ключи

Платформа их не хранит, не выдаёт и ими не управляет. Ключи к сервисам, токены и прочие секреты принадлежат модулям, и за их хранение отвечает человек. Токен запуска функции хранится только в памяти.

Секреты не допускается помещать в:

• git;
• process.json и настройки;
• журналы;
• командную строку;
• экспорт процесса.

Доверенный модуль при этом может читать доступные человеку переменные окружения и файлы и обращаться к сети.

4 Проверка программы

4.1 Диагностика

make doctor

Выводит признаки самого ядра, а затем итоги проверок среды, которые объявили функции реестра, с текстом на языке системы.

Признаки ядра: wsl2 — работает ли дистрибутив в WSL2; data_remote_fs — лежит ли папка данных на диске Windows или сетевом диске (true: сокет в ней не создать, и ядро положит его в XDG_RUNTIME_DIR или /tmp, Устройство платформы, 3.6.1); socket_path и socket_on_linux_fs — какой путь сокета ядро возьмёт и лежит ли он на файловой системе Linux; registry — есть ли реестр core/data/functions.json.

Проверки функций: sources.curl и sources.sha256sum — есть ли curl и sha256sum, которыми библиотека ищет и скачивает в источниках и сверяет скачанное (Защита, 3.14); ui.wsl_interop — запускаются ли программы Windows из WSL (без этого мастерская не откроется); ui.window — лежит ли программа окна на одном из своих мест: bin/ogas-window.exe в поставке или сборка make window в исходниках. Путь из настройки ui.window.exe doctor не видит: настройки читает работающая платформа. graph.wsl_idle_timeouts — заданы ли в .wslconfig сроки простоя WSL, существенные для долгих прогонов.

Если нет реестра или подходящего пути сокета — код выхода 1; итоги проверок функций код выхода не меняют. Python doctor не ищет (Устройство платформы, раздел 5).

4.2 Проверка мастерской

Порядок проверки после установки:

1) выполнить make doctor: дистрибутив работает в WSL2, проверки ui.wsl_interop и ui.window пройдены (passed); если окно лежит в другом месте и путь к нему задан настройкой ui.window.exe, ui.window скажет failed, и это не помеха. Для долгих прогонов существенна проверка graph.wsl_idle_timeouts: сроки простоя задаются параметрами vmIdleTimeout и instanceIdleTimeout в .wslconfig; 2) открыть мастерскую (./ogas, ogas.cmd или ярлык) и проверить панели, окна, журнал и связь с платформой; 3) посмотреть мастерскую глазами: открыть программу, собрать и запустить.

WSL обновляется командой Windows wsl --update или на этапе 1 установщика, по отметке человека; сама платформа её не запускает.

5 Дополнительные возможности

5.1 Запуск

./ogas-core start  --data-dir core/data
./ogas-core ui     --data-dir core/data
./ogas-core run    --data-dir core/data --process ID --text "hello from O.G.A.S."
./ogas-core doctor --data-dir core/data

То же самое короткими командами: make start, make ui, make doctor. Второй экземпляр на той же папке данных не появляется: замок занят, и повторный запуск мастерской запрашивает у работающего экземпляра открытие окна. Что делает каждый глагол — Устройство платформы, раздел 5.

5.2 Командная строка

ogas-core [start|ui|doctor|backup|stop] [--data-dir PATH]
ogas-core run --process ID [--data-dir PATH] [--text TEXT]
ogas-core install --process ID [--data-dir PATH]
ogas-core program --process ID [--data-dir PATH]

Что делает каждый глагол — Устройство платформы, раздел 5. Кратко: start и ./ogas запускают функции вместе с мастерской; run прогоняет процесс без окна и останавливает экземпляр; install ставит окружение процесса; program запускает платформу с мастерской, включает программу процесса и показывает её лицо вместо мастерской, а если платформа уже работает — просит об этом её (Мастерская, 6.6). Глаголы про процесс без --process отказывают с кодом выхода 1: готового процесса, который подставился бы сам, нет. backup делает резервную копию (5.6), stop останавливает работающую платформу, как выход из окна, и ждёт её конца. Глаголы, кроме start, ui, doctor, backup и stop, и их аргументы описаны в реестре функций (Форматы файлов, раздел 3); ogas-core --help перечисляет их.

5.3 Работа без Make

cargo build --workspace --locked
cargo test --workspace --locked
python3 -m unittest discover -s sdk/tests -p 'test_*.py'
python3 -m unittest discover -s scripts -p 'test_*.py'
./ogas

Это make build, make test и запуск. Проверки модулей человека в modules/ сюда не входят: их запускает автор модуля.

5.4 Остановка и сбой

Порядок обычной остановки:

1) запретить новые запуски; 2) отправить cancel активным модулям; 3) подождать отведённое время; 4) принудительно завершить оставшиеся OS-процессы; 5) закрыть функции; 6) дописать журналы; 7) снять замок.

После аварийного завершения ядра новый запуск:

• находит незавершённые прогоны: функция графа при знакомстве с ядром переводит running в interrupted;
• проверяет контрольную точку и поколение документов;
• предлагает продолжить прогон только там, где это безопасно (resume.allowed, confirm_non_idempotent).

Резервная копия не отвечает на вопрос, успел ли модуль сделать своё внешнее действие.

При отказе мастерской (в отличие от закрытия) функция ui её не перезапускает: экземпляр работает без окна. Для восстановления окна ярлык запускают повторно: второй запуск запросит у работающего экземпляра открытие окна и сразу завершится (Устройство платформы, 3.6.3).

5.5 Журналы

Таблица 1 — Журналы

Запрос журнала с run_id читает файл этого прогона, если он есть. Мастерская показывает состояние ядра и функций, текущий прогон, проблемы, события платформы и процесса. Наружу платформа ничего не отправляет.

5.6 Резервное копирование и перенос

Резервную копию делает команда ./ogas backup; установщик делает её сам перед тем, как поставить новую версию. Копия — один файл ogas-<время>.tar в папке настройки core.backups_dir (пусто — backups в папке установки; можно выбрать папку Windows, и копию не заденет беда с диском платформы). Хранится столько последних копий, сколько говорит core.backups_keep; более старые убираются, когда делается новая.

В копию входит то, чего платформа не сделает заново:

• папка данных — как data/: процессы со всем своим (документы, память узлов, файлы, прогоны с результатами), настройки, журналы;
• папки частей, которые они назвали для копии, — как places/<имя>/: установленные модули.

Не входят: data/run/, общий кэш пакетов data/cache/, окружения .venv — их ставят на месте заново, — загрузки, которые ещё не приняты, и папка нейросетей: она велика, а сети берут из их источников. Свою нейросеть, которую не скачать, копируют отдельно. Где лежала каждая папка, говорит data/places.json внутри копии. Вернуть копию — остановить платформу и распаковать data/ на место папки данных, а places/<имя>/ — на место той папки.

Передача процесса. process.export пишет экспорт процесса — папку data/exports/<process_id>/ с документами процесса и файлами его модулей как есть (Форматы файлов, 10.1). Папку передают другому человеку любым способом — архивом, флешкой, облаком; платформа способ передачи не выбирает.

Перед добавлением process.inspect показывает, что экспорт принесёт: имя процесса, модули с их человеческими названиями, размер, что модуль будет скачивать при подготовке окружения, отпечаток и есть ли такой модуль здесь — нет, такой же или другой. Прав модуля платформа не показывает: песочницы нет, и «права» были бы обещанием, которое никто не держит (Защита, 3.1).

process.import создаёт по экспорту процесс здесь:

• id занят — копия получает свободный (workshop-2), и документы переписываются на него;
• модуль, которого нет, ставится из экспорта; установленный не перезаписывается и попадает в modules_skipped вместе с признаком, совпало ли содержимое;
• окружение Python в экспорт не входит: после добавления его ставят заново;
• экспорт со ссылкой внутри модуля или с модулем, чьё содержимое не сходится с отпечатком, отклоняется;
• каждый документ процесса принимает его хозяин и проверяет его: пульт — функция пульта, значения настроек процесса — функция настроек, версии модулей — функция модулей; граф процесса пишется последним, поэтому экспорт, который хозяин не принял, процесса не создаёт.

5.7 Обновление

Платформа обновляется заменой исполняемых файлов и словарей; обновления выходят на сайте ogas.space. Порядок обновления:

1) остановить экземпляр; 2) сохранить резервную копию данных; 3) проверить совместимость форматов; 4) проверить функции и модули; 5) только затем открыть мастерскую.

Документ другой версии формата платформа не открывает и говорит об этом; откат к прежним исполняемым файлам возвращает и прежние форматы, поэтому перед обновлением сохраняют резервную копию данных.

6 Сообщения системному программисту

Коды ошибок, их хозяева и условия возникновения — Коды ошибок. Записи журнала ядра и журнала наблюдения — Форматы файлов, раздел 13.