159 lines
7.2 KiB
Markdown
159 lines
7.2 KiB
Markdown
# ROS2 子项目 Agent 铁律 + 工作流
|
||
|
||
## 铁律 (Hard Rules)
|
||
|
||
**违反任何一条,所有变更立刻回滚。**
|
||
|
||
1. **只允许在本目录 `D:\xs\ros2` 下创建/修改/删除文件。**
|
||
2. **禁止用 shell(PowerShell / cmd)编辑文件**。改/写/读文件一律用内置工具:Read / Edit / Write / Glob / Grep。
|
||
- shell 只允许运行可执行命令,例如 `docker ...`、`colcon ...`
|
||
- **不允许**用 `Set-Content`、`Out-File`、`>`、`>>` 写文件
|
||
3. **禁止到处创建文件/目录**。所有产出放在本项目内或其默认位置。
|
||
4. **禁止问与思考循环**。给出明确方案,直接开干。
|
||
5. **测试必须 100% 通过才能停手**。
|
||
- `make colcon-build` + `make colcon-test` 全绿才能汇报"完成"
|
||
- 当前实测:**12 包 / 82 用例(64 pytest + 14 gtest + 4 launch_test) 100% 通过**
|
||
6. **调试日志/临时输出统一放 `.logs/` 目录**。禁止在项目根目录散放 `*.log`、`*.xml` 等临时文件。
|
||
- `.logs/` 已加入 `.gitignore`,不会进版本控制
|
||
- 用法: `docker exec ... > .logs/build.log 2>&1`
|
||
|
||
## 编程规范(必读)
|
||
|
||
**严格遵循 [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md)**。
|
||
|
||
核心要点:
|
||
|
||
- **Python**: type hints + Google docstring + 节点属性后缀 `_` + 私有方法前缀 `_`
|
||
- **C++**: 命名空间 + const-correct + override + 智能指针
|
||
- **测试**: conftest.py + session-scope fixture + pytest/gtest
|
||
- **包内必须有 README.md**(功能 + 关键概念 + 运行 + 测试 + 深度学习链接)
|
||
- **提交不修改 git config**: 用 `git -c user.name=x -c user.email=y commit` 临时设
|
||
|
||
## 项目结构(12 包 + 完全体)
|
||
|
||
```
|
||
D:\xs\ros2\
|
||
├── AGENTS.md # 本文件(铁律 + 工作流)
|
||
├── README.md # 项目入口 + 架构 + 启动
|
||
├── LICENSE # MIT
|
||
├── CHANGELOG.md # 变更日志
|
||
├── CONTRIBUTING.md # 贡献指南
|
||
├── pyproject.toml # PEP 621 workspace 元数据
|
||
├── requirements*.txt # venv 依赖
|
||
├── Makefile # 命令聚合(Linux/macOS)
|
||
├── .gitlab-ci.yml # GitLab CI 配置
|
||
│
|
||
├── docker/
|
||
│ ├── Dockerfile
|
||
│ ├── docker-compose.yml # name: ros2 + ros2_net 自定义网络
|
||
│ └── *_e2e.log # 端到端验证日志
|
||
│
|
||
├── doc/ # 24 篇深度文档
|
||
│ ├── 00-overview.md / 00-levels.md
|
||
│ ├── 01-quickstart.md / 02-virtualenv.md
|
||
│ ├── 10-concepts.md / 20-topics.md / 30-services.md / 40-actions.md
|
||
│ ├── 50-tf2.md / 60-urdf.md
|
||
│ ├── 70-launch.md / 80-package-build.md / 85-docker.md
|
||
│ ├── 90-testing.md / 99-embodied-ai.md / 100-embedded-deployment.md
|
||
│ ├── CODING_STYLE.md # ⭐ 编程规范
|
||
│ ├── 15-params.md # ⭐ 参数系统深度
|
||
│ ├── 16-custom-interfaces.md ⭐
|
||
│ ├── 17-lifecycle.md # ⭐
|
||
│ ├── 18-composable.md # ⭐
|
||
│ ├── 19-qos.md # ⭐
|
||
│ ├── 20-bag.md # ⭐
|
||
│ └── 21-overlay-dds.md # ⭐
|
||
│
|
||
├── tools/ # 本机开发工具
|
||
│
|
||
└── src/ # 12 个 ROS2 包
|
||
├── py_pubsub/ # Topic (Python)
|
||
├── cpp_pubsub/ # Topic (C++)
|
||
├── py_srv/ # Service (Python)
|
||
├── py_action_demo/ # Action 三件套 (Python)
|
||
├── cpp_robot_tf2/ # URDF + TF2 (C++)
|
||
├── py_vision_demo/ # Image + cv_bridge (Python)
|
||
├── py_params/ # ⭐ 参数系统 (Python)
|
||
├── cpp_custom_interface/ # ⭐ 自定义 msg/srv/action (C++)
|
||
├── py_lifecycle_composable/ # ⭐ Lifecycle + Composable (Python)
|
||
├── cpp_qos_demo/ # ⭐ QoS 9 种组合 (C++)
|
||
├── py_overlay_dds/ # ⭐ DDS 配置 + colcon overlay (Python)
|
||
└── bringup/ # 跨包 launch 聚合 (Python)
|
||
```
|
||
|
||
## 工作流命令(make / 直接 docker compose)
|
||
|
||
| 步骤 | 命令 |
|
||
|---|---|
|
||
| 构建镜像 | `make build` 或 `docker compose -p ros2 -f docker/docker-compose.yml build` |
|
||
| 启动容器 | `make up` 或 `docker compose -p ros2 -f docker/docker-compose.yml up -d` |
|
||
| 容器内 build 12 包 | `make colcon-build` |
|
||
| 跑所有测试 | `make colcon-test` |
|
||
| 单包测试 | `make colcon-test-one PKG=py_pubsub` |
|
||
| 启动 full_demo(11 节点) | `make full-demo` |
|
||
| 启动单 demo | `make launch NAME=pubsub_launch` |
|
||
| 进入开发终端 | `make shell` |
|
||
| 查看日志 | `make logs` |
|
||
| 本机 venv 初始化 | `make venv-setup`(或 `powershell .\tools\setup_venv.ps1`) |
|
||
|
||
## 测试覆盖(12 包 / 82 用例 / 100% 目标)
|
||
|
||
| 包 | 类型 | 测试 |
|
||
|---|---|---|
|
||
| py_pubsub | pytest | 11/11 |
|
||
| cpp_pubsub | gtest + launch_test | 4/4 |
|
||
| py_srv | pytest | 7/7 |
|
||
| py_action_demo | pytest | 5/5 |
|
||
| cpp_robot_tf2 | gtest + launch_test | 5/5 |
|
||
| py_vision_demo | pytest | 13/13 |
|
||
| py_params | pytest | 16/16 |
|
||
| cpp_custom_interface | gtest + launch_test | 4/4 |
|
||
| py_lifecycle_composable | pytest | 6/6 |
|
||
| cpp_qos_demo | gtest + launch_test | 5/5 |
|
||
| py_overlay_dds | pytest | 6/6 |
|
||
| bringup | pytest(0) | 0/0 |
|
||
| **总计** | | **82/82** |
|
||
|
||
## 子项目约定
|
||
|
||
### Python 包用 `ament_python`,C++ 包用 `ament_cmake`
|
||
### 跨包 launch 收纳到 `bringup` 包,**包名不能叫 `launch`**
|
||
### 默认参数 `publish_rate_hz=1.0`、`topic=chatter`、`queue_size=10`
|
||
### 节点命名 `<feature>`(`chatter_publisher`,`joint_state_publisher`)
|
||
### 跨语言互通:talker_py / talker_cpp 都用 `std_msgs/String`
|
||
|
||
## 嵌入式部署硬件清单
|
||
|
||
| 设备 | 角色 | ROS2 适配 |
|
||
|---|---|---|
|
||
| PC (x86) | 主控 | ✅ 完整 ROS2 + MoveIt2 + Nav2 + RViz |
|
||
| RDK X5 (ARM + 5 TOPS NPU) | 边缘 AI | ✅ 完整 ROS2 (视觉 / 语音 / SLAM) |
|
||
| RK3506 × 2 (ARM 3核 + 512MB) | 实时控制 | ✅ 精简 ROS2 (`ros-humble-ros-base`) |
|
||
|
||
**关键**: RK3506 是 Linux 应用处理器,**直接 apt 装 `ros-humble-ros-base`**,不用 micro-ROS。
|
||
三机同 LAN 同 `ROS_DOMAIN_ID`,通过 FastDDS multicast 自动发现。
|
||
|
||
## RMW / 网络注意事项
|
||
|
||
- Docker 默认用 **`rmw_fastrtps_cpp`**(不要在 compose 里设 Cyclone,镜像没装)
|
||
- 切换 RMW 时务必 `rm -rf build/ install/ log/` 再 build
|
||
- `ros2 launch` 的 `IncludeLaunchDescription` 复用其他包 launch 时,**被包含的 launch 必须被 colcon 实际安装** — 检查 `data_files` 里 `glob('launch/*.py')` 是否覆盖
|
||
- 本仓库用自定义网络 `ros2_net`(172.20.0.0/24,脱离 docker_default)
|
||
|
||
## 调试速查
|
||
|
||
| 症状 | 排查 |
|
||
|---|---|
|
||
| `rcl_xxx not found` | `source /opt/ros/humble/setup.bash` |
|
||
| `Command ['cat', path]` 空格丢了 | launch 里改 `open().read()` |
|
||
| `rcl_shutdown already called` | 测试 fixture 别在 callback 里 shutdown |
|
||
| `frame not exist` | robot_state_publisher 还没算完,等 1-2s |
|
||
| `Cannot connect to Docker daemon` | 启动 Docker Desktop |
|
||
| Windows venv import rclpy 飘红 | 正常,容器内跑 |
|
||
|
||
## Git 提交
|
||
|
||
- **不修改全局 git config**,用 `git -c user.name=x -c user.email=y commit` 临时设
|
||
- 分支命名: `feat/<name>` / `fix/<name>` / `docs/<name>`
|
||
- commit message 格式: `<type>(<scope>): <subject>` + body + footer
|
||
- 不主动 commit / push,除非用户明确要求 |