Files
chenlin ceca51b0d8
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
Improve generic robot onboarding, walking controls and end-effector interaction
Default humanoid intake to command-following gait and support bounded Cartesian target dragging for arms. Carry model and actuator semantics through calibration, native verification and packaging. Document reusable intake decisions and cover them with regression tests.
2026-11-06 10:54:58 +08:00

62 lines
3.0 KiB
Markdown

# Repository working rules
The project is a generic robotics onboarding, simulation, and training platform.
Choose an intake route in [Workflow](docs/WORKFLOWS.md). Use
[Usage](docs/USAGE.md) for commands and [Contributing](CONTRIBUTING.md) for layout.
Apply the mandatory [per-robot skill maintenance rule](AGENTS.md#maintain-skills-after-every-robot-intake)
to every intake.
## Checks
Run from the repository root with the editable install active.
```bash
python -m pip install -e ".[dev]"
python -m pytest tests/ -q
python -m ruff check .
python scripts/train.py --list
```
For a host with unrelated pytest plugins on its Python path, run pytest in the
project environment with `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`. Use
[agent setup](docs/AGENT_SETUP.md) if imports resolve to a different checkout.
## Architecture
- The root and `rl/` are separate package roots. `rl/` has no `__init__.py`.
Keep imports from `mjrl`, `mjlab`, and `rsl_rl` in their existing form and
use the editable install to resolve them.
- `mjrl.backend.select.use_backend` must run before creating an environment.
The manager resolves mjlab's simulation class when it builds the environment.
Native MuJoCo implements the batched simulator interface that Warp provides.
- Native rollout scratch data is per worker. Restore each environment's state,
controls, and warm starts from its own buffers. Constant recomputation uses
dedicated scratch data and preserves visual statistics.
- `tasks/registry.py` discovers literal `tasks/<robot_id>/robot_spec.py`
files. Listing tasks must stay free of simulation imports. The selected
family resolves to a locked template in `tasks/templates/`.
- Keep physical facts in the robot specification and asset. Keep reward and
observation logic, randomization, curriculum, and PPO in the templates.
Adding a robot requires no changes to a template or a command entry point.
- Onboarding and verification are in `rl/mjrl/onboarding/`. Deterministic
controls live in `rl/mjrl/controllers/`, and the portable native runtime
lives in `rl/mjrl/platform/`. The legacy Rust controller and target build
tools remain in `deploy/`.
## Changes and verification
- Preserve the lock in `tests/test_template_lock.py`. Review an authorized
template revision before updating the recorded hashes, including shared
dependencies that change template behavior.
- Verify physics and control response separately. Report measured outcomes with
the model, backend, and run size. A shape check, a visual preview, or a
completed iteration alone cannot establish behavior or hardware readiness.
- Keep changes to vendored libraries identifiable with an `[mjrl]` marker,
reason, and upstream version. See [Vendoring](docs/VENDOR.md).
- Write repository material in English. A Chinese `*.zh.md` translation
carries the digest of its English source. Update both before refreshing the
marker with `tools/checks/stamp_translations.py`.
- Exercise tests against the quiet failure they claim to prevent. When an
assertion could pass vacuously, include a control that demonstrates detection.