Markdown 文件格式与样例

文件位置

Single 模式下所有文件堆在一个目录；Fleet 模式下，shared 文件放全局，机器人私有的放各自 workspace。

ENVIRONMENT.md · 环境真相源

这是系统当前环境状态的"唯一真相"。场景图、机器人位姿、导航状态全在这里。Watchdog 和感知模块负责更新，Agent 和 Critic 负责读取。

{
  "schema_version": "PhyAgentOS.environment.v1",
  "updated_at": "2026-03-17T10:20:30Z",
  "scene_graph": {
    "nodes": [
      {
        "id": "obj_red_apple",
        "class": "apple",
        "object_key": "red_apple",
        "center": {"x": 0.05, "y": 0.05, "z": 0.75},
        "size": {"x": 0.06, "y": 0.06, "z": 0.06},
        "confidence": 0.96,
        "frame": "map",
        "track_id": "track_apple_001",
        "last_seen_at": "2026-03-17T10:20:29Z"
      }
    ],
    "edges": [
      {"source": "obj_red_apple", "relation": "ON", "target": "furniture_table", "confidence": 0.97}
    ]
  },
  "robots": {
    "go2_edu_001": {
      "connection_state": {
        "status": "connected",
        "transport": "ssh",
        "host": "192.168.1.23",
        "port": 22,
        "last_heartbeat": "2026-03-17T10:20:30Z"
      },
      "robot_pose": {
        "frame": "map",
        "x": 1.23, "y": -0.45, "z": 0.0, "yaw": 1.57,
        "stamp": "2026-03-17T10:20:30Z"
      },
      "nav_state": {
        "mode": "navigating",
        "status": "running",
        "goal_id": "nav_goal_001"
      }
    }
  },
  "objects": {
    "red_apple": {
      "type": "fruit",
      "color": "red",
      "location": "table"
    }
  }
}

EMBODIED.md · 能力画像

这不是实时状态，而是给 Agent 看的能力说明书。Watchdog 启动时从 hal/profiles/*.md 复制过来。

# EMBODIED.md Template

## Identity
- **Name**: Unitree Go2 EDU
- **Type**: quadruped
- **Driver/Profile**: go2_edu

## Sensors
- **Camera**: RGBD
- **LiDAR**: yes
- **Odometry**: yes

## Supported Actions
| Action | Parameters | Description |
|--------|-----------|-------------|
| `move_to` | `x, y` | Navigate to a target pose |
| `target_navigation` | `target_label, timeout_s` | Move toward a visual target |

## Physical Constraints
- **Max speed**: 1.0 m/s
- **Safety distance**: 0.4 m
- **Collision policy**: stop when obstacle too close

写这个文件的诀窍是：别塞技术细节，让 Agent 快速知道"这是什么、能做什么、边界在哪"。

ACTION.md · 动作队列

执行链路的直接派发文件。Agent 把动作写进去，Watchdog 读出来交给 Driver。

{
  "schema_version": "PhyAgentOS.action_queue.v1",
  "actions": [
    {
      "id": "2f18c6a912ab",
      "action_type": "target_navigation",
      "parameters": {
        "robot_id": "go2_edu_001",
        "target_label": "apple",
        "timeout_s": 30
      },
      "status": "pending"
    }
  ]
}

TASK.md · 长程任务拆解

把一句自然语言拆成多个子任务，分配给不同机器人。编排器看的就是这个文件。

# Active Task

## Goal
Pick up the red apple from the table and place it into the blue basket in the kitchen.

## Sub-Tasks
| ID | Action | Target Device | Status | Depends On | Result |
|----|--------|---------------|--------|------------|--------|
| T1 | navigate_to | go2_edu_001 | completed | — | arrived |
| T2 | detect_target | go2_edu_001 | completed | T1 | found apple |
| T3 | pick_up | franka_001 | pending | T2 | — |
| T4 | navigate_to | go2_edu_001 | pending | T3 | — |
| T5 | place_in | franka_001 | pending | T4 | — |

SESSIONS.md · Runtime 会话队列

Runtime 会话循环用结构化执行替代旧的单动作 ACTION.md 队列。每个会话绑定一个 target 和一个 skill，支持优先级调度、超时、重试策略和路由元数据。

# Runtime Sessions

```yaml
version: runtime_sessions_v1
sessions:
  - session_id: sess_pick_apple_001
    goal_id: goal_pick_apple
    target_ref: target://franka_lab_a
    skill_ref: skill://rekep_grasp
    task_description: "pick up the red apple on the table"
    status: pending
    priority: high
    timeouts:
      queue_timeout_s: 30
      execute_timeout_s: 120
      policy_timeout_s: 5
    retry:
      max_retries: 1
      attempted: 0
    routing:
      policy_endpoint: dummy://local
      adapter: franka_real_adapter
```

TARGETS.md · Runtime Target 注册表

声明可用的 rollout target（仿真、真机），包含感知配置、适配器选择和 skill 兼容性。Target 的观测和动作维度在 config 中声明。

# Runtime Targets

```yaml
version: runtime_target_registry_v1
targets:
  - id: dummy_sim
    type: sim
    backend: dummy
    enabled: true
    workspace: workspaces/dummy_sim
    supported_skills:
      - openpi_sim_vla
    adapter: dummy_openpi_adapter
    perception:
      enabled: false
      strict_preflight: true
      sensor_config_ref: configs/runtime/sensors/dummy_sim.sensors.yaml
      perception_config_ref: configs/runtime/perception/dummy_sim.perception.yaml
    config:
      success_after_steps: 3
      observation:
        image_size: 16
        state_dim: 8
      action:
        action_dim: 7
        chunk_size: 4
```

SKILLS.md · Runtime Skill 注册表

Skill 声明自己需要什么（传感器、环境输出）以及由哪个 runtime 处理执行。Skill 不选择感知插件——runtime 从感知配置中解析。

# Runtime Skills

```yaml
version: runtime_skill_registry_v1
skills:
  - id: openpi_sim_vla
    category: vla
    runtime: OpenPISimSkillRuntime
    supported_target_types:
      - sim
    policy_client: dummy
    supports_chunk: true
    default_replan_every: 4
    requires:
      sensors: []
      environment_outputs: []
      strict_environment_contract: true
```

ORCHESTRATOR.md · 全局仪表盘 下一个版本更新

多机协同时的"总控台"。不存动作细节，只汇总总体进度、活跃设备和关键决策。

# Orchestrator Status

## Current Mission
Pick up the red apple from the table and place it into the blue basket.

## Progress
2/5 sub-tasks completed (40%)

## Active Devices
- go2_edu_001: navigating_to_kitchen
- franka_001: idle_awaiting_next_action

## Issues
- None

## Decision Log
- [10:05] Assigned T1 to go2_edu_001 because it has the locomotion capability.
- [10:12] Assigned T3 to franka_001 after apple was confirmed in scene_graph.

谁读谁写 · 一张表搞定