fabrilis/docs/CLI.md
loki5512344 190ef9cc4b Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
2026-11-16 23:40:39 +01:00

8.3 KiB
Raw Permalink Blame History

Headless CLI

CLI — это пульт управления движком и расчётный инструмент: пакетные прогоны и живая консоль. Внешняя программа — скрипт, агент, нейросеть — управляет движком командами, как инструментами через MCP. Окно и GPU не нужны.

Отдельный бинарник, который не зависит от render, ui и winit; общий код мира и прогонов живёт в modes, чтобы GUI и CLI считали одно и то же.

Зачем

  • прогнать сценарий на сервере и получить CSV/отчёт;
  • проверить регрессии автоматическим прогоном без дисплея;
  • считать развёртки и Monte Carlo;
  • держать один сервер физики и подключать клиентов (NETWORK.md);
  • дать внешнему коду команды open/run/step/set_actuator/read_sensor, не встраивая чужую логику в движок;
  • позволить агенту или нейросети вести эксперимент по шагам и читать только датчики.

Команды (план)

Команда Что делает
fabrilis simulate <проект> --scenario <id> --seed N --until T --out result.csv один детерминированный прогон
fabrilis validate проверки из VALIDATION.md; код возврата 1 при провале допуска
fabrilis sweep <проект> --params sweep.ron --out dir/ сетка/Монте-Карло, по процессу на прогон
fabrilis control --stdio протокол команд по stdin/stdout для скрипта/агента
fabrilis serve --bind 0.0.0.0:9000 headless-сервер физики (S1 из NETWORK.md)
fabrilis repl --connect <сокет> живая консоль: команды в запущенный движок
fabrilis info версии, возможности, доступные сценарии

Коды возврата: 0 — успех, 1 — провал проверки, 2 — ошибка аргументов, 3 — ошибка выполнения.

Гарантии

  • Без GPU и окна; шаг физики фиксированный, как в мире.
  • Один seed и одни входы дают один результат; golden-хеш проверяется автоматическим прогоном.
  • Параллельные прогоны — отдельные процессы, результат не зависит от их числа.
  • Логи по LOGGING.md: обычный уровень info, --dev — debug/trace.
  • Метрики-лог CSV и dev-лог те же, что у GUI (LOGGING.md).

Пульт управления (протокол команд)

Один и тот же набор команд доступен из CLI, из Unix-сокета/TCP и (позже) как MCP-инструменты. Это не «обучение в движке»: внешний код решает, что делать, а движок исполняет команды и возвращает состояние.

Транспорт v1 — JSON-RPC 2.0, по сообщению на строку: stdio для fabrilis control, Unix-сокет для локального агента, TCP с токеном для удалённого сервера.

-> {"jsonrpc":"2.0","id":1,"method":"engine.open","params":{"project":"cart","seed":42}}
<- {"jsonrpc":"2.0","id":1,"result":{"t":0.0,"bodies":3}}
-> {"jsonrpc":"2.0","id":2,"method":"engine.step","params":{"steps":10}}
<- {"jsonrpc":"2.0","id":2,"result":{"t":0.01,"events":[]}}
-> {"jsonrpc":"2.0","id":3,"method":"engine.set_actuator","params":{"joint":0,"torque":4.9}}
-> {"jsonrpc":"2.0","id":4,"method":"engine.read_sensor","params":{"sensor":"encoder0"}}
<- {"jsonrpc":"2.0","id":4,"result":{"angle":0.31,"t":0.01}}
Команда Смысл
engine.open / engine.close открыть проект/сценарий, освободить
engine.run / engine.pause идти по часам или стоять
engine.step ровно N шагов, без ожидания реального времени
engine.reset вернуть сцену к seed/снимку
engine.set_actuator момент/цель/скорость привода
engine.set_input GPIO/PWM/вход схемы
engine.read_sensor энкодер, IMU, ток, температура
engine.query_state позы, метрики, флаги (только разрешённое)
engine.snapshot / engine.restore снимок и откат
engine.save сохранить проект/результат

Правила:

  • команды применяются на границе шага, а не посреди решателя; ответ подтверждает, на каком времени они применены;
  • наблюдение для внешнего управления — только датчики (sensors), без ground truth; query_state — для отладки и разрешён явно;
  • шаг фиксированный; engine.step не зависит от реального времени;
  • один процесс — одна сцена; несколько внешних клиентов подключаются к serve (NETWORK.md);
  • одинаковые seed и последовательность команд дают одинаковую траекторию;
  • MCP-адаптер (позже) выставляет те же команды как инструменты с явным allowlist, без доступа к файлам и сети за пределами проекта.

Внешние контроллеры

Для обучения или скриптового управления используется тот же протокол: reset, step, set_actuator, read_sensor. Reward и условие done задаёт сценарий, а не ядро; один процесс — одна среда, вектор сред делает внешний код. Позже, если JSON-RPC не хватит по скорости, добавим бинарный протокол или PyO3-биндинги.

Разрез работ

  • C1 — бинарник fabrilis-cli и simulate: тот же мир без окна, CSV на выходе; DoD: прогон тестовой сцены, golden-хеш, нет зависимости от render/ui.
  • C2 — validate и коды возврата; DoD: специально сломанный кейс даёт код 1.
  • C3 — sweep и Monte Carlo по процессам; DoD: N прогонов, результат не зависит от числа процессов.
  • C4 — протокол команд (JSON-RPC, stdio/Unix-сокет) и repl; DoD: внешний скрипт делает open/reset/step/set_actuator/read_sensor и получает детерминированную траекторию.
  • C5 — serve; DoD: headless-сервер и клиент из NETWORK.md S1–S2.
  • C6 — MCP-адаптер поверх тех же команд; DoD: агент открывает сцену, шагает, читает датчики и снимок, не имея доступа к файлам вне проекта.

Открыто

  • Один бинарник с подкомандами или отдельные fabrilis-cli/fabrilis-server.
  • JSON-RPC по строкам достаточно или нужен бинарный протокол/shared memory.
  • MCP: отдельный процесс-адаптер или встроенный режим fabrilis mcp.
  • Права: что именно можно менять внешнему клиенту, а что только читать.
  • Частота управления по умолчанию и шаг децимации наблюдений.
  • Формат отчёта: CSV, JSON, RON или всё сразу.