| name | direction-stabilization |
| description | Use when modifying SmartDash direction/heading display, DirectionStabilizer, HeadingTracker, DirectionLabelFormatter, or any code that affects the top-right corner heading indicator. Enforces speed-layered freezing, GPS/sensor quality gating, deadband, exponential smoothing, turn rate limiting, and label hysteresis. |
SmartDash Direction Stabilization
本 skill 用于所有涉及以下主题的修改：
- 仪表右上角方向显示
DirectionStabilizer.kt 算法调参HeadingTracker.kt 原始方向暴露DirectionLabelFormatter.kt 文字方位格式化MainViewModel.stableDirectionDegrees / rideDirectionLabel
核心设计原则
方向显示不是"车头朝向"，而是"稳定行进方向"。
两轮车的车头会频繁微调（修把、避让、等红灯），如果 UI 跟着车头走，观感就是持续抽动。
5 级处理管线（不可跳过）
原始输入 (GPS bearing + sensor heading)
│
▼
1. 速度分层冻结
speed < 3 km/h → FROZEN
│
▼
2. 来源质量门控
GPS: age ≤ 2500ms, accuracy ≤ 25m, step ≥ 3m (低速)
Sensor: age ≤ 1500ms
│
▼
3. 死区过滤
Δ < 5° → 不更新
│
▼
4. 速度分层指数平滑
alpha: 0.00 / 0.06 / 0.12 / 0.20 / 0.30 (按速度分层)
│
▼
5. 转向速率限制
maxTurnRate: 35 / 50 / 70 / 90 °/s (按速度分层)
│
▼
stableDirectionDeg → DirectionLabelFormatter (12° 滞回) → UI
必守规则
1. 不要修改 HeadingTracker 传感器底层逻辑
HeadingTracker 的职责是原始数据采集和暴露。所有稳定化处理必须在 DirectionStabilizer 中完成。
2. 速度冻结是硬性约束
speed < 3 km/h 时方向必须冻结。这不是可选项，是消除静止抖动的第一道防线。
3. GPS 质量门控不可省略
只看 hasBearing() 不够。必须同时检查：
age ≤ GPS_MAX_AGE_MSaccuracy ≤ GPS_MAX_ACCURACY_M- 低速时
stepDistance ≥ GPS_MIN_STEP_DISTANCE_M
4. 文字方位必须带滞回
8 方位边界附近（如北 ↔ 东北 22.5°）极易跳字。DirectionLabelFormatter 的 hysteresisDeg = 12f 确保方向进入新扇区足够深才切换。
5. 调参只改 DirectionStabilizer 参数
不要为了调体验去改 HeadingTracker 的传感器注册/解注册逻辑、alpha 或者原始 heading 计算。所有体验调整都通过 DirectionStabilizer 的常量完成。
参数调优指南
方向还敏感？
逐步提高以下参数（每次只改一个）：
DEAD_BAND_DEG: 5° → 6° → 8°- 整体
alpha 降低 0.02
- 低速冻结阈值: 3 → 4 km/h
方向反应太慢？
逐步放宽以下参数：
DEAD_BAND_DEG: 5° → 4° → 3°- 15+ km/h
alpha: 0.20 → 0.25
maxTurnRate: 各档位 +10°/s
相关文件
data/gps/DirectionStabilizer.kt — 5 级管线data/gps/DirectionLabelFormatter.kt — 文字格式化 + 滞回data/gps/HeadingTracker.kt — 原始方向提供层MainViewModel.kt — stableDirectionDegrees + rideDirectionLabel.agents/workflows/direction-stabilization.md — 详细工作流
