Micro-AEC Benchmark — 评分与答题卡代码包

本目录是论文配套的基准核心代码：答题卡（episode bank）生成规则与 PDF、 三个验证设置（structured-observation / image-observation / execution）的确定性评分规则、 以及厂商中性的机械臂执行接口。不包含 Gazebo 与实机控制代码。

目录结构

code/
├── cards/                                   # 答题卡成品
│   ├── Micro_AEC_R_v2_seed_manifest.json    # 主题库 50 题 (5 族 × 5 任务型 × 2 难度)
│   ├── Micro_AEC_R_v2_逐题搭建卡_行为树_seed版.pdf  # 逐题答题卡 PDF (布局/真值/行为树)
│   ├── Micro_AEC_R_v2_episode_bank_and_materials.xlsx  # 题库与物料清单
│   └── micro_aec_r_seed02_cards.pdf         # 多 seed 变体答题卡样例
├── micro_aec_r/                             # 答题卡计算规则 (生成器)
│   ├── run_generate.py                      # 入口: 生成题库 + 答题卡 PDF
│   └── src/
│       ├── generator.py                     # 题目生成 (受控随机扰动)
│       ├── solver.py                        # 可解性求解器 (∃π 终态满足 g)
│       ├── behavior_tree.py                 # GEN_BT 行为树校验与参考计划模拟
│       ├── templates.py                     # F1–F5 × T1–T5 题目模板
│       ├── state_logic.py / domain.py / types_core.py / geometry.py
│       ├── card_exporter.py / pdf_renderer.py   # 答题卡 MD/PDF 渲染
│       ├── manifest_io.py / material_counter.py / audit_report.py
└── Core/
    ├── common/
    │   ├── episode_loader.py                # 题库加载 (seed{NN} manifest)
    │   ├── plan_simulator.py                # 计划确定性模拟 (CE6/CE7 依据)
    │   └── coord_transform.py               # 网格↔机器人坐标 + 可达性掩膜
    ├── episode_bank/seed02/                 # episode_loader 可直接加载的样例题库
    ├── Sim/scripts/                         # O/V 评分规则
    │   ├── metrics_original_aligned.py      # 论文口径: Aggregate=0.4·JQ+0.6·CE (CE1–CE7)
    │   ├── metrics.py                       # 早期口径 (保留备查, 论文不采用)
    │   ├── score_grounding.py               # 真实照片接地评分 (exact/within-1/格距/库存)
    │   ├── run_final_baselines.py           # 正式基线运行入口 (B0..B6)
    │   ├── baseline_registry_final.py       # 论文基线名册 (主表/附录归属)
    │   └── baseline_registry_corrected.py   # 审计修正版基线实现
    └── Real/
        ├── configs/workspace.json           # 工作区标定 (前缘参考系/TCP/夹爪参数)
        └── scripts/
            ├── arm_interface.py             # ★ 通用机械臂控制接口 (厂商中性)
            ├── score_track_p.py             # ★ Track P 评分 (论文口径, 后端中性)
            └── kinematic_sim.py             # 纯运动学模拟器 (无 Gazebo 依赖)

评分规则与论文的对应

论文	本包
Eq. (12)–(14): Aggregate = 0.4×JQ + 0.6×CE, CE = Σ wₖ·CEₖ	Core/Sim/scripts/metrics_original_aligned.py
附录 A: CE1–CE7 权重与判分逻辑	同上 (compute_metrics_aligned)
Eq. (15)–(17): Coverage / CES / CAS	Core/Real/scripts/score_track_p.py
Table 5: 接地指标 (exact-cell / within-1 / mean cell error / inventory P-R)	Core/Sim/scripts/score_grounding.py
3.5 节: 题库六元组 e=(f,m,d,s₀,u,g) 与 GEN_BT 可解性验证	micro_aec_r/src/{generator,solver,behavior_tree}.py
3.4 节: 网格→机器人坐标映射 φ 与可达性掩膜 R	Core/common/coord_transform.py

• structured-observation / image-observation 设置：两设置共用同一评分器， 对模型输出的 service-request JSON 调用 compute_metrics_aligned(request_json, episode_raw, track="O"|"V")。
• execution 设置 (Track P)：score_track_p.py 离线为各 source 的计划评分， 并聚合 Coverage/CES/CAS；执行侧统计 (phase 成功率) 从任意后端写出的 summary.json 读取，与具体机械臂/模拟器无关。

通用机械臂接口 (Track P, 无 Gazebo / 无实机 SDK)

Core/Real/scripts/arm_interface.py 提供：

• ArmInterface：抽象基类，仅三个动作原语 move_to_pose(position_m, orientation_xyzw) / gripper_open(speed) / gripper_grasp(width, speed, force, epsilon_outer)。 接任意真实机械臂或模拟器时实现该类即可。
• PlanExecutor：审计版九阶段拾放序列 (open → approach → descend → grasp → lift → transit → descend → release → lift)， 执行前强制可达性掩膜检查，坐标链经 workspace.json 前缘参考系。
• LoggingArm：dry-run 实现（只记录指令，不产生运动）， execute_plan_dry_run(episode) 一行即可演练任意题目的参考计划。

from Core.common.episode_loader import load_all_seeds, episode_by_id
from Core.Real.scripts.arm_interface import execute_plan_dry_run

eps = load_all_seeds("Core/episode_bank")
result = execute_plan_dry_run(episode_by_id(eps, "R-F1-T1-E-S02"))
print(len(result["dry_run_commands"]), "commands")

答题卡生成

# 在 code/ 目录下 (依赖: matplotlib)
python -m micro_aec_r.run_generate --sigmas 7 --output-root outputs
# 产物: outputs/seed07/micro_aec_r_seed07_manifest.json + ..._cards.pdf
# 可一次生成多个变体: --sigmas 7 8 9; 加 --strict-schema 启用严格校验

主题库（论文所用 σ=1 固定题库）的成品为 cards/Micro_AEC_R_v2_seed_manifest.json 与逐题搭建卡 PDF；多 seed 变体由同一生成器在不同 seed 下产出。

依赖

Python ≥ 3.10；matplotlib（答题卡 PDF 渲染、运动学模拟可视化）、 numpy + scipy（仅 score_grounding.py 的匈牙利匹配）。 评分核心 (metrics_original_aligned.py / plan_simulator.py) 仅用标准库。