| name | ros2-code-analyzer |
| description | 系统化分析 ROS2 功能包或基于 ROS2 的系统（Autoware、Apollo、自研系统等）。两层递进式分析：宏观层梳理启动链路和节点关系图（不丢节点、不丢输入输出），微观层分析每个节点内部的函数调用流程。最终生成可交互 HTML：节点流程图 + 双击节点查看内部函数级调用图。当用户想分析 ROS2 代码、理解功能包结构、梳理节点连接、分析 launch 文件、追溯启动链路、查看节点关系图、理解某个模块内部实现时，务必使用此技能。即使用户只说'帮我看看这个模块'或'分析一下这个 package'或'画个节点图'或'这个节点怎么工作的'，只要目标是 ROS2 项目，就应该触发。 |
ROS2 代码分析器
两层递进式分析任何 ROS2 系统的代码：
- 宏观层：启动链路 → 节点关系图 → 数据流向（全部节点、全部输入输出）
- 微观层：节点内部 → 回调函数 → 调用链 → 算法细节
适用范围：标准 ROS2（rclcpp/rclpy）、Autoware、Apollo（CyberRT）、任何基于 ROS2 的系统。
模式选择
| 用户给出的 | 选择 | 输出 |
|---|
| 一个 package 路径 | 模式 A：单节点深度分析 | 思维导图 + 函数调用图 |
| 一个目录 / package 名 / 要求分析启动链路 | 模式 B：系统级分析 | 节点关系图 + 函数钻入 |
HARD-GATE
脚本输出后，不得直接生成最终可视化。必须先完成 AI 校验：
- 孤立节点 <= 20 个：全部检查源码
- 孤立节点 > 20 个：检查全部白名单外的，采样 top-10（优先核心模块 Perception/Planning/Control 中的节点）
- 连接数 < 2 的非工具节点：检查 top-5
- 白名单（直接跳过）：rviz2, robot_state_publisher, static_transform_publisher, component_container*, glog_component, topic_tools/*
校验后将补全结果写回 connections.json，再生成可视化。
模式 A：单节点深度分析
步骤
-
识别系统类型
- Grep
rclcpp::Node / LifecycleNode（标准 ROS2）
- Grep
InterProcessPollingSubscriber（Autoware）
- Grep
cyber::Component / CreateReader（Apollo）
- 详细搜索关键词见
references/ros2_patterns.md
-
定位节点入口
- 找到节点类定义（.hpp/.cpp）
- 确认 CMakeLists.txt 中的注册方式
- 检查 launch 文件中的启动配置
-
运行函数级分析脚本
python3 scripts/analyze_node_functions.py \
--source-dir <package_path> \
-o /tmp/ros2_analysis/node_functions.json
-
AI 阅读源码补全
- 检查脚本是否遗漏了回调（常量/模板/继承模式）
- 参考
references/ai_verification_patterns.md
- 修正函数调用关系
-
梳理外部接口
- 所有 subscription（输入）
- 所有 publisher（输出）
- service/action（服务接口）
- parameter（配置参数）
- timer（定时触发）
-
追踪数据流
- 回调接收数据 → 处理 → 发布
- 注意参数对行为的影响
-
理解核心算法
-
生成输出
- 结构化 Markdown → 运行
generate_mindmap.py 生成交互式思维导图
- 或直接展示函数调用图 JSON
模式 B：系统级分析
阶段一：自动提取
-
确定工作区根目录
- 用户给的路径向上找到包含多个
package.xml 的 src 目录
- 确认目标 package 名称
-
运行启动链路追溯
python3 scripts/trace_launch_chain.py \
--workspace <workspace_src_path> \
--package <target_package> \
--output-dir /tmp/ros2_analysis/
输出：chain.json（结构化链路）、chain.md（Markdown）、connections.json（节点连接）
-
运行函数级批量分析
python3 scripts/analyze_node_functions.py \
--connections /tmp/ros2_analysis/connections.json \
--workspace <workspace_src_path> \
--output-dir /tmp/ros2_analysis/functions/
-
检查输出统计
- 节点总数、已连接数、孤立节点数
- 函数分析成功/失败数
- 如果孤立节点 > 30%，可能工作区路径不对或 launch 文件有 Python 格式
阶段二：AI 校验（HARD-GATE）
-
检查孤立节点
- 阅读源码确认是否有 topic 遗漏（正则无法覆盖的 C++ 模式）
- 常见遗漏：常量名 topic、模板参数化、基类继承、pluginlib 插件
- 详见
references/ai_verification_patterns.md
-
检查低连接节点
-
检查关键节点的函数提取
- 核心模块（Planning/Perception/Control）的节点，确认回调和发布点正确
-
写回 connections.json
阶段三：可视化生成
python3 scripts/generate_node_graph.py \
/tmp/ros2_analysis/connections.json \
--markdown /tmp/ros2_analysis/chain.md \
--functions-dir /tmp/ros2_analysis/functions/ \
-o /tmp/ros2_analysis/viewer.html \
--title "<target_package> 启动链路分析" \
--open
验证 HTML：
- 节点关系图：所有节点可见，topic 连接正确
- 搜索高亮：输入关键词能正确高亮相关节点和边
- 双击钻入：双击节点弹出函数调用图（入口蓝→回调绿→方法灰→发布黄）
- 思维导图：Tab 切换查看启动链路层级
错误处理
| 错误 | 原因 | 解决 |
|---|
| 脚本报错退出 | Python 版本 < 3.8 或路径错误 | 检查 python3 --version 和路径 |
| 0 个节点 | 工作区路径不对或没有 .launch.xml | 确认 src 目录下有 package.xml |
| 孤立节点 > 50% | 大量 .launch.py（脚本仅部分支持） | AI 手动补全关键节点 |
| Graphviz 未安装 | 系统缺少 dot 命令 | sudo apt install graphviz |
| 函数分析全失败 | 找不到 C++ 源码或类名不匹配 | 手动指定 --class-name |
| HTML 打开空白 | SVG 渲染失败 | 检查 stderr 输出的错误信息 |
脚本 CLI 参考
trace_launch_chain.py
--workspace PATH ROS2 工作区 src 目录
--package NAME 目标 package 名称
--output-dir PATH 输出目录（默认 /tmp/ros2_analysis/）
analyze_node_functions.py
单节点：--source-dir PATH [--class-name NAME] -o FILE
批量： --connections FILE --workspace PATH [--output-dir PATH]
generate_node_graph.py
INPUT connections.json 文件路径
--markdown FILE 可选，chain.md（提供则生成思维导图 Tab）
--functions-dir DIR 可选，函数分析 JSON 目录（提供则支持双击钻入）
-o FILE 输出 HTML 路径
--title TEXT 页面标题
--open 生成后自动打开浏览器
generate_mindmap.py
INPUT Markdown 文件路径
-o FILE 输出 HTML 路径
--title TEXT 页面标题
--max-width PX 节点最大宽度（默认 400）
--open 生成后自动打开浏览器
完成标准
参考文档
references/ros2_patterns.md — ROS2 代码搜索模式速查（grep 关键词、launch 格式、组件注册）references/ai_verification_patterns.md — 脚本无法处理的 C++ 模式（常量、模板、继承、pluginlib 等）及 AI 检查清单
