fix(ocr): 引擎就绪状态真实化——engine_ready 替代线程心跳判定

就绪清单/模型面板/设备设置/系统徽标四处改用 engine_ready（worker 加载成功/失败回写）：此前 ocr_alive 线程心跳在引擎加载失败时仍为 true，OCR 全挂仍显示 ✓；未就绪时不再显示请求态后端（GPU (CUDA #0)）冒充生效态。单测补充 engine_ready 缺省/往返/旧载荷兼容。

Author: Aparencia

app/src-tauri/src/commands_diag.rs

@@ -32,6 +32,8 @@ pub struct DiagSnapshot {
     pub ocr_failures: u64,
     pub ocr_backend: OcrBackend,
     pub ocr_fallback_reason: Option<String>,
+    /// v0.12.1：OCR 引擎加载成功标志（false=加载中/失败——系统徽标据此告警）
+    pub ocr_engine_ready: bool,
 }
 
 /// 健康巡检（磁盘剩余 + 模型文件 + 引擎线程心跳）。
@@ -51,7 +53,9 @@ pub fn health_status(state: State<'_, AppState>) -> HealthSnapshot {
     };
     let (asr_alive, ocr_alive) = state.engines.liveness();
     // 模型完整性：流式四件套 + 离线 SenseVoice（审查修复——此前仅查流式，
-    // sensevoice 缺失要到首次识别失败才能暴露；OCR 模型经 ModelScope 缓存路径不稳定，留日志侧）
+    // sensevoice 缺失要到首次识别失败才能暴露）。OCR 模型由 oar-ocr 托管在
+    // $OAR_HOME（默认 ~/.oar，非 app 模型目录）——就绪状态经 ocr_device_status
+    // 的 engine_ready 暴露（加载成功才算就绪），不在此处查文件清单。
     // TD-2026-08-20-E/F 清偿：增查说话人（wespeaker）与标点恢复模型——
     // 此前就绪清单（ReadyCheckCard）不含这两项，缺失要到会话页才暴露
     let missing = {
@@ -103,6 +107,7 @@ pub fn diag_snapshot(state: State<'_, AppState>) -> DiagSnapshot {
         ocr_failures,
         ocr_backend: status.actual,
         ocr_fallback_reason: status.fallback_reason,
+        ocr_engine_ready: status.engine_ready,
     }
 }
 

app/src-tauri/src/device_config.rs

@@ -59,6 +59,10 @@ pub struct OcrDeviceStatus {
     pub actual: OcrBackend,
     /// 回退原因（无回退为 None；如"运行时无 CUDA 支持"）
     pub fallback_reason: Option<String>,
+    /// 引擎是否加载成功（v0.12.1：true=加载成功可用；false=加载中或加载失败——
+    /// 失败原因见 fallback_reason；线程心跳 alive ≠ 引擎就绪，前端不得混用）
+    #[serde(default)]
+    pub engine_ready: bool,
     /// 最近校准基准
     pub bench: Option<BenchResult>,
     /// 校准进行中标记（前端轮询用）
@@ -67,7 +71,15 @@ pub struct OcrDeviceStatus {
 
 impl OcrDeviceStatus {
     pub fn new(mode: OcrDeviceMode, requested: OcrBackend, bench: Option<BenchResult>) -> Self {
-        Self { mode, requested, actual: requested, fallback_reason: None, bench, calibrating: false }
+        Self {
+            mode,
+            requested,
+            actual: requested,
+            fallback_reason: None,
+            engine_ready: false,
+            bench,
+            calibrating: false,
+        }
     }
 }
 
@@ -241,5 +253,29 @@ mod tests {
         assert_eq!(s.requested, s.actual);
         assert!(!s.calibrating);
         assert!(s.fallback_reason.is_none());
+        // v0.12.1：新建状态引擎未就绪（worker 加载成功后才置 true）
+        assert!(!s.engine_ready);
+    }
+
+    #[test]
+    fn status_roundtrip_keeps_engine_ready() {
+        // v0.12.1：engine_ready 缺省反序列化为 false（旧前端/旧 JSON 零回归）；
+        // 显式 false 往返一致
+        let s = OcrDeviceStatus {
+            mode: OcrDeviceMode::ForceCpu,
+            requested: OcrBackend::Cpu,
+            actual: OcrBackend::Cpu,
+            fallback_reason: Some("请求后端 Cuda 构建失败".to_string()),
+            engine_ready: false,
+            bench: None,
+            calibrating: false,
+        };
+        let json = serde_json::to_string(&s).unwrap();
+        let back: OcrDeviceStatus = serde_json::from_str(&json).unwrap();
+        assert_eq!(back, s);
+        // 无 engine_ready 键的旧载荷 → false（不阻断反序列化）
+        let legacy = r#"{"mode":"Auto","requested":{"Cuda":{"device_id":0}},"actual":{"Cuda":{"device_id":0}},"fallback_reason":null,"bench":null,"calibrating":false}"#;
+        let from_legacy: OcrDeviceStatus = serde_json::from_str(legacy).unwrap();
+        assert!(!from_legacy.engine_ready);
     }
 }

app/src-tauri/src/engine_worker.rs

@@ -149,14 +149,22 @@ pub(crate) fn ocr_worker_loop(
                     .unwrap_or_default()
             );
             if let Ok(mut s) = device_status.lock() {
+                // v0.12.1：engine_ready 与 actual/fallback_reason 一起回写——
+                // 前端就绪判定必须用 engine_ready，不得用线程心跳（活 ≠ 引擎就绪）
                 s.actual = engine.backend;
+                s.engine_ready = true;
                 s.fallback_reason = engine.fallback_reason.clone();
             }
         }
         Err(e) => {
             eprintln!("[Engine] OCR 引擎加载失败: {}", e);
             if let Ok(mut s) = device_status.lock() {
-                s.fallback_reason = Some(format!("OCR 引擎加载失败: {}", e));
+                // v0.12.1：失败显式回写 engine_ready=false（加载中的初始值也是 false，
+                // 重启场景仍显式置位，防未来复用旧状态）；附可行动提示——
+                // auto-download 已恢复，重启应用即重试 ModelScope 缓存命中/下载
+                s.engine_ready = false;
+                s.fallback_reason =
+                    Some(format!("OCR 引擎加载失败: {}（模型缺失或下载失败——重启应用自动重试）", e));
             }
         }
     }

