@1e0zj/dsh-plugin-mall 0.1.13 → 0.1.16

package/README.md

@@ -140,9 +140,25 @@ dsh plugin --profile web add link:C:\path\to\dsh-plugin-mall
   （文本级精准移除，用户手写的行不受影响）。
 - 安装源解析：`github:owner/repo` 优先改写为同名 npm 包（仅当 registry
   条目的 repository 指回该仓库，防止抢注），否则用 GitHub 全仓库 spec。
-- GitHub 源的插件安装时要跑 prepare 构建脚本，pnpm 默认拦截；本插件检测到
-  拦截后会把包名自动合并进 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds`
-  并自动重试一次（解析只认合法 npm 包名，写入一律加引号，不会写坏 YAML）。
+- 「更新至 x.y.z」按钮传的是 **`包名@版本`** 而不是裸包名。pnpm 11 有
+  `minimumReleaseAge` 供应链防护，默认拒绝发布不足 24 小时的版本：传裸包名
+  等于让 pnpm 自己挑「最新**可安装**版本」，于是按钮写着「更新至 0.12.3」、
+  pnpm 却回落到 0.12.2 并报 `Already up to date`，点多少次都不动。带上版本号
+  是明确指定，pnpm 照装并自行往 `minimumReleaseAgeExclude` 记一条豁免
+  （这行会出现在任务日志里）。更新检查读的是 registry 的 `/latest` 端点，
+  不经过该策略，所以两边看到的「最新版本」本就可能不同。
+  首次安装（卡片按钮）不带版本，沿用 pnpm 的策略默认值即可。
+- GitHub 源的插件、以及带原生模块的包安装时要跑构建脚本，pnpm 默认拦截；
+  本插件检测到拦截后会把包名自动合并进 profile 的 `pnpm-workspace.yaml` 的
+  `allowBuilds` 并自动重试一次。合并时跟随文件里已有的形状（pnpm 两种都认：
+  序列 `- name` 和映射 `name: true`，但**混在一起就是无效 YAML**），没有已有
+  形状时用 pnpm 自己写的映射格式；pnpm 留下的未决占位符
+  （`name: set this to true or false`）会被改写成 `true` 而不是当作已放行。
+- **对 profile 配置的每一次写入都是先写后校验、解析不过就回滚**
+  （`writeChecked`）：装别人的插件失败，绝不能留下 dsh 或 pnpm 加载不了的
+  profile。覆盖 `pnpm-workspace.yaml`、`package.json`、`cordis.patch.yml`
+  三处。`allowBuilds` 是持久化的安全配置，所以安装最终失败时这次放宽会被
+  **撤销** —— 否则一个没装成的插件会让那个包名从此静默获得构建脚本执行权。
 - 配置（`cordis.patch.yml` 中可改）：`defaultProfile`（默认装进哪个 profile，
   默认 `web`）、`apiBase`（GitHub API 地址）、`npmRegistry`（npm 查询源，留空
   则跟随 pnpm 实际安装源）、`rawSources`（验证用的 package.json 源模板列表，
@@ -169,4 +185,10 @@ npm publish --access public
 - node 半边导出具名成员 `{ name, inject, Config, apply }`，**不要** `export default`
   （cordis loader 会做 `exports.default ?? exports` 解包，default 会吞掉 inject/Config）；
   client 半边是 `window.__ModuleLoader__.load({id, factory})`，导出 `{ apply, inject }`。
-- 单测 `src/github.js`（无 harness 依赖）：`node src/github.js --self-test`。
+- 单测 `src/github.js`（无 harness 依赖）：`node src/github.js --self-test`，
+  加 `--offline` 只跑不联网的 fixture（宿主依赖检测的判据固化在那里 ——
+  它当初的实测对象 dsh-TUI 已被上报修复，网络上不再有可复现的回归用例，
+  所以改 `HOST_PACKAGES` 前请先跑这组）。
+- `src/installer.js` 也有一组 fixture，固化 `allowBuilds` 合并的全部形状
+  （改 `mergeAllowBuilds` 前必跑）。它有宿主依赖，所以要从**已安装副本**运行：
+  `node ~/.dsh/profiles/web/node_modules/@1e0zj/dsh-plugin-mall/src/installer.js --self-test`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1e0zj/dsh-plugin-mall",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "dsh 插件市场：搜索 GitHub dsh-plugin 话题下的插件仓库，一键安装到本地 dsh profile（agent 工具 + 设置页插件市场 tab）",
   "type": "module",
   "main": "src/index.js",

package/src/client.js

@@ -244,9 +244,14 @@ window.__ModuleLoader__.load({
                 h("span", { className: "mkt_desc" }, dep.name + "@" + dep.version),
                 h("span", { className: "mkt_depActions" },
                   h("span", { className: "mkt_badge" }, kindLabel(dep.kind)),
+                  // 必须带上版本号。传裸包名等于让 pnpm 自己挑"最新可安装
+                  // 版本"，而 pnpm 11 的 minimumReleaseAge 会拒绝发布不足
+                  // 24 小时的版本并回落到旧版 —— 按钮写着"更新至 0.12.3"，
+                  // pnpm 却报 "Already up to date"，点多少次都不动。
+                  // 带上版本是明确指定，pnpm 照装并自行记一条豁免。
                   upd && upd.hasUpdate ? h("button", {
                     className: "mkt_btn mkt_btnSm",
-                    onClick: function () { props.onInstallSpec(dep.name); },
+                    onClick: function () { props.onInstallSpec(dep.name + "@" + upd.latest); },
                   }, "更新至 " + upd.latest) : null,
                   h("button", {
                     className: "mkt_btn mkt_btnDanger mkt_btnSm",

package/src/github.js

@@ -289,7 +289,17 @@ export function compareVersions(a, b) {
 
 /** Cap on concurrent outbound requests — shared by verification and update checks. */
 export const NETWORK_CONCURRENCY = 8;
+// repo -> {kind, name, version, hostDeps, ts}
 const verifyCache = new Map();
+// Verdicts expire. Caching a success for the process lifetime freezes the badge
+// on whatever the repo looked like the first time it was seen: when dsh-TUI
+// moved its @deepseek-ai/* deps to peerDependencies, the red "宿主依赖风险"
+// badge stayed up until dsh restarted, still accusing a repo that had been
+// fixed. Ten minutes keeps a browsing session on cache while letting a fix
+// surface on its own.
+const VERIFY_TTL = 600000;
+// Network failures retry sooner — "unknown" carries no information worth keeping.
+const VERIFY_TTL_UNKNOWN = 60000;
 
 /**
  * Run `task` over `items` with at most `limit` workers in flight. The one
@@ -354,10 +364,21 @@ async function fetchRawPackageJson(repo, signal, sources) {
  * peerDependencies) installs real copies into the profile — the loader then
  * holds two module instances, symbol identities split, and every tool call
  * crashes with an undiagnosable "reading 'prepare'". See installer docs.
+ *
+ * ONLY the @deepseek-ai scope belongs here. This used to also match the bare
+ * upstream `cosmokit` and `schemastery` on the theory that dsh forked the
+ * cordis trio and therefore shipped those too. It does not: the host tree has
+ * no bare copy at any depth, and none of its 195 @deepseek-ai packages depends
+ * on one — the fork is complete and cut its ties to the upstream names. A
+ * plugin depending on bare `schemastery` shadows nothing, so flagging it was a
+ * pure false positive, and an expensive one: it hard-blocked 7 real plugins in
+ * the topic's top 300, `omdsh-dev/DSH-better-sidebar` (★1832) among them —
+ * every one of which declares its @deepseek-ai/* deps as peers correctly.
+ * Fixtures at the bottom of this file pin the distinction.
  */
-const HOST_PACKAGES = /^(@deepseek-ai\/|cosmokit$|schemastery$)/;
+const HOST_PACKAGES = /^@deepseek-ai\//;
 
-/** The @deepseek-ai/* (and cordis runtime) entries inside `dependencies`. */
+/** The @deepseek-ai/* entries inside `dependencies`. */
 function hostShadowDependencies(pkg) {
   if (pkg === undefined || typeof pkg !== "object") return undefined;
   const deps = Object.keys(pkg.dependencies ?? {});
@@ -376,11 +397,12 @@ export async function verifyPlugins({ repos, signal, sources }) {
   // which caller passes them in.
   const wanted = [...new Set((Array.isArray(repos) ? repos : []).map(String)
     .filter((repo) => /^[^@/\s][^/\s]*\/[^/\s]+$/.test(repo) && !repo.includes("..")))];
-  // "unknown"（网络失败）60s 后过期重试；成功结果进程内永久缓存。
+  // 每条判定都带时间戳：成功 10 分钟过期，网络失败 60 秒过期。
   const pending = wanted.filter((repo) => {
     const cached = verifyCache.get(repo);
     if (cached === undefined) return true;
-    return cached.kind === "unknown" && Date.now() - (cached.ts ?? 0) > 60000;
+    const ttl = cached.kind === "unknown" ? VERIFY_TTL_UNKNOWN : VERIFY_TTL;
+    return Date.now() - (cached.ts ?? 0) > ttl;
   });
   await mapLimit(pending, NETWORK_CONCURRENCY, async (repo) => {
     try {
@@ -389,18 +411,17 @@ export async function verifyPlugins({ repos, signal, sources }) {
         : typeof pkg.dsh?.bundle?.patch === "string" ? "bundle"
           : pkg.dsh?.client !== undefined ? "client"
             : "plain";
-      verifyCache.set(repo, { kind, name: pkg?.name, version: pkg?.version, hostDeps: hostShadowDependencies(pkg) });
+      verifyCache.set(repo, { kind, name: pkg?.name, version: pkg?.version, hostDeps: hostShadowDependencies(pkg), ts: Date.now() });
     } catch (error) {
       if (error?.name === "AbortError") throw error;
       verifyCache.set(repo, { kind: "unknown", ts: Date.now() });
     }
   });
+  // 一律重建对象：内部的 ts 不该出现在发给浏览器的响应里。
   const results = {};
   for (const repo of wanted) {
     const cached = verifyCache.get(repo);
-    results[repo] = cached === undefined || cached.ts !== undefined
-      ? { kind: cached?.kind ?? "unknown", name: cached?.name, version: cached?.version, hostDeps: cached?.hostDeps }
-      : cached;
+    results[repo] = { kind: cached?.kind ?? "unknown", name: cached?.name, version: cached?.version, hostDeps: cached?.hostDeps };
   }
   return { results };
 }
@@ -445,8 +466,69 @@ export async function repoInfo({ repo, apiBase, token, signal }) {
   };
 }
 
-// Self-test entry: node src/github.js
+// ── offline fixtures ────────────────────────────────────────────────────────
+//
+// The host-shadow check has no live regression case any more: dsh-TUI, the
+// plugin it was built against, moved its @deepseek-ai/* deps to
+// peerDependencies after being reported, and nothing else on the network pins
+// the bare-vs-scoped distinction. These manifests do. Shapes are taken from
+// real repositories in the dsh-plugin topic, trimmed to the relevant fields.
+const HOST_SHADOW_FIXTURES = [
+  {
+    label: "omdsh-dev/DSH-better-sidebar — 上游裸包，宿主不提供，放行",
+    pkg: {
+      dependencies: { schemastery: "^3.18.0", ws: "^8.18.0", clsx: "^2.1.1", "node-pty": "^1.1.0" },
+      peerDependencies: { "@deepseek-ai/dsh-tools": "^0.1.0-rc.6", "@deepseek-ai/cordis": "^4.0.1" },
+    },
+    expect: undefined,
+  },
+  {
+    label: "裸 cordis / cosmokit — fork 已与上游断开，放行",
+    pkg: { dependencies: { cordis: "^4.0.0-rc.7", cosmokit: "^1.6.3" } },
+    expect: undefined,
+  },
+  {
+    label: "作用域包写进 dependencies — 真·宿主重复，拦截",
+    pkg: { dependencies: { "@deepseek-ai/schemastery": "^1.0.0" } },
+    expect: ["@deepseek-ai/schemastery"],
+  },
+  {
+    label: "合法 peer + 非法 dep 混合 — 仍须拦截",
+    pkg: {
+      dependencies: { "@deepseek-ai/dsh-settings": "*", clsx: "^2" },
+      peerDependencies: { "@deepseek-ai/dsh-tools": "*" },
+    },
+    expect: ["@deepseek-ai/dsh-settings"],
+  },
+  {
+    label: "只在 peerDependencies 声明 — 正确写法，放行",
+    pkg: { peerDependencies: { "@deepseek-ai/dsh-tools": "*", "@deepseek-ai/cordis": "^4.0.1" } },
+    expect: undefined,
+  },
+  { label: "无 dependencies 字段", pkg: {}, expect: undefined },
+  { label: "非对象清单", pkg: undefined, expect: undefined },
+];
+
+/** Run the offline fixtures; returns the failure count. */
+function runHostShadowFixtures() {
+  let failed = 0;
+  for (const { label, pkg, expect } of HOST_SHADOW_FIXTURES) {
+    const actual = hostShadowDependencies(pkg);
+    const ok = JSON.stringify(actual ?? null) === JSON.stringify(expect ?? null);
+    if (!ok) failed++;
+    console.log(`  ${ok ? "PASS" : "FAIL"} ${label}${ok ? "" : `  期望 ${JSON.stringify(expect)}，实得 ${JSON.stringify(actual)}`}`);
+  }
+  return failed;
+}
+
+// Self-test entry: node src/github.js --self-test
+// Offline fixtures run first and gate the network smoke test below.
 if (process.argv[1]?.endsWith("github.js") && process.argv.includes("--self-test")) {
+  console.log("宿主依赖检测 fixtures:");
+  const failed = runHostShadowFixtures();
+  console.log(`${HOST_SHADOW_FIXTURES.length - failed}/${HOST_SHADOW_FIXTURES.length} passed\n`);
+  if (failed > 0) process.exit(1);
+  if (process.argv.includes("--offline")) process.exit(0);
   const apiBase = "https://api.github.com";
   const result = await searchPlugins({ query: "", perPage: 3, apiBase });
   console.log(`total=${result.total} page=${result.page} perPage=${result.perPage}`);

package/src/installer.js

@@ -7,7 +7,7 @@
 // @deepseek-ai/dsh-app-boot APIs for profile resolution and initialization.
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { createRequire } from "node:module";
 import { load } from "js-yaml";
@@ -31,6 +31,69 @@ export function normalizeSpec(raw) {
   return spec; // bare npm package name
 }
 
+// ── guarded config writes ───────────────────────────────────────────────────
+//
+// Installing someone else's plugin must never be able to leave a profile that
+// dsh or pnpm refuses to load. Every write to a shared profile config goes
+// through here: the new bytes are parsed back, and anything that does not
+// parse is rolled back to the previous bytes before the error propagates. A
+// bug in our own editing then costs a failed install, not a profile the user
+// has to repair by hand.
+//
+// This is not hypothetical. Editing `allowBuilds` as a YAML sequence while
+// pnpm had already written its own mapping stub produced a file no parser
+// accepted, and every later pnpm operation in that profile — install,
+// uninstall, update, any plugin at all — failed until the file was fixed
+// manually.
+
+/**
+ * Write a config file only if the result still parses.
+ * @param filePath - the file to write.
+ * @param nextContent - the full new contents.
+ * @param parse - throws when the content is not valid.
+ * @param label - file name used in error messages.
+ * @returns a rollback function restoring the pre-write bytes.
+ */
+function writeChecked(filePath, nextContent, parse, label) {
+  const previous = existsSync(filePath) ? readFileSync(filePath, "utf8") : undefined;
+  const rollback = () => {
+    if (previous === undefined) rmSync(filePath, { force: true });
+    else writeFileSync(filePath, previous);
+  };
+  writeFileSync(filePath, nextContent);
+  try {
+    parse(nextContent);
+  } catch (error) {
+    rollback();
+    throw new Error(`${label} would not parse after the edit and was restored unchanged (${error.message}) — this is a bug in dsh-plugin-mall, please report it`);
+  }
+  return rollback;
+}
+
+/** writeChecked for YAML profile configs. */
+function writeYamlChecked(filePath, nextContent, label) {
+  return writeChecked(filePath, nextContent, (text) => load(text), label);
+}
+
+/** writeChecked for JSON profile configs. */
+function writeJsonChecked(filePath, nextContent, label) {
+  return writeChecked(filePath, nextContent, (text) => JSON.parse(text), label);
+}
+
+/**
+ * writeChecked for cordis.patch.yml — the loader patch layer. Beyond parsing,
+ * the contract is a top-level array; anything else and dsh fails to boot, so
+ * that is checked here too rather than discovered at the next start.
+ */
+function writePatchChecked(filePath, nextContent) {
+  return writeChecked(filePath, nextContent, (text) => {
+    const doc = load(text);
+    if (doc !== null && doc !== undefined && !Array.isArray(doc)) {
+      throw new Error("expected a top-level array of patch entries");
+    }
+  }, "cordis.patch.yml");
+}
+
 // ── profile management ──────────────────────────────────────────────────────
 
 /** Resolve and initialize (on first use) the target profile directory. */
@@ -115,7 +178,7 @@ export function reconcileBundles(profileDir, beforeDeps = new Set()) {
         bundles: result,
       },
     };
-    writeFileSync(manifestPath, JSON.stringify(manifest, undefined, 2) + "\n");
+    writeJsonChecked(manifestPath, JSON.stringify(manifest, undefined, 2) + "\n", "package.json");
   }
   return result;
 }
@@ -263,12 +326,12 @@ export function ensureClientRow(profileDir, packageName) {
   if (alreadyByName) return { added: false };
   const rowId = clientRowId(packageName);
   const block = `- insert:\n    - id: ${rowId}\n      name: '${packageName}'\n`;
-  if (Array.isArray(parsed) && parsed.length === 0) {
+  const next = (Array.isArray(parsed) && parsed.length === 0)
     // The stock template is a comment plus `[]`; replace it wholesale.
-    writeFileSync(patchPath, block);
-  } else {
-    writeFileSync(patchPath, content.endsWith("\n") ? `${content}${block}` : `${content}\n${block}`);
-  }
+    ? block
+    : content.endsWith("\n") ? `${content}${block}` : `${content}\n${block}`;
+  // 这个文件是 dsh 的装配补丁层：写坏了宿主直接起不来。
+  writePatchChecked(patchPath, next);
   return { added: true, rowId };
 }
 
@@ -296,7 +359,7 @@ export function removeClientRow(profileDir, packageName) {
   }
   if (!removed) return { removed: false };
   const next = lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
-  writeFileSync(patchPath, next.length === 0 ? "[]\n" : `${next}\n`);
+  writePatchChecked(patchPath, next.length === 0 ? "[]\n" : `${next}\n`);
   return { removed: true, rowId };
 }
 
@@ -328,40 +391,95 @@ function parseIgnoredBuilds(output) {
   return [...names];
 }
 
-/** Merge new names into the profile's pnpm-workspace.yaml `allowBuilds` list. */
-function ensureAllowBuilds(profileDir, names) {
-  const valid = names.filter((name) => NPM_NAME_RE.test(name));
-  if (valid.length === 0) return;
-  const workspacePath = join(profileDir, "pnpm-workspace.yaml");
-  let content = existsSync(workspacePath)
-    ? readFileSync(workspacePath, "utf8")
-    : "packages:\n  - .\n\nnodeLinker: hoisted\n";
+/**
+ * Merge names into the profile's `pnpm-workspace.yaml` `allowBuilds`.
+ *
+ * pnpm accepts both shapes — a sequence (`- name`) and a mapping
+ * (`name: true`) — but never both under one key, and pnpm writes a mapping
+ * stub of its own (`name: set this to true or false`) when it blocks a build.
+ * Appending a sequence item to that stub is what produced an unparseable file.
+ * So: read the current shape through a real YAML parse, match it, and default
+ * to pnpm's own mapping shape when there is nothing to match, which keeps our
+ * edits and pnpm's from ever colliding again.
+ *
+ * A name already present as a mapping entry whose value is NOT `true` (pnpm's
+ * undecided stub) is rewritten rather than skipped — treating the stub as
+ * "already allowed" would leave the build still blocked on retry.
+ *
+ * Pure: takes the current file contents, returns the new contents (or
+ * undefined when nothing needs changing). The fs half is ensureAllowBuilds.
+ * Split out because this text surgery is the part that broke a profile, so it
+ * is the part the fixtures at the bottom of this file have to pin.
+ *
+ * @param content - current pnpm-workspace.yaml contents.
+ * @param names - package names to allow.
+ * @returns the new contents, or undefined when already satisfied.
+ * @throws when `content` does not parse as YAML.
+ */
+export function mergeAllowBuilds(content, names) {
+  const valid = (Array.isArray(names) ? names : []).filter((name) => NPM_NAME_RE.test(name));
+  if (valid.length === 0) return undefined;
+  // A file that is already broken is not ours to edit — we could only make it
+  // worse, and the user needs to see the real reason.
+  let parsed;
+  try {
+    parsed = load(content);
+  } catch (error) {
+    throw new Error(`pnpm-workspace.yaml does not parse, refusing to edit it: ${error.message}`);
+  }
+  const current = parsed?.allowBuilds;
+  const asSequence = Array.isArray(current);
+  const asMapping = !asSequence && current !== null && typeof current === "object";
+  const allowed = new Set(asSequence
+    ? current.map((entry) => String(entry))
+    : asMapping ? Object.entries(current).filter(([, value]) => value === true).map(([key]) => key) : []);
+  // pnpm 的未决占位符（值不是 true）要改写，不能当成已放行跳过。
+  const stubs = asMapping ? valid.filter((name) => name in current && current[name] !== true) : [];
+  const additions = valid.filter((name) => !allowed.has(name) && !stubs.includes(name));
+  if (additions.length === 0 && stubs.length === 0) return undefined;
+
+  // Quote sequence entries: a bare `@scope/name` opens with YAML's reserved
+  // `@` indicator. Mapping keys do not need it.
+  const render = (name) => (asSequence ? `  - '${name}'` : `  ${name}: true`);
   const lines = content.split("\n");
+  for (const name of stubs) {
+    const pattern = new RegExp(`^(\\s*)(['"]?)${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\2\\s*:.*$`);
+    const index = lines.findIndex((line) => pattern.test(line));
+    if (index !== -1) lines[index] = `  ${name}: true`;
+  }
+  let next;
   const keyIndex = lines.findIndex((line) => /^allowBuilds\s*:/.test(line));
   if (keyIndex === -1) {
-    if (!content.endsWith("\n")) content += "\n";
-    // Quote every entry: a bare `@scope/name` starts with YAML's reserved
-    // `@` indicator and fails to parse.
-    content += `\nallowBuilds:\n${valid.map((name) => `  - '${name}'`).join("\n")}\n`;
+    const base = lines.join("\n");
+    next = `${base.endsWith("\n") ? base : `${base}\n`}\nallowBuilds:\n${additions.map(render).join("\n")}\n`;
   } else {
-    const existing = new Set();
+    // 块内 = 缩进行；空行不终止块；顶格行是下一个 key。
     let insertIndex = keyIndex + 1;
     for (let index = keyIndex + 1; index < lines.length; index++) {
-      const item = /^\s*-\s+(.+?)\s*$/.exec(lines[index]);
-      if (item) {
-        existing.add(item[1].replace(/^['"](.*)['"]$/, "$1"));
-        insertIndex = index + 1;
-        continue;
-      }
-      if (/^\S/.test(lines[index])) break;
-    }
-    const additions = valid.filter((name) => !existing.has(name));
-    if (additions.length > 0) {
-      lines.splice(insertIndex, 0, ...additions.map((name) => `  - '${name}'`));
-      content = lines.join("\n");
+      if (lines[index].trim().length === 0) continue;
+      if (/^\s/.test(lines[index])) { insertIndex = index + 1; continue; }
+      break;
     }
+    if (additions.length > 0) lines.splice(insertIndex, 0, ...additions.map(render));
+    next = lines.join("\n");
   }
-  writeFileSync(workspacePath, content);
+  return next;
+}
+
+/** Default pnpm-workspace.yaml for a profile that has none yet. */
+const DEFAULT_WORKSPACE_YAML = "packages:\n  - .\n\nnodeLinker: hoisted\n";
+
+/**
+ * Apply mergeAllowBuilds to the profile's pnpm-workspace.yaml through the
+ * guarded writer.
+ * @returns a rollback function, or undefined when nothing needed changing.
+ */
+function ensureAllowBuilds(profileDir, names) {
+  const workspacePath = join(profileDir, "pnpm-workspace.yaml");
+  const content = existsSync(workspacePath) ? readFileSync(workspacePath, "utf8") : DEFAULT_WORKSPACE_YAML;
+  const next = mergeAllowBuilds(content, names);
+  if (next === undefined) return undefined;
+  return writeYamlChecked(workspacePath, next, "pnpm-workspace.yaml");
 }
 
 // ── in-process install tracker (browser RPC surface) ────────────────────────
@@ -591,18 +709,39 @@ export function runInstall({ profile, spec }) {
     if (ignored.length === 0) {
       return { status: "failed", detail: `pnpm add ${spec} failed (exit code ${outcome.exitCode}). See job output.` };
     }
-    push(`\n[dsh-plugin-mall] pnpm blocked build scripts: ${ignored.join(", ")} — merging into allowBuilds and retrying once\n`);
-    ensureAllowBuilds(profileDir, ignored);
+    // 放行构建脚本 = 允许这些包在安装期执行自己的任意代码，正是 pnpm 默认
+    // 拦下来的东西。说明白，别让它淹在 pnpm 的刷屏输出里。
+    push(`\n[dsh-plugin-mall] pnpm blocked install scripts for: ${ignored.join(", ")}\n`);
+    push(`[dsh-plugin-mall] allowing them in the profile's pnpm-workspace.yaml and retrying once — these packages will run their own install-time code.\n`);
+    let rollbackAllowBuilds;
+    try {
+      rollbackAllowBuilds = ensureAllowBuilds(profileDir, ignored);
+    } catch (error) {
+      return { status: "failed", detail: `could not allow the blocked build scripts: ${error.message}. The profile was left untouched — approve them yourself with \`pnpm approve-builds\` in ${profileDir}, then retry.` };
+    }
+    // allowBuilds 是持久化的安全配置。为一次没装成的插件单向放宽它，等于以后
+    // 这个包名再出现（哪怕是别人的传递依赖）就静默放行——失败必须收回。
+    const revert = () => {
+      if (rollbackAllowBuilds === undefined) return;
+      try {
+        rollbackAllowBuilds();
+        push("[dsh-plugin-mall] install failed — reverted the allowBuilds change, the profile is as it was\n");
+      } catch {
+        /* 还原失败不该盖掉真正的失败原因 */
+      }
+    };
     const retry = spawnAdd();
     current = retry.proc;
     const retryOutcome = await retry.done;
     if (retryOutcome.spawnError !== undefined) {
+      revert();
       return { status: "failed", detail: `retry could not start pnpm: ${retryOutcome.spawnError.message}` };
     }
     if (retryOutcome.exitCode === 0) {
       return finalizeSuccess();
     }
-    return { status: "failed", detail: `pnpm add ${spec} still failed after allowing build scripts (exit code ${retryOutcome.exitCode}). See job output.` };
+    revert();
+    return { status: "failed", detail: `pnpm add ${spec} still failed after allowing build scripts (exit code ${retryOutcome.exitCode}). See job output. The allowBuilds change was reverted; pnpm may still have left the dependency in the profile's package.json — market_uninstall removes it.` };
   };
 
   const first = spawnAdd();
@@ -710,3 +849,106 @@ export function runRemove({ profile, packageName }, selfHealed = false) {
     },
   };
 }
+
+// ── offline fixtures ────────────────────────────────────────────────────────
+//
+// mergeAllowBuilds is the text surgery that bricked a profile: it appended a
+// YAML sequence item under a key pnpm had already written as a mapping, and
+// the resulting file parsed nowhere, so every later pnpm operation in that
+// profile failed until it was repaired by hand. These cases pin every shape it
+// can meet. Run them from an INSTALLED copy (the bare imports at the top of
+// this file resolve through the host, not through a bare checkout):
+//   node ~/.dsh/profiles/web/node_modules/@1e0zj/dsh-plugin-mall/src/installer.js --self-test
+const BASE_WS = "packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n";
+
+const ALLOW_BUILDS_FIXTURES = [
+  {
+    label: "没有 allowBuilds —— 新建，用 pnpm 自己的映射格式",
+    content: BASE_WS,
+    names: ["node-pty"],
+    check: (out) => load(out).allowBuilds?.["node-pty"] === true,
+  },
+  {
+    label: "pnpm 的未决占位符 —— 改写成 true，而不是当作已放行跳过",
+    content: `${BASE_WS}allowBuilds:\n  node-pty: set this to true or false\n`,
+    names: ["node-pty"],
+    check: (out) => load(out).allowBuilds?.["node-pty"] === true,
+  },
+  {
+    label: "已有映射条目 —— 追加同为映射，不混格式",
+    content: `${BASE_WS}allowBuilds:\n  esbuild: true\n`,
+    names: ["node-pty"],
+    check: (out) => { const a = load(out).allowBuilds; return a?.esbuild === true && a?.["node-pty"] === true; },
+  },
+  {
+    label: "已有序列条目 —— 追加同为序列，不混格式（正是砖化那次的形状）",
+    content: `${BASE_WS}allowBuilds:\n  - 'esbuild'\n`,
+    names: ["node-pty"],
+    check: (out) => { const a = load(out).allowBuilds; return Array.isArray(a) && a.includes("esbuild") && a.includes("node-pty"); },
+  },
+  {
+    label: "序列里已存在 —— 无需改动",
+    content: `${BASE_WS}allowBuilds:\n  - 'node-pty'\n`,
+    names: ["node-pty"],
+    expectNoChange: true,
+  },
+  {
+    label: "映射里已是 true —— 无需改动",
+    content: `${BASE_WS}allowBuilds:\n  node-pty: true\n`,
+    names: ["node-pty"],
+    expectNoChange: true,
+  },
+  {
+    label: "scoped 包名在序列里要加引号（@ 是 YAML 保留指示符）",
+    content: `${BASE_WS}allowBuilds:\n  - 'esbuild'\n`,
+    names: ["@scope/native-thing"],
+    check: (out) => load(out).allowBuilds?.includes("@scope/native-thing"),
+  },
+  {
+    label: "allowBuilds 后面还有别的 key —— 不插到别人块里",
+    content: `packages:\n  - .\n\nallowBuilds:\n  esbuild: true\n\nnodeLinker: hoisted\n`,
+    names: ["node-pty"],
+    check: (out) => { const d = load(out); return d.allowBuilds?.["node-pty"] === true && d.nodeLinker === "hoisted"; },
+  },
+  {
+    label: "非法包名被过滤，无合法名时不动文件",
+    content: BASE_WS,
+    names: ["9 | - pkg", "Run \"pnpm approve-builds\""],
+    expectNoChange: true,
+  },
+  {
+    label: "文件本来就坏 —— 拒绝编辑，不让它更坏",
+    content: "allowBuilds:\n  - 'a'\n  a: b\n",
+    names: ["node-pty"],
+    expectThrow: true,
+  },
+];
+
+function runAllowBuildsFixtures() {
+  let failed = 0;
+  for (const fx of ALLOW_BUILDS_FIXTURES) {
+    let out, error;
+    try { out = mergeAllowBuilds(fx.content, fx.names); } catch (e) { error = e; }
+    let ok;
+    if (fx.expectThrow) ok = error !== undefined;
+    else if (error !== undefined) ok = false;
+    else if (fx.expectNoChange) ok = out === undefined;
+    else ok = out !== undefined && (() => { try { return fx.check(out) === true; } catch { return false; } })();
+    // 任何产出都必须是可解析的 YAML —— 这是这组用例存在的全部理由。
+    if (ok && out !== undefined) {
+      try { load(out); } catch { ok = false; }
+    }
+    if (!ok) failed++;
+    console.log(`  ${ok ? "PASS" : "FAIL"} ${fx.label}`);
+    if (!ok && out !== undefined) console.log(`       产出:\n${out.split("\n").map((l) => `       | ${l}`).join("\n")}`);
+    if (!ok && error !== undefined) console.log(`       抛错: ${error.message}`);
+  }
+  return failed;
+}
+
+if (process.argv[1]?.endsWith("installer.js") && process.argv.includes("--self-test")) {
+  console.log("allowBuilds 合并 fixtures:");
+  const failed = runAllowBuildsFixtures();
+  console.log(`${ALLOW_BUILDS_FIXTURES.length - failed}/${ALLOW_BUILDS_FIXTURES.length} passed`);
+  process.exit(failed === 0 ? 0 : 1);
+}