主题
选择与修改配置
配置字段和范围以 configuration.py(packages/core/src/pride_core/configuration.py) 和 jobs.py(packages/core/src/pride_core/jobs.py) 中的 Pydantic v2 模型为准。根 AGENTS(AGENTS.md) 规定项目级类型安全要求;验证入口见验证指南,开发检查见验证步骤。
先找需要修改的文件
| 要改变什么 | 文件位置 | 例子 |
|---|---|---|
| 机器人平台和安装 | designs/ | aubo_is7_bare.yaml、aubo_is7_left.yaml |
| 桌面物体与摆放 | scenes/ | lab_bench.yaml |
| 要执行的动作与预算 | tasks/ | pick_place_cube.yaml、aubo_is7_tracking.yaml |
| 物理引擎、驱动、手型 | configs/ | 由任务引用的物理配置 |
| 对照的布局、目标和种子 | experiments/ | workspace_layouts.yaml |
先选最接近目标的现有示例,再复制并修改必要字段。路径从仓库根目录定位;每次运行会归档实际输入和模型。不要通过修改旧 run 里的文件改变已经取得的结果。
数字单位以字段和模型约定为准:后端通常使用 m/rad,四元数使用 wxyz;网页目标字段的 mm/°会显式转换。未知字段、非有限数值、不匹配的平台和任务会被拒绝。配置报错时按字段路径修正,不删除校验或放宽厂家限位。
以下内容供开发配置模型时查阅。
命名与职责
- 模型按领域概念命名,如
Timing、Physics、Job;任务变体按行为命名,如TrackingTask。不增加含义重复的 Config、Settings、Schema 后缀。 - 字段使用 snake_case。物理量在字段名表达单位,如
wall_time_s、amplitude_rad;姿态明确坐标系和 wxyz 顺序。既有mount_angle_deg属于布局输入约定,不借迁移暗改单位。 - 配置描述用户意图;Job 保存可执行的归档契约;State 保存运行状态。配置模型不承担文件读取、环境变量覆盖、设备连接或物理步进。
- 配置文件路径使用
str保持归档格式,路径解析和资源访问留给读取、打包和完整性核验模块。环境变量只用于已有启动约定,不隐式覆盖归档中的物理参数。
声明式约束
字段类型、长度、有限值和上下界通过类型标注、Annotated、Field 表达。模型统一严格类型、拒绝未知字段、拒绝 NaN/Inf,并校验默认值;数字字符串和以 bool 冒充数字均应拒绝。整数形式的物理量可以进入 float 字段,保持现有 YAML 中的零值等输入。
任务通过 type 使用判别联合,分别声明必要字段;不同求解器各有自己的模型。无关字段是错误,不能用一个拥有大量可选字段的模型接收所有组合。旧 PhysX 配置省略 solver 时仍按 PhysX 解释,不在原文件中补写默认值。
默认值只用于已有且明确的可选行为;安全限额、验收阈值和运动预算必须显式给出。固定字段集合使用模型;关节名称到限位、文件名到哈希等开放键集合使用有类型的字典。
单字段可复用语义使用 AfterValidator,例如单位四元数;跨字段关系使用 model_validator,例如控制相机必须在启用列表内、初始状态必须符合厂家限位。跨 Design、Task、Physics 的规则集中在 validate_relationships。文件哈希和模型身份由 verify_job_model 核验,保持 I/O 与纯数据校验分离。
读取、运行与归档
validate_design、validate_inputs、validate_job 返回已验证的模型。Job 在 worker、运行循环、控制器工厂、工作台和归档读取之间直接传递,后端接口接收 Scene、Physics 和 InitialState;内部通过属性消费字段。JSON/IPC 和资产适配处显式序列化,不能在校验后丢弃返回值继续传原始字典。完整配置校验只用于读取、准备、进程进入及会话重新装载,不加入物理逐步循环。
校验不修改传入字典、不自动重写 YAML 或旧 run。模型需要序列化时明确选择是否包含默认值;归档一致性测试使用 model_dump(exclude_unset=True) 核对已有字段。文件哈希针对原始文件字节,不针对重新序列化的模型。
资产文档如 camera mounts、labware actors/seat 仍归资产模块管理;Job 声明这些承载字段,labware 继续执行其既有资产规则和完整性核验,资产格式由所属模块负责。
硬件只读请求与采样以 pride_core.hardware 的 ObservationRequest、HardwareSample 为准,复用相同的严格类型、未知字段和有限值规则。SDK 回调校验一次后通过队列传递采样模型,归档读取返回模型;网页 ObservationRow 复用 ObservationSample,仅替换纳秒字段的字符串编码。时钟递增、厂家关节映射与模型哈希仍由采集和归档完整性检查负责。
运行时模型与静态类型检查互补:Pydantic 处理外部输入,ty 检查内部使用。新增字段同时更新所属模型、领域规则及消费者,避免复制第二份字段清单。回归测试覆盖实际的错误输入、字段错误定位、配置读取不变性和归档完整性;不为每个声明字段机械复制同构测试。