dsh-plugin 2.3.7 → 2.3.9

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

@@ -18,7 +18,7 @@ import { backfillOperationLog, createOperationLogTap, lacksDiagnosticContent, op
 import { cleanLine, estimateProgress } from '../profile/progress.js';
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.js';
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.js';
-import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory, validPackageName } from '../profile/profile.js';
+import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory, sanitizeAllowBuilds, validPackageName } from '../profile/profile.js';
 import { appendLog } from '../log.js';
 import { commandOnPath, gitMissingDetail } from './preflight.js';
 import { isTransportFailure, registryHost } from './registry-fallback.js';
@@ -881,6 +881,15 @@ export async function runPluginMutation(options) {
     // operation 日志只在运行期存在（宿主结束后可能清掉），先开抓取，退出后按路径读取作为后备
     const profileDir = profileDirectory(options.profile);
     const logTap = createOperationLogTap(profileDir);
+    // 装前修掉 allowBuilds 里的非版本 spec（`pkg@https://…` / `pkg@file:…`）：pnpm v11 在依赖
+    // 解析前就会抛 ERR_PNPM_INVALID_VERSION_UNION，该 profile 里之后任何安装都会失败（#730）。
+    // 这一步失败不影响主流程 —— 真有问题仍由 pnpm 的报错决定怎么提示。
+    if (options.action !== 'remove' && (options.globalNpm ?? []).length === 0) {
+        try {
+            sanitizeAllowBuilds(options.profile);
+        }
+        catch { /* 读不到/写不进就按原样继续 */ }
+    }
     let result = await spawnMutation(options);
     // allowBuilds 放行 / 装后入口校验都是 profile 专属（pnpm 装进 profile 的场景）；
     // 全局 npm 安装直接走 npm，无 pnpm allowBuilds 拦截、也不进 profile，跳过这两类恢复

package/lib/services/profile/profile.js

@@ -152,38 +152,22 @@ function quoteYamlKey(key) {
     }
     return key;
 }
