API 使用 / Runtime 会话

Runtime 会话循环 进阶

SESSIONS.md → WatchdogSupervisor → SkillRuntime → Target → Artifacts —— 以会话为中心的执行管线。

Runtime vs HAL：两条执行路径

PhyAgentOS 提供两条执行路径。HAL 路径更简单，面向单一动作；Runtime 路径更结构化，面向会话，并增加了优先级调度、预检和感知管线。

特性HAL 路径Runtime 路径
队列格式ACTION.md（单一动作）SESSIONS.md（会话队列）
执行器hal_watchdog.pyWatchdogSupervisor + run_runtime_watchdog.py
调度策略仅 FIFO基于优先级（high / normal / low）
预检机制基本严格：传感器校准、schema 校验
感知管线未集成内置插件管线
产物输出内联于 ACTION.mdepisode.json + LOG.md
适用场景简单动作执行带可观测性的结构化 rollout

SESSIONS.md 详解

SESSIONS.md 使用类似 YAML frontmatter 的会话格式。每个会话包含优先级、超时、重试和路由字段。

## session_001 priority: high queue_timeout: 300 execute_timeout: 600 policy_timeout: 30 max_retries: 3 attempted: 1 policy_endpoint: builtin adapter: simulation status: queued instruction: "navigate to the table and pick up the red cube"
字段说明
priorityhigh → normal → low。高优先级会话先执行。同优先级按文件顺序。
queue_timeout会话在队列中等待的最长秒数，超时后标记为 timeout。
execute_timeout整个会话执行的最长秒数（包含所有步骤和重试）。
policy_timeout单次策略推理调用的最长秒数。
max_retries最大重试次数，计数器在 attempted 字段中跟踪。
policy_endpoint策略运行位置：builtin、remote 或自定义适配器名称。
adapter执行目标适配器（映射到 TargetAdapter 实例）。
status当前状态：queued、running、completed、failed、timeout、rejected。

初始化 Runtime 工作区

Runtime 工作区必须先初始化，Watchdog 才能处理会话。使用初始化脚本生成所有必需文件。

python scripts/init_runtime_workspace.py --workspace /tmp/test

生成的文件：

文件用途
TARGETS.md注册可用执行目标（模拟器、真机），包括其能力和感知配置。
SKILLS.md每个目标已声明的技能，包括传感器需求和策略端点。
SESSIONS.md会话队列。初始为空，由 Agent 或手动填充。
LOG.md执行日志，包含每个会话的结果（状态、步数、返回值）。
configs/runtime/sensors/*.yaml传感器配置文件，定义可用传感器及其通道。
configs/runtime/perception/*.yaml感知管线配置：预处理器、模型、后处理器。

运行 Runtime Watchdog

Runtime Watchdog 轮询 SESSIONS.md，将会话分派给 WatchdogSupervisor，并记录执行结果。

单次执行（--once）

python run_runtime_watchdog.py \ --workspace /tmp/test \ --once

持续轮询

python run_runtime_watchdog.py \ --workspace /tmp/test \ --environment-workspace /tmp/env

每个会话执行后的预期产出：

  • SESSIONS.md 状态更新为 completed、failed 或 timeout
  • LOG.md 追加记录，包含 session_id、target_id、status、num_steps 和 return_value
  • artifacts/runtime/<session_id>/episode.json 创建完整执行轨迹
使用 --environment-workspace 将 ENVIRONMENT.md v2 写入单独目录，使环境观测与 Runtime 会话状态解耦。

感知插件管道

在 TARGETS.md 中设置 perception.enabled: true 会在任何会话执行前触发严格的传感器和感知 YAML 配置预检。

预检机制

验证传感器可用性、标定文件路径和观测 schema。任一条件不满足则快速失败。

插件管道

预检通过后运行。串联传感器读取器、预处理器、模型推理和后处理器。

管道输出：环境工作区中的 ENVIRONMENT.md v2，包含结构化观测数据。

常见失败原因修复
missing sensor_config_refSKILLS.md 引用了 configs/runtime/sensors/ 中未定义的传感器添加缺失的传感器 YAML 或修正引用
missing observation channel传感器配置声明的通道驱动并未暴露将传感器配置通道与驱动输出对齐
dtype/shape mismatch感知模型期望的张量形状与传感器输出不匹配添加预处理器对传感器输出进行 reshape/downscale

执行结果解读

每个完成的会话生成结构化产物，用于调试、评估和回放。

LOG.md 格式

| session_id | target_id | status | num_steps | return_value | |------------|-----------|---------|-----------|--------------| | sess_001 | sim_01 | completed | 12 | 0.87 | | sess_002 | sim_01 | failed | 3 | 0.12 |

episode.json 结构

{ "session_id": "sess_001", "target_id": "sim_01", "status": "completed", "steps": [ { "step": 0, "observation": {...}, "action": {...}, "reward": 0.5, "next_observation": {...} } ], "return_value": 0.87, "metadata": { "start_time": "...", "end_time": "...", "retries": 0 } }

artifacts 目录结构：

artifacts/runtime/ ├── sess_001/ │ └── episode.json ├── sess_002/ │ └── episode.json └── latest -> sess_002/

按步骤启用感知

感知默认禁用。通过 TARGETS.md 启用并确保所有必需配置就位。

  1. 设置 TARGETS.md perception.enabled 为 true
    ## sim_01 type: simulation perception: enabled: true sensor_config_ref: sim_rgbd perception_config_ref: sim_basic
  2. 在 SKILLS.md 中添加传感器需求

    每个技能必须声明需要的传感器。例如：pick_up 需要 rgb 和 depth 通道。

  3. 确保 sensor/perception YAML 配置存在
    ls configs/runtime/sensors/sim_rgbd.yaml ls configs/runtime/perception/sim_basic.yaml
  4. 带 --environment-workspace 运行 Watchdog
    python run_runtime_watchdog.py \ --workspace /tmp/test \ --environment-workspace /tmp/env
  5. 验证 ENVIRONMENT.md 出现
    cat /tmp/env/ENVIRONMENT.md

    如果为空或不存在，检查预检输出的错误信息。

干运行校验：设置 perception.enabled: true 但以 --once --dry-run 运行 Watchdog，可在不实际执行会话的情况下验证配置管线。
Runtime 会话循环是 PhyAgentOS 未来的执行主干。HAL 模式在简单动作执行场景下仍然可用；Runtime 模式为生产级 rollout 增加了结构化、可观测性和感知能力。