CLAUDE md工作须知 - NUSNiuMu/insight-capture-dashboard GitHub Wiki

本地助手工作须知（AGENTS.md / CLAUDE.md）

本页是本地自动化助手说明的可复制版本。下载后保存为项目根目录未跟踪的 AGENTS.md 和 CLAUDE.md，两份应同步维护，不要提交到主仓库。产品功能 与使用方法以仓库 README、使用手册和 部署与发布手册为准。

开工前确认现场

git status --short --branch
cat config/.device
docker compose ps
  • 不要假设当前机器使用哪个 profile，也不要覆盖已有未提交改动。
  • config/cameras.json、config/board_calibration.json、 config/post_processing.json 是未跟踪 live config。
  • rosbags/、runs/、outputs/、data/、release/、__pycache__ 是本地产物， 不能提交。
  • 推送前检查 git log origin/main..HEAD --oneline，避免带出未知既有提交。

单分支与设备 profile

所有设备共享 main。设备差异只允许存在于 config/devices/<profile>/{cameras.json,post_processing.json}：

scripts/select_device.sh <jetson-nx|lite|lite-779>

选择后需重启 Dashboard。正在录制的机器禁止切换 profile。当前本机是哪一种， 必须以 config/.device 为准。

当前代码职责

scripts/
  multi_camera_dashboard_web.py   ROS 生命周期与服务组合 facade
  dashboard_runtime/              图像、录制桥接、worker 监管、watchdog、WS payload
  dashboard_web/                  aiohttp app/context/middleware、WebSocket、领域 routes
  dashboard_media/                JPEG 与 WebRTC 媒体实现
  inprocess_bag_writer.py          图像进程内 SQLite rosbag 写入
  post_processing.py              离线处理公共导入 facade
  post_processing_core/           录制、恢复、同步、回放、评分、优化、bag/topic catalog
  hand_tracking/                  实时 overlay、手势与夹爪逻辑
  handpose/                       离线 WiLoR 任务
  webrtc_worker.py                独立 WebRTC/H.264 worker
  hand_overlay_worker.py          按需手部叠加 worker
  insight9_mapping_core/          特征、几何、EKF、位姿图、地图和同步
  insight9_sparse_mapper.py       在线稀疏建图入口
  insight9_dense_mapper.py        内部离线稠密验证入口
  insight3_global_localizer.py    双路全局重定位入口
web_dashboard/
  src/pages/                      页面入口与页面级交互
  src/shared/ camera/ spatial/    可复用前端领域模块
  dist/                           后端直接服务、必须提交的构建产物
config/devices/<profile>/         唯一允许的设备差异
deploy/                           客户 compose、升级脚本和说明

facade 只保留兼容和组合职责。新增 HTTP endpoint 必须在 dashboard_web/app.py 注册，业务放入 dashboard_web/routes/，跨 route 状态从 DashboardContext 获取。不要重新创建全站单体 app.js，也不要把重计算塞回 PoseBridgeNode。

开发与客户部署

  • 根 docker-compose.yml：开发用，本地 build，整仓 bind-mount 到容器 /workspaces/insight_capture。Python/前端代码通常重启容器即可，Dockerfile 依赖变更必须重新 build。
  • Dockerfile 的 dev target 在 runtime 上增加 Playwright Chromium；客户发布 明确使用 runtime。调试依赖优先放 dev，不要进入客户镜像。
  • deploy/docker-compose.yml：客户机使用发布镜像，无源码 mount。升级走 deploy/update.sh，打包走 scripts/build_release.sh。
  • 容器里临时 apt-get install 不会进入镜像；验证后把必要依赖写回 Dockerfile。
  • 所有 rclpy 程序必须在 rclpy.init() 前从当前相机配置设置 ROS_DOMAIN_ID，不能硬编码。

