Artifacts 与数据契约

最后更新：2026-07-24。

本页负责 canonical input/output 与 provenance 契约，不定义实验成功阈值。指标解释见 评测策略。

输入

Artifact	责任	权威来源
task_plan.json	semantic steps、object role、target、active hand	task generation / validated task
layout_*.json	scene object identity、pose、mesh source、support geometry	SAGE scene
reference assets	reusable motion priors/keyframes	data/hsi_primitives/backend_motion_priors/

required field 缺失应立即报错，不填默认 task/object 语义。

motion.npz

canonical motion 的精确 field set 可随 multi-object/action support 扩展，但遵守以下 invariant：

• frame-aligned human root/body/hand motion；
• dynamic_object_id 或多对象 dynamic_object_ids；
• 对应 dynamic_object*_pos 与 dynamic_object*_rot_mat；
• source/timeline/task-stage metadata；
• scene_origin_xy 等 consumer 所需 coordinate metadata；
• 不含 dynamic_object*_vertices、dynamic_object*_faces 或 source-mesh 路径。

多对象通过稳定 field token 区分，例如：

dynamic_object_field_tokens
dynamic_object_<token>_id
dynamic_object_<token>_pos
dynamic_object_<token>_rot_mat

单对象兼容 field 可以存在，但 consumer 不得猜 mesh。实际 object mesh 始终在消费边界通过 layout_json + object_id 加载。

Case-root outputs

文件	语义	是否可作运行时输入
motion.npz	canonical motion/data input	是
validation.json	gate、failure reason 与 telemetry availability	只用于调度/审计
pipeline_manifest.json	config、stage timing、artifact provenance	否，不作为 state bus
kinematic_video.mp4	temporal/visual QA	否

Manifest 原则

manifest 可以记录：

• resolved input path；
• execution plan 与 anchor summary；
• stage timing/status；
• canonical artifact path；
• validation/render summary；
• source hash 与环境 provenance。

manifest 不应：

• 让下一个 Python stage 通过扫描 manifest 发现运行时对象；
• 替代函数参数或 return value；
• 保存 object mesh 作为 canonical data；
• 在缺失必需输入时提供隐式默认。

Teacher rollout 目标契约

尚未冻结。最低需要：

• case/scene/motion/body-shape identity；
• state、action、object pose/velocity、contact；
• reference visibility 与 goal mask；
• episode/seed/termination/failure；
• checkpoint/config/hash provenance。

该 schema 在首个 multi-seed teacher 通过前保持“待验证”，不得在 motion.npz 中提前塞入 simulator-specific 大数组。