dsh-plugin 2.3.1 → 2.3.3

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

@@ -3,14 +3,16 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * npm 包最新版本的发布时间查询：为「已安装插件是否有更新」提供供应链门禁依据。
- * pnpm 对发布不满 24h（dsh profile minimumReleaseAge=1440）的版本会静默回退到旧版本，
- * 因此发布未满门槛的版本不该提示更新（否则用户点了也装不上）。
+ * npm 包最新版本的发布时间查询：为「已安装插件是否有更新」提供发布冷却期依据。
+ * pnpm 对发布不满 24h（dsh profile minimumReleaseAge=1440）的版本会不提示地回退到旧版本，
+ * 因此发布还不满 24 小时的版本不该提示更新（否则用户点了也装不上）。
  * 结果按包名内存缓存，同一次会话内不重复请求；失败/超时/响应过大一律返回 null，绝不抛错、绝不阻塞。
  */
 import { get as httpsGet } from 'node:https';
 import { validPackageName } from './profile/profile.js';
 import { fetchViaCurl } from './probe.js';
+/** pnpm profile 默认 minimumReleaseAge=1440 分钟；+30 分钟缓冲与客户端 release-age 判定同一套规则。 */
+export const MIN_RELEASE_AGE_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000;
 /** 请求体包名数量上限：只为已安装插件按需查询，几十个足矣，封顶防滥用。 */
 export const MAX_RELEASE_AGE_PACKAGES = 50;
 /** 单包查询超时（ms）：慢网络下失败即返回 null，不拖住整个响应。 */
@@ -20,7 +22,7 @@ const MAX_PACKUMENT_BYTES = 10 * 1024 * 1024;
 export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
 /** 会话内缓存（源 + 包名 → 结果）：只存成功结果，一次网络抖动不会把判断永久粘住。
  *  必须带过期时间 —— 插件中心可能连续开着几小时，作者发了新版本后不能一直沿用旧结果；
- *  也必须把源算进键 —— 同一个包在官方源与镜像上的 latest / 发布时间不同，混用会算错门禁。 */
+ *  也必须把源算进键 —— 同一个包在官方源与镜像上的 latest / 发布时间不同，混用会算错冷却期。 */
 const CACHE_TTL_MS = 10 * 60 * 1000;
 const releaseCache = new Map();
 /** 从完整 packument 取 dist-tags.latest 对应版本及其发布时间；缺任一字段返回 null。 */
@@ -38,6 +40,39 @@ export function latestReleaseOf(packument) {
         return null;
     return { version, publishedAt };
 }
