跳到正文

pride 架构 ​

本文描述当前模块职责与进程边界;实现与验证缺口见当前状态。安装、extra 和锁文件以包管理及清单为准,运行操作见命令入口。

机器人会话由 ROS Launch 管理,设备状态复用 ros2_control,控制权独立。有限物理任务采用 ROS Action Goal 状态语义,worker 使用私有 gRPC;项目没有统一的 systemd/cgroup 会话托管或原生 ROS Action server。

当前代码地图 ​

入口当前职责主要依赖与边界
src/pride/公开 CLI、检查、前端和 ROS 构建、进程调度Python 运行依赖仅 core;通过子进程选择各业务环境
packages/core/src/pride_core/配置、job、模型完整性、物理观测与结果类型、任务契约、来源记录与启动辅助基础依赖仅 Pydantic/PyYAML/typing-extensions;RRD 与通用 RPC 通过 records/rpc extras 启用;不导入策略、CLI 或具体后端
packages/runtime/src/pride_runtime/执行循环、worker/session、抓放与视觉策略、episode 评估、数值感知、记录和物理归档读取core、NumPy、transitions;物理会话、规划器与相机观察源显式注入
packages/models/src/pride_models/CAD、装配、归档模型生成、几何与坐标core 与模型/数值库;不导入应用、runtime 或具体后端
apps/server/src/pride_workbench/HTTP/SSE/WS、仿真/观察/遥操会话、静态实验、导出和具体任务编排core、models、runtime;execution / client 选择并启动物理环境
backends/planning/src/pride_planning/Pinocchio/MPLib IK、FCL 碰撞、Ruckig 轨迹、静态 worker隔离原生依赖;提供 PinocchioPlanner,不拥有策略阶段或物理世界
backends/isaaclab/src/pride_isaaclab/Isaac Lab 环境、资产、执行器、传感器与物理适配core/runtime/planning;PhysX/RTX 与 Newton/Steel、MuJoCo 由 Lab 管理,ROS 控制器接入同一物理生命周期
backends/hardware/src/pride_hardware/AUBO SDK 只读采集隔离厂家 SDK;不发运动指令
backends/ros2/ROS 2 控制权、MoveIt Servo 和 ros2_control 硬件适配系统 ROS ABI;设备生命周期与控制权独立
backends/learning/LeRobot Robot 插件与示教数据桥接独立 LeRobot/Torch 环境;复用本仓库控制入口
apps/workbench/React 交互与 Three.js 显示消费生成的业务协议,不持有设备 SDK 或判定任务成功

backends/isaac/ 仅保存原生 Isaac Sim 运行时清单。单臂 ROS 物理遥操由 pride_isaaclab.teleop 启动,与动态任务复用 Lab 场景、物理步进和重置;PhysX 与 Newton/Steel 均由 Sim 原生 ros2_control 独占位置/速度目标。Newton 原生适配共享 Lab 分配的 model/state/control/solver,原生回调包围唯一的 Lab 物理步;不建立第二个世界。Kit 扩展入口补丁与模块版本隔离见原生配方(backends/isaaclab/native/README.md)。两条路径共享控制权、步进、重置与受限重力前馈;每个会话只运行一个引擎。MuJoCo 的历史 topic hardware 路径暂时保留,具体职责与验收边界见原生控制说明。

Newton 主路径为 Steel/CUDA,PhysX 保留抓放和视觉基线;MuJoCo 保留既有配置与检查。工控机实机控制无需 GPU 仿真运行时。

遥操输入在网页服务进程内转换;浏览器提交完整按键快照,转换结果交给原有 ROS 控制权入口。输入处理不启动独立 worker;mock / aubo 仍无需仿真依赖。

单臂 ROS 的 TF 发布者与 MoveIt Servo 作为两个组件共享 servo_container 进程,复用同一归档模型、会话命名空间与时钟。控制权/watchdog 保留独立进程;mock/aubo 的 ros2_control_node 也独立运行。容器故障会同时失去 TF 与 Servo,撤权和控制器命令超时仍由容器外执行。部署与关闭顺序见 ROS 2 集成。

ROS Launch 统一拥有控制图、原生 rosbag2 recorder、仿真与独立只读遥测;会话预算和归档也在 Launch 内执行。网页只启动会话入口、提交持久化停止请求并等待结果,遥测视图不再创建或终止进程。Launch 按设备停用、控制图退出、recorder 收尾、遥测五秒尾段的顺序关闭;网页死亡不移除会话预算。设备停用、启用回滚和最终关闭复用 ROS 执行层的同一停止顺序;控制器与硬件状态转换仍交给 controller manager。

依赖与进程 ​

