跳到正文

验证入口 ​

开发验证 ​

Agent 在开发中用此入口发现检查、取得失败复现并验证修复。按改动推荐直接复用 prek 路由,始终不执行检查;共享工作区优先使用本任务的明确文件列表。

sh
uv run pride check --changed --json
uv run pride check --files src/pride/checks.py tests/test_checks.py --json
uv run pride check unit --test test_checks.py --match zero_matches --dry-run --json
uv run pride check unit --test test_checks.py --match zero_matches --json --output artifacts/checks/<case-before>
uv run pride check unit --test test_checks.py --match zero_matches --json --output artifacts/checks/<case-after>
uv run pride check unit --json

--test 使用 profile 中的精确文件名(不加目录),可重复;--match 使用 unittest 的名称子串或通配 pattern。筛选只运行相应 unittest 步骤,不证明整个 profile 通过。修复前后使用相同复现参数和不同证据目录,再执行受影响的完整检查。零个测试返回失败;跳过数量仍需核对。

每次执行默认创建 artifacts/checks/<unique-id>/result.json 和逐步日志;显式 --output 目录也必须不存在。先读结果中的失败步骤、退出码、摘要和日志路径,再读取对应日志。JSON 只写 stdout,进度写 stderr;成功不回显整份日志。停止、超时、未执行和外部验收的语义见验证指南。

sh
uv run pride check
uv run pride check --list
uv run pride check docs
uv run pride check dependencies
uv run pride check planning
uv run pride check kinematics
uv run pride check workbench
uv run pride check workspace
uv run pride check isaaclab
uv run pride check newton
uv run pride check cameras
uv run pride check rerun
uv run pride check hardware
uv run pride check ros2
uv run pride check learning-bridge
uv run prek run --all-files

默认检查为 Ruff、ty 与轻量测试,不启动 GPU。指定 profile 时可以追加 --dry-run 查看计划、--timeout 调整每条命令的时限。GPU、相机和学习框架的检查范围见 验证矩阵。检查只有这一条公开入口。

开发修改统一通过 pride check 选择环境和保存检查结果。先按本页步骤选择检查,再查下方各检查的覆盖范围。

检查只通过根 CLI 分发,实现在 src/pride/checks.py,按 profile 调用对应的 uv 环境。缺环境时 uv 会按锁文件同步,首次安装可能超过默认超时;先按 docs/software-setup.md 安装所需环境。

检查列表和计划支持结构化发现,示例见发现能力与检查计划。requires 是声明的前提:workspace 指根 uv 工作区,后端名称指相应独立项目或包;*-assets 指资产,*-extra 指可选依赖,ros2-build / isaac-runtime / node-pnpm 指外部构建或运行时,cuda / rtx 指 GPU 能力。它不探测可用性,也不授权设备操作。physical_device 标识检查是否需要真实设备;当前 profiles 均不连接实机。机器输出和运行器共用超时默认值、环境处理规则与命令计划。

按改动选择 ​

