主题
Python 包、workspace 和运行环境
首次使用按安装与准备操作。本文用于维护包边界、依赖和锁文件。
本项目以 uv 管理 Python、依赖、锁文件与运行入口,以 prek 做本地提交检查。公开命令按当前职责定义,模型、资产和任务产物保持可追溯。
环境与锁文件
当前模块职责和依赖方向由架构入口维护。包名、依赖与 extras 从对应 pyproject.toml 读取,版本从所属锁文件读取。
| 环境 | 清单与锁文件 | 隔离原因 |
|---|---|---|
| 根 workspace | 根清单(pyproject.toml)、根 uv.lock;成员由 tool.uv.workspace.members 定义 | CLI、共享契约、NumPy runtime 与当前模型/网页应用共享可兼容依赖 |
| planning | 规划清单(backends/planning/pyproject.toml)、项目 uv.lock | 静态 IK/碰撞可独立运行,不要求物理引擎或 Torch |
| isaaclab | Lab 清单(backends/isaaclab/pyproject.toml)、项目 uv.lock | 使用匹配原生 Isaac Sim 的 bundled Python 与锁定引擎栈 |
| hardware | 硬件清单(backends/hardware/pyproject.toml)、项目 uv.lock | 厂家 SDK 只读采集依赖;Linux ARM64/x86_64 |
| learning | LeRobot 清单(backends/learning/pyproject.toml)、项目 uv.lock | 独立 LeRobot/Torch 栈,与 Lab 版本要求分离 |
| ROS 2 | backends/ros2/*/package.xml、原生 SDK/Servo/topic hardware 来源清单 | 系统 Python 与 ROS ABI,使用 colcon,不能伪装成 uv 项目 |
workspace 成员共享根环境和锁文件;独立 uv 项目通过 path sources 使用共享包。通用执行入口接收装配好的 Execution,通过 PhysicsSession 推进物理,通过 PolicyFactory 创建策略,不反向导入具体后端。
静态工作空间评估走独立 planning worker,不需要先安装物理引擎或 Torch。MPLib 仍使用已验证的 ARM64 wheel。MPLib wheel、补丁与来源位于 backends/planning/wheels / native;共享 ARM64 构建配方位于 packages/wheel-repairs。移动保持二进制及 SHA-256 不变。构建源只保留当前 cuSPARSELt 配方。
交互客户端位于 apps/workbench,React/TanStack Start/R3F/XState 依赖由 pnpm 锁定,Python 工作台使用 FastAPI/Pydantic/Uvicorn,并显式依赖 websockets 提供姿态流。客户端构建、许可证与输入输出哈希由 pride build workbench 生成;不再依赖 Viser wheel。来源见 THIRD_PARTY(apps/workbench/THIRD_PARTY.md)。
安装与日常运行
仓库 .python-version 选定 Python 3.12。workspace 的包保留 Python 3.11–3.12 范围;当前独立引擎和规划环境要求 3.12,Isaac Lab/规划锁文件限制 Linux ARM64。驱动和 Vulkan 仍由宿主提供。
uv sync 默认做精确同步,会移除本环境未选中的包。按需启用的 extra 在下次精确同步时需要继续带上。日常运行、检查与跨环境调度采用 uv 默认行为:uv run 按需更新锁文件并按所选包补齐环境;跨引擎依赖留在独立环境。
开发工具在 lint group,轻量测试依赖在 test group,默认 dev 组合这两个 group。基础 CLI/core 不安装 Rerun、Arrow、NumPy 或 gRPC。core 的 records extra 声明 RRD 依赖,rpc extra 声明 gRPC;runtime/server 显式选择两者,planning 只选择 rpc,hardware/learning 选择 records。开发 test group 装配 runtime/server,以运行跨模块轻量检查。
可选能力
独立 backends/learning 项目继续用于 LeRobot 桥接。learning、isaaclab 两个消费者声明共享 spark-wheel-compat 构建后端的 find-links。CAD 由 models 的 cad extra 提供,server 的 cad extra 显式消费它。
入口和数据根目录
公开应用入口为安装后的 pride。工作台、模型准备、离线记录、物理和规划的 _pride-* console entry point 仅用于跨环境调度;不提供同义的模块执行入口。
evaluate 在 server 环境编排,import-cad 直接选择 models;audit / diagnose 由根包的 records extra 和私有 _pride-records 执行入口承载,复用同一公开参数定义。基础命令发现不安装这些可选能力。
工作台类命令通过 exec 将公开 CLI 进程交给选定环境的应用,由应用处理 Ctrl+C 和退出归档,避免中间等待进程提前杀死仍在清理的会话。
数据根目录与包安装目录分离:CLI 的全局参数 --root 优先,其次 PRIDE_ROOT,否则从当前目录向上查找 pyproject.toml 的 [tool.pride]。包可以安装为普通 wheel;CAD、任务、配置和运行数据由显式的数据根目录提供,不打进 Python wheel。
跨环境通过 pride_core.project.uv_command 生成无 shell 的 uv 命令,通过 worker_env 传递数据根目录并清除其他项目的虚拟环境设置。ROS Launch 使用 uv_worker_command 先在该项目准备并解析已安装入口,再直接拥有 worker 的 PID;环境准备探针限时 60 秒,不将 uv 留在信号路径中。代码不拼接 .venv/bin/python,也不根据 site-packages 或源码目录的层数定位资产。
验证与更新
ty 覆盖 CLI、core、完整 runtime 及迁出的 server execution/client,包含 NumPy 感知和记录模块,不再设置后端 import 忽略。引擎与 GUI 绑定在对应环境通过运行和集成检查验证。
workspace 依赖变更更新根锁文件。共享包元数据变化时同步引用它的独立项目锁文件,不顺带升级第三方版本。实验 provenance 从所选项目的本地依赖闭包收集源码、包元数据、所属锁文件和本地 wheel;静态布局实验选择 workbench/planning(依赖闭包包含 models) 并包含共享包。历史运行仍使用保存的模型和轨迹读取,不能以旧运行的成功代替迁移后执行验证。
共享协议、校验和任务判据由 pride_core 提供;数值执行、感知与记录由 pride_runtime 提供。调用方直接依赖所属包,不通过重导出模块或命令别名访问。
pride-isaaclab 显式依赖 pride-planning,在自身环境导入共享 Pinocchio IK 和 Ruckig 轨迹模块; 静态评估仍启动独立 planning worker。MPLib 因此属于 isaaclab 的基础依赖闭包, Ruckig 固定 0.19.4,上游源包与哈希由各消费项目锁文件保存, ARM64 通过 uv 原生构建,无 site-packages 补丁。状态机 transitions 随策略归 runtime;core 声明 Pydantic v2 和用于边界 TypedDict 的 typing-extensions,元数据同步至所有消费环境锁文件。Pydantic Core 的原生 wheel 由锁文件固定。配置契约见配置设计。
Isaac Lab 环境使用锁定原生 Isaac Sim 的 bundled Python 创建独立 venv,再由 uv 同步;启动通过原生 python.sh 的有界探针取得官方环境,再以 exec 保持实际 worker PID,避免 shell 留在信号路径中;不修改安装目录。安装顺序见命令入口。原生版本清单作为 tool.pride.runtime-inputs 纳入 provenance;共享规划器只有 pride_planning 一处实现。
PhysX 与 Steel 原生遥操的 isaacsim、rclpy 和 ROS 消息包由上述原生运行时提供。Kit 先加载自己的 USD ABI,再安装仅约束 newton 包的导入器,固定到 Lab 锁定的 1.9.0.dev0;缺失模块直接报错,不回退至 Sim 内置 1.6.1。原生 Newton stage factory 的源码配方(backends/isaaclab/native/README.md)校验上游文件与补丁哈希,在 artifacts/native-newton/ 生成隔离扩展并记录输出哈希;配方纳入 Lab provenance。MuJoCo 历史路径仍使用系统 Jazzy、官方 JointStateTopicSystem 和外部 controller manager,其 deb、版本、哈希和提取文件由 backends/ros2/topic-hardware-runtime.json 固定,随 ROS 构建暂存至 artifacts。tool.pride.runtime-imports 按模块指向已声明的运行时清单,打包检查验证提供方路径;这些模块不冒充 PyPI 依赖,也不进入全局 import 忽略。网页键盘输入不再使用独立环境。
网页遥操的按键转换由 pride_workbench.sessions.teleop_input.keyboard_input 在服务进程内完成,只使用网页包已有的 NumPy/SciPy;不依赖 NVIDIA Capture、Torch 或仿真运行时,也不启动输入 worker。转换保留原有六轴键位、XYZ 组合旋转与归一化语义;ROS 侧继续负责速度限制、控制权与输入过期检查。来源记录包含转换代码、网页包清单、根锁文件及实际数值库版本。
ROS 业务事件和 launch 状态契约使用系统 Python 的独立 wheel 目录 artifacts/ros2/python,由 ROS 构建入口按 backends/ros2/recording-requirements.txt 的版本与哈希同步 Rerun SDK、Pydantic、gRPC 及其依赖。Pydantic 校验跨进程的启动与退出证据,避免系统 ROS Python 隐式依赖 workspace 环境。该目录只进入 ROS 子进程的搜索路径,不修改 /usr,也不混入 workspace 虚拟环境。原生诊断直接链接官方 Rerun C++ SDK;版本与下载哈希在 ROS CMake 中固定。
pride-core[rpc] 声明 grpcio 运行依赖,各独立消费环境锁定同一兼容版本。规划与交互物理使用其官方 unary RPC 和自定义 JSON 序列化接口,不依赖 protoc 或生成代码;业务校验继续使用 Pydantic。通信职责见工作台协议。