仓库中现有的风格约定
建议直接遵循仓库已有的约定，这些规范体现在配置文件中，清晰直观。
pyproject.toml
Ruff 做 linter/formatter，line-length = 100，target = py311
hal/base_driver.py
Driver 接口用清晰动词：load_scene、execute_action、get_scene
hal/drivers/__init__.py
内置 driver 短名用 snake_case：go2_edu、xlerobot_2wheels_remote
模板与 profile
运行态协议文件全大写：ENVIRONMENT.md、EMBODIED.md、ACTION.md
命名约定
Driver 短名
snake_case，如 go2_edu、rekep_real。直接用在 --driver 参数和注册表里。
Python 类名
PascalCase，如 Go2Driver、RekepRealDriver。模块和类名保持稳定直观。
profile 文件名
建议和 driver 短名一致：go2_edu.md、rekep_real.md。排查时一眼对应。
可预测原则
看到 --driver my_robot、my_robot.md、MyRobotDriver 能自然推断是同一套东西。
目录边界与职责划分
命名错误易于修正，但职责边界混乱则难以恢复。
| 位置 | 适合放置 | 不应放置 |
|---|---|---|
PhyAgentOS/agent/tools/ |
高层工具封装、schema、Agent 协作入口 | 具体硬件 SDK 调用 |
hal/drivers/ |
内置 driver 的最小执行适配 | 大段第三方 SDK 和复杂 runtime |
hal/profiles/ |
能力画像、支持动作、物理约束 | 运行时数据 |
插件仓库 runtime/ |
真机桥接、厂商 SDK、预检、dry-run | 主仓库级通用协议逻辑 |
Ruff 配置
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]
ignore = ["E501"]I
导入顺序
N
命名风格
E/F/W
语法与常见错误
插件仓库结构建议
顶层文件
PhyAgentOS_plugin.tomlREADME.md/README_zh.mdpyproject.tomltests/
目录分工
- Python 包目录：driver.py + profiles/
runtime/：桥接、厂商 SDKtests/：manifest、driver 路由、预检
文档与样例
| 内容 | 建议 |
|---|---|
| 命令样例 | 提供可直接复制的完整命令，避免省略式伪代码 |
| 配置样例 | 提供最小可用配置，再说明可选字段 |
| 动作样例 | 提供标准 ACTION.md JSON，避免仅作口头描述 |
| profile 样例 | 说明支持哪些动作、有哪些硬约束 |
最低质量门槛
代码无需追求完美，但应确保其他维护者能够正常运行并理解。
- Driver / 插件能被成功加载
- 有对应 profile，运行时能安装为 EMBODIED.md
- 最少有一组动作或命令验证路径
- 有基础测试或冒烟验证
- README 能解释安装、启动、调试方式
判断标准：其他维护者能否仅凭仓库内容完成安装、理解职责边界并进行最小验证？