dsh-mcp-connector 0.2.24 → 0.2.26

package/CHANGELOG.md

@@ -4,6 +4,33 @@
 
 ## [Unreleased]
 
+## [0.2.26] - 2026-08-27
+
+### Fixed
+
+- 升级启动时自动发现并归并历史版本为同 issuer 卡片保存的多份 OAuth Grant；归并前先验证过期 Grant 是否仍可刷新，避免用较新但已失效的凭据覆盖可恢复授权。
+- 多个 DSH 进程并发刷新同一组轮换式 Refresh Token 时，收到 `invalid_grant` 后会短暂重读本机持久化 Grant；发现其他进程已保存新 Token 时自动采用并重试，不再误报“需重新授权”。
+- 页面不再盲信 Update Provider 的 `succeeded`；独立校验更新前、预期与实际版本，检测降级、解析版本偏差或无效结果时拒绝重启，并在 Provider 保留恢复点时自动回滚。
+
+### Verification
+
+- 129 项自动测试、lint、npm 发布包白名单与敏感内容扫描通过；新增历史 Grant 安全归并、失效候选回退、跨进程 Token 轮换恢复和 Provider 版本完整性回归测试。
+
+## [0.2.25] - 2026-08-27
+
+### Added
+
+- 新增 Update Provider 适配层，将版本发现与安装执行解耦；UI 通过统一能力调用更新检查、任务、回滚和重启，为 DSH 原生或其他插件市场预留适配边界。
+- 首个 DSH Market API v1 Provider 适配器：能力探测通过后可一键更新插件，并轮询展示安装进度、稳定失败码、兼容回滚结果及按 Web/Desktop 宿主能力提供的刷新或重启操作。
+
+### Compatibility
+
+- Provider 未安装、协议不兼容、广告跨源/无效端点或版本检查不一致时不调用私有更新路由，继续使用现有“前往插件市场”/npm 页面降级路径。
+
+### Verification
+
+- 125 项自动测试、lint、npm 发布包白名单/敏感内容扫描通过；已在 web profile 的 dshmarket 1.33.0 上验证 `/dsh-market/api/v1/capabilities` 与 Connector 版本检查响应。
+
 ## [0.2.24] - 2026-08-27
 
 ### Added
@@ -399,7 +426,9 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.24...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.26...HEAD
+[0.2.26]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.25...v0.2.26
+[0.2.25]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.24...v0.2.25
 [0.2.24]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.23...v0.2.24
 [0.2.23]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.22...v0.2.23
 [0.2.22]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.21...v0.2.22

package/README.en.md

@@ -28,7 +28,7 @@ Browse and install MCP connectors from different providers in DeepSeek Harness D
 - Persistent connection lifecycle management: restore on restart, enable/disable, disconnect, retry transient OAuth refresh failures with bounded backoff, and revoke authorization. Cards declaring issuer-level sharing reuse one grant; DCR client secrets remain local to that grant.
 - Built-in, remote, and local catalogs with `published` and `featured` controls.
 - A standalone remote Registry, allowing new marketplace cards to appear after refresh without publishing a new npm version.
-- Plugin version awareness: the MCP Connector title shows the installed version, while a server-side cached check compares npm `latest` with GitHub Releases and routes available updates through the DSH plugin marketplace.
+- Plugin version and one-click updates: version discovery is independent of the installation source, while an Update Provider adapter layer negotiates safe mutation capabilities. DSH Market API v1 is the first adapter and supports progress, normalized failures, rollback, and capability-gated restart/refresh actions; without a compatible provider, the UI falls back to the current plugin marketplace or npm.
 - Explicit, non-destructive migration from the two earlier Qichacha OAuth plugins, plus active-plugin conflict detection that blocks duplicate server management and credential overwrites.
 
 <!-- catalog-stats:start -->

package/README.md

@@ -28,7 +28,7 @@
 - 生命周期管理：连接持久化、重启恢复、启停、断开、OAuth 自动刷新/退避恢复与撤销；同 issuer 卡片可共享一次授权，DCR 返回的客户端密钥与 Token 一同只保存在本机。
 - 目录运营：内置目录、远程 registry、本地覆盖，支持 `published` 上下架与 `featured` 精选。
 - 独立远程 Registry：新市场卡片合并后客户端刷新即可见，无需重新发布 npm；远程不可用时自动回退内置目录。
-- 插件版本感知：MCP连接器标题显示当前版本，服务端缓存检查 npm 与 GitHub Release；发现 npm 新版本时引导到 DSH 插件市场更新。
+- 插件版本与一键更新：版本发现独立于安装来源；页面通过 Update Provider 适配层探测安全更新能力。DSH Market API v1 是首个适配器，支持进度、稳定失败码、回滚及按宿主能力提供的重启/刷新操作；无可用 Provider 时回退到当前插件市场或 npm。
 - Registry 工具链：Schema/唯一性/密钥审计、MCP/OAuth 无凭据探针、每周健康巡检。
 - 平滑迁移：显式扫描并复制两个旧企查查 OAuth 插件授权；检测到旧插件仍启用并管理同名 Server 时阻断重复连接，避免凭据相互覆盖。
 - 对话工具：`mcp_connector_catalog`、`connect`、`configure`、`import_json`、`install_from_url`、`status`、`health_check`、`set_enabled`、`disconnect`、`refresh_catalog`、`publish`、`tools_list`。

package/docs/PLUGIN-UPDATE.md

