dsh-mcp-connector 0.2.22 → 0.2.24

package/CHANGELOG.md

@@ -4,6 +4,33 @@
 
 ## [Unreleased]
 
+## [0.2.24] - 2026-08-27
+
+### Added
+
+- MCP连接器标题显示当前插件版本，并由服务端缓存检查 npm `latest` 与 GitHub Release；发现新版本时引导用户前往 DSH 插件市场安全更新。
+
+### Changed
+
+- 市场页原“刷新”按钮改为“刷新连接器目录”，明确该操作仅更新 Registry 卡片，不会升级插件本身。
+
+### Verification
+
+- 123 项自动测试、lint、npm 发布包白名单/敏感内容扫描和 npm/GitHub 真实版本源验收通过。
+
+## [0.2.23] - 2026-08-26
+
+### Fixed
+
+- OAuth Grant 现在保存 Access Token 的真实过期时间，并在提前刷新遇到网络、发现端点或服务端暂时故障时采用有上限的指数退避自动恢复；只有 `invalid_grant`、`invalid_client` 等明确不可恢复错误才显示“需重新授权”。
+- 启动恢复不再吞掉 Token 刷新异常；脱敏日志会记录阶段、OAuth 错误码、HTTP 状态与永久/暂时分类，且不会输出 Access Token、Refresh Token 或客户端密钥。
+- `grantSharing: "issuer"` 正式生效：同账号、同 issuer/scope 的卡片共享动态客户端与 Grant，后续连接同组卡片不再重复打开授权页；重新授权会把同组已连接卡片迁移到新 Grant。
+- 启动和连接前检测仍启用的 `qcc-mcp-oauth` / `qcc-legal-mcp-oauth` 及其残留 mcp-client 条目；发现同名 Server 时阻断新连接，避免旧 Token 覆盖新连接器凭据。
+
+### Verification
+
+- 新增 OAuth 刷新失败分类/脱敏/退避、暂时故障自动恢复、永久失效重新授权、同 issuer 顺序与并发共享授权、旧插件冲突阻断回归测试。
+
 ## [0.2.22] - 2026-08-26
 
 ### Fixed
@@ -372,7 +399,9 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.22...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.24...HEAD
+[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
 [0.2.21]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.20...v0.2.21
 [0.2.20]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.19...v0.2.20

package/README.en.md

@@ -25,10 +25,11 @@ Browse and install MCP connectors from different providers in DeepSeek Harness D
 - Credential and MCP initialize validation before HTTP API-key connectors are saved as installed, plus declarative multi-field credential-to-env bindings for marketplace stdio connectors.
 - Dynamic tool discovery grouped by MCP server, including descriptions, search, batched rendering, and an independent scroll region.
 - Curated prompt templates that can open a DSH conversation and prefill its draft; missing variables are requested before the prompt is sent.
-- Persistent connection lifecycle management: restore on restart, enable/disable, disconnect, refresh OAuth tokens, and revoke authorization. DCR client secrets are kept with the local grant only.
+- 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.
-- Explicit, non-destructive migration of authorization from the two earlier Qichacha OAuth plugins.
+- 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.
+- 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 -->
 As of 2026-08-25, the public Registry publishes 78 connector descriptors. After merging and deduplicating them with the 4 bundled Qichacha cards, the Marketplace exposes 82 cards across 9 business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for 6 featured cards in total. The Registry evolves independently; the badge shown after a client refresh and the live badges above are the authoritative current counts.
@@ -111,7 +112,7 @@ npm run dev:ui
 
 Every Registry merge regenerates `catalog-stats.json`; an hourly workflow in this repository synchronizes the Chinese and English product copy plus a local stats snapshot. The static npm README updates with package releases, while the live badges above read the Registry directly and therefore stay current without another npm release.
 
-The current public version is [`dsh-mcp-connector@0.2.22`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.22](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.22).
+The current public version is [`dsh-mcp-connector@0.2.24`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.24](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.24).
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md) for the Desktop release checklist.
 

package/README.md

