ros2-code-analyzer

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：单节点深度分析

步骤

1. 识别系统类型

   • Grep rclcpp::Node / LifecycleNode（标准 ROS2）
   • Grep InterProcessPollingSubscriber（Autoware）
   • Grep cyber::Component / CreateReader（Apollo）
   • 详细搜索关键词见 references/ros2_patterns.md

2. 定位节点入口

   • 找到节点类定义（.hpp/.cpp）
   • 确认 CMakeLists.txt 中的注册方式
   • 检查 launch 文件中的启动配置

3. 运行函数级分析脚本

   python3 scripts/analyze_node_functions.py \
     --source-dir <package_path> \
     -o /tmp/ros2_analysis/node_functions.json
   

4. AI 阅读源码补全

   • 检查脚本是否遗漏了回调（常量/模板/继承模式）
   • 参考 references/ai_verification_patterns.md
   • 修正函数调用关系

5. 梳理外部接口

   • 所有 subscription（输入）
   • 所有 publisher（输出）
   • service/action（服务接口）
   • parameter（配置参数）
   • timer（定时触发）

6. 追踪数据流

   • 回调接收数据 → 处理 → 发布
   • 注意参数对行为的影响

7. 理解核心算法

   • 展开关键函数的处理逻辑
   • 记录算法分支条件

8. 生成输出

   • 结构化 Markdown → 运行 generate_mindmap.py 生成交互式思维导图
   • 或直接展示函数调用图 JSON

---

模式 B：系统级分析

阶段一：自动提取

1. 确定工作区根目录

   • 用户给的路径向上找到包含多个 package.xml 的 src 目录
   • 确认目标 package 名称

2. 运行启动链路追溯

   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（节点连接）

3. 运行函数级批量分析

   python3 scripts/analyze_node_functions.py \
     --connections /tmp/ros2_analysis/connections.json \
     --workspace <workspace_src_path> \
     --output-dir /tmp/ros2_analysis/functions/
   

4. 检查输出统计

   • 节点总数、已连接数、孤立节点数
   • 函数分析成功/失败数
   • 如果孤立节点 > 30%，可能工作区路径不对或 launch 文件有 Python 格式

阶段二：AI 校验（HARD-GATE）

1. 检查孤立节点

   • 阅读源码确认是否有 topic 遗漏（正则无法覆盖的 C++ 模式）
   • 常见遗漏：常量名 topic、模板参数化、基类继承、pluginlib 插件
   • 详见 references/ai_verification_patterns.md

2. 检查低连接节点

   • 连接数 < 2 的非工具节点，阅读源码补全

3. 检查关键节点的函数提取

   • 核心模块（Planning/Perception/Control）的节点，确认回调和发布点正确

4. 写回 connections.json

   • 补全遗漏的 topic 后，更新 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              生成后自动打开浏览器

---

完成标准

• 覆盖率 >= 80%（已连接节点 / 总节点）
• 核心路径无断点：Sensing → Localization → Perception → Planning → Control → Vehicle
• 孤立节点已处理：全部在白名单中，或已检查源码
• 互斥对已标注：条件启动的节点在图中有红色虚线
• HTML 可正常打开：节点关系图 + 思维导图均渲染正确
• 函数钻入可用（如提供了 --functions-dir）：双击节点弹出调用图
• 向用户报告统计：总节点数、连接数、孤立数、覆盖率

---

参考文档

• references/ros2_patterns.md — ROS2 代码搜索模式速查（grep 关键词、launch 格式、组件注册）
• references/ai_verification_patterns.md — 脚本无法处理的 C++ 模式（常量、模板、继承、pluginlib 等）及 AI 检查清单