@@ -0,0 +1,35 @@
+# MCP连接器插件更新协议
+
+MCP连接器把“刷新连接器目录”和“升级插件代码”视为两个独立动作：前者只重新拉取 Registry 卡片，后者必须由当前 DSH 宿主中可用的安全 Update Provider 执行。
+
+## 分层与 Provider 适配
+
+版本发现与更新执行彻底分离：
+
+- MCP连接器自己的 Host 检查 npm `latest` 与 GitHub Release，所有安装方式都可显示已安装版本和新版本提示。
+- 客户端通过 `UPDATE_PROVIDER_ADAPTERS` 按顺序探测 Provider。UI 只调用统一的 `probe` / `check` / `start` / `operation` / `rollback` / `restart` 能力，不持有市场私有路由。
+- DSH Market API v1 是首个 Provider 适配器。后续可在不改动更新 UI 状态机的前提下增加 DSH 原生能力或其他插件市场的版本化协议适配器。
+
+## 能力协商
+
+每个 Provider 适配器只硬编码自己的 capabilities 入口，其余更新、任务、回滚和重启端点均从能力响应中读取。客户端只接受当前 DSH 页面的相对同源端点，拒绝跨域 URL、协议不匹配、缺少必要端点或未声明 `features.update` 的 Provider。
+
+DSH Market 适配器从 `GET /dsh-market/api/v1/capabilities` 开始，要求 `schema: dsh-market/update-api/v1` 与 `apiVersion: 1`。未安装任何可用 Provider、接口返回 404、协议不兼容或检查失败时，页面不会尝试私有更新路由，而是回退到“前往插件市场”；设置入口不可用时再打开 npm 包页面。
+
+## 更新流程
+
+1. 插件自己的服务端缓存检查 npm `latest` 与 GitHub Release，只在 npm 已有可安装新版本时提示升级。
+2. 选中的 Provider 再检查本 profile 中 `dsh-mcp-connector` 的实际安装版本和目标版本。
+3. 用户点击“一键更新”后，Provider 立即返回 `operationId`；页面通过适配器轮询任务状态，展示排队、解析、下载和安装进度。
+4. Provider 报告成功后，页面仍会独立校验 `beforeVersion`、点击时的预期版本与 `installedVersion`。降级、目标不一致或无效结果会被拒绝；Provider 保留恢复点时自动回滚，不向用户展示重启。
+5. 完整性校验通过后，按 Provider 返回的激活结论展示“刷新生效”或重启提示。Web 且 Provider 明确允许进程重启时才展示“立即重启”；Desktop 等由外壳管理生命周期的宿主只提示用户重启，不自行杀进程。
+6. Provider 保留恢复点时展示“回滚”。回滚仍由 Provider 执行，MCP连接器不直接修改 profile、lockfile 或 `node_modules`。
+
+失败结果使用稳定代码区分正在运行的 Agent、其他安装任务占用、镜像同步、版本未变化、超时和权限拒绝，以及 `DOWNGRADE_DETECTED`、`RESOLVED_VERSION_MISMATCH`、`INVALID_UPDATE_RESULT` 三类完整性故障。可重试失败保留重试操作；Registry 刚发布但镜像仍未同步时，用户可在看到明确提示后选择强制重试。
+
+## 安全边界
+
+- 所有变更请求均为浏览器同源 POST，并继续接受 Provider 自身的 Origin、环回地址和运行中任务保护。
+- MCP连接器不执行 `npm`/`pnpm`、不保存回滚 Token，也不复制任何 Provider 的安装算法。
+- 重启按钮完全服从能力响应；接口未声明支持时不得构造其他进程控制路径。
+- 更新任务属于当前 Host 进程。Host 已更换后，旧页面的任务编号自然失效，避免把旧进度误认为新进程状态。

package/docs/USER-GUIDE.md

@@ -42,7 +42,7 @@ dsh web
 - **已安装**：查看已经保存到本机的连接，页签徽标显示连接数。
 - **搜索**：按名称、服务商、简介和标签查找。
 - **添加连接**：导入 JSON、手动配置 HTTP/stdio，或从市场描述 URL 安装。
-- **版本与更新提示**：标题旁显示当前插件版本。检测到 npm 有新版本时，点击更新提示前往 DSH 插件市场执行安全升级；升级后按页面提示完全重启 DSH。
+- **版本与更新提示**：标题旁显示当前插件版本，版本检查不依赖安装所用的插件市场。检测到 npm 有新版本且当前宿主存在兼容 Update Provider 时，可在当前页面一键更新并查看进度、失败原因和可用回滚。DSH Market API v1 是当前首个 Provider；无可用 Provider 时自动回退为“前往插件市场”或 npm 页面。
 - **刷新连接器目录**：重新拉取 Registry 卡片，并更新连接健康状态；该操作不会升级 MCP连接器插件本身。
 
 ## 3. 浏览市场与分类
@@ -75,7 +75,7 @@ stdio 市场卡片也可能显示一个或多个凭据字段，例如 API Token
 
 OAuth 一键连接要求服务商支持标准 OAuth 2.1/PKCE 和公开元数据发现。动态客户端注册既支持无需客户端密钥的 `none`，也支持服务商签发密钥的 `client_secret_post` 与 `client_secret_basic`。客户端密钥仅与 OAuth Grant 一同保存在 DSH 本机，用于换取、刷新和撤销 Token；插件不会要求用户把 OAuth Token 或客户端密钥复制到聊天中。
 
