PhyAgentOS Benchmarking Architecture

1 · Architectural Boundary

Agent skill 负责“如何评测”；SkillRuntime 负责“如何执行策略”

benchmarking · Agent Skill

PhyAgentOS/skills/benchmarking/SKILL.md

进入 Agent skills summary，按需加载 Markdown 指令。
选择 target / policy skillruntime，发现 task list。
创建 pending sessions，等待标准 Runtime 回写。
聚合日志与 artifacts，计算指标并撰写报告。

≠

Policy SkillRuntime · Runtime Executor

SKILLRUNTIME.md → runtime_kind: policy

实现 policy closed loop、observation/action contract。
由 SessionRunner 与 WatchdogSupervisor 调度。
连接 target、policy client、adapter 与 safety bridge。
产出 SessionResult，不负责评测实验编排。

关键边界：Benchmarking 不新增 SKILLRUNTIME.md 条目，也不直接实例化 SessionRunner。它通过现有 session 协议复用 Runtime 的执行与回写能力。

2 · Runtime-Aware Availability Gate

控制“技能是否可见”，不替代 Runtime preflight

ContextBuilder

传入 workspace、独立 runtime_workspace、runtime_enabled 和 target enabled overrides。

construct

SkillsLoader._check_runtime_requirement()

① Runtime 模式enabled == true配置关闭时立即不可用。

② Simulation Targettarget_kind: simulation读取 runtime workspace 的 TARGETS.md。

③ Target 已启用enabled: true应用 runtime_target_enabled 覆盖。

④ Policy 可连接supported ∩ policy IDs必须支持真实存在的 policy skillruntime。

visibility

available=true
出现在 skills summary，可被 Agent 按需读取。

available=false
summary 显示具体 Runtime 缺失原因。

声明入口：requires.runtime = { enabled: true, target_kind: "simulation", skillruntime_kind: "policy" }。若 TARGETS.md 或 SKILLRUNTIME.md 缺失/无效，技能保持不可用。

3 · Benchmark Lifecycle

Agent 编排 → Runtime 执行 → Agent 汇总

1Load Protocol

读取 RUNTIME、TARGETS、SKILLRUNTIME、SESSIONS、LOG。

2Select Pair

选择 enabled simulation target 与其支持的 policy skillruntime。

3Discover Tasks

优先调用 target.describe 获取 task_list；失败时回退静态 config。

4Compile Sessions

按 task × init-state 生成唯一 pending session，保留既有记录。

5Execute

Watchdog claim、preflight、SessionRunner、policy loop。

6Write Back

回写 SessionResult、LOG.md 和每个 episode artifact。

7Report

聚合成功率、steps、reward、错误分布，生成论文风格报告。

Agent Control Plane ↑　　文件协议 / TargetWS RPC　　Runtime Execution Plane ↓

SESSIONS.md

status: pending
target_ref · skillruntime_ref · task_description · routing · execution

→

WatchdogSupervisor

claim → health/preflight → running → finalizing；拒绝不兼容组合。

→

SessionRunner

target lifecycle + policy inference + adapter/bridge + execution status。

→

ResultWriter

SessionResult → episode.json → LOG.md → SESSIONS.md final state。

4 · Evidence Aggregation

按字段优先级读取，避免从文本日志猜测结果

SESSIONS.md

最终 status、result.success、num_steps、return_value、artifact_dir、error_code。

LOG.md

按 session_id 索引的历史摘要、目标、状态、延迟、错误和 artifact 路径。

episode.json

benchmark、task/init-state、success、reward、steps、chunks 和 metadata。

Σ

Run-Level Metrics

Success Ratesuccesses / total episodes

Per-Task SRgroup by task_id

Step Statisticsmean + median completed steps

Reward / Returnmean when available

Status Countsfailed · timed_out · rejected · cancelled

Error Taxonomyerror_code frequency + examples

字段优先级：episode.json["benchmark"] → result.metadata.final_status → session-level result。静态 task discovery 或缺失指标必须在报告中显式披露。

5 · Experiment Report Contract

benchmark-aware，而不是固定模板堆砌

Recommended Report Structure

Setuptarget、policy、endpoint、runtime config

Benchmarksuite、task split、init states、task source

Metrics成功定义、聚合口径、缺失值处理

Results总体表、per-task 表、steps/reward

Failures状态分布、error_code、代表案例

Artifactssession IDs、episode paths、logs

Reproducemax_steps、replan、timeouts、版本

Discussion与对应 simulation 论文口径对齐

Reporting Invariants

1

保持原始证据不可变报告只引用和汇总，不覆盖 runtime 日志与 episode artifacts。

2

记录任务来源区分 live target.describe 与 TARGETS.md 静态回退。

3

区分失败类型policy failure、timeout、preflight rejection 不应混为普通 task failure。

4

对齐论文口径如 LIBERO 报告 suite、task、init-state 和 success-rate 聚合方式。

6 · Source Map

图中行为对应当前代码与协议文件

agent/skills.py解析 metadata、检查 runtime requirements、输出 availability。

agent/context.py传递 agent/runtime workspace 与 runtime enable overrides。

skills/benchmarking/SKILL.md定义 discovery、session construction、aggregation 和 report workflow。

runtime/watchdog/supervisor.pysession claim、preflight、execution、final state。

runtime/artifacts/episode_writer.py将 benchmark episode summary 提升到 episode.json。