Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (69 loc) · 4.8 KB

AGENTS.md

File metadata and controls

87 lines (69 loc) · 4.8 KB
Raw

UniLab Agent Principles

Always use uv run, not python.

UniLab 是一个 高性能、模块化、contract 驱动 的 RL infrastructure 仓库。

Core Principles

  1. Contract first: 不为了一次通过绕过 env / backend / runner contract。
  2. Fix at owner layer: scripts/ 只组装流程，不承载长期业务规则。
  3. Config first: task / reward / backend 优先通过 Hydra + registry 表达。
  4. Backend isolation: MuJoCo / Motrix 差异留在 backend 适配层和配置层。
  5. Evidence only: support claim 只写仓库里已有的注册、配置、测试或 benchmark 事实。
  6. Validate near risk: 在最接近风险的边界补验证，不只跑顶层命令。
  7. Cold-path asset access only: asset/XML/model metadata 只允许在 init / materialization / cache 等低频路径处理；热路径不能解析 asset，也不能靠 getattr / hasattr 探测 backend 私有能力。

High-Risk Areas

区域 不可破坏的不变量
Env NpEnvState.obs 必须是 dict；reset() 返回 (obs_dict, info_dict)；obs_groups_spec 影响 wrapper 和 learner 维度。
Config / Reward reward 通过 Hydra 注入；后端切换必须通过 task=<task>/<backend> 选择 owner YAML，training.sim_backend 只是 owner YAML 的身份字段，不能单独 override 来切后端。算法超参数直接走 YAML compose，不经 Python 层解释。
Backend backend-specific 逻辑留在 backend / env 适配层，不向训练脚本扩散。env 层只能调用 SimBackend（base.py）中已声明的方法；若某方法只在 MuJoCo 或 Motrix 中存在，必须先将其加入 SimBackend 抽象接口（可抛 NotImplementedError），禁止直接在 env 里调用 backend 子类的私有方法（即"功能泄漏/feature leakage"）。新增 backend 专有能力时，需同步更新 SimBackend。
Asset / Metadata ASSETS_ROOT_PATH、model_file、XML / asset 元数据只允许在 init / materialization / cache 等低频路径访问；step/reset/domain randomization 等热路径不得解析 asset 或基于 asset 元数据做运行时分支。
Asset / XML structure <keyframe> 必须放在 task-level XML（scene_*.xml 或 locomotion_task.xml 等 fragment），禁止放进 robot.xml。robot.xml 是纯机器人描述（body / joint / actuator / sensor），跟 task / 场景无关；keyframe 是 task 起始姿态，属于场景或 task 资源。motrix 后端需要 keyframe 时通过 scene.fragment_files 引用 fragment XML。
Async 不绕开 runner lifecycle，也不另起 collector / learner 同步协议。

Pointers

  • PPO: scripts/train_rsl_rl.py
  • MLX PPO: scripts/train_mlx_ppo.py
  • APPO: scripts/train_appo.py
  • SAC / TD3: scripts/train_offpolicy.py
  • env contract: src/unilab/base/np_env.py
  • backend contract: src/unilab/base/backend/base.py
  • training run helpers: src/unilab/training/run.py
  • visualization helpers: src/unilab/visualization/
  • env shared numeric helpers: src/unilab/envs/common/rotation.py, src/unilab/envs/common/math.py
  • MLX rotation helpers: src/unilab/algos/mlx/common/rotation.py
  • config schema: src/unilab/structured_configs.py
  • async runner: src/unilab/ipc/async_runner.py

GitHub CLI (gh) 速查

Issue 查看

gh issue view <number>
gh api repos/<owner>/<repo>/issues/<number> --jq '.body'

PR 创建与管理

gh pr create --title "标题" --body "内容" --base main
gh pr list
gh pr view

PR Gate

创建或更新 PR 前必须满足：

  1. 最终提交已经完成，且 git status --short --branch 确认工作树干净。
  2. 最终提交已经通过 make test-all。
  3. 如果用户明确说明已经跑过 make test-all，不要重复跑；但必须在 PR body 的 Validation 里记录 make test-all 已完成。
  4. 如果 make test-all 未通过且用户没有明确 override，不要创建或更新 PR。

CI 工作流查看

gh run list
gh run list --workflow=<workflow-name>
gh run view <run-id>
gh run list --status=failure

常用组合

gh api repos/unilabsim/UniLab/issues/174 --jq '.title, .body'
git push -u origin fix/issue-174-mlx-ppo-config-alignment
gh pr create --title "fix: xxx" --body "Fixes #174" --base main

Context