--sim 时按仿真台别名导出手眼真值：--arm 89 --sim 照着文档敲必然失败

`--arm 89 --sim` 是个**合法且有意的**用法（run_gauge_assembly.sh 里
_HAD_ARM 那段写着"想用仿真核对某台真机的点位时会这么用"），但手眼真值导出
传的是 ${ROBOT_SN} —— 于是帧名成了 Rizon4-063989_flange，而仿真 URDF 里是
sim_flange。导出先干等 20s，再报"仿真栈起来了吗？"，把人引去重启一个明明在
跑的仿真。文档 §7 里写的就是这条命令，所以照着敲 100% 失败。

真值必须按**仿真台**的帧名导出，与"用哪台臂的点位"无关 → 固定用仿真台别名
（SIM_ARM_ALIAS 可覆盖，默认 sim）。

顺带把 §7 那组验收命令补成真能跑的：
  · 以前只写"先编"，没说**怎么起仿真**，也没说**起之前要清干净** ——
    这次就是在这两步上栽的，新增 §6.5 把三步（编 / 清 / 起）写全；
  · "arm_application 子集 454 passed"配的那条裸 `PYTHONPATH=... pytest`
    命令实测已经收集阶段就 error（导入不到 ament），改成走 run_unit_tests.sh
    并更新数字；总测试数 1118 → 1128。

验证：`bash scripts/run_gauge_assembly.sh --arm 89 --sim --dry-run` 现在
state=DONE ok=True 2/2 孔、退出码 0（修改前必然退出码 1）。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/GAUGE_ASSEMBLY.md

@@ -252,12 +252,45 @@ S07 接触（腕部 FT）：轴向 +48.37N 相对基线 -21.82N 超过 +8.0N（
 
    250|---
 
+## 6.5 仿真跑之前：三件事（顺序别换）
+
+第 7 节的验收命令**都要求仿真已经在跑**，而这里以前只写了"先编"，没写"怎么起"
+和"起之前要清干净"——2026-09-28 实测就是在这两步上栽的。
+
+```bash
+# 1) 编（改过 src/ 之后必须；仿真 install_sim/ 是拷贝，不是 symlink —— 坑 2）
+bash ~/ros2/scripts/build_sim.sh
+
+# 2) 清干净：上一轮的仿真进程、以及**在真机域上跑着的 mock 栈**
+bash ~/ros2/scripts/stop_sim_gz.sh            # 仿真栈（进程组 + install_sim/ 兜底）
+bash ~/ros2/scripts/stop_real.sh --list       # 真机/mock 侧（应为空）
+
+# 3) 起仿真（默认无头；要看画面加 --gui）
+bash ~/ros2/scripts/run_sim_gz.sh
+```
+
+第 2 步里的 `stop_real.sh` **不是可选的礼貌动作**，实测踩过一次：
+
+> `run_sim.sh`（mock 栈）名为 sim，用的却是**真机的 `install/`**、节点名与真机
+> 完全一样，而且它当时**不管 `ROS_DOMAIN_ID`** —— 调用者 shell 里带着 77
+> （之前跑过仿真）就落到**仿真的域**上。于是 mock 的 `joint_state_publisher`
+> 与 Gazebo 争 `/joint_states`：**控制器 `feedback` 与 `reference` 完全一致**
+> （控制器没坏），TF 却显示末端**一动不动**。
+>
+> 表现是"仿真上料失败、臂摆不到竖直位姿"，顺着现象查会一路查到 IK / TF / 时钟上。
+> 现在两侧的域都钉死了（`run_sim.sh` → 真机域 0，`run_sim_gz.sh` → 仿真域 77，
+> 见 `scripts/lib/ros_domain.sh`），但**残留进程本身**仍要靠第 2 步清掉。
+
 ## 7. 验收命令（都是真跑过的）
 
 ```bash
 # 1) 纯逻辑层（不需要机器人）
-PYTHONPATH=src/arm_application python3 -m pytest src/arm_application/test -q
+bash ~/ros2/scripts/run_unit_tests.sh src/arm_application
-#    仿真环境：454 passed, 14 skipped（缺 onnx 的用例跳过，不伪装成失败）
+#    真机环境：557 passed（`onnx` 齐）；仿真环境会少几项 —— 缺 onnx 的用例 skip，
+#    不伪装成失败（R5.10）。
+#    别用裸 `PYTHONPATH=src/... python3 -m pytest`：那样导入不到 ament/ROS、
+#    收集阶段就报 error，看起来像"测试挂了"，其实只是环境没装 —— 用上面这个
+#    运行器（它负责切 conda、按包拼 PYTHONPATH）。
 
 # 2) 干跑全流程：S00→S01→…→S11→DONE，脚本退出码 0，结论 ok=true
 bash ~/ros2/scripts/run_gauge_assembly.sh --arm 89 --sim --dry-run

docs/HANDBOOK.md

@@ -357,7 +357,7 @@ bash scripts/weights.sh doctor --check-engines
 
 ### 4.3 单元测试怎么跑
 
-**每个功能包都有自己的测试**，改完对应包就跑一下。当前 pytest 收集 **1118 项**
+**每个功能包都有自己的测试**，改完对应包就跑一下。当前 pytest 收集 **1128 项**
 （另有 1 项按环境 skip）。
 
 ```bash

scripts/run_gauge_assembly.sh

@@ -120,7 +120,15 @@ if [[ "${USE_SIM}" == true ]]; then ARGS+=(use_sim_time:=true); fi
 if [[ "${USE_SIM}" == true ]]; then
   ARGS+=(publish_handeye_tf:=false)
   echo "=== 刷新仿真手眼真值（sim_eye_in_hand.yaml / sim_d435_eye_to_hand.yaml） ==="
-  if ! python3 "${ROOT}/scripts/gen_sim_handeye.py" --arm "${ROBOT_SN:-sim}"; then
+  # ⚠️ 这里**必须**用仿真台的别名，不能用 ${ROBOT_SN}。
+  #    真值要按**仿真 URDF 的帧名**导出（sim_flange / sim_d405_color_optical_frame）。
+  #    而 `--arm 89 --sim` 是个**合法且有意的**用法（见上面 _HAD_ARM 那段：
+  #    "想用仿真核对某台真机的点位时会这么用"）——那时 ROBOT_SN=Rizon4-063989，
+  #    帧名就成了 Rizon4-063989_flange，仿真里根本没有这个帧：
+  #    导出会先等 20s 再报"仿真栈起来了吗？"，把人引去重启一个明明在跑的仿真。
+  #    实测（2026-09-28）就是这么踩的 —— 文档 §7 里写的就是 `--arm 89 --sim`，
+  #    照着敲必然失败。
+  if ! python3 "${ROOT}/scripts/gen_sim_handeye.py" --arm "${SIM_ARM_ALIAS:-sim}"; then
     echo "ERROR: 仿真手眼真值导出失败（上面有原因）。仿真栈起来了吗？" >&2
     echo "       bash scripts/run_sim_gz.sh  之后重试。" >&2
     exit 1