diff --git a/docs/HANDBOOK.md b/docs/HANDBOOK.md
index b433894..3a0b445 100644
--- a/docs/HANDBOOK.md
+++ b/docs/HANDBOOK.md
@@ -338,6 +338,7 @@ source scripts/env.sh                                # 真机环境
 source scripts/sim_env.sh                            # 仿真环境（独立 conda）
 
 # —— 设备与配置 ——
+bash scripts/run_real_preflight.sh --arm 89          # 真机开工体检（只读，含 RDK/相机/USB/几何）
 ros2 run arm_interfaces device_check                 # 设备契约 + site.yaml 必填项
 bash scripts/show_site_config.sh                     # site.yaml 解析结果
 python3 scripts/check_arm_prefixes.py                # 含臂名的配置是否跟着当前臂（换臂必跑）
@@ -356,29 +357,36 @@ bash scripts/weights.sh doctor --check-engines
 
 ### 4.3 单元测试怎么跑
 
-**每个功能包都有自己的测试**，改完对应包就跑一下。当前 pytest 收集 **608 项**。
+**每个功能包都有自己的测试**，改完对应包就跑一下。当前 pytest 收集 **1118 项**
+（另有 1 项按环境 skip）。
 
 ```bash
 source scripts/env.sh                                # 或 sim_env.sh
 
-# 逐包跑（跳过需要厂商 flexivrdk 包的 flexiv_rdk，那个环境里没有）
-for d in src/*/test; do
-  case "$d" in src/flexiv_rdk/*) continue;; esac
-  printf '%-28s ' "$d"; python3 -m pytest "$d" -q -p no:cacheprovider 2>&1 | tail -1
-done
-
-# 只跑一个包
-python3 -m pytest src/arm_sim_gazebo/test -q
+bash scripts/run_unit_tests.sh                       # 全部
+bash scripts/run_unit_tests.sh src/arm_kinematics/test          # 只跑一个包
+bash scripts/run_unit_tests.sh src/arm_application/test/test_real_preflight.py
+bash scripts/run_unit_tests.sh -k gauge              # 只跑名字带 gauge 的
 ```
 
-改动前后对比数量是最省事的回归判据 —— 现在应该是（pytest 收集数，共 608 项）：
+> 用这个脚本，别直接 `python3 -m pytest src/xxx/test`。脚本会把 `src/*` 全部
+> 挂到 `PYTHONPATH` 最前面，两个原因：
+>
+> 1. 测试按**包名**导入，少挂一个包会在收集阶段 `ModuleNotFoundError` ——
+>    现象是"0 个测试 / 1 个 error"，很容易被读成测试环境坏了。
+> 2. 更隐蔽：`install/` 里那份**旧的**同名模块会先被找到（它在 `PYTHONPATH` 上）。
+>    实测 `src/arm_sim_gazebo/test` 直接跑会报
+>    `cannot import name 'RESET_GIVE_UP'` —— 导的是 `install/` 里的旧副本，
+>    源码里明明有这个符号。挂上 `src/` 之后才测的是你改的那份。
+
+按包统计（改动前后对比数量是最省事的回归判据）：
 
 | 包 | 测试数 | 覆盖什么 |
 |----|--------|----------|
-| `arm_application` | 233 | 纯逻辑：滤波器、解析器、几何、参数合并 |
-| `arm_sim_gazebo` | 236 | 场景校验、URDF 归一化、相机内参、触觉适配 |
+| `arm_application` | 547 | 纯逻辑：滤波器、解析器、几何、参数合并、装配状态机 |
+| `arm_sim_gazebo` | 400 | 场景校验、URDF 归一化、相机内参、触觉适配 |
+| `arm_interfaces` | 78 | 路径解析、清单校验、配置守卫 |
 | `arm_driver_flexiv` | 69 | 驱动适配、下压控制、超时 |
-| `arm_interfaces` | 46 | 路径解析、清单校验、配置守卫 |
 | `arm_kinematics` | 24 | 正逆运动学 |
 
 > `src/flexiv_rdk/test` 需要厂商的 `flexivrdk` Python 包，仿真环境里没有，
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index a423feb..f3c7aa7 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -45,6 +45,29 @@ source scripts/env.sh
 
 ## 第一次实机
 
+**开工前先体检**（不需要机械臂能动，只读）：
+
+```bash
+bash ~/ros2/scripts/run_real_preflight.sh --arm 89
+```
+
+它按"现场该处理的顺序"给结论，最后汇总**要人工做的事**。它专门盯这几类
+"报错的地方不是坏的地方"的问题：
+
+| 检查项 | 抓的是 |
+| --- | --- |
+| 现场配置 | 这一轮到底在读哪份 site.yaml、认哪台臂 |
+| 遗留进程 | 上一轮没退干净的 ros2_control（它占着 RDK，会让 RDK 报"连不上"） |
+| 机器人在网 | ping 不通；以及**两个 IP 指向同一个 MAC**（两台臂出厂 MAC 相同时会互相抢转发） |
+| 机械臂 RDK | 连不上 / 示教器在 Manual（这个 SW 切不了，只能人到现场拨） |
+| 腕部相机 | 本臂配置的那只 D405 **在不在 USB 上** —— 它掉了以后报错会变成"点云为空" |
+| 触觉 / USB / 几何 | 触觉是"没插"还是"内核卡死"、RealSense 协商速率、手眼矩阵与悬停高度 |
+
+结论是 `NO-GO` 时**不要往下走**：硬阻断项（RDK、腕部相机）会让后面每一步
+都以别的样子失败。
+
+然后是常规步骤：
+
 1. 示教器：AUTO + Remote Ethernet，清故障。关 Studio。
 2. `bash ~/ros2/scripts/test_rdk_python.sh`（可选）
 3. T1 `run_real.sh`，T2 `run_camera_d405.sh --preview`
diff --git a/scripts/run_unit_tests.sh b/scripts/run_unit_tests.sh
index 91c82b9..8439eb8 100755
--- a/scripts/run_unit_tests.sh
+++ b/scripts/run_unit_tests.sh
@@ -38,7 +38,23 @@ if [ "${#test_dirs[@]}" -eq 0 ]; then
 fi
 
 cd "${ROOT}"
-if [ "$#" -gt 0 ]; then
-  exec "${PY}" -m pytest "${test_dirs[@]}" -q "$@"
+# 位置参数里**存在的路径**当作"只跑这些"，其余（-k / -x / --tb=… 及其取值）
+# 原样透传给 pytest。
+#
+# 为什么要分开：以前是 `pytest "${test_dirs[@]}" "$@"` —— 传进来的路径只是被
+# **追加**到"全部测试目录"后面，于是 `run_unit_tests.sh src/x/test` 实际跑的是
+# **整仓库**。脚本头部的用法示例看起来像"只跑这个文件"，实际不是，很容易被读成
+# "我只改了 x，怎么蹦出别的包的失败"。用法示例就是承诺，得让它成立。
+paths=()
+extra=()
+for a in "$@"; do
+  if [[ "${a}" != -* && -e "${a}" ]]; then
+    paths+=("${a}")
+  else
+    extra+=("${a}")
+  fi
+done
+if [ "${#paths[@]}" -gt 0 ]; then
+  exec "${PY}" -m pytest "${paths[@]}" -q "${extra[@]}"
 fi
-exec "${PY}" -m pytest "${test_dirs[@]}" -q
+exec "${PY}" -m pytest "${test_dirs[@]}" -q "${extra[@]}"