PhyAgentOS Developer Guide - Code Style & Naming Conventions

Existing Style Conventions in the Repository

It is recommended to follow the existing conventions in the repository. These standards are reflected in configuration files and are clear and intuitive.

pyproject.toml

Ruff as linter/formatter, line-length = 100, target = py311

hal/base_driver.py

Driver interface uses clear verbs: load_scene, execute_action, get_scene

hal/drivers/__init__.py

Built-in driver short names use snake_case: go2_edu, xlerobot_2wheels_remote

Templates & profiles

Runtime protocol files are ALL_CAPS: ENVIRONMENT.md, EMBODIED.md, ACTION.md

Naming Conventions

Driver Short Names

snake_case, e.g. go2_edu, rekep_real. Used directly in --driver arguments and the registry.

Python Class Names

PascalCase, e.g. Go2Driver, RekepRealDriver. Keep module and class names stable and intuitive.

Profile Filenames

Recommended to match driver short name: go2_edu.md, rekep_real.md. One-glance correspondence when debugging.

Predictability Principle

Seeing --driver my_robot, my_robot.md, MyRobotDriver should naturally imply they're the same thing.

Directory Boundaries & Responsibility Separation

Naming errors are easy to correct, but unclear responsibility boundaries are difficult to recover from.

Location	Suitable For	Not Suitable For
`PhyAgentOS/agent/tools/`	High-level tool wrappers, schemas, Agent collaboration entry points	Specific hardware SDK calls
`hal/drivers/`	Minimal execution adapters for built-in drivers	Large third-party SDKs and complex runtime
`hal/profiles/`	Capability profiles, supported actions, physical constraints	Runtime data
Plugin repo `runtime/`	Real-robot bridging, vendor SDKs, preflight, dry-run	Main-repo-level generic protocol logic

Ruff Configuration

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]
ignore = ["E501"]

I

Import order

N

Naming style

E/F/W

Syntax & common errors

Plugin Repository Structure Recommendations

Top-Level Files

PhyAgentOS_plugin.toml
README.md / README_zh.md
pyproject.toml
tests/

Directory Responsibilities

Python package directory: driver.py + profiles/
runtime/: bridging, vendor SDKs
tests/: manifest, driver routing, preflight

Documentation & Examples

Content	Recommendation
Command examples	Provide complete, copy-pasteable commands — avoid abbreviated pseudocode
Config examples	Provide minimal working configs, then explain optional fields
Action examples	Provide standard ACTION.md JSON — avoid verbal descriptions only
Profile examples	Explain supported actions and hard constraints

Minimum Quality Bar

Code does not need to be perfect, but it should ensure that other maintainers can run and understand it.

Driver / plugin can be successfully loaded
Has a corresponding profile that can be installed as EMBODIED.md at runtime
Has at least one action or command verification path
Has basic tests or smoke verification
README explains installation, startup, and debugging methods

Judgment criterion: can other maintainers complete installation, understand responsibility boundaries, and perform minimal verification using only the repository contents?