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.
This commit is contained in:
parent
79928b645b
commit
93075ab1fd
107 changed files with 14785 additions and 46 deletions
116
docs/CLI.md
Normal file
116
docs/CLI.md
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
# Headless CLI
|
||||
|
||||
CLI — это пульт управления движком и расчётный инструмент: пакетные прогоны и
|
||||
живая консоль. Внешняя программа — скрипт, агент, нейросеть — управляет движком
|
||||
командами, как инструментами через MCP. Окно и GPU не нужны.
|
||||
|
||||
Отдельный бинарник, который не зависит от `render`, `ui` и `winit`; общий код мира
|
||||
и прогонов живёт в `modes`, чтобы GUI и CLI считали одно и то же.
|
||||
|
||||
## Зачем
|
||||
|
||||
- прогнать сценарий на сервере и получить CSV/отчёт;
|
||||
- проверить регрессии в CI без дисплея;
|
||||
- считать развёртки и 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-хеш проверяется в CI.
|
||||
- Параллельные прогоны — отдельные процессы, результат не зависит от их числа.
|
||||
- Логи по 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 или всё сразу.
|
||||
Loading…
Add table
Add a link
Reference in a new issue