-/**
- * 向 profile 的 pnpm-workspace.yaml 追加一条 `allowBuilds` 记录：与已有条目合并，
- * 其余 yaml 保持不变；重写时丢弃损坏的占位条目（pnpm 安装失败的 bug 会写入
- * 字面量 `set this to true or false`）。
- *
- * 任何形态的既有 `allowBuilds` 都会被**整体替换**成规范化块：块写法、行内数组
- * `allowBuilds: ["a@1"]`、以及末尾无换行的 `allowBuilds:` 都算命中。否则会在文件里
- * 再多写一个同名键 —— pnpm 解析时直接报 `duplicated mapping key`，该 profile 里
- * 所有插件都装不上（#562）。
- */
-export function addAllowBuildsKey(profile, key) {
-    const file = join(profileDirectory(profile), 'pnpm-workspace.yaml');
-    let yaml = '';
-    try {
-        yaml = readFileSync(file, 'utf8');
-    }
-    catch { /* 文件不存在，下方创建 */ }
-    const eol = /\r\n/.test(yaml) ? '\r\n' : '\n';
-    // header 行（可选行内值）+ 其后任意缩进条目行；行内写法没有后续缩进行也能匹配
-    const blockRe = /^[ \t]*allowBuilds:[^\r\n]*(?:(?:\r?\n)[ \t]{2,}[^\r\n]*)*/gm;
+/** `allowBuilds` 段：header 行（可带行内数组值）+ 其后任意缩进条目行。 */
+const ALLOW_BLOCK_RE = /^[ \t]*allowBuilds:[^\r\n]*(?:(?:\r?\n)[ \t]{2,}[^\r\n]*)*/gm;
+function unquoteYamlKey(key) {
+    const quoted = key.length >= 2 && ((key[0] === "'" && key[key.length - 1] === "'") || (key[0] === '"' && key[key.length - 1] === '"'));
+    return quoted ? key.slice(1, -1) : key;
+}
+/** 读出 yaml 里所有 `allowBuilds` 段的条目（key → 值，缺省 true）。 */
+function readAllowBuilds(yaml) {
     const map = new Map();
-    for (const match of Array.from(yaml.matchAll(blockRe))) {
+    for (const match of Array.from(yaml.matchAll(ALLOW_BLOCK_RE))) {
         const [header, ...rest] = match[0].split(/\r?\n/);
         for (const line of rest) {
             const m = /^[ \t]+(\S.*?)\s*:\s*(true|false)?\s*$/.exec(line);
             if (m === null || m[1] === '')
                 continue;
-            let k = m[1];
-            if (k.length >= 2 && ((k[0] === "'" && k[k.length - 1] === "'") || (k[0] === '"' && k[k.length - 1] === '"'))) {
-                k = k.slice(1, -1);
-            }
-            map.set(k, m[2] ?? 'true');
+            map.set(unquoteYamlKey(m[1]), m[2] ?? 'true');
         }
         // 行内数组写法：allowBuilds: ["a@1.0.0", 'b@2'] —— 保留已有条目，别丢
         const inline = /^[ \t]*allowBuilds:\s*\[(.*)\]\s*$/.exec(header);
@@ -195,12 +179,72 @@ export function addAllowBuildsKey(profile, key) {
             }
         }
     }
-    map.set(key, 'true');
+    return map;
+}
+/** 把所有 `allowBuilds` 段合并写成一段规范化块，其余 yaml 原样保留；无该段时追加。 */
+function writeAllowBuilds(yaml, map) {
+    const eol = /\r\n/.test(yaml) ? '\r\n' : '\n';
     const block = Array.from(map).map(([k, v]) => `  ${quoteYamlKey(k)}: ${v}`).join(eol);
     const blockText = `allowBuilds:${eol}${block}${eol}`;
     let seen = 0;
-    let next = yaml.replace(blockRe, () => (seen++ === 0 ? blockText : ''));
-    if (seen === 0)
-        next = `${yaml.replace(/\r?\n?$/, eol)}${blockText}`;
-    writeFileSync(file, next);
+    const next = yaml.replace(ALLOW_BLOCK_RE, () => (seen++ === 0 ? blockText : ''));
+    return seen === 0 ? `${yaml.replace(/\r?\n?$/, eol)}${blockText}` : next;
+}
+/**
+ * `allowBuilds` 的 key 必须是 `包名@精确版本`。pnpm v11 在真正安装前会把每条规则解析成
+ * 「包名 + 精确版本」，遇到 URL/git/file spec（`pkg@https://…`、`pkg@file:…`）直接抛
+ * `ERR_PNPM_INVALID_VERSION_UNION` —— 该 profile 里之后**任何**安装都会失败（#730）。
+ * 非 semver 的 spec 一律降级为裸包名（pnpm 按包名匹配所有版本）。
+ */
+export function safeAllowBuildsKey(key) {
+    const at = key.startsWith('@') ? key.indexOf('@', 1) : key.indexOf('@');
+    if (at <= 0)
+        return key;
+    const spec = key.slice(at + 1);
+    return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(spec) ? key : key.slice(0, at);
+}
+/**
+ * 安装前修复**已有** `allowBuilds` 里的非法 key。pnpm 的报错发生在依赖解析之前，
+ * 走不到 `addAllowBuildsKey` 的失败恢复路径，只能主动清理。返回是否改写了文件。
+ */
+export function sanitizeAllowBuilds(profile) {
+    const file = join(profileDirectory(profile), 'pnpm-workspace.yaml');
+    let yaml = '';
+    try {
+        yaml = readFileSync(file, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (Array.from(yaml.matchAll(ALLOW_BLOCK_RE)).length === 0)
+        return false;
+    const before = readAllowBuilds(yaml);
+    const after = new Map();
+    for (const [k, v] of before)
+        after.set(safeAllowBuildsKey(k), v);
+    if (after.size === before.size && Array.from(after).every(([k, v]) => before.get(k) === v))
+        return false;
+    writeFileSync(file, writeAllowBuilds(yaml, after));
+    return true;
+}
+/**
+ * 向 profile 的 pnpm-workspace.yaml 追加一条 `allowBuilds` 记录：与已有条目合并，
+ * 其余 yaml 保持不变；重写时丢弃损坏的占位条目（pnpm 安装失败的 bug 会写入
+ * 字面量 `set this to true or false`）。
+ *
+ * 任何形态的既有 `allowBuilds` 都会被**整体替换**成规范化块：块写法、行内数组
+ * `allowBuilds: ["a@1"]`、以及末尾无换行的 `allowBuilds:` 都算命中。否则会在文件里
+ * 再多写一个同名键 —— pnpm 解析时直接报 `duplicated mapping key`，该 profile 里
+ * 所有插件都装不上（#562）。
+ */
+export function addAllowBuildsKey(profile, key) {
+    const file = join(profileDirectory(profile), 'pnpm-workspace.yaml');
+    let yaml = '';
+    try {
+        yaml = readFileSync(file, 'utf8');
+    }
+    catch { /* 文件不存在，下方创建 */ }
+    const map = readAllowBuilds(yaml);
+    map.set(safeAllowBuildsKey(key), 'true');
+    writeFileSync(file, writeAllowBuilds(yaml, map));
 }

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

@@ -32,6 +32,18 @@ export declare function validPackageName(name: string): boolean;
  * 无则返回 null。
  */
 export declare function parseAllowBuildsKey(output: string): string | null;
+/**
+ * `allowBuilds` 的 key 必须是 `包名@精确版本`。pnpm v11 在真正安装前会把每条规则解析成
+ * 「包名 + 精确版本」，遇到 URL/git/file spec（`pkg@https://…`、`pkg@file:…`）直接抛
+ * `ERR_PNPM_INVALID_VERSION_UNION` —— 该 profile 里之后**任何**安装都会失败（#730）。
+ * 非 semver 的 spec 一律降级为裸包名（pnpm 按包名匹配所有版本）。
+ */
+export declare function safeAllowBuildsKey(key: string): string;
+/**
+ * 安装前修复**已有** `allowBuilds` 里的非法 key。pnpm 的报错发生在依赖解析之前，
+ * 走不到 `addAllowBuildsKey` 的失败恢复路径，只能主动清理。返回是否改写了文件。
+ */
+export declare function sanitizeAllowBuilds(profile: string): boolean;
 /**
  * 向 profile 的 pnpm-workspace.yaml 追加一条 `allowBuilds` 记录：与已有条目合并，
  * 其余 yaml 保持不变；重写时丢弃损坏的占位条目（pnpm 安装失败的 bug 会写入

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin",
-  "version": "2.3.7",
-  "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 20000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：20000+ 人工精选社区插件，每日更新。",
+  "version": "2.3.9",
+  "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 6000+ hand-verified npm plugins out of 23000+ indexed, without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：收录 23000+ 社区插件，其中 6000+ 已发布 npm 包、可一键安装，每日更新。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",

package/src/client/components/modals/NotificationsModal.tsx

@@ -338,6 +338,11 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // pnpm 每次 add 都重校验整棵树，该 profile 内的安装都会失败 —— 给定位/移除指引，不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failProfileLocalBuildHint'))
                     }
+                    if (kind === 'profileBadAllowBuilds') {
+                      // allowBuilds 里有 pnpm 解析不了的 spec（`pkg@https://…` / `pkg@file:…`）：
+                      // pnpm v11 在依赖解析前就中止，该 profile 内的安装都会失败 —— 给删除/改正指引，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failProfileBadAllowBuildsHint'))
+                    }
                     if (kind === 'profileState') {
                       // profile 的 pnpm 元数据与本机不一致（lockfile 过期 / packageManager 版本不符 /
                       // 补丁未生效）：pnpm 在真正装插件之前就中止，该 profile 内的安装都会失败 ——

package/src/client/components/modals/modals.tsx

@@ -472,6 +472,11 @@ export function ErrorModal({ message, repo, action, command, attempts, t, env, o
               // 被拦的构建脚本属于 profile 里已有的 file:/link: 本地插件，不是本次装的插件：
               // pnpm 每次 add 都重校验整棵树，该 profile 内的安装都会失败 —— 给定位/移除指引，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failProfileLocalBuildHint'))
+              : failureKind === 'profileBadAllowBuilds'
+              // allowBuilds 里有 pnpm 解析不了的 spec（`pkg@https://…` / `pkg@file:…`）：pnpm v11 在
+              // 依赖解析前就把每条规则当「包名@精确版本」校验并中止，该 profile 内的安装都会失败 ——
+              // 给删除/改正指引，不引导提 Issue
+              ? h('div', { className: styles.failPrepareHint }, t('failProfileBadAllowBuildsHint'))
               : failureKind === 'profileState'
               // profile 的 pnpm 元数据与本机不一致（lockfile 过期 / packageManager 版本不符 /
               // 补丁未生效）：pnpm 在真正装插件之前就中止，该 profile 内的安装都会失败 ——

package/src/client/locales.ts

@@ -394,7 +394,10 @@ export const zh = {
   failKind_profileYamlCorrupted: 'profile 的 YAML 配置损坏',
   failReason_profileYamlCorrupted: 'profile 目录里的 pnpm-workspace.yaml 或 pnpm-lock.yaml 有重复的键，pnpm 在解析阶段就退出了。',
   failKind_profileLocalBuild: 'profile 里已有的本地插件构建失败',
+  failKind_profileBadAllowBuilds: 'profile 的 allowBuilds 有条目无法解析',
+  failProfileBadAllowBuildsHint: '安装器调用 pnpm 时，pnpm 在解析依赖之前就中止了：这台机器 profile 的 pnpm-workspace.yaml 里，allowBuilds 有一条写成「包名@版本」的规则，而版本位置填的是 URL 或本地路径（报错形如 Invalid versions union. Found: "xxx@https"）。pnpm 会把每条规则当成「包名@精确版本」解析，解析不了就直接报错，所以这个 profile 里装任何插件都会失败——与本次要装的插件无关，也不该去找它的作者。请打开 ~/.dsh/profiles/<profile>/pnpm-workspace.yaml，把 allowBuilds 下那条带 https://、git、file: 的键删掉（或只保留包名，例如改成 `dsh-purge: true`），保存后重试。升级到 2.3.9 之后，插件中心会在安装前自动把这类键修正成包名。',
   failReason_profileLocalBuild: 'pnpm 每次安装都会重校验整个 profile，这次失败来自 profile 里已有的 file:/link: 本地插件的构建脚本，和本次要装的插件无关。',
+  failReason_profileBadAllowBuilds: 'profile 的 pnpm-workspace.yaml 里 allowBuilds 有一条写成了「包名@URL / 本地路径」，pnpm 解析不了这条规则，安装还没开始就中止了——和本次要装的插件无关。',
   failKind_profileState: 'profile 的 pnpm 元数据与本机不一致',
   failReason_profileState: 'profile 的 lockfile / package.json / packageManager 版本与当前 pnpm 对不上，安装没开始就被中止。',
   failKind_nodeEngine: '本机 Node / pnpm 版本不满足要求',
@@ -905,7 +908,10 @@ export const en = {
   failKind_profileYamlCorrupted: 'profile YAML config is corrupted',
   failReason_profileYamlCorrupted: 'A YAML file in the profile directory has a duplicate key, so pnpm aborts at parse time.',
   failKind_profileLocalBuild: 'a local plugin already in the profile fails its build',
+  failKind_profileBadAllowBuilds: 'an allowBuilds entry in the profile cannot be parsed',
+  failProfileBadAllowBuildsHint: 'pnpm aborted before resolving dependencies: the allowBuilds list in this machine\'s profile (pnpm-workspace.yaml) has a rule written as "package@version" where the version part is a URL or local path (the error looks like Invalid versions union. Found: "xxx@https"). pnpm parses every rule as an exact "package@version" pair and fails on anything else, so every install into this profile fails — it is unrelated to the plugin you were installing, and reporting it to that plugin\'s author will not help. Open ~/.dsh/profiles/<profile>/pnpm-workspace.yaml, delete that key containing https://, git or file:, or keep just the package name (for example `dsh-purge: true`), then retry. From 2.3.9 the hub repairs such keys automatically before installing.',
   failReason_profileLocalBuild: 'pnpm re-validates the whole profile on every install; this failure comes from the build script of a local (file:/link:) package already in the profile, not from the plugin being installed.',
+  failReason_profileBadAllowBuilds: 'The allowBuilds list in the profile\'s pnpm-workspace.yaml has an entry written as "package@URL / local path", which pnpm cannot parse, so the install aborts before starting — unrelated to the plugin being installed.',
   failKind_profileState: 'profile pnpm metadata does not match this machine',
   failReason_profileState: 'The profile lockfile / package.json / packageManager version disagrees with the current pnpm, so the install aborts before starting.',
   failKind_nodeEngine: 'Node / pnpm on this machine is below the required version',

package/src/client/logic/failures.ts

@@ -148,7 +148,7 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'nodeEngine' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmModulesMismatch' | 'profileYamlCorrupted' | 'profileLocalBuild' | 'profileState' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'registryAuth' | 'profileExclusive' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'tlsTrust' | 'network' | 'hostCliSpawn' | 'hubState' | 'profileBundleMissing' | 'timeout' | 'profileLock' | 'dshTooOld' | 'localEnv' | 'hub'
+export type FailureKind = 'npmTooOld' | 'nodeEngine' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmModulesMismatch' | 'profileYamlCorrupted' | 'profileLocalBuild' | 'profileBadAllowBuilds' | 'profileState' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'registryAuth' | 'profileExclusive' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'buildToolchainMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'hostIncompatible' | 'tlsTrust' | 'network' | 'hostCliSpawn' | 'hubState' | 'profileBundleMissing' | 'timeout' | 'profileLock' | 'dshTooOld' | 'localEnv' | 'hub'
 
 /** 失败动作规则：标题、上报正文与提示文案按安装/更新/卸载取词，不写死「安装」。 */
 export type FailureAction = 'install' | 'update' | 'uninstall'
@@ -286,6 +286,10 @@ export function classifyFailure(message: string): FailureKind {
   // 名单全是本地 file:/link: 依赖时，失败只能来自 profile 自身的包重校验：归本机状态，
   // 不能记到本次插件头上。必须在 pnpmIgnoredBuild 之前，否则会被它先按插件侧接走
   if (localBuildScriptsOnly(message)) return 'profileLocalBuild'
+  // profile 的 allowBuilds 里有 pnpm 解析不了的 spec（`pkg@https://…` / `pkg@file:…`）：
+  // pnpm v11 在依赖解析之前就把每条规则当成「包名@精确版本」解析并抛错，该 profile 里
+  // 之后任何安装都会失败 —— 与本次要装的插件无关（#730）
+  if (/ERR_PNPM_INVALID_VERSION_UNION|Invalid versions union/i.test(message)) return 'profileBadAllowBuilds'
   // 构建脚本被 allowBuilds 拦截。必须在 network 之前判：日志尾部混重试残留的连接失败特征
   if (/ERR_PNPM_IGNORED_BUILDS|Ignored build scripts:|ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED/i.test(message)) return 'pnpmIgnoredBuild'
   // npm 源拒绝了访问（401/403）：私有源要登录凭据，或当前网络/IP 不被源允许。

package/src/client/logic/urls.ts

@@ -52,6 +52,7 @@ function reasonTitleOf(kind: FailureKind, action: FailureAction): string {
     case 'profileState': return `the user profile's pnpm metadata does not match the local pnpm for this ${word}`
     case 'profileYamlCorrupted': return 'the user profile has a corrupted YAML config (duplicated mapping key)'
     case 'profileLocalBuild': return 'a local (file:/link:) plugin already in the user profile has a failing build script'
+    case 'profileBadAllowBuilds': return 'the user profile has an allowBuilds entry that pnpm cannot parse'
     case 'dshMissing': return 'dsh command not found on the user machine'
     case 'pnpmMissing': return 'pnpm command not found on the user machine'
     case 'pnpmStore': return 'pnpm store version mismatch on the user machine'
@@ -118,6 +119,8 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
         ? 'the local certificate chain is not trusted by Node/pnpm (corporate SSL inspection, antivirus web shield, or a local MITM proxy) — local environment issue'
       : kind === 'profileLocalBuild'
         ? 'no plugin-side cause found — pnpm rejects a build script of a local (file:/link:) package that already exists in the user profile, so every install into that profile fails the same way (local environment issue)'
+      : kind === 'profileBadAllowBuilds'
+        ? 'no plugin-side cause found — the allowBuilds list in the user profile\'s pnpm-workspace.yaml contains a spec pnpm cannot parse (a URL, git or file path where an exact version is required), so pnpm aborts every install into that profile before resolving the plugin (local environment issue)'
       : kind === 'localEnv'
         ? 'no evidence of a plugin-side cause; the log shows local-environment signals (system error codes, certificates/proxy, or a broken local config), so this is reported for triage of the classifier only'
       : kind === 'dshTooOld'

package/src/server/services/install/task-queue.ts

@@ -20,7 +20,7 @@ import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.ts'
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.ts'
-import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory, validPackageName } from '../profile/profile.ts'
+import { addAllowBuildsKey, bundleIncludes, githubRepoOf, parseAllowBuildsKey, profileDirectory, sanitizeAllowBuilds, validPackageName } from '../profile/profile.ts'
 import { appendLog } from '../log.ts'
 import { commandOnPath, gitMissingDetail } from './preflight.ts'
 import { isTransportFailure, registryHost } from './registry-fallback.ts'
@@ -939,6 +939,12 @@ export async function runPluginMutation(options: {
   // operation 日志只在运行期存在（宿主结束后可能清掉），先开抓取，退出后按路径读取作为后备
   const profileDir = profileDirectory(options.profile)
   const logTap = createOperationLogTap(profileDir)
+  // 装前修掉 allowBuilds 里的非版本 spec（`pkg@https://…` / `pkg@file:…`）：pnpm v11 在依赖
+  // 解析前就会抛 ERR_PNPM_INVALID_VERSION_UNION，该 profile 里之后任何安装都会失败（#730）。
+  // 这一步失败不影响主流程 —— 真有问题仍由 pnpm 的报错决定怎么提示。
+  if (options.action !== 'remove' && (options.globalNpm ?? []).length === 0) {
+    try { sanitizeAllowBuilds(options.profile) } catch { /* 读不到/写不进就按原样继续 */ }
+  }
   let result = await spawnMutation(options)
   // allowBuilds 放行 / 装后入口校验都是 profile 专属（pnpm 装进 profile 的场景）；
   // 全局 npm 安装直接走 npm，无 pnpm allowBuilds 拦截、也不进 profile，跳过这两类恢复

package/src/server/services/profile/profile.ts

@@ -153,34 +153,23 @@ function quoteYamlKey(key: string): string {
   return key
 }
 
-/**
- * 向 profile 的 pnpm-workspace.yaml 追加一条 `allowBuilds` 记录：与已有条目合并，
- * 其余 yaml 保持不变；重写时丢弃损坏的占位条目（pnpm 安装失败的 bug 会写入
- * 字面量 `set this to true or false`）。
- *
- * 任何形态的既有 `allowBuilds` 都会被**整体替换**成规范化块：块写法、行内数组
- * `allowBuilds: ["a@1"]`、以及末尾无换行的 `allowBuilds:` 都算命中。否则会在文件里
- * 再多写一个同名键 —— pnpm 解析时直接报 `duplicated mapping key`，该 profile 里
- * 所有插件都装不上（#562）。
- */
-export function addAllowBuildsKey(profile: string, key: string): void {
-  const file = join(profileDirectory(profile), 'pnpm-workspace.yaml')
-  let yaml = ''
-  try { yaml = readFileSync(file, 'utf8') } catch { /* 文件不存在，下方创建 */ }
-  const eol = /\r\n/.test(yaml) ? '\r\n' : '\n'
-  // header 行（可选行内值）+ 其后任意缩进条目行；行内写法没有后续缩进行也能匹配
-  const blockRe = /^[ \t]*allowBuilds:[^\r\n]*(?:(?:\r?\n)[ \t]{2,}[^\r\n]*)*/gm
+/** `allowBuilds` 段：header 行（可带行内数组值）+ 其后任意缩进条目行。 */
+const ALLOW_BLOCK_RE = /^[ \t]*allowBuilds:[^\r\n]*(?:(?:\r?\n)[ \t]{2,}[^\r\n]*)*/gm
+
+function unquoteYamlKey(key: string): string {
+  const quoted = key.length >= 2 && ((key[0] === "'" && key[key.length - 1] === "'") || (key[0] === '"' && key[key.length - 1] === '"'))
+  return quoted ? key.slice(1, -1) : key
+}
+
+/** 读出 yaml 里所有 `allowBuilds` 段的条目（key → 值，缺省 true）。 */
+function readAllowBuilds(yaml: string): Map<string, string> {
   const map = new Map<string, string>()
-  for (const match of Array.from(yaml.matchAll(blockRe))) {
+  for (const match of Array.from(yaml.matchAll(ALLOW_BLOCK_RE))) {
     const [header, ...rest] = match[0].split(/\r?\n/)
     for (const line of rest) {
       const m = /^[ \t]+(\S.*?)\s*:\s*(true|false)?\s*$/.exec(line)
       if (m === null || m[1] === '') continue
-      let k = m[1]
-      if (k.length >= 2 && ((k[0] === "'" && k[k.length - 1] === "'") || (k[0] === '"' && k[k.length - 1] === '"'))) {
-        k = k.slice(1, -1)
-      }
-      map.set(k, m[2] ?? 'true')
+      map.set(unquoteYamlKey(m[1]), m[2] ?? 'true')
     }
     // 行内数组写法：allowBuilds: ["a@1.0.0", 'b@2'] —— 保留已有条目，别丢
     const inline = /^[ \t]*allowBuilds:\s*\[(.*)\]\s*$/.exec(header)
@@ -191,11 +180,64 @@ export function addAllowBuildsKey(profile: string, key: string): void {
       }
     }
   }
-  map.set(key, 'true')
+  return map
+}
+
+/** 把所有 `allowBuilds` 段合并写成一段规范化块，其余 yaml 原样保留；无该段时追加。 */
+function writeAllowBuilds(yaml: string, map: Map<string, string>): string {
+  const eol = /\r\n/.test(yaml) ? '\r\n' : '\n'
   const block = Array.from(map).map(([k, v]) => `  ${quoteYamlKey(k)}: ${v}`).join(eol)
   const blockText = `allowBuilds:${eol}${block}${eol}`
   let seen = 0
-  let next = yaml.replace(blockRe, () => (seen++ === 0 ? blockText : ''))
-  if (seen === 0) next = `${yaml.replace(/\r?\n?$/, eol)}${blockText}`
-  writeFileSync(file, next)
+  const next = yaml.replace(ALLOW_BLOCK_RE, () => (seen++ === 0 ? blockText : ''))
+  return seen === 0 ? `${yaml.replace(/\r?\n?$/, eol)}${blockText}` : next
+}
+
+/**
+ * `allowBuilds` 的 key 必须是 `包名@精确版本`。pnpm v11 在真正安装前会把每条规则解析成
+ * 「包名 + 精确版本」，遇到 URL/git/file spec（`pkg@https://…`、`pkg@file:…`）直接抛
+ * `ERR_PNPM_INVALID_VERSION_UNION` —— 该 profile 里之后**任何**安装都会失败（#730）。
+ * 非 semver 的 spec 一律降级为裸包名（pnpm 按包名匹配所有版本）。
+ */
+export function safeAllowBuildsKey(key: string): string {
+  const at = key.startsWith('@') ? key.indexOf('@', 1) : key.indexOf('@')
+  if (at <= 0) return key
+  const spec = key.slice(at + 1)
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(spec) ? key : key.slice(0, at)
+}
+
+/**
+ * 安装前修复**已有** `allowBuilds` 里的非法 key。pnpm 的报错发生在依赖解析之前，
+ * 走不到 `addAllowBuildsKey` 的失败恢复路径，只能主动清理。返回是否改写了文件。
+ */
+export function sanitizeAllowBuilds(profile: string): boolean {
+  const file = join(profileDirectory(profile), 'pnpm-workspace.yaml')
+  let yaml = ''
+  try { yaml = readFileSync(file, 'utf8') } catch { return false }
+  if (Array.from(yaml.matchAll(ALLOW_BLOCK_RE)).length === 0) return false
+  const before = readAllowBuilds(yaml)
+  const after = new Map<string, string>()
+  for (const [k, v] of before) after.set(safeAllowBuildsKey(k), v)
+  if (after.size === before.size && Array.from(after).every(([k, v]) => before.get(k) === v)) return false
+  writeFileSync(file, writeAllowBuilds(yaml, after))
+  return true
+}
+
+/**
+ * 向 profile 的 pnpm-workspace.yaml 追加一条 `allowBuilds` 记录：与已有条目合并，
+ * 其余 yaml 保持不变；重写时丢弃损坏的占位条目（pnpm 安装失败的 bug 会写入
+ * 字面量 `set this to true or false`）。
+ *
+ * 任何形态的既有 `allowBuilds` 都会被**整体替换**成规范化块：块写法、行内数组
+ * `allowBuilds: ["a@1"]`、以及末尾无换行的 `allowBuilds:` 都算命中。否则会在文件里
+ * 再多写一个同名键 —— pnpm 解析时直接报 `duplicated mapping key`，该 profile 里
+ * 所有插件都装不上（#562）。
+ */
+export function addAllowBuildsKey(profile: string, key: string): void {
+  const file = join(profileDirectory(profile), 'pnpm-workspace.yaml')
+  let yaml = ''
+  try { yaml = readFileSync(file, 'utf8') } catch { /* 文件不存在，下方创建 */ }
+  const map = readAllowBuilds(yaml)
+  map.set(safeAllowBuildsKey(key), 'true')
+  writeFileSync(file, writeAllowBuilds(yaml, map))
 }