PhyAgentOS是一个开源的具身AI框架，采用认知-物理解耦架构，通过Markdown协议文件实现软硬件通信，支持多机器人群体协作和跨平台零代码迁移。

PhyAgentOS：面向具身智能的自进化操作系统框架\n\n## 项目背景与核心理念\n\n随着大语言模型技术的快速发展，如何将其能力从数字世界延伸到物理世界成为具身智能领域的核心挑战。传统方案往往采用"大模型直接控制硬件"的黑盒模式，这种方式缺乏透明度且难以调试。中山大学人机协同与具身智能实验室推出的PhyAgentOS项目，提出了一种全新的"认知-物理解耦"架构范式，通过构建语言-动作接口，彻底分离动作表示与机器人形态，实现了从云端高推理模型到边缘物理执行层的标准化映射。\n\n## 架构设计：State-as-a-File协议矩阵\n\nPhyAgentOS最显著的创新在于其"State-as-a-File"设计理念。系统通过本地Markdown文件（如ENVIRONMENT.md、ACTION.md、EMBODIED.md）实现软硬件间的通信，这种设计带来了几个关键优势：\n\n### 完全解耦与极端透明\n\n传统的ROS或专用中间件往往将状态隐藏在内存或二进制消息中，而PhyAgentOS将所有状态以人类可读的Markdown格式持久化到文件系统。开发者可以直接打开文件查看当前环境状态、待执行动作和机器人配置，极大降低了调试难度。\n\n### 零代码跨平台迁移\n\n由于通信协议完全基于文件读写，新的硬件平台只需实现相应的文件解析和写入逻辑即可接入系统，无需修改核心代码。这种设计原生支持多机器人形态的无缝迁移。\n\n## 双轨多智能体系统\n\nPhyAgentOS采用独特的双轨架构设计：\n\n### 轨道A：认知核心\n\n该轨道包含Planner（规划器）和Critic（评判器）两个核心组件。大模型并不直接下发命令，而是必须经过Critic的严格验证。Critic会根据当前机器人的运行时EMBODIED.md（从profiles复制而来）检查规划动作的合法性和安全性，通过后才将动作提交到ACTION.md。\n\n这种设计引入了类似人类"三思而后行"的安全机制，防止智能体工作流失控。系统还维护LESSONS.md经验库，记录失败案例用于后续优化。\n\n### 轨道B：物理执行\n\n独立的硬件看门狗进程（hal_watchdog.py）负责监控和执行命令。该轨道与认知核心完全解耦，支持单实例模式和多机器人群体（Fleet）模式。在Fleet模式下，多个机器人可以共享全局环境信息，同时保持各自的本地动作队列。\n\n## 动态插件机制与安全校正\n\n### HAL硬件抽象层\n\nPhyAgentOS通过HAL（Hardware Abstraction Layer）协议支持多种机器人形态。外部硬件驱动可以动态加载到hal/drivers/目录，无需修改核心代码即可添加新硬件支持。目前已验证支持AgileX PIPER机械臂、Dobot Nova 2、Unitree Go2四足机器人等。\n\n### 语义导航与感知\n\n系统内置SemanticNavigationTool和PerceptionService，支持将高层语义目标（如"去厨房拿杯子"）解析为物理坐标，并通过融合几何和语义信息构建场景图。\n\n### 仿真循环\n\nPhyAgentOS内置轻量级仿真环境，允许在没有真实硬件的情况下验证从自然语言指令到物理状态变化的完整链条。这对于算法开发和测试极为重要。\n\n## 实际应用演示\n\n项目提供了多个演示视频展示系统能力：\n\n- 一键部署：展示AgileX PIPER机械臂的零代码部署流程\n- SAM3自然语言抓取：通过SAM3分割模型实现"抓取桌上的苹果"这类自然语言指令\n- ReKep任务执行：在Dobot Nova 2上展示基于关键点约束的抓取任务\n\n## 技术实现细节\n\n### 工作空间结构\n\n系统采用清晰的工作空间组织方式：\n\n- ~/.PhyAgentOS/workspace/：单实例运行时工作空间\n- ~/.PhyAgentOS/workspaces/：Fleet拓扑目录\n - shared/：智能体工作空间和全局ENVIRONMENT.md\n - go2_edu_001/：机器人本地ACTION.md和EMBODIED.md\n\n### 协议文件说明\n\n- EMBODIED.md：运行时机器人配置文件，描述当前机器人的物理形态和能力\n- ENVIRONMENT.md：当前场景图，包含感知到的物体和位置信息\n- ACTION.md：待执行的动作命令队列\n- LESSONS.md：失败经验记录，用于自我改进\n- SKILL.md：成功工作流的标准操作程序\n\n## 快速开始\n\n部署PhyAgentOS非常简洁：\n\nbash\ngit clone https://github.com/SYSU-HCP-EAI/PhyAgentOS.git\ncd PhyAgentOS\npip install -e .\npip install watchdog\npaos onboard\n\n\n执行后会生成核心Markdown协议文件。然后分别启动硬件看门狗和智能体：\n\nbash\n# 终端1：启动硬件层\npython hal/hal_watchdog.py\n\n# 终端2：启动认知层\npaos agent\n\n\n在智能体CLI中输入自然语言指令如"看看桌子上有什么，然后帮我拿那个苹果"，即可观察完整执行流程。\n\n## 项目路线图\n\nPhyAgentOS采用分阶段开发策略：\n\n第一阶段（桌面循环与协议建立）：已完成框架设计、具身技能插件、视觉解耦与抓取管道（SAM3和ReKep）、基于原子动作的VLN管道、多智能体协议设计。\n\n第二阶段（多形态协作与多模态记忆）：计划实现多机器人协调和长期记忆机制。\n\n第三阶段（约束求解与高层异构协调）：探索更复杂的任务规划和异构机器人协作。\n\n## 总结与意义\n\nPhyAgentOS代表了具身智能领域的一个重要探索方向。通过将状态外化为文件、将认知与物理解耦、引入多智能体安全机制，该项目为构建可靠、透明、可扩展的具身AI系统提供了新的思路。对于从事机器人开发、具身智能研究的工程师和研究者而言，这是一个值得关注和参与的开源项目。