+/**
+ * 已过发布冷却期的最高稳定版本：安装锁定它，pnpm 不会回退到旧版本。
+ * 只看纯 x.y.z（预发布版不参与，避免把用户带到不兼容预览版）；时间表缺失或无满足项返回 null。
+ */
+export function installableReleaseOf(packument, now = Date.now()) {
+    if (packument === null || typeof packument !== 'object')
+        return null;
+    const time = packument.time;
+    if (time === null || typeof time !== 'object')
+        return null;
+    let best = null;
+    for (const [version, published] of Object.entries(time)) {
+        if (!/^\d+\.\d+\.\d+$/.test(version) || typeof published !== 'string')
+            continue;
+        const at = Date.parse(published);
+        if (Number.isNaN(at) || now - at < MIN_RELEASE_AGE_MS)
+            continue;
+        if (best === null || compareVersion(version, best.version) > 0)
+            best = { version, publishedAt: published };
+    }
+    return best;
+}
+/** 纯数字段版本比较（installableReleaseOf 只在 x.y.z 里用）。 */
+function compareVersion(a, b) {
+    const pa = a.split('.');
+    const pb = b.split('.');
+    for (let i = 0; i < 3; i++) {
+        const d = Number.parseInt(pa[i] ?? '0', 10) - Number.parseInt(pb[i] ?? '0', 10);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
 /** 请求体 → 去重后的合法包名列表；非数组 / 超量 / 含非法包名一律 null（拒绝非法输入）。 */
 export function parseReleaseAgeRequest(body) {
     if (body === null || typeof body !== 'object')
@@ -91,7 +126,7 @@ function getJson(url, timeoutMs) {
         req.on('error', () => finish(null));
     });
 }
-/** 拉取一个包的完整 packument 正文；配了代理时复用与安装/目录同一套代理口径（curl 子进程注入 proxy env）。 */
+/** 拉取一个包的完整 packument 正文；配了代理时复用与安装/目录同一套代理规则（curl 子进程注入 proxy env）。 */
 async function fetchPackument(url, proxy, timeoutMs) {
     if (proxy !== '') {
         const r = await fetchViaCurl(url, proxy, timeoutMs);
@@ -99,7 +134,7 @@ async function fetchPackument(url, proxy, timeoutMs) {
     }
     return getJson(url, timeoutMs);
 }
-/** 查询一个包的最新版本与发布时间（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
+/** 查询一个包的最新版本、发布时间与可锁定的安装版本（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
 export async function lookupReleaseAge(packageName, registry, proxy, timeoutMs = RELEASE_AGE_TIMEOUT_MS) {
     const base = registry.replace(/\/+$/, '') || DEFAULT_NPM_REGISTRY;
     const key = `${base}\n${packageName}`;
@@ -116,8 +151,10 @@ export async function lookupReleaseAge(packageName, registry, proxy, timeoutMs =
     catch {
         return null;
     }
-    const release = latestReleaseOf(parsed);
-    if (release !== null)
-        releaseCache.set(key, { at: Date.now(), release });
+    const latest = latestReleaseOf(parsed);
+    if (latest === null)
+        return null;
+    const release = { ...latest, installable: installableReleaseOf(parsed) };
+    releaseCache.set(key, { at: Date.now(), release });
     return release;
 }

package/lib/services/probe.js

@@ -30,13 +30,13 @@ export function curlTlsArgs() {
 export function curlRevokeFlagUnsupported(code, stderr) {
     return code === 2 && /ssl-revoke-best-effort/i.test(stderr) && /unknown|unrecognized/i.test(stderr);
 }
-/** 彻底关闭证书吊销检查的兜底参数（curl ≥ 7.19），比降级参数覆盖更老的 Windows curl。 */
+/** 彻底关闭证书吊销检查的保底参数（curl ≥ 7.19），比降级参数覆盖更老的 Windows curl。 */
 const NO_REVOKE_ARG = '--ssl-no-revoke';
 /** stderr 是否指向 Schannel 取不到证书吊销信息（据此归因为环境 TLS 问题，而非网络不通）。 */
 export function tlsRevocationBlocked(stderr) {
     return /CRYPT_E_NO_REVOCATION_CHECK|CRYPT_E_REVOCATION_OFFLINE|0x80092012/i.test(stderr);
 }
-/** 探测/安装同一套代理口径：curl 与 git 子进程都读 HTTP(S)_PROXY 环境变量。 */
+/** 探测/安装同一套代理规则：curl 与 git 子进程都读 HTTP(S)_PROXY 环境变量。 */
 function proxyEnv(proxy) {
     if (proxy === '')
         return { ...process.env };
@@ -132,11 +132,11 @@ function runCurl(args, env, timeoutMs) {
         child.stderr.on('data', (c) => { stderr += c.toString(); });
         child.on('error', () => finish(null));
         child.on('close', (code) => finish(code));
-        // 超时兜底：curl --max-time 到点自行退出，此处再设一个进程级超时防止悬挂
+        // 超时保护：curl --max-time 到点自行退出，此处再设一个进程级超时防止悬挂
         const timer = setTimeout(() => { child.kill(); finish(null); }, timeoutMs + 1000);
     });
 }
-/** 带 TLS 兜底的 curl 调用：先按平台参数跑（Windows 带吊销检查降级），
+/** 带 TLS 重试的 curl 调用：先按平台参数跑（Windows 带吊销检查降级），
  *  若本机 curl 不认这个参数（curl < 7.70）则去掉参数重跑一次，保证老版本不因此直接失败；
  *  降级后仍被吊销检查拦死（CRYPT_E_NO_REVOCATION_CHECK）时，再用 --ssl-no-revoke
  *  彻底关掉吊销检查跑一次 —— 该参数 curl ≥ 7.19 即存在，覆盖面比降级参数更广，
@@ -150,7 +150,7 @@ async function curlWithTlsFallback(args, env, timeoutMs) {
     }
     if (tlsArgs.length > 0 && tlsRevocationBlocked(run.stderr)) {
         const retry = await runCurl([NO_REVOKE_ARG, ...args], env, timeoutMs);
-        // 只在兜底本身跑起来（非「不认识该参数」）时采用其结果，否则保留原始失败线索
+        // 只在重试本身跑起来（非「不认识该参数」）时采用其结果，否则保留原始失败线索
         if (retry.code !== null && !curlRevokeFlagUnsupported(retry.code, retry.stderr))
             run = retry;
     }
@@ -158,7 +158,7 @@ async function curlWithTlsFallback(args, env, timeoutMs) {
 }
 /**
  * curl 子进程探测：spawn curl -s -w '%{http_code}' 并注入代理 env。
- * curl 读 HTTP_PROXY/HTTPS_PROXY 是原生行为，与 pnpm/git 安装通道同一套代理口径；
+ * curl 读 HTTP_PROXY/HTTPS_PROXY 是原生行为，与 pnpm/git 安装通道同一套代理规则；
  * 失败（curl 不存在 / 连接失败 / 超时）都归为不可达，全程不抛错。
  * 证书吊销检查受阻（Windows Schannel）另记 reason，供诊断给出对症提示。
  */
@@ -219,7 +219,7 @@ export function gitLsRemote(url, proxy, timeoutMs) {
         const child = spawn('git', ['ls-remote', '--exit-code', url, 'HEAD'], { env });
         let out = '';
         child.stdout.on('data', (c) => { out += c.toString(); });
-        // git 的报错不透传给终端：结果以退出码 + HEAD ref 是否返回为准
+        // git 的报错不原样传递给终端：结果以退出码 + HEAD ref 是否返回为准
         child.stderr.on('data', () => { });
         let done = false;
         const finish = (r) => {
@@ -235,14 +235,14 @@ export function gitLsRemote(url, proxy, timeoutMs) {
             // status 复用为 git 退出码（0 = 克隆握手成功）；客户端 git 行不把它显示成 HTTP 码
             finish({ ok, ms: Date.now() - started, status: code });
         });
-        // 超时兜底：与 curlProbe 同口径，防止 git 挂起
+        // 超时保护：与 curlProbe 同一套规则，防止 git 挂起
         const timer = setTimeout(() => { child.kill(); finish(probeFail()); }, timeoutMs + 1000);
     });
 }
 /**
  * 请求一个 URL 并返回重定向后的最终地址（curl -I -L -w %{url_effective}）。
  * 供 GitHub 仓库改名解析使用：对已改名仓库 GitHub 回 301，跟随跳转后的最终地址
- * 即规范地址。与其它 GitHub 访问同口径 —— curl 子进程注入代理 env（Node 内置
+ * 即规范地址。与其它 GitHub 访问同一套规则 —— curl 子进程注入代理 env（Node 内置
  * http(s) 读不到系统代理，直连在部分网络下不可达）。
  * 未发生跳转（200/404）、网络失败或 curl 不可用都返回 null，调用方保留原始地址。
  */
