v0.12.0 — OriEra Engine

v0.12.0-embodied-crate — 具身独立 crate × 七预设 × 幽灵夹持破除 × 深度数据链治废

v0.12.0-embodied-crate — Embodied Crate Split × Seven Presets × Ghost-Grip Breaker × Depth Data Integrity

日期 / Date: 2026-11-07 · 范围 / Scope: PR #174–#179 + 0ef51c6/8a4722e（PLAN-embodied-v3 P2 深水区两波 + L9 crate 拆分 + 三波收尾；v0.11.0 → 0.12.0）

为什么升级 / Why

v0.11.0 给世界装上了手臂；v0.12.0 把手臂从认知层里拆成独立 crate、把官方预设
扩到七个、用新落地的失败相位遥测找到并破除了 Panda 抓取那 20% 失败背后的
接触层幽灵，并堵住了一个会悄悄毁掉深度数据的转换器漏洞。全部改动在金标锚
（contracts/golden/）逐集相等、LeRobot v2.1 输出逐字节冻结的前提下完成。

0.11.0 gave the world arms; 0.12.0 moves them into their own crate
(oriera-embodied), grows the official preset library to seven, uses the new
failure-phase telemetry to find and break the contact-layer ghost grip
behind Panda's residual 20% failures, and closes a converter hole that was
silently destroying depth data. Every change lands with the golden anchors
episode-equal and LeRobot v2.1 output byte-frozen.

架构 / Architecture（#175, #176, ADR 0004）

	前 / Before	后 / After
