From 4adb50c5a087f7bfc2882a275cafa1894dadb212 Mon Sep 17 00:00:00 2001
From: hllshiro <hllshiro@users.noreply.github.com>
Date: Sun, 16 Aug 2026 18:34:00 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat(settings):=20=E6=A8=A1=E5=9E=8B?=
 =?UTF-8?q?=E8=B7=AF=E7=94=B1=E8=BF=9E=E9=80=9A=E6=80=A7=E6=A3=80=E6=9F=A5?=
 =?UTF-8?q?=E7=BB=9F=E4=B8=80=E7=8A=B6=E6=80=81=E7=AE=A1=E7=90=86=EF=BC=88?=
 =?UTF-8?q?single-flight=20+=20=E6=8C=87=E7=BA=B9=E7=BC=93=E5=AD=98?=
 =?UTF-8?q?=EF=BC=89=20=20-=20=E5=90=8E=E7=AB=AF=EF=BC=9A=E6=96=B0?=
 =?UTF-8?q?=E5=A2=9E=20checkController=20=E7=BB=9F=E4=B8=80=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81=E6=9C=BA=EF=BC=88idle/running/done=EF=BC=89=EF=BC=8Cs?=
 =?UTF-8?q?ingle-flight=20=E5=B9=B6=E5=8F=91=E5=8E=BB=E9=87=8D=EF=BC=8C=20?=
 =?UTF-8?q?=20=20=E9=85=8D=E7=BD=AE=E6=8C=87=E7=BA=B9=E7=BC=93=E5=AD=98?=
 =?UTF-8?q?=EF=BC=88force=20=E5=8F=AF=E7=BB=95=E8=BF=87=EF=BC=89=EF=BC=8C?=
 =?UTF-8?q?=E5=85=A8=E5=A4=B1=E8=B4=A5=E4=B8=8D=E6=9B=B4=E6=96=B0=E6=8C=87?=
 =?UTF-8?q?=E7=BA=B9=20-=20connectivity.ts=EF=BC=9A=E6=8A=BD=E5=8F=96?=
 =?UTF-8?q?=E5=AF=BC=E5=87=BA=20runModelRoutesProbe=EF=BC=8CtestModelRoute?=
 =?UTF-8?q?s=20=E4=BF=9D=E7=95=99=E4=B8=BA=E5=85=BC=E5=AE=B9=E8=96=84?=
 =?UTF-8?q?=E5=B0=81=E8=A3=85=20-=20=E8=B7=AF=E7=94=B1=EF=BC=9APOST=20/mod?=
 =?UTF-8?q?el-routes/connectivity=20=E6=8E=A5=E5=8F=97=20{=20force=20}?=
 =?UTF-8?q?=EF=BC=8C=E6=96=B0=E5=A2=9E=20GET=20.../status=20-=20=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=EF=BC=9AuseModelRouteCheck=20=E7=BB=9F=E4=B8=80=20Hoo?=
 =?UTF-8?q?k=EF=BC=88=E8=BF=9B=E5=85=A5=E9=A1=B5=E9=9D=A2=E9=9B=B6?=
 =?UTF-8?q?=E6=8E=A2=E9=92=88=EF=BC=8Crunning=20=E8=BD=AE=E8=AF=A2=202s?=
 =?UTF-8?q?=EF=BC=89=EF=BC=9B=20=20=20ModelRoutesPage=20/=20SettingsOvervi?=
 =?UTF-8?q?ewPage=20=E6=8E=A5=E5=85=A5=EF=BC=9BReadinessCard=20=E5=A2=9E?=
 =?UTF-8?q?=E5=8A=A0=E6=9C=AA=E6=A3=80=E6=B5=8B=E7=8A=B6=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 client/src/api/settings.ts                    |  26 +++-
 client/src/hooks/useModelRouteCheck.ts        |  48 +++++++
 client/src/pages/settings/ModelRoutesPage.tsx |  48 +++----
 .../components/SettingsReadinessCard.tsx      |  26 +++-
 .../settings/views/SettingsOverviewPage.tsx   |  15 +-
 server/src/llm/checkController.ts             | 132 ++++++++++++++++++
 server/src/llm/connectivity.ts                |  35 +++--
 server/src/routes/llm.ts                      |  21 ++-
 8 files changed, 295 insertions(+), 56 deletions(-)
 create mode 100644 client/src/hooks/useModelRouteCheck.ts
 create mode 100644 server/src/llm/checkController.ts

diff --git a/client/src/api/settings.ts b/client/src/api/settings.ts
index 13d98eaa42..c2ac163707 100644
--- a/client/src/api/settings.ts
+++ b/client/src/api/settings.ts
@@ -169,6 +169,18 @@ export interface ModelRouteConnectivityResponse {
   statuses: ModelRouteConnectivityStatus[];
 }
 
