dsh-m 0.1.0 → 0.2.0

package/lib/core/market.js

@@ -1,15 +1,157 @@
 /**
- * 市场编排层：registry × profile × 最新版本 → 市场列表 / 已装列表 / outdated /
- * 安装 / 卸载 / 升级。安装语义见 DESIGN.md §3（npm 精确锁定、GitHub 锁 SHA）。
+ * 市场编排层：registry × profile × 最新版本 → 市场列表（服务端分页）/ 已装列表 /
+ * 安装 / 升级。安装语义见 DESIGN.md §3（npm 精确锁定、GitHub 锁 SHA）。
+ * Task 3：服务端 query/category/offset/limit 过滤；只对当前页查 latest（并发 ≤8、
+ * TTL cache、共享全局 deadline）；unavailable 返回结构化空页；host/cli namespace 贯穿。
  */
 import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { addDshPlugin } from './dsh-cli.js';
-import { dshHome, webProfileDir } from './env.js';
-import { listInstalledPlugins, readProfileDeps, removeInstalledPlugin, } from './installed.js';
+import { addDshPlugin, removeDshPlugin, runCommand } from './dsh-cli.js';
+import { dshHome, installTimeoutMs, webProfileDir } from './env.js';
+import { assertNpmIntegrity, readPnpmLockIntegrity, restoreSnapshots, snapshotFiles } from './npm-integrity.js';
+import { listInstalledPlugins as defaultListInstalledPlugins, readProfileDeps, removeInstalledPlugin, } from './installed.js';
 import { setLivePluginDisabled } from './live-plugin.js';
