1

README.md

@@ -88,10 +88,22 @@ docker build -t ros2-humble-dev:latest -f docker/Dockerfile .
 
 容器 = 用镜像启动的"Linux 虚拟机实例"。本仓库的容器名是 `ros2_dev`。
 
+**方式 A — 推荐(走 docker compose,跟 Makefile 等价)**
 ```powershell
-docker run -d --name ros2_dev -v "${PWD}:/root/ros2_ws" --network ros2_net ros2-humble-dev:latest
+docker compose -p ros2 -f docker/docker-compose.yml up -d
 ```
 
+**方式 B — 手动 docker run**(等价;注意末尾的 `bash` 用来保活,**重要** ❗)
+
+```powershell
+docker run -d -it --name ros2_dev `
+  -v "${PWD}:/root/ros2_ws" `
+  --network ros2_net `
+  ros2-humble-dev:latest bash
+```
+
+> ❗ **一定要带末尾的 `bash`**: 否则容器启动后立刻 `Exited (0)`,因为基础镜像默认 ENTRYPOINT 跑 bash,无 tty 时立刻退出。
+
 **预期输出**:一串 hash(容器 ID),没有报错就行。
 
 **验证容器跑起来了**:
@@ -127,7 +139,9 @@ source /opt/ros/humble/setup.bash
 
 **怎么验证**:
 ```bash
-ros2 --version   # 应该显示 ROS 2 package version 1.0 (or similar)
+ros2 --help | head -5                # 应该输出 ros2 CLI 用法
+# 或
+dpkg -l ros-humble-rclcpp | tail -1  # 应该看到已装的 ROS2 humble 版本行
 ```
 
 **常见错误**:直接输入 `ros2` 提示 `command not found` → 说明你忘了 source。
@@ -143,6 +157,13 @@ echo "source /root/ros2_ws/install/setup.bash" >> ~/.bashrc  # 这一行要等
 
 `colcon` 是 ROS2 的官方编译工具(类似 `make` 但专为 ROS2 设计)。
 
+**方式 A — 推荐**:用项目脚本(自带 source ROS2 + 12 包列表)
+```bash
+cd /root/ros2_ws
+bash scripts/build.sh
+```
+
+**方式 B — 手动**:
 ```bash
 cd /root/ros2_ws
 colcon build --symlink-install
@@ -158,6 +179,12 @@ Summary: 12 packages finished [4 min 32 s]
 
 ### 9. 加载本项目环境 + 跑测试
 
+**方式 A — 推荐**:用项目脚本
+```bash
+bash scripts/test.sh
+```
+
+**方式 B — 手动**:
 ```bash
 source install/setup.bash
 colcon test
@@ -188,10 +215,17 @@ build/<package>/test_results/.../test_*.gtest.xml:  PASS
 
 **打开第一个终端**(容器内):
 
+**方式 A — 推荐**:项目脚本(自带 source)
+```bash
+bash scripts/launch.sh pubsub_launch 30
+# 第 2 个参数 = 运行时长(秒),空 = 一直跑
+```
+
+**方式 B — 手动**(跨语言 4 节点 Topic 互通)
 ```bash
 source /opt/ros/humble/setup.bash
 source /root/ros2_ws/install/setup.bash
-ros2 launch py_pubsub pubsub_launch.py
+ros2 launch bringup pubsub_launch.py
 ```
 
 **预期输出**(每个终端都会一直打印,这是正常的):
@@ -212,8 +246,8 @@ ros2 launch py_pubsub pubsub_launch.py
 你已经跑通了 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)
+2. **玩参数**:另开一个终端,输入 `docker exec ros2_dev bash -lc "source /opt/ros/humble/setup.bash && source /root/ros2_ws/install/setup.bash && ros2 param set py_publisher publish_rate_hz 5.0"`,回到第一个终端你会看到消息频率从 1 Hz 变成 5 Hz
+3. **看节点关系图**:输入 `docker exec ros2_dev bash -lc "rqt_graph"`(需要图形界面,详见 doc/85-docker.md)
 
 > **📖 想看更详细的图文版 + Windows 截图**?见 [`doc/01-quickstart.md`](doc/01-quickstart.md)(已读过的章节可跳读)。本节内容已覆盖 doc/01-quickstart 的核心流程。
 
@@ -506,6 +540,8 @@ docker rm -f ros2_dev      # 删除(下次要从头 docker run)
 | [`LICENSE`](LICENSE) | MIT 协议 | 想二次发布时读 |
 | [`pyproject.toml`](pyproject.toml) | PEP 621 包元数据 | 想 IDE 配置时 |
 | [`AGENTS.md`](AGENTS.md) | 开发者铁律(给 AI Agent 看的) | **不要读**,这是给 AI 写代码时的规则 |
+| [`scripts/`](scripts/README.md) | 容器内常用命令脚本(build/test/launch/clean/shell/e2e) | 推荐用 |
+| [`.docs/bug_logs/`](.docs/bug_logs/2026-08-04_quickstart_audit.md) | 入门文档 bug 审计 + 修复历史 | 复盘 / 找历史坑时 |
 
 ---