Skip to content

README_zh.md

Latest commit

 

History

History
303 lines (249 loc) · 12.9 KB

README_zh.md

File metadata and controls

303 lines (249 loc) · 12.9 KB
Raw
PhyAgentOS

认知与物理解耦 —— 面向具身智能的 Session-Centered 运行时

Stars Forks

Python License 技术报告 Website PRs

English · 中文

📢 更新日志

版本 日期 更新内容
v0.1.7 2026-07-5 支持 Policy loop 以及 Target native builtin 路径的 Benchmarking，并加入了 Agent 验证与失败恢复服务 ｜
v0.1.6 2026-06-27 支持 Behavior 1K Benchmark；用于 Agent 校验的 SessionVerfier; VerifySessionTool
v0.1.5 2026-06-11 清理协议文件及文档，game 场景分离至 general-game-agent 分支独立推进；当前分支聚焦仿真 & 真机重构
v0.1.4 2026-06-5 优化用户友好的启动流程; 通信协议规范; 更合理的代码规范; Game Agent & Benchmarking 就绪
v0.1.3 2026-05-25 PolicySkillRuntime / BuiltinSkillRuntime 边界严格分离，Game Agent & Benchmarking 就绪
v0.1.2 2026-05-20 感知插件体系：SensorConfig / PerceptionConfig YAML + EnvironmentWriter 可审计写回
v0.1.1 2026-05-18 Session-Centered Runtime MVP：DummySimTarget + DummyAdapter + DummyClient 串行链路
v0.1.0 2026-04-29 Hackathon 基线：插件化 HAL，ReKep / SAM3 真机抓取与 VLN 全链路

🤔 为什么选择 PhyAgentOS？

传统的"大模型直连硬件"方案高度耦合，换一个机器人就要重写整个执行链路。PhyAgentOS 通过 认知-物理解耦 + Session-Centered Runtime 彻底改变了这一点：

🔌同代码，万硬件 — 新增机器人只需实现一个 Target Adapter（~100 行），调度层零改动。
🛡️三道安全防线 — Critic 校验 → Strict Preflight → Target-side SafetyGuard，真机场景不可绕过。
📋全程可审计 — 状态、动作、感知结果以 Markdown + YAML 落盘，每一步可追溯复现。
🔄零摩擦迁移 — 同一套 Session 协议在 sim / real 2类 target 上无差别运行。
架构图

▲ Session-Centered Runtime 架构全览

✨ 核心特性

🔄 Session-Centered Runtime WatchdogSupervisor → SessionRunner → SkillRuntime → TargetSessionHandle 执行链路，抛弃 Driver-Center 旧架构
🎯 Target-Configured debug / simulation / real_robot 三类 target，TARGETS.md 统一注册，adapter 按需挂载
🧩 Adapter + Bridge TargetAdapter + PolicyAdapter + ActionBridge 三段解耦，并显式声明 observation/action 契约；AdapterPlan 自动编排，消灭 target×skill 组合爆炸
⚡ 双轨 Skill 运行时 PolicySkillRuntime 维护 policy 闭环 + BuiltinSkillRuntime 管理 target-native benchmark、受约束 agent 交互等内建闭环
🛡️ Strict Preflight 运行时前置校验（target / sensor / perception / adapter contract / action contract / tool），不合格直接 rejected
📝 文件协议矩阵 TARGETS.md · SKILLRUNTIME.md · SESSIONS.md · ENVIRONMENT.md · LESSONS.md + 外部 YAML
🔐 多层安全 Critic 校验 → Preflight 契约检查 → Target-side SafetyGuard → Operator Override
🌐 Fleet 模式 多机器人协同，shared + per-robot 工作区，优先级串行调度
🖥️ 内置 TUI paos tui — 全屏界面：平铺对话 + 实时状态/日志窗格、Provider 与设置管理、莫兰迪主题

🚀 5 分钟快速开始

1

安装

git clone https://github.com/PhyAgentOS/PhyAgentOS.git && cd PhyAgentOS
pip install -e .            # Python ≥ 3.11
pip install -e ".[dev]"     # 开发依赖
2

初始化工作区

paos onboard
3

启动 Agent

paos agent    # CLI 对话
paos tui      # 全屏 TUI
4

可选：连接 Runtime 服务

下面的示例通过 LiberoBenchmarkSkillRuntime 的 builtin 路径，在启用 episode replan 的情况下使用官方 PI0.5 policy 评估 libero_spatial。 三个终端位于同一主机，所有命令均从项目根目录执行。

# 终端 1：LIBERO TargetWS
MUJOCO_GL=egl PYTHONWARNINGS=ignore \
conda run --no-capture-output -n libero \
  python PhyAgentOS/runtime/targets/remote/libero/server.py \
  --host 0.0.0.0 --port 9002 \
  --camera-height 256 --camera-width 256 \
  --max-steps 300 --num-steps-wait 10 \
  --control-mode relative --seed 7

# 终端 2：官方 OpenPI PI0.5 policy server
conda run --no-capture-output -n openpi \
  python -m PhyAgentOS.runtime.policy.openpi.native_openpi_server \
  --policy-config pi05_libero \
  --checkpoint-dir gs://openpi-assets/checkpoints/pi05_libero \
  --host 0.0.0.0 --port 8000

