dsh-mcp-connector 0.2.21 → 0.2.23

package/lib/index.js

@@ -15,7 +15,10 @@ import {
   DEFAULT_CATALOG_URL,
   DEFAULT_CATALOG_FALLBACK_URLS,
   DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_STARTUP_TIMEOUT_MS,
   DEFAULT_REFRESH_SKEW_MS,
+  DEFAULT_REFRESH_RETRY_BASE_MS,
+  DEFAULT_REFRESH_RETRY_MAX_MS,
   DEFAULT_CATALOG_TTL_MS,
 } from './constants.js';
 import { defineConnectorDomain, ConnectionStore, GrantStore, CatalogStore } from './stores.js';
@@ -24,7 +27,7 @@ import { loadBundledCatalog, fetchRemoteCatalogWithFallback, mergeCatalog, listC
 import { oauthAuthorize } from './connectors/oauth-connector.js';
 import { buildManualRecord } from './connectors/manual-connector.js';
 import { normalizeJsonImport } from './connectors/json-connector.js';
-import { discoverServerMetadata, refreshAccessToken, revokeRefreshToken } from './oauth.js';
+import { discoverServerMetadata, refreshAccessToken, revokeRefreshToken, extractTokenResources } from './oauth.js';
 import { provision, disable, remove, entryIdFor } from './mcp-provision.js';
 import { classifyConnectionError, validateConnectionRecords } from './mcp-validation.js';
 import { listMcpTools, McpHttpError } from './mcp-http.js';
@@ -32,9 +35,21 @@ import { registerTools } from './tools.js';
 import { mountWebRoutes } from './web.js';
 import { assertSafeUrl } from './util.js';
 import { readLegacyGrantCandidates, planLegacyMigration, toConnectorGrant, toConnectionRecords } from './migration.js';
+import { classifyRefreshFailure, refreshRetryDelay } from './grant-lifecycle.js';
 
 export const name = 'mcp-connector';
 
+const LEGACY_OAUTH_PLUGINS = [
+  {
+    id: 'qcc-mcp-oauth',
+    servers: ['qcc-company', 'qcc-risk', 'qcc-ipr', 'qcc-operation', 'qcc-history', 'qcc-executive'],
+  },
+  {
+    id: 'qcc-legal-mcp-oauth',
+    servers: ['qcc-regulation', 'qcc-case'],
+  },
+];
+
 export const inject = ['tools', 'storageDomain', 'loader'];
 
 export const Config = z.object({
@@ -52,8 +67,14 @@ export const Config = z.object({
   callbackTimeoutMs: z.number().default(300_000),
   /** 网络请求超时（ms） */
   requestTimeoutMs: z.number().default(DEFAULT_REQUEST_TIMEOUT_MS),
+  /** 首次启动并完成 MCP initialize + tools/list 的超时（ms） */
+  startupTimeoutMs: z.number().default(DEFAULT_STARTUP_TIMEOUT_MS),
   /** 提前刷新阈值（ms） */
   refreshSkewMs: z.number().default(DEFAULT_REFRESH_SKEW_MS),
+  /** 刷新暂时失败后的首次重试间隔（ms） */
+  refreshRetryBaseMs: z.number().default(DEFAULT_REFRESH_RETRY_BASE_MS),
+  /** 刷新暂时失败后的最大重试间隔（ms） */
+  refreshRetryMaxMs: z.number().default(DEFAULT_REFRESH_RETRY_MAX_MS),
   /** 是否自动打开浏览器（false = 仅打印授权 URL） */
   openBrowser: z.boolean().default(true),
   /** 授权账号标识（预留多账号） */
@@ -78,9 +99,10 @@ export async function apply(ctx, config) {
     dynamic: new Map(),         // URL 安装的临时连接器
     overrides: new Map(),       // id -> { published?, featured? }
     connections: new Map(),     // key -> ConnectionRecord
-    grants: new Map(),          // grantKey -> { grant, timer, refreshPromise, needsReauth }
+    grants: new Map(),          // grantKey -> { grant, timer, refreshPromise, needsReauth, refreshFailure* }
     health: new Map(),          // connectorId -> 最近一次主动连通性检查摘要（不持久化）
-    oauthConnects: new Map(),   // connectorId -> 正在进行的 OAuth 授权 Promise（防重复弹窗/重复 grant）
+    oauthConnects: new Map(),   // sharingKey -> { promise, requestedConnectorIds }（防同 issuer 重复弹窗）
+    warnedLegacyConflicts: new Set(),
   };
 
   /* ───────────────────────── 目录加载 ───────────────────────── */
@@ -151,8 +173,91 @@ export async function apply(ctx, config) {
     await recomputeMerged();
   }
 
+  /* ───────────────────────── 旧 OAuth 插件冲突 ───────────────────────── */
+
+  function loaderEntryActive(id) {
+    try {
+      const entry = ctx.loader.resolve(id);
+      return !!entry && entry.disabled !== true && entry.options?.disabled !== true;
+    } catch {
+      return false;
+    }
+  }
+
+  function activeLegacyPlugin(definition) {
+    if (loaderEntryActive(definition.id)) return definition.id;
+    // 兼容旧插件本体已经移除、但其动态 mcp-client 条目仍残留的配置树。
+    return definition.servers.some((serverName) => loaderEntryActive(`mcp-${serverName}`))
+      ? definition.id
+      : null;
+  }
+
+  function legacyConflictForServer(serverName) {
+    for (const definition of LEGACY_OAUTH_PLUGINS) {
+      if (definition.servers.includes(serverName) && activeLegacyPlugin(definition)) return definition.id;
+    }
+    return null;
+  }
+
+  function legacyConflictForRecord(record) {
+    const pluginId = legacyConflictForServer(record?.serverName);
+    if (!pluginId) return null;
+    return {
+      pluginId,
+      serverName: record.serverName,
+      message: `检测到旧插件 ${pluginId} 仍在管理同名服务 ${record.serverName}；请停用旧插件并重启 DSH`,
+    };
+  }
+
+  function legacyConflictForConnector(connector) {
+    for (const server of connector?.servers ?? []) {
+      const pluginId = legacyConflictForServer(server.serverName);
+      if (pluginId) {
+        return {
+          pluginId,
+          serverName: server.serverName,
+          message: `检测到旧插件 ${pluginId} 仍在管理同名服务 ${server.serverName}；为避免凭据覆盖，请停用旧插件并重启 DSH 后再连接`,
+        };
+      }
+    }
+    return null;
+  }
+
+  function warnLegacyConflict(conflict) {
+    if (!conflict || state.warnedLegacyConflicts.has(conflict.pluginId)) return;
+    state.warnedLegacyConflicts.add(conflict.pluginId);
+    logger.warn(`legacy OAuth plugin conflict: ${conflict.message}`);
+  }
+
+  function detectLegacyPluginConflicts() {
+    const conflicts = [];
+    for (const definition of LEGACY_OAUTH_PLUGINS) {
+      if (!activeLegacyPlugin(definition)) continue;
+      const conflict = {
+        pluginId: definition.id,
+        message: `检测到旧插件 ${definition.id} 仍处于启用状态；它会与 MCP连接器重复管理企查查 Server`,
+      };
+      conflicts.push(conflict);
+      warnLegacyConflict(conflict);
+    }
+    return conflicts;
+  }
+
   /* ───────────────────────── grant 刷新 ───────────────────────── */
 
+  function grantRuntime(grant) {
+    return {
+      grant,
+      timer: undefined,
+      refreshPromise: null,
+      needsReauth: false,
+      refreshFailureKind: null,
+      refreshFailureCount: 0,
+      lastRefreshError: null,
+      refreshRetryAt: null,
+    };
+  }
+
   function grantMap() {
     const map = new Map();
     for (const [key, g] of state.grants) map.set(key, g.grant);
@@ -161,10 +266,16 @@ export async function apply(ctx, config) {
 
   async function refreshGrant(grantKey) {
     const entry = state.grants.get(grantKey);
-    if (!entry || !entry.grant.refreshToken) throw new Error('no refresh token available');
+    if (!entry || !entry.grant.refreshToken) {
+      const error = new Error('no refresh token available');
+      error.code = 'missing_refresh_token';
+      throw error;
+    }
     if (entry.grant.clientSecret && entry.grant.clientSecretExpiresAt > 0
         && entry.grant.clientSecretExpiresAt * 1000 <= Date.now()) {
-      throw new Error('OAuth dynamic client secret expired');
+      const error = new Error('OAuth dynamic client secret expired');
+      error.code = 'client_secret_expired';
+      throw error;
     }
     if (entry.refreshPromise) return entry.refreshPromise;
     entry.refreshPromise = (async () => {
@@ -174,22 +285,39 @@ export async function apply(ctx, config) {
         clientSecret: entry.grant.clientSecret,
         tokenEndpointAuthMethod: entry.grant.tokenEndpointAuthMethod ?? 'none',
         refreshToken: entry.grant.refreshToken,
-        resource: entry.grant.authorizedResources[0],
+        // 多资源共享 Grant 不应在刷新时被第一个 resource 意外收窄。
+        resource: entry.grant.authorizedResources.length === 1 ? entry.grant.authorizedResources[0] : undefined,
         scope: entry.grant.scope,
         timeoutMs: config.requestTimeoutMs,
       });
+      const refreshedResources = extractTokenResources(token.accessToken);
       const next = {
         ...entry.grant,
         accessToken: token.accessToken,
-        accessTokenExpiresAt: Date.now() + token.expiresIn * 1000 - config.refreshSkewMs,
+        // 持久化真实过期时间；提前刷新只用于定时调度，不能冒充 Token 已过期。
+        accessTokenExpiresAt: Date.now() + token.expiresIn * 1000,
         refreshToken: token.refreshToken ?? entry.grant.refreshToken,
+        authorizedResources: refreshedResources?.length ? refreshedResources : entry.grant.authorizedResources,
+        updatedAt: Date.now(),
       };
       entry.grant = next;
       entry.needsReauth = false;
+      entry.refreshFailureKind = null;
+      entry.refreshFailureCount = 0;
+      entry.lastRefreshError = null;
+      entry.refreshRetryAt = null;
       state.grants.set(grantKey, entry);
       if (config.persistSecrets) await grantStore.put(next);
       for (const [key, record] of state.connections) {
-        if (record.auth?.grantKey === grantKey) await provision(ctx, config, record, grantMap());
+        if (record.auth?.grantKey !== grantKey || record.enabled === false) continue;
+        const conflict = legacyConflictForRecord(record);
+        if (conflict) {
+          warnLegacyConflict(conflict);
+          continue;
+        }
+        await provision(ctx, config, record, grantMap()).catch((error) => {
+          logger.warn(`re-provision "${key}" after OAuth refresh failed: ${error.message}`);
+        });
       }
       scheduleRefresh(grantKey);
       return next;
@@ -201,20 +329,61 @@ export async function apply(ctx, config) {
     }
   }
 
-  function scheduleRefresh(grantKey) {
+  function scheduleRefresh(grantKey, { delayMs } = {}) {
     const entry = state.grants.get(grantKey);
     if (!entry) return;
     if (entry.timer) clearTimeout(entry.timer);
-    const delay = Math.max(0, entry.grant.accessTokenExpiresAt - Date.now());
+    const tokenLifetime = Math.max(0, entry.grant.accessTokenExpiresAt - (entry.grant.updatedAt || Date.now()));
+    const effectiveSkew = Math.min(
+      Math.max(0, config.refreshSkewMs),
+      Math.max(1_000, Math.floor(tokenLifetime * 0.1)),
+    );
+    const delay = delayMs === undefined
+      ? Math.max(0, entry.grant.accessTokenExpiresAt - effectiveSkew - Date.now())
+      : Math.max(0, delayMs);
     entry.timer = setTimeout(() => {
-      refreshGrant(grantKey).catch((error) => {
-        entry.needsReauth = true;
-        logger.warn(`grant ${grantKey} refresh failed: ${error.message}`);
-      });
+      entry.timer = undefined;
+      refreshGrantWithRecovery(grantKey, 'scheduled').catch(() => {});
     }, delay);
     entry.timer.unref?.();
   }
 
+  function recordRefreshFailure(grantKey, error, phase) {
+    const entry = state.grants.get(grantKey);
+    if (!entry) return classifyRefreshFailure(error);
+    const failure = classifyRefreshFailure(error);
+    entry.refreshFailureCount = (entry.refreshFailureCount ?? 0) + 1;
+    entry.refreshFailureKind = failure.kind;
+    entry.lastRefreshError = failure.message;
+    entry.needsReauth = failure.permanent;
+    entry.refreshRetryAt = null;
+
+    const status = failure.httpStatus ? ` http=${failure.httpStatus}` : '';
+    const action = failure.permanent ? 'reauthorization required' : 'automatic retry scheduled';
+    logger.warn(`OAuth grant refresh failed phase=${phase} grant=${grantKey} code=${failure.code}${status} classification=${failure.kind}: ${failure.message}; ${action}`);
+
+    if (!failure.permanent) {
+      const delay = refreshRetryDelay(
+        entry.refreshFailureCount,
+        config.refreshRetryBaseMs,
+        config.refreshRetryMaxMs,
+      );
+      entry.refreshRetryAt = Date.now() + delay;
+      scheduleRefresh(grantKey, { delayMs: delay });
+    }
+    return failure;
+  }
+
+  async function refreshGrantWithRecovery(grantKey, phase) {
+    try {
+      return await refreshGrant(grantKey);
+    } catch (error) {
+      // 多个调用方可能等待同一个 refreshPromise；同一次失败只能记一次并调度一个重试。
+      if (!error.refreshFailure) error.refreshFailure = recordRefreshFailure(grantKey, error, phase);
+      throw error;
+    }
+  }
+
   async function retireGrantIfUnused(grantKey, { revoke = false } = {}) {
     if ([...state.connections.values()].some((record) => record.auth?.grantKey === grantKey)) return false;
     const entry = state.grants.get(grantKey);
@@ -251,48 +420,225 @@ export async function apply(ctx, config) {
 
   /* ───────────────────────── 连接记录落库 / 挂载 ───────────────────────── */
 
+  function clearRecordHealth(record) {
+    if (record?.connectorId) state.health.delete(record.connectorId);
+  }
+
   async function persistRecord(record) {
-    state.connections.set(record.key, record);
-    if (record.connectorId) state.health.delete(record.connectorId);
+    // 存储成功后才更新内存，避免落盘失败却在当前进程显示为“已安装”。
     if (config.persistSecrets) await connectionStore.put(record);
+    state.connections.set(record.key, record);
+    clearRecordHealth(record);
   }
 
-  async function upsertRecord(record) {
-    const existing = state.connections.get(record.key);
-    const merged = existing ? { ...existing, ...record, updatedAt: Date.now() } : record;
-    await persistRecord(merged);
-    await provision(ctx, config, merged, grantMap());
-    return merged;
+  async function restorePersistedRecord(key, original) {
+    const current = state.connections.get(key);
+    if (config.persistSecrets) {
+      if (original) await connectionStore.put(original);
+      else await connectionStore.delete(key);
+    }
+    if (original) state.connections.set(key, original);
+    else state.connections.delete(key);
+    clearRecordHealth(current);
+    clearRecordHealth(original);
+  }
+
+  async function restoreProvisionedEntry(record, original) {
+    if (original) await provision(ctx, config, original, grantMap(), { failOnStartupError: false });
+    else await remove(ctx, config, record);
+  }
+
+  async function provisionUntilReady(record, original, { strictStartup = true } = {}) {
+    if (!strictStartup) {
+      return provision(ctx, config, record, grantMap(), { failOnStartupError: false });
+    }
+    const startupTimeoutMs = Math.max(1_000, Number(config.startupTimeoutMs) || DEFAULT_STARTUP_TIMEOUT_MS);
+    const timeoutError = Object.assign(
+      new Error(`MCP Server 启动与工具同步超过 ${Math.ceil(startupTimeoutMs / 1000)} 秒`),
+      { code: 'ETIMEDOUT' },
+    );
+    let timer;
+    const task = provision(ctx, config, record, grantMap(), { failOnStartupError: true });
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(timeoutError), startupTimeoutMs);
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([task, deadline]);
+    } catch (error) {
+      if (error === timeoutError) {
+        // loader 可能仍在等待 SDK 请求；它最终成功时必须恢复旧条目/移除新条目，绝不迟到落库。
+        task.then(
+          () => restoreProvisionedEntry(record, original).catch((rollbackError) => {
+            logger.error(`late startup rollback "${record.key}" failed: ${rollbackError.message}`);
+          }),
+          () => {},
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function rollbackProvisionedRecords(records, originals) {
+    const failures = [];
+    for (const record of [...records].reverse()) {
+      try {
+        await restoreProvisionedEntry(record, originals.get(record.key));
+      } catch (error) {
+        failures.push(error);
+        logger.error(`connection rollback "${record.key}" failed: ${error.message}`);
+      }
+    }
+    return failures;
+  }
+
+  async function commitConnectionRecords(records, { strictStartup = true } = {}) {
+    const originals = new Map(records.map((record) => [record.key, state.connections.get(record.key)]));
+    const staged = records.map((record) => {
+      const existing = originals.get(record.key);
+      return existing ? { ...existing, ...record, updatedAt: Date.now() } : record;
+    });
+    const provisioned = [];
+    let activeRecord;
+    try {
+      for (const record of staged) {
+        activeRecord = record;
+        await provisionUntilReady(record, originals.get(record.key), { strictStartup });
+        provisioned.push(record);
+      }
+    } catch (error) {
+      await rollbackProvisionedRecords(provisioned, originals);
+      const wrapped = new Error(`MCP Server "${activeRecord?.serverName ?? activeRecord?.key ?? 'unknown'}" 未完成启动`, { cause: error });
+      wrapped.connectionRecord = activeRecord;
+      throw wrapped;
+    }
+
+    try {
+      for (const record of staged) await persistRecord(record);
+    } catch (error) {
+      const rollbackErrors = await rollbackProvisionedRecords(provisioned, originals);
+      for (const record of staged) {
+        try {
+          await restorePersistedRecord(record.key, originals.get(record.key));
+        } catch (rollbackError) {
+          rollbackErrors.push(rollbackError);
+          logger.error(`connection storage rollback "${record.key}" failed: ${rollbackError.message}`);
+        }
+      }
+      const wrapped = new Error('连接记录持久化失败，已回滚 Host 条目', { cause: error });
+      wrapped.connectionRecord = activeRecord;
+      wrapped.rollbackErrors = rollbackErrors;
+      throw wrapped;
+    }
+    return staged;
+  }
+
+  async function upsertRecord(record, options) {
+    return (await commitConnectionRecords([record], options))[0];
   }
 
   function grantFailure(record) {
     if (record.auth?.mode !== 'oauth') return null;
+    const conflict = legacyConflictForRecord(record);
+    if (conflict) {
+      warnLegacyConflict(conflict);
+      return { ok: false, kind: 'conflict', serverKey: record.serverKey, serverName: record.serverName, message: conflict.message };
+    }
     const grantKey = record.auth.grantKey;
     const entry = grantKey ? state.grants.get(grantKey) : null;
     if (!entry) return { ok: false, kind: 'auth', serverKey: record.serverKey, serverName: record.serverName, message: 'OAuth 授权缺失，请重新授权' };
     const clientSecretExpired = entry.grant.clientSecret && entry.grant.clientSecretExpiresAt > 0
       && entry.grant.clientSecretExpiresAt * 1000 <= Date.now();
-    if (entry.needsReauth || clientSecretExpired || entry.grant.accessTokenExpiresAt <= Date.now()) {
+    if (entry.needsReauth || clientSecretExpired) {
       return { ok: false, kind: 'auth', serverKey: record.serverKey, serverName: record.serverName, message: 'OAuth 授权已过期或刷新失败，请重新授权' };
     }
+    if (entry.grant.accessTokenExpiresAt <= Date.now()) {
+      return {
+        ok: false,
+        kind: 'refresh',
+        serverKey: record.serverKey,
+        serverName: record.serverName,
+        message: entry.refreshPromise
+          ? 'OAuth Access Token 已到期，正在自动刷新'
+          : `OAuth 刷新暂时失败，正在自动重试${entry.lastRefreshError ? `：${entry.lastRefreshError}` : ''}`,
+      };
+    }
     return null;
   }
 
+  function registeredStdioTools(record) {
+    if (typeof ctx.tools?.schemas !== 'function') {
+      return { supported: false, tools: [] };
+    }
+    const prefix = `mcp__${record.serverName}__`;
+    try {
+      const tools = ctx.tools.schemas()
+        .filter((schema) => typeof schema?.name === 'string' && schema.name.startsWith(prefix))
+        .map((schema) => ({
+          name: schema.name.slice(prefix.length),
+          publicName: schema.name,
+          title: schema.title || schema.name.slice(prefix.length),
+          description: schema.description || '',
+        }));
+      return { supported: true, tools };
+    } catch (error) {
+      logger.warn(`read registered tools for "${record.serverName}" failed: ${error.message}`);
+      return { supported: true, tools: [], error };
+    }
+  }
+
+  function readinessResults(records, validationResults = []) {
+    return records.map((record, index) => {
+      const validated = validationResults[index];
+      return {
+        ...(validated ?? {}),
+        ok: true,
+        kind: 'connected',
+        serverKey: record.serverKey,
+        serverName: record.serverName,
+        message: record.transport === 'stdio'
+          ? 'Host 已完成 stdio MCP 初始化与首次工具同步'
+          : validated?.message,
+      };
+    });
+  }
+
+  function connectionSetupFailure(error, prefix = '连接失败') {
+    const record = error?.connectionRecord;
+    const classified = classifyConnectionError(error, { transport: record?.transport });
+    return {
+      ok: false,
+      message: `${prefix}：${classified.message}。未保存连接，请修正后重试。`,
+      detail: {
+        kind: classified.kind,
+        serverKey: record?.serverKey,
+        serverName: record?.serverName,
+        ...(classified.exitCode !== undefined ? { exitCode: classified.exitCode } : {}),
+      },
+    };
+  }
+
   function healthSummary(connectorId, records, results, checkedAt = Date.now()) {
     const enabledRecords = records.filter((record) => record.enabled !== false);
-    const availableServers = results.filter((result) => result.ok).length;
-    const failedServers = results.length - availableServers;
+    const availableServers = results.filter((result) => result.ok && result.kind !== 'managed').length;
+    const pendingServers = results.filter((result) => result.ok && result.kind === 'managed').length;
+    const failedServers = results.filter((result) => !result.ok).length;
     const authFailures = results.filter((result) => !result.ok && result.kind === 'auth').length;
+    const refreshFailures = results.filter((result) => !result.ok && result.kind === 'refresh').length;
     let connectionState = 'configured';
     if (records.length === 0) connectionState = 'disconnected';
     else if (enabledRecords.length === 0) connectionState = 'disabled';
-    else if (failedServers === 0 && availableServers > 0) connectionState = 'healthy';
-    else if (availableServers > 0) connectionState = 'degraded';
+    else if (failedServers === 0 && pendingServers === 0 && availableServers > 0) connectionState = 'healthy';
+    else if (availableServers > 0 && (failedServers > 0 || pendingServers > 0)) connectionState = 'degraded';
+    else if (pendingServers > 0 && failedServers === 0) connectionState = 'configured';
     else if (authFailures > 0) connectionState = 'reauth';
+    else if (refreshFailures > 0) connectionState = 'recovering';
     else if (failedServers > 0) connectionState = 'unavailable';
     const labels = {
       disconnected: '未连接', configured: '已配置', disabled: '已停用', healthy: '已连接',
-      degraded: '部分异常', reauth: '需重新授权', unavailable: '连接异常',
+      degraded: '部分异常', reauth: '需重新授权', recovering: '自动重试中', unavailable: '连接异常',
     };
     return {
       connectorId,
@@ -301,6 +647,7 @@ export async function apply(ctx, config) {
       configuredServers: records.length,
       enabledServers: enabledRecords.length,
       availableServers,
+      pendingServers,
       failedServers,
       checkedAt,
       results,
@@ -356,6 +703,156 @@ export async function apply(ctx, config) {
     return env;
   }
 
+  /* ───────────────────────── OAuth Grant 共享 ───────────────────────── */
+
+  function canonicalIssuer(value) {
+    try {
+      const url = new URL(value);
+      return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+    } catch {
+      return String(value ?? '').replace(/\/+$/, '');
+    }
+  }
+
+  function oauthResourceOrigins(connector) {
+    return [...new Set((connector.servers ?? []).map((server) => {
+      try { return new URL(server.url).origin; } catch { return ''; }
+    }).filter(Boolean))].sort();
+  }
+
+  function oauthSharingConnectors(connector) {
+    if (connector.auth?.grantSharing !== 'issuer' || !connector.auth.issuer) return [connector];
+    const issuer = canonicalIssuer(connector.auth.issuer);
+    const resourceOrigins = new Set(oauthResourceOrigins(connector));
+    const matches = state.merged.filter((candidate) => (
+      candidate.published !== false
+      && candidate.auth?.mode === 'oauth2-pkce'
+      && candidate.auth.grantSharing === 'issuer'
+      && canonicalIssuer(candidate.auth.issuer) === issuer
+      && candidate.auth.scope === connector.auth.scope
+      && candidate.auth.tokenEndpointAuthMethod === connector.auth.tokenEndpointAuthMethod
+      // 防止同 issuer 的第三方描述把共享 Bearer Token 聚合到其他资源域名。
+      && oauthResourceOrigins(candidate).every((origin) => resourceOrigins.has(origin))
+    ));
+    // 授权请求的 resource 必须优先使用用户点击的卡片；其余同组 Server 只用于识别共享范围。
+    return [connector, ...matches.filter((candidate) => candidate.id !== connector.id)];
+  }
+
+  function oauthSharingKey(connector) {
+    if (connector.auth?.grantSharing !== 'issuer' || !connector.auth.issuer) return `connector:${connector.id}`;
+    return `issuer:${config.account}:${canonicalIssuer(connector.auth.issuer)}:${connector.auth.scope}:${connector.auth.tokenEndpointAuthMethod}:${oauthResourceOrigins(connector).join(',')}`;
+  }
+
+  function oauthAuthorizationDescriptor(connector, sharingConnectors) {
+    if (sharingConnectors.length === 1) return connector;
+    const seen = new Set();
+    const servers = [];
+    for (const candidate of sharingConnectors) {
+      for (const server of candidate.servers) {
+        if (seen.has(server.url)) continue;
+        seen.add(server.url);
+        servers.push({ ...server, serverKey: `${candidate.id}:${server.serverKey}` });
+      }
+    }
+    return { ...connector, servers };
+  }
+
+  function oauthRecordsFor(connectors, authorizedResources, grantKey) {
+    const granted = new Set(authorizedResources);
+    const now = Date.now();
+    const records = [];
+    for (const connector of connectors) {
+      for (const server of connector.servers.filter((candidate) => granted.has(candidate.url))) {
+        records.push({
+          key: `${connector.id}-${server.serverKey}`,
+          connectorId: connector.id,
+          kind: 'oauth',
+          name: connector.servers.length > 1 ? `${connector.name}·${server.serverKey}` : connector.name,
+          serverKey: server.serverKey,
+          transport: server.transport,
+          url: server.url,
+          serverName: server.serverName,
+          headers: server.headers,
+          auth: { mode: 'oauth', grantKey },
+          enabled: true,
+          createdAt: now,
+          updatedAt: now,
+        });
+      }
+    }
+    return records;
+  }
+
+  function ensureRequestedConnectorsAuthorized(requestedIds, records) {
+    const connectedIds = new Set(records.map((record) => record.connectorId));
+    const missing = [...requestedIds].filter((id) => !connectedIds.has(id));
+    if (missing.length === 0) return;
+    throw new Error(`本次授权未包含连接器所需的 MCP 资源：${missing.join(', ')}`);
+  }
+
+  async function findReusableSharedGrant(connector) {
+    if (connector.auth?.grantSharing !== 'issuer' || !connector.auth.issuer) return null;
+    const issuer = canonicalIssuer(connector.auth.issuer);
+    for (const [grantKey, entry] of state.grants) {
+      const grant = entry.grant;
+      if (entry.needsReauth
+          || grant.account !== config.account
+          || grant.scope !== connector.auth.scope
+          || (grant.tokenEndpointAuthMethod ?? 'none') !== connector.auth.tokenEndpointAuthMethod
+          || canonicalIssuer(grant.issuer) !== issuer) continue;
+
+      if (grant.accessTokenExpiresAt <= Date.now()) {
+        try {
+          await refreshGrantWithRecovery(grantKey, 'shared-connect');
+        } catch (error) {
+          if (error.refreshFailure?.kind === 'transient') {
+            return { temporaryFailure: error.refreshFailure };
+          }
+          continue;
+        }
+      }
+      if (connector.servers.some((server) => entry.grant.authorizedResources.includes(server.url))) {
+        return { grantKey, entry };
+      }
+    }
+    return null;
+  }
+
+  async function attachConnectorsToGrant(grantKey, entry, connectors, requestedIds) {
+    const usableConnectors = connectors.filter((connector) => {
+      const conflict = legacyConflictForConnector(connector);
+      if (!conflict) return true;
+      warnLegacyConflict(conflict);
+      return false;
+    });
+    const records = oauthRecordsFor(usableConnectors, entry.grant.authorizedResources, grantKey);
+    ensureRequestedConnectorsAuthorized(requestedIds, records);
+    const connectedConnectorIds = [...new Set(records.map((record) => record.connectorId))];
+    const previous = entry.grant;
+    const next = {
+      ...previous,
+      connectorIds: [...new Set([...(previous.connectorIds ?? []), ...connectedConnectorIds])],
+      updatedAt: Date.now(),
+    };
+    entry.grant = next;
+    if (config.persistSecrets) await grantStore.put(next);
+    try {
+      const committed = await commitConnectionRecords(records);
+      for (const connector of usableConnectors) {
+        const own = committed.filter((record) => record.connectorId === connector.id);
+        if (own.length > 0) cacheHealth(connector.id, own, readinessResults(own));
+      }
+      scheduleRefresh(grantKey);
+      return committed;
+    } catch (error) {
+      entry.grant = previous;
+      if (config.persistSecrets) await grantStore.put(previous).catch((rollbackError) => {
+        logger.error(`shared grant rollback ${grantKey} failed: ${rollbackError.message}`);
+      });
+      throw error;
+    }
+  }
+
   /* ───────────────────────── api 门面 ───────────────────────── */
 
   const api = {
@@ -415,18 +912,67 @@ export async function apply(ctx, config) {
       if (!connector) return { ok: false, message: `连接器 "${connectorId}" 不存在（可先 mcp_connector_refresh_catalog 或 mcp_connector_catalog 查看）` };
 
       if (connector.auth.mode === 'oauth2-pkce') {
-        const inFlight = state.oauthConnects.get(connector.id);
-        if (inFlight) return inFlight;
+        const conflict = legacyConflictForConnector(connector);
+        if (conflict) {
+          warnLegacyConflict(conflict);
+          return { ok: false, message: conflict.message, detail: { kind: 'plugin-conflict', pluginId: conflict.pluginId, serverName: conflict.serverName } };
+        }
+
+        const sharingKey = oauthSharingKey(connector);
+        const inFlight = state.oauthConnects.get(sharingKey);
+        if (inFlight) {
+          inFlight.requestedConnectorIds.add(connector.id);
+          return inFlight.promise;
+        }
+        const requestedConnectorIds = new Set([connector.id]);
         const promise = (async () => {
           try {
+            const sharingConnectors = oauthSharingConnectors(connector);
+            const reusable = await findReusableSharedGrant(connector);
+            if (reusable?.temporaryFailure) {
+              return {
+                ok: false,
+                message: `OAuth 授权刷新暂时失败（${reusable.temporaryFailure.code}），插件将自动重试，无需重新授权`,
+                detail: { kind: 'refresh-retry', retrying: true },
+              };
+            }
+            if (reusable?.entry) {
+              const requestedConnectors = sharingConnectors.filter((item) => requestedConnectorIds.has(item.id));
+              const committed = await attachConnectorsToGrant(
+                reusable.grantKey,
+                reusable.entry,
+                requestedConnectors,
+                requestedConnectorIds,
+              );
+              const created = committed.map((record) => record.key);
+              return {
+                ok: true,
+                message: `已复用同账号 OAuth 授权连接 ${requestedConnectors.length} 个连接器（${created.length} 个 MCP server），无需再次授权`,
+                detail: { keys: created, grantKey: reusable.grantKey, reusedGrant: true, retiredGrantCount: 0 },
+              };
+            }
+
+            const sharingConnectorIds = new Set(sharingConnectors.map((item) => item.id));
             const previousGrantKeys = new Set(
               [...state.grants]
-                .filter(([, entry]) => entry.grant.connectorIds?.includes(connector.id))
+                .filter(([, entry]) => entry.grant.connectorIds?.some((id) => sharingConnectorIds.has(id)))
                 .map(([key]) => key),
             );
-            const authz = await oauthAuthorize({ connector, config, logger, signal });
+            const authorizationConnector = oauthAuthorizationDescriptor(connector, sharingConnectors);
+            const authz = await oauthAuthorize({ connector: authorizationConnector, config, logger, signal });
             const grantKey = grantStore.keyFor(config.account, authz.issuer, authz.clientId, authz.scope);
             const entryResource = authz.entryResource;
+            const authorizedResources = authz.grantedResources?.length ? authz.grantedResources : [entryResource];
+            const alreadyConnectedIds = new Set(
+              [...state.connections.values()]
+                .filter((record) => sharingConnectorIds.has(record.connectorId))
+                .map((record) => record.connectorId),
+            );
+            const targetIds = new Set([...alreadyConnectedIds, ...requestedConnectorIds]);
+            const targetConnectors = sharingConnectors.filter((item) => targetIds.has(item.id));
+            const previewRecords = oauthRecordsFor(targetConnectors, authorizedResources, grantKey);
+            ensureRequestedConnectorsAuthorized(requestedConnectorIds, previewRecords);
+            const grantedConnectorIds = [...new Set(previewRecords.map((record) => record.connectorId))];
             const grant = {
               key: grantKey,
               issuer: authz.issuer,
@@ -438,62 +984,41 @@ export async function apply(ctx, config) {
               scope: authz.scope,
               account: config.account,
               accessToken: authz.token.accessToken,
-              accessTokenExpiresAt: Date.now() + authz.token.expiresIn * 1000 - config.refreshSkewMs,
+              accessTokenExpiresAt: Date.now() + authz.token.expiresIn * 1000,
               refreshToken: authz.token.refreshToken ?? '',
-              authorizedResources: connector.servers
-                .filter((s) => authz.grantedKeys.includes(s.serverKey))
-                .map((s) => s.url).length
-                ? connector.servers.filter((s) => authz.grantedKeys.includes(s.serverKey)).map((s) => s.url)
-                : [entryResource],
-              connectorIds: [connector.id],
+              authorizedResources,
+              connectorIds: grantedConnectorIds,
               updatedAt: Date.now(),
             };
-            state.grants.set(grantKey, { grant, timer: undefined, refreshPromise: null, needsReauth: false });
+            const runtime = grantRuntime(grant);
+            state.grants.set(grantKey, runtime);
             if (config.persistSecrets) await grantStore.put(grant);
-
-            const created = [];
-            for (const sk of authz.grantedKeys) {
-              const server = connector.servers.find((s) => s.serverKey === sk);
-              if (!server) continue;
-              const record = {
-                key: `${connector.id}-${sk}`,
-                connectorId: connector.id,
-                kind: 'oauth',
-                name: connector.servers.length > 1 ? `${connector.name}·${sk}` : connector.name,
-                serverKey: sk,
-                transport: server.transport,
-                url: server.url,
-                serverName: server.serverName,
-                headers: server.headers,
-                auth: { mode: 'oauth', grantKey },
-                enabled: true,
-                createdAt: Date.now(),
-                updatedAt: Date.now(),
-              };
-              await upsertRecord(record);
-              created.push(record.key);
-            }
-            scheduleRefresh(grantKey);
+            const committed = await attachConnectorsToGrant(grantKey, runtime, targetConnectors, requestedConnectorIds);
+            const created = committed.map((record) => record.key);
             let retiredGrantCount = 0;
             for (const previousKey of previousGrantKeys) {
               if (previousKey !== grantKey && await retireGrantIfUnused(previousKey, { revoke: true })) retiredGrantCount += 1;
             }
             return {
               ok: true,
-              message: `已连接 "${connector.name}"（${created.length} 个 MCP server），共 ${created.length} 条`,
-              detail: { keys: created, grantKey, retiredGrantCount },
+              message: sharingConnectors.length > 1
+                ? `OAuth 授权成功；已为同一账号保存共享授权并连接 ${targetConnectors.length} 个连接器（${created.length} 个 MCP server）`
+                : `已连接 "${connector.name}"（${created.length} 个 MCP server），共 ${created.length} 条`,
+              detail: { keys: created, grantKey, sharedGrant: sharingConnectors.length > 1, retiredGrantCount },
             };
           } catch (error) {
             logger.error(`oauth connect failed: ${error.message}`);
             await pruneOrphanGrants();
-            return { ok: false, message: `连接失败: ${error.message}` };
+            return error?.connectionRecord
+              ? connectionSetupFailure(error)
+              : { ok: false, message: `连接失败: ${error.message}` };
           }
         })();
-        state.oauthConnects.set(connector.id, promise);
+        state.oauthConnects.set(sharingKey, { promise, requestedConnectorIds });
         try {
           return await promise;
         } finally {
-          if (state.oauthConnects.get(connector.id) === promise) state.oauthConnects.delete(connector.id);
+          if (state.oauthConnects.get(sharingKey)?.promise === promise) state.oauthConnects.delete(sharingKey);
         }
       }
 
@@ -518,8 +1043,15 @@ export async function apply(ctx, config) {
           createdAt: Date.now(),
           updatedAt: Date.now(),
         };
-        await upsertRecord(record);
-        return { ok: true, message: `已连接 "${connector.name}"`, detail: { key: record.key } };
+        const validation = await validateConnectionRecords([record], { timeoutMs: config.requestTimeoutMs });
+        if (!validation.ok) return { ...validation, detail: { connectorId: connector.id, ...validation.detail } };
+        try {
+          const [committed] = await commitConnectionRecords([record]);
+          cacheHealth(connector.id, [committed], readinessResults([committed], validation.detail.results));
+          return { ok: true, message: `已连接 "${connector.name}"`, detail: { key: committed.key } };
+        } catch (error) {
+          return connectionSetupFailure(error);
+        }
       }
 
       // bearer / api-key 型：目录不含密钥，引导自定义配置
@@ -574,12 +1106,9 @@ export async function apply(ctx, config) {
           const validation = await validateConnectionRecords(records, { timeoutMs: config.requestTimeoutMs });
           if (!validation.ok) return { ...validation, detail: { connectorId: connector.id, ...validation.detail } };
 
-          const created = [];
-          for (const record of records) {
-            await upsertRecord(record);
-            created.push(record.key);
-          }
-          cacheHealth(connector.id, records, validation.detail.results);
+          const committed = await commitConnectionRecords(records);
+          const created = committed.map((record) => record.key);
+          cacheHealth(connector.id, committed, readinessResults(committed, validation.detail.results));
           return {
             ok: true,
             message: `已配置并连接 "${connector.name}"（${created.length} 个 MCP Server）`,
@@ -587,20 +1116,39 @@ export async function apply(ctx, config) {
           };
         }
         const record = buildManualRecord(params);
-        await upsertRecord(record);
-        return { ok: true, message: `已配置并连接 "${record.name}"（serverName=${record.serverName}）`, detail: { key: record.key, serverName: record.serverName } };
+        const validation = await validateConnectionRecords([record], { timeoutMs: config.requestTimeoutMs });
+        if (!validation.ok) return validation;
+        const [committed] = await commitConnectionRecords([record]);
+        cacheHealth(committed.connectorId, [committed], readinessResults([committed], validation.detail.results));
+        return { ok: true, message: `已配置并连接 "${committed.name}"（serverName=${committed.serverName}）`, detail: { key: committed.key, serverName: committed.serverName } };
       } catch (error) {
-        return { ok: false, message: `配置失败: ${error.message}` };
+        return error?.connectionRecord
+          ? connectionSetupFailure(error, '配置失败')
+          : { ok: false, message: `配置失败: ${error.message}` };
       }
     },
 
     async importJson(json) {
       try {
         const { records, skipped } = normalizeJsonImport(json);
-        const keys = [];
-        for (const record of records) {
-          await upsertRecord(record);
-          keys.push(record.key);
+        const validation = await validateConnectionRecords(records, {
+          timeoutMs: config.requestTimeoutMs,
+          concurrency: 4,
+        });
+        if (!validation.ok) return validation;
+        const committed = await commitConnectionRecords(records);
+        const keys = committed.map((record) => record.key);
+        const grouped = new Map();
+        for (const record of committed) {
+          if (!grouped.has(record.connectorId)) grouped.set(record.connectorId, []);
+          grouped.get(record.connectorId).push(record);
+        }
+        for (const [connectorId, connectorRecords] of grouped) {
+          const results = connectorRecords.map((record) => {
+            const index = committed.findIndex((item) => item.key === record.key);
+            return readinessResults([record], [validation.detail.results[index]])[0];
+          });
+          cacheHealth(connectorId, connectorRecords, results);
         }
         const extra = skipped.length ? `；跳过：${skipped.join('、')}` : '';
         return {
@@ -609,7 +1157,9 @@ export async function apply(ctx, config) {
           detail: { keys, skipped },
         };
       } catch (error) {
-        return { ok: false, message: `导入失败: ${error.message}` };
+        return error?.connectionRecord
+          ? connectionSetupFailure(error, '导入失败')
+          : { ok: false, message: `导入失败: ${error.message}` };
       }
     },
 
@@ -651,6 +1201,9 @@ export async function apply(ctx, config) {
                 grantKey: record.auth.grantKey,
                 accessTokenExpiresAt: g.grant.accessTokenExpiresAt,
                 needsReauth: !!g.needsReauth,
+                refreshFailureKind: g.refreshFailureKind,
+                lastRefreshError: g.lastRefreshError,
+                refreshRetryAt: g.refreshRetryAt,
               }
             : { grantKey: record.auth.grantKey, missing: true };
         }
@@ -667,7 +1220,9 @@ export async function apply(ctx, config) {
           authMode: record.auth?.mode ?? 'none',
           grant: grantInfo,
           lastError: record.lastError ?? null,
-          connectionState: recordHealth?.ok ? 'healthy' : recordHealth ? health.connectionState : health?.connectionState ?? 'configured',
+          connectionState: recordHealth?.ok && recordHealth.kind !== 'managed'
+            ? 'healthy'
+            : recordHealth ? health.connectionState : health?.connectionState ?? 'configured',
           healthCheckedAt: health?.checkedAt ?? null,
           healthMessage: recordHealth?.message ?? null,
         });
@@ -694,7 +1249,29 @@ export async function apply(ctx, config) {
         for (const record of enabledRecords) {
           const failure = grantFailure(record);
           if (failure) immediateResults.push(failure);
-          else checkable.push(record);
+          else if (record.transport === 'stdio') {
+            const registered = registeredStdioTools(record);
+            if (registered.tools.length > 0) {
+              immediateResults.push({
+                ok: true,
+                kind: 'connected',
+                serverKey: record.serverKey,
+                serverName: record.serverName,
+                toolCount: registered.tools.length,
+                message: `Host 已注册 ${registered.tools.length} 个工具`,
+              });
+            } else {
+              immediateResults.push({
+                ok: true,
+                kind: 'managed',
+                serverKey: record.serverKey,
+                serverName: record.serverName,
+                message: registered.supported
+                  ? 'Host 尚未注册该 stdio Server 的工具'
+                  : '当前 Host 无法读取 stdio 工具注册状态',
+              });
+            }
+          } else checkable.push(record);
         }
         let checkedResults = [];
         if (checkable.length > 0) {
@@ -708,7 +1285,7 @@ export async function apply(ctx, config) {
         summaries.push(cacheHealth(id, records, [...immediateResults, ...checkedResults]));
       }
       const healthy = summaries.filter((item) => item.connectionState === 'healthy').length;
-      const attention = summaries.filter((item) => ['reauth', 'degraded', 'unavailable'].includes(item.connectionState)).length;
+      const attention = summaries.filter((item) => ['reauth', 'recovering', 'degraded', 'unavailable'].includes(item.connectionState)).length;
       return {
         ok: true,
         message: targetIds.length === 0
@@ -741,24 +1318,34 @@ export async function apply(ctx, config) {
         if (plan.summary.alreadyMigrated) { skipped.push(`${plan.summary.connectorName}(已迁移)`); continue; }
         const grantKey = grantStore.keyFor(config.account, plan.candidate.grant.issuer, plan.candidate.grant.clientId, plan.candidate.grant.scope);
         const grant = toConnectorGrant(plan.candidate, { key: grantKey, account: config.account, connectorIds: [plan.connector.id] });
-        state.grants.set(grantKey, { grant, timer: undefined, refreshPromise: null, needsReauth: false });
+        state.grants.set(grantKey, grantRuntime(grant));
         if (config.persistSecrets) await grantStore.put(grant);
 
         let enabled = true;
+        let provisionNow = true;
         let lastError;
+        const legacyConflict = legacyConflictForConnector(plan.connector);
+        if (legacyConflict) {
+          warnLegacyConflict(legacyConflict);
+          provisionNow = false;
+          lastError = `${legacyConflict.message}；授权已复制，重启后将由 MCP连接器恢复`;
+        }
         if (grant.accessTokenExpiresAt <= Date.now()) {
-          try { await refreshGrant(grantKey); }
+          try { await refreshGrantWithRecovery(grantKey, 'legacy-migration'); }
           catch (error) {
-            enabled = false;
-            lastError = `旧授权已过期且刷新失败，请重新连接：${error instanceof Error ? error.message : String(error)}`;
-            state.grants.get(grantKey).needsReauth = true;
+            const permanent = error.refreshFailure?.permanent === true;
+            enabled = !permanent;
+            provisionNow = false;
+            lastError = permanent
+              ? `旧授权已失效，请重新连接：${error.refreshFailure?.message ?? error.message}`
+              : `旧授权刷新暂时失败，正在自动重试：${error.refreshFailure?.message ?? error.message}`;
           }
         } else {
           scheduleRefresh(grantKey);
         }
         const records = toConnectionRecords(plan, grantKey, { enabled, lastError });
         for (const record of records) {
-          if (enabled) await upsertRecord(record);
+          if (enabled && provisionNow) await upsertRecord(record);
           else await persistRecord(record);
         }
         migrated.push({ connectorId: plan.connector.id, keys: records.map((record) => record.key), enabled });
@@ -775,11 +1362,26 @@ export async function apply(ctx, config) {
     async setEnabled(key, enabled) {
       const record = state.connections.get(key);
       if (!record) return { ok: false, message: `连接 "${key}" 不存在` };
-      record.enabled = !!enabled;
-      await persistRecord(record);
-      if (record.enabled) await provision(ctx, config, record, grantMap());
-      else await disable(ctx, config, record);
-      return { ok: true, message: `已${record.enabled ? '启用' : '停用'} "${record.name}"` };
+      const next = { ...record, enabled: !!enabled, updatedAt: Date.now() };
+      if (next.enabled) {
+        try {
+          const [committed] = await commitConnectionRecords([next]);
+          if (committed.connectorId) cacheHealth(committed.connectorId, [committed], readinessResults([committed]));
+          return { ok: true, message: `已启用 "${committed.name}"` };
+        } catch (error) {
+          return connectionSetupFailure(error, '启用失败');
+        }
+      }
+      await disable(ctx, config, next);
+      try {
+        await persistRecord(next);
+      } catch (error) {
+        await provision(ctx, config, record, grantMap(), { failOnStartupError: false }).catch((rollbackError) => {
+          logger.error(`disable rollback "${record.key}" failed: ${rollbackError.message}`);
+        });
+        throw error;
+      }
+      return { ok: true, message: `已停用 "${next.name}"` };
     },
 
     async disconnect(key, signal) {
@@ -887,19 +1489,30 @@ export async function apply(ctx, config) {
       const servers = [];
       for (const record of records) {
         if (record.transport === 'stdio') {
+          const registered = registeredStdioTools(record);
           const snapshot = (connector.toolsSnapshot ?? []).find((item) =>
             item.serverKey === record.serverKey || item.serverName === record.serverName);
+          const liveTools = registered.tools;
           servers.push({
             serverKey: record.serverKey || record.name,
             serverName: record.serverName,
-            ok: true,
+            ok: liveTools.length > 0,
             managed: true,
-            preview: Boolean(snapshot),
-            tools: (snapshot?.tools ?? []).map((tool) => ({
-              name: tool.name,
-              title: tool.title || tool.name,
-              description: tool.description || '',
-            })),
+            live: liveTools.length > 0,
+            preview: liveTools.length === 0 && Boolean(snapshot),
+            tools: liveTools.length > 0
+              ? liveTools
+              : (snapshot?.tools ?? []).map((tool) => ({
+                  name: tool.name,
+                  title: tool.title || tool.name,
+                  description: tool.description || '',
+                })),
+            ...(liveTools.length === 0 ? {
+              errorKind: registered.supported ? 'startup' : 'host-version',
+              error: registered.supported
+                ? 'Host 尚未注册该 stdio Server 的工具，请检查启动日志后重试'
+                : '当前 DSH Host 不支持读取工具注册状态，请升级 Host 后重试',
+            } : {}),
           });
           continue;
         }
@@ -938,7 +1551,7 @@ export async function apply(ctx, config) {
       const totalTools = servers.reduce((sum, s) => sum + (s.tools?.length || 0), 0);
       const availableServers = servers.filter((server) => server.ok).length;
       const failedServers = servers.length - availableServers;
-      const managedWithoutSnapshot = servers.filter((server) => server.managed && !server.preview).length;
+      const pendingManagedServers = servers.filter((server) => server.managed && !server.ok).length;
       const health = cacheHealth(connectorId, records, servers.map((server) => server.ok
         ? { ok: true, kind: 'connected', serverKey: server.serverKey, serverName: server.serverName }
         : { ok: false, kind: server.errorKind ?? 'network', serverKey: server.serverKey, serverName: server.serverName, message: server.error }));
@@ -948,10 +1561,16 @@ export async function apply(ctx, config) {
         ok: availableServers > 0,
         message: failedServers > 0
           ? `工具加载失败：${failureSummary}${failedServers > 3 ? `；另有 ${failedServers - 3} 个 Server 不可用` : ''}${availableServers > 0 ? `；${availableServers} 个 Server 仍可用` : ''}`
-          : managedWithoutSnapshot > 0
-            ? `共 ${servers.length} 个 server；${managedWithoutSnapshot} 个 stdio Server 的工具由 DSH Host 注册，当前目录无工具快照`
-            : `共 ${servers.length} 个 server，${totalTools} 个工具`,
-        detail: { connectorId, servers, totalTools, availableServers, failedServers, managedWithoutSnapshot, connectionState: health.connectionState },
+          : `共 ${servers.length} 个 server，${totalTools} 个工具`,
+        detail: {
+          connectorId,
+          servers,
+          totalTools,
+          availableServers,
+          failedServers,
+          pendingManagedServers,
+          connectionState: health.connectionState,
+        },
       };
     },
   };
@@ -959,6 +1578,7 @@ export async function apply(ctx, config) {
   /* ───────────────────────── 启动恢复 ───────────────────────── */
 
   await loadCatalog();
+  detectLegacyPluginConflicts();
 
   for (const [key, raw] of await connectionStore.entries().catch(() => [])) {
     try {
@@ -970,7 +1590,7 @@ export async function apply(ctx, config) {
   }
   for (const [key, raw] of await grantStore.entries().catch(() => [])) {
     try {
-      state.grants.set(key, { grant: raw, timer: undefined, refreshPromise: null, needsReauth: false });
+      state.grants.set(key, grantRuntime(raw));
     } catch (error) {
       logger.warn(`skip invalid stored grant "${key}": ${error.message}`);
     }
@@ -982,16 +1602,19 @@ export async function apply(ctx, config) {
   for (const [grantKey, g] of state.grants) {
     if (g.grant.accessTokenExpiresAt <= Date.now()) {
       try {
-        await refreshGrant(grantKey);
-      } catch {
-        g.needsReauth = true;
-      }
+        await refreshGrantWithRecovery(grantKey, 'startup');
+      } catch {}
     } else {
       scheduleRefresh(grantKey);
     }
   }
   for (const [key, record] of state.connections) {
     if (record.enabled !== false) {
+      const failure = grantFailure(record);
+      if (failure) {
+        logger.warn(`skip provision "${key}" at startup: ${failure.message}`);
+        continue;
+      }
       await provision(ctx, config, record, grantMap()).catch((error) => {
         logger.warn(`provision "${key}" failed: ${error.message}`);
       });