# ROS2 学习套件 — 从零到具身智能 / VLA 完全体 > **如果你是 ROS2 完全的新手,不知道怎么开始 → [从零开始指南](#-从零开始-30-分钟跑通-hello-world)** --- ## 🆘 从零开始:30 分钟跑通 Hello World **如果你从来没接触过 ROS2,不知道"Docker 是什么"、"make 命令在哪"、不知道怎么开终端,按下面一步一步来。** ### 0. 你需要准备什么?(只看这一节就够) | 工具 | 是什么 | 怎么得到 | 大约多大 | |---|---|---|---| | **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 | **你不需要装**:Python、ROS2、Ubuntu、虚拟机、Linux。 **磁盘空间**: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`。 **方式 A — 推荐(走 docker compose,跟 Makefile 等价)** ```powershell 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),没有报错就行。 **验证容器跑起来了**: ```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 --help | head -5 # 应该输出 ros2 CLI 用法 # 或 dpkg -l ros-humble-rclcpp | tail -1 # 应该看到已装的 ROS2 humble 版本行 ``` **常见错误**:直接输入 `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 设计)。 **方式 A — 推荐**:用项目脚本(自带 source ROS2 + 12 包列表) ```bash cd /root/ros2_ws bash scripts/build.sh ``` **方式 B — 手动**: ```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. 加载本项目环境 + 跑测试 **方式 A — 推荐**:用项目脚本 ```bash bash scripts/test.sh ``` **方式 B — 手动**: ```bash source install/setup.bash colcon test ``` **预期输出**(成功的话): ``` Summary: 12 packages finished [3 min 15 s] ``` **怎么确认 100% 通过**: ```bash colcon test-result --all ``` 期望看到: ``` build//pytest.xml: PASS build//test_results/.../test_*.gtest.xml: PASS ``` 所有包都 PASS = 全绿。 ### 10. 跑 Hello World(Topic 演示) **Topic 是什么**:发布-订阅模式。一个节点(Publisher)发消息,另一个节点(Subscriber)收消息。这是 ROS2 最核心的通信方式。 **打开第一个终端**(容器内): **方式 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 bringup 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. **玩参数**:另开一个终端,输入 `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 的核心流程。 --- ## 🔧 常见问题(新手必看) ### ❌ 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//` 下的 `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//pytest.xml` 或 `build//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 `) 4. **改参数试效果**(`ros2 param set `) 5. **跑测试**(`colcon test --packages-select `) --- ## 📖 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 source /opt/ros/humble/setup.bash # 加载 ROS2 环境(每次新终端都要) source /root/ros2_ws/install/setup.bash # 加载本项目编译产物(同上) ros2 run # 跑节点,例:ros2 run py_pubsub chatter_publisher ros2 launch # 跑 launch 文件 ros2 topic list # 列出所有话题 ros2 topic echo /chatter # 订阅看消息(按 Ctrl+C 退出) ros2 node list # 列出所有节点 ros2 node info # 看某个节点的详细信息(话题/服务/参数) ros2 param list # 看节点参数 ros2 param set # 改参数(运行时,例:ros2 param set py_publisher publish_rate_hz 5.0) ros2 service list # 列出所有服务 ros2 service call # 手动调用服务 ros2 action list # 列出所有 Action ros2 bag record -a -o my_bag # 录制所有话题数据 ros2 bag play my_bag # 回放数据 ``` **退出容器**:`exit` 或 `Ctrl+D`。**容器还在跑,下次直接 `docker exec -it ros2_dev bash` 再进。** **停容器**: ```powershell docker stop ros2_dev # 停止(不删除,下次 docker start) docker rm -f ros2_dev # 删除(下次要从头 docker run) ``` --- ## ✅ L1 基础完成清单(打勾用) 每学完一个包,把 `[ ]` 改成 `[x]`,4 个维度独立勾: ``` [ ] 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 — 跑通 / 改过参数 / 改过代码 / 测过测试 ``` **判定 "L1 完成"**: 12 × 4 = **48 个勾** ≥ 36 个(75%)。 --- ## 🗺 学完之后下一步做什么? | 阶段 | 内容 | 学完后能 | |---|---|---| | ✅ L1 基础(本仓库) | 12 包 + 78 测试 + 23 文档 | 自己设计 ROS2 项目 | | ➡️ L2 进阶 | ros2_control + MoveIt2 + Gazebo 仿真 | 控制真实机械臂 / 用仿真调参 | | ➡️ L3 真实机器人 | xArm / UR / Franka 驱动 | 上工业机械臂 | | ➡️ L4 具身智能 / VLA | OpenVLA / π0 / RKNN NPU 推理 | 让机器人理解自然语言指令 | 详见 [doc/99-embodied-ai.md](doc/99-embodied-ai.md) 和 [doc/00-levels.md](doc/00-levels.md)。 --- ## 📖 术语速查(给完全零基础的新手) | 术语 | 一句话解释 | 生活化例子 | |---|---|---| | **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 频道 | --- ## 🤝 致谢 - [ROS2 官方文档](https://docs.ros.org/en/humble/) - [REP-2000: ROS 2 Design](https://www.ros.org/reps/rep-2002.html) - [OSRF](https://www.openrobotics.org/) `osrf/ros:humble-desktop` 镜像 --- ## 📜 项目元信息 | 文件 | 是什么 | 你要读吗 | |---|---|---| | [`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 写代码时的规则 | | [`scripts/`](scripts/README.md) | 容器内常用命令脚本(build/test/launch/clean/shell/e2e) | 推荐用 | | [`.docs/bug_logs/`](.docs/bug_logs/2026-08-04_quickstart_audit.md) | 入门文档 bug 审计 + 修复历史 | 复盘 / 找历史坑时 | --- **下一步** → 跑通上面的"从零开始:30 分钟跑通 Hello World",然后选 [第一梯队第 1 个包 py_pubsub](src/py_pubsub/README.md) 开始学。