P5c-6 场景物料落地 + Gazebo 中文手册：工件/通止规模型、场景校验、两处静默失效修复

一、场景物料（新增）
  devices/sim/gazebo/models/workpiece/   带三个孔的铝板。碰撞体是"带方孔的平板"，
    视觉额外加两个 φ14/φ7 亮环 —— 因为真机的 HoughCircles 就是靠这两个亮环找孔，
    只按碰撞体建视觉会让"孔检测"在仿真里永远失败，而那看起来像算法问题。
  devices/sim/gazebo/models/gauge/       通止规：通端/套环/握柄/止端四段，各段异色
    便于肉眼判断方向。接触刚度刻意比台面软 —— 位置控制器会"刚性压进去"，
    用默认刚度会被弹飞（注释里写了原因，不是随手抄的参数）。
  devices/sim/gazebo/models/gauge_stand/ 规座（static）。规直接站在台面上会立刻倒，
    加个方孔底座把它立住。
  三个模型都是 model.sdf + model.config，原点在**底面中心**，单位米。

二、场景配置与校验（新增）
  config/scene.yaml     物体不再写死在 world 里，改为 scene.yaml + 启动时动态 spawn。
    理由：world 是"环境"（地面/台面/相机/系统插件），场景是"这一批活做什么"。
    动 world 的风险面太大 —— 它只要丢一个系统声明，所有模型都 spawn 不进去（见旧坑 2）。
    含 operating（相机到工件的距离等作业条件）与 gates_px（像素门槛）。
  sim_scene.py          摆放校验：从 SDF **逐碰撞体**解析 AABB（不抄尺寸，避免漂移），
    检查原点在底面 / 不穿台面 / 不出界 / 物体之间不嵌入。
    重叠判定必须逐碰撞体三维判，不能拿总包围盒相交 ——
    正常装配里本来就有嵌套（规立在规座方孔里），粗判会误报，
    而误报的后果是人把检查整个关掉，之后真重叠也抓不到。
    另有成像几何：把亮环/孔间距按相机距离换算成像素，与门槛比对。
  scripts/check_sim_scene.py  验收工具（退出码可用）：摆放 + 门槛漂移 + 成像几何 +
    悬停高度 vs 工作空间 + 手外相机是否**完整**看得见工件 + Gazebo 实际位姿。

三、修掉两处静默失效（都是"看起来一切正常"）
  1) parse_spawned_poses 一直是**死代码**：它按 "x: N / y: N / z: N" 解析，
     而 Fortress 实际输出是方括号两行（XYZ / RPY）。对不上 → 永远返回空 →
     调用方按设计"降级成跳过位姿核对" → 位姿检查**从来没跑过**，
     而日志只说"跳过"，看起来像正常降级。
     现在两种格式都支持，并用真实抓下来的输出样本做回归测试。
     教训：宽容降级会把"没检查"伪装成"检查通过"。
  2) stop_sim_gz.sh 的模式表里漏了 robot_state_publisher（而注释里写着它有覆盖）：
     脚本报"已停止"，它却还在发上一份 /robot_description 与 TF，
     下一次启动就会"改了描述却不生效"。
     顺带修掉同源的两个问题：awk 用 -v 传模式导致它匹配到自己、每次复查都多报
     一个空命令行的幽灵 PID；以及"杀的时候"和"复查的时候"两份扫描实现会各自漂移。
     现在共用同一个 scan_pids()，模式改用环境变量传递，并在杀完之后**再扫一遍**：
     有残留就报出来并非零退出 —— 下次再有漏项，不再静默。
     实测：--list 列出全套 9 个进程；停止后 rc=0 且 pgrep 干净。

四、相机：D405 分辨率对齐真机
  仿真的 D405 此前渲染 640x480，而真机跑 848x480（fx 337 而非 447）。后果是
  58mm 的两孔间距成像只剩 85px，低于 hole_distance_min=90 ——
  孔检测在仿真里根本不可能通过，而现象看起来像"算法不行"。
  已把 xacro 与 cameras.yaml 一起改成 848x480，并把启动时的比对从"只比视场"
  扩成"视场 + 图幅"（sim_cameras.check_camera_consistency），
  不一致时说明它对像素门槛的影响。

