PhyAgentOS API 使用 - 插件使用说明

插件的注册

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

1

清单

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

2

部署

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

3

注册

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

4

加载

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

5

启动

Watchdog 用 --driver 像内置 driver 一样启动

框架只认统一接口，不关心插件内部用了什么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、桥接脚本或真机适配器的问题，因为它把故障范围缩到了最小。

ReKep 为什么值得参考

🚪

Driver 层

driver.py 对接 BaseDriver 接口，是框架能看到的唯一入口。

⚙️

runtime 层

dobot_bridge.py 负责预检、dry-run、真机执行，承载重逻辑和第三方依赖。

🔌

适配层

robot_factory.py 等负责不同机器人 family 的具体适配，边界清晰。

三种调试方式怎么选

方式	适合阶段	优点	注意
Watchdog + Agent	完整链路验证、演示	最接近真实场景	问题可能横跨三层
直接写 ACTION.md	动作映射测试	绕过 Agent，快速验证 Driver	仍依赖 Watchdog
直接调 runtime	插件开发、SDK 排查	故障范围最小	不代表全链路已通