PhyAgentOS 开发指南 - 以 ReKep 为样例的插件开发

为什么推荐参考 ReKep

🧱

边界清楚

主仓库仅关注 Driver 接口；插件内部可自由使用任意 SDK。

🏗️

结构完整

清单、Driver、runtime、部署脚本、测试一应俱全。

🔄

可直接迁移

把 ReKep 的名字、动作映射、runtime 实现换掉，就是你的新插件。

最小插件结构

无需一次性实现所有功能。建议先搭建基础骨架，确保 Watchdog 能正常加载，再逐步补充复杂能力。

my-phyagentos-plugin/
├── PhyAgentOS_plugin.toml ← 清单，告诉主仓库你是谁
├── README.md / README_zh.md
├── pyproject.toml
├── my_plugin/
│ ├── __init__.py
│ ├── driver.py ← BaseDriver 实现
│ └── profiles/
│ └── my_robot.md ← 能力画像
├── runtime/
│ └── your_runtime_entry.py ← 真机桥接、重逻辑
└── tests/
└── test_my_driver.py

路径	用途说明
`PhyAgentOS_plugin.toml`	声明 driver 名、入口类、profile 位置
`my_plugin/driver.py`	Watchdog 实际加载的 BaseDriver 子类
`my_plugin/profiles/*.md`	运行时会被复制为 EMBODIED.md
`runtime/`	存放第三方 SDK、桥接脚本、长流程逻辑
`tests/`	插件级别的冒烟测试

清单文件编写指南

[plugin]
name = "my_robot"
version = "0.1.0"
description = "My robot plugin for PhyAgentOS"

[driver]
name = "my_robot"
module = "my_plugin.driver"
class = "MyRobotDriver"
profile_path = "my_plugin/profiles/my_robot.md"

[python]
sys_paths = ["."]

[[requirements]]
path = "runtime/requirements.txt"
optional = false

最关键的两个字段：driver.name 决定 Watchdog 用 --driver 什么名字找到你；driver.module + driver.class 决定主仓库实际导入哪个 Python 类。

Driver 与 runtime 的职责划分

Driver 层

负责对接 BaseDriver 接口：接收动作、转换参数、返回结果、暴露 profile。建议保持此层尽量精简。

runtime 层

负责预检、dry-run、真机执行、长程任务。重依赖和复杂桥接逻辑应放置于此，不应放入 Driver 层。

职责分离的直接优势：出现问题时，可快速定位是"主仓库协议适配"故障还是"真机执行"故障。

本地联调结构

推荐的本地开发方式：将插件仓库与主仓库放置于同级目录，通过本地路径完成安装。

git clone https://github.com/SYSU-HCP-EAI/PhyAgentOS.git
git clone https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.git

cd PhyAgentOS
pip install -e .

python scripts/deploy_rekep_real_plugin.py \
  --repo-url ../PhyAgentOS-rekep-real-plugin

这样你可以一边改插件代码，一边用主仓库的 Watchdog 和 Agent 跑完整链路验证。

验证顺序：preflight → dry-run → 全链路

1

preflight

→

2

dry-run

→

3

全链路

# 1. 预检 — 确认 runtime 环境正常
python runtime/dobot_bridge.py preflight --pretty

# 2. dry-run — 不碰真机，验证动作解析
python runtime/dobot_bridge.py execute \
  --instruction "pick up the red block and place it on the tray" \
  --pretty

# 3. 真机执行
python runtime/dobot_bridge.py execute \
  --instruction "pick up the red block and place it on the tray" \
  --execute_motion \
  --pretty

# 4. 回到 Watchdog + Agent 完整闭环
paos onboard
python hal/hal_watchdog.py --driver rekep_real --workspace ~/.PhyAgentOS/workspace
paos agent

ReKep 兼容两种动作协议

插件原生动作

real_preflight、real_execute、real_execute_background、real_scene_qa、real_longrun_start

直接映射到 runtime 子命令，适合调用插件的专用能力。

通用高层动作

move_to、pick_up、put_down、push、point_to、open_gripper、close_gripper

会被转成自然语言 instruction 后落到统一执行入口。

设计新插件时也建议保留这两层：一层给主仓库通用协议，一层给插件内部专用接口。

ReKep 插件开发样例

为什么推荐参考 ReKep

边界清楚

结构完整

可直接迁移

最小插件结构

清单文件编写指南

Driver 与 runtime 的职责划分

Driver 层

runtime 层

本地联调结构

验证顺序：preflight → dry-run → 全链路

ReKep 兼容两种动作协议

插件原生动作

通用高层动作

推荐的社区开发流程