ccg-ros2-workflow 2.2.2 → 3.0.0

package/templates/skills/domains/ros2-perception/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: ros2-perception
+description: ROS2 感知技能。激光雷达、相机、点云处理、传感器融合、SLAM 输入。当用户提到激光雷达、LiDAR、点云、PCL、PointCloud2、相机标定、深度图、传感器融合时使用。
+user-invocable: false
+category: domain
+---
+
+# ROS2 感知技能
+
+## 适用场景
+
+机器人感知层开发,处理传感器原始数据并提取语义信息。
+
+### 触发关键词
+
+- 激光雷达 / LiDAR / RPLidar / Velodyne / Ouster
+- 点云 / PointCloud2 / PCL / 点云分割 / 体素
+- 相机 / RGB / 深度相机 / RealSense / ZED
+- 标定 / calibration / 内参 / 外参
+- SLAM 输入 / 里程计输入 / 传感器融合
+
+---
+
+## 激光雷达驱动
+
+### 标准包列表
+
+| 厂商 | ROS2 包 | 默认 Topic |
+|------|---------|------------|
+| RPLidar | `rplidar_ros` | `/scan` (sensor_msgs/LaserScan) |
+| Velodyne | `velodyne_driver` | `/velodyne_points` (sensor_msgs/PointCloud2) |
+| Ouster | `ouster_ros` | `/ouster/points` |
+| Livox | `livox_ros_driver2` | `/livox/lidar` |
+
+### 启动示例
+
+```python
+# launch/rplidar.launch.py
+Node(
+    package='rplidar_ros',
+    executable='rplidar_node',
+    name='rplidar',
+    parameters=[{
+        'serial_port': '/dev/ttyUSB0',
+        'frame_id': 'laser_link',
+        'angle_compensate': True,
+        'scan_mode': 'Standard',
+    }],
+)
+```
+
+---
+
+## 点云处理 (PCL)
+
+### 体素降采样
+
+```cpp
+#include <pcl/filters/voxel_grid.h>
+#include <pcl_conversions/pcl_conversions.h>
+
+void cloud_callback(const sensor_msgs::msg::PointCloud2::SharedPtr msg) {
+  pcl::PointCloud<pcl::PointXYZ>::Ptr cloud(new pcl::PointCloud<pcl::PointXYZ>);
+  pcl::fromROSMsg(*msg, *cloud);
+
+  pcl::VoxelGrid<pcl::PointXYZ> voxel;
+  voxel.setInputCloud(cloud);
+  voxel.setLeafSize(0.05f, 0.05f, 0.05f);  // 5cm 体素
+  pcl::PointCloud<pcl::PointXYZ>::Ptr filtered(new pcl::PointCloud<pcl::PointXYZ>);
+  voxel.filter(*filtered);
+
+  sensor_msgs::msg::PointCloud2 output;
+  pcl::toROSMsg(*filtered, output);
+  output.header = msg->header;
+  pub_->publish(output);
+}
+```
+
+### 平面分割 (RANSAC)
+
+```cpp
+#include <pcl/segmentation/sac_segmentation.h>
+
+pcl::SACSegmentation<pcl::PointXYZ> seg;
+seg.setOptimizeCoefficients(true);
+seg.setModelType(pcl::SACMODEL_PLANE);
+seg.setMethodType(pcl::SAC_RANSAC);
+seg.setDistanceThreshold(0.01);
+seg.setInputCloud(cloud);
+
+pcl::ModelCoefficients::Ptr coefficients(new pcl::ModelCoefficients);
+pcl::PointIndices::Ptr inliers(new pcl::PointIndices);
+seg.segment(*inliers, *coefficients);
+```
+
+---
+
+## 相机集成
+
+### RealSense 启动
+
+```bash
+ros2 launch realsense2_camera rs_launch.py \
+  enable_color:=true \
+  enable_depth:=true \
+  align_depth.enable:=true \
+  pointcloud.enable:=true
+```
+
+### 深度图转点云
+
+```cpp
+// depth_image_proc 功能包提供
+#include <depth_image_proc/point_cloud_xyz.hpp>
+```
+
+---
+
+## 传感器融合
+
+### TF2 时间同步
+
+```cpp
+#include <message_filters/subscriber.h>
+#include <message_filters/time_synchronizer.h>
+#include <message_filters/sync_policies/approximate_time.h>
+
+using SyncPolicy = message_filters::sync_policies::ApproximateTime<
+    sensor_msgs::msg::PointCloud2,
+    sensor_msgs::msg::Image>;
+
+message_filters::Subscriber<sensor_msgs::msg::PointCloud2> cloud_sub_;
+message_filters::Subscriber<sensor_msgs::msg::Image> image_sub_;
+message_filters::Synchronizer<SyncPolicy> sync_(SyncPolicy(10), cloud_sub_, image_sub_);
+sync_.registerCallback(&Node::fusion_callback, this);
+```
+
+---
+
+## 关键 QoS 策略
+
+| 数据类型 | Reliability | Durability | History | Depth |
+|----------|-------------|------------|---------|-------|
+| LaserScan | Best Effort | Volatile | Keep Last | 5 |
+| PointCloud2 | Best Effort | Volatile | Keep Last | 1 |
+| Image (高分辨率) | Best Effort | Volatile | Keep Last | 1 |
+| 相机内参 | Reliable | Transient Local | Keep Last | 1 |
+
+---
+
+## 调试工具
+
+```bash
+# 查看话题数据
+ros2 topic echo /scan --no-arr
+ros2 topic hz /velodyne_points
+
+# RViz2 可视化
+rviz2 -d perception.rviz
+
+# 录制 rosbag
+ros2 bag record /scan /velodyne_points /camera/image_raw
+
+# 回放
+ros2 bag play <bag_file>
+```