五、文档
  devices/sim/gazebo/README.md 重写为中文手册：使用方法 / 建模要求 / 导入格式 /
    配置方式（含"改哪里才真的生效"的接线表）/ 11 条实测坑（每条都有"怎么发现"）。
  manifest.yaml 的进度、assets、description、坑清单与本轮状态对齐。
  scripts/README.md 补两个验收工具与停止脚本；根 README 补仿真入口与手册链接。
  cameras.yaml 里一处过期的函数名（check_fov_consistency）修正。

六、测试
  新增 test_sim_scene.py（79 条，此前 sim_scene.py 完全没有单测 —— 这正是
    位姿解析死掉却无人发现的原因）与 test_check_sim_scene.py（21 条），
  含三条回归：world_boxes 的偏移碰撞体不能被对称化放大（假重叠）、
  center_bore 不能被 _bore 后缀吃掉、Fortress 位姿输出格式。
  全量：src/arm_sim_gazebo + arm_interfaces + arm_application 共 515 通过。

同时附上 config/site.example.yaml 的重新生成（此前 site.yaml 的注释改动没同步，
它的 parity 测试是红的）。

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

devices/sim/gazebo/models/workpiece/model.config

@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!--
+  Gazebo 模型清单文件。作用是让这个目录能被当成 model:// 资源引用，
+  并给 GUI / `ign model --list` 提供可读信息。
+
+  ⚠️ 命名规则（两条都是框架约定，改之前先看 README 的"建模要求"）：
+    1. <name> 必须与**目录名一致**（此处 workpiece），否则 model:// 引用会
+       找不到 —— 而 Gazebo 只会静默跳过，不报错。
+    2. <name> 必须与推理用的**类别名一致**（YOLO 的 labels 里那个名字）。
+       否则仿真里算出的工件坐标和检测结果对不上：明明检测到工件，
+       坐标却是另一个东西的。这条最容易在"新建一个模型试试"时被破坏。
+-->
+<model>
+  <name>workpiece</name>
+  <version>1.0</version>
+  <sdf version="1.9">model.sdf</sdf>
+
+  <author>
+    <name>ros2 通止规装配项目</name>
+    <email></email>
+  </author>
+
+  <description>
+    通止规装配的工件：140×100×12mm 板，中心 φ40 光孔（会被检测的 max_radius 滤掉），
+    两侧各一个 φ7 光孔、孔心间距 58mm、孔口带 φ14 亮环（二阶段 HoughCircles 检测的目标）。
+
+    详细说明（尺寸怎么反推出来的、哪些是近似）见 model.sdf 文件头与
+    devices/sim/gazebo/README.md 的"仿真 ≠ 真机"一节。
+  </description>
+</model>

devices/sim/gazebo/models/workpiece/model.sdf

