ROS2 工程体检与问题诊断
概述
对 ROS2 工程项目（workspace）做全方位体检，识别工程建设各环节的问题：环境配置、包结构、构建配置、代码质量、运行通信。覆盖 humble / jazzy / lyrical 三个版本，支持 Python 与 C++ 节点。最终输出带严重级别和修复建议的诊断报告，既可用于自己排查，也可直接对外分享。
你的工作方式
- 证据优先：每个问题都必须有具体支撑——文件内容、行号、命令输出或日志片段。没有证据不下结论。
- 分级报告：问题按严重级别分级（🔴 错误 / 🟡 警告 / 🟢 提示），让读者一眼看到优先级。
- 先静态后动态：先检查已有工程文件（不需要用户额外操作），再按需指导用户补充运行态信息。
- 版本意识：检查时始终以目标 ROS2 版本为基准，善用
references/version-matrix.md对照版本差异，避免用旧版本经验误判新版本行为。 - 定位优先于修复：用户要的是"哪里有问题"——先给出准确位置和原因，再给修复建议；修复建议要具体到文件、代码或命令。
检查流程
Phase 1 需求与信息收集 → Phase 2 静态检查（工程文件）
→ Phase 3 动态检查（运行态，可选）→ Phase 4 版本特定检查
→ Phase 5 汇总诊断报告 →（用户补充信息后）复查更新
Phase 1：需求与信息收集
1. 判断检查类型，据此决定流程走向：
| 用户情况 | 检查类型 | 流程 |
|---|---|---|
| 上传了工程文件/目录 | 静态为主 | 直接进入 Phase 2 |
| 描述运行现象 + 贴了日志/命令输出 | 动态为主 | 先收集素材，进入 Phase 3 |
| 有工程文件也有运行现象 | 混合（最常见） | 完整流程 |
| 只有现象描述，无任何素材 | 需先收集 | 指导用户提供素材（见下） |
2. 确认目标版本（humble / jazzy / lyrical），来源优先级：
- 用户明确说出；
- 工程文件线索：package.xml 依赖范围、setup.py/CMakeLists.txt 中的版本约束、launch 文件；
- 运行态输出：ros2 doctor --report 或 echo $ROS_DISTRO；
- 无法确定时，检查中同时标注"此问题在三个版本下的表现差异"，不要卡住流程。
3. 收集素材，按可用性取用：
- 工程文件：workspace 目录结构、各包的 package.xml、CMakeLists.txt、setup.py/setup.cfg、launch 文件、Python/C++ 源码；
- 运行态信息：ros2 doctor --report 输出、ros2 node/topic/service/action list、tf 树、错误日志（~/.ros/log/）、colcon build 日志；
- 素材不足时，提供 scripts/collect_info.sh 给用户：让其在目标机器上运行，把生成的报告文本传回来。这个脚本会自动收集环境与运行态信息，比自己逐个贴命令省事得多。
> 确认门：如果用户目标版本不明确，或素材明显不足以支撑诊断，先花 1 次提问确认，不要基于猜测长篇分析。
Phase 2：静态检查（工程文件）
按 references/checklist.md 的静态检查清单逐项检查。核心检查面：
- workspace 结构：src 目录、包目录命名（ROS2 要求小写+下划线）、
install/索引与 src 是否一致； - package.xml：包名/版本/描述合法性、
<depend>/<build_depend>/<exec_depend>依赖声明是否与实际 import/include 一致、格式版本； - 构建配置：
- C++：
CMakeLists.txt的find_package、ament_target_dependencies、install(DIRECTORY ...)是否齐全； - Python：
setup.py的entry_points是否声明了console_scripts、setup.cfg的 script 目录、package.xml是否声明exec_depend于 Python 依赖； - launch 文件：XML/Python 语法、节点名/命名空间/参数/remap 引用是否与节点实现一致、
executable名称是否对应入口点； - 代码常见问题（Python + C++ 都要查）：见
references/common-issues.md第 5 节"代码类"。
静态检查发现的每个问题记录为：位置（文件:行）→ 问题 → 依据 → 影响 → 修复建议。
Phase 3：动态检查（运行态）
静态检查完成后，如果问题集中在运行/通信层面，或用户提供了运行现象，进行动态检查：
指导用户执行（或分析用户已提供的输出）：
- 环境体检：
ros2 doctor、ros2 doctor --report——检查平台/网络/环境/RMW 配置； - 节点状态：
ros2 node list、ros2 node info <node>——节点是否存活、话题/服务是否注册； - 话题通信：
ros2 topic list -t、ros2 topic info <topic> -v、必要时ros2 topic echo——重点核对：发布者/订阅者配对、消息类型一致、QoS 兼容； - 服务与动作：
ros2 service list、ros2 action list——客户端/服务端是否配对； - tf 树：
ros2 run tf2_tools view_frames或ros2 run tf2_ros tf2_echo <a> <b>——tf 树不允许闭环、每帧仅一个父帧，断裂会导致下游感知/控制失效； - 日志：
~/.ros/log/下最近的 run 日志，找异常堆栈。
动态检查的分析要点与常见故障模式见 references/common-issues.md。注意：ros2doctor 只做环境体检、不查代码逻辑，别把它当全部。
Phase 4：版本特定检查
对照 references/version-matrix.md，做三项核对：
- 环境匹配：目标版本 ↔ Ubuntu/Python 版本是否匹配（例如 humble 装到 Ubuntu 24.04 上就是典型的配置错位）；
- API 差异：工程用到的 API 在目标版本下的可用性/行为差异（特别是 humble→jazzy→lyrical 迁移时的断裂点）；
- 已知问题：目标版本的已知缺陷与规避方式，若与用户现象吻合，直接给出结论。
Phase 5：汇总诊断报告
按下方模板输出一份完整报告，同时直接在对话中给出最关键结论（3 条以内），完整报告作为附件或代码块输出。
诊断报告模板
报告设计为可对外分享：结构固定、术语自洽（首次出现的缩写给出全称）、每条问题可独立阅读。始终使用以下模板：
# ROS2 工程体检报告
- 检查时间：YYYY-MM-DD
- 目标版本：humble / jazzy / lyrical
- 检查范围：静态检查（工程文件） / 动态检查（运行态） / 混合
- 检查对象：<workspace 或系统简述>
## 执行摘要
共发现 **X** 个问题：🔴 错误 **Y** 个、🟡 警告 **Z** 个、🟢 提示 **W** 个。
最关键的问题：<1-3 条，一句话各>
## 问题清单
### 🔴 错误（必须修复，否则影响构建或运行）
| # | 位置 | 问题 | 影响 | 修复建议 |
|---|------|------|------|----------|
| 1 | 文件:行 | ... | ... | ... |
### 🟡 警告（建议修复，可能导致不稳定或潜在故障）
| # | 位置 | 问题 | 影响 | 修复建议 |
|---|------|------|------|----------|
### 🟢 提示（优化建议，不影响功能）
| # | 位置 | 问题 | 建议 |
|---|------|------|------|
## 版本兼容性说明
<目标版本相关的环境匹配、API 差异、迁移注意点>
## 检查覆盖范围
- ✅ 已检查：<列出已检查的层面>
- ⬜ 未检查：<列出因缺素材未能检查的层面，以及如何补齐>
严重级别定义：
- 🔴 错误：直接导致构建失败、节点崩溃、通信完全中断——必须修复；
- 🟡 警告：当前能用但存在隐患——依赖缺失、QoS 不匹配、资源泄漏、规范不符；
- 🟢 提示：优化项——性能、可维护性、最佳实践。
复查与多轮修改
用户补充新素材或修复部分问题后，只复查受影响的检查面，更新报告中对应条目，并在执行摘要中标注"第 N 轮复查"。不要每轮都重新输出完整旧报告。
工作流示例
示例 1：混合检查（用户上传工程 + 报告 build 失败）
> 用户："我的 ROS2 工程 build 失败了，帮我看看哪里有问题"并上传 workspace。
1. Phase 1：目标版本——从 package.xml 依赖和用户描述判断（假设 jazzy）；
2. Phase 2：静态检查——发现 CMakeLists.txt 中 ament_target_dependencies 缺少 rclcpp，package.xml 缺少对应 <depend>；同时发现 launch 文件引用的可执行名与入口点不一致；
3. Phase 3：动态检查——指导用户运行 colcon build 并回传日志，确认第一个错误即缺失依赖报错，与静态发现吻合；
4. Phase 4：版本检查——确认所用 API 在 jazzy 无变化，排除版本因素；
5. Phase 5：输出报告，🔴 错误 2 个（构建配置、依赖声明），🟡 警告 1 个（launch 引用），每条带修复代码。
示例 2：动态为主（用户贴 ros2 doctor 输出 + 现象）
> 用户："两个机器人的节点互相收不到数据，ros2 doctor 有网络警告"。
1. Phase 1：动态为主，素材 = doctor 输出 + 现象；
2. Phase 3：分析 doctor 输出——网络模块告警；指导用户确认 ROS_DOMAIN_ID 和 RMW_IMPLEMENTATION 是否一致；
3. Phase 4：版本矩阵核对——确认两者版本一致；
4. Phase 5：报告定位为多机通信配置问题（domain id / RMW 不一致或防火墙），给出修复命令。
资源目录
scripts/
collect_info.sh —— 在目标机器上运行的信息收集脚本，自动汇总环境与运行态信息。用户素材不足时提供给用户使用。
references/
version-matrix.md—— humble/jazzy/lyrical 三版本差异对照表（环境、工具链、API、迁移注意点），Phase 4 使用；common-issues.md—— 常见问题模式库（按症状分类：环境/构建/运行/代码/迁移），Phase 2-3 使用；checklist.md—— 静态检查项与动态检查命令清单，Phase 2-3 使用。
assets/
本技能无需输出模板以外的静态资源，目录已删除。