@@ -257,11 +257,11 @@ export async function finalUrl(url, proxy, timeoutMs) {
     return r.code === 0 && final !== '' ? final : null;
 }
 /**
- * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入与 TLS 参数兜底）。
+ * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入与 TLS 参数重试）。
  * 供服务端 /catalog 代理路由使用：目录/统计数据经此拉到服务端再转给浏览器，
- * 使「目录数据请求走设置里的代理」与 npm / git 安装通道口径一致。
+ * 使「目录数据请求走设置里的代理」与 npm / git 安装通道规则一致。
  * 失败（curl 不存在 / 连接失败 / 超时 / 非零退出）时 ok=false，全程不抛错；
- * reason 区分「证书吊销受阻」这类环境 TLS 问题，供调用方决定兜底策略。
+ * reason 区分「证书吊销受阻」这类环境 TLS 问题，供调用方决定备用策略。
  */
 export function fetchViaCurl(url, proxy, timeoutMs) {
     // 同样用 -sS：正文之外还要 stderr 里的 TLS 失败线索（被 stderr 收集，不外泄给用户）。

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

@@ -65,7 +65,7 @@ export function recordInstalledVersion(profile, repo, version, updatedAt) {
 export function recordResolvedNpmPackage(profile, repo, npmPackage) {
     const table = readInstalledVersions(profile);
     const key = repo.toLowerCase();
-    // 显式写全字段：这一步发生在安装开始时，版本还不知道 —— 但落盘记录必须是完整形状，
+    // 显式写全字段：这一步发生在安装开始时，版本还不知道 —— 但写入磁盘记录必须是完整形状，
     // 否则只带 npmPackage 的残缺记录会在客户端版本比较时崩掉整块界面
     table[key] = {
         version: table[key]?.version ?? '',
@@ -85,7 +85,7 @@ function writeVersions(profile, table) {
     const file = versionsFilePath(profile);
     mkdirSync(dirname(file), { recursive: true });
     // 先写临时文件再原子替换：直接覆盖时进程被杀/磁盘满会留下截断的 JSON，
-    // 下次读取整份账本都会失效（更新检测静默停摆），而用户看不到任何报错
+    // 下次读取整份账本都会失效（更新检测随之失效），而用户看不到任何报错
     const tmp = `${file}.tmp`;
     writeFileSync(tmp, JSON.stringify(table, null, 2) + '\n', 'utf8');
     renameSync(tmp, file);

package/lib/services/profile/profile.js

@@ -77,7 +77,7 @@ export function githubTarget(repo, ref) {
  * 非命令输入原样返回。兼容「直接粘贴完整命令」（防用户输错）：--profile 必填且只有长选项
  * （官方 CLI 无 -p 简写，省略即报错），支持 `--profile=<name>` 等号形式，命令大小写不敏感。
  * update = 更新已安装目标到最新；remove 不在此列（卸载走 /uninstall 路由，按已装包名直卸）。
- * 与客户端 CustomInstallView 口径一致。
+ * 与客户端 CustomInstallView 规则一致。
  */
 const DSH_PLUGIN_CMD_RE = /^dsh\s+plugin\s+--profile(?:\s+|=)\S+\s+(add|update)\s+(.+)$/i;
 export function installTargetOf(value) {
@@ -88,7 +88,7 @@ export function installTargetOf(value) {
 /**
  * npm 全局安装命令（官方 README 的 `npm install -g <pkgs>`，如 dsh-tui 的安装命令）——
  * 提取 -g 之后的包列表。支持 `npm install|i` 与 `-g|--global`；任一包名非法（或格式
- * 不匹配）返回 null，由调用方按「不支持的目标」处理。与客户端 CustomInstallView 同口径。
+ * 不匹配）返回 null，由调用方按「不支持的目标」处理。与客户端 CustomInstallView 同一套规则。
  */
 const NPM_GLOBAL_CMD_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(.+)$/i;
 export function globalNpmPackagesOf(value) {

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

@@ -6,5 +6,5 @@ export declare function versionOf(output: string): string | 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 时兜底）。探测成功即缓存，失败不缓存以便下次重试。 */
+ *  （dsh 不在 PATH 时使用）。探测成功即缓存，失败不缓存以便下次重试。 */
 export declare function hostDshVersion(): string | null;

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

@@ -34,14 +34,14 @@ export interface InstallTask {
     status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
     timedOut: boolean;
     exitCode: number | null;
-    /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
+    /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出；没有进度行时按阶段行估算 */
     progress: number;
     /** 输出行最新在前（消费方展示尾部）。 */
     lines: string[];
-    /** 完成后是否仍需宿主重启才生效：仅「热挂载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
-     *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
+    /** 完成后是否仍需宿主重启才生效：仅「热加载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
+     *  无 loader」等刷新解决不了的例外场景为 true（弹窗给「立即重启」）；其余一律 false。 */
     needsRestart: boolean;
-    /** 完成结果是否只需刷新页面即生效（插件已热挂进运行中 loader，仅剩客户端 UI 待页面重新加载，
+    /** 完成结果是否只需刷新页面即生效（插件已热加载进运行中 loader，仅剩客户端 UI 待页面重新加载，
      *  网页端与桌面端一致）：true 时关闭结果弹窗即自动刷新页面，不给手动刷新按钮。 */
     needsReload?: boolean;
     /** 自更新成功、但该 profile 的 dsh.profile.bundles 已不含 dsh-plugin：重启后市场不会出现 */
@@ -75,7 +75,7 @@ export interface QueueItem {
         installChannel?: 'npm';
         /** npm 源候选（首选在前）：传输层失败时按顺序换源重试 */
         registries?: string[];
-        /** 精确安装 spec（Hub 自我更新钉版本） */
+        /** 精确安装 spec（Hub 自我更新时锁定版本） */
         installSpec?: string;
     };
 }

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

@@ -18,7 +18,7 @@ export declare function hasSubstantiveOutput(output: string): boolean;
 /**
  * 运行期抓取：宿主的 operation 日志只在命令运行期间存在，结束后可能被清理，
  * 退出后再按路径读往往已经拿不到。这里在安装过程中轮询 profile 下最新的
- * `.plugin-manager/logs/<operation>/pnpm.log`，用抓到的内容兜底。
+ * `.plugin-manager/logs/<operation>/pnpm.log`，用抓到的内容补全。
  * 只认本次运行产生的新文件（mtime 晚于启动基线），避免复述上一次安装的日志。
  */
 export declare function createOperationLogTap(profileDir: string): {

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

@@ -1,7 +1,7 @@
 /** 缺 git 的失败标记：前端按 `[git-missing]` 归类并给「安装 git」指引（乱码免疫）。 */
 export declare const GIT_MISSING_DETAIL = "[git-missing] the git CLI was not found on this machine (install git and add it to the PATH, then retry)";
 /** 命令存在性探测：which/where 找 PATH 里的命令。
- *  探测自身异常（which/where 不可用等）返回 true，不拦截安装，交给装后校验兜底。 */
+ *  探测自身异常（which/where 不可用等）返回 true，不拦截安装，交给装后校验处理。 */
 export declare function commandOnPath(cmd: string, env?: NodeJS.ProcessEnv): boolean;
 /** 该安装目标是否需要 git：github: / git+ / git@ 与 owner/repo 简写都要先 clone；
  *  release 直链（https://…releases/download/…tgz）由 pnpm 直接下载，不需要 git。

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

@@ -4,7 +4,7 @@ export declare function normalizeRegistry(value: string): string;
 export declare function isPublicRegistry(value: string): boolean;
 /**
  * 依次尝试的源：显式配置 → 本机 npm 配置 → 官方源。
- * 只有公共源才追加后备（最多 3 个）；关闭降级或源不在白名单时只返回它自己。
+ * 只有公共源才追加后备（最多 3 个）；关闭换源或源不在白名单时只返回它自己。
  */
 export declare function registryCandidates(configured: string, userRegistry: string, enabled: boolean): string[];
 /** 本机 npm 实际生效的源（含 profile 目录的 .npmrc）；读不到返回空串。 */

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

@@ -6,7 +6,7 @@
  * 预构建 release 直链的仓库身份解析。部分插件（如 loopx）当初以 GitHub release 的 .tgz
  * 安装过，仓库 HEAD 反而是 monorepo 根、走 git 直装会因缺入口文件失败；老安装记录里留的
  * 就是这种 release 直链。这里把「历史安装目标」还原成所属仓库身份，供已装态读回、队列
- * 去重与展示复用（单一事实来源，避免两端口径漂移）。
+ * 去重与展示复用（单一事实来源，避免两端规则漂移）。
  *
  * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
  * 输入是记录/展示数据、绝非 shell 代码，绝不执行其文本；跨仓跳转、外部主机、凭据、

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

@@ -39,7 +39,7 @@ export declare function cancelTask(id: number): boolean;
  */
 export declare function desktopCliBootstrap(entry: string): string | null;
 /**
- * 传给 CLI 的安装目标：钉住版本优先（Hub 自我更新提示的是已过供应链门禁的版本），
+ * 传给 CLI 的安装目标：锁定版本优先（Hub 自我更新提示的是已过发布冷却期的版本），
  * 其次 npm 的 add/update 都显式 `@latest`；git 源、全局安装、已带版本/tag 的 spec 保持原样。
  */
 export declare function npmInstallTargetOf(target: string, opts: {
@@ -48,6 +48,9 @@ export declare function npmInstallTargetOf(target: string, opts: {
     pinned?: string;
     add?: boolean;
 }): string;
+/** 重复卸载：目标已不在 profile 依赖里，pnpm 报「没有这个依赖」。
+ *  结果与卸载成功等价 —— 按失败上报会弹出错误并自动提一条不存在的 Issue。 */
+export declare function isAlreadyRemoved(action: 'add' | 'remove' | 'update', output: string): boolean;
 /**
  * 插件变更入队并返回其任务。任务严格串行：队列 worker 只在上一个结束后才启动下一个。
  * 完成前可通过 `getTask(id)` / `activeTask()` 查看进度。
@@ -62,7 +65,7 @@ export declare function startPluginMutation(options: {
     globalNpm?: string[];
     /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
     displayTarget?: string;
-    /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
+    /** 运行中 loader：安装成功后热加载新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
      *  （缺失时安装/卸载仍需重启） */
     loader?: LoaderHandle;
     /** 入队前已尝试的安装方式：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
@@ -72,10 +75,10 @@ export declare function startPluginMutation(options: {
     /** 自定义安装入口渠道（NPM 包卡片）：任务输出行与系统日志据此溯源「从哪个入口发起」；
      *  目录插件安装不传 */
     installChannel?: 'npm';
-    /** npm 源候选（首选在前）：传输层失败时按顺序换源重试，空/单个表示不降级 */
+    /** npm 源候选（首选在前）：传输层失败时按顺序换源重试，空/单个表示不换源 */
     registries?: string[];
-    /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：Hub 自我更新提示的是已过供应链门禁的版本，
-     *  必须钉住安装，不能再用 @latest 被带回门禁内的最新版 */
+    /** 精确安装 spec（如 `dsh-plugin@2.0.5`）：Hub 自我更新提示的是已过发布冷却期的版本，
+     *  必须锁定安装，不能再用 @latest 被带回冷却期内的最新版 */
     installSpec?: string;
 }): InstallTask;
 /**
@@ -102,7 +105,7 @@ export declare function verifyInstalledEntry(profile: string, target: string): {
  */
 export declare function hostSpawnMarker(invocation: Invocation, error: unknown): string | null;
 /**
- * 执行插件变更，带一条恢复路径：当 `add` 因 pnpm 的 allowBuilds 门禁拦下构建脚本而失败 ——
+ * 执行插件变更，带一条恢复路径：当 `add` 因 pnpm 的 allowBuilds 限制拦下构建脚本而失败 ——
  * 或是 git 源包自己的 `prepare`（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，key 取自打印的
  * key@url 提示），或是某依赖的原生构建（`ERR_PNPM_IGNORED_BUILDS`，key = 列出的 name@version）——
  * 就把确切的 key 写进 profile 的 pnpm-workspace.yaml 并重试一次。
@@ -117,7 +120,7 @@ export declare function runPluginMutation(options: {
     task?: InstallTask;
     /** 待重启行的展示目标（owner/repo）：卸载时用于把 npm 包名映射回仓库名 */
     displayTarget?: string;
-    /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目（缺失时仍需重启） */
+    /** 运行中 loader：安装成功后热加载新条目、卸载成功后停用旧条目（缺失时仍需重启） */
     loader?: LoaderHandle;
     /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
     globalNpm?: string[];

package/lib/types/services/loader.d.ts

@@ -1,5 +1,5 @@
 /**
- * 运行中 loader 的最小接口：卸载即时停用 / 安装即时热挂载用。
+ * 运行中 loader 的最小接口：卸载即时停用 / 安装即时热加载用。
  * 对应官方 `ctx.loader`（cordis-plugin-loader 的 Loader 服务）的读取、新建与移除面。
  * 移除方式：对匹配条目 live-disable（`entry.update({ disabled: true })`），
  * 而不是 `loader.remove(id)` —— disable 走 Entry.update 的 disabled 分支，不触发
@@ -28,7 +28,7 @@ export interface LoaderHandle {
         id?: string;
         name: string;
     }): Promise<string>;
-    /** 按 id 解析条目：热挂载后确认 fiber 真的起来了（import 失败时条目在、但 fiber 为空）。 */
+    /** 按 id 解析条目：热加载后确认 fiber 真的起来了（import 失败时条目在、但 fiber 为空）。 */
     resolve(id: string): {
         id: string;
         options?: {
@@ -59,7 +59,7 @@ export declare function isEntryLoaded(loader: LoaderHandle | undefined, name: st
  *  - `{ ok: true, live: false }`：宿主从未加载过它（磁盘已干净），无需刷新/重启；
  *  - `{ ok: true, live: true }`：曾在 loader 中存活且已 live-disable —— 服务端即时卸载；
  *    带客户端 UI 的插件面板要页面刷新才摘除（由调用方按 `hadClientUi` 决定 needsReload）；
- *  - `{ ok: false, live: true }`：disable 失败 / 超时，需宿主重启兜底清理。
+ *  - `{ ok: false, live: true }`：disable 失败 / 超时，需宿主重启后清理。
  * 宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
  */
 export declare function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<{
@@ -67,7 +67,7 @@ export declare function removeLoadedEntry(loader: LoaderHandle, name: string): P
     live: boolean;
 }>;
 /**
- * 安装成功后把新插件热挂进运行中 loader（等价 profile bundle patch 的
+ * 安装成功后把新插件热加载进运行中 loader（等价 profile bundle patch 的
  * `- insert: - name: <pkg>` 行），让插件无需重启宿主即可生效。
  * 做法：在 Loader 根组新建条目并启动 —— Loader.write() 为空实现，不写盘；
  * 重启后由 profile 的 bundles 清单重新挂载，不会重复。
@@ -78,7 +78,7 @@ export declare function removeLoadedEntry(loader: LoaderHandle, name: string): P
 export declare function mountLoadedEntry(loader: LoaderHandle, name: string): Promise<boolean>;
 /**
  * 已安装包是否带客户端 UI（package.json 的 `dsh.client` 声明）：client-modules 据它把
- * 客户端 bundle 注入宿主页面。带 UI 的插件热挂载后需要页面重新加载才会渲染，
+ * 客户端 bundle 注入宿主页面。带 UI 的插件热加载后需要页面重新加载才会渲染，
  * 网页端与桌面端一致 —— `__DSH_BOOT__` 注入清单由宿主服务端按请求现场拼装，
  * 壳不缓存，所以桌面端刷新页面同样能拿到新清单，无需重开 App。
  */

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

@@ -2,6 +2,13 @@ export interface NpmRelease {
     version: string;
     publishedAt: string;
 }
+/** 最新版 + 可锁定的安装版本：安装锁定后者，pnpm 才不会回退到旧版本。 */
+export interface NpmReleaseWithInstallable extends NpmRelease {
+    /** 已过发布冷却期的最高稳定版；时间表缺失或没有满足项时为 null（调用方退回不锁定版本）。 */
+    installable: NpmRelease | null;
+}
+/** pnpm profile 默认 minimumReleaseAge=1440 分钟；+30 分钟缓冲与客户端 release-age 判定同一套规则。 */
+export declare const MIN_RELEASE_AGE_MS: number;
 /** 请求体包名数量上限：只为已安装插件按需查询，几十个足矣，封顶防滥用。 */
 export declare const MAX_RELEASE_AGE_PACKAGES = 50;
 /** 单包查询超时（ms）：慢网络下失败即返回 null，不拖住整个响应。 */
@@ -9,7 +16,12 @@ export declare const RELEASE_AGE_TIMEOUT_MS = 8000;
 export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 /** 从完整 packument 取 dist-tags.latest 对应版本及其发布时间；缺任一字段返回 null。 */
 export declare function latestReleaseOf(packument: unknown): NpmRelease | null;
+/**
+ * 已过发布冷却期的最高稳定版本：安装锁定它，pnpm 不会回退到旧版本。
+ * 只看纯 x.y.z（预发布版不参与，避免把用户带到不兼容预览版）；时间表缺失或无满足项返回 null。
+ */
+export declare function installableReleaseOf(packument: unknown, now?: number): NpmRelease | null;
 /** 请求体 → 去重后的合法包名列表；非数组 / 超量 / 含非法包名一律 null（拒绝非法输入）。 */
 export declare function parseReleaseAgeRequest(body: unknown): string[] | null;
-/** 查询一个包的最新版本与发布时间（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
-export declare function lookupReleaseAge(packageName: string, registry: string, proxy: string, timeoutMs?: number): Promise<NpmRelease | null>;
+/** 查询一个包的最新版本、发布时间与可锁定的安装版本（成功结果按源缓存 10 分钟）；registry 为空回退官方源，失败返回 null。 */
+export declare function lookupReleaseAge(packageName: string, registry: string, proxy: string, timeoutMs?: number): Promise<NpmReleaseWithInstallable | null>;

package/lib/types/services/probe.d.ts

@@ -63,17 +63,17 @@ export declare function gitLsRemote(url: string, proxy: string, timeoutMs: numbe
 /**
  * 请求一个 URL 并返回重定向后的最终地址（curl -I -L -w %{url_effective}）。
  * 供 GitHub 仓库改名解析使用：对已改名仓库 GitHub 回 301，跟随跳转后的最终地址
- * 即规范地址。与其它 GitHub 访问同口径 —— curl 子进程注入代理 env（Node 内置
+ * 即规范地址。与其它 GitHub 访问同一套规则 —— curl 子进程注入代理 env（Node 内置
  * http(s) 读不到系统代理，直连在部分网络下不可达）。
  * 未发生跳转（200/404）、网络失败或 curl 不可用都返回 null，调用方保留原始地址。
  */
 export declare function finalUrl(url: string, proxy: string, timeoutMs: number): Promise<string | null>;
 /**
- * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入与 TLS 参数兜底）。
+ * curl 子进程抓取响应体（与 probeUrl 同一套代理 env 注入与 TLS 参数重试）。
  * 供服务端 /catalog 代理路由使用：目录/统计数据经此拉到服务端再转给浏览器，
- * 使「目录数据请求走设置里的代理」与 npm / git 安装通道口径一致。
+ * 使「目录数据请求走设置里的代理」与 npm / git 安装通道规则一致。
  * 失败（curl 不存在 / 连接失败 / 超时 / 非零退出）时 ok=false，全程不抛错；
- * reason 区分「证书吊销受阻」这类环境 TLS 问题，供调用方决定兜底策略。
+ * reason 区分「证书吊销受阻」这类环境 TLS 问题，供调用方决定备用策略。
  */
 export declare function fetchViaCurl(url: string, proxy: string, timeoutMs: number): Promise<{
     ok: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "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",