@@ -0,0 +1,325 @@
+<?xml version="1.0"?>
+<!--
+  =============================================================================
+  devices/sim/gazebo/models/workpiece/model.sdf
+  工件（被装配的对象）。
+
+  由 config/scene.yaml 决定摆在台面上的哪个位置，启动时由 gazebo_sim.launch.py
+  用 ros_gz_sim create -file 生成。**不要**把位姿写死在这里 ——
+  位姿属于"场景"，不属于"模型"，分开才能同一个模型摆多处。
+
+  ============================================================================
+  这个模型在还原真机的什么
+  ============================================================================
+  尺寸与孔位不是随便定的，是按真机检测参数（src/arm_application/config/
+  hole_detect.yaml）反推出来的，每条都对得上：
+
+    两个螺纹孔间距 58mm
+        依据 insert_bolt_radius_mm: 29.0（注释写明"两目标孔物理间距~58mm"）。
+        这两个孔就是二阶段要对准的 k1 / k2。
+
+    孔口是"环"而不是"洞"（视觉上）
+        检测用的是 HoughCircles 找**亮环**，且 hough_min_radius=10 /
+        hough_max_radius=30。换算成物理尺寸（真机 D405：848 宽、87° 视场，
+        fx≈447，相机到工件约 0.23m）：
+            radius_px = r_m × 447 / 0.23 ≈ r_m × 1943
+            10px ≈ 5.1mm     30px ≈ 15.4mm
+        也就是说**能被检测到的圆，半径必须在 5.1~15.4mm 之间**。
+        本模型把每个螺纹孔的亮环外径做成 φ14（半径 7mm → 约 13.6px，落在
+        区间中段），孔本身 φ7（半径 3.5mm → 约 6.8px，**低于下限会被滤掉**）。
+        这正是真机上的情形：检测到的是嵌件的环，不是螺纹孔本身。
+
+    中间有个大孔，且必须被滤掉
+        hole_detect 的 max_radius=30（"滤掉中间大孔"）与 site.yaml 的
+        "过小会配到中心孔" 都说明真件中心有一个大孔。这里做成 φ40
+        （半径 20mm → 约 38.9px > 30）→ 会被 max_radius 正确滤除。
+        它的存在是有意义的：中心的**光孔**正是通止规的"通端要通过"的区域，
+        也是二阶段粗居中时 bbox 的中心特征。
+
+  ============================================================================
+  ⚠️ 两个必须知道的近似（都写在 README 的"仿真≠真机"一节）
+  ============================================================================
+  1) SDF **没有布尔运算**，无法在板上"挖"一个圆孔。所以：
+        碰撞体 = 用 10 个 box 拼出板子，留下**方孔**
+                 中心 40×40mm、两侧 7×7mm
+        视觉   = 同一批 box（保证视觉与碰撞完全一致，不会骗人）
+                 + 每个孔上方贴一个亮圆盘 / 暗圆柱，做出"环 + 暗孔"的样子
+     相机从上往下看到的仍然是**圆环**（贴片是圆的），所以二阶段的圆检测
+     在仿真里能看到该看到的东西；而通止规要穿过的是那个方孔 ——
+     φ6 的规过 7×7 的方孔：对边间隙 0.5mm，足够。
+     方孔在 GUI 里看得出来，这是有意的取舍，不是 bug。
+
+  2) 真机是 **M6 螺纹孔**，仿真里按**光孔**建模（SDF 没有螺纹）。
+     孔的直径（φ7）比 M6 的小径（≈4.9mm）大，是为了让接触求解器稳定：
+     world 的 contact_surface_layer 是 1mm，间隙小于 1mm 时求解器会认为
+     一直贴着。**因此仿真里的插入力/接触力只能定性参考，不能用来标定真机的
+     力阈值** —— 真机阈值必须在真机上标。
+
+  ============================================================================
+  单位：米。SDF 一律用米，用毫米建模的必须先缩放（见 README 的建模要求）。
+  坐标原点：板子**底面中心**。所以场景里把 z 设成台面高度，板子就正好落在台面上。
+  =============================================================================
+-->
+<sdf version="1.9">
+  <model name="workpiece">
+
+    <!-- 静态试跑时可把下面这行改成 true 钉住工件（调试检测/对孔时很有用：
+         否则一次误碰就把它推走了，而你会以为是检测出问题）。
+         正常装配流程必须 false —— 工件被推动本身就是要观察的物理现象。 -->
+    <static>false</static>
+    <self_collide>false</self_collide>
+
+    <link name="body">
+
+      <!-- =====================================================================
+           惯量
+           =====================================================================
+           铝合金（ρ≈2700）实心等效：无孔板体积 0.14×0.10×0.012 = 1.68e-4 m³
+           → 质量 0.454kg。三个孔挖掉约 1.7e-5 m³（≈10%），但这里**不扣**，
+           偏保守（略重 = 略稳，不会因为惯量偏小而在接触里抖）。
+           惯量按整块长方体的公式算：I = m/12 × (另两边平方和)
+           ========================================================================= -->
+      <inertial>
+        <mass>0.454</mass>
+        <inertia>
+          <ixx>3.804e-04</ixx>
+          <ixy>0</ixy>
+          <ixz>0</ixz>
+          <iyy>7.404e-04</iyy>
+          <iyz>0</iyz>
+          <izz>1.110e-03</izz>
+        </inertia>
+      </inertial>
+
+      <!-- =====================================================================
+           碰撞体：10 个 box 拼出的"带方孔的板"
+           =====================================================================
+           切分方式（局部坐标，原点在底面中心，x 沿 140mm 方向）：
+              y 方向切 5 条带，等宽处由孔决定：
+                 A [-0.050,-0.020]   只避开中心孔
+                 B [-0.020,-0.0035]  避开中心孔
+                 C [-0.0035,0.0035]  同时避开中心孔与两侧小孔
+                 D [ 0.0035,0.020]   同 B
+                 E [ 0.020, 0.050]   整条实心
+              x 方向按各带里有哪些孔再切。
+           留下的孔（都是方孔）：
+              中心  x∈[-0.020,0.020] y∈[-0.020,0.020]   40×40mm
+              左    x∈[-0.0325,-0.0255] y∈[-0.0035,0.0035]  7×7mm @ x=-29mm
+              右    x∈[ 0.0255, 0.0325] 同上                7×7mm @ x=+29mm
+           两侧小孔中心距恰好 58mm（0.058），与 insert_bolt_radius_mm=29 对齐。
+           ===================================================================== -->
+
+      <!-- A：最下一条带，整条实心 -->
+      <collision name="plate_a">
+        <pose>0 -0.035 0.006 0 0 0</pose>
+        <geometry><box><size>0.140 0.030 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+
+      <!-- B：中心孔左侧 -->
+      <collision name="plate_b_left">
+        <pose>-0.045 -0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+      <!-- B：中心孔右侧 -->
+      <collision name="plate_b_right">
+        <pose>0.045 -0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+
+      <!-- C：穿过三个孔的那条带，被切成 4 段（见上面 x 切分） -->
+      <collision name="plate_c_far_left">
+        <pose>-0.05125 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0375 0.007 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+      <!-- 中心孔与小孔之间那道 5.5mm 的窄壁 —— 真件上就是这里最薄，
+           也是通止规对孔时最容易别到的地方，保留它是有意义的。 -->
+      <collision name="plate_c_web_left">
+        <pose>-0.02275 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0055 0.007 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+      <collision name="plate_c_web_right">
+        <pose>0.02275 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0055 0.007 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+      <collision name="plate_c_far_right">
+        <pose>0.05125 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0375 0.007 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+
+      <!-- D：中心孔左/右 -->
+      <collision name="plate_d_left">
+        <pose>-0.045 0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+      <collision name="plate_d_right">
+        <pose>0.045 0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+
+      <!-- E：最上一条带，整条实心 -->
+      <collision name="plate_e">
+        <pose>0 0.035 0.006 0 0 0</pose>
+        <geometry><box><size>0.140 0.030 0.012</size></box></geometry>
+        <surface><friction><ode><mu>0.6</mu><mu2>0.6</mu2></ode></friction></surface>
+      </collision>
+
+      <!-- =====================================================================
+           视觉：与碰撞体**同一批 box**（不另画一个"漂亮但不一样"的板子）
+           =====================================================================
+           材质：深灰哑光。选哑光是因为真机的金属件在 D405 的环形光下不会
+           镜面反光到过曝 —— 过曝会把亮环淹掉，检测直接失效。
+           ===================================================================== -->
+      <visual name="plate_a_vis">
+        <pose>0 -0.035 0.006 0 0 0</pose>
+        <geometry><box><size>0.140 0.030 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_b_left_vis">
+        <pose>-0.045 -0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_b_right_vis">
+        <pose>0.045 -0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_c_far_left_vis">
+        <pose>-0.05125 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0375 0.007 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_c_web_left_vis">
+        <pose>-0.02275 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0055 0.007 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_c_web_right_vis">
+        <pose>0.02275 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0055 0.007 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_c_far_right_vis">
+        <pose>0.05125 0 0.006 0 0 0</pose>
+        <geometry><box><size>0.0375 0.007 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_d_left_vis">
+        <pose>-0.045 0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_d_right_vis">
+        <pose>0.045 0.01175 0.006 0 0 0</pose>
+        <geometry><box><size>0.050 0.0165 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+      <visual name="plate_e_vis">
+        <pose>0 0.035 0.006 0 0 0</pose>
+        <geometry><box><size>0.140 0.030 0.012</size></box></geometry>
+        <material>
+          <ambient>0.35 0.36 0.38 1</ambient>
+          <diffuse>0.42 0.43 0.45 1</diffuse>
+        </material>
+      </visual>
+
+      <!-- =====================================================================
+           两个螺纹孔的"嵌件环"（视觉）—— 二阶段要检测的就是这个环
+           =====================================================================
+           做法：一个**亮**圆盘（φ14，环的外径）贴在孔里 2mm 深处，
+           再叠一个**暗**圆柱（φ7，孔本身）比它高 1mm。
+           上往下看：暗圆柱把亮盘中心挡掉 → 剩下的就是一圈亮环（φ7→φ14）。
+           这不是"画个圆假装有孔"，而是用两个实体拼出环的**可见几何**，
+           所以遮挡关系是对的、深度也是对的（孔比面低 1mm）。
+
+           为什么亮盘用 φ14：见文件头 —— 要让环外径落在
+           hough 的 10~30px 有效区间，而 13.6px 正好在区间中段。
+           ===================================================================== -->
+      <visual name="insert_left_ring">
+        <pose>-0.029 0 0.010 0 0 0</pose>
+        <geometry><cylinder><radius>0.007</radius><length>0.001</length></cylinder></geometry>
+        <material>
+          <!-- 亮：嵌件是机加工面，比哑光的板面亮得多 —— 检测靠的就是这个对比 -->
+          <ambient>0.85 0.85 0.82 1</ambient>
+          <diffuse>0.95 0.95 0.90 1</diffuse>
+          <specular>0.2 0.2 0.2 1</specular>
+        </material>
+      </visual>
+      <visual name="insert_left_bore">
+        <pose>-0.029 0 0.0075 0 0 0</pose>
+        <geometry><cylinder><radius>0.0035</radius><length>0.007</length></cylinder></geometry>
+        <material>
+          <!-- 暗：孔内是阴影 + 无光，与亮环形成对比，HoughCircles 才能锁定 -->
+          <ambient>0.02 0.02 0.02 1</ambient>
+          <diffuse>0.03 0.03 0.03 1</diffuse>
+        </material>
+      </visual>
+
+      <visual name="insert_right_ring">
+        <pose>0.029 0 0.010 0 0 0</pose>
+        <geometry><cylinder><radius>0.007</radius><length>0.001</length></cylinder></geometry>
+        <material>
+          <ambient>0.85 0.85 0.82 1</ambient>
+          <diffuse>0.95 0.95 0.90 1</diffuse>
+          <specular>0.2 0.2 0.2 1</specular>
+        </material>
+      </visual>
+      <visual name="insert_right_bore">
+        <pose>0.029 0 0.0075 0 0 0</pose>
+        <geometry><cylinder><radius>0.0035</radius><length>0.007</length></cylinder></geometry>
+        <material>
+          <ambient>0.02 0.02 0.02 1</ambient>
+          <diffuse>0.03 0.03 0.03 1</diffuse>
+        </material>
+      </visual>
+
+      <!-- 中心大孔：只做一个暗的深孔。半径 20mm → 约 38.9px，
+           超过 hough_max_radius=30，会被检测正确滤掉（真件也是这个行为）。 -->
+      <visual name="center_bore">
+        <pose>0 0 0.007 0 0 0</pose>
+        <geometry><cylinder><radius>0.020</radius><length>0.010</length></cylinder></geometry>
+        <material>
+          <ambient>0.02 0.02 0.02 1</ambient>
+          <diffuse>0.03 0.03 0.03 1</diffuse>
+        </material>
+      </visual>
+
+    </link>
+  </model>
+</sdf>