@ziztechnology/dial-library 0.0.11 → 0.0.13

package/README.md

@@ -225,9 +225,11 @@ controller.destroy();
 
 控制器默认每 200ms 读取一次，并保证上一次读取结束后才开始下一次。所有确认都使用传感器时间而不是轮询次数；相同 `sampledAtMs` 的重复数据不会推进窗口。
 
-静止和匀速使用 accelerometer 的 1 秒三轴 MAD 稳健波动窗口，至少需要 5 个唯一样本。运动量不高于 `0.12 m/s²` 且陀螺仪足够稳定，连续 5 秒才进入 `STOPPED`；运动量达到 `0.18 m/s²` 或陀螺仪出现持续运动，连续 0.6 秒进入 `STEADY_DRIVING`。中间区间保持原基础状态。
+静止和匀速使用 accelerometer 的 1 秒三轴 MAD 稳健波动窗口，至少需要 5 个唯一样本。运动量不高于 `0.12 m/s²` 且陀螺仪足够稳定，连续 3 秒才进入 `STOPPED`；运动量达到 `0.18 m/s²` 或陀螺仪出现持续运动，连续 0.6 秒进入 `STEADY_DRIVING`。中间区间保持原基础状态。
 
-普通加速和刹车要求 0.8 秒内至少 4/5 的样本方向一致；急加速和急刹要求峰值、0.6 秒持续均值及方向一致性同时成立，并拒绝垂直能量占主导或短时间反号的颠簸。转向由偏航持续值或累计转角触发并锁存到回正结束。最终优先级为：急加减速、已锁存转向、普通加减速、基础状态。
+普通加速和刹车要求 0.8 秒内至少 4/5 的样本方向一致；急加速和急刹要求峰值、0.6 秒持续均值及方向一致性同时成立，并拒绝垂直能量占主导或短时间反号的颠簸。车辆刚出现方向稳定的物理偏航后，强转向路径要求 0.4 秒内至少 3 个唯一样本，窗口均值达到 `0.08 rad/s`；在默认轮询频率下通常会在 0.4–0.6 秒内触发。转向也可以由累计转角触发，并锁存到回正结束。算法不会预测车辆尚未产生转动时的驾驶意图。最终优先级为：急加减速、已锁存转向、普通加减速、基础状态。
+
+缓慢转向还要求偏航旋转占陀螺仪能量的主要部分，或存在足够的横向加速度；垂直颠簸占主导且缺少偏航佐证时不会创建转向事件。重力样本短时缺失时，控制器会在 `maxSampleAgeMs` 内复用最后一个滤波后的车辆坐标系；缓存到期后按传感器不可用处理。单独调用 `classifyDrivingSnapshot()` 不会使用控制器缓存。
 
 ### 读取当前状态
 
@@ -252,19 +254,29 @@ console.log(snapshot.tuningVersion);
 ```ts
 const controller = createDrivingStatusController({
   tuning: {
-    turnYawThreshold: 0.13,
+    turnYawThreshold: 0.08,
+    turnConfirmationMs: 400,
+    turnMinimumSamples: 3,
     motionWindowMs: 1_200,
     motionMinimumSamples: 6,
     drivingMotionThreshold: 0.2,
     stoppedMotionThreshold: 0.11,
-    stoppedConfirmationMs: 5_000,
+    stoppedConfirmationMs: 3_000,
     longitudinalThreshold: 0.75,
+    turnYawDominanceThreshold: 0.65,
+    turnLateralEvidenceThreshold: 0.3,
   },
 });
 ```
 
 `drivingMotionThreshold` 必须大于 `stoppedMotionThreshold`，进入阈值也必须大于相应退出阈值。样本数必须是正整数，方向一致率必须大于 `0.5` 且不大于 `1`，其余窗口和阈值必须是正有限数值。
 
