dsh-plugin-discovery 1.1.1 → 1.2.4

package/index.js

@@ -14,6 +14,90 @@ const DEFAULT_CATALOG_GITEE_URL =
 	"https://gitee.com/hjhcos/dsh-plugin-discovery/raw/main/data/recommended.json";
 const DEFAULT_CATALOG_GITHUB_URL =
 	"https://raw.githubusercontent.com/hjhcos/dsh-plugin-discovery/main/data/recommended.json";
+const SELF_PACKAGE_NAME = "dsh-plugin-discovery";
+const DEFAULT_SELF_PACKAGE_GITEE_URL =
+	"https://gitee.com/hjhcos/dsh-plugin-discovery/raw/main/package.json";
+const DEFAULT_SELF_PACKAGE_GITHUB_URL =
+	"https://raw.githubusercontent.com/hjhcos/dsh-plugin-discovery/main/package.json";
+
+function readLocalPackageMeta() {
+	try {
+		const raw = readFileSync(join(__dirname, "package.json"), "utf8");
+		const data = JSON.parse(raw);
+		return {
+			name: data.name || SELF_PACKAGE_NAME,
+			version: String(data.version || "0.0.0"),
+		};
+	} catch {
+		return { name: SELF_PACKAGE_NAME, version: "0.0.0" };
+	}
+}
+
+function parseSemverParts(version) {
+	const cleaned = String(version || "0")
+		.trim()
+		.replace(/^v/i, "")
+		.split("-")[0]
+		.split("+")[0];
+	return cleaned.split(".").map((part) => {
+		const n = Number.parseInt(part, 10);
+		return Number.isFinite(n) ? n : 0;
+	});
+}
+
+/** @returns {number} 1 if a>b, -1 if a<b, 0 if equal */
+function compareSemver(a, b) {
+	const pa = parseSemverParts(a);
+	const pb = parseSemverParts(b);
+	const len = Math.max(pa.length, pb.length);
+	for (let i = 0; i < len; i += 1) {
+		const x = pa[i] || 0;
+		const y = pb[i] || 0;
+		if (x > y) return 1;
+		if (x < y) return -1;
+	}
+	return 0;
+}
+
+async function fetchJsonWithTimeout(url, timeoutMs = 12000) {
+	const trimmed = String(url || "").trim();
+	if (!trimmed) return null;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetch(trimmed, {
+			headers: {
+				Accept: "application/json,text/plain,*/*",
+				"User-Agent": USER_AGENT,
+			},
+			signal: controller.signal,
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		return await response.json();
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function fetchLatestSelfVersion(urls) {
+	const errors = [];
+	for (const entry of urls) {
+		try {
+			if (entry.kind === "npm") {
+				const data = await fetchJsonWithTimeout(entry.url);
+				const version = data?.version || data?.["dist-tags"]?.latest;
+				if (version) return { version: String(version), origin: "npm", url: entry.url };
+			} else {
+				const data = await fetchJsonWithTimeout(entry.url);
+				const version = data?.version;
+				if (version) return { version: String(version), origin: entry.label || "remote", url: entry.url };
+			}
+		} catch (error) {
+			errors.push(`${entry.label || entry.kind}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return { version: null, origin: null, url: null, error: errors.join("; ") || "latest version unavailable" };
+}
 
 function emptyCatalog(error) {
 	return {
@@ -305,6 +389,171 @@ async function searchNpm(query, limit) {
 	});
 }
 
+/** 在线搜索时把精选目录命中置顶，避免同名冷门包（如 @dsh-ssh/dsh-ssh）盖过已验证的 @linxin666/dsh-ssh。 */
+function catalogHitsForQuery(catalog, query, limit) {
+	const rows = filterCatalogPlugins(catalog, {
+		category: "",
+		query,
+		personalize: false,
+		installedNames: [],
+	});
+	return rows.slice(0, Math.max(0, limit)).map((row) => ({
+		...mapCatalogPlugin(row),
+		reason: "catalog",
+	}));
+}
+
+function suggestCatalogAlternatives(catalog, failedSpec, limit = 3) {
+	const failed = String(failedSpec || "").trim().toLowerCase();
+	if (!failed) return [];
+	const tokens = failed
+		.replace(/^@/, "")
+		.split(/[/@._-]+/)
+		.map((part) => part.trim().toLowerCase())
+		.filter((part) => part.length >= 3 && part !== "dsh" && part !== "plugin");
+	const uniq = [];
+	const seen = new Set([failed]);
+	for (const token of tokens.length ? tokens : [failed]) {
+		for (const row of catalogHitsForQuery(catalog, token, 8)) {
+			const spec = String(row.spec || "").trim();
+			if (!spec || seen.has(spec.toLowerCase())) continue;
+			seen.add(spec.toLowerCase());
+			uniq.push(spec);
+			if (uniq.length >= limit) return uniq;
+		}
+	}
+	return uniq;
+}
+
+/** ManagementError 没有 message 字段，只有 code / diagnostic；再拼上 packageResult 输出尾部。 */
+function formatChangeFailure(result, fallbackApplication = "failed") {
+	const parts = [];
+	const err = result?.error;
+	if (err && typeof err === "object") {
+		if (err.diagnostic) parts.push(String(err.diagnostic).trim());
+		if (err.code) parts.push(`错误码：${err.code}`);
+		if (Array.isArray(err.incompatible) && err.incompatible.length) {
+			const names = err.incompatible
+				.map((row) => `${row?.name || "?"}@${row?.version || "?"}`)
+				.filter(Boolean);
+			if (names.length) parts.push(`不兼容：${names.join("、")}`);
+		}
+	} else if (typeof err === "string" && err.trim()) {
+		parts.push(err.trim());
+	} else if (err?.message) {
+		parts.push(String(err.message).trim());
+	}
+
+	const pkg = result?.packageResult;
+	if (pkg && typeof pkg === "object") {
+		if (pkg.kind) parts.push(`失败类型：${pkg.kind}`);
+		if (pkg.timedOut) parts.push("安装超时（长时间无输出）");
+		if (typeof pkg.exitCode === "number") parts.push(`退出码：${pkg.exitCode}`);
+		const output = String(pkg.output || "").trim();
+		if (output) {
+			const lines = output
+				.split(/\r?\n/)
+				.map((line) => line.trim())
+				.filter(Boolean);
+			const tail = lines.slice(-8).join("\n");
+			if (tail) parts.push(tail);
+		}
+		if (pkg.logPath) parts.push(`完整日志：${pkg.logPath}`);
+	}
+
+	if (result?.failedAt) parts.push(`失败位置：${result.failedAt}`);
+	if (Array.isArray(result?.pendingBuilds) && result.pendingBuilds.length) {
+		parts.push(`待批准构建脚本：${result.pendingBuilds.join("、")}`);
+	}
+	if (Array.isArray(result?.warnings) && result.warnings.length) {
+		parts.push(`警告：${result.warnings.slice(0, 3).join("；")}`);
+	}
+
+	const unique = [];
+	const seen = new Set();
+	for (const part of parts) {
+		const text = String(part || "").trim();
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		unique.push(text);
+	}
+	if (unique.length) return unique.join("\n");
+	const application = result?.application || fallbackApplication;
+	return `安装失败（${application}）。插件管理器未返回 diagnostic / 安装日志。`;
+}
+
+function extractIncompatibility(result) {
+	const code = result?.error?.code || null;
+	const incompatible = Array.isArray(result?.error?.incompatible)
+		? result.error.incompatible
+				.map((row) => ({
+					name: String(row?.name || "").trim(),
+					version: String(row?.version || "").trim(),
+					runtimeVersion: String(row?.runtimeVersion || "").trim(),
+					peers: row?.peers && typeof row.peers === "object" ? row.peers : {},
+				}))
+				.filter((row) => row.name && row.version)
+		: [];
+	return {
+		code,
+		incompatible,
+		needsRiskExemption: code === "incompatible-version" && incompatible.length > 0,
+	};
+}
+
+/** 安装失败时从精选目录推荐相近/同标签插件，优先给出可替代的当前生态包。 */
+function buildFailureRecommendations(catalog, failedSpec, limit = 4) {
+	const failed = String(failedSpec || "").trim();
+	const seen = new Set([failed.toLowerCase()]);
+	const out = [];
+	const pushRow = (row, reason) => {
+		const spec = String(row?.spec || "").trim();
+		if (!spec || seen.has(spec.toLowerCase())) return;
+		seen.add(spec.toLowerCase());
+		out.push({
+			spec,
+			title: row.title || spec,
+			description: row.description || "",
+			source: "catalog",
+			installSpec: spec,
+			catalogId: row.id || row.spec,
+			reason: reason || "similar",
+			featured: row.featured === true,
+			rank: typeof row.rank === "number" ? row.rank : 0,
+		});
+	};
+
+	const plugins = Array.isArray(catalog?.plugins) ? catalog.plugins : [];
+	const failedRow = plugins.find((row) => String(row.spec || "").toLowerCase() === failed.toLowerCase());
+	if (failedRow) {
+		for (const rel of failedRow.related || []) {
+			const hit = plugins.find((row) => String(row.spec || "") === rel || String(row.id || "") === rel);
+			if (hit) pushRow(hit, "related");
+			if (out.length >= limit) return out;
+		}
+		for (const tag of failedRow.tags || []) {
+			for (const row of plugins) {
+				if ((row.tags || []).includes(tag)) pushRow(row, "tag");
+				if (out.length >= limit) return out;
+			}
+		}
+		for (const cat of failedRow.categories || []) {
+			if (cat === "featured") continue;
+			for (const row of plugins) {
+				if ((row.categories || []).includes(cat)) pushRow(row, "category");
+				if (out.length >= limit) return out;
+			}
+		}
+	}
+
+	for (const spec of suggestCatalogAlternatives(catalog, failed, limit)) {
+		const hit = plugins.find((row) => String(row.spec || "") === spec) || { spec, title: spec };
+		pushRow(hit, "similar");
+		if (out.length >= limit) break;
+	}
+	return out.slice(0, limit);
+}
+
 function mapGithubRepos(items) {
 	return (Array.isArray(items) ? items : []).map((repo) => ({
 		source: "github",
@@ -381,6 +630,14 @@ class PluginDiscoveryService extends TypertRemoteService {
 		catalogGithubUrl: z.string().default(DEFAULT_CATALOG_GITHUB_URL),
 		/** 远程检查间隔；期间复用内存/磁盘缓存 */
 		catalogRefreshTtlMs: z.number().min(0).max(86400000 * 7).default(3600000),
+		/** 启动与打开面板时检查本插件是否有新版本 */
+		selfUpdateCheckEnabled: z.boolean().default(true),
+		/** 发现新版本后自动执行更新（file: 本地开发安装会跳过自动更新） */
+		selfUpdateAuto: z.boolean().default(true),
+		selfUpdateCheckTtlMs: z.number().min(0).max(86400000 * 7).default(21600000),
+		selfPackageName: z.string().default(SELF_PACKAGE_NAME),
+		selfPackageGiteeUrl: z.string().default(DEFAULT_SELF_PACKAGE_GITEE_URL),
+		selfPackageGithubUrl: z.string().default(DEFAULT_SELF_PACKAGE_GITHUB_URL),
 	});
 
 	constructor(ctx, config) {
@@ -390,14 +647,206 @@ class PluginDiscoveryService extends TypertRemoteService {
 		this.catalog = pickNewerCatalog(loadBundledCatalog(), loadCachedCatalog());
 		this.catalogCheckedAt = 0;
 		this.catalogRefreshPromise = null;
+		this.selfUpdateCheckedAt = 0;
+		this.selfUpdateState = null;
+		this.selfUpdatePromise = null;
 		this.ctx.effect(() => this.registerTools());
 		// 启动后后台拉一次，不阻塞启动
 		this.ctx.effect(() => {
 			void this.refreshCatalog({ force: false }).catch(() => {});
+			void this.checkSelfUpdate({ force: false, auto: this.config.selfUpdateAuto === true }).catch(() => {});
 			return () => {};
 		});
 	}
 
+	getLocalInstallMeta() {
+		const local = readLocalPackageMeta();
+		const real = (() => {
+			try {
+				return join(__dirname);
+			} catch {
+				return "";
+			}
+		})();
+		const isFileInstall = /[\\/]bundles[\\/]dsh-plugin-discovery$/i.test(real.replace(/\\/g, "/"));
+		return {
+			name: this.config.selfPackageName || local.name || SELF_PACKAGE_NAME,
+			version: local.version,
+			isFileInstall,
+		};
+	}
+
+	selfUpdateSourceUrls() {
+		const name = this.config.selfPackageName || SELF_PACKAGE_NAME;
+		const urls = [
+			{
+				kind: "npm",
+				label: "npm",
+				url: `https://registry.npmjs.org/${encodeURIComponent(name)}/latest`,
+			},
+		];
+		const gitee = String(this.config.selfPackageGiteeUrl || "").trim();
+		const github = String(this.config.selfPackageGithubUrl || "").trim();
+		if (gitee) urls.push({ kind: "json", label: "gitee", url: gitee });
+		if (github) urls.push({ kind: "json", label: "github", url: github });
+		return urls;
+	}
+
+	async resolveInstalledSelfVersion() {
+		const local = this.getLocalInstallMeta();
+		try {
+			const bundles = await this.ctx.pluginManager.listBundles();
+			const row = (Array.isArray(bundles) ? bundles : []).find((item) => item && item.name === local.name);
+			if (row?.version) {
+				return { currentVersion: String(row.version), source: "bundle", isFileInstall: local.isFileInstall, name: local.name };
+			}
+		} catch {
+			/* ignore */
+		}
+		return {
+			currentVersion: local.version,
+			source: "package",
+			isFileInstall: local.isFileInstall,
+			name: local.name,
+		};
+	}
+
+	async checkSelfUpdate(options = {}) {
+		if (!this.config.enabled) {
+			return { ok: false, message: "发现插件已停用" };
+		}
+		if (this.config.selfUpdateCheckEnabled === false) {
+			return { ok: true, skipped: true, reason: "check disabled", update: this.selfUpdateState };
+		}
+		const force = options.force === true;
+		const auto = options.auto === true;
+		const ttl = this.config.selfUpdateCheckTtlMs ?? 21600000;
+		if (!force && this.selfUpdateCheckedAt && Date.now() - this.selfUpdateCheckedAt < ttl && this.selfUpdateState) {
+			if (auto && this.selfUpdateState.updateAvailable && !this.selfUpdateState.isFileInstall) {
+				return this.updateSelf({ latestVersion: this.selfUpdateState.latestVersion });
+			}
+			return { ok: true, skipped: true, reason: "ttl", update: this.selfUpdateState };
+		}
+		if (this.selfUpdatePromise) return this.selfUpdatePromise;
+
+		this.selfUpdatePromise = (async () => {
+			const installed = await this.resolveInstalledSelfVersion();
+			const latestInfo = await fetchLatestSelfVersion(this.selfUpdateSourceUrls());
+			this.selfUpdateCheckedAt = Date.now();
+			if (!latestInfo.version) {
+				this.selfUpdateState = {
+					...installed,
+					latestVersion: null,
+					updateAvailable: false,
+					origin: null,
+					checkedAt: this.selfUpdateCheckedAt,
+					error: latestInfo.error,
+				};
+				return { ok: false, message: latestInfo.error || "无法获取最新版本", update: this.selfUpdateState };
+			}
+			const updateAvailable = compareSemver(latestInfo.version, installed.currentVersion) > 0;
+			this.selfUpdateState = {
+				name: installed.name,
+				currentVersion: installed.currentVersion,
+				latestVersion: latestInfo.version,
+				updateAvailable,
+				origin: latestInfo.origin,
+				isFileInstall: installed.isFileInstall,
+				checkedAt: this.selfUpdateCheckedAt,
+			};
+			if (auto && updateAvailable && !installed.isFileInstall && this.config.selfUpdateAuto !== false) {
+				const updated = await this.updateSelf({ latestVersion: latestInfo.version });
+				return { ...updated, update: this.selfUpdateState };
+			}
+			return {
+				ok: true,
+				update: this.selfUpdateState,
+				message: updateAvailable
+					? `发现新版本 ${latestInfo.version}（当前 ${installed.currentVersion}）`
+					: `已是最新版本 ${installed.currentVersion}`,
+			};
+		})().finally(() => {
+			this.selfUpdatePromise = null;
+		});
+
+		return this.selfUpdatePromise;
+	}
+
+	async updateSelf(options = {}) {
+		if (!this.config.enabled) {
+			return { ok: false, message: "发现插件已停用" };
+		}
+		const installed = await this.resolveInstalledSelfVersion();
+		if (installed.isFileInstall) {
+			return {
+				ok: false,
+				skipped: true,
+				message: "当前为本地 file: 开发安装，已跳过自动更新。发布版用户会从 npm 升级。",
+				update: this.selfUpdateState,
+			};
+		}
+		let latestVersion = typeof options.latestVersion === "string" ? options.latestVersion.trim() : "";
+		if (!latestVersion) {
+			const checked = await this.checkSelfUpdate({ force: true, auto: false });
+			latestVersion = checked?.update?.latestVersion || "";
+			if (!checked?.update?.updateAvailable) {
+				return {
+					ok: true,
+					updated: false,
+					message: checked?.message || "没有可更新版本",
+					update: checked?.update || this.selfUpdateState,
+				};
+			}
+		}
+		const name = installed.name || SELF_PACKAGE_NAME;
+		const spec = `${name}@${latestVersion}`;
+		const requestId =
+			globalThis.crypto?.randomUUID?.() || `pd-self-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+		try {
+			const result = await this.ctx.pluginManager.installBundle(spec, {
+				requestId,
+				enabled: true,
+			});
+			const application = result?.application;
+			const failed = application === "failed" || application === "cancelled";
+			if (!failed) {
+				this.selfUpdateState = {
+					...(this.selfUpdateState || {}),
+					name,
+					currentVersion: latestVersion,
+					latestVersion,
+					updateAvailable: false,
+					origin: this.selfUpdateState?.origin || "npm",
+					isFileInstall: false,
+					checkedAt: Date.now(),
+				};
+			}
+			return {
+				ok: !failed,
+				updated: !failed,
+				spec,
+				requestId,
+				application,
+				packageName: name,
+				version: latestVersion,
+				message: failed
+					? result?.error?.message || `更新失败（${application || "unknown"}）`
+					: `已更新到 ${latestVersion}，请刷新页面或重启 dsh web 使界面生效`,
+				update: this.selfUpdateState,
+				result,
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				updated: false,
+				spec,
+				requestId,
+				message: error instanceof Error ? error.message : String(error),
+				update: this.selfUpdateState,
+			};
+		}
+	}
+
 	getCatalog() {
 		return this.catalog || loadBundledCatalog();
 	}
@@ -573,6 +1022,14 @@ class PluginDiscoveryService extends TypertRemoteService {
 
 		// 打开推荐/分类时尝试按 TTL 拉远程；失败静默回退本地
 		await this.refreshCatalog({ force: opts.refresh === true }).catch(() => {});
+		const selfUpdate = await this.checkSelfUpdate({
+			force: opts.refresh === true,
+			auto: this.config.selfUpdateAuto === true,
+		}).catch((error) => ({
+			ok: false,
+			message: error instanceof Error ? error.message : String(error),
+			update: this.selfUpdateState,
+		}));
 
 		const catalog = this.getCatalog();
 		const personalize = mode === "recommend";
@@ -594,6 +1051,9 @@ class PluginDiscoveryService extends TypertRemoteService {
 			categories: catalog.categories,
 			results,
 			total: results.length,
+			selfUpdate: selfUpdate?.update || this.selfUpdateState,
+			selfUpdateMessage: selfUpdate?.message || null,
+			selfUpdated: selfUpdate?.updated === true,
 		};
 	}
 
@@ -641,6 +1101,9 @@ class PluginDiscoveryService extends TypertRemoteService {
 
 		const limit = this.config.maxCandidates;
 		const token = opts.githubToken ?? this.config.githubToken;
+		await this.refreshCatalog({ force: false }).catch(() => {});
+		const catalog = this.getCatalog();
+		const catalogHits = catalogHitsForQuery(catalog, q === "dsh" ? "" : q, limit);
 		let raw = [];
 		try {
 			if (source === "npm" || source === "all") {
@@ -651,23 +1114,27 @@ class PluginDiscoveryService extends TypertRemoteService {
 			}
 		} catch (error) {
 			this.ctx.logger.warn("[plugin-discovery] search failed", error);
-			return {
-				ok: false,
-				message: error instanceof Error ? error.message : String(error),
-				results: [],
-				total: 0,
-			};
+			if (!catalogHits.length) {
+				return {
+					ok: false,
+					message: error instanceof Error ? error.message : String(error),
+					results: [],
+					total: 0,
+				};
+			}
+			// 在线源失败时仍返回精选命中，避免「搜得到却全空」
+			raw = [];
 		}
 
 		const seen = new Set();
 		const deduped = [];
-		for (const row of raw) {
+		for (const row of [...catalogHits, ...raw]) {
 			if (!row.spec || seen.has(row.spec)) continue;
 			seen.add(row.spec);
 			deduped.push({
 				...row,
 				installSpec: row.spec,
-				bundle: null,
+				bundle: row.bundle ?? null,
 			});
 			if (deduped.length >= limit) break;
 		}
@@ -791,6 +1258,17 @@ class PluginDiscoveryService extends TypertRemoteService {
 				message: `「${existing}」已在 DSH 插件列表中，无需重复安装。请到「插件」页查看。`,
 			};
 		}
+		const withInstallHint = (message) => {
+			const text = String(message || "").trim() || "安装失败";
+			const looksNetwork =
+				/ERR_PNPM_META_FETCH_FAIL|fetch failed|ECONNRESET|ETIMEDOUT|ENOTFOUND|network|镜像/i.test(text);
+			if (!looksNetwork) return text;
+			const alts = suggestCatalogAlternatives(this.getCatalog(), trimmed);
+			if (!alts.length) {
+				return `${text}。若持续失败，可改用「分类浏览 / 为你推荐」里的精选包，或稍后重试。`;
+			}
+			return `${text}。可改试精选目录中的相近插件：${alts.join("、")}`;
+		};
 		try {
 			const result = await this.ctx.pluginManager.installBundle(trimmed, {
 				requestId,
@@ -799,6 +1277,18 @@ class PluginDiscoveryService extends TypertRemoteService {
 			const packageName = result?.bundle || pre.name || trimmed;
 			const application = result?.application;
 			const failed = application === "failed" || application === "cancelled";
+			const rawMessage = failed
+				? formatChangeFailure(result, application || "failed")
+				: `「${packageName}」安装完成（${application || "applied"} / ${result?.stage || "install"}）`;
+			const incompat = failed ? extractIncompatibility(result) : {};
+			const recommendations =
+				failed && (incompat.needsRiskExemption || incompat.code === "incompatible-version")
+					? buildFailureRecommendations(this.getCatalog(), trimmed, 4)
+					: undefined;
+			let message = failed ? withInstallHint(rawMessage) : rawMessage;
+			if (failed && recommendations && recommendations.length) {
+				message = `${message}\n推荐改试：${recommendations.map((row) => row.spec).join("、")}`;
+			}
 			return {
 				ok: !failed,
 				alreadyInstalled: false,
@@ -806,15 +1296,65 @@ class PluginDiscoveryService extends TypertRemoteService {
 				requestId,
 				application,
 				stage: result?.stage,
-				message: failed
-					? result?.error?.message || `安装失败（${application || "unknown"}）`
-					: `「${packageName}」安装完成（${application || "applied"} / ${result?.stage || "install"}）`,
+				message,
+				detail: failed ? rawMessage : undefined,
+				logPath: failed ? result?.packageResult?.logPath : undefined,
+				code: incompat.code || undefined,
+				incompatible: incompat.incompatible || undefined,
+				needsRiskExemption: incompat.needsRiskExemption === true,
+				recommendations,
+				installSpec: trimmed,
 				result,
 			};
 		} catch (error) {
 			return {
 				ok: false,
 				requestId,
+				message: withInstallHint(error instanceof Error ? error.message : String(error)),
+				installSpec: trimmed,
+			};
+		}
+	}
+
+	/** Typert Remote：参数必须是独立形参，不能解构、不能默认值、不能 rest。 */
+	async grantVersionExemption(packageVersion, runtimeVersion, acceptRisk) {
+		if (!this.config.enabled) {
+			return { ok: false, message: "发现插件已停用" };
+		}
+		const pkg = String(packageVersion == null ? "" : packageVersion).trim();
+		const runtime = String(runtimeVersion == null ? "" : runtimeVersion).trim();
+		const accepted = acceptRisk === true;
+		if (!pkg || !runtime) {
+			return { ok: false, message: "缺少 packageVersion 或 runtimeVersion" };
+		}
+		if (!accepted) {
+			return {
+				ok: false,
+				message: "未确认风险。授予版本豁免必须 acceptRisk=true，并先明确告知可能崩溃或数据丢失。",
+			};
+		}
+		if (typeof this.ctx.pluginManager?.setVersionExemption !== "function") {
+			return { ok: false, message: "当前 DSH 不支持 setVersionExemption" };
+		}
+		try {
+			const result = await this.ctx.pluginManager.setVersionExemption(pkg, runtime, true, true);
+			const application = result?.application;
+			const failed = application === "failed" || application === "cancelled";
+			return {
+				ok: !failed,
+				packageVersion: pkg,
+				runtimeVersion: runtime,
+				application,
+				message: failed
+					? formatChangeFailure(result, application || "failed")
+					: `已为 ${pkg} 在 DSH ${runtime} 上授予精确版本豁免，可重新安装。`,
+				result,
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				packageVersion: pkg,
+				runtimeVersion: runtime,
 				message: error instanceof Error ? error.message : String(error),
 			};
 		}
@@ -829,6 +1369,22 @@ class PluginDiscoveryService extends TypertRemoteService {
 				return { ok: true, settled: null, pending: true, message: "安装仍在进行或已丢失" };
 			}
 			const failed = settled.application === "failed" || settled.application === "cancelled";
+			const failText = failed ? formatChangeFailure(settled, settled.application) : "";
+			const incompat = failed ? extractIncompatibility(settled) : {};
+			const failedSpec =
+				(Array.isArray(incompat.incompatible) && incompat.incompatible[0]
+					? `${incompat.incompatible[0].name}@${incompat.incompatible[0].version}`
+					: "") || settled.bundle || "";
+			const recommendations =
+				failed && (incompat.needsRiskExemption || incompat.code === "incompatible-version")
+					? buildFailureRecommendations(this.getCatalog(), failedSpec, 4)
+					: undefined;
+			let message = failed
+				? failText
+				: `安装完成（${settled.application} / ${settled.stage}）`;
+			if (failed && recommendations && recommendations.length) {
+				message = `${message}\n推荐改试：${recommendations.map((row) => row.spec).join("、")}`;
+			}
 			return {
 				ok: !failed,
 				settled,
@@ -836,9 +1392,14 @@ class PluginDiscoveryService extends TypertRemoteService {
 				packageName: settled.bundle,
 				application: settled.application,
 				stage: settled.stage,
-				message: failed
-					? settled.error?.message || `安装失败（${settled.application}）`
-					: `安装完成（${settled.application} / ${settled.stage}）`,
+				message,
+				detail: failed ? failText : undefined,
+				logPath: failed ? settled?.packageResult?.logPath : undefined,
+				code: incompat.code || undefined,
+				incompatible: incompat.incompatible || undefined,
+				needsRiskExemption: incompat.needsRiskExemption === true,
+				recommendations,
+				installSpec: failedSpec || undefined,
 			};
 		} catch (error) {
 			return {
@@ -929,6 +1490,28 @@ class PluginDiscoveryService extends TypertRemoteService {
 				}),
 			),
 		);
+		disposers.push(
+			this.ctx.tools.register(
+				defineTool({
+					name: "plugin_discovery_check_update",
+					description: "Check whether dsh-plugin-discovery has a newer npm/Gitee version and optionally update.",
+					parameters: {
+						autoUpdate: {
+							type: "boolean",
+							description: "If true and a newer version exists, install it now",
+						},
+					},
+					output: toolOutput,
+					async execute(args) {
+						return service.checkSelfUpdate({
+							force: true,
+							auto: args.autoUpdate === true,
+						});
+					},
+					presentCall: () => present("Check dsh-plugin-discovery update"),
+				}),
+			),
+		);
 		return () => {
 			for (const dispose of disposers.reverse()) dispose();
 		};
@@ -939,8 +1522,11 @@ class PluginDiscoveryService extends TypertRemoteService {
 
 markRemoteMethod(PluginDiscoveryService.prototype, "search");
 markRemoteMethod(PluginDiscoveryService.prototype, "listCatalog");
+markRemoteMethod(PluginDiscoveryService.prototype, "checkSelfUpdate");
+markRemoteMethod(PluginDiscoveryService.prototype, "updateSelf");
 markRemoteMethod(PluginDiscoveryService.prototype, "resolve");
 markRemoteMethod(PluginDiscoveryService.prototype, "installPlugin");
+markRemoteMethod(PluginDiscoveryService.prototype, "grantVersionExemption");
 markRemoteMethod(PluginDiscoveryService.prototype, "listInstalled");
 markRemoteMethod(PluginDiscoveryService.prototype, "waitInstall");