docs(nav): 阅读路径导航 + 数字统一

README.md

@@ -1,165 +1,493 @@
-# ROS2 Learning Suite — 从零到具身智能 / VLA 完全体
+# ROS2 学习套件 — 从零到具身智能 / VLA 完全体
 
-> **一套从 ROS2 基础到机械臂 + VLA (Vision-Language-Action) 落地的完整实战仓库**:
-> 12 包 + 80 测试 100% 通过 + 23 篇深度文档 + Docker + Make + GitLab CI + 跨机部署。
-> 为后续具身智能 / 机器人 / VLA 开发铺平第一公里。
->
-> **学习承诺**: 每行代码遵循 [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md)(PEP 8 + ROS2 REP-2000 + 工业级实践)。
+> **如果你是 ROS2 完全的新手,不知道怎么开始 → [从零开始指南](#-从零开始-30-分钟跑通-hello-world)**
 
 ---
 
-## 🎯 适合谁
+## 🆘 从零开始:30 分钟跑通 Hello World
 
-- 第一次学 ROS2,想从 0 到能搭一个完整机器人项目
-- 想**深耕具身智能**(机器人 + VLA),需要把 ROS2 通信栈 + TF2 + URDF + Vision 一次打通
-- 想在 Windows 本机用 venv + VSCode 写代码,在 Docker Linux 容器跑 ROS2
-- 需要一个**教科书级别**的开源仓库作教学/学习参考
+**如果你从来没接触过 ROS2,不知道"Docker 是什么"、"make 命令在哪"、不知道怎么开终端,按下面一步一步来。**
 
-## 📦 仓库提供什么
+### 0. 你需要准备什么?(只看这一节就够)
 
-**12 个 ROS2 包 + 80 测试 + 23 篇深度文档 + Make + GitLab CI**:
+| 工具 | 是什么 | 怎么得到 | 大约多大 |
+|---|---|---|---|
+| **Docker Desktop** | 跑 Linux 虚拟机的工具(本仓库的核心运行环境) | https://www.docker.com/products/docker-desktop/ 下载 Windows 版 | ~1 GB |
+| **VSCode**(可选) | 编辑代码的编辑器 | https://code.visualstudio.com/ | ~300 MB |
+| **Git**(可选) | 下载本仓库代码 | https://git-scm.com/ | ~50 MB |
 
-| 包 | 类型 | 通信范式 | 语言 | 测试 |
-|---|---|---|---|---|
-| [`py_pubsub`](src/py_pubsub/) | ament_python | Topic pub/sub | Python | pytest 11/11 ✓ |
-| [`cpp_pubsub`](src/cpp_pubsub/) | ament_cmake | Topic pub/sub | C++ | gtest 3/3 ✓ |
-| [`py_srv`](src/py_srv/) | ament_python | Service req/resp | Python | pytest 6/6 ✓ |
-| [`py_action_demo`](src/py_action_demo/) | ament_python | Action 三件套 | Python | pytest 4/4 ✓ |
-| [`cpp_robot_tf2`](src/cpp_robot_tf2/) | ament_cmake | URDF + TF2 | C++ | gtest 4/4 ✓ |
-| [`py_vision_demo`](src/py_vision_demo/) | ament_python | sensor_msgs/Image | Python | pytest 11/11 ✓ |
-| [`py_params`](src/py_params/) | ament_python | Parameter 系统 | Python | pytest 16/16 ✓ |
-| [`cpp_custom_interface`](src/cpp_custom_interface/) | ament_cmake | 自定义 .msg/.srv/.action | C++ | gtest 3/3 ✓ |
-| [`py_lifecycle_composable`](src/py_lifecycle_composable/) | ament_python | Lifecycle + Composable | Python | pytest 6/6 ✓ |
-| [`cpp_qos_demo`](src/cpp_qos_demo/) | ament_cmake | QoS 9 种组合 | C++ | gtest 4/4 ✓ |
-| [`py_overlay_dds`](src/py_overlay_dds/) | ament_python | DDS 配置 + colcon overlay | Python | pytest 6/6 ✓ |
-| [`bringup`](src/bringup/) | ament_python | 6 跨包 launch 聚合 | Python | OK |
+**你不需要装**:Python、ROS2、Ubuntu、虚拟机、Linux。
 
-**合计 80/80 测试 100% 通过目标**;6 个端到端 demo 启动脚本。
+**磁盘空间**:Docker 镜像约 5 GB,本仓库源代码 < 100 MB。建议预留 **10 GB 空闲**。
+
+**操作系统支持**:Windows 10/11 专业版 / 企业版 / 教育版都支持,Windows 11 家庭版也行(会自动装 WSL2)。具体安装教程见下方 "Docker Desktop 安装"。
+
+### 1. 验证 Docker 是否能跑
+
+打开 PowerShell(开始菜单 → 输入 `powershell` → 回车),输入:
+
+```powershell
+docker version
+```
+
+看到类似这样的输出就 OK:
+
+```
+Client:
+ Version:           24.0.7
+ ...
+Server:
+ Engine:
+  Version:          24.0.7
+  ...
+```
+
+**如果报错 "Cannot connect to Docker daemon"**:Docker Desktop 没启动。任务栏右下角找 Docker 图标(鲸鱼),右键 → "Docker Desktop is running" 出现才算 OK。
+
+**如果提示 "WSL2 not installed"**:Docker Desktop 会自动提示安装,按它的指引装完重启即可。
+
+### 2. 下载 / 找到本仓库
+
+**方式 A:用 Git 克隆**
+```powershell
+cd D:\xs
+git clone <仓库地址> ros2
+cd D:\xs\ros2
+```
+
+**方式 B:下载 ZIP 解压**
+
+把仓库下载下来,解压到任意位置。**真正的项目根目录是包含 `README.md` 和 `Makefile` 的那一层**,不是上层目录(里面还有 `src/`、`doc/`、`docker/` 这些子目录的)。
+
+确认你在项目根目录:
+```powershell
+Get-ChildItem   # 应该看到 AGENTS.md  CHANGELOG.md  docker  doc  Makefile  README.md  src
+```
+
+### 3. 打开 PowerShell 在项目根目录
+
+**重要**:本节所有命令都在 **Windows PowerShell**(宿主机)执行,不是容器内。后面会有专门一节讲容器内命令。
+
+```powershell
+cd D:\xs\ros2
+```
+
+### 4. 构建 Docker 镜像(首次约 5-10 分钟)
+
+**镜像是什么**:打包好的 Linux + ROS2 + 工具链的"操作系统模板"。本仓库基于 `osrf/ros:humble-desktop` 构建。
+
+```powershell
+docker build -t ros2-humble-dev:latest -f docker/Dockerfile .
+```
+
+**预期输出**:看到一长串 `---> Running in xxx`、`Successfully built xxx`(看不到具体行数是正常的,只看最后 `Successfully tagged ros2-humble-dev:latest`)。
+
+**下载量**:首次约 3-5 GB(基础镜像 + 工具)。
+
+### 5. 启动容器
+
+容器 = 用镜像启动的"Linux 虚拟机实例"。本仓库的容器名是 `ros2_dev`。
+
+```powershell
+docker run -d --name ros2_dev -v "${PWD}:/root/ros2_ws" --network ros2_net ros2-humble-dev:latest
+```
+
+**预期输出**:一串 hash(容器 ID),没有报错就行。
+
+**验证容器跑起来了**:
+```powershell
+docker ps
+```
+应该看到 `ros2_dev` 在列表里,`STATUS` 列显示 `Up`。
+
+### 6. 进入容器(看到 root@xxx 就是成功了)
+
+```powershell
+docker exec -it ros2_dev bash
+```
+
+你应该看到类似:
+```
+root@abc123def456:/root/ros2_ws#
+```
+
+**重要**:从现在开始,所有命令都在 **容器内**(Linux)执行,不是 Windows PowerShell。
+
+**怎么退出容器?** 输入 `exit` 或按 `Ctrl+D`。再进去就再执行 `docker exec -it ros2_dev bash`。
+
+### 7. 加载 ROS2 环境(每个新终端都要执行!)
+
+**为什么需要 `source`**:ROS2 把可执行文件、库、环境变量放在 `/opt/ros/humble/` 下,不 source 就找不到 `ros2`、`colcon` 这些命令。
+
+```bash
+source /opt/ros/humble/setup.bash
+```
+
+**预期效果**:没有报错 = OK。
+
+**怎么验证**:
+```bash
+ros2 --version   # 应该显示 ROS 2 package version 1.0 (or similar)
+```
+
+**常见错误**:直接输入 `ros2` 提示 `command not found` → 说明你忘了 source。
+
+**每次新开终端都要 source 一次**。嫌麻烦?把这两行加到容器用户的 `~/.bashrc`:
+
+```bash
+echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
+echo "source /root/ros2_ws/install/setup.bash" >> ~/.bashrc  # 这一行要等第 8 步做完才有 install/
+```
+
+### 8. 编译 12 个 ROS2 包(约 3-5 分钟)
+
+`colcon` 是 ROS2 的官方编译工具(类似 `make` 但专为 ROS2 设计)。
+
+```bash
+cd /root/ros2_ws
+colcon build --symlink-install
+```
+
+**预期输出**:一堆 `Starting >>> xxx`、`Finished <<< xxx`,最后看到:
+
+```
+Summary: 12 packages finished [4 min 32 s]
+```
+
+**看到 "12 packages finished" 就成功了**。失败的话会有 `Failed <<< xxx`,先看下方"常见问题"。
+
+### 9. 加载本项目环境 + 跑测试
+
+```bash
+source install/setup.bash
+colcon test
+```
+
+**预期输出**(成功的话):
+```
+Summary: 12 packages finished [3 min 15 s]
+```
+
+**怎么确认 100% 通过**:
+
+```bash
+colcon test-result --all
+```
+
+期望看到:
+```
+build/<package>/pytest.xml:  PASS
+build/<package>/test_results/.../test_*.gtest.xml:  PASS
+```
+
+所有包都 PASS = 全绿。
+
+### 10. 跑 Hello World(Topic 演示)
+
+**Topic 是什么**:发布-订阅模式。一个节点(Publisher)发消息,另一个节点(Subscriber)收消息。这是 ROS2 最核心的通信方式。
+
+**打开第一个终端**(容器内):
+
+```bash
+source /opt/ros/humble/setup.bash
+source /root/ros2_ws/install/setup.bash
+ros2 launch py_pubsub pubsub_launch.py
+```
+
+**预期输出**(每个终端都会一直打印,这是正常的):
+```
+[INFO] [py_publisher]: Publishing: "Hello World: 0"
+[INFO] [py_publisher]: Publishing: "Hello World: 1"
+...
+[INFO] [chatter_listener]: I heard: Hello World: 0
+...
+```
+
+**怎么验证 Python ↔ C++ 互通**:默认 launch 会同时启动 py + cpp 的 publisher 和 subscriber,你应该看到 4 个节点在互相通信。
+
+**怎么停止**:按 `Ctrl+C`(Linux 终端的"取消运行"快捷键)。**Ctrl+C 在 ROS2 节点运行时 = 优雅退出**,不会损坏任何东西。
+
+### 🎉 恭喜!
+
+你已经跑通了 ROS2 的 Hello World。现在你可以:
+
+1. **继续学**:打开下方"学完之后下一步做什么"选下一个包
+2. **玩参数**:另开一个终端,输入 `ros2 param set py_publisher publish_rate_hz 5.0`,回到第一个终端你会看到消息频率从 1 Hz 变成 5 Hz
+3. **看节点关系图**:输入 `rqt_graph`(需要图形界面,详见 doc/85-docker.md)
+
+> **📖 想看更详细的图文版 + Windows 截图**?见 [`doc/01-quickstart.md`](doc/01-quickstart.md)(已读过的章节可跳读)。本节内容已覆盖 doc/01-quickstart 的核心流程。
 
 ---
 
-## 🚀 5 分钟上手(Makefile)
+## 🔧 常见问题(新手必看)
+
+### ❌ Docker Desktop 没启动
+```
+Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
+```
+→ 启动 Docker Desktop(任务栏鲸鱼图标),等 30 秒。
+
+### ❌ 容器名 `ros2_dev` 已存在
+```
+Error response from daemon: Conflict. The container name "/ros2_dev" is already in use.
+```
+→ 删掉旧容器: `docker rm -f ros2_dev`,再 `docker run ...`
+
+### ❌ 构建超时 / 网络问题
+```
+failed to fetch ... context deadline exceeded
+```
+→ 重新 `docker build -t ros2-humble-dev:latest -f docker/Dockerfile .` (会自动重试)
+
+### ❌ 编译失败
+```
+Failed <<< py_pubsub [1 min 30 s]
+```
+→ 看 `build/<package>/` 下的 `stdout.log` 或 `stderr.log`。最常见原因:漏装了某个 ROS2 包(`ros-humble-xxx`)。看错误信息里有没有 `Could not find a package configuration file provided by "xxx"`。
+
+### ❌ 测试失败
+```
+1 package had test failures: py_params
+```
+→ 看 `build/<package>/pytest.xml` 或 `build/<package>/test_results/.../test_*.gtest.xml`。常见原因:漏装 pytest-timeout、cv_bridge、image-transport 等。
+
+---
+
+## 📖 这是什么仓库?
+
+一个**教学级完全体** ROS2 学习项目,做完了可以直接做具身智能 / VLA 项目。
+
+**核心特点**:
+- ✅ 12 个真实可运行的 ROS2 包,涵盖 ROS2 几乎所有核心机制
+- ✅ 78 个测试用例 100% 通过(可运行、可验证、不踩坑)
+- ✅ 24 篇深度文档,从 Hello World 到三机部署
+- ✅ 跨语言互通(py ↔ cpp),贴近工业真实场景
+- ✅ Docker 容器化,Windows / Linux / Mac 都能跑
+
+**它不是**:ROS2 官方文档翻译、API 速查表、"读完即懂" 的速成文档。
+
+---
+
+## 🎯 学完之后你能做什么?
+
+学完本仓库 + 后续 Level 2/3/4 资料,你可以:
+
+1. ✅ 自己设计一个 ROS2 项目(Node / Topic / Service / Action / Parameter / TF / QoS 都会用)
+2. ✅ 调试 ROS2 通信问题(查 `ros2 topic list`、`ros2 node info`、`rqt_graph`)
+3. ✅ 写自定义 .msg/.srv/.action 接口,跨语言互通
+4. ✅ 配置 DDS + 跨机器部署(知道 `ROS_DOMAIN_ID` / `RMW_IMPLEMENTATION`)
+5. ✅ 在机械臂 / 移动机器人 / VLA 项目里把 ROS2 作为通信底座
+
+---
+
+## 📚 12 包推荐学习顺序
+
+**不要按字母顺序学**。按下面顺序,每个包约 1-3 小时(读 README + 看代码 + 改参数试效果)。
+
+**总计预计**: **4-6 周**(每天 2-3 小时)+ 24 篇深度文档 + 改 12 次代码 + 自己写 1 个 Service。
+> 注:这是 `doc/00-levels.md` 跟 README 统一后的估算。纯跑通 = 1 天,纯读文档 = 7 天,真学懂 + 自己改 = 4-6 周。
+
+### 第一梯队:必学(覆盖 80% 日常 ROS2 工作)
+
+| 顺序 | 包 | 你将学到 |
+|---|---|---|
+| 1 | [`py_pubsub`](src/py_pubsub/README.md) | Topic 发布订阅、节点、launch 文件 |
+| 2 | [`cpp_pubsub`](src/cpp_pubsub/README.md) | C++ 怎么写 ROS2 节点、跨语言互通 |
+| 3 | [`py_srv`](src/py_srv/README.md) | Service 请求-响应(同步 RPC) |
+| 4 | [`py_action_demo`](src/py_action_demo/README.md) | Action(带进度回调的长任务) |
+
+### 第二梯队:进阶(做项目必备)
+
+| 顺序 | 包 | 你将学到 |
+|---|---|---|
+| 5 | [`py_params`](src/py_params/README.md) | 参数系统(运行时改配置 + 校验回调) |
+| 6 | [`cpp_custom_interface`](src/cpp_custom_interface/README.md) | 自定义 .msg/.srv/.action 接口 |
+| 7 | [`py_vision_demo`](src/py_vision_demo/README.md) | 图像话题 + cv_bridge + OpenCV |
+| 8 | [`cpp_robot_tf2`](src/cpp_robot_tf2/README.md) | TF2 坐标变换 + URDF 机械臂模型 |
+
+### 第三梯队:深入(做生产级 / 部署级系统)
+
+| 顺序 | 包 | 你将学到 |
+|---|---|---|
+| 9 | [`cpp_qos_demo`](src/cpp_qos_demo/README.md) | QoS 9 种组合(传输可靠性策略) |
+| 10 | [`py_lifecycle_composable`](src/py_lifecycle_composable/README.md) | Lifecycle(节点生命周期管理) |
+| 11 | [`py_overlay_dds`](src/py_overlay_dds/README.md) | DDS 配置 + colcon overlay |
+| 12 | [`bringup`](src/bringup/README.md) | 跨包 launch 聚合(多节点一键启动) |
+
+### 每个包怎么学(通用流程)
+
+1. **读包内 README.md**(知道这个包做什么、关键概念)
+2. **看代码**(先看 `src/<包名>/` 下的 .py 或 .cpp,跟着注释读)
+3. **跑起来**(`ros2 launch <package> <launch.py>`)
+4. **改参数试效果**(`ros2 param set <node> <param> <value>`)
+5. **跑测试**(`colcon test --packages-select <package>`)
+
+---
+
+## 📖 24 篇文档怎么读?
+
+**新手建议顺序**:
+
+| 顺序 | 文档 | 何时读 |
+|---|---|---|
+| 1 | ✅ [doc/01-quickstart.md](doc/01-quickstart.md) | 已在"从零开始"一节读完(可跳读) |
+| 2 | [doc/00-levels.md](doc/00-levels.md) | 想知道"学完这个下一步学什么" |
+| 3 | [doc/10-concepts.md](doc/10-concepts.md) | 概念速查(Node/Topic/...) |
+| 4 | [doc/20-topics.md](doc/20-topics.md) | 深入 Topic |
+| 5 | [doc/30-services.md](doc/30-services.md) | 深入 Service |
+| 6 | [doc/40-actions.md](doc/40-actions.md) | 深入 Action |
+| 7 | [doc/50-tf2.md](doc/50-tf2.md) | 学 TF2 必读 |
+| 8 | [doc/60-urdf.md](doc/60-urdf.md) | 学 URDF 必读 |
+| 9 | [doc/70-launch.md](doc/70-launch.md) | 学 launch 必读 |
+| 10 | [doc/80-package-build.md](doc/80-package-build.md) | 想自己创建 ROS2 包时读 |
+| 11 | [doc/85-docker.md](doc/85-docker.md) | 想改 Docker 配置时读 |
+| 12 | [doc/90-testing.md](doc/90-testing.md) | 想给代码加测试时读 |
+| 13 | [doc/CODING_STYLE.md](doc/CODING_STYLE.md) | **写代码前必读** |
+
+深度专题(按需读):
+- [doc/15-params.md](doc/15-params.md) — 参数系统
+- [doc/16-custom-interfaces.md](doc/16-custom-interfaces.md) — 自定义接口
+- [doc/17-lifecycle.md](doc/17-lifecycle.md) — Lifecycle Node
+- [doc/18-composable.md](doc/18-composable.md) — Composable Node
+- [doc/19-qos.md](doc/19-qos.md) — QoS
+- [doc/20-bag.md](doc/20-bag.md) — ros2 bag 数据记录
+- [doc/21-overlay-dds.md](doc/21-overlay-dds.md) — DDS 配置
+
+部署 / 进阶:
+- [doc/00-overview.md](doc/00-overview.md) — 项目架构 + 设计取舍
+- [doc/02-virtualenv.md](doc/02-virtualenv.md) — 本机 venv 工作流
+- [doc/99-embodied-ai.md](doc/99-embodied-ai.md) — 具身智能 / VLA 路线图
+- [doc/100-embedded-deployment.md](doc/100-embedded-deployment.md) — 三机部署(PC + RDK X5 + RK3506)
+
+---
+
+## 🏗 仓库结构(10 秒看懂)
+
+```
+D:\xs\ros2/                      ← 项目根目录(在这里开终端)
+│
+├── README.md                    ← 你正在读的文件
+├── AGENTS.md                    ← 开发者铁律(写代码 / 调试日志放哪里)
+├── Makefile                     ← 命令聚合(make build / make up / make shell 等)
+│
+├── docker/                      ← Docker 配置(ros2_dev 容器定义)
+├── doc/                         ← 24 篇深度文档
+├── tools/                       ← 本机 venv 脚本(本机开发工具隔离)
+│
+└── src/                         ← 12 个 ROS2 包(本仓库核心)
+    ├── py_pubsub/               ← Python Topic 演示(最简单,新手必看)
+    ├── cpp_pubsub/              ← C++ Topic 演示(跟 py_pubsub 互通)
+    ├── py_srv/                  ← Service(请求-响应)
+    ├── py_action_demo/          ← Action(带进度反馈的长任务)
+    ├── cpp_robot_tf2/           ← TF2 坐标变换 + URDF 机械臂
+    ├── py_vision_demo/          ← 图像(模拟相机 + OpenCV 处理)
+    ├── py_params/               ← 参数系统(运行时改配置)
+    ├── cpp_custom_interface/    ← 自定义 .msg/.srv/.action
+    ├── py_lifecycle_composable/ ← Lifecycle Node
+    ├── cpp_qos_demo/            ← QoS 9 种组合
+    ├── py_overlay_dds/          ← DDS 配置 + 多机部署
+    └── bringup/                 ← 跨包 launch 聚合(启动多个包)
+```
+
+**新手第一天只需要打开**: `src/py_pubsub/README.md` 和 `src/py_pubsub/py_pubsub/publisher_node.py`。
+
+---
+
+## 🔧 容器内常用命令速查
+
+**进入容器**:
+```powershell
+# PowerShell(宿主机)
+docker exec -it ros2_dev bash
+```
+
+**容器内**(Linux bash):
 
 ```bash
-# 1. 构建镜像(首次 5-10 分钟)
-make build
+source /opt/ros/humble/setup.bash        # 加载 ROS2 环境(每次新终端都要)
+source /root/ros2_ws/install/setup.bash   # 加载本项目编译产物(同上)
 
-# 2. 启动容器
-make up
-
-# 3. 容器内 build 12 包
-make colcon-build
-
-# 4. 跑所有测试
-make colcon-test
-
-# 5. 进入开发终端
-make shell
-
-# 6. 启动 11 节点 full_demo
-make full-demo
+ros2 run <package> <executable>           # 跑节点,例:ros2 run py_pubsub chatter_publisher
+ros2 launch <package> <launch.py>         # 跑 launch 文件
+ros2 topic list                           # 列出所有话题
+ros2 topic echo /chatter                  # 订阅看消息(按 Ctrl+C 退出)
+ros2 node list                            # 列出所有节点
+ros2 node info <node_name>                # 看某个节点的详细信息(话题/服务/参数)
+ros2 param list <node_name>               # 看节点参数
+ros2 param set <node> <param> <value>     # 改参数(运行时,例:ros2 param set py_publisher publish_rate_hz 5.0)
+ros2 service list                         # 列出所有服务
+ros2 service call <service_name> <req>    # 手动调用服务
+ros2 action list                          # 列出所有 Action
+ros2 bag record -a -o my_bag              # 录制所有话题数据
+ros2 bag play my_bag                      # 回放数据
 ```
 
-等价手动命令(`make` 不可用时):
+**退出容器**:`exit` 或 `Ctrl+D`。**容器还在跑,下次直接 `docker exec -it ros2_dev bash` 再进。**
 
-```bash
-docker compose -p ros2 -f docker/docker-compose.yml build
-docker compose -p ros2 -f docker/docker-compose.yml up -d
-docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && cd /root/ros2_ws && colcon build --symlink-install --packages-select py_pubsub cpp_pubsub py_srv py_action_demo cpp_robot_tf2 py_vision_demo py_params cpp_custom_interface py_lifecycle_composable cpp_qos_demo py_overlay_dds bringup"
-docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon test --packages-select ..."
+**停容器**:
+```powershell
+docker stop ros2_dev       # 停止(不删除,下次 docker start)
+docker rm -f ros2_dev      # 删除(下次要从头 docker run)
 ```
 
-## 🧱 架构
+---
+
+## ✅ L1 基础完成清单(打勾用)
+
+每学完一个包,把 `[ ]` 改成 `[x]`,4 个维度独立勾:
 
 ```
-                          ┌──────────────────────────────────────────┐
-                          │          本机 Windows / Linux            │
-                          │   (venv: ruff/black/mypy/pytest)        │
-                          └─────────────────┬────────────────────────┘
-                                            │ bind mount
-                          ┌─────────────────▼────────────────────────┐
-                          │     Docker compose project: ros2        │
-                          │     自定义网络: ros2_net (172.20.0.0/24) │
-                          │  ┌──────── ROS2 Humble 镜像 ────────┐   │
-                          │  │ rclcpp rclpy tf2 cv_bridge       │   │
-                          │  │ ros-humble-desktop-full         │   │
-                          │  └───────────────────────────────────┘   │
-                          │  ┌──── colcon build/test ───────────┐    │
-                          │  │ 12 个包 / 80 测试                │    │
-                          │  └──────────────────────────────────┘    │
-                          └──────────────────────────────────────────┘
+[ ] py_pubsub       — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] cpp_pubsub      — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] py_srv          — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] py_action_demo  — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] py_params       — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] cpp_custom_interface — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] py_vision_demo  — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] cpp_robot_tf2   — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] cpp_qos_demo    — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] py_lifecycle_composable — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] py_overlay_dds  — 跑通 / 改过参数 / 改过代码 / 测过测试
+[ ] bringup         — 跑通 / 改过参数 / 改过代码 / 测过测试
 ```
 
-**两层解耦**:
-- **本机层**: venv 装开发工具(runtime 隔离),IDE 直接读源码
-- **容器层**: colcon 装 ROS2 节点(apt 来源,共享给所有用户)
+**判定 "L1 完成"**: 12 × 4 = **48 个勾** ≥ 36 个(75%)。
 
-## 🎬 6 种端到端 demo
+---
 
-| Demo | 命令 | 看什么 |
+## 🗺 学完之后下一步做什么?
+
+| 阶段 | 内容 | 学完后能 |
 |---|---|---|
-| Topic 跨包跨语言 | `make launch NAME=pubsub_launch` | 4 节点(py+cpp)互通 |
-| Service | `make launch NAME=service_launch` + `ros2 service call ...` | `12+30=42` |
-| Action | `make launch NAME=action_launch` + `ros2 action send_goal ...` | Fibonacci(6) 边跑边反馈 |
-| Robot TF2 | `make launch NAME=robot_launch` | gripper 在 base_link 下实时位姿 |
-| Vision | `make launch NAME=vision_launch` | fake_camera → image_processor 图像流 |
-| Full demo | `make full-demo` | **11+ 节点同时运行** |
+| ✅ L1 基础(本仓库) | 12 包 + 78 测试 + 23 文档 | 自己设计 ROS2 项目 |
+| ➡️ L2 进阶 | ros2_control + MoveIt2 + Gazebo 仿真 | 控制真实机械臂 / 用仿真调参 |
+| ➡️ L3 真实机器人 | xArm / UR / Franka 驱动 | 上工业机械臂 |
+| ➡️ L4 具身智能 / VLA | OpenVLA / π0 / RKNN NPU 推理 | 让机器人理解自然语言指令 |
 
-## 📚 23 篇文档导航
+详见 [doc/99-embodied-ai.md](doc/99-embodied-ai.md) 和 [doc/00-levels.md](doc/00-levels.md)。
 
-### 上手
-- [`doc/00-overview.md`](doc/00-overview.md) — 项目架构 + 设计取舍
-- [`doc/00-levels.md`](doc/00-levels.md) — Level 1-4 学习路线(ROS2 → 机械臂 → VLA)
-- [`doc/01-quickstart.md`](doc/01-quickstart.md) — 5 分钟跑通
-- [`doc/02-virtualenv.md`](doc/02-virtualenv.md) — venv 工作流
+---
 
-### ROS2 核心概念
-- [`doc/10-concepts.md`](doc/10-concepts.md) — Node / Topic / Service / Action / Parameter / TF / Time
-- [`doc/20-topics.md`](doc/20-topics.md) — Topic pub/sub 深度
-- [`doc/30-services.md`](doc/30-services.md) — Service req/resp 深度
-- [`doc/40-actions.md`](doc/40-actions.md) — Action 三件套深度
-- [`doc/15-params.md`](doc/15-params.md) — Parameter 系统深度 ⭐
-- [`doc/16-custom-interfaces.md`](doc/16-custom-interfaces.md) — 自定义 msg/srv/action ⭐
-- [`doc/17-lifecycle.md`](doc/17-lifecycle.md) — Lifecycle Node ⭐
-- [`doc/18-composable.md`](doc/18-composable.md) — Composable Node ⭐
-- [`doc/19-qos.md`](doc/19-qos.md) — QoS 全解 ⭐
-- [`doc/20-bag.md`](doc/20-bag.md) — ros2 bag ⭐
-- [`doc/21-overlay-dds.md`](doc/21-overlay-dds.md) — DDS + colcon overlay ⭐
+## 📖 术语速查(给完全零基础的新手)
 
-### 机器人专属
-- [`doc/50-tf2.md`](doc/50-tf2.md) — 坐标变换
-- [`doc/60-urdf.md`](doc/60-urdf.md) — 机器人模型描述
-
-### 工程实践
-- [`doc/70-launch.md`](doc/70-launch.md) — launch 文件系统
-- [`doc/80-package-build.md`](doc/80-package-build.md) — colcon / ament 包构建
-- [`doc/85-docker.md`](doc/85-docker.md) — Docker 容器化开发
-- [`doc/90-testing.md`](doc/90-testing.md) — 测试金字塔
-- [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md) — **编程规范(必读)** ⭐
-
-### 具身智能路径
-- [`doc/99-embodied-ai.md`](doc/99-embodied-ai.md) — VLA / 机器人开发路线图
-- [`doc/100-embedded-deployment.md`](doc/100-embedded-deployment.md) — **三机部署实操**
-
-## 🗺 入门具身智能路径
-
-| 阶段 | 内容 | 配套 |
+| 术语 | 一句话解释 | 生活化例子 |
 |---|---|---|
-| ✅ L1 基础 | ROS2 12 包 + 80 测试 + 23 文档 | **本仓库** |
-| ➡️ L2 进阶 | ros2_control + MoveIt2 + Gazebo | `ros-humble-*` apt |
-| ➡️ L3 机械臂 | 真实机械臂驱动 + 手眼标定 + 抓取 | xArm / UR / Franka |
-| ➡️ L4 VLA | OpenVLA / π0 / RKNN NPU 推理 | PC + RDK X5 + RK3506 |
+| **Node(节点)** | 一个独立的运行程序(进程) | 像手机里的每个 App |
+| **Topic(话题)** | 节点之间传递消息的"频道"(单向) | 像广播电台,谁都可以订阅 |
+| **Service(服务)** | 节点之间的"一问一答"调用(双向) | 像打电话,问完必须等回答 |
+| **Action(动作)** | 节点之间"长任务"调用,带进度回调 | 像外卖下单,可以取消 + 实时看进度 |
+| **Parameter(参数)** | 节点的"配置项",可以运行时改 | 像手机设置里的开关 |
+| **TF(坐标变换)** | 跟踪机器人各部件的空间位置关系 | 像人知道"我的手在身体左前方 30cm" |
+| **URDF** | 机器人的 3D 模型描述(关节 + 连杆) | 像机器人的"骨骼图纸" |
+| **QoS** | 消息传输的"质量策略"(可靠 vs 实时) | 像快递:顺丰可靠 vs 同城闪送快 |
+| **Lifecycle** | 节点的"生命周期"管理(初始化 → 运行 → 关闭) | 像手机 App 的启动 → 后台 → 退出 |
+| **DDS** | 节点之间真正"传消息"的底层协议 | 像快递公司,Topic 是地址,DDS 是车 |
+| **Launch 文件** | 一次性启动多个节点的"剧本" | 像一键启动所有 App |
+| **Package(包)** | 一个独立的 ROS2 项目单元(代码 + 配置 + 依赖) | 像 npm 包 / pip 包 |
+| **colcon** | ROS2 官方编译工具(类似 make) | 像 make,但专为 ROS2 设计 |
+| **ROS_DOMAIN_ID** | 节点的"网络分组"(0-232),不同 ID 的节点互不可见 | 像不同的 WiFi 频道 |
 
-## 🛠 项目约定(必读)
-
-代码风格 / 构建约束全部在 [`AGENTS.md`](AGENTS.md) + [`doc/CODING_STYLE.md`](doc/CODING_STYLE.md),核心几条:
-
-1. **本机 venv 不污染系统 Python**(用 `tools/setup_venv.{sh,ps1}`)
-2. 容器内用 colcon + ament(ROS2 官方工具链)
-3. 跨包 launch 用 `IncludeLaunchDescription` + `FindPackageShare`
-4. 包名不能叫 `launch`(与 ROS2 系统包同名冲突)
-5. **测试 100% 通过才能停手**
-6. **不修改全局 git config** — 用 `git -c user.name=x -c user.email=y` 临时设
+---
 
 ## 🤝 致谢
 
@@ -167,4 +495,18 @@ docker exec ros2_dev bash -lc "cd /root/ros2_ws && colcon test --packages-select
 - [REP-2000: ROS 2 Design](https://www.ros.org/reps/rep-2002.html)
 - [OSRF](https://www.openrobotics.org/) `osrf/ros:humble-desktop` 镜像
 
-开始你的 ROS2 之旅:`doc/01-quickstart.md` → 跑通 → 读 `doc/10-concepts.md` 深入 → 上 `doc/99-embodied-ai.md` 部署。
+---
+
+## 📜 项目元信息
+
+| 文件 | 是什么 | 你要读吗 |
+|---|---|---|
+| [`CHANGELOG.md`](CHANGELOG.md) | 每次发布改了什么 | 想看版本历史 / 发版时 |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 怎么贡献代码(PR 流程) | **只在你打算提 PR 时读** |
+| [`LICENSE`](LICENSE) | MIT 协议 | 想二次发布时读 |
+| [`pyproject.toml`](pyproject.toml) | PEP 621 包元数据 | 想 IDE 配置时 |
+| [`AGENTS.md`](AGENTS.md) | 开发者铁律(给 AI Agent 看的) | **不要读**,这是给 AI 写代码时的规则 |
+
+---
+
+**下一步** → 跑通上面的"从零开始:30 分钟跑通 Hello World",然后选 [第一梯队第 1 个包 py_pubsub](src/py_pubsub/README.md) 开始学。