d-robotics 244d19dd5b feat: 板端最小 runtime + 文档三件套(INTERFACE/MIGRATION/DEPLOY)
- scripts/pack_board.sh: 装配 payload(23 文件 18M:大脑+网页+SPINE-B+clips),
  MANIFEST sha256 板上校验演练通过;--with-wheels 可选
- docs/INTERFACE.md: 9 项依赖契约 + 环境变量契约 + 端口 + 已知问题
- docs/UPSTREAM_MIGRATION.md: 上游升级 SOP(探测→接口面核对→subtree pull→
  恢复 meshes/checkpoints→verify→tag→pack)
- docs/DEPLOY_BOARD.md: 手动 scp 交接流程(含可变状态回捞、回滚、一次性清理)

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-08 19:00:52 +08:00

4.0 KiB
Raw Permalink Blame History

INTERFACE — 上下游依赖契约

本文件是"上游升级不翻车"的锚点:下游对上游 HoloMotion 的全部依赖都在这张表里。 升级前逐行核对,升级后跑 bash scripts/verify_stack.sh 全绿即迁移完成。

1. 文件级依赖(下游 → upstream/)

# 下游消费者 依赖的上游文件 用途 破坏后果
1 console/robot_service/service.py checkpoints/.../velocity_model.onnx WALK 推理 + meta 服务起不来
2 〃 checkpoints/.../model_16200.onnx DANCE 推理(KV cache) 〃
3 〃 checkpoints/.../config.yaml 动作跟踪 obs 配置(dof_names) DANCE 崩
4 console/robot_service/net_harness_body.py holomotion.src.evaluation.eval_mujoco_sim2sim(MujocoEvaluator/process_config) 仿真机体 = 官方物理 + PD 机体起不来
5 〃 velocity_model.onnx 仅读 meta(关节名/默认位姿映射) 〃
6 〃 assets/.../29dof/scene_29dof.xml 默认平地场景(板端实证配置) 〃
7 console/robot_service/obs_builder_np.py 源码移植自 holomotion/src/evaluation/obs/obs_builder.py numpy 版 obs 构建 对拍门红(升级必查)
8 console/spine_v2/spine.py velocity_model.onnx 仅首次读安全位姿→缓存 spine_safe.json 一次性 bootstrap
9 scenes/*.xml <include> 上游 g1_29dof.xml + G1/meshes(经 meshdir 覆盖) 自建多物体/斜坡场景 场景加载失败

checkpoints/ 与 upstream/thirdparties/HoloMotion_assets/(89M meshes)不在 git 里: 本机经仓库根软链取自旧工作区;板子用自己的 $BD/HoloMotion/checkpoints。 git subtree pull 永远不会带这两处内容——升级 SOP 里有对应的恢复步骤。

2. 环境变量契约

变量 A 机(本机)默认 板端(B)值 谁消费
RS_CKPT_DIR <repo>/checkpoints(软链) $BD/HoloMotion/checkpoints service / spine / 机体
RS_CLIPS_DIRS <repo>/clips $BD/clips:$BD/clips/y26p:$BD/clips/motion_data service / web_remote
RS_TEL_URI tcp://127.0.0.1:5572 同左(SPINE-B 转发) service / web_remote
RS_UPSTREAM <repo>/upstream 不存在(板端 payload 无 upstream/) 仅 A 机进程
RS_SCENE 上游 scene_29dof.xml(平地) 不存在 仅 A 机进程
RS_OBS_FAST 1 1 service
RS_ORT_THREADS 0(ORT 默认) 2(钉核 16-17) service
SPINE_ROLE / SPINE_PEER_IP A / 板 IP B / A 机 IP spine
CONSOLE_PY $HOME/miniconda3/envs/holomotion_train/bin/python 板上脚本内写死 $BD python run_*.sh

规则:service / web_remote / spine 在 import 期不得访问 RS_UPSTREAM / RS_SCENE 指向的内容(板端没有这两样),路径对象构造除外。

conda 环境:A 机 holomotion_train,板子 holomotion(/root/ssd/miniconda3/envs/)。

3. 网络端口

5571 cmd SUB(service 绑)· 5572 遥测 PUB(机体绑,SPINE-B 在板端转发) · 5573 目标 PUB(service 绑,CONFLATE)· 5574 状态 PUB(service 绑) · 5575 机位 SUB(机体绑,网页→A 机)· 8877 网页 HTTP(板端 web_remote)

4. 已知问题(如实记录)

  • 模式 1 WALK→DANCE 间歇性摔倒(~7 跑 3 摔,2026-10-08 实测):入混合从行进间 切舞蹈时偶发。摔倒探测器(tests/smoke_local.py 持续低位判定)能捕获。板端 SPINE 链路下未复现该统计。属既有行为,非本仓库化引入。
  • 板端 $BD/robot_service/net_harness_body.py 是陈旧漂移副本(该文件仅 A 机运行); 切换本仓库 payload 后可删除。
  • RS_G1_DIR 由板端脚本导出但当前无 .py 消费者(本机+板端 grep 双侧确认); 保留导出以防板端布局依赖,消费方出现前不要清理 $BD/g1_assets。
  • 板端 spine.py 常驻进程 RSS ~14.8G(53% 内存)异常,见旧工作区 net_probe/ 诊断记录,建议单独立项。