录制、回放与完整性

  • 图像复用 Dashboard 已有 DDS reader，直接喂给每路 InProcessBagWriter；禁止 恢复额外 ros2 bag record 图像订阅。IMU、VIO 等小消息仍由录制子进程负责。
  • header timestamp 映射到 recorder timeline，录制期间持续审计图像帧间隔。 停止结果优先使用 live audit。
  • check_bag.py --fast 是 SQLite 每 topic COUNT/MIN/MAX(timestamp) 聚合，不读 CDR payload，也不是基于 metadata.yaml 时长的估算。
  • /tf_static 只检查至少一条；没有 nominal rate 的 topic 只报告存在性。
  • SQLite 的 WAL + synchronous=OFF 是性能/断电恢复折中，不得改回 NORMAL/FULL。_staging 中断录制会在启动时认领；ros2 bag convert 输出 可能非确定性崩溃，必须单独验证。
  • 回放依赖 /bagplay/... remap 区分来源。新增展示 topic 时同步增加影子订阅和 remap，不能用相机时间戳判断实时/回放。
  • ROS image callback 中禁止阻塞、编码和磁盘 I/O；录制时优先保采集。

建图与重定位

  • Insight9 稀疏建图 + Insight3 全局重定位是唯一在线空间校准源。旧 AprilTag 在线对齐已删除，不要引用不存在的 scripts/alignment/ 或 live_alignment.py。
  • 客户发布自 v2.0.0 起包含 SuperGlue、sparse mapper 和 Insight3 localizer。 dense mapper 与 mapping RViz profile 仍只供内部验证。
  • TensorRT engine 首次冷编译约 15 分钟，superglue-engines volume 使缓存跨 升级保留，不要把正常编译误判为卡死。

WebRTC、手部与 WebSocket

  • WebRTC 和手部叠加分别运行在独立 worker；日志为 outputs/webrtc_worker.log 和 outputs/hand_overlay_worker.log。先查 health 与日志，再判断 UI 卡顿来源。
  • 手势只消费 Insight9 实时 keypoint；几何识别留在 hand_gestures.py，启停 状态机留在 dashboard_runtime/gesture_recording.py。ROS callback 不能直接 阻塞启停，手势停止不能终止网页手动录制。
  • pose WS 正常发送轨迹增量，并周期性发送完整 snapshot。payload 与网络/CPU 敏感，不能任意提高频率或恢复每次全量历史；3D 渲染保持独立限频。
  • 当前离线 Hand pose 只使用 WiLoR；不要恢复已删除的 MediaPipe 路径。
  • 当前本机显示为单个 Firefox kiosk；Qt 双窗口和 A/B 分屏 kiosk 均已删除。

前端变更

node web_dashboard/build.js

修改 web_dashboard/src/ 后必须构建并同时提交对应 src/dist。不要直接编辑生成的 业务 JS；dist 中 vendored Babylon 文件由构建脚本保留。页面验证至少覆盖目标 页面加载、控制台错误以及关键 API/WS；容器的 Playwright 浏览器位于 /opt/pw-browsers。

验证与调试

  • 每次代码变更必须做实际功能验证：相关单元/脚本 → 真实 API/WS 或 ROS 路径 → 需要时无头页面。语法检查不能替代功能验证。
  • 临时/复用测试放 ~/workspaces/insight_capture_tests/，不要放入仓库；记录可复核 的日志、计数、截图或前后差异。
  • rclpy 对 SIGTERM 不可靠；后台试运行用 nohup ... &，结束用 kill -INT。
  • ros2 node list 重名时先 ros2 daemon stop 排除 CLI 缓存。
  • GNOME 会按 workarea 裁剪普通窗口；固定屏幕 Qt 工具才使用 Qt.X11BypassWindowManagerHint，这不是恢复旧 Qt Dashboard 的理由。

文档、提交与语言

  • 完成功能并验证后，默认创建英文 conventional commit、推送当前分支，并同步 更新、提交和推送 GitHub Wiki；用户明确要求只留本地时除外。
  • Wiki 本地 clone 通常在 ~/workspaces/insight-capture-dashboard.wiki，中文简洁 记录“做了什么、为什么、如何验证”，月度 changelog 新条目置顶。
  • 主仓提交使用 fix:、perf:、ui:、feat:、docs: 等英文前缀。
  • 对话和用户文档使用中文；代码、注释和 Git 提交信息使用英文。
⚠️ **GitHub.com Fallback** ⚠️