@@ -25,11 +25,12 @@
 - Prompt 模板：使用 `{{company}}` 等变量，发送前填写真实查询主体。
 - 三种接入：OAuth 2.0 PKCE、自定义 HTTP/stdio、导入 `mcpServers` JSON；也支持从连接器描述 URL 安装。OAuth 动态注册兼容公共客户端以及 `client_secret_post` / `client_secret_basic` 机密客户端。
 - 市场 Bearer/API Key 连接器先执行 MCP initialize 连通性与凭据校验，全部 HTTP Server 通过后才持久化凭据并进入“已安装”；stdio 卡片可声明多个本机凭据字段及其环境变量映射。
-- 生命周期管理：连接持久化、重启恢复、启停、断开、OAuth 刷新与撤销；DCR 返回的客户端密钥与 Token 一同只保存在本机。
+- 生命周期管理：连接持久化、重启恢复、启停、断开、OAuth 自动刷新/退避恢复与撤销；同 issuer 卡片可共享一次授权，DCR 返回的客户端密钥与 Token 一同只保存在本机。
 - 目录运营：内置目录、远程 registry、本地覆盖，支持 `published` 上下架与 `featured` 精选。
 - 独立远程 Registry：新市场卡片合并后客户端刷新即可见，无需重新发布 npm；远程不可用时自动回退内置目录。
+- 插件版本感知：MCP连接器标题显示当前版本，服务端缓存检查 npm 与 GitHub Release；发现 npm 新版本时引导到 DSH 插件市场更新。
 - Registry 工具链：Schema/唯一性/密钥审计、MCP/OAuth 无凭据探针、每周健康巡检。
-- 平滑迁移：显式扫描并复制两个旧企查查 OAuth 插件授权；不删除原插件或原凭据。
+- 平滑迁移：显式扫描并复制两个旧企查查 OAuth 插件授权；检测到旧插件仍启用并管理同名 Server 时阻断重复连接，避免凭据相互覆盖。
 - 对话工具：`mcp_connector_catalog`、`connect`、`configure`、`import_json`、`install_from_url`、`status`、`health_check`、`set_enabled`、`disconnect`、`refresh_catalog`、`publish`、`tools_list`。
 
 <!-- catalog-stats:start -->