package/templates/skills/domains/ros2-upper-app/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ros2-upper-app
+description: ROS2 上层应用集成域。Launch 编排、参数配置、RViz 可视化、Python 节点、Gazebo/Ignition 仿真。当用户提到 launch 文件、launch.py、参数 YAML、RViz、URDF 显示、Python 节点、rclpy、Gazebo、Ignition 仿真、机器人状态发布时使用。
+user-invocable: false
+category: domain
+---
+
+# ROS2 上层应用集成域
+
+## 域定位
+
+负责 ROS2 系统的**上层编排与可视化**——把各个底层节点(感知/控制/驱动)串成可启动、可配置、可视化、可仿真的整体。
+
+**Authority Model**: Antigravity 优先(默认),Gemini 备选。
+
+## 子技能索引
+
+| 子技能 | 职责 | 触发关键词 |
+|--------|------|------------|
+| [launch-files.md](./launch-files.md) | Launch 文件编排 | launch, launch.py, IncludeLaunchDescription, launch_arguments |
+| [parameters.md](./parameters.md) | 参数 YAML / declare_parameter | params.yaml, ros__parameters, declare_parameter, override |
+| [rviz-config.md](./rviz-config.md) | RViz 可视化配置 | rviz, rviz2, .rviz config, displays, fixed frame, TF tree |
+| [python-nodes.md](./python-nodes.md) | rclpy 节点开发 | rclpy, Python node, async, MultiThreadedExecutor, callback group |
+| [simulation.md](./simulation.md) | Gazebo / Ignition 仿真 | gazebo, gz, ignition, sdf, world, robot_state_publisher, controller spawner |
+
+## 与其他 ROS2 域的关系
+
+```
+┌─────────────────────────────┐
+│   ros2-upper-app(本域)     │  ← Antigravity 主导
+│   Launch / Params / Viz     │
+└──────────┬──────────────────┘
+           │ 启动并连接
+           ↓
+┌──────────────────────────────────────────────┐
+│   ros2-perception / control / navigation /   │  ← Codex 主导
+│   manipulation / hardware                    │
+└──────────────────────────────────────────────┘
+```
+
+- 本域负责 **how to compose**(如何组装)
+- 其他 ROS2 域负责 **what to compute**(算什么)
+
+## 通用约束
+
+- 路径不要硬编码 — 用 `FindPackageShare` + `PathJoinSubstitution`
+- 参数不要散落在 launch 中 — 集中到 `config/*.yaml`
+- 节点命名空间显式声明 — 多机器人场景下避免冲突
+- TF tree 单根原则 — 全系统只有一个根 frame(通常是 `map` 或 `odom`)
+- `use_sim_time` 在仿真场景必须显式传递到所有节点

package/templates/skills/domains/ros2-upper-app/launch-files.md