app/src/components/ModelManagementPanel.tsx

@@ -16,7 +16,7 @@ import { invoke } from "@tauri-apps/api/core";
 import { listen } from "@tauri-apps/api/event";
 import StructureModelSetting from "./StructureModelSetting";
 // L11 去重：HealthSnapshot/StreamingModelStatus/DownloadProgress 单一定义源在 types/system.ts
-import type { DownloadProgress, HealthSnapshot, StreamingModelStatus } from "../types";
+import type { DownloadProgress, HealthSnapshot, OcrDeviceStatus, StreamingModelStatus } from "../types";
 
 /** 说话人下载状态。 */
 interface SpeakerDownloadStatus {
@@ -31,6 +31,7 @@ const badge: React.CSSProperties = { fontSize: 11, padding: "1px 8px", borderRad
 
 export default function ModelManagementPanel() {
   const [health, setHealth] = useState<HealthSnapshot | null>(null);
+  const [ocr, setOcr] = useState<OcrDeviceStatus | null>(null);
   const [streaming, setStreaming] = useState<StreamingModelStatus | null>(null);
   const [streamProgress, setStreamProgress] = useState<DownloadProgress | null>(null);
   const [streamBusy, setStreamBusy] = useState(false);
@@ -41,12 +42,14 @@ export default function ModelManagementPanel() {
   const refresh = useCallback(async () => {
     setError("");
     try {
-      const [h, s] = await Promise.all([
+      const [h, s, o] = await Promise.all([
         invoke<HealthSnapshot>("health_status"),
         invoke<StreamingModelStatus>("asr_streaming_model_status"),
+        invoke<OcrDeviceStatus>("ocr_device_status"),
       ]);
       setHealth(h);
       setStreaming(s);
+      setOcr(o);
       setSpeaker(await invoke<SpeakerDownloadStatus>("speaker_model_download_status"));
     } catch (e) {
       setError(`模型状态查询失败: ${e}`);
@@ -177,15 +180,19 @@ export default function ModelManagementPanel() {
         <span style={{ fontSize: 10.5, color: "#9ca3af" }}>脚本 scripts/download-punctuation.mjs 可安装</span>
       </div>
 
-      {/* OCR 模型（ModelScope 自动缓存） */}
+      {/* OCR 模型（ModelScope 自动缓存）——v0.12.1：就绪判定用 engine_ready
+          （引擎加载成功），不再用 ocr_alive 线程心跳（活 ≠ 就绪） */}
       <div style={{ display: "flex", alignItems: "center", gap: 8, marginBottom: 9, flexWrap: "wrap" }}>
         <span style={{ fontSize: 11, width: 200 }}>OCR（PP-OCRv6）</span>
-        {health?.ocr_alive ? (
+        {ocr?.engine_ready ? (
           <span style={{ ...badge, background: "#f0fdfa", color: "#0d9488" }}>✓ 引擎运行中</span>
         ) : (
-          <span style={{ ...badge, background: "#fffbeb", color: "#b45309" }}>引擎未就绪</span>
+          <span style={{ ...badge, background: "#fef2f2", color: "#dc2626" }}>✗ 引擎未就绪</span>
         )}
         <span style={{ fontSize: 10.5, color: "#9ca3af" }}>首次使用经 ModelScope 自动缓存</span>
+        {!ocr?.engine_ready && (
+          <span style={{ fontSize: 10.5, color: "#b45309" }}>重启应用自动重试；失败原因见设置页「OCR 推理设备」</span>
+        )}
       </div>
 
       {/* 结构模型（版面/表格/公式——原结构分析模型区段） */}

app/src/components/OcrDeviceSetting.tsx

@@ -137,8 +137,23 @@ export function OcrDeviceSetting() {
       </div>
       {status && (
         <div style={{ fontSize: 11, lineHeight: 1.7, color: "#6b7280" }}>
+          {!status.engine_ready && (
+            <div
+              style={{
+                background: "#fef2f2",
+                border: "1px solid #fecaca",
+                borderRadius: 6,
+                padding: "5px 8px",
+                marginBottom: 6,
+                color: "#b91c1c",
+              }}
+            >
+              ⚠ OCR 引擎未就绪：模型文件缺失或下载失败，重启应用自动重试（
+              <span style={{ fontWeight: 600 }}>{backendLabel(status.actual)}</span> 请求未生效）
+            </div>
+          )}
           <div>
-            当前后端：
+            {status.engine_ready ? "当前后端：" : "请求后端："}
             <b style={{ color: backendLabel(status.actual) === "CPU" ? "#6b7280" : "#0d9488" }}>
               {backendLabel(status.actual)}
             </b>
@@ -150,7 +165,10 @@ export function OcrDeviceSetting() {
             <div style={{ color: "#b45309" }}>⚠ {status.fallback_reason}</div>
           )}
           {status.bench && (
-            <div>校准：CPU {status.bench.cpu_ms.toFixed(1)}ms / GPU {status.bench.gpu_ms.toFixed(1)}ms</div>
+            <div style={{ color: status.engine_ready ? undefined : "#9ca3af" }}>
+              校准：CPU {status.bench.cpu_ms.toFixed(1)}ms / GPU {status.bench.gpu_ms.toFixed(1)}ms
+              {!status.engine_ready && "（历史基准，引擎恢复后重新检测）"}
+            </div>
           )}
         </div>
       )}

app/src/components/ReadyCheckCard.tsx

@@ -21,6 +21,8 @@ interface OcrDeviceStatus {
   mode: string;
   actual: string | { Cuda: { device_id: number } };
   fallback_reason: string | null;
+  /** v0.12.1：引擎加载成功标志（false=加载中/失败；就绪判定以此为准） */
+  engine_ready: boolean;
 }
 
 interface ReadyItem {
@@ -78,11 +80,15 @@ export default function ReadyCheckCard() {
           detail: missingPunct.length > 0 ? "未下载（无标点降级，不影响转写）" : undefined,
         },
         {
-          label: `OCR 引擎（${ocrBackendLabel(ocr.actual)}）`,
-          ok: health.ocr_alive,
-          warn: !health.ocr_alive ? false : !!ocr.fallback_reason,
-          detail: !health.ocr_alive
-            ? "引擎未就绪"
+          // v0.12.1：就绪判定由线程心跳改为 engine_ready（加载成功才算就绪；
+          // 原 ocr_alive 在引擎加载失败时仍为 true——线程活着≠引擎可用，
+          // 曾导致 OCR 全挂仍显示 ✓ 的误报）；未就绪时标签不显示后端，
+          // 避免"GPU (CUDA #0)"这类请求态冒充生效态
+          label: `OCR 引擎（${ocr.engine_ready ? ocrBackendLabel(ocr.actual) : "未就绪"}）`,
+          ok: ocr.engine_ready,
+          warn: !ocr.engine_ready ? false : !!ocr.fallback_reason,
+          detail: !ocr.engine_ready
+            ? "引擎未就绪" + (ocr.fallback_reason ? `：${ocr.fallback_reason}` : "")
             : ocr.fallback_reason ?? undefined,
         },
         {

app/src/components/SystemStatusBadge.tsx

@@ -20,6 +20,8 @@ interface DiagSnapshot {
   ocr_failures: number;
   ocr_backend: string | { Cuda: { device_id: number } };
   ocr_fallback_reason: string | null;
+  /** v0.12.1：OCR 引擎加载成功标志（false=加载中/失败——徽标告警依据） */
+  ocr_engine_ready: boolean;
 }
 
 function backendLabel(b: DiagSnapshot["ocr_backend"]): string {
@@ -53,7 +55,14 @@ export function SystemStatusBadge() {
     return () => clearInterval(timer);
   }, [refresh]);
 
-  const warn = health?.disk_warn || (health?.missing_models.length ?? 0) > 0 || health?.asr_alive === false || health?.ocr_alive === false;
+  // v0.12.1：OCR 引擎加载失败（engine_ready=false）计入告警——此前仅看线程心跳，
+  // 引擎挂了仍显示健康
+  const warn =
+    health?.disk_warn ||
+    (health?.missing_models.length ?? 0) > 0 ||
+    health?.asr_alive === false ||
+    health?.ocr_alive === false ||
+    diag?.ocr_engine_ready === false;
   const engineDown = health && (health.asr_alive === false || health.ocr_alive === false);
 
   return (
@@ -103,6 +112,9 @@ export function SystemStatusBadge() {
             引擎心跳：ASR {health?.asr_alive ? "●" : "✗"} OCR {health?.ocr_alive ? "●" : "✗"}
             {engineDown && <b style={{ color: "#dc2626" }}>（引擎异常）</b>}
           </div>
+          <div>
+            OCR 引擎：{diag?.ocr_engine_ready ? "✓ 就绪" : <b style={{ color: "#dc2626" }}>未就绪（重启应用重试）</b>}
+          </div>
           <hr style={{ border: "none", borderTop: "1px solid #f3f4f6", margin: "6px 0" }} />
           <div style={{ fontWeight: 600, marginBottom: 4 }}>诊断（开发期）</div>
           <div>OCR 缓存：命中 {diag?.ocr_cache_hits ?? 0} / 未中 {diag?.ocr_cache_misses ?? 0}（{diag?.ocr_hit_rate.toFixed(0)}%）</div>

app/src/types/system.ts

@@ -59,6 +59,8 @@ export interface OcrDeviceStatus {
   requested: OcrBackend;
   actual: OcrBackend;
   fallback_reason: string | null;
+  /** v0.12.1：引擎加载成功标志（false=加载中/失败；就绪判定以此为准，非线程心跳） */
+  engine_ready: boolean;
   bench: BenchResult | null;
   calibrating: boolean;
 }