PhyAgentOS — 插件与驱动

插件发现链路

外部插件不会自动生效。主仓库需要通过清单文件知道用户提供了什么 driver、入口类在哪、profile 在哪等信息。整个发现链路如下：

1

清单

PhyAgentOS_plugin.toml 声明 driver 名、模块、类、profile 路径

2

部署

部署脚本把插件 clone/复制到本地插件目录

3

注册

hal/plugins.py 解析清单并写入本地 registry

4

加载

内置 driver 表找不到时，从外部 registry 动态导入

5

启动

Watchdog 用 --driver <name> 像内置 driver 一样启动

主仓库只认 BaseDriver 统一接口，不关心插件内部用了什么 SDK，这是插件机制的核心边界。

ReKep 插件安装

ReKep 是目前最完整的外部插件参考。你可以在线安装，也可以本地联调。

在线安装

python scripts/deploy_rekep_real_plugin.py \
  --repo-url https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.git

本地联调

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

# 带 solver 依赖
python scripts/deploy_rekep_real_plugin.py \
  --repo-url https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.git \
  --with-solver

# 只注册不装依赖
python scripts/deploy_rekep_real_plugin.py \
  --repo-url ../PhyAgentOS-rekep-real-plugin \
  --no-install-deps

通过 Watchdog 调用

这是最接近真实场景的用法。Agent 生成动作，Watchdog 监听 ACTION.md 并调用插件执行。

# 终端 1
paos onboard
python hal/hal_watchdog.py --driver rekep_real --workspace ~/.PhyAgentOS/workspace

# 终端 2
paos agent

演示"感知—决策—执行"完整闭环时，推荐用这种模式。

直接写 ACTION.md 调试

想绕过 Agent，直接验证某个动作能不能被插件接受？手动改 ACTION.md 是最快的办法。

插件原生动作

{
  "action_type": "real_execute",
  "parameters": {
    "instruction": "pick up the chili pepper and place it in the plate",
    "execute_motion": true
  },
  "status": "pending"
}

通用高层动作

{
  "action_type": "pick_up",
  "parameters": {
    "target": "red_apple"
  },
  "status": "pending"
}

ReKep 同时支持这两类协议。前者走插件专用能力，后者会被转成自然语言 instruction 再执行。

直接调 Runtime 排查

开发阶段最常见的需求：先绕开 Agent 和 Markdown，单独验证 runtime 本身有没有问题。

# 预检
python runtime/dobot_bridge.py preflight --pretty

# dry-run
python runtime/dobot_bridge.py execute \
  --instruction "pick up the red block and place it on the tray" \
  --pretty

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

# 切换 robot family
python runtime/dobot_bridge.py preflight \
  --robot_family cellbot \
  --robot_driver your_driver

runtime 级调试最适合定位第三方 SDK、桥接脚本或真机适配器的问题，因为它把故障范围缩到了最小。

内置驱动参考

PhyAgentOS 仓库内置的所有驱动完整参考。

驱动名称	机器人	类型	状态	说明
`simulation`	内置模拟器	仿真	已验证	默认模拟器，包含简单桌面场景。支持 move_to、pick_up、target_navigation、strategy。
`go2_edu`	Unitree Go2	四足	部分支持	四足机器人运动与导航。支持基于板载传感器的 target_navigation。
`franka`	Franka Research 3	机械臂	部分支持	7 自由度机械臂。支持笛卡尔空间运动和关节空间控制。
`piper`	AgileX PIPER	机械臂	部分支持	轻量级 6 自由度臂。主要配合 ReKep 用于抓取任务。
`dobot`	Dobot Nova 2	机械臂	部分支持	协作机器人臂。通过 ReKep 真机插件桥接部署。
`xlerobot`	XLeRobot	双臂	部分支持	双臂移动操作平台。支持协调双机械臂任务。
`pipergo2_manipulation`	PIPER + Go2	复合	部分支持	移动操作：PIPER 臂安装在 Go2 四足上。结合移动与抓取能力。

驱动配置透传

通过 --driver-config 参数将 JSON 配置文件直接传入驱动构造函数。

# 传入驱动专属配置
python hal/hal_watchdog.py --driver franka --driver-config examples/franka_config.json

JSON 对象会直接转发给驱动的构造函数。每个驱动定义自己的配置 schema——参考驱动文档了解可用字段。常见字段包括 ip、control_mode、gripper_type 和 sensor_config。

配置示例：{"ip": "192.168.1.100", "control_mode": "joint_position", "gripper_type": "parallel_jaw"}

插件与内置驱动如何选择

什么时候创建独立插件仓库，什么时候直接贡献到内置驱动表。

场景	使用插件仓库	使用内置驱动
重型 SDK 依赖（ROS、ReKep solver、CUDA）	插件隔离依赖膨胀	保持主仓库轻量
带专有 SDK 的真机	插件可自定 License	主仓库保持 MIT-only
需要独立版本管理	插件仓库独立发版	版本随 PhyAgentOS 发布
仿真小修小改	独立仓库的开销不值得	直接 PR 到 hal/drivers/
改进已有内置驱动	插件会重复造轮子	直接 PR 到对应驱动文件
通用工具类（日志、数学、I/O）	一般不适合插件形态	添加到 hal/utils/ 或 PhyAgentOS/utils/