-当市场描述声明 `grantSharing: "issuer"` 时，同一账号下相同 issuer、scope 和客户端鉴权方式的卡片共享一组 Grant。首次授权仍只启用用户点击的卡片；之后连接同组卡片会直接复用现有授权，不再重复打开 OAuth 页面。网络、OAuth 元数据发现或服务端 5xx 等暂时故障只进入“自动重试中”，明确收到 Refresh Token/客户端失效错误时才进入“需重新授权”。
+当市场描述声明 `grantSharing: "issuer"` 时，同一账号下相同 issuer、scope 和客户端鉴权方式的卡片共享一组 Grant。首次授权仍只启用用户点击的卡片；之后连接同组卡片会直接复用现有授权，不再重复打开 OAuth 页面。升级时会验证并自动归并旧版本留下的同 issuer 多份 Grant；多个 DSH 进程并发轮换 Refresh Token 时也会重读较新的本机持久化凭据后自动恢复。网络、OAuth 元数据发现或服务端 5xx 等暂时故障只进入“自动重试中”，确认本机也没有其他进程保存的新 Token，且明确收到 Refresh Token/客户端失效错误时，才进入“需重新授权”。
 
 ## 5. 查看详情、Prompt 与工具
 

package/lib/client.js

@@ -22,6 +22,17 @@ window.__ModuleLoader__.load({
 		const VERSION_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
 		const VERSION_CHECK_RETRY_MS = 5 * 60 * 1e3;
 		const NPM_PACKAGE_URL = "https://www.npmjs.com/package/dsh-mcp-connector";
+		const PLUGIN_PACKAGE_NAME = "dsh-mcp-connector";
+		const UPDATE_PROVIDER_OPERATION_POLL_MS = 1e3;
+		const UPDATE_PROVIDER_ADAPTERS = Object.freeze([
+			createHttpUpdateProviderAdapter({
+				id: "dsh-market-v1",
+				label: "DSH Market",
+				schema: "dsh-market/update-api/v1",
+				apiVersion: 1,
+				capabilitiesUrl: "/dsh-market/api/v1/capabilities"
+			})
+		]);
 
 		/**
 		 * Desktop 内置的社区插件市场也注册在 sidebar.footer.action。
@@ -114,6 +125,37 @@ window.__ModuleLoader__.load({
 	outline: 2px solid #6366f1;
 	outline-offset: 1px;
 }
+.mcpConnectorUpdateButton:disabled {
+	opacity: 0.65;
+	cursor: wait;
+}
+.mcpConnectorUpdateControls {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	min-width: 0;
+}
+.mcpConnectorUpdateStatus {
+	max-width: 240px;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	color: #166534;
+	background: #f0fdf4;
+	border-radius: 999px;
+	padding: 3px 8px;
+	font-size: 12px;
+	font-weight: 600;
+}
+.mcpConnectorUpdateStatus[data-tone="error"] {
+	color: #b91c1c;
+	background: #fef2f2;
+}
+.mcpConnectorUpdateSecondary {
+	color: #4b5563;
+	background: transparent;
+	border-color: #d1d5db;
+}
 .mcpConnectorMarketClose { color: #6b7280; }
 .mcpConnectorMarketClose:hover,
 .mcpConnectorMarketClose:focus-visible {
@@ -131,6 +173,9 @@ window.__ModuleLoader__.load({
 	.mcpConnectorUpdateButton { color: #c7d2fe; background: #312e81; border-color: #4f46e5; }
 	.mcpConnectorUpdateButton:hover,
 	.mcpConnectorUpdateButton:focus-visible { background: #3730a3; }
+	.mcpConnectorUpdateStatus { color: #bbf7d0; background: #14532d; }
+	.mcpConnectorUpdateStatus[data-tone="error"] { color: #fecaca; background: #7f1d1d; }
+	.mcpConnectorUpdateSecondary { color: #d1d5db; background: transparent; border-color: #4b5563; }
 	.mcpConnectorMarketClose { color: #c4c8d0; }
 	.mcpConnectorMarketClose:hover,
 	.mcpConnectorMarketClose:focus-visible { background: #30343d !important; color: #ffffff; }
@@ -180,6 +225,219 @@ window.__ModuleLoader__.load({
 			return result.detail;
 		}
 
+		/**
+		 * 更新 Provider 只能广告当前 DSH 页面的同源端点。这个边界既避免
+		 * Connector 跨域传递安装指令，也使后续市场适配器可复用同一客户端。
+		 */
+		function sameOriginProviderEndpoint(value) {
+			if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//")) return null;
+			try {
+				const url = new URL(value, window.location.origin);
+				if (url.origin !== window.location.origin || url.search !== "" || url.hash !== "") return null;
+				return url.pathname;
+			} catch {
+				return null;
+			}
+		}
+
+		/**
+		 * 把一个版本化的同源 HTTP 更新协议适配为 Connector 内部通用能力。
+		 * UI 不接触供应商路由或响应封装；新市场只需新增适配器。
+		 */
+		function createHttpUpdateProviderAdapter(options) {
+			const { id, label, schema, apiVersion, capabilitiesUrl } = options;
+			async function readResponse(response) {
+				let result;
+				try {
+					result = await response.json();
+				} catch {
+					result = null;
+				}
+				if (!response.ok) {
+					const error = new Error(result?.error ?? result?.failure?.message ?? `HTTP ${response.status}`);
+					error.code = result?.failure?.code ?? `HTTP_${response.status}`;
+					error.retryable = result?.failure?.retryable === true;
+					throw error;
+				}
+				if (result?.schema !== schema) throw new Error(`${label} 更新接口版本不兼容`);
+				return result;
+			}
+
+			async function post(path, body) {
+				return readResponse(await window.fetch(path, {
+					method: "POST",
+					headers: { accept: "application/json", "content-type": "application/json" },
+					body: JSON.stringify(body)
+				}));
+			}
+
+			return Object.freeze({
+				id,
+				label,
+				async probe() {
+					const response = await window.fetch(capabilitiesUrl, { headers: { accept: "application/json" } });
+					if (response.status === 404) return null;
+					const result = await readResponse(response);
+					if (result.apiVersion !== apiVersion || result.features?.update !== true) return null;
+					const endpoints = {
+						updates: sameOriginProviderEndpoint(result.endpoints?.updates),
+						operations: sameOriginProviderEndpoint(result.endpoints?.operations),
+						rollback: sameOriginProviderEndpoint(result.endpoints?.rollback),
+						restart: sameOriginProviderEndpoint(result.endpoints?.restart)
+					};
+					if (endpoints.updates === null || endpoints.operations === null) return null;
+					if (result.features?.rollback === true && endpoints.rollback === null) return null;
+					if (result.restart?.supported === true && endpoints.restart === null) return null;
+					return {
+						providerId: id,
+						providerLabel: label,
+						runtime: result.runtime,
+						features: result.features,
+						restart: result.restart,
+						endpoints
+					};
+				},
+				async check(capabilities, packageName, force = false) {
+					const query = new URLSearchParams({ name: packageName });
+					if (force) query.set("force", "1");
+					const result = await readResponse(await window.fetch(`${capabilities.endpoints.updates}?${query}`, {
+						headers: { accept: "application/json" }
+					}));
+					return result.package;
+				},
+				async start(capabilities, packageName, force = false) {
+					const result = await post(capabilities.endpoints.updates, {
+						packageName,
+						...(force ? { force: true } : {})
+					});
+					if (typeof result.operation?.operationId !== "string") {
+						throw new Error(`${label} 未返回更新任务编号`);
+					}
+					return result.operation;
+				},
+				async operation(capabilities, operationId) {
+					const query = new URLSearchParams({ operationId });
+					const result = await readResponse(await window.fetch(`${capabilities.endpoints.operations}?${query}`, {
+						headers: { accept: "application/json" }
+					}));
+					return result.operation;
+				},
+				async rollback(capabilities, operationId) {
+					if (capabilities.endpoints.rollback === null) throw new Error(`${label} 不支持回滚`);
+					const result = await post(capabilities.endpoints.rollback, { operationId });
+					return result.operation;
+				},
+				async restart(capabilities) {
+					if (capabilities.endpoints.restart === null) throw new Error(`${label} 不支持重启`);
+					return post(capabilities.endpoints.restart, {});
+				}
+			});
+		}
+
+		async function discoverUpdateProvider(packageName, force = false) {
+			for (const provider of UPDATE_PROVIDER_ADAPTERS) {
+				try {
+					const capabilities = await provider.probe();
+					if (capabilities === null) continue;
+					const update = await provider.check(capabilities, packageName, force);
+					return { provider, capabilities, update };
+				} catch (error) {
+					console.warn(`[mcp-connector] ${provider.id} update provider unavailable:`, error);
+				}
+			}
+			return null;
+		}
+
+		function updateProgressLabel(operation) {
+			if (operation?.state === "queued") return "更新任务排队中…";
+			const percent = operation?.progress?.percent;
+			if (typeof percent === "number") return `正在更新 ${percent}%`;
+			const phase = operation?.progress?.phase;
+			if (typeof phase === "string" && phase !== "") return `正在更新：${phase}`;
+			return "正在更新…";
+		}
+
+		function updateFailureLabel(failure) {
+			const labels = {
+				AGENTS_RUNNING: "有任务正在运行，请结束后重试",
+				OPERATION_BUSY: "插件市场正在处理其他任务",
+				RELEASE_TOO_FRESH: "新版本仍在镜像同步",
+				VERSION_UNCHANGED: "下载后版本未变化",
+				DOWNGRADE_DETECTED: "已阻止版本降级",
+				RESOLVED_VERSION_MISMATCH: "下载版本与预期不一致",
+				INVALID_UPDATE_RESULT: "更新服务未返回有效版本",
+				UPDATE_TIMEOUT: "更新超时",
+				UPDATE_FORBIDDEN: "更新请求被拒绝",
+				UPDATE_REJECTED: "无法执行本次更新"
+			};
+			return labels[failure?.code] ?? failure?.message ?? "更新失败";
+		}
+
+		function parseClientVersion(value) {
+			if (typeof value !== "string") return null;
+			const normalized = value.trim().replace(/^v/i, "");
+			if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(normalized)) return null;
+			const [withoutBuild] = normalized.split("+");
+			const [core, prerelease] = withoutBuild.split("-", 2);
+			return { normalized, core: core.split(".").map(Number), prerelease: prerelease?.split(".") ?? [] };
+		}
+
+		function compareClientVersions(left, right) {
+			const a = parseClientVersion(left);
+			const b = parseClientVersion(right);
+			if (a === null || b === null) return null;
+			for (let index = 0; index < 3; index += 1) {
+				if (a.core[index] !== b.core[index]) return a.core[index] - b.core[index];
+			}
+			if (a.prerelease.length === 0 && b.prerelease.length > 0) return 1;
+			if (a.prerelease.length > 0 && b.prerelease.length === 0) return -1;
+			const length = Math.max(a.prerelease.length, b.prerelease.length);
+			for (let index = 0; index < length; index += 1) {
+				const aPart = a.prerelease[index];
+				const bPart = b.prerelease[index];
+				if (aPart === void 0) return -1;
+				if (bPart === void 0) return 1;
+				if (aPart === bPart) continue;
+				const aNumeric = /^\d+$/.test(aPart);
+				const bNumeric = /^\d+$/.test(bPart);
+				if (aNumeric && bNumeric) return Number(aPart) - Number(bPart);
+				if (aNumeric) return -1;
+				if (bNumeric) return 1;
+				return aPart.localeCompare(bPart);
+			}
+			return 0;
+		}
+
+		/** Independently verify a provider's terminal success before asking the user to restart. */
+		function completedUpdateIntegrityFailure(operation, expectedVersion) {
+			if (operation?.state !== "succeeded") return null;
+			const installed = parseClientVersion(operation.installedVersion);
+			if (installed === null) {
+				return {
+					code: "INVALID_UPDATE_RESULT",
+					message: "更新服务报告成功，但未返回有效的已安装版本",
+					retryable: false
+				};
+			}
+			const before = parseClientVersion(operation.beforeVersion);
+			if (before !== null && compareClientVersions(installed.normalized, before.normalized) < 0) {
+				return {
+					code: "DOWNGRADE_DETECTED",
+					message: `更新服务将插件从 v${before.normalized} 降级到 v${installed.normalized}`,
+					retryable: false
+				};
+			}
+			const expected = parseClientVersion(expectedVersion);
+			if (expected !== null && compareClientVersions(installed.normalized, expected.normalized) !== 0) {
+				return {
+					code: "RESOLVED_VERSION_MISMATCH",
+					message: `预期安装 v${expected.normalized}，更新服务实际安装了 v${installed.normalized}`,
+					retryable: true
+				};
+			}
+			return null;
+		}
+
 		/**
 		 * DSH 暂未公开“打开指定设置分区”服务：只依赖稳定的 sidebar.settings
 		 * slot 和可访问文本打开插件市场，不依赖构建生成的 CSS 类名。
@@ -258,6 +516,15 @@ window.__ModuleLoader__.load({
 			const open = useStore((state) => state.open);
 			const detailOpen = useStore((state) => state.detailOpen);
 			const [versionStatus, setVersionStatus] = (0, react.useState)(null);
+			const [updateProviderState, setUpdateProviderState] = (0, react.useState)("checking");
+			const [updateProviderSelection, setUpdateProviderSelection] = (0, react.useState)(null);
+			const [providerUpdateCheck, setProviderUpdateCheck] = (0, react.useState)(null);
+			const [expectedUpdateVersion, setExpectedUpdateVersion] = (0, react.useState)(null);
+			const [updateOperation, setUpdateOperation] = (0, react.useState)(null);
+			const [updateError, setUpdateError] = (0, react.useState)(null);
+			const [updateStarting, setUpdateStarting] = (0, react.useState)(false);
+			const [rollbackRunning, setRollbackRunning] = (0, react.useState)(false);
+			const [restarting, setRestarting] = (0, react.useState)(false);
 			const frameRef = (0, react.useRef)(null);
 			const closeRef = (0, react.useRef)(null);
 			(0, react.useEffect)(() => {
@@ -328,6 +595,93 @@ window.__ModuleLoader__.load({
 					window.clearTimeout(pollTimer);
 				};
 			}, [open]);
+			(0, react.useEffect)(() => {
+				if (!open) return void 0;
+				let disposed = false;
+				setUpdateProviderState("checking");
+				discoverUpdateProvider(PLUGIN_PACKAGE_NAME, true).then((selection) => {
+					if (disposed) return;
+					if (selection === null) {
+						setUpdateProviderSelection(null);
+						setProviderUpdateCheck(null);
+						setUpdateProviderState("unavailable");
+						return;
+					}
+					setUpdateProviderSelection(selection);
+					setProviderUpdateCheck(selection.update);
+					setUpdateProviderState("ready");
+				}).catch((error) => {
+					console.warn("[mcp-connector] update provider discovery failed:", error);
+					if (disposed) return;
+					setUpdateProviderSelection(null);
+					setProviderUpdateCheck(null);
+					setUpdateProviderState("unavailable");
+				});
+				return () => { disposed = true; };
+			}, [open]);
+			(0, react.useEffect)(() => {
+				const operationId = updateOperation?.operationId;
+				const provider = updateProviderSelection?.provider;
+				const capabilities = updateProviderSelection?.capabilities;
+				if (!open || provider === void 0 || capabilities === void 0
+					|| typeof operationId !== "string" || !["queued", "running"].includes(updateOperation.state)) {
+					return void 0;
+				}
+				let disposed = false;
+				let timer;
+				const poll = () => {
+					provider.operation(capabilities, operationId).then((operation) => {
+						if (disposed) return;
+						setUpdateError(null);
+						const integrityFailure = completedUpdateIntegrityFailure(operation, expectedUpdateVersion);
+						if (integrityFailure !== null) {
+							const failedOperation = { ...operation, state: "failed", failure: integrityFailure };
+							setUpdateOperation(failedOperation);
+							const canRollback = capabilities.features?.rollback === true
+								&& operation.outcome?.rollback?.available === true
+								&& capabilities.endpoints.rollback !== null;
+							if (!canRollback) return;
+							setRollbackRunning(true);
+							provider.rollback(capabilities, operationId).then((rolledBackOperation) => {
+								if (disposed) return;
+								setRollbackRunning(false);
+								setUpdateOperation({ ...rolledBackOperation, integrityFailure });
+							}, (error) => {
+								console.error("[mcp-connector] automatic rollback failed:", error);
+								if (disposed) return;
+								const detail = error instanceof Error ? error.message : String(error);
+								setRollbackRunning(false);
+								setUpdateOperation({
+									...failedOperation,
+									outcome: {
+										...failedOperation.outcome,
+										rollback: { available: true, state: "failed", detail }
+									}
+								});
+							});
+							return;
+						}
+						setUpdateOperation(operation);
+						if (["queued", "running"].includes(operation.state)) {
+							timer = window.setTimeout(poll, UPDATE_PROVIDER_OPERATION_POLL_MS);
+							return;
+						}
+						if (operation.state === "succeeded") {
+							provider.check(capabilities, PLUGIN_PACKAGE_NAME, true).then(setProviderUpdateCheck, () => {});
+						}
+					}, (error) => {
+						console.warn("[mcp-connector] update operation polling failed:", error);
+						if (disposed) return;
+						setUpdateError(error instanceof Error ? error.message : String(error));
+						timer = window.setTimeout(poll, UPDATE_PROVIDER_OPERATION_POLL_MS * 2);
+					});
+				};
+				timer = window.setTimeout(poll, UPDATE_PROVIDER_OPERATION_POLL_MS);
+				return () => {
+					disposed = true;
+					window.clearTimeout(timer);
+				};
+			}, [open, updateOperation?.operationId, updateProviderSelection?.provider?.id, expectedUpdateVersion]);
 			(0, react.useEffect)(() => {
 				if (!open) return void 0;
 				closeRef.current?.focus?.();
@@ -336,6 +690,206 @@ window.__ModuleLoader__.load({
 				return () => { window.removeEventListener("keydown", onKeyDown); };
 			}, [open, actions]);
 			if (!open) return null;
+			const updateRunning = updateStarting || updateOperation !== null && ["queued", "running"].includes(updateOperation.state);
+			const startUpdate = (force = false) => {
+				const provider = updateProviderSelection?.provider;
+				const capabilities = updateProviderSelection?.capabilities;
+				if (updateRunning || provider === void 0 || capabilities === void 0) return;
+				setUpdateError(null);
+				setUpdateStarting(true);
+				setExpectedUpdateVersion(providerUpdateCheck?.latestVersion ?? versionStatus?.latestVersion ?? null);
+				provider.start(capabilities, PLUGIN_PACKAGE_NAME, force).then((operation) => {
+					setUpdateStarting(false);
+					setUpdateOperation(operation);
+				}, (error) => {
+					console.error("[mcp-connector] update start failed:", error);
+					setUpdateStarting(false);
+					if (error?.retryable === true) {
+						setUpdateOperation({
+							state: "failed",
+							failure: {
+								code: error.code ?? "UPDATE_FAILED",
+								message: error instanceof Error ? error.message : String(error),
+								retryable: true
+							},
+							outcome: { rollback: { available: false, state: "unavailable" } }
+						});
+					} else {
+						setUpdateError(error instanceof Error ? error.message : String(error));
+					}
+				});
+			};
+			const rollbackUpdate = () => {
+				const provider = updateProviderSelection?.provider;
+				const capabilities = updateProviderSelection?.capabilities;
+				if (rollbackRunning || provider === void 0 || capabilities === void 0
+					|| typeof updateOperation?.operationId !== "string") return;
+				setUpdateError(null);
+				setRollbackRunning(true);
+				provider.rollback(capabilities, updateOperation.operationId).then((operation) => {
+					setRollbackRunning(false);
+					setUpdateOperation(operation);
+				}, (error) => {
+					console.error("[mcp-connector] rollback failed:", error);
+					setRollbackRunning(false);
+					setUpdateError(error instanceof Error ? error.message : String(error));
+				});
+			};
+			const restartHost = () => {
+				const provider = updateProviderSelection?.provider;
+				const capabilities = updateProviderSelection?.capabilities;
+				if (restarting || provider === void 0 || capabilities === void 0) return;
+				setRestarting(true);
+				setUpdateError(null);
+				provider.restart(capabilities).catch((error) => {
+					console.error("[mcp-connector] restart failed:", error);
+					setRestarting(false);
+					setUpdateError(error instanceof Error ? error.message : String(error));
+				});
+			};
+			const renderUpdateControls = () => {
+				if (!versionStatus?.updateAvailable && updateOperation === null && updateError === null) return null;
+				if (updateRunning) {
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "mcpConnectorUpdateControls",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton",
+								disabled: true,
+								children: updateStarting ? "正在启动更新…" : updateProgressLabel(updateOperation)
+							}),
+							updateError !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								"data-tone": "error",
+								title: updateError,
+								children: "暂时无法读取进度，正在重试"
+							})
+						]
+					});
+				}
+				if (updateOperation?.state === "failed") {
+					const force = ["RELEASE_TOO_FRESH", "VERSION_UNCHANGED"].includes(updateOperation.failure?.code);
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "mcpConnectorUpdateControls",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								"data-tone": "error",
+								title: updateOperation.failure?.message ?? "更新失败",
+								children: updateFailureLabel(updateOperation.failure)
+							}),
+							updateOperation.failure?.retryable && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton",
+								onClick: () => startUpdate(force),
+								children: force ? "强制重试" : "重试更新"
+							}),
+							rollbackRunning && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								children: "检测到异常版本，正在自动回滚…"
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton mcpConnectorUpdateSecondary",
+								onClick: () => openDshPluginMarket(actions),
+								children: "打开插件市场"
+							})
+						]
+					});
+				}
+				if (["succeeded", "rolled-back"].includes(updateOperation?.state)) {
+					const rolledBack = updateOperation.state === "rolled-back";
+					const restartRequired = updateOperation.outcome?.restartRequired === true;
+					const refreshRequired = updateOperation.outcome?.refreshRequired === true;
+					const rollbackFailed = updateOperation.outcome?.rollback?.state === "failed";
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "mcpConnectorUpdateControls",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								children: rolledBack
+									? updateOperation.integrityFailure === void 0 ? "已回滚" : "已阻止异常版本并回滚"
+									: `已安装 v${updateOperation.installedVersion ?? versionStatus?.latestVersion}`
+							}),
+							rollbackFailed && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								"data-tone": "error",
+								title: updateOperation.outcome.rollback.detail ?? "回滚失败",
+								children: "回滚失败"
+							}),
+						restartRequired && updateProviderSelection?.capabilities?.restart?.supported === true && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton",
+								disabled: restarting,
+								onClick: restartHost,
+								children: restarting ? "正在重启…" : "立即重启"
+							}),
+						restartRequired && updateProviderSelection?.capabilities?.restart?.supported !== true && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "mcpConnectorUpdateStatus",
+							title: `重启由 ${updateProviderSelection?.capabilities?.restart?.managedBy ?? "宿主"} 管理`,
+							children: updateProviderSelection?.capabilities?.runtime === "desktop" ? "请重启 DSH Desktop" : "请重启 DSH"
+							}),
+							!restartRequired && refreshRequired && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton",
+								onClick: () => window.location.reload(),
+								children: "刷新生效"
+							}),
+							updateOperation.outcome?.rollback?.available === true && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton mcpConnectorUpdateSecondary",
+								disabled: rollbackRunning,
+								onClick: rollbackUpdate,
+								children: rollbackRunning ? "正在回滚…" : rollbackFailed ? "重试回滚" : "回滚"
+							})
+						]
+					});
+				}
+				if (updateError !== null) {
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "mcpConnectorUpdateControls",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								"data-tone": "error",
+								title: updateError,
+								children: "更新服务调用失败"
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "mcpConnectorUpdateButton mcpConnectorUpdateSecondary",
+								onClick: () => openDshPluginMarket(actions),
+								children: "打开插件市场"
+							})
+						]
+					});
+				}
+				if (updateProviderState === "checking") {
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: "mcpConnectorUpdateButton",
+						disabled: true,
+						children: "正在准备更新…"
+					});
+				}
+				if (updateProviderState === "ready" && providerUpdateCheck?.updateAvailable === true) {
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: "mcpConnectorUpdateButton",
+						title: `由 ${updateProviderSelection?.provider?.label ?? "更新服务"} 安全更新到 v${providerUpdateCheck.latestVersion}`,
+						onClick: () => startUpdate(false),
+						children: `一键更新到 v${providerUpdateCheck.latestVersion}`
+					});
+				}
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+					type: "button",
+					className: "mcpConnectorUpdateButton",
+					title: `npm 已发布 v${versionStatus?.latestVersion}`,
+					onClick: () => openDshPluginMarket(actions),
+					children: `前往插件市场更新到 v${versionStatus?.latestVersion}`
+				});
+			};
 			const src = window.location.origin + "/mcp-connector/ui/";
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				style: {
@@ -379,7 +933,7 @@ window.__ModuleLoader__.load({
 								},
 								children: [
 									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-										style: { display: "flex", alignItems: "center", gap: 10 },
+									style: { display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap", minWidth: 0, flex: 1 },
 										children: [
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: { fontSize: 22 }, children: "\u{1F9E9}" }),
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { id: "mcp-connector-market-title", className: "mcpConnectorMarketTitle", style: { fontSize: 18, fontWeight: 600 }, children: "MCP连接器" }),
@@ -388,13 +942,7 @@ window.__ModuleLoader__.load({
 												title: versionStatus === null ? "正在检查插件版本" : `当前版本 v${versionStatus.installedVersion}`,
 												children: versionStatus === null ? "v…" : `v${versionStatus.installedVersion}`
 											}),
-											versionStatus?.updateAvailable && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-												type: "button",
-												className: "mcpConnectorUpdateButton",
-												title: `npm 已发布 v${versionStatus.latestVersion}`,
-												onClick: () => openDshPluginMarket(actions),
-												children: `前往插件市场更新到 v${versionStatus.latestVersion}`
-											}),
+											renderUpdateControls(),
 											versionStatus?.releasePending && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 												className: "mcpConnectorVersion",
 												title: "GitHub Release 已发布，等待 npm 同步后即可更新",

package/lib/index.js

@@ -380,12 +380,41 @@ export async function apply(ctx, config) {
   }
 
   async function refreshGrantWithRecovery(grantKey, phase) {
+    const observed = state.grants.get(grantKey)?.grant;
     try {
       return await refreshGrant(grantKey);
     } catch (error) {
+      let finalError = error;
+      const initialFailure = classifyRefreshFailure(error);
+      // Refresh tokens are commonly rotated. If another DSH process refreshed
+      // the same persisted grant first, this process still holds the old token
+      // and receives invalid_grant. Re-read storage before declaring the user
+      // logged out; a newer token is authoritative and can be retried once.
+      if (config.persistSecrets && observed
+          && ['invalid_grant', 'invalid_token'].includes(initialFailure.code)) {
+        for (const delayMs of [0, 100, 250]) {
+          if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+          const persisted = await grantStore.get(grantKey).catch(() => undefined);
+          const entry = state.grants.get(grantKey);
+          if (!entry || !persisted
+              || persisted.updatedAt <= observed.updatedAt
+              || persisted.refreshToken === observed.refreshToken) continue;
+          entry.grant = persisted;
+          entry.needsReauth = false;
+          entry.refreshFailureKind = null;
+          entry.lastRefreshError = null;
+          logger.info(`OAuth grant ${grantKey} adopted a newer persisted token after a concurrent rotation`);
+          try {
+            return await refreshGrant(grantKey);
+          } catch (retryError) {
+            finalError = retryError;
+          }
+          break;
+        }
+      }
       // 多个调用方可能等待同一个 refreshPromise；同一次失败只能记一次并调度一个重试。
-      if (!error.refreshFailure) error.refreshFailure = recordRefreshFailure(grantKey, error, phase);
-      throw error;
+      if (!finalError.refreshFailure) finalError.refreshFailure = recordRefreshFailure(grantKey, finalError, phase);
+      throw finalError;
     }
   }
 
@@ -858,6 +887,86 @@ export async function apply(ctx, config) {
     }
   }
 
+  /**
+   * v0.2.22 及更早版本会让四张企查查卡片分别保存动态客户端和 Grant。
+   * 新版升级时把同 issuer、同资源域且授权范围完整的历史记录归并为一组，
+   * 这样启动只刷新一个 refresh token，之后任意一张卡片重新授权也会修复整组。
+   */
+  async function consolidatePersistedSharedGrants() {
+    const groups = new Map();
+    for (const record of state.connections.values()) {
+      if (record.auth?.mode !== 'oauth' || !record.auth.grantKey) continue;
+      const connector = state.merged.find((item) => item.id === record.connectorId);
+      if (connector?.auth?.grantSharing !== 'issuer') continue;
+      const groupKey = oauthSharingKey(connector);
+      const group = groups.get(groupKey) ?? { records: [], grantKeys: new Set() };
+      group.records.push(record);
+      group.grantKeys.add(record.auth.grantKey);
+      groups.set(groupKey, group);
+    }
+
+    let consolidated = 0;
+    for (const group of groups.values()) {
+      if (group.grantKeys.size <= 1) continue;
+      const requiredResources = new Set(group.records.map((record) => record.url).filter(Boolean));
+      const candidates = [...group.grantKeys]
+        .map((key) => [key, state.grants.get(key)])
+        .filter(([, entry]) => entry
+          && [...requiredResources].every((resource) => entry.grant.authorizedResources.includes(resource)))
+        .sort((left, right) => (
+          (right[1].grant.updatedAt ?? 0) - (left[1].grant.updatedAt ?? 0)
+          || (right[1].grant.accessTokenExpiresAt ?? 0) - (left[1].grant.accessTokenExpiresAt ?? 0)
+        ));
+      if (candidates.length === 0) continue;
+
+      // Do not retire three recoverable historical grants in favour of a newer
+      // but already-revoked refresh token. Validate expired candidates in
+      // recency order and only consolidate after one grant is demonstrably
+      // usable. If none is usable, preserve every grant so one subsequent
+      // authorization can replace the group without destroying recovery data.
+      let winnerCandidate;
+      for (const candidate of candidates) {
+        const [candidateKey, candidateEntry] = candidate;
+        if (candidateEntry.needsReauth) continue;
+        if (candidateEntry.grant.accessTokenExpiresAt <= Date.now()) {
+          try {
+            await refreshGrantWithRecovery(candidateKey, 'startup-consolidation');
+          } catch {
+            continue;
+          }
+        }
+        winnerCandidate = candidate;
+        break;
+      }
+      if (winnerCandidate === undefined) {
+        logger.warn(`preserved ${group.grantKeys.size} historical issuer-shared OAuth grants because none could be refreshed`);
+        continue;
+      }
+
+      const [winnerKey, winnerEntry] = winnerCandidate;
+      const connectorIds = [...new Set([
+        ...(winnerEntry.grant.connectorIds ?? []),
+        ...group.records.map((record) => record.connectorId),
+      ])];
+      const winner = { ...winnerEntry.grant, connectorIds, updatedAt: Date.now() };
+      winnerEntry.grant = winner;
+      if (config.persistSecrets) await grantStore.put(winner);
+
+      for (const record of group.records) {
+        if (record.auth.grantKey === winnerKey) continue;
+        const next = { ...record, auth: { ...record.auth, grantKey: winnerKey }, updatedAt: Date.now() };
+        const persisted = config.persistSecrets ? await connectionStore.put(next) : next;
+        state.connections.set(record.key, persisted);
+      }
+      for (const losingKey of group.grantKeys) {
+        if (losingKey !== winnerKey) await retireGrantIfUnused(losingKey);
+      }
+      consolidated += group.grantKeys.size - 1;
+      logger.info(`consolidated ${group.grantKeys.size} issuer-shared OAuth grants into ${winnerKey}`);
+    }
+    return consolidated;
+  }
+
   /* ───────────────────────── api 门面 ───────────────────────── */
 
   const api = {
@@ -1612,6 +1721,9 @@ export async function apply(ctx, config) {
     }
   }
 
+  const consolidatedGrantCount = await consolidatePersistedSharedGrants();
+  if (consolidatedGrantCount > 0) logger.info(`consolidated ${consolidatedGrantCount} historical OAuth grant(s) during startup`);
+
   const prunedGrantCount = await pruneOrphanGrants();
   if (prunedGrantCount > 0) logger.info(`removed ${prunedGrantCount} unreferenced OAuth grant(s) from local storage`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "General-purpose MCP connector, connection manager, plugin extension, and integration marketplace for DeepSeek Harness, initiated and maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",
@@ -19,6 +19,7 @@
     "registry",
     "docs/DESKTOP-E2E.md",
     "docs/MARKET-REGISTRATION.md",
+    "docs/PLUGIN-UPDATE.md",
     "docs/STDIO-SUPPORT.md",
     "docs/USER-GUIDE.md",
     "cordis.patch.yml",