@@ -0,0 +1,224 @@
+# ROS2 Launch 文件编排
+
+## 何时使用
+
+- 启动单节点(`Node`)
+- 多节点编排,带启动顺序、条件、重映射
+- 复用其他 launch 文件(`IncludeLaunchDescription`)
+- 接收命令行参数 / 从 YAML 读取参数
+
+## 标准 launch.py 模板
+
+```python
+from launch import LaunchDescription
+from launch.actions import DeclareLaunchArgument, IncludeLaunchDescription, GroupAction
+from launch.conditions import IfCondition, UnlessCondition
+from launch.launch_description_sources import PythonLaunchDescriptionSource
+from launch.substitutions import LaunchConfiguration, PathJoinSubstitution, TextSubstitution
+from launch_ros.actions import Node, PushRosNamespace
+from launch_ros.substitutions import FindPackageShare
+
+
+def generate_launch_description():
+    pkg_share = FindPackageShare('my_robot')
+
+    use_sim_time = LaunchConfiguration('use_sim_time')
+    namespace = LaunchConfiguration('namespace')
+    params_file = LaunchConfiguration('params_file')
+
+    declare_use_sim_time = DeclareLaunchArgument(
+        'use_sim_time', default_value='false',
+        description='Use simulation (Gazebo) clock if true')
+
+    declare_namespace = DeclareLaunchArgument(
+        'namespace', default_value='',
+        description='Top-level namespace')
+
+    declare_params = DeclareLaunchArgument(
+        'params_file',
+        default_value=PathJoinSubstitution([pkg_share, 'config', 'params.yaml']),
+        description='Full path to the ROS2 parameters file')
+
+    bringup_group = GroupAction([
+        PushRosNamespace(namespace),
+
+        Node(
+            package='my_robot',
+            executable='controller_node',
+            name='controller',
+            parameters=[params_file, {'use_sim_time': use_sim_time}],
+            remappings=[
+                ('/cmd_vel', 'cmd_vel'),
+                ('/odom', 'odom'),
+            ],
+            output='screen',
+            emulate_tty=True,
+        ),
+
+        IncludeLaunchDescription(
+            PythonLaunchDescriptionSource(
+                PathJoinSubstitution([pkg_share, 'launch', 'sensors.launch.py'])),
+            launch_arguments={
+                'use_sim_time': use_sim_time,
+            }.items(),
+        ),
+    ])
+
+    return LaunchDescription([
+        declare_use_sim_time,
+        declare_namespace,
+        declare_params,
+        bringup_group,
+    ])
+```
+
+## 关键 API
+
+### Node 参数
+
+| 参数 | 用途 |
+|------|------|
+| `package` | ament 包名 |
+| `executable` | `setup.py` 中 console_scripts 名,或 C++ 可执行文件名 |
+| `name` | 节点运行时名(不写则用代码里的名) |
+| `namespace` | 节点的 ROS namespace |
+| `parameters` | 列表:dict / yaml 文件路径都可以 |
+| `remappings` | `[(from, to), ...]` |
+| `arguments` | 透传给 `argv` |
+| `respawn` | 崩溃自动重启 |
+| `output` | `screen`(打印到终端)/ `log`(写入日志) |
+| `emulate_tty` | 让 RCLCPP_INFO 等日志保留颜色 |
+
+### 路径替换(永远不要硬编码)
+
+```python
+# ❌ 错误
+params=['/opt/ros/humble/share/my_pkg/config/params.yaml']
+
+# ✅ 正确
+PathJoinSubstitution([
+    FindPackageShare('my_pkg'), 'config', 'params.yaml'
+])
+```
+
+## 条件启动
+
+```python
+from launch.conditions import IfCondition, UnlessCondition
+
+Node(
+    package='rviz2', executable='rviz2',
+    condition=IfCondition(LaunchConfiguration('use_rviz')),
+)
+
+# CLI: ros2 launch my_robot bringup.launch.py use_rviz:=true
+```
+
+## 启动顺序与延迟
+
+```python
+from launch.actions import TimerAction
+from launch.event_handlers import OnProcessStart
+from launch.actions import RegisterEventHandler
+
+# 方案 A: 固定延时(简单但不优雅)
+TimerAction(period=2.0, actions=[
+    Node(package='nav2_bringup', executable='bringup_launcher')
+])
+
+# 方案 B: 事件驱动(推荐)
+RegisterEventHandler(
+    OnProcessStart(
+        target_action=robot_state_publisher_node,
+        on_start=[
+            Node(package='controller_manager', executable='spawner',
+                 arguments=['joint_state_broadcaster'])
+        ]
+    )
+)
+```
+
+## 包含其他 launch
+
+### Python launch
+
+```python
+IncludeLaunchDescription(
+    PythonLaunchDescriptionSource(
+        PathJoinSubstitution([FindPackageShare('nav2_bringup'),
+                              'launch', 'bringup_launch.py'])),
+    launch_arguments={'use_sim_time': 'true'}.items(),
+)
+```
+
+### XML launch(老式)
+
+```python
+from launch.launch_description_sources import FrontendLaunchDescriptionSource
+
+IncludeLaunchDescription(
+    FrontendLaunchDescriptionSource(
+        PathJoinSubstitution([FindPackageShare('legacy_pkg'),
+                              'launch', 'old.launch.xml']))
+)
+```
+
+## 多机器人 / 命名空间
+
+```python
+robots = [
+    {'name': 'robot1', 'x': '0', 'y': '0'},
+    {'name': 'robot2', 'x': '2', 'y': '0'},
+]
+
+actions = []
+for r in robots:
+    actions.append(GroupAction([
+        PushRosNamespace(r['name']),
+        Node(package='my_robot', executable='controller', name='controller'),
+    ]))
+```
+
+## install 配置(否则 launch 找不到)
+
+`CMakeLists.txt`(ament_cmake 包):
+```cmake
+install(DIRECTORY launch config rviz urdf
+        DESTINATION share/${PROJECT_NAME})
+```
+
+`setup.py`(ament_python 包):
+```python
+data_files=[
+    ('share/' + package_name, ['package.xml']),
+    (os.path.join('share', package_name, 'launch'),
+        glob('launch/*.launch.py')),
+    (os.path.join('share', package_name, 'config'),
+        glob('config/*.yaml')),
+],
+```
+
+## 调试
+
+```bash
+# 列出所有可用 launch
+ros2 pkg list | xargs -I{} ros2 launch --show-args {} 2>/dev/null
+
+# 看 launch 实际展开成什么节点
+ros2 launch my_robot bringup.launch.py --show-args
+
+# 启动后查看节点拓扑
+ros2 node list
+ros2 node info /controller
+ros2 topic list -t
+```
+
+## 常见反模式
+
+| 反模式 | 问题 | 修复 |
+|--------|------|------|
+| 路径硬编码 | 装载到其他机器或 colcon 构建后失效 | `FindPackageShare` |
+| 参数散落 launch 各处 | 难以从外部覆盖,难审计 | 集中到 `config/*.yaml` |
+| 节点重启策略缺失 | 单节点崩溃整个系统挂 | `respawn=True` + 上限 |
+| `use_sim_time` 不传递 | 仿真时间不一致,TF 错乱 | 顶层 LaunchConfiguration 透传到所有 Node |
+| 多 launch 重复 declare 同名参数 | 后者覆盖前者,行为难以预测 | 顶层 declare,子 launch 通过 launch_arguments 接收 |