+export type ModelRouteConnectivityCheckStatus = "idle" | "running" | "done";
+
+export interface ModelRouteConnectivityCheckResponse {
+  status: ModelRouteConnectivityCheckStatus;
+  taskId: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  fingerprint: string | null;
+  result: ModelRouteConnectivityResponse | null;
+  cached?: boolean;
+}
+
 export interface StructuredFallbackSettings {
   enabled: boolean;
   provider: LLMProvider;
@@ -418,8 +430,18 @@ export async function getModelRoutes() {
   return data;
 }
 
-export async function testModelRouteConnectivity() {
-  const { data } = await apiClient.post<ApiResponse<ModelRouteConnectivityResponse>>("/llm/model-routes/connectivity");
+export async function testModelRouteConnectivity(force = false) {
+  const { data } = await apiClient.post<ApiResponse<ModelRouteConnectivityCheckResponse>>(
+    "/llm/model-routes/connectivity",
+    { force },
+  );
+  return data;
+}
+
+export async function getModelRouteConnectivityStatus() {
+  const { data } = await apiClient.get<ApiResponse<ModelRouteConnectivityCheckResponse>>(
+    "/llm/model-routes/connectivity/status",
+  );
   return data;
 }
 
diff --git a/client/src/hooks/useModelRouteCheck.ts b/client/src/hooks/useModelRouteCheck.ts
new file mode 100644
index 0000000000..e38095bcd8
--- /dev/null
+++ b/client/src/hooks/useModelRouteCheck.ts
@@ -0,0 +1,48 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { getModelRouteConnectivityStatus, testModelRouteConnectivity } from "@/api/settings";
+import { queryKeys } from "@/api/queryKeys";
+
+/**
+ * 模型路由连通性检查统一 Hook。
+ *
+ * - 所有设置页面共用同一状态源（后端 single-flight 状态机 + 指纹缓存）
+ * - 进入页面只查 GET /status（轻量），绝不自动触发探针
+ * - running 时自动轮询（2s），done/idle 停止
+ * - triggerCheck(force)：手动刷新；checkAfterConfigChange()：保存路由后自动检查
+ */
+export function useModelRouteCheck() {
+  const queryClient = useQueryClient();
+  const checkKey = queryKeys.settings.modelRouteConnectivity;
+
+  const statusQuery = useQuery({
+    queryKey: checkKey,
+    queryFn: getModelRouteConnectivityStatus,
+    refetchInterval: (query) => (query.state.data?.data?.status === "running" ? 2000 : false),
+    refetchOnWindowFocus: false,
+  });
+
+  const triggerCheck = useMutation({
+    mutationFn: (force: boolean) => testModelRouteConnectivity(force),
+    onSuccess: (resp) => {
+      // 统一状态写入，跨页面共享
+      queryClient.setQueryData(checkKey, resp);
+      if (resp.data?.status === "running") {
+        void statusQuery.refetch();
+      }
+    },
+  });
+
+  return {
+    /** 当前检查状态（idle/running/done + result），来自 GET /status */
+    status: statusQuery.data?.data,
+    /** 是否正在检查（POST 进行中 或 后端 running） */
+    isChecking: triggerCheck.isPending || statusQuery.data?.data?.status === "running",
+    /** 触发检查：true 强制绕过指纹缓存（仍受 single-flight 约束） */
+    triggerCheck,
+    /** 配置变更后自动触发新检查（指纹变化 → 后端启动新任务） */
+    checkAfterConfigChange: () => {
+      void queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRoutes });
+      triggerCheck.mutate(false);
+    },
+  };
+}
diff --git a/client/src/pages/settings/ModelRoutesPage.tsx b/client/src/pages/settings/ModelRoutesPage.tsx
index 444239cfb8..82e786ab4a 100644
--- a/client/src/pages/settings/ModelRoutesPage.tsx
+++ b/client/src/pages/settings/ModelRoutesPage.tsx
@@ -9,8 +9,8 @@ import {
   getStructuredFallbackConfig,
   saveModelRoute,
   saveStructuredFallbackConfig,
-  testModelRouteConnectivity,
 } from "@/api/settings";
+import { useModelRouteCheck } from "@/hooks/useModelRouteCheck";
 import { queryKeys } from "@/api/queryKeys";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -61,12 +61,12 @@ export default function ModelRoutesPage() {
     queryFn: getModelRoutes,
   });
 
-  const modelRouteConnectivityQuery = useQuery({
-    queryKey: queryKeys.settings.modelRouteConnectivity,
-    queryFn: testModelRouteConnectivity,
-    enabled: modelRoutesQuery.isSuccess,
-    refetchOnWindowFocus: false,
-  });
+  const {
+    status: connectivityCheck,
+    isChecking,
+    triggerCheck,
+    checkAfterConfigChange,
+  } = useModelRouteCheck();
 
   const structuredFallbackQuery = useQuery({
     queryKey: queryKeys.settings.structuredFallback,
@@ -78,10 +78,8 @@ export default function ModelRoutesPage() {
     mutationFn: (payload: RouteSavePayload) => saveModelRoute(payload),
     onSuccess: async () => {
       setActionResult("保存完成，这个任务会使用新路由。");
-      await Promise.all([
-        queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRoutes }),
-        queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRouteConnectivity }),
-      ]);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRoutes });
+      checkAfterConfigChange();
     },
   });
 
@@ -92,10 +90,8 @@ export default function ModelRoutesPage() {
     },
     onSuccess: async (count) => {
       setActionResult(`保存完成，${count} 个任务会使用新路由。`);
-      await Promise.all([
-        queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRoutes }),
-        queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRouteConnectivity }),
-      ]);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRoutes });
+      checkAfterConfigChange();
     },
   });
 
@@ -103,16 +99,14 @@ export default function ModelRoutesPage() {
     mutationFn: (payload: Partial<StructuredFallbackSettings>) => saveStructuredFallbackConfig(payload),
     onSuccess: async () => {
       setActionResult("结构化备用模型保存完成。");
-      await Promise.all([
-        queryClient.invalidateQueries({ queryKey: queryKeys.settings.structuredFallback }),
-        queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRouteConnectivity }),
-      ]);
+      await queryClient.invalidateQueries({ queryKey: queryKeys.settings.structuredFallback });
+      checkAfterConfigChange();
     },
   });
 
   const providerConfigs = useMemo(() => apiKeySettingsQuery.data?.data ?? [], [apiKeySettingsQuery.data?.data]);
   const modelRoutes = modelRoutesQuery.data?.data;
-  const modelRouteConnectivity = modelRouteConnectivityQuery.data?.data;
+  const modelRouteConnectivity = connectivityCheck?.result;
   const structuredFallback = structuredFallbackQuery.data?.data;
   const taskTypes = modelRoutes?.taskTypes ?? [];
   const providerOptions = useMemo(() => providerConfigs.map((item) => item.provider), [providerConfigs]);
