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

116 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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