wave-agent-sdk 1.2.0 → 1.3.0

package/dist/services/MarketplaceService.js

@@ -1,8 +1,11 @@
 import { promises as fs, existsSync, mkdirSync } from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
+import { AsyncLocalStorage } from "async_hooks";
 import { getPluginsDir } from "../utils/configPaths.js";
 import { GitService } from "./GitService.js";
+import { parsePluginSource, describePluginSource, } from "../utils/pluginSource.js";
+import { DEFAULT_PLUGIN_VERSION } from "../constants/plugins.js";
 import { ALLOW_OFFICIAL_MARKET_GIT_FALLBACK, fetchOfficialMarketplaceFromMirror, } from "./officialMarketplaceMirror.js";
 import { ConfigurationService } from "./configurationService.js";
 import { logger, logError, logWarn } from "../utils/globalLogger.js";
@@ -17,6 +20,8 @@ import { logger, logError, logWarn } from "../utils/globalLogger.js";
  */
 export class MarketplaceService {
     constructor(workdir = process.cwd(), configurationService = new ConfigurationService()) {
+        /** In-flight [refreshMarketplaces] call (single-flight, spec 插件市场 场景 13). */
+        this.refreshInFlight = null;
         this.workdir = workdir;
         this.configurationService = configurationService;
         this.pluginsDir = getPluginsDir();
@@ -59,7 +64,6 @@ export class MarketplaceService {
                         continue;
                     const config = {
                         source: m.source,
-                        autoUpdate: m.autoUpdate,
                     };
                     await this.configurationService.addMarketplaceToScope(this.workdir, "user", m.name, config);
                 }
@@ -82,12 +86,11 @@ export class MarketplaceService {
             // Add to user-scope settings if not already in any scope
             const scoped = this.configurationService.getMergedMarketplaces(this.workdir);
             if (!scoped[builtin.name]) {
-                await this.configurationService.addMarketplaceToScope(this.workdir, "user", builtin.name, { source: builtin.source, autoUpdate: builtin.autoUpdate });
+                await this.configurationService.addMarketplaceToScope(this.workdir, "user", builtin.name, { source: builtin.source });
             }
             // Update cache: add entry + set builtinSeeded flag
             await this.updateCacheMarketplace(builtin.name, {
                 source: builtin.source,
-                autoUpdate: builtin.autoUpdate,
                 isBuiltin: true,
                 declaredScope: "builtin",
             });
@@ -133,10 +136,10 @@ export class MarketplaceService {
     }
     /**
      * Acquires a file-based lock (with PID tracking for stale lock detection) and executes the provided function.
-     * Supports re-entrancy within the same process.
+     * Supports re-entrancy within the same call chain (see [lockChain]).
      */
     async withLock(fn) {
-        if (MarketplaceService.isLockedInProcess) {
+        if (MarketplaceService.lockChain.getStore()) {
             return await fn();
         }
         let lockFd;
@@ -169,12 +172,10 @@ export class MarketplaceService {
             throw new Error(`Failed to acquire marketplace lock after ${maxRetries} retries. If no other wave-agent process is running, please delete ${this.lockPath}`);
         }
         await fs.writeFile(this.lockPath, String(process.pid), "utf-8");
-        MarketplaceService.isLockedInProcess = true;
         try {
-            return await fn();
+            return await MarketplaceService.lockChain.run(true, fn);
         }
         finally {
-            MarketplaceService.isLockedInProcess = false;
             await lockFd.close();
             await fs.unlink(this.lockPath).catch(() => { });
         }
@@ -283,6 +284,36 @@ export class MarketplaceService {
         await fs.writeFile(tmpPath, JSON.stringify(registry, null, 2));
         await fs.rename(tmpPath, this.installedPluginsPath);
     }
+    /**
+     * Whether an install record belongs to the given install location.
+     *
+     * Records written before scopes were tracked carry no `scope`; they stand for
+     * "installed once on this machine" and match any scope, so uninstalling them
+     * keeps working (they are that plugin's only record). They still match by
+     * project path, so records of two different projects stay distinguishable.
+     */
+    matchesInstallLocation(entry, location) {
+        if (!entry.scope) {
+            return (entry.projectPath === undefined ||
+                entry.projectPath === location.projectPath);
+        }
+        return (entry.scope === location.scope &&
+            entry.projectPath === location.projectPath);
+    }
+    /**
+     * The install location a record is keyed by. Scope-less legacy records are
+     * treated as user-scope when they have to be re-created (e.g. by an update).
+     */
+    locationOf(entry) {
+        return { scope: entry.scope ?? "user", projectPath: entry.projectPath };
+    }
+    describeInstallLocations(entries) {
+        return entries
+            .map((entry) => entry.scope
+            ? `${entry.scope}${entry.projectPath ? ` (${entry.projectPath})` : ""}`
+            : "unscoped")
+            .join(", ");
+    }
     /**
      * Loads a marketplace manifest from a local path
      */
@@ -326,7 +357,6 @@ export class MarketplaceService {
         return {
             name,
             source: config.source,
-            autoUpdate: config.autoUpdate ?? cache?.autoUpdate,
             lastUpdated: cache?.lastUpdated,
             isBuiltin: name === MarketplaceService.BUILTIN_MARKETPLACE.name,
             declaredScope,
@@ -346,6 +376,53 @@ export class MarketplaceService {
             return "builtin";
         return null;
     }
+    /**
+     * 已注册的市场（作用域配置 + 缓存注册表合并去重），用于添加前的判重
+     */
+    async listRegisteredMarketplaces() {
+        const scoped = this.configurationService.getMergedMarketplaces(this.workdir);
+        const registered = Object.entries(scoped).map(([name, config]) => ({
+            name,
+            source: config.source,
+        }));
+        const cache = await this.getCacheRegistry();
+        for (const entry of cache?.marketplaces ?? []) {
+            if (!registered.some((m) => m.name === entry.name)) {
+                registered.push({ name: entry.name, source: entry.source });
+            }
+        }
+        return registered;
+    }
+    /**
+     * 添加市场前判重（spec ecosystem/plugin「设置页插件市场」场景 16）：来源重复或
+     * 清单声明的名称与已有市场同名时不允许添加。只传 source 时仅判来源（用于克隆
+     * 之前，避免为一个已存在的来源白克隆一次）。
+     */
+    async assertMarketplaceAddable(source, name) {
+        const registered = await this.listRegisteredMarketplaces();
+        const sameSource = registered.find((m) => MarketplaceService.isSameMarketplaceSource(m.source, source));
+        if (sameSource) {
+            throw new Error(`该市场来源已添加：${sameSource.name}`);
+        }
+        if (name && registered.some((m) => m.name === name)) {
+            throw new Error(`同名市场已存在：${name}`);
+        }
+    }
+    /** 两个市场来源是否指向同一处（同类型比 url/repo/path，忽略 ref） */
+    static isSameMarketplaceSource(a, b) {
+        if (a.source !== b.source)
+            return false;
+        if (a.source === "directory" && b.source === "directory") {
+            return a.path === b.path;
+        }
+        if (a.source === "github" && b.source === "github") {
+            return a.repo === b.repo;
+        }
+        if (a.source === "git" && b.source === "git") {
+            return a.url === b.url;
+        }
+        return false;
+    }
     /**
      * Adds a new marketplace (local directory, GitHub repo, or Git URL)
      */
@@ -368,6 +445,7 @@ export class MarketplaceService {
                 const tempSource = isFullUrl
                     ? { source: "git", url: urlOrRepo, ref }
                     : { source: "github", repo: urlOrRepo, ref };
+                await this.assertMarketplaceAddable(tempSource);
                 const targetPath = this.getMarketplacePath(tempSource);
                 if (!existsSync(targetPath)) {
                     try {
@@ -389,12 +467,15 @@ export class MarketplaceService {
                     source: isFullUrl
                         ? { source: "git", url: urlOrRepo, ref }
                         : { source: "github", repo: urlOrRepo, ref },
-                    autoUpdate: false,
                     lastUpdated: new Date().toISOString(),
                 };
             }
             else {
                 const absolutePath = path.resolve(input);
+                await this.assertMarketplaceAddable({
+                    source: "directory",
+                    path: absolutePath,
+                });
                 let manifest;
                 try {
                     manifest = await this.loadMarketplaceManifest(absolutePath);
@@ -405,19 +486,18 @@ export class MarketplaceService {
                 marketplace = {
                     name: manifest.name,
                     source: { source: "directory", path: absolutePath },
-                    autoUpdate: false,
                     lastUpdated: new Date().toISOString(),
                 };
             }
+            // 名称来自市场自身清单，加载后才知道 → 同名判重放在这里（来源判重已在分支内）
+            await this.assertMarketplaceAddable(marketplace.source, marketplace.name);
             const config = {
                 source: marketplace.source,
-                autoUpdate: marketplace.autoUpdate,
             };
             await this.configurationService.addMarketplaceToScope(this.workdir, scope, marketplace.name, config);
             // Update cache with metadata
             await this.updateCacheMarketplace(marketplace.name, {
                 source: marketplace.source,
-                autoUpdate: marketplace.autoUpdate,
                 lastUpdated: marketplace.lastUpdated,
             });
             return marketplace;
@@ -497,8 +577,18 @@ export class MarketplaceService {
     }
     /**
      * Updates a specific marketplace or all marketplaces
+     *
+     * `refreshCheckout` (default true) pulls the checkout from its upstream; pass
+     * false to upgrade plugins against the current checkout only — the interactive
+     * "批量更新插件" path does that, because opening the plugin-marketplace surface
+     * already refreshed the checkout (spec 插件市场 A-013).
+     *
+     * Returns the number of installed plugins whose version actually changed
+     * during this run (0 = everything was already up to date) — the GUI hosts
+     * use it to tell "已更新 N 个插件" apart from "已是最新" (spec 插件市场 场景 13).
      */
     async updateMarketplace(name, options) {
+        const refreshCheckout = options?.refreshCheckout ?? true;
         return this.withLock(async () => {
             const marketplaces = await this.listMarketplaces();
             const toUpdate = name
@@ -509,65 +599,76 @@ export class MarketplaceService {
             }
             const isGitAvailable = await this.gitService.isGitAvailable();
             const errors = [];
+            let upgradedPlugins = 0;
             for (const marketplace of toUpdate) {
                 try {
-                    // Builtin official marketplace: prefer the zip-snapshot mirror
-                    // (content-addressed zip over a plain HTTP base, no git/GitHub
-                    // needed). Only the builtin is special-cased by name — its
-                    // `source` stays "github" in settings/cache, so there is zero
-                    // data migration. On mirror failure (e.g. prod URL not yet live)
-                    // fall back to the git path unless the kill switch forbids it.
-                    const isOfficialBuiltin = marketplace.name === MarketplaceService.BUILTIN_MARKETPLACE.name;
-                    let mirrorUpdated = false;
-                    if (isOfficialBuiltin) {
-                        const targetPath = this.getMarketplacePath(marketplace.source);
-                        const mirrorSha = await fetchOfficialMarketplaceFromMirror(targetPath, this.marketplacesDir);
-                        if (mirrorSha !== null) {
-                            mirrorUpdated = true;
-                        }
-                        else if (!ALLOW_OFFICIAL_MARKET_GIT_FALLBACK) {
-                            logWarn(`Skipping update for official marketplace "${marketplace.name}": mirror fetch failed and git fallback is disabled.`);
-                            continue;
-                        }
-                    }
-                    if (marketplace.source.source === "github" ||
-                        marketplace.source.source === "git") {
-                        if (!mirrorUpdated) {
-                            if (!isGitAvailable) {
-                                logWarn(`Skipping update for Git/GitHub marketplace "${marketplace.name}" because Git is not installed.`);
-                                continue;
+                    const targetPath = this.getMarketplacePath(marketplace.source);
+                    if (refreshCheckout) {
+                        // Builtin official marketplace: prefer the zip-snapshot mirror
+                        // (content-addressed zip over a plain HTTP base, no git/GitHub
+                        // needed). Only the builtin is special-cased by name — its
+                        // `source` stays "github" in settings/cache, so there is zero
+                        // data migration. Both envs' mirror channels are live and carry
+                        // content (verified 2026-09-23); on mirror failure
+                        // (network/timeout/404/bad content) fall back to the git path
+                        // unless the kill switch forbids it.
+                        const isOfficialBuiltin = marketplace.name === MarketplaceService.BUILTIN_MARKETPLACE.name;
+                        let mirrorUpdated = false;
+                        if (isOfficialBuiltin) {
+                            const mirrorSha = await fetchOfficialMarketplaceFromMirror(targetPath, this.marketplacesDir);
+                            if (mirrorSha !== null) {
+                                mirrorUpdated = true;
                             }
-                            const targetPath = this.getMarketplacePath(marketplace.source);
-                            if (existsSync(targetPath)) {
-                                await this.gitService.pull(targetPath);
+                            else if (!ALLOW_OFFICIAL_MARKET_GIT_FALLBACK) {
+                                logWarn(`Skipping update for official marketplace "${marketplace.name}": mirror fetch failed and git fallback is disabled.`);
+                                continue;
                             }
-                            else {
-                                let url;
-                                if (marketplace.source.source === "github") {
-                                    url = marketplace.source.repo;
+                        }
+                        if (marketplace.source.source === "github" ||
+                            marketplace.source.source === "git") {
+                            if (!mirrorUpdated) {
+                                if (!isGitAvailable) {
+                                    logWarn(`Skipping update for Git/GitHub marketplace "${marketplace.name}" because Git is not installed.`);
+                                    continue;
+                                }
+                                if (existsSync(targetPath)) {
+                                    await this.gitService.pull(targetPath);
                                 }
                                 else {
-                                    url = marketplace.source.url;
+                                    let url;
+                                    if (marketplace.source.source === "github") {
+                                        url = marketplace.source.repo;
+                                    }
+                                    else {
+                                        url = marketplace.source.url;
+                                    }
+                                    await this.gitService.clone(url, targetPath, marketplace.source.ref);
                                 }
-                                await this.gitService.clone(url, targetPath, marketplace.source.ref);
                             }
                         }
                     }
-                    const manifest = await this.loadMarketplaceManifest(this.getMarketplacePath(marketplace.source));
-                    marketplace.lastUpdated = new Date().toISOString();
-                    // Update cache metadata
-                    await this.updateCacheMarketplace(marketplace.name, {
-                        lastUpdated: marketplace.lastUpdated,
-                    });
+                    const manifest = await this.loadMarketplaceManifest(targetPath);
+                    // 只在真的刷了检出时记账：跳过刷新时把 lastUpdated 顶到当前时间会
+                    // 让 CLI 的市场列表谎报「上次更新」时间。
+                    if (refreshCheckout) {
+                        marketplace.lastUpdated = new Date().toISOString();
+                        // Update cache metadata
+                        await this.updateCacheMarketplace(marketplace.name, {
+                            lastUpdated: marketplace.lastUpdated,
+                        });
+                    }
                     if (options?.updatePlugins) {
                         const installedRegistry = await this.getInstalledPlugins();
                         const pluginsToUpdate = installedRegistry.plugins.filter((p) => p.marketplace === marketplace.name);
+                        // 升级前版本快照：安装完成后比对，只有版本真的变了的才算「已更新」
+                        // （重新安装同版本 = 无更新，宿主据此提示「已是最新」）。
+                        const versionBefore = new Map(pluginsToUpdate.map((p) => [p.name, p.version]));
                         for (const plugin of pluginsToUpdate) {
                             const pluginEntry = manifest.plugins.find((p) => p.name === plugin.name);
                             if (!pluginEntry) {
                                 logger.warn(`Plugin "${plugin.name}" no longer found in marketplace "${marketplace.name}". Uninstalling...`);
                                 try {
-                                    await this.uninstallPlugin(`${plugin.name}@${plugin.marketplace}`, plugin.projectPath);
+                                    await this.uninstallPlugin(`${plugin.name}@${plugin.marketplace}`, this.locationOf(plugin));
                                 }
                                 catch (error) {
                                     logError(`Failed to uninstall orphaned plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
@@ -575,12 +676,21 @@ export class MarketplaceService {
                                 continue;
                             }
                             try {
-                                await this.installPlugin(`${plugin.name}@${plugin.marketplace}`, plugin.projectPath);
+                                await this.installPlugin(`${plugin.name}@${plugin.marketplace}`, this.locationOf(plugin));
                             }
                             catch (error) {
                                 logError(`Failed to update plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
                             }
                         }
+                        const afterRegistry = await this.getInstalledPlugins();
+                        for (const plugin of afterRegistry.plugins) {
+                            if (plugin.marketplace !== marketplace.name)
+                                continue;
+                            const before = versionBefore.get(plugin.name);
+                            if (before !== undefined && before !== plugin.version) {
+                                upgradedPlugins++;
+                            }
+                        }
                     }
                 }
                 catch (error) {
@@ -592,53 +702,63 @@ export class MarketplaceService {
             if (errors.length > 0) {
                 throw new Error(`Some marketplaces failed to update:\n${errors.join("\n")}`);
             }
+            return upgradedPlugins;
         });
     }
     /**
-     * Automatically updates all marketplaces that have auto-update enabled
+     * 交互界面的「批量更新插件」：按当前清单把该市场内所有已安装且有新版本的插件
+     * 升级到最新，**不拉取检出**——清单的新鲜度由打开插件市场界面时的那次刷新保证
+     * （spec 插件市场 A-013/场景 14）。检出尚未据此刷新的场景（无界面可依赖的非交互
+     * 命令）走 [updateMarketplace] 的默认行为。
      */
-    async autoUpdateAll() {
-        return this.withLock(async () => {
-            const scopedMarketplaces = this.configurationService.getMergedMarketplaces(this.workdir);
-            const toAutoUpdate = Object.entries(scopedMarketplaces)
-                .filter(([, config]) => config.autoUpdate)
-                .map(([name]) => name);
-            for (const marketplaceName of toAutoUpdate) {
-                try {
-                    await this.updateMarketplace(marketplaceName, {
-                        updatePlugins: true,
-                    });
-                }
-                catch (error) {
-                    logError(`Auto-update failed for marketplace "${marketplaceName}":`, error);
-                }
-            }
+    async updateMarketplacePlugins(name) {
+        return await this.updateMarketplace(name, {
+            updatePlugins: true,
+            refreshCheckout: false,
         });
     }
     /**
-     * Toggles auto-update for a marketplace
+     * Refreshes the local checkout of every registered marketplace.
+     *
+     * Callers are the plugin-marketplace surfaces (GUI settings view / CLI plugin
+     * manager), refreshed when the user opens them — the agent-startup path no
+     * longer refreshes anything (spec 插件市场 A-013 场景 5).
+     *
+     * This is a fixed behavior with no opt-in/opt-out: `autoUpdate` no longer
+     * exists, so all marketplaces are refreshed alike (A-014). Refreshing only
+     * updates the checkout — installed plugins are never reinstalled here, so a
+     * newer plugin version surfaces as an explicit "更新" (per plugin) /
+     * "批量更新插件" (batch) action instead of being applied behind the user's
+     * back.
+     *
+     * Single-flight: a call landing while a refresh is running reuses it instead
+     * of pulling every checkout twice (spec 场景 13).
      */
-    async toggleAutoUpdate(name, enabled) {
-        return this.withLock(async () => {
-            const declaringSource = this.getMarketplaceDeclaringSource(name);
-            if (!declaringSource || declaringSource === "builtin") {
-                throw new Error(`Marketplace ${name} not found`);
-            }
-            const scoped = this.configurationService.getScopedMarketplaces(this.workdir, declaringSource);
-            const config = scoped[name];
-            if (!config) {
-                throw new Error(`Marketplace ${name} not found`);
+    async refreshMarketplaces() {
+        if (this.refreshInFlight)
+            return this.refreshInFlight;
+        this.refreshInFlight = this.withLock(async () => {
+            const marketplaces = this.configurationService.getMergedMarketplaces(this.workdir);
+            for (const marketplaceName of Object.keys(marketplaces)) {
+                try {
+                    await this.updateMarketplace(marketplaceName);
+                }
+                catch (error) {
+                    logError(`Marketplace refresh failed for "${marketplaceName}":`, error);
+                }
             }
-            config.autoUpdate = enabled;
-            await this.configurationService.addMarketplaceToScope(this.workdir, declaringSource, name, config);
-            // Also update cache
-            await this.updateCacheMarketplace(name, { autoUpdate: enabled });
+        }).finally(() => {
+            this.refreshInFlight = null;
         });
+        return this.refreshInFlight;
     }
     /**
      * Installs a plugin from a marketplace
+     *
+     * @param location 该次安装记账的位置（spec plugin A-015）。缺省只在内部调用
+     *   （宿主加载时补装）出现，此时写入一条不带作用域的历史形态记录。
      */
-    async installPlugin(pluginAtMarketplace, projectPath) {
+    async installPlugin(pluginAtMarketplace, location) {
         return this.withLock(async () => {
             const [pluginName, marketplaceName] = pluginAtMarketplace.split("@");
             if (!pluginName || !marketplaceName) {
@@ -655,25 +775,32 @@ export class MarketplaceService {
             if (!pluginEntry) {
                 throw new Error(`Plugin ${pluginName} not found in marketplace ${marketplaceName}`);
             }
-            const isGitSource = pluginEntry.source.startsWith("http://") ||
-                pluginEntry.source.startsWith("https://") ||
-                pluginEntry.source.startsWith("git@") ||
-                pluginEntry.source.startsWith("ssh://");
+            const parsedSource = parsePluginSource(pluginEntry.source);
+            if (!parsedSource) {
+                throw new Error(`Plugin ${pluginName} in marketplace ${marketplaceName} declares an unsupported source: ${describePluginSource(pluginEntry.source)}`);
+            }
+            const isGitSource = parsedSource.kind === "git";
             let pluginSrcPath;
             let tempCloneDir;
             try {
-                if (isGitSource) {
+                if (parsedSource.kind === "git") {
                     tempCloneDir = path.join(this.tmpDir, `clone-${Date.now()}`);
-                    let url = pluginEntry.source;
-                    let ref;
-                    if (url.includes("#")) {
-                        [url, ref] = url.split("#");
+                    await this.gitService.clone(parsedSource.url, tempCloneDir, parsedSource.ref);
+                    if (parsedSource.sha) {
+                        // Without this a `ref` would drift with its branch; a sha that cannot
+                        // be checked out fails loudly instead of silently using the branch tip
+                        // (spec plugin A-021 场景 3).
+                        await this.gitService.checkout(tempCloneDir, parsedSource.sha);
+                    }
+                    pluginSrcPath = parsedSource.subdir
+                        ? path.join(tempCloneDir, parsedSource.subdir)
+                        : tempCloneDir;
+                    if (parsedSource.subdir && !existsSync(pluginSrcPath)) {
+                        throw new Error(`Subdirectory '${parsedSource.subdir}' not found in repository ${parsedSource.url}`);
                     }
-                    await this.gitService.clone(url, tempCloneDir, ref);
-                    pluginSrcPath = tempCloneDir;
                 }
                 else {
-                    pluginSrcPath = path.resolve(marketplacePath, pluginEntry.source);
+                    pluginSrcPath = path.resolve(marketplacePath, parsedSource.path);
                 }
                 let pluginManifestPath = path.join(pluginSrcPath, ".wave-plugin", "plugin.json");
                 if (!existsSync(pluginManifestPath)) {
@@ -685,7 +812,7 @@ export class MarketplaceService {
                 }
                 const pluginManifestContent = await fs.readFile(pluginManifestPath, "utf-8");
                 const pluginManifest = JSON.parse(pluginManifestContent);
-                const version = pluginManifest.version || "1.0.0";
+                const version = pluginManifest.version || DEFAULT_PLUGIN_VERSION;
                 const tmpPluginDir = path.join(this.tmpDir, `${pluginName}-${Date.now()}`);
                 try {
                     if (isGitSource) {
@@ -704,13 +831,14 @@ export class MarketplaceService {
                     const installedRegistry = await this.getInstalledPlugins();
                     const existingIndex = installedRegistry.plugins.findIndex((p) => p.name === pluginName &&
                         p.marketplace === marketplaceName &&
-                        p.projectPath === projectPath);
+                        (location ? this.matchesInstallLocation(p, location) : !p.scope));
                     const installedPlugin = {
                         name: pluginName,
                         marketplace: marketplaceName,
                         version,
                         cachePath,
-                        projectPath,
+                        scope: location?.scope,
+                        projectPath: location?.projectPath,
                     };
                     if (existingIndex >= 0) {
                         installedRegistry.plugins[existingIndex] = installedPlugin;
@@ -738,45 +866,116 @@ export class MarketplaceService {
     }
     /**
      * Uninstalls a plugin
+     *
+     * With a [location], only that scope's install record is removed — other
+     * scopes (including other projects' project/local records) keep theirs, and
+     * the shared cache directory is deleted only once no record references it
+     * (spec plugin A-015). Without one, every record of the plugin is removed
+     * (used by [updatePlugin] and the marketplace-level cleanup).
      */
-    async uninstallPlugin(pluginAtMarketplace, projectPath) {
+    async uninstallPlugin(pluginAtMarketplace, location) {
         return this.withLock(async () => {
             const [pluginName, marketplaceName] = pluginAtMarketplace.split("@");
             if (!pluginName || !marketplaceName) {
                 throw new Error("Invalid plugin format. Use name@marketplace");
             }
             const installedRegistry = await this.getInstalledPlugins();
-            const pluginIndex = installedRegistry.plugins.findIndex((p) => p.name === pluginName &&
-                p.marketplace === marketplaceName &&
-                p.projectPath === projectPath);
-            if (pluginIndex === -1) {
-                throw new Error(`Plugin ${pluginName}@${marketplaceName} is not installed${projectPath ? ` for project ${projectPath}` : ""}`);
-            }
-            const pluginToRemove = installedRegistry.plugins[pluginIndex];
-            installedRegistry.plugins.splice(pluginIndex, 1);
+            const allRecords = installedRegistry.plugins.filter((p) => p.name === pluginName && p.marketplace === marketplaceName);
+            const pluginToRemove = allRecords.filter((p) => !location || this.matchesInstallLocation(p, location));
+            if (pluginToRemove.length === 0) {
+                const installedAt = this.describeInstallLocations(allRecords);
+                throw new Error(location
+                    ? `Plugin ${pluginName}@${marketplaceName} is not installed in ${location.scope} scope${location.projectPath ? ` for project ${location.projectPath}` : ""}${installedAt ? `. Installed at: ${installedAt}` : ""}`
+                    : `Plugin ${pluginName}@${marketplaceName} is not installed`);
+            }
+            const removed = new Set(pluginToRemove);
+            installedRegistry.plugins = installedRegistry.plugins.filter((p) => !removed.has(p));
             await this.saveInstalledPlugins(installedRegistry);
-            const isStillReferenced = installedRegistry.plugins.some((p) => p.cachePath === pluginToRemove.cachePath);
-            if (!isStillReferenced && existsSync(pluginToRemove.cachePath)) {
-                await fs.rm(pluginToRemove.cachePath, { recursive: true, force: true });
+            for (const plugin of pluginToRemove) {
+                const isStillReferenced = installedRegistry.plugins.some((p) => p.cachePath === plugin.cachePath);
+                if (!isStillReferenced && existsSync(plugin.cachePath)) {
+                    await fs.rm(plugin.cachePath, { recursive: true, force: true });
+                }
+            }
+        });
+    }
+    /**
+     * Moves a plugin's install record to another location（「更换安装作用域」）:
+     * the record currently at [from] (or the plugin's only record when [from] is
+     * omitted or unknown) is rewritten to [to], so that uninstalling the plugin
+     * at its new scope still finds it (spec plugin A-015). A duplicate record
+     * already at [to] wins and the moved one is dropped.
+     */
+    async relocatePlugin(pluginAtMarketplace, from, to) {
+        return this.withLock(async () => {
+            const [pluginName, marketplaceName] = pluginAtMarketplace.split("@");
+            if (!pluginName || !marketplaceName) {
+                throw new Error("Invalid plugin format. Use name@marketplace");
+            }
+            const installedRegistry = await this.getInstalledPlugins();
+            const records = installedRegistry.plugins.filter((p) => p.name === pluginName && p.marketplace === marketplaceName);
+            const source = from
+                ? records.find((p) => this.matchesInstallLocation(p, from))
+                : records[0];
+            if (!source)
+                return;
+            const duplicate = records.find((p) => p !== source && this.matchesInstallLocation(p, to));
+            if (duplicate) {
+                installedRegistry.plugins = installedRegistry.plugins.filter((p) => p !== source);
             }
+            else {
+                source.scope = to.scope;
+                source.projectPath = to.projectPath;
+            }
+            await this.saveInstalledPlugins(installedRegistry);
         });
     }
     /**
-     * Updates a plugin (uninstall followed by install)
+     * Updates a plugin (uninstall followed by install). Every install record of
+     * the plugin is re-created at its original location, so the install scopes
+     * stay unchanged (spec plugin「设置页插件市场」场景 12 / A-015).
      */
     async updatePlugin(pluginAtMarketplace) {
         return this.withLock(async () => {
+            const [pluginName, marketplaceName] = pluginAtMarketplace.split("@");
+            const before = await this.getInstalledPlugins();
+            const locations = before.plugins
+                .filter((p) => p.name === pluginName && p.marketplace === marketplaceName)
+                .map((p) => this.locationOf(p));
             await this.uninstallPlugin(pluginAtMarketplace);
-            return this.installPlugin(pluginAtMarketplace);
+            const installed = await this.installPlugin(pluginAtMarketplace, locations[0] ?? { scope: "user" });
+            if (locations.length > 1) {
+                const restored = await this.getInstalledPlugins();
+                for (const location of locations.slice(1)) {
+                    restored.plugins.push({
+                        name: installed.name,
+                        marketplace: installed.marketplace,
+                        version: installed.version,
+                        cachePath: installed.cachePath,
+                        scope: location.scope,
+                        projectPath: location.projectPath,
+                    });
+                }
+                await this.saveInstalledPlugins(restored);
+            }
+            return installed;
         });
     }
 }
-MarketplaceService.isLockedInProcess = false;
+/**
+ * 已持有市场操作锁的调用链标记（重入判据）。
+ *
+ * 用 AsyncLocalStorage 而不是进程内布尔值：锁内发起的嵌套调用（如
+ * refreshMarketplaces → updateMarketplace → installPlugin）必须跳过再次加锁，
+ * 否则会自锁；但**另一条并发调用链**必须老老实实排队。布尔值无法区分这两者
+ * ——第二个并发调用会以为「已在锁内」而跳过锁直接执行，于是两个操作并行改同一
+ * 个市场检出（并发两次 `git pull` 同一检出必然失败，spec 插件市场 场景 14）。
+ */
+MarketplaceService.lockChain = new AsyncLocalStorage();
 MarketplaceService.BUILTIN_MARKETPLACE = {
     name: "wave-plugins-official",
     source: {
         source: "github",
         repo: "netease-lcap/wave-plugins-official",
     },
-    autoUpdate: true,
 };