PhyAgentOS：面向具身智能的自进化操作系统框架\n\n项目背景与核心理念\n\n随着大语言模型技术的快速发展，如何将其能力从数字世界延伸到物理世界成为具身智能领域的核心挑战。传统方案往往采用"大模型直接控制硬件"的黑盒模式，这种方式缺乏透明度且难以调试。中山大学人机协同与具身智能实验室推出的PhyAgentOS项目，提出了一种全新的"认知-物理解耦"架构范式，通过构建语言-动作接口，彻底分离动作表示与机器人形态，实现了从云端高推理模型到边缘物理执行层的标准化映射。\n\n架构设计：State-as-a-File协议矩阵\n\nPhyAgentOS最显著的创新在于其"State-as-a-File"设计理念。系统通过本地Markdown文件（如ENVIRONMENT.md、ACTION.md、EMBODIED.md）实现软硬件间的通信，这种设计带来了几个关键优势：\n\n完全解耦与极端透明\n\n传统的ROS或专用中间件往往将状态隐藏在内存或二进制消息中，而PhyAgentOS将所有状态以人类可读的Markdown格式持久化到文件系统。开发者可以直接打开文件查看当前环境状态、待执行动作和机器人配置，极大降低了调试难度。\n\n零代码跨平台迁移\n\n由于通信协议完全基于文件读写，新的硬件平台只需实现相应的文件解析和写入逻辑即可接入系统，无需修改核心代码。这种设计原生支持多机器人形态的无缝迁移。\n\n双轨多智能体系统\n\nPhyAgentOS采用独特的双轨架构设计：\n\n轨道A：认知核心\n\n该轨道包含Planner（规划器）和Critic（评判器）两个核心组件。大模型并不直接下发命令，而是必须经过Critic的严格验证。Critic会根据当前机器人的运行时EMBODIED.md（从profiles复制而来）检查规划动作的合法性和安全性，通过后才将动作提交到ACTION.md。\n\n这种设计引入了类似人类"三思而后行"的安全机制，防止智能体工作流失控。系统还维护LESSONS.md经验库，记录失败案例用于后续优化。\n\n轨道B：物理执行\n\n独立的硬件看门狗进程（hal_watchdog.py）负责监控和执行命令。该轨道与认知核心完全解耦，支持单实例模式和多机器人群体（Fleet）模式。在Fleet模式下，多个机器人可以共享全局环境信息，同时保持各自的本地动作队列。\n\n动态插件机制与安全校正\n\nHAL硬件抽象层\n\nPhyAgentOS通过HAL（Hardware Abstraction Layer）协议支持多种机器人形态。外部硬件驱动可以动态加载到hal/drivers/目录，无需修改核心代码即可添加新硬件支持。目前已验证支持AgileX PIPER机械臂、Dobot Nova 2、Unitree Go2四足机器人等。\n\n语义导航与感知\n\n系统内置SemanticNavigationTool和PerceptionService，支持将高层语义目标（如"去厨房拿杯子"）解析为物理坐标，并通过融合几何和语义信息构建场景图。\n\n仿真循环\n\nPhyAgentOS内置轻量级仿真环境，允许在没有真实硬件的情况下验证从自然语言指令到物理状态变化的完整链条。这对于算法开发和测试极为重要。\n\n实际应用演示\n\n项目提供了多个演示视频展示系统能力：\n\n- 一键部署：展示AgileX PIPER机械臂的零代码部署流程\n- SAM3自然语言抓取：通过SAM3分割模型实现"抓取桌上的苹果"这类自然语言指令\n- ReKep任务执行：在Dobot Nova 2上展示基于关键点约束的抓取任务\n\n技术实现细节\n\n工作空间结构\n\n系统采用清晰的工作空间组织方式：\n\n- ~/.PhyAgentOS/workspace/：单实例运行时工作空间\n- ~/.PhyAgentOS/workspaces/：Fleet拓扑目录\n - shared/：智能体工作空间和全局ENVIRONMENT.md\n - go2_edu_001/：机器人本地ACTION.md和EMBODIED.md\n\n协议文件说明\n\n- EMBODIED.md：运行时机器人配置文件，描述当前机器人的物理形态和能力\n- ENVIRONMENT.md：当前场景图，包含感知到的物体和位置信息\n- ACTION.md：待执行的动作命令队列\n- LESSONS.md：失败经验记录，用于自我改进\n- SKILL.md：成功工作流的标准操作程序\n\n快速开始\n\n部署PhyAgentOS非常简洁：\n\nbash\ngit clone https://github.com/SYSU-HCP-EAI/PhyAgentOS.git\ncd PhyAgentOS\npip install -e .\npip install watchdog\npaos onboard\n\n\n执行后会生成核心Markdown协议文件。然后分别启动硬件看门狗和智能体：\n\nbash\n终端1：启动硬件层\npython hal/hal_watchdog.py\n\n终端2：启动认知层\npaos agent\n\n\n在智能体CLI中输入自然语言指令如"看看桌子上有什么，然后帮我拿那个苹果"，即可观察完整执行流程。\n\n项目路线图\n\nPhyAgentOS采用分阶段开发策略：\n\n第一阶段（桌面循环与协议建立）：已完成框架设计、具身技能插件、视觉解耦与抓取管道（SAM3和ReKep）、基于原子动作的VLN管道、多智能体协议设计。\n\n第二阶段（多形态协作与多模态记忆）：计划实现多机器人协调和长期记忆机制。\n\n第三阶段（约束求解与高层异构协调）：探索更复杂的任务规划和异构机器人协作。\n\n总结与意义\n\nPhyAgentOS代表了具身智能领域的一个重要探索方向。通过将状态外化为文件、将认知与物理解耦、引入多智能体安全机制，该项目为构建可靠、透明、可扩展的具身AI系统提供了新的思路。对于从事机器人开发、具身智能研究的工程师和研究者而言，这是一个值得关注和参与的开源项目。