双目测距方案重构与其他小修改

utils/stereo_ranger/warn_throttle.py

@@ -0,0 +1,30 @@
+"""告警节流器（§4/§5）：每类异常"第 1 次 + 每满 100 次"打印，带累计计数。
+
+高频热路径（每帧数学）不打日志；所有异常日志走本通道，且不落在数学热路径
+的决策上（§11.3 单周期处理无阻塞、无 IO）。
+"""
+
+from typing import Dict
+
+
+class WarnThrottle:
+    """按异常类独立计数与限频。"""
+
+    def __init__(self, every: int = 100) -> None:
+        if every < 1:
+            raise ValueError("every 必须 ≥ 1")
+        self._every = every
+        self._counts: Dict[str, int] = {}
+
+    def should_emit(self, category: str) -> bool:
+        """推进该类异常计数并返回本次是否应打印（第 1 次 + 每满 every 次）。"""
+        count = self._counts.get(category, 0) + 1
+        self._counts[category] = count
+        return count == 1 or count % self._every == 0
+
+    def count(self, category: str) -> int:
+        """该类异常的累计次数。"""
+        return self._counts.get(category, 0)
+
+    def clear(self) -> None:
+        self._counts.clear()