公开 CLI 经通用项目定位与环境启动入口选择 worker。应用服务可以依赖模型、协议和执行能力;core/runtime 通过接口接收具体实现,不能反向导入应用或引擎。后端不依赖 CLI。具体后端目录映射和启动编排属于应用;core 中的 Isaac/ROS 辅助仅保留共享 ABI、环境与契约操作,供各入口共同使用。

  • 静态链路:准备归档模型 → 独立 planning worker → 有预算的 IK / 碰撞结果。此链路不启动物理引擎。
  • 动态链路:准备 job → Isaac Lab worker → 实际积分、逐步测量、任务判据与归档。isaaclab 是动态 job 后端;physx / steel 是其求解器选择。
  • 网页链路:React → HTTP/SSE/位姿流 → 业务会话 → 所选 worker 或设备控制进程。协议定义见工作台协议。
  • 实机链路:显式会话 → 生命周期启用 → 独立控制权 → Servo / ros2_control → 厂家 SDK。观察、命令接受、实际反馈和任务成功分别记录。

规划、交互物理 worker 与 ROS 控制入口统一使用本机 Unix domain socket 上的 gRPC unary 调用;规划/物理的通信与进程资源所有权在 pride_core.rpc,ROS 的类型化调用位于 pride_core.control_rpc;业务客户端保留各自的就绪和错误语义。规划/物理 gRPC 服务线程只交接命令,计算仍由原执行线程串行处理;ROS 控制调用使用有界线程池,反馈与 watchdog 保留独立 executor。ROS 会话由 Launch 持有,控制 channel 不拥有或终止它。控制 schema 位于 pride_core.control,网页模型继承它并生成客户端。工作台一次提交有限 run,物理拥有线程自主推进,业务状态轮询不驱动时间;轨迹/证据与相机各用有界单写入线程归档,不增加进程。协议及故障语义见工作台协议。

每次物理运行只有一处推进时间。任务目标与验收契约不随控制策略或求解器改变;记录保留测量、时间、模型来源与证据缺口。模型与实验约定见领域说明,任务语义见任务契约。

物理适配以 PhysicsSession 暴露已加载的世界,advance 返回同一步的 PhysicsFrame(状态、诊断和带独立采集时间的相机观察)。Isaac Lab 入口将物理会话与策略工厂装配为 Execution;策略只接收规划接口与相机观察源,不能推进引擎。TaskStepper 先检查物理有效性,再将每个有效步交给独立 TaskEvaluator 和记录器,最后推进 Policy。策略报告执行进度,评估器拥有判据历史并合成任务结果;策略自报成功不足以通过验收。

配置与进程边界使用严格 Pydantic 模型,内部使用有明确字段的 dataclass、TypedDict 和 Protocol。诊断、相机观察、动作计划和执行结果不再使用 Any;打包检查禁止生产 Python 代码引入它。静态检查的当前覆盖范围仍以验证入口为准。

命名约定 ​

项目和公开命令名为 pride。下表区分生态要求与本仓库选择:

对象约定与例子
Python 分发包本项目采用小写连字符,如 pride-core;分发名与导入名是不同概念
Python 导入包/模块小写合法标识符,如 pride_core、planning_client.py;函数用 snake_case,类用 CapWords
隔离 worker本项目内部约定 _pride-*;用户操作仍由 pride 分发
环境变量与工具配置PRIDE_*、[tool.pride];原生第三方变量维持其上游名称
ROS 包、C++ namespace小写下划线,如 pride_control、pride_aubo_hardware、pride_aubo
LeRobot 插件lerobot_robot_pride_is7;保留上游发现协议的 lerobot_robot_ 前缀
前端应用与组件应用包 @pride/workbench;React 组件 PascalCase,hooks 使用 use…
项目 skill小写连字符 pride-verify、pride-experiment;目录与 frontmatter name 一致
领域与外部身份idx-rig、two_arm_rig、厂家 link/joint ID、版本化第三方 wheel、既有浏览器存储键及原始归档路径保持原名

依据:PyPA 的分发包与导入包、PEP 8、ROS REP 144、LeRobot 插件发现。连字符分发名与内部 worker 前缀属于本项目选择,不能描述成所有社区的强制规定。

更名更新源码、清单、启动入口、生成协议、测试与文档,不保留旧软件命令或 import 别名。保留的归档不重写其字节和哈希;已退役实验数据与读取兼容可按迁移范围删除,不为它们保留旧执行入口。已版本化的 spark-wheel-compat 是 ARM64 wheel 构建工具身份,其更名需要显式更新构建产物及消费者。

扩展与维护 ​

新增仿真需求先核对锁定 Isaac Lab 的组件和扩展点;记录具体缺口,只保留平台与领域适配。布局优化不增加通用框架。性能优先改善数据布局、资源/实例分离、批处理和重复计算。保留当前执行所需状态、模型来源与许可;旧实验数据、旧格式读取及仅服务于它们的依赖允许随退役删除,清理约定见文档维护。

稳定的依赖约束通过包导入检查验证;协议由 Python 模型生成 OpenAPI/TypeScript 并核对一致性。指引与文档通过本地检查维护,操作见开发验证。

离线故障证据由 src/pride/diagnostics.py 编排:复用 core 归档与时间线校验,调用系统 coredumpctl/Apport 查询已匹配进程的元数据,生成可携带证据包与跨目录索引。不依赖设备后端,不改变记录状态或物理判据; core 的 cabinet.py 关联已校验的 SDK 目标与本地柜端 RPC 日志,保留双侧源身份和原始时间,不负责设备连接或时钟校准; 流程见诊断 SOP。