@@ -265,7 +259,7 @@ export default function ModelRoutesPage() {
             <div className="flex flex-wrap items-center gap-3 text-xs">
               <span className="inline-flex items-center gap-2">
                 <RouteStatusDot
-                  state={modelRouteConnectivityQuery.isPending || modelRouteConnectivityQuery.isFetching
+                  state={isChecking
                     ? "checking"
                     : connectivitySummary.failed > 0
                       ? "failed"
@@ -273,7 +267,7 @@ export default function ModelRoutesPage() {
                         ? "healthy"
                         : "idle"}
                 />
-                {modelRouteConnectivityQuery.isPending || modelRouteConnectivityQuery.isFetching
+                {isChecking
                   ? "正在检测生效路由..."
                   : connectivitySummary.total > 0
                     ? `检测结果：${connectivitySummary.total} 条路由，健康 ${connectivitySummary.healthy}，异常 ${connectivitySummary.failed}`
@@ -287,11 +281,11 @@ export default function ModelRoutesPage() {
           <div className="flex items-center gap-2">
             <Button
               variant="outline"
-              onClick={() => void modelRouteConnectivityQuery.refetch()}
-              disabled={modelRouteConnectivityQuery.isFetching || !modelRoutesQuery.isSuccess}
+              onClick={() => triggerCheck.mutate(true)}
+              disabled={triggerCheck.isPending || !modelRoutesQuery.isSuccess}
             >
-              <RefreshCw className={`h-4 w-4 ${modelRouteConnectivityQuery.isFetching ? "animate-spin" : ""}`} />
-              {modelRouteConnectivityQuery.isFetching ? "检测中..." : "重新检测"}
+              <RefreshCw className={`h-4 w-4 ${isChecking ? "animate-spin" : ""}`} />
+              {isChecking ? "检测中..." : "重新检测"}
             </Button>
             <Button asChild variant="outline">
               <Link to="/settings">
@@ -434,7 +428,7 @@ export default function ModelRoutesPage() {
         const connectivity = connectivityMap.get(taskType);
         const connectivityState = resolveConnectivityState(
           connectivity,
-          modelRouteConnectivityQuery.isPending || modelRouteConnectivityQuery.isFetching,
+          isChecking,
         );
         const isDirty = dirtyTaskTypeSet.has(taskType);
         const hasUnsavedRouteDiff = connectivity != null
diff --git a/client/src/pages/settings/components/SettingsReadinessCard.tsx b/client/src/pages/settings/components/SettingsReadinessCard.tsx
index 28cbf190f1..f5666ed069 100644
--- a/client/src/pages/settings/components/SettingsReadinessCard.tsx
+++ b/client/src/pages/settings/components/SettingsReadinessCard.tsx
@@ -16,7 +16,7 @@ export type SettingsReadinessItem = {
   key: "model" | "routes" | "rag" | "style";
   title: string;
   description: string;
-  state: "ready" | "warning" | "optional" | "checking";
+  state: "ready" | "warning" | "optional" | "checking" | "idle";
 };
 
 function getReadinessIcon(state: SettingsReadinessItem["state"]) {
@@ -26,7 +26,7 @@ function getReadinessIcon(state: SettingsReadinessItem["state"]) {
   if (state === "checking") {
     return <Loader2 className="h-4 w-4 animate-spin text-amber-600" />;
   }
-  if (state === "optional") {
+  if (state === "optional" || state === "idle") {
     return <CircleDashed className="h-4 w-4 text-sky-600" />;
   }
   return <CircleAlert className="h-4 w-4 text-amber-600" />;
@@ -40,6 +40,8 @@ function getReadinessBadge(state: SettingsReadinessItem["state"]) {
       return "检查中";
     case "optional":
       return "可选增强";
+    case "idle":
+      return "未检测";
     case "warning":
       return "需要处理";
   }
@@ -88,12 +90,24 @@ export function buildSettingsReadinessItems(input: {
     {
       key: "routes",
       title: "模型路由",
-      state: isModelRoutesChecking ? "checking" : hasRoutes && failedRouteCount === 0 ? "ready" : "warning",
+      state: isModelRoutesChecking
+        ? "checking"
+        : !hasRoutes
+          ? "warning"
+          : modelRouteConnectivity == null
+            ? "idle"
+            : failedRouteCount === 0
+              ? "ready"
+              : "warning",
       description: isModelRoutesChecking
         ? "正在检查开书、拆章、正文生成和审核任务的模型兼容性。"
-        : hasRoutes && failedRouteCount === 0
-          ? "创作任务已有可用路由，后续流程会按任务选择模型。"
-          : "部分创作任务还需要补齐或修复模型路由。",
+        : !hasRoutes
+          ? "尚未配置任何任务路由，进入模型与厂商页面可补齐。"
+          : modelRouteConnectivity == null
+            ? "尚未检测模型兼容性，进入模型与厂商页面可执行检测。"
+            : failedRouteCount === 0
+              ? "创作任务已有可用路由，后续流程会按任务选择模型。"
+              : "部分创作任务还需要补齐或修复模型路由。",
     },
     {
       key: "rag",
diff --git a/client/src/pages/settings/views/SettingsOverviewPage.tsx b/client/src/pages/settings/views/SettingsOverviewPage.tsx
index 302a0f10d4..31498645fb 100644
--- a/client/src/pages/settings/views/SettingsOverviewPage.tsx
+++ b/client/src/pages/settings/views/SettingsOverviewPage.tsx
@@ -7,8 +7,8 @@ import {
   getModelRoutes,
   getRagSettings,
   getStyleEngineRuntimeSettings,
-  testModelRouteConnectivity,
 } from "@/api/settings";
+import { useModelRouteCheck } from "@/hooks/useModelRouteCheck";
 import { queryKeys } from "@/api/queryKeys";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
@@ -26,23 +26,18 @@ const entries = [
 export default function SettingsOverviewPage() {
   const providersQuery = useQuery({ queryKey: queryKeys.settings.apiKeys, queryFn: getAPIKeySettings });
   const routesQuery = useQuery({ queryKey: queryKeys.settings.modelRoutes, queryFn: getModelRoutes });
-  const connectivityQuery = useQuery({
-    queryKey: queryKeys.settings.modelRouteConnectivity,
-    queryFn: testModelRouteConnectivity,
-    enabled: routesQuery.isSuccess,
-    refetchOnWindowFocus: false,
-  });
+  const { status: connectivityCheck, isChecking } = useModelRouteCheck();
   const ragQuery = useQuery({ queryKey: queryKeys.settings.rag, queryFn: getRagSettings });
   const styleQuery = useQuery({ queryKey: queryKeys.settings.styleEngineRuntime, queryFn: getStyleEngineRuntimeSettings });
   const items = useMemo(() => buildSettingsReadinessItems({
     providers: providersQuery.data?.data ?? [],
     modelRoutes: routesQuery.data?.data,
-    modelRouteConnectivity: connectivityQuery.data?.data,
+    modelRouteConnectivity: connectivityCheck?.result ?? null,
     ragSettings: ragQuery.data?.data,
     styleSettings: styleQuery.data?.data,
-    isModelRoutesChecking: connectivityQuery.isPending || connectivityQuery.isFetching,
+    isModelRoutesChecking: isChecking,
     isStyleSettingsLoaded: styleQuery.isSuccess,
-  }), [connectivityQuery.data?.data, connectivityQuery.isFetching, connectivityQuery.isPending, providersQuery.data?.data, ragQuery.data?.data, routesQuery.data?.data, styleQuery.data?.data, styleQuery.isSuccess]);
+  }), [connectivityCheck?.result, isChecking, providersQuery.data?.data, ragQuery.data?.data, routesQuery.data?.data, styleQuery.data?.data, styleQuery.isSuccess]);
   const configuredProvider = providersQuery.data?.data?.find((item) => item.isConfigured && item.isActive);
   const routeCount = routesQuery.data?.data?.routes.filter((route) => route.provider && route.model).length ?? 0;
   const rag = ragQuery.data?.data;
diff --git a/server/src/llm/checkController.ts b/server/src/llm/checkController.ts
new file mode 100644
index 0000000000..03359c5d29
--- /dev/null
+++ b/server/src/llm/checkController.ts
@@ -0,0 +1,132 @@
+import type { ModelRouteTaskType } from "@ai-novel/shared/types/novel";
+import { MODEL_ROUTE_TASK_TYPES, resolveModel } from "./modelRouter";
+import { runModelRoutesProbe, type ModelRouteProbeInput, type ModelRoutesResult } from "./connectivity";
+
+/**
+ * 模型路由连通性检查统一状态机（single-flight + 指纹缓存）。
+ *
+ * - 全局单例：进程内只有一个检查任务状态，任何页面/请求触发都作用于同一任务
+ * - single-flight：已有任务在跑时，后续触发只返回 running 状态，不重复走探针
+ * - 指纹缓存：配置（路由指纹）未变时返回上次结果，零探针；force 可绕过
+ * - 全失败不更新指纹缓存：下次触发会重新探测
+ */
+export type ModelRoutesCheckStatus = "idle" | "running" | "done";
+
+export interface ModelRoutesCheckState {
+  status: ModelRoutesCheckStatus;
+  taskId: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  /** 本次检查对应的配置指纹；仅成功（非全失败）时更新 */
+  fingerprint: string | null;
+  result: ModelRoutesResult | null;
+}
+
+export interface ModelRoutesCheckResponse extends ModelRoutesCheckState {
+  /** done 且来自指纹缓存时标记 */
+  cached?: boolean;
+}
+
+let state: ModelRoutesCheckState = {
+  status: "idle",
+  taskId: null,
+  startedAt: null,
+  completedAt: null,
+  fingerprint: null,
+  result: null,
+};
+
+let inFlight: Promise<void> | null = null;
+let taskCounter = 0;
+
+function computeFingerprint(routes: readonly ModelRouteProbeInput[]): string {
+  return JSON.stringify(routes.map((route) => [
+    route.taskType,
+    route.provider,
+    route.model,
+    route.requestProtocol,
+    route.structuredResponseFormat,
+  ]));
+}
+
+function toResponse(cached = false): ModelRoutesCheckResponse {
+  return { ...state, cached };
+}
+
+export async function triggerModelRoutesCheck(options: {
+  force?: boolean;
+  taskTypes?: readonly ModelRouteTaskType[];
+} = {}): Promise<ModelRoutesCheckResponse> {
+  const { force = false, taskTypes = MODEL_ROUTE_TASK_TYPES } = options;
+
+  // 1. single-flight：已有任务在跑 → 直接返回进行中状态，不新起任务
+  if (state.status === "running" && inFlight) {
+    return toResponse();
+  }
+
+  // 2. 解析当前生效路由（与探针执行体共享同一份解析结果）并计算配置指纹
+  const resolvedRoutes = await Promise.all(taskTypes.map(async (taskType) => ({
+    taskType,
+    ...(await resolveModel(taskType)),
+  })));
+  const fingerprint = computeFingerprint(resolvedRoutes);
+
+  // 3. 指纹缓存：配置未变且非 force → 返回缓存结果，零探针
+  if (!force && state.status === "done" && state.fingerprint === fingerprint && state.result) {
+    return toResponse(true);
+  }
+
+  // 4. 启动新任务：同步置 running，异步执行探针，请求立即返回
+  const taskId = `model-routes-check-${Date.now()}-${++taskCounter}`;
+  state = {
+    status: "running",
+    taskId,
+    startedAt: new Date().toISOString(),
+    completedAt: null,
+    fingerprint: null,
+    result: null,
+  };
+
+  inFlight = (async () => {
+    try {
+      const result = await runModelRoutesProbe(resolvedRoutes);
+      const allFailed = result.statuses.length > 0 && result.statuses.every((item) => !item.ok);
+      state.status = "done";
+      state.completedAt = new Date().toISOString();
+      state.result = result;
+      // 完全失败时不更新指纹缓存：下次触发重新探测
+      if (!allFailed) {
+        state.fingerprint = fingerprint;
+      }
+    } catch (error) {
+      // 探针执行体异常：状态回退 idle，允许下次重试
+      state.status = "idle";
+      state.taskId = null;
+      state.startedAt = null;
+      state.completedAt = null;
+      state.fingerprint = null;
+      state.result = null;
+      throw error;
+    } finally {
+      inFlight = null;
+    }
+  })();
+
+  return toResponse();
+}
+
+export function getModelRoutesCheckStatus(): ModelRoutesCheckResponse {
+  return toResponse();
+}
+
+export function resetModelRoutesCheckState(): void {
+  state = {
+    status: "idle",
+    taskId: null,
+    startedAt: null,
+    completedAt: null,
+    fingerprint: null,
+    result: null,
+  };
+  inFlight = null;
+}
diff --git a/server/src/llm/connectivity.ts b/server/src/llm/connectivity.ts
index 89e0587fa8..d2a19e5389 100644
--- a/server/src/llm/connectivity.ts
+++ b/server/src/llm/connectivity.ts
@@ -12,6 +12,7 @@ import {
   resolveModel,
   toStructuredOutputStrategy,
   upsertModelRouteConfig,
+  type ResolvedModel,
 } from "./modelRouter";
 import { invokeStructuredLlmDetailed, summarizeStructuredOutputFailure } from "./structuredInvoke";
 import {
@@ -329,17 +330,22 @@ async function testConnection(input: {
   });
 }
 
-async function testModelRoutes(taskTypes: readonly ModelRouteTaskType[] = MODEL_ROUTE_TASK_TYPES): Promise<{
+export interface ModelRoutesResult {
   testedAt: string;
   statuses: ModelRouteConnectivityStatus[];
-}> {
-  const resolvedRoutes = await Promise.all(taskTypes.map(async (taskType) => ({
-    taskType,
-    ...(await resolveModel(taskType)),
-  })));
+}
+
+export interface ModelRouteProbeInput extends ResolvedModel {
+  taskType: ModelRouteTaskType;
+}
 
+/**
+ * 探针执行体：对已解析的生效路由发送普通对话 + 结构化输出两类探针请求。
+ * 逻辑与旧 testModelRoutes 主体一致，仅做编排层解耦，供 checkController 调用。
+ */
+export async function runModelRoutesProbe(routes: readonly ModelRouteProbeInput[]): Promise<ModelRoutesResult> {
   const dedupedChecks = new Map<string, Promise<LLMConnectivityStatus>>();
-  for (const route of resolvedRoutes) {
+  for (const route of routes) {
     const key = [
       route.provider,
       route.model,
@@ -357,7 +363,7 @@ async function testModelRoutes(taskTypes: readonly ModelRouteTaskType[] = MODEL_
     }
   }
 
-  const statuses = await Promise.all(resolvedRoutes.map(async (route) => {
+  const statuses = await Promise.all(routes.map(async (route) => {
     const key = [
       route.provider,
       route.model,
@@ -404,7 +410,20 @@ async function testModelRoutes(taskTypes: readonly ModelRouteTaskType[] = MODEL_
   };
 }
 
+/**
+ * 兼容薄封装：解析生效路由后交给探针执行体。
+ * 新代码应优先通过 checkController.triggerModelRoutesCheck 触发统一检查。
+ */
+export async function testModelRoutes(taskTypes: readonly ModelRouteTaskType[] = MODEL_ROUTE_TASK_TYPES): Promise<ModelRoutesResult> {
+  const resolvedRoutes = await Promise.all(taskTypes.map(async (taskType) => ({
+    taskType,
+    ...(await resolveModel(taskType)),
+  })));
+  return runModelRoutesProbe(resolvedRoutes);
+}
+
 export const llmConnectivityService = {
   testConnection,
   testModelRoutes,
+  runModelRoutesProbe,
 };
diff --git a/server/src/routes/llm.ts b/server/src/routes/llm.ts
index 253e74fc98..912d75bc94 100644
--- a/server/src/routes/llm.ts
+++ b/server/src/routes/llm.ts
@@ -3,6 +3,7 @@ import type { ApiResponse } from "@ai-novel/shared/types/api";
 import { z } from "zod";
 import { prisma } from "../db/prisma";
 import { llmConnectivityService } from "../llm/connectivity";
+import { getModelRoutesCheckStatus, triggerModelRoutesCheck } from "../llm/checkController";
 import { getStructuredFallbackSettings, saveStructuredFallbackSettings } from "../llm/structuredFallbackSettings";
 import { getProviderModels } from "../llm/modelCatalog";
 import { listModelRouteConfigs, MODEL_ROUTE_TASK_TYPES, upsertModelRouteConfig } from "../llm/modelRouter";
@@ -106,13 +107,27 @@ router.get("/model-routes", async (_req, res, next) => {
   }
 });
 
-router.post("/model-routes/connectivity", async (_req, res, next) => {
+router.post("/model-routes/connectivity", async (req, res, next) => {
   try {
-    const data = await llmConnectivityService.testModelRoutes();
+    const force = req.body?.force === true;
+    const data = await triggerModelRoutesCheck({ force });
     res.status(200).json({
       success: true,
       data,
-      message: "模型路由连通性检测完成。",
+      message: data.status === "running" ? "模型路由连通性检测已启动。" : "模型路由连通性检测完成。",
+    } satisfies ApiResponse<typeof data>);
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.get("/model-routes/connectivity/status", async (_req, res, next) => {
+  try {
+    const data = getModelRoutesCheckStatus();
+    res.status(200).json({
+      success: true,
+      data,
+      message: "模型路由连通性检测状态已获取。",
     } satisfies ApiResponse<typeof data>);
   } catch (error) {
     next(error);

From 6603cb96211d4c74b0010d1828cf867648f8a3c8 Mon Sep 17 00:00:00 2001
From: hllshiro <hllshiro@users.noreply.github.com>
Date: Sun, 16 Aug 2026 18:34:13 +0800
Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E6=A0=87=E8=AE=B0=E6=A8=A1?=
 =?UTF-8?q?=E5=9E=8B=E8=B7=AF=E7=94=B1=E8=BF=9E=E9=80=9A=E6=80=A7=E6=A3=80?=
 =?UTF-8?q?=E6=9F=A5=E8=AE=A1=E5=88=92=E4=B8=BA=E5=B7=B2=E5=AE=9E=E6=96=BD?=
 =?UTF-8?q?=EF=BC=884adb50c5=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...e-connectivity-check-unified-state-plan.md | 323 ++++++++++++++++++
 1 file changed, 323 insertions(+)
 create mode 100644 docs/plans/model-route-connectivity-check-unified-state-plan.md

diff --git a/docs/plans/model-route-connectivity-check-unified-state-plan.md b/docs/plans/model-route-connectivity-check-unified-state-plan.md
new file mode 100644
index 0000000000..636122bd06
--- /dev/null
+++ b/docs/plans/model-route-connectivity-check-unified-state-plan.md
@@ -0,0 +1,323 @@
+# 模型路由连通性检查统一状态管理计划
+
+> 状态：已实施（Implemented）
+> 实施提交：`4adb50c5`（分支 `ops/deploy-fixes`，基于 v0.4.13 308ca1b3）
+> 日期：2026-08-16
+> 作者：运维总监（ops_agent）
+> 关联模块：前端设置页 / 后端 LLM 连通性检查服务
+> 验证状态：前端 tsc + vite build 通过；后端 tsc 零新增错误（上游 4 处 pre-existing 错误除外）；
+> Docker 部署与运行验证待执行（依赖部署文件恢复，见 Open Work）
+
+---
+
+## 1. 问题描述
+
+### 1.1 现象
+
+进入系统设置相关页面时，会**反复触发完整的模型路由连通性检查**，每次检查都会向所有已配置的模型服务商（如本地 LM Studio 私有化部署）发送普通对话 + 结构化输出两类探针请求：
+
+- 进入 `/settings`（设置首页）→ 触发一次全量检查
+- 进入 `/settings/models`（模型与厂商）→ 触发一次全量检查
+- 刷新页面后再次进入 → 再次触发
+
+在私有化部署的小型模型场景下，模型被探针请求持续占用，**导致正常创作任务无法使用模型**。
+
+### 1.2 根因分析
+
+| 层 | 根因 | 证据 |
+|----|------|------|
+| 前端 | 两个设置页面各自用 `useQuery` 自动触发检查，`staleTime` 未设置（React Query 默认 0），组件挂载时数据恒为过期 → 每次进入页面自动重新请求 | `SettingsOverviewPage.tsx`、`ModelRoutesPage.tsx` 中 `connectivityQuery` 均无 `staleTime`，`refetchOnMount` 默认开启 |
+| 前端 | 两个页面互不感知，各自持有独立的检查逻辑，无统一入口 | 两个页面分别 `import { testModelRouteConnectivity }` 并各自 `useQuery` |
+| 后端 | `testModelRoutes()` 每次调用都全量解析路由并发送探针，**无任务去重、无结果缓存、无配置变化感知** | `server/src/llm/connectivity.ts:332`，每次调用 `resolveModel` + `testConnection({ probeMode: "both" })` |
+
+### 1.3 影响
+
+- 私有化部署的小模型（响应 25–37s）被高频探针请求持续骚扰，创作任务排队/超时
+- 探针请求与真实创作请求争抢模型资源
+- 多个设置页面进入即触发，浪费算力与 API 配额
+
+---
+
+## 2. 目标与设计原则
+
+### 2.1 目标
+
+1. **任务唯一**：无论从哪里触发检查，只要已有检查任务在运行，后续触发只返回当前任务状态，不重复走探针流程（single-flight）
+2. **配置感知**：只要模型路由配置没有变化，就返回上次检查的结果，不发探针
+3. **手动可控**：允许用户主动触发检查并刷新检查状态
+
+### 2.2 设计原则
+
+- **状态收口**：检查任务状态由后端统一持有（全局单例），前端只消费状态
+- **前端统一**：所有页面通过同一个 Hook 与后端交互，消除重复逻辑
+- **异步非阻塞**：检查任务异步执行，触发请求立即返回任务状态，前端轮询完成
+- **改动最小**：探针执行体（`runModelRoutesProbe`）逻辑不变，仅做编排层改造
+
+---
+
+## 3. 架构设计
+
+### 3.1 统一任务状态机
+
+```
+┌──────────┐   POST /check (指纹变化 或 force)   ┌───────────┐
+│   idle   │ ──────────────────────────────────▶ │  running  │
+└──────────┘                                     └─────┬─────┘
+     ▲                                                │ 完成
+     │                                                ▼
+     │          ┌────────┐                     ┌──────────────┐
+     └──────────│  done  │◀────────────────────│ 探针执行体     │
+                └────────┘                     │(single-flight)│
+                 (结果+指纹+时间)               └──────────────┘
+```
+
+状态说明：
+
+| 状态 | 含义 |
+|------|------|
+| `idle` | 无检查任务（进程启动后初始态） |
+| `running` | 有检查任务正在执行（全局仅允许一个） |
+| `done` | 检查完成，持有结果 + 配置指纹 + 时间戳 |
+
+### 3.2 触发决策流程
+
+```
+POST /api/llm/model-routes/connectivity  { force?: boolean }
+
+1. status === "running"
+   → 返回 { status: "running", taskId, startedAt }        // single-flight，不新起任务
+
+2. 解析当前生效路由 → 计算配置指纹 fingerprint_now
+   指纹 = 全量路由 [taskType, provider, model, requestProtocol, structuredResponseFormat] 序列化
+
+3. !force && status === "done" && fingerprint === fingerprint_now
+   → 返回 { status: "done", result: 缓存结果, cached: true }   // 配置未变 → 零探针
+
+4. 否则 → 启动新任务（异步执行，请求立即返回 running）
+   state.status = "running"
+   state.inFlight = runModelRoutesProbe(routes)
+     .then(完成 → status="done", 存 result + fingerprint)
+```
+
+---
+
+## 4. 详细设计
+
+### 4.1 后端
+
+#### 4.1.1 新建 `server/src/llm/checkController.ts`
+
+全局单例状态：
+
+```ts
+interface ModelRoutesCheckState {
+  status: "idle" | "running" | "done";
+  taskId: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  fingerprint: string | null;       // 本次检查对应的配置指纹
+  result: ModelRoutesResult | null;
+  inFlight: Promise<ModelRoutesResult> | null;
+}
+```
+
+导出函数：
+
+| 函数 | 职责 |
+|------|------|
+| `triggerModelRoutesCheck({ force? })` | 统一触发入口，执行 3.2 决策流程 |
+| `getModelRoutesCheckStatus()` | 返回当前任务状态（供前端轮询） |
+| `resetModelRoutesCheckState()` | 重置状态（测试/维护用） |
+
+要点：
+
+- **single-flight 原子性**：第一个请求同步将 `status` 置为 `running` 后再进入异步探针，后续请求进入时已能看到 `running`（JS 单线程天然保证）
+- **并发去重**：`inFlight` 保存进行中的 Promise，同一时刻仅一个探针执行体
+- **指纹缓存**：`done` 状态持有指纹，配置未变且非 force 时直接返回缓存
+- **失败处理**：检查全部失败时结果保留在 `statuses`（每条带 `error`），UI 显示异常；**全失败时不更新指纹缓存**，下次触发重查
+
+#### 4.1.2 改造 `server/src/llm/connectivity.ts`
+
+将现有 `testModelRoutes` 主体抽取为 `runModelRoutesProbe(routes)` 并导出，包含：
+
+- 同路由去重（现有 `dedupedChecks`）
+- `probeMode: "both"` 探针
+- `shouldPersistProbeResult` → `upsertModelRouteConfig` 逻辑（探针发现有效协议/格式差异时持久化）
+
+`testModelRoutes` 原导出保留为薄封装（调用 `triggerModelRoutesCheck`），保持兼容。
+
+#### 4.1.3 改造 `server/src/routes/llm.ts`
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/llm/model-routes/connectivity` | POST | 改造：body `{ force?: boolean }`，返回任务状态（`running`/`done`） |
+| `/api/llm/model-routes/connectivity/status` | GET | 新增：返回当前任务状态，供前端轮询 |
+
+响应结构统一：
+
+```ts
+interface ModelRoutesCheckResponse {
+  status: "idle" | "running" | "done";
+  taskId: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  result: ModelRoutesResult | null;   // 仅 done 时非空
+  cached?: boolean;                    // done 且来自缓存时标记
+}
+```
+
+### 4.2 前端
+
+#### 4.2.1 改造 `client/src/api/settings.ts`
+
+```ts
+export async function testModelRouteConnectivity(force = false) {
+  const { data } = await apiClient.post<ApiResponse<ModelRouteConnectivityCheckResponse>>(
+    "/llm/model-routes/connectivity", { force },
+  );
+  return data;
+}
+
+export async function getModelRouteConnectivityStatus() {
+  const { data } = await apiClient.get<ApiResponse<ModelRouteConnectivityCheckResponse>>(
+    "/llm/model-routes/connectivity/status",
+  );
+  return data;
+}
+```
+
+#### 4.2.2 新建 `client/src/hooks/useModelRouteCheck.ts`
+
+统一 Hook，所有页面共用：
+
+```ts
+export function useModelRouteCheck() {
+  const queryClient = useQueryClient();
+  const checkKey = queryKeys.settings.modelRouteConnectivity;
+
+  // 状态查询：running 时自动轮询 2s，done/idle 停止
+  const statusQuery = useQuery({
+    queryKey: checkKey,
+    queryFn: getModelRouteConnectivityStatus,
+    refetchInterval: (q) => q.state.data?.data?.status === "running" ? 2000 : false,
+    refetchOnWindowFocus: false,
+  });
+
+  // 触发检查（后端保证 single-flight + 指纹缓存）
+  const triggerCheck = useMutation({
+    mutationFn: (force = false) => testModelRouteConnectivity(force),
+    onSuccess: (resp) => {
+      queryClient.setQueryData(checkKey, resp);          // 统一状态写入，跨页面共享
+      if (resp.data.status === "running") statusQuery.refetch();  // 开始轮询
+    },
+  });
+
+  return {
+    status: statusQuery.data?.data,
+    isChecking: statusQuery.data?.data?.status === "running",
+    triggerCheck,                       // 手动刷新：triggerCheck(true)
+    checkAfterConfigChange: () => {     // 保存路由后：invalidate + 触发
+      void queryClient.invalidateQueries({ queryKey: queryKeys.settings.modelRoutes });
+      triggerCheck.mutate(false);
+    },
+  };
+}
+```
+
+#### 4.2.3 改造 `client/src/pages/settings/ModelRoutesPage.tsx`
+
+- 删除自有 `modelRouteConnectivityQuery`，改用 `useModelRouteCheck()`
+- 手动"重新检测"按钮 → `triggerCheck(true)`（force 刷新）
+- 三个保存 mutation（保存路由 / 套用模型 / 保存备用模型）onSuccess → `checkAfterConfigChange()`
+- UI 状态判断改用 `isChecking` / `status.result`
+
+#### 4.2.4 改造 `client/src/pages/settings/views/SettingsOverviewPage.tsx`
+
+- 删除自有 `connectivityQuery`，改用 `useModelRouteCheck()`
+- ReadinessCard 传入统一状态：
+  - `running` → checking（"检查中"）
+  - `done` → 按结果（ready / warning）
+  - `idle` → 未检测
+
+#### 4.2.5 （可选）改造 `SettingsReadinessCard.tsx`
+
+- `SettingsReadinessItem` state 增加 `"idle"`（未检测）
+- 现状：从未检测过时 `failedRouteCount === 0` 导致"模型路由"误显示"可用"
+- 增加 idle 分支，badge 显示"未检测"，主按钮仍导向 `/settings/models`
+
+---
+
+## 5. 需求映射
+
+| 用户要求 | 实现 |
+|---------|------|
+| 1. 已开启检查则后续触发只返回任务状态 | 后端 `running` 分支 + `inFlight` single-flight，不重复走流程 |
+| 2. 配置未变返回上次结果 | 后端指纹缓存（`!force && fingerprint 相同 → 返回缓存`） |
+| 3. 允许手动刷新检查状态 | 前端 `triggerCheck(true)` → `force` 绕过后端指纹缓存（仍受 single-flight 约束） |
+
+---
+
+## 6. 改动清单
+
+| 文件 | 改动类型 | 说明 |
+|------|---------|------|
+| `server/src/llm/checkController.ts` | 新增 | 统一状态机、single-flight、指纹缓存 |
+| `server/src/llm/connectivity.ts` | 修改 | 抽取导出 `runModelRoutesProbe`，`testModelRoutes` 改为薄封装 |
+| `server/src/routes/llm.ts` | 修改 | POST 改造 + 新增 GET status |
+| `client/src/api/settings.ts` | 修改 | `testModelRouteConnectivity(force)` + 新增 `getModelRouteConnectivityStatus` |
+| `client/src/hooks/useModelRouteCheck.ts` | 新增 | 统一 Hook |
+| `client/src/pages/settings/ModelRoutesPage.tsx` | 修改 | 接入 Hook，保存后自动检查 |
+| `client/src/pages/settings/views/SettingsOverviewPage.tsx` | 修改 | 接入 Hook |
+| `client/src/pages/settings/components/SettingsReadinessCard.tsx` | 修改（可选） | 增加"未检测"状态 |
+
+---
+
+## 7. 实施步骤
+
+1. **后端状态机**：新建 `checkController.ts`，实现状态管理 + 指纹缓存 + single-flight
+2. **后端探针抽取**：`connectivity.ts` 抽取 `runModelRoutesProbe`
+3. **后端路由**：`routes/llm.ts` 改造 POST + 新增 GET status
+4. **后端自测**：单元测试覆盖状态机分支（running 去重 / 指纹缓存 / force）
+5. **前端 API**：`settings.ts` 新增/改造 API 函数
+6. **前端 Hook**：新建 `useModelRouteCheck.ts`
+7. **页面接入**：`ModelRoutesPage.tsx`、`SettingsOverviewPage.tsx`
+8. **ReadinessCard 优化**（可选）：idle 状态
+9. **构建与部署**：前端 build + Docker 容器组重启
+10. **验证**：见第 8 节
+
+---
+
+## 8. 验证方案
+
+| 场景 | 预期 |
+|------|------|
+| 进入 `/settings` 首页 | LM Studio 日志**无探针消息**，页面显示上次结果或"未检测" |
+| 进入 `/settings/models` | LM Studio 日志**无探针消息** |
+| 刷新页面后再进入 | 无探针消息（需手动触发才检查） |
+| 点"重新检测"按钮 | 恰好**一次**探针请求 |
+| 检查进行中再次点"重新检测" | 返回 `running`，**不发起新探针** |
+| 保存任意路由配置 | 自动触发**一次**新检查（指纹变化） |
+| 配置未变、检查完成后再次触发 | 返回缓存结果（`cached: true`），零探针 |
+| 多个浏览器标签页同时触发 | 后端仅一个探针任务，其余返回 `running` |
+| 手动 force 刷新 | 绕过缓存，重新探针（进行中仍受 single-flight 约束） |
+
+---
+
+## 9. 边界情况与风险
+
+| 场景 | 处理 | 风险等级 |
+|------|------|---------|
+| 并发触发（多请求同时进入） | 首个请求同步置 running，后续返回进行中 | 低 |
+| 检查全部失败 | 结果保留 error 信息，不更新指纹缓存，下次重查 | 低 |
+| force 手动刷新期间有任务在跑 | 返回 running，不并发探针 | 低 |
+| 进程重启 | 状态归零 → idle，首次触发正常启动 | 低 |
+| 外部模型变更（LM Studio 换模型） | 手动 force 刷新获取新鲜结果 | 低 |
+| 缓存结果与真实状态偏差（TTL 缺失） | 指纹缓存无 TTL，靠 force 手动刷新；如需自动过期可后续加 TTL（如 5min） | 中（接受） |
+
+---
+
+## 10. 回滚方案
+
+- 后端：`checkController.ts` 删除、`connectivity.ts` / `routes/llm.ts` 恢复为当前版本（git checkout）
+- 前端：`useModelRouteCheck.ts` 删除，两个页面恢复原 `useQuery` 逻辑
+- 整体：`git stash` / 保留改动前的分支标签