@@ -106,7 +107,7 @@ npm run dev:ui
 
 公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.22`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.22](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.22)。
+当前公开版本为 [`dsh-mcp-connector@0.2.24`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.24](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.24)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/docs/USER-GUIDE.md

@@ -42,7 +42,8 @@ dsh web
 - **已安装**：查看已经保存到本机的连接，页签徽标显示连接数。
 - **搜索**：按名称、服务商、简介和标签查找。
 - **添加连接**：导入 JSON、手动配置 HTTP/stdio，或从市场描述 URL 安装。
-- **刷新**：重新拉取目录，并更新连接健康状态。
+- **版本与更新提示**：标题旁显示当前插件版本。检测到 npm 有新版本时，点击更新提示前往 DSH 插件市场执行安全升级；升级后按页面提示完全重启 DSH。
+- **刷新连接器目录**：重新拉取 Registry 卡片，并更新连接健康状态；该操作不会升级 MCP连接器插件本身。
 
 ## 3. 浏览市场与分类
 
@@ -63,7 +64,8 @@ dsh web
 | `连接` | OAuth 或免密连接器尚未连接 | 点击后按页面提示完成授权或连通性检查 |
 | `配置` | 需要 Bearer Token 或 API Key | 录入服务商签发的凭据并验证 |
 | `需重新授权` | OAuth 授权过期、被撤销或不可用 | 点击后重新完成 OAuth 授权 |
-| `已配置` | 本机已有配置，尚未完成本轮健康确认 | 点击“刷新”或进入详情检查 |
+| `自动重试中` | OAuth Token 刷新遇到网络或服务端暂时故障 | 无需重新授权；保持 DSH 运行，插件会按退避策略自动恢复 |
+| `已配置` | 本机已有配置，尚未完成本轮健康确认 | 点击“刷新连接器目录”或进入详情检查 |
 | `已连接` | 最近一次健康检查通过 | 可直接在会话中使用对应 MCP 工具 |
 | `部分异常` / `连接异常` | 一个或多个 Server 未通过检查 | 打开详情查看提示，核对网络、权限和服务状态 |
 
@@ -73,6 +75,8 @@ 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/客户端失效错误时才进入“需重新授权”。
+
 ## 5. 查看详情、Prompt 与工具
 
 点击卡片或“详情”可打开连接器详情：
@@ -137,7 +141,7 @@ stdio 进程由 `@deepseek-ai/dsh-mcp-client` 管理，插件透传 `command`、
 - 执行健康检查；
 - 断开连接并删除该连接的本机配置。
 
-OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端点时仍会删除 DSH 本机授权记录。连接状态发生变化后，可点击“刷新”重新检查。
+OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端点时仍会删除 DSH 本机授权记录。连接状态发生变化后，可点击“刷新连接器目录”重新检查。
 
 ## 8. 安全边界
 
@@ -157,7 +161,7 @@ OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端
 
 ### 市场里没有最新卡片
 
-点击“刷新”。如果远程 Registry 暂时不可用，页面会继续显示缓存或内置目录；稍后恢复网络再刷新即可。
+点击“刷新连接器目录”。如果远程 Registry 暂时不可用，页面会继续显示缓存或内置目录；稍后恢复网络再刷新即可。
 
 ### Token/API Key 一直验证失败
 

package/lib/client.js

@@ -19,6 +19,9 @@ window.__ModuleLoader__.load({
 		];
 		const PROMPT_REQUEST_TYPE = "mcp-connector:start-session";
 		const PROMPT_RESULT_TYPE = "mcp-connector:start-session-result";
+		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";
 
 		/**
 		 * Desktop 内置的社区插件市场也注册在 sidebar.footer.action。
@@ -86,6 +89,31 @@ window.__ModuleLoader__.load({
 .mcpConnectorMarketPanel { background: #ffffff; color: #111827; }
 .mcpConnectorMarketHeader { border-color: #e5e7eb; }
 .mcpConnectorMarketTitle { color: #111827; }
+.mcpConnectorVersion {
+	color: #6b7280;
+	background: #f3f4f6;
+	border-radius: 999px;
+	padding: 2px 8px;
+	font-size: 12px;
+	font-weight: 600;
+}
+.mcpConnectorUpdateButton {
+	color: #4338ca;
+	background: #eef2ff;
+	border: 1px solid #c7d2fe;
+	border-radius: 8px;
+	padding: 5px 9px;
+	font: inherit;
+	font-size: 12px;
+	font-weight: 600;
+	cursor: pointer;
+}
+.mcpConnectorUpdateButton:hover,
+.mcpConnectorUpdateButton:focus-visible {
+	background: #e0e7ff;
+	outline: 2px solid #6366f1;
+	outline-offset: 1px;
+}
 .mcpConnectorMarketClose { color: #6b7280; }
 .mcpConnectorMarketClose:hover,
 .mcpConnectorMarketClose:focus-visible {
@@ -99,6 +127,10 @@ window.__ModuleLoader__.load({
 	.mcpConnectorMarketPanel { background: #1b1e25; color: #f3f4f6; }
 	.mcpConnectorMarketHeader { border-color: #30343d; }
 	.mcpConnectorMarketTitle { color: #f3f4f6; }
+	.mcpConnectorVersion { color: #d1d5db; background: #30343d; }
+	.mcpConnectorUpdateButton { color: #c7d2fe; background: #312e81; border-color: #4f46e5; }
+	.mcpConnectorUpdateButton:hover,
+	.mcpConnectorUpdateButton:focus-visible { background: #3730a3; }
 	.mcpConnectorMarketClose { color: #c4c8d0; }
 	.mcpConnectorMarketClose:hover,
 	.mcpConnectorMarketClose:focus-visible { background: #30343d !important; color: #ffffff; }
@@ -135,6 +167,50 @@ window.__ModuleLoader__.load({
 			return mount;
 		}
 
+		async function fetchVersionStatus() {
+			const response = await window.fetch("/mcp-connector/api", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ method: "versionStatus", params: {} })
+			});
+			const result = await response.json();
+			if (!response.ok || result.ok !== true || result.detail === void 0) {
+				throw new Error(result.message ?? `HTTP ${response.status}`);
+			}
+			return result.detail;
+		}
+
+		/**
+		 * DSH 暂未公开“打开指定设置分区”服务：只依赖稳定的 sidebar.settings
+		 * slot 和可访问文本打开插件市场，不依赖构建生成的 CSS 类名。
+		 */
+		function openDshPluginMarket(actions) {
+			const settingsHost = document.querySelector('[data-slot="sidebar.settings"]');
+			const settingsTrigger = settingsHost?.querySelector?.('button[aria-haspopup="dialog"]');
+			if (settingsTrigger === null || settingsTrigger === void 0) {
+				window.open(NPM_PACKAGE_URL, "_blank", "noopener,noreferrer");
+				return;
+			}
+			actions.close();
+			window.setTimeout(() => {
+				settingsTrigger.click();
+				let attempts = 0;
+				const selectMarket = () => {
+					const marketButton = [...document.querySelectorAll('[role="dialog"] nav button')].find((button) => {
+						const label = button.textContent?.trim() ?? "";
+						return /^(\u63d2\u4ef6\u5e02\u573a|Plugin Market|Plugin Marketplace)$/i.test(label);
+					});
+					if (marketButton !== void 0) {
+						marketButton.click();
+						return;
+					}
+					attempts += 1;
+					if (attempts < 20) window.setTimeout(selectMarket, 50);
+				};
+				window.requestAnimationFrame(selectMarket);
+			}, 0);
+		}
+
 		/** 创建弹框 store（使用 DSH defineStore，与社区插件市场一致）。 */
 		function createMarketViewStore() {
 			return (0, _deepseek_ai_dsh_client_runtime_client.defineStore)({
@@ -181,6 +257,7 @@ window.__ModuleLoader__.load({
 			const { wide, useStore, actions, startPromptSession: launchPromptSession } = props;
 			const open = useStore((state) => state.open);
 			const detailOpen = useStore((state) => state.detailOpen);
+			const [versionStatus, setVersionStatus] = (0, react.useState)(null);
 			const frameRef = (0, react.useRef)(null);
 			const closeRef = (0, react.useRef)(null);
 			(0, react.useEffect)(() => {
@@ -219,6 +296,38 @@ window.__ModuleLoader__.load({
 				window.addEventListener("message", onMessage);
 				return () => { window.removeEventListener("message", onMessage); };
 			}, [actions, launchPromptSession]);
+			(0, react.useEffect)(() => {
+				if (!open) return void 0;
+				let disposed = false;
+				let pollTimer;
+				const schedule = (delayMs) => {
+					window.clearTimeout(pollTimer);
+					pollTimer = window.setTimeout(check, Math.max(1e3, delayMs));
+				};
+				const check = () => {
+					fetchVersionStatus().then((status) => {
+						if (disposed) return;
+						setVersionStatus(status);
+						if (status.checking) {
+							schedule(1e3);
+							return;
+						}
+						const nextCheckAt = Date.parse(status.nextCheckAt ?? "");
+						const delay = Number.isFinite(nextCheckAt)
+							? Math.min(VERSION_CHECK_INTERVAL_MS, nextCheckAt - Date.now())
+							: VERSION_CHECK_INTERVAL_MS;
+						schedule(delay);
+					}, (error) => {
+						console.warn("[mcp-connector] plugin update check failed:", error);
+						if (!disposed) schedule(VERSION_CHECK_RETRY_MS);
+					});
+				};
+				check();
+				return () => {
+					disposed = true;
+					window.clearTimeout(pollTimer);
+				};
+			}, [open]);
 			(0, react.useEffect)(() => {
 				if (!open) return void 0;
 				closeRef.current?.focus?.();
@@ -273,7 +382,24 @@ window.__ModuleLoader__.load({
 										style: { display: "flex", alignItems: "center", gap: 10 },
 										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连接器" })
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { id: "mcp-connector-market-title", className: "mcpConnectorMarketTitle", style: { fontSize: 18, fontWeight: 600 }, children: "MCP连接器" }),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "mcpConnectorVersion",
+												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}`
+											}),
+											versionStatus?.releasePending && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "mcpConnectorVersion",
+												title: "GitHub Release 已发布，等待 npm 同步后即可更新",
+												children: `v${versionStatus.release.version} 正在同步`
+											})
 										]
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {

package/lib/connectors/oauth-connector.js

@@ -80,12 +80,19 @@ export async function oauthAuthorize({ connector, config, logger, signal }) {
   // 按 token 实际授权范围过滤 server；非 JWT / 无 resource claim 时 fallback 全部
   const grantedUrls = extractTokenResources(token.accessToken);
   let grantedKeys;
+  let grantedResources;
   if (grantedUrls) {
     const granted = new Set(grantedUrls);
-    grantedKeys = connector.servers.filter((s) => granted.has(s.url)).map((s) => s.serverKey);
-    if (grantedKeys.length === 0) grantedKeys = [entryServer.serverKey];
+    const grantedServers = connector.servers.filter((s) => granted.has(s.url));
+    grantedKeys = grantedServers.map((s) => s.serverKey);
+    grantedResources = grantedServers.map((s) => s.url);
+    if (grantedKeys.length === 0) {
+      grantedKeys = [entryServer.serverKey];
+      grantedResources = [entryServer.url];
+    }
   } else {
     grantedKeys = connector.servers.map((s) => s.serverKey);
+    grantedResources = connector.servers.map((s) => s.url);
   }
 
   return {
@@ -98,6 +105,7 @@ export async function oauthAuthorize({ connector, config, logger, signal }) {
     scope: connector.auth.scope,
     token,
     grantedKeys,
+    grantedResources,
     entryResource,
   };
 }

package/lib/constants.js

@@ -30,6 +30,9 @@ export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 /** 首次启动 MCP Server 并完成 initialize + tools/list 的最长等待时间 */
 export const DEFAULT_STARTUP_TIMEOUT_MS = 120_000;
 export const DEFAULT_REFRESH_SKEW_MS = 300_000;
+/** OAuth 刷新暂时失败后的指数退避范围。 */
+export const DEFAULT_REFRESH_RETRY_BASE_MS = 30_000;
+export const DEFAULT_REFRESH_RETRY_MAX_MS = 300_000;
 export const DEFAULT_CATALOG_TTL_MS = 3_600_000;
 
 /** PKCE 约束（RFC 7636） */

package/lib/grant-lifecycle.js

@@ -0,0 +1,47 @@
+/** OAuth Grant 刷新失败分类、日志脱敏与重试退避。 */
+
+const PERMANENT_REFRESH_CODES = new Set([
+  'invalid_grant',
+  'invalid_token',
+  'invalid_client',
+  'unauthorized_client',
+  'invalid_scope',
+  'client_secret_expired',
+  'missing_refresh_token',
+]);
+
+/** 防止 OAuth 服务端错误描述意外回显凭据。 */
+export function redactOAuthDetail(value) {
+  return String(value ?? '')
+    .replace(/\bBearer\s+[^\s,;]+/gi, 'Bearer [REDACTED]')
+    .replace(/([?&](?:access_token|refresh_token|client_secret|code)=)[^&#\s]*/gi, '$1[REDACTED]')
+    .replace(/((?:access_token|refresh_token|client_secret)\s*[=:]\s*)[^\s,;&}]+/gi, '$1[REDACTED]')
+    .slice(0, 500);
+}
+
+/**
+ * 只有明确表示 Refresh Token / 动态客户端不可恢复的 OAuth 错误才要求重新授权。
+ * 网络、发现端点、5xx、超时和未知服务端错误都按暂时故障自动重试。
+ */
+export function classifyRefreshFailure(error) {
+  const code = typeof error?.code === 'string' && error.code
+    ? redactOAuthDetail(error.code).slice(0, 80)
+    : error?.name === 'OAuthNetworkError' ? 'network_error' : 'refresh_failed';
+  const httpStatus = Number.isInteger(error?.httpStatus) ? error.httpStatus : undefined;
+  const permanent = PERMANENT_REFRESH_CODES.has(code) || httpStatus === 401 || httpStatus === 403;
+  return {
+    permanent,
+    kind: permanent ? 'permanent' : 'transient',
+    code,
+    httpStatus,
+    message: redactOAuthDetail(error?.message || code),
+  };
+}
+
+/** 指数退避：base、2×、4×……，封顶 max。failureCount 从 1 开始。 */
+export function refreshRetryDelay(failureCount, baseMs, maxMs) {
+  const base = Math.max(1_000, Number(baseMs) || 30_000);
+  const max = Math.max(base, Number(maxMs) || 300_000);
+  const exponent = Math.max(0, Math.min(20, Number(failureCount || 1) - 1));
+  return Math.min(max, base * (2 ** exponent));
+}