# 终端 3：Agent、Watchdog 与 Verification Service
paos agent --workspace ~/.PhyAgentOS/workspace -m \
  "使用 PI0.5 评估 LIBERO 的 libero_spatial suite。选择 libero_real_remote target、libero_target_benchmark builtin runtime、target_native 执行路径和 recovery 校验；task id 使用 0-9，init-state id 使用 0-49，max_steps 设为 300，replan_every_steps 设为 5，policy endpoint 使用 openpi://127.0.0.1:8000。"

启动终端 3 前，需要启用 libero_real_remote、配置 Runtime verification， 并在 Target 配置中设置 retry_instruction_mode: original。 后者使 recovery attempt 保持原任务指令；需要把 verifier 返回的非空 rewrite 作为 policy 指令时，改用 verifier_rewrite。 完整的全局配置、Target、SkillRuntime、Session、benchmark、verification 和 远程部署参数参见 Runtime 参数配置参考， 其中包含 LIBERO 配置示例。

🗂️ 协议文件

进入上下文逻辑 文件 所属工作区 功能
始终进入 agent system prompt AGENTS.md Agent workspace Agent 的项目级运行规则
始终进入 agent system prompt SOUL.md Agent workspace 身份、行为边界与助手风格
始终进入 agent system prompt USER.md Agent workspace 用户偏好与长期画像
始终进入 agent system prompt TOOLS.md Agent workspace 工具使用规则与可用工具说明
始终进入 agent system prompt SKILLS.md Agent workspace 面向 Agent 的 skill 发现与加载规则
存在时进入上下文；涉及 target 时按启用 target 过滤 EMBODIED.md Agent workspace Target 能力的人类可读描述
存在时作为状态进入上下文，不是 bootstrap 规则 ENVIRONMENT.md Agent/runtime workspace 当前 target、场景与环境状态
存在时作为记忆/状态进入上下文 LESSONS.md Agent workspace 运行经验、失败记录与修正建议
存在时作为任务状态进入上下文 TASK.md Agent workspace 多步任务拆解与进度
Runtime 协议；创建 session 前读取 RUNTIME.md Runtime workspace 写入合法 runtime session 的说明
Runtime 协议；创建 session 前读取 TARGETS.md Runtime workspace 已启用 target、endpoint/adapter/config 引用、支持的 skill runtime
Runtime 协议；创建 session 前读取 SKILLRUNTIME.md Runtime workspace Policy/builtin skill runtime 注册表与执行契约
Runtime 队列/状态；Agent 与 watchdog 写入 SESSIONS.md Runtime workspace 待执行、执行中、已完成 session 与结果

SKILLS.md 服务 Agent 能力与 skill 发现；SKILLRUNTIME.md 服务 runtime 执行契约，并与 TARGETS.md、SESSIONS.md 配套使用。

📦 项目结构

PhyAgentOS/
│
├── PhyAgentOS/agent/          # Track A  ─  Planner / Critic / Memory
│
├── PhyAgentOS/runtime/        # Track B  ─  执行平面
│   ├── watchdog/              #   WatchdogSupervisor
│   ├── sessions/              #   SessionRunner / TargetSessionHandle
│   ├── targets/               #   RolloutTarget (debug·sim·real)
│   │   └── remote/libero/     #   LIBERO benchmark TargetWS server + proxy
│   ├── skillruntime/          #   PolicySkillRuntime / BuiltinSkillRuntime
│   ├── adapters/              #   TargetAdapter / PolicyAdapter / Bridge
│   │   ├── libero/            #   LIBERO target adapter
│   │   └── openpi/            #   OpenPI policy adapters
│   ├── policy/openpi/         #   OpenPI client + LeRobot pi0-family server
│   ├── perception/            #   感知运行时 / EnvironmentWriter
│   ├── preflight/             #   RuntimeCompatibilityPreflight
│   └── schemas/               #   Pydantic Schema
│
├── configs/runtime/           # Sensor / Perception / Contract YAML
├── scripts/                   # 工具脚本
├── workspace/                 # Agent 工作区；runtime 文件可按配置共用该目录
├── docs/                      # 文档
└── tests/                     # 测试

🏷️ 支持目标

Kind 位置 示例
🐛 debug Local echo / mock / dry-run —— 零硬件验证协议链路
🧪 simulation Remote RoboCasa、LIBERO —— Benchmark 评测与批量经验挖掘
🤖 real_robot Remote Franka、Go2、XLeRobot、AgileX PIPER —— 真实运行

全部 target 通过 TARGETS.md 统一注册，target_adapter:// URI 标识 adapter。 更多实例与演示 → 项目网站

📖 文档

文档 面向 说明
🌐 项目网站 所有人 完整文档、架构详解、Demo 演示
📘 用户手册 使用者 安装部署、运行操作指南
📙 开发指南 开发者 二次开发、硬件接入、插件编写

🤝 参与贡献

欢迎提交 PR 和 Issue，我们的开发计划可以在此处查看👉 开发计划。

由 中山大学 HCP 实验室、鹏城实验室 与 拓元智慧 联合开发


HCP     Pengcheng     X-Era Lab
MIT License · Copyright © 2025-2026 PhyAgentOS