跳到正文

开发与维护操作 ​

现代 Web 指南 ​

前端采用范围见前端指引(apps/workbench/AGENTS.md),实施取舍见工作台与开发工具状态。以下命令用于开发时检索,不加入应用运行时或提交检查;从仓库根目录执行:

sh
npx -y modern-web-guidance@latest search "simplify CSS architecture"
npx -y modern-web-guidance@latest retrieve css,css-layout

按具体任务替换检索主题,读取命中的指南并核对浏览器支持。全目录现代化审视时可运行候选扫描;它只覆盖部分指南,结果需排除第三方实现和必要回退:

sh
npx -y modern-web-guidance@latest legacy-scan apps/workbench/src --json

Python 执行环境 ​

项目 Python 和临时分析脚本通过 uv 选定环境,不能依赖 shell 中是否存在 python / python3,也不硬编码 .venv/bin/python。从仓库根目录执行:

sh
uv run --project . python -c 'import sys; print(sys.executable)'
uv run --package pride-workbench python -c 'import sys; print(sys.executable)'
uv run --project backends/planning python -c 'import sys; print(sys.executable)'

根 workspace、包成员及独立后端按包与环境选择;开发测试优先使用上面的 check 入口。项目进程内使用 sys.executable 继承已选环境。ROS/Apport 等系统 ABI 操作沿用其系统入口;这是明确的环境要求,不能作为普通项目脚本绕过 uv 的理由。

资产维护 ​

以下脚本各自承担独立的维护操作,不提供同义的应用命令。下载脚本的 --check 仅校验本地资产;同步资产时去掉该选项。

sh
uv run python scripts/fetch_labware.py --check
uv run python scripts/fetch_aubo_is7.py --check
uv run --package pride-models python scripts/build_robot.py
uv run --package pride-models python scripts/register_flange_geometry.py
uv run --package pride-models python scripts/register_robot_geometry.py
uv run pride import-cad

生成厂家装配、配准几何与导入 CAD 是不同操作;原始输入、来源和许可须保留。

离线相机与硬件工具 ​

离线 Isaac 工作流使用静态相机快照,与实时物理相机任务不同:

sh
uv run --package pride-models --extra cad python -m pride_models.camera_scene --output runs/camera-inspection
isaac-sim-python scripts/render_cameras_isaac.py --input runs/camera-inspection
uv run --package pride-models python scripts/analyze_camera_captures.py --input runs/camera-inspection
uv run --package pride-models python scripts/validate_camera_captures.py --input runs/camera-inspection
uv run python scripts/export_realsense_intrinsics.py --output runs/realsense-intrinsics.json
isaac-sim-python scripts/smoke_isaac.py

硬件内参导出需要已连接设备及 RealSense SDK。Isaac 脚本使用其自带 Python,不使用项目环境替代。

打包 ​

sh
uv build --all-packages --wheel

共享包按普通 wheel 构建;资产和任务数据由项目根目录提供。原生依赖的构建配方属于构建输入,其操作说明保留在相应 recipe 文档中。

客户端构建见交互工作台构建;旧 Viser wheel 与客户端构建入口已删除。

远程查看 ​

sh
ssh -L 8080:127.0.0.1:8080 <node>

在本机浏览器打开终端打印的工作台地址。端口设置说明见 CLI 帮助。

工控机开发与 Spark 回传 ​

工控机源码目录为 /home/ubuntu/Developer/pride-telemetry,开发分支为 codex/ipc-telemetry。 使用同一套公开构建与检查入口,依赖仍由各自的锁文件管理。工控机没有 NVIDIA GPU,也不运行仿真环境。 先确定两端共同的已回传基线,只传递此后差异,不能用远端整仓快照覆盖本地未提交修改。

sh
# 在 Spark:已有同名 remote 时先核对 URL,不覆盖它
# 首次配置一次
git remote add ipc ssh://ubuntu@192.168.77.2/home/ubuntu/Developer/pride-telemetry
git fetch ipc codex/ipc-telemetry
# 将此变量设为已核对的共同基线提交
PRIDE_RETURN_BASE=共同基线提交
mkdir -p artifacts/ipc-return
git diff --binary "$PRIDE_RETURN_BASE" ipc/codex/ipc-telemetry > artifacts/ipc-return/return.patch

应用前逐文件比较:远端本次改动的旧文件,在 Spark 工作区中的 SHA-256 必须与起始基线相同; 新增文件必须不存在。任何冲突停止应用并单独合并,不能 stash、reset 或覆盖本地工作。

sh
# 仅在上述完整文件核对通过后执行;应用到工作区,不自动暂存或提交
git apply --check artifacts/ipc-return/return.patch
git apply artifacts/ipc-return/return.patch

后续按上次已回传提交到新提交的增量重复此流程,并重新核对起点;不要反复应用首次差异。 两端工作区整理为已提交的一致基线后,可以直接 fetch 后 merge/cherry-pick 对应功能提交。 产物另行复制并校验 manifest;不通过 Git 同步虚拟环境、构建缓存或采集目录。

原生 wheel 构建维护 ​

MPLib 来源和补丁见 构建记录(backends/planning/native/README.md)。共享修复工具改动须更新版本、重新构建 wheel 并核对 backend-artifact.json,不能修改安装目录。仅移动配方无需重建二进制。

sh
PYTHONPATH=packages/wheel-repairs/src uv run python -m unittest discover -s packages/wheel-repairs/tests -v
uv build --wheel --out-dir packages/wheel-repairs/wheels packages/wheel-repairs