# Go2 环境安装与构建交接记录

状态日期：2026-08-04

项目目录：`/home/limerly/go2_autonomous_inspection`

## 当前结论

`robot/inspection-core` 已恢复为完整版本。默认 Cargo workspace 测试以及启用 ROS2 `ros2`
feature 的全 workspace 检查均已通过，因此按照当前要求不再优化 Inspection Core 实现。

统一依赖路径下的联网版本校验、外部依赖构建、仓库 ROS 包构建、导航构建和 Inspection Core
检查已经在同一次一键脚本运行中成功完成。环境安装与构建任务没有遗留的软件阻塞；后续工作
转为现场硬件全链路验证，验证通过后再决定是否清理旧 workspace。

## 已完成内容

- 已安装当前机器缺少的主要系统、ROS2、Python、Rust 和 Node.js 环境。
- Rust 当前版本为 `rustc 1.97.1`、`cargo 1.97.1`。
- 用户级 Node.js 当前版本为 `v22.23.1`，位置为
  `/home/limerly/.local/opt/node-v22.23.1-linux-arm64`。
- 已完成 rosdep 初始化和更新。
- 已创建 `dependencies/install.sh`，作为新机器的一键依赖安装与构建入口。
- 已创建 `dependencies/environment.sh`，统一所有外部 workspace 和缓存路径。
- 已创建 `dependencies/external.repos` 和 `dependencies/external-versions.env`，固定以下依赖：
  - Livox SDK2：`08f523c930b2f0ba1e98a6afaa8d7476bf479908`
  - Livox ROS Driver 2：`1.2.6`，对应已验证提交
    `13eb05e4e6dd7a765b934d0c5fd6236676a57b49`
  - FAST-LIO ROS2：`2fffc570a25d0df172720bac034fbdb6a13d2162`
  - Unitree ROS2：`668d1ec5a05d1c38d3306bdca7d59f2ba3581a88`
- 已补齐导航构建入口：
  - `robot/navigation/scripts/build/local_packages.sh`
  - `robot/navigation/scripts/build/navigation.sh`
- mapping、navigation 和 dashboard 启动脚本已改为读取
  `dependencies/environment.sh` 中的统一路径变量。
- 构建生成物默认放在 `${XDG_CACHE_HOME:-$HOME/.cache}/go2_autonomous_inspection`，不会写入
  `robot/` 或仓库自有 ROS 依赖源码目录。
- 四个固定版本的外部仓库已下载到 `dependencies/external`，源码树均保持干净，FAST-LIO 的
  `ikd-Tree` 子模块也已检出固定提交 `e2e3f4e9d3b95a9e66b1ba83dc98d4a05ed8a3c4`。
- Livox SDK2、Livox ROS Driver 2、FAST-LIO ROS2 和 Unitree ROS2 已构建到新的统一缓存路径。
- `dependencies/install.sh` 已修复两项实际全链路构建问题：
  - 在 `set -u` 模式下安全加载 ROS setup 文件。
  - 为 ROS2 Rust bindgen 自动加入 GCC 标准头文件目录。
- 当前容器禁止 `sudo` 提权，因此已安装的系统包未重复安装；以下联网版本校验和完整构建命令
  已成功退出：

```bash
./dependencies/install.sh --skip-system --jobs 4
```

## 已通过验证

- Inspection Core 默认 workspace：全部测试通过，共 92 个单元测试，doc tests 通过。
- Inspection Core ROS2 feature：`cargo check --workspace --all-targets --features ros2 --locked`
  通过。
- Navigation Python：`111/111` 通过。
- Mapping Python：`14/14` 通过。
- Dashboard Python：`53/53` 通过；HTTP 测试需要允许绑定 localhost socket。
- 新统一缓存路径中的外部构建通过：
  - Livox SDK2
  - Livox ROS Driver 2
  - FAST-LIO ROS2
  - Unitree ROS2（`unitree_api`、`unitree_go`、`unitree_hg`）
- 新统一缓存路径中的仓库 ROS 构建通过：
  - `go2_description`
  - `go2_twist_bridge`
  - `go2_inspection_navigation`
- 新增和修改的 shell 脚本均通过 `bash -n`。
- 一键脚本的离线工具链检查已通过：

```bash
./dependencies/install.sh --offline --skip-download --skip-build
```

## 尚未完成

依赖安装和构建任务已完成。尚未执行的是连接真实 Go2 和 Livox 设备后的现场全链路验证。

当前机器早期构建的外部 workspace 仍保留在旧路径：

```text
/home/limerly/ws_livox
/home/limerly/fast_lio_ws
/home/limerly/unitree_ros2
/home/limerly/Livox-SDK2
```

新的默认路径已由 `dependencies/environment.sh` 指向并完成构建：

```text
/home/limerly/go2_autonomous_inspection/dependencies/external
/home/limerly/.cache/go2_autonomous_inspection/external
```

在现场验证通过前不要删除这些旧 workspace。

## 后续操作

开始现场验证前加载统一环境：

```bash
cd /home/limerly/go2_autonomous_inspection
source dependencies/environment.sh
go2_dependencies_source_external_ros
```

按照项目根目录的 `end-to-end-inspection-runbook.md` 完成真实设备上的 mapping、导航和巡检任务
验证。确认新路径运行稳定后，再单独评估旧 workspace 的清理。

## 手工复核命令

一键脚本执行完成后，至少运行：

```bash
cd /home/limerly/go2_autonomous_inspection
source "$HOME/.cargo/env"
source /opt/ros/humble/setup.bash
source dependencies/environment.sh

python3 -m unittest discover -s robot/mapping/test -p 'test_*.py'

PYTHONPATH="robot/navigation:${PYTHONPATH:-}" \
  python3 -m unittest discover -s robot/navigation/test -p 'test_*.py'

PYTHONPATH="robot/dashboard:${PYTHONPATH:-}" \
  python3 -m unittest discover -s robot/dashboard/test -p 'test_*.py'

CARGO_TARGET_DIR=/tmp/go2-inspection-core cargo test \
  --manifest-path robot/inspection-core/Cargo.toml --workspace --locked

export BINDGEN_EXTRA_CLANG_ARGS="-I$(gcc -print-file-name=include)"
CARGO_TARGET_DIR=/tmp/go2-inspection-core-ros2 cargo check \
  --manifest-path robot/inspection-core/Cargo.toml --workspace --all-targets \
  --features ros2 --locked
```

## 注意事项

- 不修改 Inspection Core 业务实现，除非完整编译或测试出现明确失败。
- 不删除旧 workspace，等现场验证通过后再决定是否清理。
- 当前容器设置了 `no new privileges`，不能在容器内运行脚本的 apt 阶段；宿主机或新机器上仍应
  使用具备 apt 管理权限的默认命令 `./dependencies/install.sh`。
- 非登录 shell 可能找不到用户级 Rust 和 Node.js，必要时执行：

```bash
source "$HOME/.cargo/env"
export PATH="$HOME/.local/bin:$PATH"
```

- `python3 tools/documentation.py check` 当前会报告仓库内既有的历史 session-state 文件命名和
  server 文档索引问题；这不是依赖安装任务造成的，后续应作为独立文档治理任务处理。