PhyAgentOS 开发指南 - 接入新 Driver 的完整流程

BaseDriver 接口概览

实现以下方法后，Watchdog 即可像使用内置 Driver 一样使用您的 Driver。建议先实现最小接口，确保 Watchdog 能正常加载。

class BaseDriver(ABC):
    def get_profile_path(self) -> Path: ...
    def load_scene(self, scene: dict[str, dict]) -> None: ...
    def execute_action(self, action_type: str, params: dict) -> str: ...
    def get_scene(self) -> dict[str, dict]: ...

    # 常用可选
    def connect(self) -> bool: ...
    def disconnect(self) -> None: ...
    def is_connected(self) -> bool: ...
    def health_check(self) -> bool: ...
    def get_runtime_state(self) -> dict[str, Any]: ...

get_profile_path()

返回 EMBODIED.md profile 的路径

load_scene()

用 ENVIRONMENT.md 初始化内部状态

execute_action()

执行动作，返回人类可读结果

get_scene()

返回当前环境状态，回写 ENVIRONMENT.md

先实现最小可加载版本

建议先确保 Watchdog 能正常导入和实例化 Driver，并完成一轮完整的动作消费流程，再逐步扩展功能。

from pathlib import Path
from hal.base_driver import BaseDriver

class MyRobotDriver(BaseDriver):
    def __init__(self, gui: bool = False, **kwargs):
        self._scene = {}

    def get_profile_path(self) -> Path:
        return Path(__file__).resolve().parent / "profiles" / "my_robot.md"

    def load_scene(self, scene: dict[str, dict]) -> None:
        self._scene = dict(scene)

    def execute_action(self, action_type: str, params: dict) -> str:
        return f"executed {action_type}"

    def get_scene(self) -> dict[str, dict]:
        return dict(self._scene)

这个最小实现的目标是：确认主仓库能稳定导入 driver、安装 profile，顺利完成动作消费与状态回写。后续再逐步补动作映射和真机逻辑。

补充 profile 文件

profile 里写什么

Identity：名称、类型、driver/profile
Sensors / Degrees of Freedom
Supported Actions
Physical Constraints
Connection 与 Runtime Protocol

缺失的影响

Critic 没有动作约束依据，ROBOTS.md 无法给出可靠能力摘要。Agent 会不知道该让这台机器人干什么。

内置 Driver 注册方式

做内置 driver（不是外部插件）还需要在注册表里加一行短名映射。

DRIVER_REGISTRY: dict[str, str] = {
    "simulation": "hal.drivers.simulation_driver.SimulationDriver",
    "go2_edu": "hal.drivers.go2_driver.Go2Driver",
    "my_robot": "hal.drivers.my_robot_driver.MyRobotDriver",
}

外部插件由插件清单和 registry 负责发现，不需要改这行。

Watchdog 实际调用顺序

加载 driver

能 import 并实例化

安装 profile 到 EMBODIED.md

get_profile_path() 返回有效路径

建立连接，刷新健康状态

connect() / health_check() 正常

读取 ACTION.md，调用 execute_action()

动作类型和参数能被接住

回写状态到 ENVIRONMENT.md

get_scene() / get_runtime_state() 序列化正常

调试顺序

先让 driver 能被 import 和实例化

在 Python shell 里 from hal.drivers.my_robot_driver import MyRobotDriver; d = MyRobotDriver() 不报错

确认 profile 能安装到 EMBODIED.md

看启动日志或检查 workspace 下是否生成了正确的 EMBODIED.md

确认动作能进入 execute_action()

在方法中添加日志输出，确认是否被正确调用

确认状态能回写 ENVIRONMENT.md

执行完动作后 cat ENVIRONMENT.md，看机器人状态是否更新

最后再用 paos agent 做自然语言链路联调

用简单明确的指令触发，观察 ACTION.md 生成和执行结果

调试的核心思路是分层验证：先确认"能加载"，再确认"能执行"，最后确认"能回写"。建议避免直接追求完整链路。