# 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 --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 с токеном для удалённого сервера. ```text -> {"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 или всё сразу.