Profile内容前提与证据边界
docsMarkdown 链接、图片、所有指南中的 CLI 示例、skill 与检查目录;锁定安装并构建 VitePress。需要 Node.js/npx,首次依赖安装可能联网,不使用 GPU。
core(默认)Ruff、ty、pride doctor、simulation/manipulation/task_contract/labware、CLI 与 packaging 测试workspace dev 依赖和仓库 labware 资产;无 GPU。契约用例包括独立评估、分块恢复、测量序列化与证据缺口。doctor 只打印环境信息。测试后端不证明真实引擎任务成功。
lintRuff E9,F401,F63,F7,F82,F841语法、高置信错误与未使用代码。注册导入用局部注释说明保留原因;不开自动修复,不做格式或全量类型检查。
typesty 检查 CLI(含检查实现)、packages/core/src、完整 packages/runtime/src 和 server 的 execution/client使用 workspace 的显式数值依赖,包含 perception/recording;无后端导入例外。
unitcore 的各组轻量测试无 GPU;供 prek 独立调用,避免重复执行 lint 和 ty。
dependencies根 workspace 与独立消费项目的锁文件一致性、隔离安装后的 HTTP/SSE/WebSocket 握手与键盘转换分别隔离安装基础 CLI 与 server;基础 CLI 断言不安装 NumPy/Rerun/Arrow/gRPC,catalog/check-list/doctor 可运行;无 CAD、GPU 或实机。验证最低运行依赖,不复用现有环境里偶然安装的包。
planning原生 IK / 轨迹约束单测独立 planning 环境;无 CAD、GPU 或实机。布局集成另用 workspace。
kinematicsCAD、工作台业务协议、记录读取、perception、单臂模型测试server + models 的 cad extra、Git LFS CAD 和派生资产;本地临时 WebSocket 端口。无需物理 worker,不验证浏览器画面。
workbenchPython 边界协议 ty、三类会话与 HTTP/SSE/WS、键盘转换测试、JSON Schema / 生成 TypeScript 一致性、Vite+ 静态检查、TypeScript 和 XState 测试workspace dev + server、已安装的前端依赖与 Node/pnpm;无需 GPU,不验证浏览器画面。
hardware只读记录完整性、fake SDK、只读网页观察协议独立 hardware 环境 + workspace server,厂商资产;不连接实机、不上电或发送动作。真实采集需显式运行观察入口。
ros2进程内键盘转换(六轴、组合旋转、释放、无效输入)、控制权单测;严格共享控制 schema、长中文输出路径的真实 gRPC 通信、超时不重发、并发会话隔离及完整 mock 生命周期;原生 AUBO Session 故障与异步调用记录用例、原生记录的 Python 读回、SDK 链接插件加载和实机配置检查;真实 ROS GenericSystem 显式启用/停用、点动、超时停止、旧控制权拒绝、停止复位与首轮关节限额;TF/Servo 组件与进程归属、静态/动态 TF 对照归档 FK、容器暂停时撤权和停止、显式停用后恢复容器并正常关闭;原生 recorder 的进程归属,recorder 提前正常退出与控制权进程被强杀后的整图回收及失败归档;网页强杀后预算与归档继续;真实 Launch + fake SDK 验证启动取消、遥测就绪超时和控制退出后的五秒尾段先完成 ROS 系统依赖、构建与网页环境;原生插件不执行 configure,不连接控制柜;运动及容器暂停仅 mock,最多等待 40 秒启动,每段动作约 1 秒;不验证 SIGCONT 热恢复运动或实机安全。
isaacLab 与原生控制器单臂闭环、模型/FK/惯量、解析动力学、步长收敛、10 次生命周期、60 秒实时性及物理步/回调一致性锁定 Isaac Lab / Isaac 6.2、ROS 构建与 CAD;有限 PhysX/无传感器任务,不连接硬件。GUI 另行实际操作。完整门槛见 Isaac 集成。
single-arm-runtime有界写入延迟/失败、真实 socket 自主推进与停止;iS7 Newton/Steel 2600 步、reset、取消、分块 RRD 读回锁定 Lab、CUDA、CAD;每条命令 300 秒,无相机/实机。停止确认与归档末帧分别核对,不证明抓放或视觉任务。
mjwarp真正 CUDA MuJoCo Warp 的六轴模型/FK、两轮各 1000 步、100 Hz 目标跟踪、位置/速度边界、复位与重复轨迹锁定 Lab、GB10/CUDA、CAD 与已构建 ROS 配方(仅模型准备,不启动 ROS 控制);不运行相机/实机。默认 300 秒超时;单 world 测试不代表批量训练或实时遥操验收。
newton-teleopNewton 1.9/Steel CUDA 原生单臂闭环、模块来源与共享物理世界、模型/FK/惯量、真实 2 ms/1 ms 收敛、10 次生命周期、Kit 事件泵、故障撤权、物理步/原生回调一致性及 60 秒实时性锁定 Lab、Isaac 6.2 与原生扩展配方、CUDA、ROS 构建和 CAD;无相机/实机,不声称抓放或 sim-to-real 验证;结果写入 artifacts/steel-teleop-acceptance/,不覆盖旧 MuJoCo 证据。
isaaclab真实 Isaac Lab 3 落物、耗材落稳、抓放,以及工作台有限任务执行、连续 reset 的场景/目标/时钟恢复和归档独立 bundled-Python 环境、锁定原生运行时、CAD/耗材;CPU PhysX,每条命令有限预算。当前不含 RTX 相机、浏览器或实机。
teleop-presets六个预设门控单测、14 项真实 ROS mock 验收与独立 Isaac Lab 关节参考重放ROS 构建、models CAD 与独立 isaaclab 环境;无需 GPU/相机/真机。总命令预算 600 秒,物理阶段 150 秒。分别报告控制链路和名义物理模型结果,不证明真实伺服性能或现场安全。
learning-bridge两个独立环境间的 ROS mock / HTTP 控制权 / 自研 LeRobot Robot;示教导出和 LeRobot 官方读回同 ROS,加独立 learning 锁定环境。有限关节动作约 2 秒,无 GPU 训练、图像或实机验收。
rerun读取真实 RRD chunk,验证双时间轴、末帧、外参、米制、估计清除和哈希拒绝运动学项目(必需 Rerun SDK);无需 CAD、物理 worker 或 GPU。不验证查看器画面。
workspace原生轨迹约束单测、workspace 与 experiments 集成测试workspace + cad extra、CAD 资产、独立 planning 项目;调用 MPLib 静态 IK / 碰撞 worker,不初始化物理引擎。
newton解析转子力矩/限位、接触动量与支撑冲量、四项 Steel 任务与有限工作台同一个 Isaac Lab 环境、GB10/CUDA;官方 Steel 后端,每项两轮检查 reset;完整抓放另按任务原配置执行与审计。
cameras完整视觉抓放与双臂观察;工作台 RGB-D 标定/时钟审计;遮黑与过期帧拒绝;帧送达边界、带未送达帧的 reset 与跨 episode 标定归档Isaac Lab RTX、CAD/耗材;真实图像与物理任务,不代替浏览器视觉验收。