oriera-agent	17,611 行：认知层 + 五期堆叠的具身运行时混居	4,772 行：纯认知（cognition / memory / story / genai 桥 / PyO3 认知桥）
oriera-embodied（新）	—	12,904 行 src + 2,380 行 tests + specs/**：embodied_env / spec / urdf / meshres / lerobot / eval / ik / manifest
oriera-wasm	→ oriera-agent（浏览器 bundle 被迫拖上认知层）	→ oriera-embodied（bundle 甩掉认知层）

• 兼容层 / Compat：oriera_agent::embodied_env::* 等全部历史路径经 8 条 feature 门控
  pub use 继续解析，外部零改动；build_info() receipts 逐字节不变。新代码请直接依赖
  oriera-embodied。
• 纯移动硬证据 / Pure-move proof：git 按 92–100% 相似度配对 38 个 rename；金标
  三口径 + pre-m0a 连续性 12/12 逐集相等；全仓 #[test] 计数 234 = 234。
• 路径搬迁 / Path migration：crates/oriera-agent/specs → crates/oriera-embodied/specs
  （29 文件同步，gen_spec_index --check / sync-resolved --check 零漂移）。

七预设 / Seven official presets

预设	course@v1	paper@v1	本版变化
tabletop-4dof-pick	11/12 = 91.7%（金标锚）	—	逐位不变
panda-7dof-pick	10/12 → 12/12	80/100 → 95/100（Wilson [88.8, 97.8]）	幽灵夹持破除器（#179）
panda-contact-criterion（新官方）	12/12	95/100	lab → official 升格（#178）；判据=双板法向力 ≥1 N ∧ 滑速 ≤0.05 m/s
stack-4dof	11/12	—	渲染 props[1..] 修齐
bin-pick-4dof	12/12	—	真料箱 fixture
drawer-4dof-v2	12/12	—	kernel.js 抽屉相位机（页面「▶」可拉开抽屉）
mobile-arm-4dof	12/12	—	目标圈贴地修复

Panda 幽灵夹持（ghost grip）/ P2-Wave-3B：Wave-1 遥测实锤 20 个 paper 失败集全在 lift
相位、方块抬升量恒为 0；逐 tick 复盘到 rapier 接触层——板↔方块碰撞对在接近姿态创建时
流形冻结于推测接触点，回收预算放大到 5 cm，21 mm 闭爪扫掠永远跨不过，求解器输出恰好 0 N。
唯一有效的是杀掉碰撞对再重生：检测到首段抬升 8 tick 内抬升 <4 mm → 开爪上撤 8 cm
（碰撞对在 broad-phase 消亡）→ 驻留 → 降回同一组 ±z 面 → 全力重闭 → 40 tick 挤压沉降
再竖直抬升。机制只在 heavy（≥6 DoF）路径启用：tabletop 与 HEAD 二进制 12 集逐字段全等、
mobile-arm 12 集全等、金标 no drift。残余 5 集（seeds 132091/197645/197647/197660/525382）
入档；试过无效已撤：重闭斜坡、检测延后到 16 tick、水平偏航撤离。

Contact 判据升官方 / Contact criterion promoted：同 seeds 两口径逐集对照成功翻转 0、
steps 差 0、transitions 全等；失败集 reward +9…+22 = TipRadius 在预接触/放置尾窗发假
「夹住」标签的物理修正量化（U-6 设计目的）。幽灵夹持的 5 个残余集在 Contact 口径下归
grasp（0 N 不认夹住）而非 lift——判据把归因落到了正确相位。

数据链治废 / Data-pipeline integrity（#177 D 包，真 lerobot 0.7.0 端到端验证）

• 🔴 深度数据毁灭 bug 修复：v3 转换器曾把 u16 毫米深度 PNG 压成 8-bit H.264 mp4
  （实测最大值 1451 mm → 8，不可逆，原 PNG 被删）→ 改为 PNG 原字节嵌入 parquet Image()
  列，深度 stats 形状 (1,1,1) 补算。
• v3 深度元数据：names [height,width,channels] + is_depth_map: true + depth_unit: "mm"
  • 逐集 4 指针列；幻影零帧 RGB 特征（曾让 v2.1 selfcheck 失败）清除；tasks.parquet
    无 pandas 时手写索引（lerobot 曾把任务全读成 "0"）；names: null 崩 lerobot-train 修复。
• add_camera_channels 契约 API：depth-only 相机只声明、只落深度轨，误送 RGB 帧报错。
• CI 分层：a 层 emulate（纯 pyarrow 复刻 lerobot 0.7.0 读取路径）进 data-pipeline
  PR 门禁；b 层 lerobot-loader（torch CPU + lerobot 0.7.0 钉版，HF_HUB_OFFLINE=1）
  夜间 / 手动 dispatch。selfcheck 对账项 57 → 63 / 85 / 75。
• LeRobot v2.1 输出按 FeatureDialect 冻结逐字节不动；npz == v2.1 == v3.0 三格式逐位一致。

遥测 × 物理 × 渲染 / Telemetry × physics × rendering

• failure_phase@v1：reach / grasp / lift / place 四相位分类器，--failure-phases
  接 baseline 与 collect 两入口（默认路径逐字节不变），aggregate / plot 出
  fail_* 列与 failure_phases.csv/.png。
• LinkShape::Ball 直通 rapier Ball（identity tag 5，旧 hash 不动）+ URDF <sphere>
  直通（原映射为 Box 包络）+ pinhole 渲染球体；mount_rpy 底座朝向链（零值逐位走旧路径，
  FK 一致性 3.6e-7 m）；坑位警告第三坑可判并给修正 yaw。
• 渲染三入口修齐：kernel.js 形状字段读法 bug（props[1..] 全画成默认小方块）根治、
  propGeom 按 spec 真形状建几何；pinhole 悬空目标盘改落 goal_marker() 支撑面；
  legacy 俯视轨补画 fixtures。守卫 10 项含反向验证（改回旧逻辑守卫变红）。
• 只读接触探针 API（plate_force_on / debug_plate_state / 碰撞对检视）入 rigid3d / env。
• kernel.js：抽屉相位机（drawer@v2 页面真跑 max_pull 0.087 m ≥ 0.08）、任务面板按 spec
  task.id + params 渲染、?policy=wasm 下 drawer 的 policySource 如实报 js-phases、
  tools/wasm_golden_check.mjs --policy js 内置 three 解析钩子开箱可跑。
• 夜间慢测试腿 embodied-slow（schedule 03:23 UTC，三件 #[ignore = "slow: …"]
  物理长跑不进 PR 门禁，30 min 硬顶）。

门面 / Facade

• assets/hero.gif 重录：具身仿真台脚本策略真跑抓放一集（640×387 · 14 s）。
• Pages 索引卡补 14 影游内核 / 15 具身仿真台（01–15 齐）；独立页与 Studio 卡片墙
  均七卡对齐（drawer 指 v2，v1 为对照档案不下墙）。
• Studio：卡片墙 5 → 7，vendored lerobot.rs 外科同步（669 → 2,398 行，零 engine 导入，
  v2.1 逐字节冻结），build-release.cmd msvc-local 自动探测 + ASCII-only 约定。

兼容性 / Compatibility

• 不破坏：oriera_agent::{embodied_env,spec,eval,lerobot,urdf,meshres,ik,manifest}
  路径全部可用；所有官方预设 spec_hash 不变；金标 contracts/golden/** 不变；
  results/reference/{b5535a74,95f75626}/ 因 Panda 策略升级而重写（双跑逐集位同），
  其余预设 reference 不变。
• 建议：新代码改依赖 oriera-embodied（oriera-wasm 已切）；
  pip install oriera-sim==0.12.0；LeRobot 相机数据集请走 v3（v2.1 的 names: null
  与帧目录形式按冻结约定保留，lerobot 0.3.x 训练相机集仍会崩）。
• 发版 SOP：docs/OPEN_SOURCE_GUIDE.md §9（本版起英文版 §9 同步）。