ROS2_learn/AGENTS.md

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 包 / 78 用例(65 pytest + 13 gtest) 100% 通过
6. 调试日志/临时输出统一放 .logs/ 目录。禁止在项目根目录散放 *.log、*.xml 等临时文件。
   • .logs/ 已加入 .gitignore,不会进版本控制
   • 用法: docker exec ... > .logs/build.log 2>&1

编程规范(必读)

严格遵循 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 包 / 74 用例 / 100% 目标)

包	类型	测试
py_pubsub	pytest	11/11
cpp_pubsub	gtest	3/3
py_srv	pytest	6/6
py_action_demo	pytest	4/4
cpp_robot_tf2	gtest	4/4
py_vision_demo	pytest	11/11
py_params	pytest	16/16
cpp_custom_interface	gtest	3/3
py_lifecycle_composable	pytest	6/6
cpp_qos_demo	gtest	4/4
py_overlay_dds	pytest	6/6
bringup	launch	6/6
总计		80/80

子项目约定

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,除非用户明确要求