默认路径显式选择测试文件,避免在根环境执行 unittest discover 导入缺失的后端依赖。每项检查前脚本打印实际命令,失败即停并返回非零码。--dry-run 不执行命令、不安装环境,也不证明检查通过。

脚本移除继承的 VIRTUAL_ENV、UV_PROJECT_ENVIRONMENT 和 PRIDE_PHYSICS_TESTS / PRIDE_CAMERA_TESTS / PRIDE_TEST_SOLVER,仅为选中的 profile 设置开关,避免轻量检查意外跑 GPU 集成。未设置时将 BLAS/OMP 线程数设为 1。每条命令默认限时 300 秒;超时返回 124,Ctrl+C 返回 130。Linux 使用 child subreaper 回收整个检查进程树,包括自行创建 session 的后端和父进程退出后留下的 worker;正常退出也清理残留子进程。其他 POSIX 系统按仍可追踪的进程树清理,不能保证回收已经被系统收养的孤儿进程。

本地 prek ​

使用根目录 prek.toml,工具版本随根 uv.lock 锁定。首次克隆按环境准备安装本地 Git shim。

pre-commit 根据相关文件触发检查,实际路由以 prek.toml 为准。文档和 skill 触发 docs 检查;包元数据及锁文件触发依赖检查;代码按职责选择类型与行为检查。每个 hook 调用根 CLI 且不接收文件名,按完整检查范围执行一次。配置使用本地 hook,不下载远程 hook 仓库、不运行 GPU,也不改写代码。

--all-files 的触发集合是 Git 跟踪的文件,检查命令自身会读取当前工作树;新克隆必须包含本项目配置和脚本。新增文件在正常提交时通过暂存区参与匹配。可用 prek run --files <path> 检查指定改动的路由。

安装只添加 pre-commit shim,保留 Git LFS 的其他 hooks。其他克隆仍需各自执行 prek install。本项目当前不配置 CI。

ty 覆盖 CLI、core 和完整 NumPy runtime,workbench profile 另外检查 Python 请求与响应协议;后端实现与 GUI 绑定仍通过各自的真实集成检查验证。共享执行入口接收 Execution,通过 PhysicsSession、Policy 和规划接口约束内部调用;PhysicsFrame、动作计划与执行结果使用明确字段。Pydantic 校验配置、Job 和进程边界,内部不逐步重建完整模型。打包测试通过 AST 禁止生产 Python 代码使用显式 Any,这项禁令不等于所有第三方引擎接口均已完成静态验证。文件哈希统一使用 pride_core.files.digest。包与环境的权威说明见 包管理。

针对一个症状缩小循环 ​