+### 识别诊断
+
+`onDiagnostic` 的 `sample_available` 事件包含 `frameSource`（`live` 或 `cached`）和 `frameAgeMs`。`detector_evidence` 会报告基础状态 MAD、普通/急加减速的均值、峰值、方向一致率和 RMS，以及转向的累计角度、偏航主导率和横向/垂直 RMS。
+
+检测器状态变化时还会发送 `detector_transition`，其 `phase` 为 `candidate_entered`、`candidate_rejected`、`candidate_confirmed` 或 `candidate_exited`。该事件携带当时的完整 `statistics`，可直接用于真车回放调参；同一状态不会逐轮询重复发送。
+
 惯性传感器无法严格区分“完全静止”和“没有任何振动的理想匀速直线运动”。默认算法使用稳健振动统计、陀螺仪扰动和 5 秒确认近似判断，修改阈值后应使用完整路测过程回放验证。
 
 ### 驱动行车表情

package/dist/index.d.mts

@@ -102,6 +102,10 @@ interface DrivingStatusTuning {
   turnConfirmationMs: number;
   turnIntegratedAngleThreshold: number;
   turnSignCoherence: number;
+  turnYawDominanceThreshold: number;
+  turnLateralEvidenceThreshold: number;
+  turnVerticalNoiseFloor: number;
+  turnVerticalBumpRatio: number;
   turnExitYawThreshold: number;
   turnExitConfirmationMs: number;
   turnClosureWindowMs: number;
@@ -115,6 +119,7 @@ interface DrivingVehicleFrame {
 }
 interface DrivingMetricsCorrection {
   filteredGravity?: Vector3Value;
+  filteredGravitySampledAtMs?: number;
   linearAccelerationBias?: Vector3Value;
   gyroscopeBias?: Vector3Value;
 }
@@ -247,10 +252,54 @@ interface DrivingStatusEvent {
   reason: DrivingStatusChangeReason;
   atMs: number;
 }
+type DrivingFrameSource = 'live' | 'cached';
+type DrivingDetectorName = 'base' | 'rapid_longitudinal' | 'longitudinal' | 'turn';
+type DrivingDetectorTransitionPhase = 'candidate_entered' | 'candidate_rejected' | 'candidate_confirmed' | 'candidate_exited';
+type DrivingDetectorRejectionReason = 'vertical_bump' | 'longitudinal_reversal' | null;
+interface DrivingBaseDetectorStatistics {
+  sampleCount: number;
+  durationMs: number;
+  motionMad: number | null;
+  gyroMagnitude: number;
+  rawGyroMagnitude: number;
+}
+interface DrivingLongitudinalWindowStatistics {
+  sampleCount: number;
+  durationMs: number;
+  mean: number;
+  peak: number;
+  coherence: number;
+}
+interface DrivingRapidLongitudinalStatistics extends DrivingLongitudinalWindowStatistics {
+  longitudinalRms: number;
+  verticalRms: number;
+  hasReversal: boolean;
+}
+interface DrivingTurnDetectorStatistics {
+  sampleCount: number;
+  durationMs: number;
+  strongMean: number;
+  strongCoherence: number;
+  signedAngle: number;
+  gentleCoherence: number;
+  yawRms: number;
+  rawGyroRms: number;
+  yawDominance: number;
+  lateralRms: number;
+  verticalRms: number;
+}
+interface DrivingDetectorStatistics {
+  base: DrivingBaseDetectorStatistics;
+  longitudinal: DrivingLongitudinalWindowStatistics | null;
+  rapidLongitudinal: DrivingRapidLongitudinalStatistics | null;
+  turn: DrivingTurnDetectorStatistics | null;
+}
 type DrivingStatusDiagnosticEvent = {
   type: 'sample_available';
   atMs: number;
   capturedAtMs: number;
+  frameSource: DrivingFrameSource;
+  frameAgeMs: number;
   tuningVersion: string;
 } | {
   type: 'sample_unavailable';
@@ -266,7 +315,19 @@ type DrivingStatusDiagnosticEvent = {
   rapidCandidate: 'RAPID_ACCELERATION' | 'SUDDEN_BRAKING' | null;
   longitudinalCandidate: 'ACCELERATION' | 'BRAKING' | null;
   turnCandidate: 'LEFT_TURN' | 'RIGHT_TURN' | null;
-  rejectionReason: 'vertical_bump' | 'longitudinal_reversal' | null;
+  rejectionReason: DrivingDetectorRejectionReason;
+  frameSource: DrivingFrameSource;
+  frameAgeMs: number;
+  statistics: DrivingDetectorStatistics;
+  tuningVersion: string;
+} | {
+  type: 'detector_transition';
+  atMs: number;
+  detector: DrivingDetectorName;
+  phase: DrivingDetectorTransitionPhase;
+  status: CarRunningStatus | null;
+  rejectionReason: DrivingDetectorRejectionReason;
+  statistics: DrivingDetectorStatistics;
   tuningVersion: string;
 } | {
   type: 'candidate_changed';
@@ -352,6 +413,10 @@ interface DrivingExpressionPlayerSnapshot {
 }
 interface DrivingExpressionPlayerOptions {
   config: DrivingExpressionsConfigInput;
+  /**
+   * Emoji and image entries are renderable fallbacks. Other structured kinds
+   * remain accepted for source compatibility but are reported as invalid_config.
+   */
   fallbacks?: Partial<Readonly<Record<CarRunningStatus, StructuredDrivingExpressionMedia>>>;
   loadTimeoutMs?: number;
   retryBackoffMs?: number;
@@ -373,4 +438,4 @@ interface DrivingExpressionPlayer {
 }
 declare const createDrivingExpressionPlayer: (container: HTMLElement, options: DrivingExpressionPlayerOptions) => DrivingExpressionPlayer;
 //#endregion
-export { AvailableSensorMetric, BATTERY_HEALTH_LABELS, BatteryCapacityValue, BatteryHealth, BatteryPlugged, BatteryStateValue, BatteryStatus, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, CarRunningStatus, CompleteDrivingExpressionsConfig, DEFAULT_DRIVING_STATUS_TUNING, DrivingControllerSnapshot, DrivingExpressionMedia, DrivingExpressionPlayer, DrivingExpressionPlayerDiagnosticEvent, DrivingExpressionPlayerErrorCategory, DrivingExpressionPlayerOptions, DrivingExpressionPlayerSnapshot, DrivingExpressionResolutionError, DrivingExpressionsConfig, DrivingExpressionsConfigError, DrivingExpressionsConfigErrorCode, DrivingExpressionsConfigInput, DrivingMetricsCorrection, DrivingSensorProvider, DrivingSnapshotAnalysis, DrivingSnapshotCandidate, DrivingSnapshotMetrics, DrivingSnapshotRejectionReason, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, DrivingVehicleFrame, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, buildVehicleFrame, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };
+export { AvailableSensorMetric, BATTERY_HEALTH_LABELS, BatteryCapacityValue, BatteryHealth, BatteryPlugged, BatteryStateValue, BatteryStatus, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, CarRunningStatus, CompleteDrivingExpressionsConfig, DEFAULT_DRIVING_STATUS_TUNING, DrivingBaseDetectorStatistics, DrivingControllerSnapshot, DrivingDetectorName, DrivingDetectorRejectionReason, DrivingDetectorStatistics, DrivingDetectorTransitionPhase, DrivingExpressionMedia, DrivingExpressionPlayer, DrivingExpressionPlayerDiagnosticEvent, DrivingExpressionPlayerErrorCategory, DrivingExpressionPlayerOptions, DrivingExpressionPlayerSnapshot, DrivingExpressionResolutionError, DrivingExpressionsConfig, DrivingExpressionsConfigError, DrivingExpressionsConfigErrorCode, DrivingExpressionsConfigInput, DrivingFrameSource, DrivingLongitudinalWindowStatistics, DrivingMetricsCorrection, DrivingRapidLongitudinalStatistics, DrivingSensorProvider, DrivingSnapshotAnalysis, DrivingSnapshotCandidate, DrivingSnapshotMetrics, DrivingSnapshotRejectionReason, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, DrivingTurnDetectorStatistics, DrivingVehicleFrame, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, buildVehicleFrame, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };