dsh-plugin 2.1.0 → 2.2.1

package/lib/http/diagnostics.js

@@ -5,75 +5,14 @@
  *
  * 诊断路由：流式连通性自检、代理校验，以及与任务模块 /env 路由共享的宿主环境快照。
  */
-import { readFileSync } from 'node:fs';
 import { homedir, release } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { loadSettings } from '../services/settings.js';
+import { hostDshVersion, toolVersion } from '../services/host-version.js';
 import { gitLsRemote, probeUrl, systemProxy } from '../services/probe.js';
 import { appendLog } from '../services/log.js';
 import { readJsonBody, requireTrustedPost, sendJson } from './shared.js';
-/** 宿主 dsh CLI 版本：优先直接跑 `dsh --version`（与 pnpm/npm/git 同款同步探测，1500ms 超时兜底，
- *  绝不挂起）；拿不到再退回从入口 `process.argv[1]` 向上找 package.json（dsh 不在 PATH 时兜底）。 */
-function hostDshVersion() {
-    const viaCli = toolVersion('dsh', ['--version']);
-    if (viaCli)
-        return viaCli;
-    const entry = process.argv[1];
-    if (entry === undefined)
-        return null;
-    let dir = dirname(resolve(entry));
-    for (let depth = 0; depth < 4; depth++) {
-        try {
-            const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-            const name = manifest.name ?? '';
-            if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
-                return manifest.version;
-            }
-        }
-        catch {
-            /* 不是包根，继续向上查找 */
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return null;
-}
-/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
- *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文（统一再加 `v` 前缀）拼成
- *  `vgit version 2.55.0.windows.5`。只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
-function versionOf(output) {
-    const first = output.trim().split(/\r?\n/)[0]?.trim() ?? '';
-    if (!first)
-        return null;
-    const match = /\d+\.\d+[0-9A-Za-z.\-+]*/.exec(first);
-    return match === null ? null : match[0];
-}
-/** 探测命令行工具的版本号（pnpm --version / npm --version / git --version）：
- *  未安装 / 不在 PATH / 超时一律返回 null —— issue 环境快照如实写 unknown，绝不挂起。
- *  （同步探测仅用于启动期/请求期的低频率 /env 快照，安装通道不经过这里。）
- *
- *  Windows 上 pnpm/npm 是 .cmd shim，不带 shell 的 spawnSync 起不来 —— 上报的 issue 里
- *  因此长期是 `pnpm: unknown` / `npm: unknown`，而 pnpm 版本恰恰是 allowBuilds 那类问题的
- *  关键信息（门禁行为随版本变）。故 win32 走 shell 让 cmd 解析 shim；参数是固定的
- *  `--version`，没有注入面。 */
-function toolVersion(cmd, args) {
-    try {
-        const r = spawnSync(cmd, args, {
-            timeout: 1500,
-            encoding: 'utf8',
-            shell: process.platform === 'win32',
-        });
-        if (r.error || r.status !== 0)
-            return null;
-        return versionOf(r.stdout ?? '');
-    }
-    catch {
-        return null;
-    }
-}
 /** 本机实际生效的 npm registry：诊断与安装同口径 —— 设置里留空时读用户 npm 配置
  *  （含 profile 目录的 .npmrc），而不是硬探官方源，避免「能装但诊断说源不通」。
  *  读不到（npm 缺失/超时/输出异常）时回退官方源。 */

package/lib/services/host-version.js

@@ -0,0 +1,72 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 宿主与命令行工具的版本探测：dsh 版本同时用于诊断快照和「插件要求更高 DSH」判定，
+ * pnpm/npm/git 只用于诊断快照。同步探测 + 1500ms 超时兜底，拿不到一律 null，绝不挂起。
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
+ *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文拼成 `vgit version …`。
+ *  只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
+export function versionOf(output) {
+    const first = output.trim().split(/\r?\n/)[0]?.trim() ?? '';
+    if (!first)
+        return null;
+    const match = /\d+\.\d+[0-9A-Za-z.\-+]*/.exec(first);
+    return match === null ? null : match[0];
+}
+/** 探测命令行工具版本：未安装 / 不在 PATH / 超时一律 null。
+ *  Windows 上 pnpm/npm 是 .cmd shim，不走 shell 起不来；参数是固定的 `--version`，没有注入面。 */
+export function toolVersion(cmd, args) {
+    try {
+        const r = spawnSync(cmd, args, {
+            timeout: 1500,
+            encoding: 'utf8',
+            shell: process.platform === 'win32',
+        });
+        if (r.error || r.status !== 0)
+            return null;
+        return versionOf(r.stdout ?? '');
+    }
+    catch {
+        return null;
+    }
+}
+let cachedDshVersion = null;
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export function hostDshVersion() {
+    if (cachedDshVersion !== null)
+        return cachedDshVersion;
+    const viaCli = toolVersion('dsh', ['--version']);
+    if (viaCli !== null) {
+        cachedDshVersion = viaCli;
+        return viaCli;
+    }
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return null;
+    let dir = dirname(resolve(entry));
+    for (let depth = 0; depth < 4; depth++) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            const name = manifest.name ?? '';
+            if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
+                cachedDshVersion = manifest.version;
+                return cachedDshVersion;
+            }
+        }
+        catch {
+            /* 不是包根，继续向上查找 */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}

package/lib/services/install/dsh-compat.js

@@ -0,0 +1,105 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 「插件要求的 DSH 版本高于当前宿主」判定：安装失败后读一次 npm 元数据，取
+ * peerDependencies（@deepseek-ai/dsh-*）与 engines.dsh 声明的最低版本里最高的那个，
+ * 与宿主版本比较；宿主更低就产出 [dsh-too-old] 标记 —— 前端据此提示「先升级 DSH」，
+ * 不再把这类失败归成「未分类」丢给用户或插件作者。
+ *
+ * 只在失败路径调用：peer 不满足本身通常只是警告，成功安装时不该出现这个提示；
+ * 任何网络/解析异常都静默返回 null，不改变原有失败处理。
+ */
+import { hostDshVersion } from '../host-version.js';
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export function npmNameOf(target) {
+    const raw = target.trim();
+    if (raw === '')
+        return null;
+    if (/^(?:github:|git\+|https?:|file:|link:|\.{0,2}[\\/])/i.test(raw))
+        return null;
+    // owner/repo（非 scope）：git 目标的另一种写法，不是包名
+    if (!raw.startsWith('@') && /^[^\s@]+\/[^\s]+$/.test(raw))
+        return null;
+    const at = raw.lastIndexOf('@');
+    const name = at > 0 ? raw.slice(0, at) : raw;
+    return /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(name) ? name : null;
+}
+/** `0.2.1-rc.1` / `^0.2.1` / `>=0.2.0 <0.3.0` → [0,2,1]；解析不出返回 null。
+ *  只取版本三段：DSH 的 prerelease 序号（rc.1）不参与「太低」判断，避免比较误差。 */
+export function versionTriple(raw) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw);
+    return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compareTriple(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return 0;
+}
+/** 插件声明的最低 DSH 版本：engines.dsh 与 peerDependencies 里 @deepseek-ai/dsh-* 的下限取最大。
+ *  返回原始声明文本（如 `^0.2.1-rc.1`）供提示直接展示；没有声明返回 null。 */
+export function dshFloorOf(manifest) {
+    const m = manifest;
+    const ranges = [];
+    const engineDsh = m?.engines?.dsh;
+    if (typeof engineDsh === 'string')
+        ranges.push(engineDsh);
+    for (const [name, range] of Object.entries(m?.peerDependencies ?? {})) {
+        if (/^@deepseek-ai\/dsh(?:-|$)/.test(name) && typeof range === 'string')
+            ranges.push(range);
+    }
+    let floor = null;
+    let floorTriple = null;
+    for (const range of ranges) {
+        const triple = versionTriple(range);
+        if (triple === null)
+            continue;
+        if (floorTriple === null || compareTriple(triple, floorTriple) > 0) {
+            floor = range;
+            floorTriple = triple;
+        }
+    }
+    return floor;
+}
+/**
+ * 产出「插件要求更高的 DSH」标记行；没有声明、读不到元数据、宿主版本未知或已满足时返回 null。
+ * 用版本级 manifest（`/<pkg>/latest`）：packument 的精简形态不带 peerDependencies。
+ */
+export async function dshTooOldMarker(target, opts = {}) {
+    const name = npmNameOf(target);
+    if (name === null)
+        return null;
+    const current = opts.currentVersion ?? hostDshVersion();
+    if (current === null)
+        return null;
+    const currentTriple = versionTriple(current);
+    if (currentTriple === null)
+        return null;
+    const base = (opts.registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+    // scope 包的路径要编码：`@scope/name` → `%40scope%2Fname`
+    const url = `${base}/${name.replace('@', '%40').replace('/', '%2F')}/latest`;
+    let manifest;
+    try {
+        const res = await (opts.fetchImpl ?? fetch)(url, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 4000),
+        });
+        if (!res.ok)
+            return null;
+        manifest = await res.json();
+    }
+    catch {
+        return null;
+    }
+    const floor = dshFloorOf(manifest);
+    const floorTriple = floor === null ? null : versionTriple(floor);
+    if (floor === null || floorTriple === null)
+        return null;
+    if (compareTriple(currentTriple, floorTriple) >= 0)
+        return null;
+    return `[dsh-too-old] ${name} requires DSH >= ${floor} (declared in engines / peerDependencies), but this host runs ${current} — upgrade DSH before installing`;
+}

package/lib/services/install/operation-log.js

@@ -95,7 +95,7 @@ export function backfillOperationLog(output, profileDir) {
 export function hasSubstantiveOutput(output) {
     return output.split(/\r?\n/).some((raw) => {
         const line = raw.trim();
-        return line !== '' && !/^\[(?:exit\b|timed out\]|install-channel\]|stale pipe\]|error\]|pnpm log\])/.test(line);
+        return line !== '' && !/^\[(?:exit\b|timed out\]|install-channel\]|stale pipe\]|error\]|pnpm log\]|registry-fallback\]|allow build\])/.test(line);
     });
 }
 /**

package/lib/services/install/registry-fallback.js

@@ -71,11 +71,16 @@ export function userNpmRegistry(cwd) {
 /**
  * 传输层失败才值得换源：超时、连接重置、DNS、5xx。
  * 404 / 版本不存在 / 鉴权失败必须保持原样 —— 换源只会掩盖作者侧问题或装到滞后版本。
+ * 本机证书链不被信任（TLS 校验失败）同样不换源：换哪个公共镜像都会以同样方式失败，
+ * 白白多等两轮超时、把真正的根因淹进换源噪音里。
  */
 export function isTransportFailure(text) {
     if (/\b(?:ERR_PNPM_FETCH_404|E404|ERR_PNPM_NO_MATCHING_VERSION|ETARGET|ERR_PNPM_FETCH_401|ERR_PNPM_FETCH_403|E401|E403)\b/i.test(text)) {
         return false;
     }
+    if (/unable to verify the first certificate|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ERR_TLS_CERT_ALTNAME_INVALID|CERT_HAS_EXPIRED|CERT_UNTRUSTED|UNABLE_TO_GET_ISSUER_CERT/i.test(text)) {
+        return false;
+    }
     return /\b(?:ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|EPIPE)\b|socket hang up|getaddrinfo|network request failed|connect timeout|request to .+ failed|FetchError|ERR_PNPM_FETCH_5\d\d|ERR_PNPM_META_FETCH_FAIL/i.test(text);
 }
 /** 日志里展示用的源主机名（不打印可能带凭据的完整 URL）。 */

package/lib/services/install/task-queue.js

@@ -22,6 +22,7 @@ import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, p
 import { appendLog } from '../log.js';
 import { commandOnPath, gitMissingDetail } from './preflight.js';
 import { isTransportFailure, registryHost } from './registry-fallback.js';
+import { dshTooOldMarker } from './dsh-compat.js';
 import { OutputDecoder } from './decode-output.js';
 /** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map();
@@ -365,6 +366,12 @@ function spawnMutation(options) {
     const invocation = isGlobalNpm
         ? { file: 'npm', prefixArgs: [], cwd: process.cwd(), useShell: process.platform === 'win32' }
         : cliInvocation(profile);
+    // 打包桌面端却回退到 PATH 上的 dsh：说明 desktop CLI 引导路径没命中，desktop profile 必被宿主拒绝。
+    // 留一行 ASCII 标记，后续同类上报可直接区分「用户自起 CLI」与「我们没走对引导路径」。
+    if (task && task.status !== 'cancelled' && invocation.file === 'dsh'
+        && process.versions.electron !== undefined) {
+        pushLine(task, '[desktop-cli-fallback] running inside Electron but no desktop CLI bootstrap was found — falling back to dsh on PATH (a desktop-managed profile will be rejected)');
+    }
     // 更新已安装的 npm 包：显式指定 @latest。pnpm add <pkg>（无版本）对已存在依赖
     // （尤其精确 spec 如 "1.3.0"）是幂等的 —— 输出 "Already up to date" 且不改 package.json，
     // 导致「更新成功」但实际仍停留在旧版本；git 地址与全局安装不受此影响。
@@ -605,6 +612,12 @@ function spawnMutation(options) {
                 task.status = result.timedOut || result.exitCode !== 0 ? 'failed' : 'done';
                 if (task.status === 'done') {
                     task.progress = 100;
+                    // 实际装上的版本：目录版本可能滞后，客户端账本必须记这个值，否则「有更新」永久失真
+                    if (!isGlobalNpm && action !== 'remove') {
+                        const installed = installedVersionOf(profile, target);
+                        if (installed !== null)
+                            task.installedVersion = installed;
+                    }
                     // 市场自更新：若 bundle 已被取消勾选，重启后市场不会出现，结果页要明确提示
                     if ((action === 'add' || action === 'update') && (target === 'dsh-plugin' || target.startsWith('dsh-plugin@'))
                         && !bundleIncludes(profile, 'dsh-plugin')) {
@@ -653,9 +666,39 @@ function spawnMutation(options) {
                 pushLine(task, result.timedOut ? '[timed out]' : `[exit ${result.exitCode ?? '?'}]${printedNothing ? ' (no output captured)' : ''}`);
             }
         }
-        return result;
+        // 带上最终生效的源：后续注解（如 [dsh-too-old]）读元数据必须与安装同源，
+        // 否则换过源之后会去另一个源查，查不到就静默漏报
+        return activeRegistry === undefined ? result : { ...result, registry: activeRegistry };
     })();
 }
+/**
+ * 安装成功后从 profile 的 `node_modules/<pkg>/package.json` 读**实际**版本；
+ * 定位不到包名或读不到返回 null。客户端拿它写版本账本 —— 目录里的版本可能滞后。
+ */
+export function installedVersionOf(profile, target) {
+    const profileDir = profileDirectory(profile);
+    let deps = {};
+    try {
+        const pkg = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'));
+        deps = pkg.dependencies ?? {};
+    }
+    catch {
+        return null;
+    }
+    const targetRepo = githubRepoOf(target)?.toLowerCase();
+    const name = targetRepo !== undefined
+        ? Object.keys(deps).find((k) => githubRepoOf(deps[k])?.toLowerCase() === targetRepo)
+        : deps[target] !== undefined ? target : Object.keys(deps).find((k) => deps[k] === target);
+    if (!name)
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(join(profileDir, 'node_modules', name, 'package.json'), 'utf8'));
+        return typeof meta.version === 'string' && meta.version !== '' ? meta.version : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 安装后校验已装包里 package.json 声明的文件（main / exports["."].default 与
  * dsh.bundle.patch）是否真实存在。npm 包也可能漏发构建产物（lib/ 等），pnpm 装完没有
@@ -746,6 +789,24 @@ async function annotateRegistryMissing(result, options) {
         pushLine(options.task, line);
     return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
 }
+/** 安装失败且插件声明的最低 DSH 版本高于当前宿主 → 注入 [dsh-too-old] 标记。
+ *  只在失败路径上发生：peer 不满足本身通常只是警告，装成功时不该冒这个提示。
+ *  超时也算失败 —— 旧宿主上插件可能卡在半兼容状态，这个信息同样有用。 */
+async function annotateDshTooOld(result, options) {
+    if (options.action === 'remove' || result.exitCode === 0)
+        return result;
+    // 全局 npm 装的是本机 CLI 工具，不进 profile，没有宿主版本要求
+    if ((options.globalNpm ?? []).length > 0)
+        return result;
+    // 用安装**实际**使用的源读元数据：换源重试后候选表首位可能并不是真正生效的那个，
+    // 用错源会读不到包而静默漏报；私有源/镜像里同样能读到包声明的 engines
+    const line = await dshTooOldMarker(options.target, { registry: result.registry ?? options.registries?.[0] });
+    if (line === null)
+        return result;
+    if (options.task && options.task.status !== 'cancelled')
+        pushLine(options.task, line);
+    return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
+}
 /**
  * 宿主自身 CLI 调不起来时的 ASCII 标记行：spawn 我们解析出的宿主入口报 ENOENT 时返回
  * `[host-spawn]`，供前端单独归因、不引导提 Issue。PATH 上的 dsh/npm 各有自己的标记，返回 null。
@@ -860,6 +921,8 @@ export async function runPluginMutation(options) {
     }
     // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」
     result = await annotateRegistryMissing(result, options);
+    // 插件声明的最低 DSH 版本高于当前宿主 → 追加 [dsh-too-old] 标记，前端提示先升级 DSH
+    result = await annotateDshTooOld(result, options);
     // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因
     return annotateNpmTooLow(result, options);
 }

package/lib/services/npm-release-age.js

@@ -18,7 +18,10 @@ export const RELEASE_AGE_TIMEOUT_MS = 8000;
 /** 响应体上限：完整 packument 可能达数 MB，超限直接放弃，避免异常大包拖垮服务。 */
 const MAX_PACKUMENT_BYTES = 10 * 1024 * 1024;
 export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
-/** 会话内缓存（包名 → 版本与发布时间）：只存成功结果，一次网络抖动不会把判断永久粘住。 */
+/** 会话内缓存（源 + 包名 → 结果）：只存成功结果，一次网络抖动不会把判断永久粘住。
+ *  必须带过期时间 —— 插件中心可能连续开着几小时，作者发了新版本后不能一直沿用旧结果；
+ *  也必须把源算进键 —— 同一个包在官方源与镜像上的 latest / 发布时间不同，混用会算错门禁。 */
+const CACHE_TTL_MS = 10 * 60 * 1000;
 const releaseCache = new Map();
 /** 从完整 packument 取 dist-tags.latest 对应版本及其发布时间；缺任一字段返回 null。 */
 export function latestReleaseOf(packument) {
@@ -96,12 +99,13 @@ async function fetchPackument(url, proxy, timeoutMs) {
     }
     return getJson(url, timeoutMs);
 }
-/** 查询一个包的最新版本与发布时间（成功结果缓存，同会话内同包不重复请求）；registry 为空回退官方源，失败返回 null。 */
+/** 查询一个包的最新版本与发布时间（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
 export async function lookupReleaseAge(packageName, registry, proxy, timeoutMs = RELEASE_AGE_TIMEOUT_MS) {
-    const cached = releaseCache.get(packageName);
-    if (cached !== undefined)
-        return cached;
     const base = registry.replace(/\/+$/, '') || DEFAULT_NPM_REGISTRY;
+    const key = `${base}\n${packageName}`;
+    const cached = releaseCache.get(key);
+    if (cached !== undefined && Date.now() - cached.at < CACHE_TTL_MS)
+        return cached.release;
     const body = await fetchPackument(`${base}/${encodeURIComponent(packageName)}`, proxy, timeoutMs);
     if (body === null)
         return null;
@@ -114,6 +118,6 @@ export async function lookupReleaseAge(packageName, registry, proxy, timeoutMs =
     }
     const release = latestReleaseOf(parsed);
     if (release !== null)
-        releaseCache.set(packageName, release);
+        releaseCache.set(key, { at: Date.now(), release });
     return release;
 }

package/lib/services/profile/installed-versions.js

@@ -17,7 +17,7 @@
  * 存储：`DSH_HOME/profiles/<profile>/gro.ngilp-hsd-versions.json`
  *   { "<owner>/<repo>"（小写）: { version, updatedAt, installedAt } }
  */
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 export function versionsFilePath(profile) {
@@ -60,5 +60,9 @@ export function removeInstalledVersion(profile, repo) {
 function writeVersions(profile, table) {
     const file = versionsFilePath(profile);
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(table, null, 2) + '\n', 'utf8');
+    // 先写临时文件再原子替换：直接覆盖时进程被杀/磁盘满会留下截断的 JSON，
+    // 下次读取整份账本都会失效（更新检测静默停摆），而用户看不到任何报错
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(table, null, 2) + '\n', 'utf8');
+    renameSync(tmp, file);
 }

package/lib/types/services/host-version.d.ts

@@ -0,0 +1,10 @@
+/** 从命令输出里抽出版本号本体：pnpm/npm 直接打印 `11.7.0`，而 `git --version` 打印
+ *  `git version 2.55.0.windows.5` —— 原样取首行会让 issue 正文拼成 `vgit version …`。
+ *  只取版本号，顺带兼容 `v1.2.3` 这类自带前缀的输出。 */
+export declare function versionOf(output: string): string | null;
+/** 探测命令行工具版本：未安装 / 不在 PATH / 超时一律 null。
+ *  Windows 上 pnpm/npm 是 .cmd shim，不走 shell 起不来；参数是固定的 `--version`，没有注入面。 */
+export declare function toolVersion(cmd: string, args: string[]): string | null;
+/** 宿主 dsh 版本：优先 `dsh --version`；拿不到再从入口 `process.argv[1]` 向上找 package.json
+ *  （dsh 不在 PATH 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+export declare function hostDshVersion(): string | null;

package/lib/types/services/install/dsh-compat.d.ts

@@ -0,0 +1,19 @@
+/** 从安装目标里取 npm 包名：`@scope/pkg@1.2.3` → `@scope/pkg`。
+ *  git / URL / 本地路径等非 npm 目标返回 null。 */
+export declare function npmNameOf(target: string): string | null;
+/** `0.2.1-rc.1` / `^0.2.1` / `>=0.2.0 <0.3.0` → [0,2,1]；解析不出返回 null。
+ *  只取版本三段：DSH 的 prerelease 序号（rc.1）不参与「太低」判断，避免比较误差。 */
+export declare function versionTriple(raw: string): [number, number, number] | null;
+/** 插件声明的最低 DSH 版本：engines.dsh 与 peerDependencies 里 @deepseek-ai/dsh-* 的下限取最大。
+ *  返回原始声明文本（如 `^0.2.1-rc.1`）供提示直接展示；没有声明返回 null。 */
+export declare function dshFloorOf(manifest: unknown): string | null;
+/**
+ * 产出「插件要求更高的 DSH」标记行；没有声明、读不到元数据、宿主版本未知或已满足时返回 null。
+ * 用版本级 manifest（`/<pkg>/latest`）：packument 的精简形态不带 peerDependencies。
+ */
+export declare function dshTooOldMarker(target: string, opts?: {
+    currentVersion?: string | null;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    registry?: string;
+}): Promise<string | null>;

package/lib/types/services/install/install-types.d.ts

@@ -12,6 +12,8 @@ export interface InstallResult {
     error: string | null;
     stdout: string;
     stderr: string;
+    /** 实际执行安装用的 npm 源（换源重试后是最终那一个）：后续读元数据的注解要跟它同源 */
+    registry?: string;
 }
 export interface InstallTask {
     id: number;
@@ -44,6 +46,9 @@ export interface InstallTask {
     needsReload?: boolean;
     /** 自更新成功、但该 profile 的 dsh.profile.bundles 已不含 dsh-plugin：重启后市场不会出现 */
     bundleDeselected?: boolean;
+    /** 安装/更新成功后，从 profile 的 node_modules 读到的**实际**版本。
+     *  客户端用它写版本账本（目录版本可能滞后，抄目录字段会让「有更新」永久失真）。 */
+    installedVersion?: string;
     /** 卸载入队时该包是否带客户端 UI（`dsh.client`）：卸载后包已从磁盘删除，只能入队前快照，
      *  卸载成功且曾存活时据此决定是否需要刷新页面摘除插件面板。 */
     hadClientUi?: boolean;

package/lib/types/services/install/registry-fallback.d.ts

@@ -12,6 +12,8 @@ export declare function userNpmRegistry(cwd: string): string;
 /**
  * 传输层失败才值得换源：超时、连接重置、DNS、5xx。
  * 404 / 版本不存在 / 鉴权失败必须保持原样 —— 换源只会掩盖作者侧问题或装到滞后版本。
+ * 本机证书链不被信任（TLS 校验失败）同样不换源：换哪个公共镜像都会以同样方式失败，
+ * 白白多等两轮超时、把真正的根因淹进换源噪音里。
  */
 export declare function isTransportFailure(text: string): boolean;
 /** 日志里展示用的源主机名（不打印可能带凭据的完整 URL）。 */

package/lib/types/services/install/task-queue.d.ts

@@ -77,6 +77,11 @@ export declare function startPluginMutation(options: {
      *  必须钉住安装，不能再用 @latest 被带回门禁内的最新版 */
     installSpec?: string;
 }): InstallTask;
+/**
+ * 安装成功后从 profile 的 `node_modules/<pkg>/package.json` 读**实际**版本；
+ * 定位不到包名或读不到返回 null。客户端拿它写版本账本 —— 目录里的版本可能滞后。
+ */
+export declare function installedVersionOf(profile: string, target: string): string | null;
 /**
  * 安装后校验已装包里 package.json 声明的文件（main / exports["."].default 与
  * dsh.bundle.patch）是否真实存在。npm 包也可能漏发构建产物（lib/ 等），pnpm 装完没有

package/lib/types/services/npm-release-age.d.ts

@@ -11,5 +11,5 @@ export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 export declare function latestReleaseOf(packument: unknown): NpmRelease | null;
 /** 请求体 → 去重后的合法包名列表；非数组 / 超量 / 含非法包名一律 null（拒绝非法输入）。 */
 export declare function parseReleaseAgeRequest(body: unknown): string[] | null;
-/** 查询一个包的最新版本与发布时间（成功结果缓存，同会话内同包不重复请求）；registry 为空回退官方源，失败返回 null。 */
+/** 查询一个包的最新版本与发布时间（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
 export declare function lookupReleaseAge(packageName: string, registry: string, proxy: string, timeoutMs?: number): Promise<NpmRelease | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 10000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：10000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",