ROS 遥操故障先按诊断 SOP索引、检查和保留证据。离线归档判据与执行级复现分别记录; 退出码为零的 ROS launch 不足以证明其子进程正常。诊断 CLI 的回归随 core/unit 检查运行。

开发过程中使用同一 pride check 入口发现、复现和回归,不等到交付才运行。--changed 读取 staged、unstaged 和未跟踪文件,--files 限定本任务路径;两者直接读取 prek.toml 的路由,输出命中的 hook、文件与 profile,并列出未命中路径。它们始终只推荐,不启动检查;不代表跨模块依赖分析或完整验收计划。共享工作区优先给出本任务文件,不能把他人的修改算入本次验证范围。

用 --dry-run 查看实际环境和命令。--test 选择该 profile 已有的 unittest 文件,可重复;--match 缩小测试名称。筛选只执行选中的 unittest 步骤,其他 lint、类型、构建与 smoke 步骤不会执行;原 profile 已有名称过滤时拒绝覆盖。未知文件、无可筛选步骤和空 pattern 提前报错;执行零个测试返回失败。先取得失败的最小复现,修复后用同一参数复验,再运行受影响的完整 profile。

每次执行新建证据目录,默认在 artifacts/checks/,可显式指定不存在的 output 目录。result.json 记录 profile、是否筛选、实际 argv、工作目录、测试环境覆盖、逐步状态、退出码、耗时和日志路径;unittest 的执行数及跳过数来自实际摘要。成功步骤不回显完整日志,失败步骤附有限尾部;--json 的 stdout 只输出结果,进度写 stderr。所有命令的完整 stdout/stderr 合并保存在各自日志中,先读结果再定位失败步骤。

检查失败后其余步骤标为 not_run;超时为 timed_out/124,Ctrl+C 为 interrupted/130,启动失败与零测试单独标识。每个步骤前后原子更新 receipt;宿主强杀后留下的 running 是未完成记录。既有目录拒绝覆盖。结果只证明对应命令在运行时的结果,不冻结共享工作区、校验全部源码身份或证明实机安全;源码并发变化时应在稳定版本重新检查。跳过项、筛选范围和外部验收仍需单独判断。

先确认复现的是用户的症状,再修根因。涉及真实后端、物理参数或相机渲染的改动,补充相应真实集成检查;测试后端的绿灯不替代它。仅改指引时,检查路径、命令、skill frontmatter 和 diff 即可。

直接检查产物 ​

  • 静态实验:核对 experiment.json 的状态、目标哈希、模型哈希、seed、budget 和 report.md,复用 workspace_experiment.py 的 load_result / verify_model 验证完整性。
  • 动态实验:核对 job.json、manifest.json、result.json 与 trajectory.rrd;复用 pride_runtime.archives.load_recording 校验哈希、状态与采样。记录物理有效性和任务成功各自的值。
  • 抓放契约:新 run / episode 包含逐步测量与契约,使用命令入口中的 audit 重算;一致性、契约满足、任务成功和物理有效性分别报告。字段与人工操作要求见任务验收。
  • 相机:同时核对渲染帧、相机外参/内参、仿真时间和 docs/cameras.md 中的验收入口。工作台协议测试通过不能单独证明显示正常。

报告实际运行的命令和结果;unittest 的 skipped 数单独说明。环境或资源缺失时说明未验证的内容,不修改判据把失败变绿,也不从旧运行目录推断本次结果。

开始验证时按用户本轮目标列出必验层级,分别标明所需环境、已有授权、实际入口与完成证据。已授权且前提具备的浏览器、真实后端或设备检查必须执行,不能把它们移到“未验证”列表后当作完成。失败后先区分可修复的软件问题与具体外部阻塞;可修复问题复现、修复并复验,外部阻塞保留本次探测证据。用户明确缩小范围的项目单独记录,历史通过不代替本轮检查。

前端交互通过公开工作台入口启动后,使用共享浏览器检查实际页面。用户要求或已授权 UI 验收时,优先交给一个独立 Agent 实际操作,记录步骤、页面结果、画面证据与无法覆盖的项目,将反馈返回实现 Agent,修复后再浏览器复验。不为外观或交互改动新增组件标记/SSR 断言或自动化 UI 测试,不新增或运行 Playwright 测试;状态机、数值校验和业务协议测试仍按需要执行。类型检查或静态服务响应不作为浏览器交互验收。