- 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>
4.0 KiB
4.0 KiB
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/诊断记录,建议单独立项。