package/templates/skills/domains/ros2-upper-app/parameters.md

@@ -0,0 +1,192 @@
+# ROS2 参数体系
+
+## 参数三层模型
+
+```
+[CLI / launch override]   最高优先级
+     ↓
+[YAML params_file]        中等
+     ↓
+[declare_parameter 默认值] 最低
+```
+
+## YAML 标准格式
+
+### 节点完整名(/ namespace + 节点名)
+
+```yaml
+# config/params.yaml
+controller:
+  ros__parameters:
+    max_speed: 1.0
+    safe_distance: 0.5
+    enabled_features:
+      - lidar
+      - imu
+
+/robot1/controller:
+  ros__parameters:
+    max_speed: 0.8
+
+# 通配符(rclcpp_components / 多节点共享)
+"/**":
+  ros__parameters:
+    use_sim_time: false
+```
+
+### 嵌套参数(reflected as dotted keys)
+
+```yaml
+controller:
+  ros__parameters:
+    pid:
+      kp: 1.0
+      ki: 0.1
+      kd: 0.01
+```
+
+代码中读:`this->get_parameter("pid.kp")`
+
+## 节点端声明
+
+### C++
+
+```cpp
+class Controller : public rclcpp::Node {
+public:
+  Controller() : Node("controller") {
+    this->declare_parameter<double>("max_speed", 1.0);
+    this->declare_parameter<double>("safe_distance", 0.5);
+    this->declare_parameter<std::vector<std::string>>("enabled_features", {});
+
+    max_speed_ = this->get_parameter("max_speed").as_double();
+    enabled_ = this->get_parameter("enabled_features").as_string_array();
+
+    // 监听运行时变化
+    param_cb_handle_ = this->add_on_set_parameters_callback(
+      [this](const std::vector<rclcpp::Parameter>& params) {
+        rcl_interfaces::msg::SetParametersResult result;
+        result.successful = true;
+        for (const auto& p : params) {
+          if (p.get_name() == "max_speed") {
+            if (p.as_double() < 0) {
+              result.successful = false;
+              result.reason = "max_speed must be >= 0";
+            } else {
+              max_speed_ = p.as_double();
+            }
+          }
+        }
+        return result;
+      });
+  }
+
+private:
+  double max_speed_;
+  std::vector<std::string> enabled_;
+  OnSetParametersCallbackHandle::SharedPtr param_cb_handle_;
+};
+```
+
+### Python
+
+```python
+from rcl_interfaces.msg import SetParametersResult
+
+class Controller(Node):
+    def __init__(self):
+        super().__init__('controller')
+
+        self.declare_parameter('max_speed', 1.0)
+        self.declare_parameter('safe_distance', 0.5)
+        self.declare_parameter('enabled_features', [])
+
+        self.max_speed = self.get_parameter('max_speed').value
+
+        self.add_on_set_parameters_callback(self.on_param_change)
+
+    def on_param_change(self, params):
+        for p in params:
+            if p.name == 'max_speed':
+                if p.value < 0:
+                    return SetParametersResult(
+                        successful=False, reason='must be >= 0')
+                self.max_speed = p.value
+        return SetParametersResult(successful=True)
+```
+
+## 参数描述符(强约束 + 文档化)
+
+```cpp
+auto descriptor = rcl_interfaces::msg::ParameterDescriptor();
+descriptor.description = "Maximum linear speed in m/s";
+
+rcl_interfaces::msg::FloatingPointRange range;
+range.from_value = 0.0;
+range.to_value = 5.0;
+descriptor.floating_point_range.push_back(range);
+
+this->declare_parameter("max_speed", 1.0, descriptor);
+```
+
+效果:`ros2 param set` 超出 [0, 5] 直接拒绝。
+
+## CLI 操作
+
+```bash
+# 列出节点参数
+ros2 param list /controller
+
+# 读
+ros2 param get /controller max_speed
+
+# 写
+ros2 param set /controller max_speed 0.8
+
+# 整体 dump
+ros2 param dump /controller > current.yaml
+
+# 整体 load
+ros2 param load /controller params.yaml
+```
+
+## 在 Launch 中加载
+
+```python
+Node(
+    package='my_robot',
+    executable='controller_node',
+    name='controller',
+    parameters=[
+        # 1. 来自 YAML
+        PathJoinSubstitution([FindPackageShare('my_robot'),
+                              'config', 'params.yaml']),
+        # 2. 命令行覆盖单项
+        {'max_speed': LaunchConfiguration('max_speed')},
+        # 3. 强制 use_sim_time
+        {'use_sim_time': use_sim_time},
+    ],
+)
+```
+
+注意:**列表后面的覆盖前面的**。
+
+## 命名约定
+
+| 类型 | 风格 |
+|------|------|
+| 简单标量 | `snake_case`: `max_speed` |
+| 嵌套组 | `pid.kp`, `pid.ki` |
+| 频率 | `update_rate_hz` (单位写在名里) |
+| 启用开关 | `enable_<feature>` 或 `<feature>.enabled` |
+| 阈值 | `min_<x>` / `max_<x>` / `<x>_threshold` |
+
+## 反模式
+
+| 反模式 | 后果 |
+|--------|------|
+| 不 declare 直接 get | 抛 `ParameterNotDeclaredException` |
+| 在构造函数读完就忘了 | 运行时改参数无效 — 用 set 回调 |
+| 不同节点参数命名风格混乱 | 难维护、难审计 |
+| 把硬件路径写死(`/dev/ttyUSB0`) | udev 编号变化即崩 — 改成参数 + udev rules |
+| 把超大数据(图像、点云)塞参数 | 参数服务器不是为大数据设计的 — 用 topic |