-import { loadRegistry } from './registry.js';
-import { githubHeadSha, isNewerVersion, npmLatest } from './versions.js';
+import { loadRegistry as defaultLoadRegistry, } from './registry.js';
+import { githubLatestTag as defaultGithubLatestTag, isNewerVersion, npmLatest as defaultNpmLatest, npmVersion } from './versions.js';
+// ---------- 通用工具 ----------
+const DEFAULT_DEADLINE_MS = 60_000;
+const WITH_LATEST_MAX = 50;
+const METADATA_ONLY_MAX = 80;
+const LATEST_WORKERS = 8;
+export function abortError() {
+    const err = new Error('Aborted');
+    err.name = 'AbortError';
+    return err;
+}
+/** 稳定顺序的并发 map：结果顺序与输入一致，in-flight ≤ limit。 */
+export async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const size = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+    const runners = Array.from({ length: size }, async () => {
+        for (;;) {
+            const index = next;
+            if (index >= items.length)
+                return;
+            next += 1;
+            results[index] = await worker(items[index], index);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
+function zeroCounts() {
+    return { market: 0, tools: 0, ui: 0, search: 0, media: 0, other: 0 };
+}
+function clampLimit(raw, max) {
+    const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.floor(raw) : max;
+    return Math.min(max, Math.max(1, n));
+}
+function normalizeOffset(raw) {
+    const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.floor(raw) : 0;
+    return n > 0 ? n : 0;
+}
+function stateOf(loaded) {
+    return {
+        configuredAddress: loaded.configuredAddress,
+        activeAddress: loaded.activeAddress,
+        source: loaded.source,
+        status: loaded.status,
+        isDefault: loaded.isDefault,
+        stale: loaded.stale,
+        fetchedAt: loaded.fetchedAt,
+        errors: loaded.errors,
+        count: loaded.count,
+    };
+}
+function timeoutRegistryState(cfg) {
+    const configuredAddress = typeof cfg.registryUrl === 'string' ? cfg.registryUrl.trim() : '';
+    return {
+        configuredAddress,
+        activeAddress: null,
+        source: configuredAddress === '' ? 'default-cache' : 'custom-unavailable',
+        status: 'unavailable',
+        isDefault: configuredAddress === '',
+        stale: false,
+        fetchedAt: null,
+        errors: ['registry 加载超出 deadline'],
+        count: 0,
+    };
+}
+function deadlineRace(task, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve('deadline'), Math.max(0, ms));
+        task.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+const latestCache = new Map();
+const LATEST_CACHE_MAX = 5000;
+function latestCacheKey(namespace, registryKey, item) {
+    const id = item.source === 'npm' && item.npm ? `npm:${item.npm}` : item.github ? `gh:${item.github}` : item.id;
+    return `${namespace}|${registryKey}|${id}`;
+}
+function readLatestCache(key, ttlMin) {
+    const entry = latestCache.get(key);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.at >= ttlMin * 60_000) {
+        latestCache.delete(key);
+        return null;
+    }
+    return entry.value;
+}
+function writeLatestCache(key, value) {
+    if (latestCache.size >= LATEST_CACHE_MAX) {
+        const oldest = latestCache.keys().next().value;
+        if (oldest !== undefined)
+            latestCache.delete(oldest);
+    }
+    latestCache.set(key, { at: Date.now(), value });
+}
+function probeTask(item, deps, timeoutMs, signal) {
+    if (item.source === 'npm' && item.npm) {
+        return deps.npmLatest(item.npm, timeoutMs, signal).then((r) => ({ version: r.version }));
+    }
+    return deps.githubLatestTag(item.github, timeoutMs, signal).then((r) => ({ tag: r.tag, sha: r.sha }));
+}
+/**
+ * 单个 probe 的 deadline 收敛：即使依赖忽略 AbortSignal 也通过 race 返回。
+ * 外部 signal abort → 抛 AbortError（由上层终止整次请求）。
+ */
+async function probeWithBudget(task, budgetMs, signal) {
+    let timer;
+    const timeoutP = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ ok: false, timeout: true }), Math.max(1, budgetMs));
+    });
+    const safeTask = task.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+    const abortP = signal
+        ? new Promise((_, reject) => {
+            signal.addEventListener('abort', () => reject(abortError()), { once: true });
+        })
+        : null;
+    try {
+        return await Promise.race(abortP ? [safeTask, timeoutP, abortP] : [safeTask, timeoutP]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function applyProbe(item, value) {
+    if (value.version !== undefined)
+        item.latestVersion = value.version;
+    if (value.tag !== undefined)
+        item.latestTag = value.tag;
+    if (value.sha !== undefined)
+        item.latestSha = value.sha;
+}
 function matchInstalledByEntry(entry, installed) {
     return installed.find((it) => {
         if (entry.npm && it.pkg === entry.npm)
@@ -24,125 +166,356 @@ function matchInstalledByEntry(entry, installed) {
         return false;
     });
 }
-export async function listMarket(cfg = {}, opts = {}) {
-    const [loaded, installed] = await Promise.all([
-        loadRegistry(cfg, opts),
-        listInstalledPlugins(),
-    ]);
-    const timeoutMs = cfg.timeoutMs ?? 20_000;
-    const items = [];
-    for (const entry of loaded.registry.plugins) {
-        const inst = matchInstalledByEntry(entry, installed.items);
-        const item = {
-            ...entry,
-            installed: Boolean(inst),
-            outdated: false,
+// ---------- 市场列表 ----------
+function marketDeps() {
+    return {
+        loadRegistry: defaultLoadRegistry,
+        listInstalledPlugins: defaultListInstalledPlugins,
+        npmLatest: defaultNpmLatest,
+        githubLatestTag: defaultGithubLatestTag,
+    };
+}
+export async function listMarket(cfg = {}, opts = {}, deps = {}) {
+    const d = { ...marketDeps(), ...deps };
+    const startedAt = Date.now();
+    const deadlineMs = typeof opts.deadlineMs === 'number' && Number.isFinite(opts.deadlineMs) && opts.deadlineMs > 0
+        ? opts.deadlineMs
+        : DEFAULT_DEADLINE_MS;
+    const deadlineAt = startedAt + deadlineMs;
+    const namespace = opts.namespace ?? 'host';
+    const withLatest = opts.withLatest !== false;
+    const maxLimit = withLatest ? WITH_LATEST_MAX : METADATA_ONLY_MAX;
+    const signal = opts.signal;
+    const remaining = () => deadlineAt - Date.now();
+    const registryTask = d.loadRegistry(cfg, { namespace, signal, force: opts.force, deadlineMs });
+    const installedTask = d.listInstalledPlugins().catch(() => null);
+    let loaded;
+    try {
+        loaded = await deadlineRace(registryTask, remaining());
+    }
+    catch (err) {
+        void installedTask;
+        throw err;
+    }
+    if (loaded === 'deadline') {
+        void installedTask;
+        return {
+            items: [],
+            total: 0,
+            offset: 0,
+            limit: maxLimit,
+            categoryCounts: zeroCounts(),
+            registryState: timeoutRegistryState(cfg),
+            installedComplete: false,
+            latestComplete: false,
+            latestTimedOut: true,
+        };
+    }
+    const registryState = stateOf(loaded);
+    if (loaded.status === 'unavailable') {
+        void installedTask;
+        return {
+            items: [],
+            total: 0,
+            offset: 0,
+            limit: maxLimit,
+            categoryCounts: zeroCounts(),
+            registryState,
+            installedComplete: false,
+            latestComplete: false,
+            latestTimedOut: false,
         };
+    }
+    const installed = await installedTask;
+    const installedComplete = installed !== null;
+    const installedItems = installed?.items ?? [];
+    // 全量统计 + query/category 过滤 + 分页（同步，极轻）
+    const all = loaded.registry.plugins;
+    const counts = zeroCounts();
+    for (const entry of all)
+        counts[entry.category] += 1;
+    const q = (opts.query ?? '').trim().toLowerCase();
+    const cat = opts.category ?? null;
+    const filtered = all.filter((entry) => {
+        if (cat && entry.category !== cat)
+            return false;
+        if (!q)
+            return true;
+        return `${entry.id} ${entry.name} ${entry.description} ${entry.tags.join(' ')}`.toLowerCase().includes(q);
+    });
+    const total = filtered.length;
+    const limit = clampLimit(opts.limit, maxLimit);
+    let offset = normalizeOffset(opts.offset);
+    if (total > 0 && offset >= total)
+        offset = Math.floor((total - 1) / limit) * limit;
+    const items = filtered.slice(offset, offset + limit).map((entry) => {
+        const inst = matchInstalledByEntry(entry, installedItems);
+        const item = { ...entry, installed: Boolean(inst), outdated: false };
         if (inst) {
             item.installedPkg = inst.pkg;
             item.installedVersion = inst.version;
         }
-        try {
-            if (entry.source === 'npm' && entry.npm) {
-                const latest = await npmLatest(entry.npm, timeoutMs);
-                item.latestVersion = latest.version;
-                if (inst?.version && isNewerVersion(latest.version, inst.version))
-                    item.outdated = true;
+        return item;
+    });
+    let latestComplete = true;
+    let latestTimedOut = false;
+    if (withLatest && items.length > 0) {
+        // 先吃 cache 命中
+        const ttlMin = Math.max(0, cfg.cacheTtlMin ?? 60);
+        for (const item of items) {
+            const cached = readLatestCache(latestCacheKey(namespace, loaded.configuredAddress, item), ttlMin);
+            if (cached)
+                applyProbe(item, cached);
+        }
+        const todo = items.filter((it) => it.latestVersion === undefined && it.latestTag === undefined && it.latestSha === undefined);
+        if (todo.length > 0) {
+            const budget = remaining();
+            if (budget <= 0) {
+                for (const item of todo)
+                    item.latestErrorCode = 'LATEST_TIMEOUT';
+                latestComplete = false;
+                latestTimedOut = true;
             }
-            else if (entry.github) {
-                const sha = await githubHeadSha(entry.github, timeoutMs);
-                item.latestSha = sha;
-                if (inst && !inst.spec.includes(sha))
-                    item.outdated = true;
+            else {
+                await mapWithConcurrency(todo, LATEST_WORKERS, async (item) => {
+                    const perBudget = Math.max(1, remaining());
+                    const task = probeTask(item, d, Math.min(cfg.timeoutMs ?? 20_000, perBudget), signal);
+                    const outcome = await probeWithBudget(task, perBudget, signal);
+                    if (outcome.ok && outcome.value) {
+                        applyProbe(item, outcome.value);
+                        writeLatestCache(latestCacheKey(namespace, loaded.configuredAddress, item), outcome.value);
+                    }
+                    else if (outcome.timeout) {
+                        item.latestErrorCode = 'LATEST_TIMEOUT';
+                        latestComplete = false;
+                        latestTimedOut = true;
+                    }
+                    else if (outcome.error !== undefined) {
+                        if (signal?.aborted)
+                            throw abortError();
+                        item.latestError = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+                        item.latestErrorCode = 'LATEST_ERROR';
+                    }
+                });
             }
         }
-        catch (err) {
-            item.latestError = err instanceof Error ? err.message : String(err);
+        // outdated 判定统一在 probe 后进行
+        for (const item of items) {
+            const inst = item.installedPkg !== undefined ? installedItems.find((i) => i.pkg === item.installedPkg) : undefined;
+            if (!inst)
+                continue;
+            if (item.latestVersion !== undefined && inst.version) {
+                item.outdated = isNewerVersion(item.latestVersion, inst.version);
+            }
+            else if (item.latestSha !== undefined) {
+                item.outdated = !inst.spec.includes(item.latestSha);
+            }
         }
-        items.push(item);
     }
-    return {
-        items,
-        registrySource: loaded.source,
-        registryFetchedAt: loaded.fetchedAt,
-        registryErrors: loaded.errors,
-    };
+    return { items, total, offset, limit, categoryCounts: counts, registryState, installedComplete, latestComplete, latestTimedOut };
 }
-export async function listInstalledWithMeta(cfg = {}) {
-    const [{ items: installed, others, profileDir }, loaded] = await Promise.all([
-        listInstalledPlugins(),
-        loadRegistry(cfg),
-    ]);
-    const timeoutMs = cfg.timeoutMs ?? 20_000;
-    const items = [];
-    for (const it of installed) {
-        const entry = loaded.registry.plugins.find((e) => matchInstalledByEntry(e, [it]));
-        const item = { ...it, outdated: false };
-        if (entry)
+// ---------- 已装列表 ----------
+export async function listInstalledWithMeta(cfg = {}, opts = {}, deps = {}) {
+    const d = { ...marketDeps(), ...deps };
+    const startedAt = Date.now();
+    const deadlineMs = typeof opts.deadlineMs === 'number' && Number.isFinite(opts.deadlineMs) && opts.deadlineMs > 0
+        ? opts.deadlineMs
+        : DEFAULT_DEADLINE_MS;
+    const deadlineAt = startedAt + deadlineMs;
+    const namespace = opts.namespace ?? 'host';
+    const signal = opts.signal;
+    const remaining = () => deadlineAt - Date.now();
+    const installedPromise = d.listInstalledPlugins();
+    const registryTask = d.loadRegistry(cfg, { namespace, signal, force: opts.force, deadlineMs });
+    const installed = await installedPromise;
+    const items = installed.items.map((it) => ({ ...it, outdated: false }));
+    let loaded;
+    try {
+        loaded = await deadlineRace(registryTask, remaining());
+    }
+    catch {
+        loaded = 'deadline';
+    }
+    if (loaded === 'deadline' || loaded.status === 'unavailable') {
+        // registry 不可用：不做 matching，直接返回已装列表
+        const registryState = loaded === 'deadline' ? timeoutRegistryState(cfg) : stateOf(loaded);
+        return { items, others: installed.others, profileDir: installed.profileDir, registryState };
+    }
+    const registryState = stateOf(loaded);
+    const ttlMin = Math.max(0, cfg.cacheTtlMin ?? 60);
+    await mapWithConcurrency(items, LATEST_WORKERS, async (item) => {
+        const entry = loaded.registry.plugins.find((e) => matchInstalledByEntry(e, [item]));
+        if (entry) {
             item.registryId = entry.id;
-        try {
-            if (!entry && it.source === 'npm') {
-                const latest = await npmLatest(it.pkg, timeoutMs);
-                item.latestVersion = latest.version;
-                item.outdated = isNewerVersion(latest.version, it.version);
-            }
-            else if (entry?.source === 'npm' && entry.npm) {
-                const latest = await npmLatest(entry.npm, timeoutMs);
-                item.latestVersion = latest.version;
-                item.outdated = isNewerVersion(latest.version, it.version);
+            item.registryGithub = entry.github ?? null;
+            item.registryIcon = entry.icon ?? null;
+        }
+        // latest 探测沿用 listMarket 的 TTL cache
+        const cacheKey = entry
+            ? latestCacheKey(namespace, loaded.configuredAddress, entry)
+            : item.source === 'npm'
+                ? `npm-only|${namespace}|npm:${item.pkg}`
+                : null;
+        if (cacheKey) {
+            const cached = readLatestCache(cacheKey, ttlMin);
+            if (cached) {
+                applyProbe(item, cached);
             }
-            else if (it.source === 'github') {
-                const m = /^github:([^#]+)/.exec(it.spec);
-                if (m) {
-                    const sha = await githubHeadSha(m[1], timeoutMs);
-                    item.outdated = !it.spec.includes(sha);
+            else if (remaining() > 0) {
+                const budget = Math.max(1, remaining());
+                try {
+                    let value = null;
+                    if (!entry && item.source === 'npm') {
+                        const latest = await d.npmLatest(item.pkg, Math.min(cfg.timeoutMs ?? 20_000, budget), signal);
+                        value = { version: latest.version };
+                    }
+                    else if (entry?.source === 'npm' && entry.npm) {
+                        const latest = await d.npmLatest(entry.npm, Math.min(cfg.timeoutMs ?? 20_000, budget), signal);
+                        value = { version: latest.version };
+                    }
+                    else if (item.source === 'github') {
+                        const m = /^github:([^#]+)/.exec(item.spec);
+                        if (m) {
+                            const latest = await d.githubLatestTag(m[1], Math.min(cfg.timeoutMs ?? 20_000, budget), signal);
+                            value = { tag: latest.tag, sha: latest.sha };
+                        }
+                    }
+                    if (value) {
+                        applyProbe(item, value);
+                        writeLatestCache(cacheKey, value);
+                    }
+                }
+                catch (err) {
+                    item.latestError = err instanceof Error ? err.message : String(err);
                 }
             }
         }
-        catch {
-            /* 查询失败不阻塞列表，outdated 维持 false */
-        }
-        items.push(item);
-    }
-    return { items, others, profileDir };
+        if (item.latestVersion !== undefined && item.version)
+            item.outdated = isNewerVersion(item.latestVersion, item.version);
+        else if (item.latestSha !== undefined)
+            item.outdated = !item.spec.includes(item.latestSha);
+    });
+    return { items, others: installed.others, profileDir: installed.profileDir, registryState };
+}
+async function defaultRestoreInstall(profileDir) {
+    return runCommand('pnpm', ['--dir', profileDir, 'install', '--frozen-lockfile'], { timeoutMs: installTimeoutMs() });
 }
 /** 从 registry 收录条目安装（npm → 精确锁定最新版；github → 锁 HEAD SHA）。 */
-export async function installFromRegistry(id, cfg = {}, opts = {}) {
-    const { registry } = await loadRegistry(cfg);
-    const entry = registry.plugins.find((e) => e.id === id);
+export async function installFromRegistry(id, cfg = {}, opts = {}, deps) {
+    const loaded = await (deps?.loadRegistry ?? defaultLoadRegistry)(cfg, { namespace: opts.namespace ?? 'host' });
+    if (loaded.status === 'unavailable') {
+        throw new Error(`收录清单不可用，无法安装 ${id}；请检查 registry 配置或网络后重试`);
+    }
+    const entry = loaded.registry.plugins.find((e) => e.id === id);
     if (!entry)
         throw new Error(`registry 中没有该条目: ${id}`);
-    return installEntry(entry, cfg, opts);
+    return installEntry(entry, cfg, opts, deps);
 }
-export async function installEntry(entry, cfg = {}, opts = {}) {
+export async function installEntry(entry, cfg = {}, opts = {}, deps) {
     const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const d = {
+        npmLatest: deps?.npmLatest ?? defaultNpmLatest,
+        npmVersion: deps?.npmVersion ?? npmVersion,
+        addDshPlugin: deps?.addDshPlugin ?? addDshPlugin,
+        removeDshPlugin: deps?.removeDshPlugin ?? removeDshPlugin,
+        readProfileDeps: deps?.readProfileDeps ?? readProfileDeps,
+        readLockIntegrity: deps?.readLockIntegrity ?? readPnpmLockIntegrity,
+        restoreInstall: deps?.restoreInstall ?? defaultRestoreInstall,
+    };
+    const profileDir = deps?.profileDir ?? webProfileDir();
     if (entry.source === 'npm' && entry.npm) {
-        const version = opts.version && /^\d+\.\d+\.\d+/.test(opts.version) ? opts.version : (await npmLatest(entry.npm, timeoutMs)).version;
-        const spec = `${entry.npm}@${version}`;
-        const res = await addDshPlugin(spec);
-        // 安装后校验：落盘版本必须与意图一致（tarball 完整性由 pnpm 按 lock integrity 保证）
-        const deps = await readProfileDeps(webProfileDir());
-        const specInProfile = deps[entry.npm];
-        if (specInProfile === undefined)
-            throw new Error(`安装后未在 profile 依赖中找到 ${entry.npm}`);
-        return {
-            id: entry.id,
-            pkg: entry.npm,
-            spec,
-            version,
-            usedAllowAllBuilds: res.usedAllowAllBuilds,
-            needsRestart: true,
-            output: res.output.slice(-800),
-        };
+        const pkg = entry.npm;
+        // npm：无论 latest 还是用户指定 exact，都先读取该精确版本的 dist metadata
+        let version;
+        let expectedIntegrity;
+        if (opts.version) {
+            const meta = await d.npmVersion(pkg, opts.version, timeoutMs, opts.signal);
+            version = meta.version;
+            expectedIntegrity = meta.integrity;
+        }
+        else {
+            const latest = await d.npmLatest(pkg, timeoutMs, opts.signal);
+            version = latest.version;
+            expectedIntegrity = latest.integrity;
+        }
+        if (!expectedIntegrity)
+            throw new Error(`npm metadata 缺少 dist integrity：${pkg}@${version}，拒绝安装`);
+        const spec = `${pkg}@${version}`;
+        // 安装前快照：失败时 best-effort 依赖回滚的依据
+        const snapshots = await snapshotFiles([
+            join(profileDir, 'package.json'),
+            join(profileDir, 'pnpm-lock.yaml'),
+            join(profileDir, 'pnpm-workspace.yaml'),
+        ]);
+        try {
+            const res = await d.addDshPlugin(spec);
+            const depsNow = await d.readProfileDeps(profileDir);
+            if (depsNow[pkg] === undefined)
+                throw new Error(`安装后未在 profile 依赖中找到 ${pkg}`);
+            if (depsNow[pkg] !== version)
+                throw new Error(`profile 依赖版本 ${depsNow[pkg]} 与目标 ${version} 不一致`);
+            let lockText;
+            try {
+                lockText = await readFile(join(profileDir, 'pnpm-lock.yaml'), 'utf8');
+            }
+            catch {
+                throw new Error('安装后未找到 pnpm-lock.yaml，无法核对 integrity');
+            }
+            const actual = d.readLockIntegrity(lockText, pkg, version);
+            assertNpmIntegrity(expectedIntegrity, actual, pkg, version);
+            return {
+                id: entry.id,
+                pkg,
+                spec,
+                version,
+                usedAllowAllBuilds: res.usedAllowAllBuilds,
+                needsRestart: true,
+                output: res.output.slice(-800),
+            };
+        }
+        catch (err) {
+            // best-effort rollback：原子恢复 manifest/lock/workspace 快照，再 frozen-lockfile 重装
+            let rollbackError = null;
+            try {
+                await restoreSnapshots(snapshots);
+                await d.restoreInstall(profileDir);
+            }
+            catch (rerr) {
+                rollbackError = rerr instanceof Error ? rerr.message : String(rerr);
+                // 原先不存在该依赖且恢复安装失败：尝试移除
+                const originallyAbsent = snapshots[0] && snapshots[0].existed && (() => {
+                    try {
+                        return !JSON.parse(snapshots[0].bytes.toString('utf8'))?.dependencies?.[pkg];
+                    }
+                    catch {
+                        return false;
+                    }
+                })();
+                if (originallyAbsent) {
+                    try {
+                        await d.removeDshPlugin(pkg);
+                        rollbackError = null;
+                    }
+                    catch (rmErr) {
+                        rollbackError = `${rollbackError}；移除 ${pkg} 也失败（${rmErr instanceof Error ? rmErr.message : String(rmErr)}）`;
+                    }
+                }
+            }
+            if (rollbackError) {
+                throw new Error(`integrity 校验失败（${err instanceof Error ? err.message : String(err)}）；依赖回滚也失败（${rollbackError}），profile 可能需要人工修复`);
+            }
+            throw new Error(`integrity 校验失败，已回滚到安装前状态：${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     if (entry.github) {
-        const sha = await githubHeadSha(entry.github, timeoutMs);
+        const { tag, sha } = await defaultGithubLatestTag(entry.github, timeoutMs, opts.signal);
         const spec = `github:${entry.github}#${sha}`;
-        const res = await addDshPlugin(spec);
-        const deps = await readProfileDeps(webProfileDir());
-        const pkgKey = Object.keys(deps).find((k) => deps[k] === spec || deps[k].startsWith(`github:${entry.github}#`));
+        const res = await d.addDshPlugin(spec);
+        const depsNow = await d.readProfileDeps(profileDir);
+        const pkgKey = Object.keys(depsNow).find((k) => depsNow[k] === spec || depsNow[k].startsWith(`github:${entry.github}#`));
         if (!pkgKey)
             throw new Error(`安装后未在 profile 依赖中找到 ${entry.github}`);
+        void tag;
         return {
             id: entry.id,
             pkg: pkgKey,
@@ -156,24 +529,28 @@ export async function installEntry(entry, cfg = {}, opts = {}) {
     throw new Error(`条目 ${entry.id} 缺少可安装来源`);
 }
 /** 卸载：live-disable → pnpm remove → 报告疑似残留（DESIGN.md §3：删包不删数据）。 */
-export async function uninstallPlugin(pkg, _cfg = {}) {
+export async function uninstallPlugin(pkg, _cfg = {}, _opts = {}) {
     const liveDisabled = await setLivePluginDisabled(pkg, true);
     await removeInstalledPlugin(pkg);
     return { pkg, liveDisabled, needsRestart: true, leftovers: leftoverCandidates(pkg) };
 }
 /** 升级 = 按最新重新安装（npm 拉最新精确版；github 重新锁 HEAD）。 */
-export async function upgradePlugin(pkg, cfg = {}) {
-    const { registry } = await loadRegistry(cfg);
-    const { items: installed } = await listInstalledPlugins();
+export async function upgradePlugin(pkg, cfg = {}, opts = {}, deps) {
+    const loaded = await (deps?.loadRegistry ?? defaultLoadRegistry)(cfg, { namespace: opts.namespace ?? 'host' });
+    if (loaded.status === 'unavailable') {
+        throw new Error(`收录清单不可用，无法升级 ${pkg}；请检查 registry 配置或网络后重试`);
+    }
+    const { items: installed } = await (deps?.listInstalledPlugins ?? defaultListInstalledPlugins)();
     const target = installed.find((it) => it.pkg === pkg);
     if (!target)
         throw new Error(`web profile 未安装该插件: ${pkg}`);
-    const entry = registry.plugins.find((e) => matchInstalledByEntry(e, [target]));
+    const entry = loaded.registry.plugins.find((e) => matchInstalledByEntry(e, [target]));
     if (!entry)
         throw new Error(`「${pkg}」不是经 dsh-m 收录的插件；直接升级请用 dsh plugin update 或先在 registry 收录它`);
-    const result = await installEntry(entry, cfg);
+    const result = await installEntry(entry, cfg, opts, deps);
     return { ...result, fromVersion: target.version };
 }
+// ---------- 变更互斥 ----------
 /** 变更互斥：安装/卸载/升级串行执行（skillhub install-lock 同款思路）。 */
 let mutationTail = Promise.resolve();
 export function withMutationLock(task) {