@noob-stupid/dsh-plugin-console 0.5.37 → 0.5.38

package/lib/client.js

@@ -113,6 +113,7 @@ window.__ModuleLoader__.load({
 			// 2026-09-27 加法：安装结果旁的「建议动作」执行框（短句进面板，长解释进悬浮 title）
 			actionBoxTitle: "建议动作",
 			actionPinLabel: "钉住该依赖（按 link: 记录）",
+			actionPersistLabel: "一键钉住（清单 + lock + 挂载行）",
 			actionReconcileLabel: "重建 pnpm-lock.yaml",
 			actionRun: "执行",
 			actionCopy: "复制",
@@ -279,11 +280,16 @@ window.__ModuleLoader__.load({
 			subpackagesEmpty: "未发现可安装的子包。",
 			recentFailures: "最近安装失败",
 			installed: "已安装并启用",
+			// 0.5.38 加法：三处没齐备（清单 / lock / 挂载行）时**绝不**说"已安装并启用"——
+			// 那种状态下任何一次 pnpm 操作或重启都会把它清掉（真机 dshmarket 现场）。
+			installedNotPersisted: "⚠ 已装上但未持久化（重启/重装会消失）",
 			installNote: "HMR 正在生效；若插件带界面，请刷新页面",
 			bundleNote: "该包是 bundle 层插件（如皮肤合集），重启 DSH 服务后生效",
 			// ── 安装诊断短句（2026-09-26 加法）：面板只放短句；解释性长文留在服务端字段里，
 			// 前端只把它挂到 title 悬浮提示上，不铺进面板（用户明确要求）──
 			diagCardTitle: "安装诊断",
+			// 0.5.38 加法：持久化判据（服务端 domain/persist.js）——三处任一没就位就出这张卡
+			diagNotPersisted: "未持久化：清单 / lock / 挂载行有缺口",
 			// 分隔符也进字典：英文界面用半角标点，避免中文全角标点混进英文句子
 			diagColon: "：",
 			diagSemi: "；",
@@ -674,6 +680,7 @@ window.__ModuleLoader__.load({
 			safetyLockRepairBtn: "Rebuild lock (explicit)",
 			actionBoxTitle: "Suggested action",
 			actionPinLabel: "Pin this dependency (record as link:)",
+			actionPersistLabel: "Pin it in one click (manifest + lock + mount row)",
 			actionReconcileLabel: "Rebuild pnpm-lock.yaml",
 			actionRun: "Run",
 			actionCopy: "Copy",
@@ -838,11 +845,13 @@ window.__ModuleLoader__.load({
 			subpackagesEmpty: "No installable subpackages found.",
 			recentFailures: "Recent install failures",
 			installed: "Installed and enabled",
+			installedNotPersisted: "⚠ Installed but NOT persisted (it disappears on restart/reinstall)",
 			installNote: "HMR is applying; refresh the page if the plugin ships UI",
 			bundleNote: "This package is a bundle-layer plugin (e.g. skin packs); restart the DSH service to activate it",
 			// ── install-diagnosis one-liners (2026-09-26, additive): the panel shows short sentences only;
 			// the long server-side explanations go to the title tooltip, never into the panel body ──
 			diagCardTitle: "Install diagnosis",
+			diagNotPersisted: "Not persisted: a gap remains in manifest / lock / mount row",
 			// separators live in the dictionary too: English uses half-width punctuation
 			diagColon: ": ",
 			diagSemi: "; ",
@@ -3282,6 +3291,12 @@ window.__ModuleLoader__.load({
 										// 「预设：新建会话时选择」（点击安装的当下没有新会话，必须先说清楚下一步）。
 										setMessage(t("presetInstalledMsg") + "：" + data.presetNote + t("presetDot") + diagMessage(data));
 										setReloadHint(true);
+									} else if (data.persisted === false) {
+										// 0.5.38 加法（用户诉求「下载下来就不用 lock、重启也不会消失」）：
+										// 三处没齐备时**绝不报"已安装并启用"** —— 说清它还缺什么、后果是什么，
+										// 并把服务端下发的「一键钉住」执行框带出来（下面的 suggestedAction 分支）。
+										setMessage(t("installedNotPersisted") + "：" + data.packageName + (typeof data.persistNote === "string" && data.persistNote !== "" ? "。" + data.persistNote : "") + diagMessage(data));
+										setReloadHint(true);
 									} else {
 										setMessage(t("installed") + "：" + data.packageName + "（" + (data.entryId ?? "") + "）。" + (data.curlNote ?? (data.bundle ? t("bundleNote") : t("installNote"))) + (data.bundleNote ? "。" + data.bundleNote : "") + (data.lockNote ? "。⚠️ " + data.lockNote : "") + (data.depNote ? "。" + data.depNote : "") + diagMessage(data));
 									}
@@ -3293,6 +3308,9 @@ window.__ModuleLoader__.load({
 									}
 									if (data.bundle) {
 										setRestartHint(true);
+									} else if (data.persisted === false) {
+										// 未持久化：不自动刷新（卡片上的「一键钉住」还没点，刷新会把结果冲掉）
+										setReloadHint(true);
 									} else if ((data.suggestedAction !== null && data.suggestedAction !== undefined)
 										|| (typeof data.presetNote === "string" && data.presetNote !== "")) {
 										// 有建议动作时不自动刷新页面（2026-09-27 加法）：旧行为 2.5 秒后 reload，
@@ -3428,6 +3446,17 @@ window.__ModuleLoader__.load({
 						title: channelNotes.join("\n"),
 					});
 				}
+				// ⑤ 持久化判据（0.5.38 加法，服务端 domain/persist.js：{ missing, actual, note }）：
+				//    三处（清单 spec / pnpm-lock.yaml 条目 / 挂载行）任一没就位 → error 级诊断行，
+				//    完整缺口清单挂 title。**装成功但没钉住**的作业从此不会只显示"已安装并启用"。
+				if (view.status === "done" && view.persisted === false) {
+					lines.push({
+						key: "persist",
+						text: t("diagNotPersisted") + (Array.isArray(view.persist?.missing) && view.persist.missing.length > 0 ? t("diagColon") + view.persist.missing.join(" / ") : ""),
+						level: "error",
+						title: typeof view.persistNote === "string" && view.persistNote !== "" ? view.persistNote : (typeof view.persist?.note === "string" ? view.persist.note : null),
+					});
+				}
 				return lines;
 			};
 			/** 诊断短句 → 消息栏后缀（空串 = 没问题）：只在既有文案**末尾追加**，一个字都不替换。 */
@@ -5731,6 +5760,7 @@ window.__ModuleLoader__.load({
 			if (action === null || typeof action.command !== "string" || state.closed === true) return null;
 			const running = state.phase === "running";
 			const label = action.kind === "pin-dependency" ? t("actionPinLabel")
+				: action.kind === "persist-plugin" ? t("actionPersistLabel")
 				: action.kind === "reconcile-lock" ? t("actionReconcileLabel")
 					: action.kind === "allow-builds" ? t("actionAllowLabel")
 						: action.kind === "overwrite-preset" ? t("actionOverwritePresetLabel")

package/lib/server/domain/bundle-refs.js

@@ -31,8 +31,15 @@ function readBundlePatchRefNames(profileDir, pkgName) {
       if (/^- insert:\s*$/u.test(line)) { inInsert = true; continue }
       if (/^- /u.test(line) && !/^ {4}- /u.test(line)) inInsert = false
       if (!inInsert) continue
-      const nameM = (lines[i + 1] ?? '').match(/^ {6}name: ['"]([^'"]+)['"]\s*$/u)
-      if (nameM) names.push(nameM[1])
+      // ★ 2026-10-04 改错（0.5.38）：`name:` 的值**加不加引号都是合法 YAML** —— 真机 dsh-whale-widget
+      // 写的是不带引号的 `name: dsh-whale-widget`，旧判据只认带引号 ⇒ 引用清单为空 ⇒ 注册前的
+      // "引用包是否都可解析"这道防崩闸门对这类包**形同不存在**。现在两种形态都认。
+      const nameM = (lines[i + 1] ?? '').match(/^ {6}name:\s*(.+?)\s*$/u)
+      if (nameM) {
+        const raw = nameM[1].replace(/\s+#.*$/u, '').trim()
+        const value = /^(['"]).*\1$/u.test(raw) ? raw.slice(1, -1) : raw
+        if (value !== '') names.push(value)
+      }
     }
     return names
   } catch { return [] }

package/lib/server/domain/install-cleanup.js

@@ -1,11 +1,13 @@
-// L1 · domain —— install-cleanup.js（安装失败清场 + 授权被拒/超时后的失败文案）
+// L1 · domain —— install-cleanup.js（安装失败清场 + 授权被拒/超时后的失败文案 + pnpm remove）
 // 2026-09-27 从 install-job.js 原样搬出（install-job.js 触到 600 行硬顶，见 test-architecture-guard.mjs）。
 // 只搬移、未改逻辑；install-job.js 继续 re-export 这两个名字，调用点与测试的 import 面一个字都没变。
+// 2026-10-04：`pnpmRemove` 同样**原样搬入**（0.5.38 要给安装收口腾行数；卸载路径与清场同族）。
 
 import { existsSync, readdirSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import { AI_CONSENT_TIMEOUT_MS } from './install.js'
 import { disposeDir, disposeNote } from '../infra/fsx.js'
+import { buildPnpmEnv, runPnpmWithFallback } from '../infra/exec.js'
 
 /** 安装失败清场：把本次尝试过的候选包目录与 pnpm `_tmp_` 半成品一起清掉，并**如实汇报**清了什么、什么没清掉
  * （2026-09-20 真装演练：聚合仓库跑 19 分钟后失败，node_modules 留着 `…_tmp_56272_2` 半成品，面板只说"安装失败"）。
@@ -59,4 +61,23 @@ function aiConsentFailureText(decision, leftovers, timeoutMs = AI_CONSENT_TIMEOU
   return `${base}${cleanedNote}${trashedNote}${failedNote}`
 }
 
-export { cleanupAttemptedCandidates, aiConsentFailureText }
+/** 用 corepack pnpm 移除包（与安装同一管理器与凭据抑制环境）。
+ * 注意：pnpm remove 不支持 --registry 选项，去掉避免静默失败。
+ * 2026-10-04 从 install-job.js **原样搬入**（那边要给安装收口腾行数；install-job.js 继续 re-export）。 */
+async function pnpmRemove(profileDir, packageName) {
+  const args = ['remove', packageName]
+  const opts = {
+    cwd: profileDir,
+    timeout: 120000,
+    windowsHide: true,
+    maxBuffer: 4 * 1024 * 1024,
+    // 2026-09-26：env 统一走 buildPnpmEnv（在既有 COREPACK_NPM_REGISTRY / 禁交互之上追加
+    // npm_config_fetch_timeout / npm_config_fetch_retries / CI=true）。**不加** --fetch-timeout 类
+    // CLI 选项：实测 `pnpm remove --fetch-timeout=…` 会 `[ERROR] Unknown options` 直接失败。
+    env: buildPnpmEnv('https://registry.npmmirror.com'),
+  }
+  // 与 pnpmInstall 同一套跨平台定位（Linux 的 corepack 不在 <node bin>/node_modules 下）
+  await runPnpmWithFallback(args, { execOpts: opts })
+}
+
+export { cleanupAttemptedCandidates, aiConsentFailureText, pnpmRemove }

package/lib/server/domain/install-job.js

@@ -2,13 +2,12 @@
 // 分层 Step 8c-2 从 lib/index.js 搬出；形参由 ctx 收窄为 ports（调用方注入的窄接口），只搬移未改逻辑。
 // 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
-import { readFileSync, existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { aiRepair } from './ai-run.js'
 import { maybeAutoAdaptCompat } from './compat.js'
 import { getReposDir } from './repoland.js'
-import { aiConsentFailureText, cleanupAttemptedCandidates } from './install-cleanup.js'
+import { aiConsentFailureText, cleanupAttemptedCandidates, pnpmRemove } from './install-cleanup.js'
 import { GIT_CHANNEL_BUDGET_MS, GIT_MIN_ATTEMPT_MS, GIT_SPEC_TIMEOUT_MS, gitChannelBudgetMs, noteChannel, formatBudgetMs, tryGitChannel } from './git-channel.js'
 import { DEFAULT_BUNDLES, AI_CONSENT_TIMEOUT_MS, PNPM_INSTALL_TIMEOUT_MS, addBundleToManifest, backfillMissingDeps, curlManualInstall, detectBundleOnly, ensureBundlePatchIntegrity, githubReleaseInstall, pnpmInstall, raceInstallChannels, readGithubAuth, syncAggregateSubpackageVersions } from './install.js'
 import { readBundlePatchRefNames } from './bundle-refs.js' // 0.5.26 搬家：install.js 贴着 600 行硬顶
@@ -19,14 +18,14 @@ import { tryPresetSourceChannel } from './preset-source.js'
 import { settlePresetOutcome } from './preset-in-package.js'
 import { alreadyInstalledTarget, verifyInstalledEntry } from './install-verify.js'
 import { applyNpmNameHint, expandSubpackageCandidates, fetchRepoPackage, fetchRepoPackageEx, fetchSubpackageNames, npmNameHintForRepo, packageProbeErrorText, subpackageCandidates } from './market.js'
-import { declareProfileDependency } from './manifest.js'
-import { appendInsert, readPatchState, syncNameFromNote } from './patch.js'
-import { deriveEntryId, listEntries } from './runtime.js'
+import { ensurePersisted } from './persist.js'
+import { readPatchState, syncNameFromNote } from './patch.js'
+import { listEntries } from './runtime.js'
 import { detectSkillRepo, runSkillInstallJob } from './skills.js'
 import { orderedRegistries, readSources } from './sources.js'
 import { reconcileLockfile } from './selfupdate.js'
 import { fetchRepoMeta, runSuiteInstallJob, shouldRunSuiteInstall } from './suite.js'
-import { buildPnpmEnv, execFileAsync, runPnpmWithFallback } from '../infra/exec.js'
+import { execFileAsync } from '../infra/exec.js'
 import { cleanupStalePackageDir, startTrashCleanup, trashScanRoots } from '../infra/fsx.js'
 import { findPatchPath, packageNameOf, resolvePackageJson } from '../infra/paths.js'
 
@@ -224,14 +223,6 @@ async function runInstallJob(job, ports, deps = {}) {
   // 源码通道（体积门禁 + 稀疏取源码 + 预设装配）的注入缝：与 marketProbes 同一风格，生产调用方不传。
   const sourceDeps = deps.sourceDeps ?? {}
   const aiConsentTimeoutMs = Number.isFinite(deps.aiConsentTimeoutMs) && deps.aiConsentTimeoutMs > 0 ? deps.aiConsentTimeoutMs : AI_CONSENT_TIMEOUT_MS
-  /** 「安装即声明」的收尾（三个调用点共用一个出口）：清单写回结果 → job 上的可见字段。
-   *  depNote / suggestedAction 也在这里落地：面板必须能看见"清单里**实际**写成了什么"，以及"没写成时点哪个按钮"。 */
-  const applyDeclared = (declared) => {
-    if (declared.changed) job.declared = declared.version
-    if (declared.depNote !== null) job.depNote = declared.depNote
-    if (declared.suggested !== null) job.suggestedAction = declared.suggested
-    if (declared.lockSynced === false && declared.lockNote !== null) job.lockNote = declared.lockNote
-  }
   try {
     job.stage = 'preparing'
     // 2026-09-06 事故（室友机器）：对 deepseek-ai/deepseek-harness（框架本体仓库）点安装会按 bundle 规则
@@ -479,7 +470,10 @@ async function runInstallJob(job, ports, deps = {}) {
     // lock 对账（2026-09-21，用户报告的自更新缺陷同源）：主包 + 本次被补装/对齐的聚合子包一起核对，
     // 一次 pnpm add 把漂移的包全写进 lock；对不上就留 lockNote，让面板如实告知（不假装成功）。
     try {
-      const lock = await reconcileLockfile({
+      // 同一个离线测试缝（见下方 `deps.persistDeps` 注释）：安装路径上"动 lock"的两处都归它，
+      // 否则负控里这一处会先偷偷把 lock 写齐，收口那一步就再也测不出"未持久化"。
+      const reconcile = typeof deps.persistDeps?.reconcile === 'function' ? deps.persistDeps.reconcile : reconcileLockfile
+      const lock = await reconcile({
         profileDir,
         packages: [installedName, ...syncedNames].map((name) => ({ name })),
         registries,
@@ -501,7 +495,14 @@ async function runInstallJob(job, ports, deps = {}) {
     const alreadyServed = listEntries(ports).some((e) => String(e.moduleName).startsWith(installedName)
       || String(e.moduleName) === installedName
       || packageNameOf(e.moduleName) === installedName)
+    // 安装收口（0.5.38）：**一次动作内**把该插件钉住 —— ① 清单 spec ② pnpm-lock.yaml 条目
+    // ③ 挂载行（cordis.patch.yml 的 insert 行 / dsh.profile.bundles 的 bundle 层）。
+    // 三处齐备才算 `persisted`；缺任何一处都**如实**报「未持久化」+ 一键钉住动作 —— 绝不报成功
+    // （用户真机现场：dshmarket 装了、bundle 行挂着，清单里却没有条目 ⇒ 重启/任何 pnpm 操作即消失）。
+    // 判据与写入的唯一承担者是 domain/persist.js（别处不许再各判一套）。
+    let mode = 'insert'
     if (await detectBundleOnly(profileDir, installedName)) {
+      mode = 'bundle'
       // 官方 dsh plugin add 行为：声明 dsh.bundle 的包追加为 profile bundle 层，
       // 其 cordis.patch.yml 在下次启动时参与组合（含皮肤包与 web-ui-settings 这类有入口的包）
       if (!alreadyServed) {
@@ -521,23 +522,27 @@ async function runInstallJob(job, ports, deps = {}) {
       } else {
         job.bundleNote = (job.bundleNote ? job.bundleNote + '；' : '') + `${installedName} 已由已安装聚合包提供，仅更新包本身，不再注册重复行`
       }
-      // 安装即声明（2026-09-24）：装到哪版就写进 profile 清单并立刻同步 lock —— 只写清单不写 lock 会让
-      // 之后任何 pnpm 操作硬失败（ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS）。2026-09-27：写回**形态**由
-      // registry 可解析性决定（非 registry 包写 link:，见 manifest.js#planDependencySpec），故必须传 registries。
-      applyDeclared(await declareProfileDependency(profileDir, installedName, null, { registries }))
-      job.status = 'done'
-      return
-    }
-    if (alreadyServed) {
+    } else if (alreadyServed) {
+      mode = 'served'
       job.note = `${installedName} 已由已安装条目提供，仅更新包本身，不重复注册`
-      applyDeclared(await declareProfileDependency(profileDir, installedName, null, { registries }))
-      job.status = 'done'
-      return
     }
-    const entryId = deriveEntryId(installedName, taken)
-    await appendInsert(patchPath, entryId, installedName)
-    job.entryId = entryId
-    applyDeclared(await declareProfileDependency(profileDir, installedName, null, { registries }))
+    // `deps.persistDeps` 是**离线测试缝**（与 marketProbes/sourceDeps 同一风格）：正控/负控必须能
+    // 确定性地让 lock 那一步失败（"故意让 lock 写入失败 ⇒ 必须报未持久化而不是成功"），
+    // 生产调用方不传第三个参数时形状与默认值一个字都不变。
+    const persist = await ensurePersisted({ profileDir, patchPath, packageName: installedName, mode, taken, entries: listEntries(ports), registries, deps: deps.persistDeps ?? {} })
+    const persistNotes = [persist.declared?.depNote, persist.declared?.lockNote, persist.lock?.lockNote, persist.lock?.depNote, ...persist.notes]
+      .filter((n) => typeof n === 'string' && n !== '')
+    if (persistNotes.length > 0) job.depNote = job.depNote === undefined ? persistNotes.join('；') : `${job.depNote}；${persistNotes.join('；')}`
+    if (persist.declared?.changed === true) job.declared = persist.declared.spec
+    // entryId 的语义**与旧行为一致**：只有"用户补丁里的 insert 行"才算本作业注册的行（bundle 层提供的行
+    // 与运行时已有行都不算，旧代码在这两条路上也不设 entryId）——撤销安装的归属判定依赖这一点。
+    job.entryId = persist.after.parts.mount.via === 'patch-row' ? (persist.rowId ?? null) : null
+    job.persisted = persist.persisted
+    job.persist = { missing: persist.missing, actual: persist.after.actual, note: persist.note }
+    if (persist.persisted !== true) {
+      job.persistNote = persist.note
+      if (persist.suggested !== null && persist.suggested !== undefined && (job.suggestedAction === undefined || job.suggestedAction === null)) job.suggestedAction = persist.suggested
+    }
     job.status = 'done'
   } catch (error) {
     job.status = 'failed'
@@ -546,23 +551,6 @@ async function runInstallJob(job, ports, deps = {}) {
     job.finishedAt = Date.now()
   }
 }
-/** 用 corepack pnpm 移除包（与安装同一管理器与凭据抑制环境）。
- * 注意：pnpm remove 不支持 --registry 选项，去掉避免静默失败。 */
-async function pnpmRemove(profileDir, packageName) {
-  const args = ['remove', packageName]
-  const opts = {
-    cwd: profileDir,
-    timeout: 120000,
-    windowsHide: true,
-    maxBuffer: 4 * 1024 * 1024,
-    // 2026-09-26：env 统一走 buildPnpmEnv（在既有 COREPACK_NPM_REGISTRY / 禁交互之上追加
-    // npm_config_fetch_timeout / npm_config_fetch_retries / CI=true）。**不加** --fetch-timeout 类
-    // CLI 选项：实测 `pnpm remove --fetch-timeout=…` 会 `[ERROR] Unknown options` 直接失败。
-    env: buildPnpmEnv('https://registry.npmmirror.com'),
-  }
-  // 与 pnpmInstall 同一套跨平台定位（Linux 的 corepack 不在 <node bin>/node_modules 下）
-  await runPnpmWithFallback(args, { execOpts: opts })
-}
 /** 读取用户额外 bundle（非官方模板）的补丁插入行 id 与包名，用于"额外插件"判定。 */
 async function readExtraBundleRows(profileDir) {
   const rows = new Set()

package/lib/server/domain/install.js

@@ -546,6 +546,9 @@ function installJobView(job) {
     diagnosis: job.diagnosis ?? null,
     // 装后校验与下载物摘要（2026-09-26 加法，见 install-verify.js）：**只提示**，不改变既有成功判定
     entryCheck: job.entryCheck ?? null, integrity: job.integrity ?? null,
+    // 持久化判据（0.5.38 加法，见 domain/persist.js）：`persisted:false` ⇒ 面板必须报「未持久化」
+    // （重启/任何一次 pnpm 操作后可能消失）并给出「一键钉住」动作 —— 绝不报"安装成功"。
+    persisted: job.persisted ?? null, persistNote: job.persistNote ?? null, persist: job.persist ?? null,
   }
 }
 

package/lib/server/domain/manifest.js

@@ -240,6 +240,27 @@ async function pinProfileDependency(profileDir, packageName, options = {}) {
   return { ok: after === spec, spec, before, after, changed, dir }
 }
 
+/**
+ * 把清单里的该包 spec **原样写成给定值**（0.5.38 加法，供 domain/persist.js 的持久化收口用）。
+ * 场景：`node_modules/<包名>` 是指向**用户自己位置**的链接（开发目录 / 别的盘），而清单里没有条目。
+ * 此时"按磁盘真实值写 spec"就是写这条链接本身 —— 走 `pinProfileDependency` 会把它**物化复制**到
+ * plugin-src 并把 spec 换成一个新拷贝，等于悄悄改掉用户的来源（那是另一件事，不该由收口代做）。
+ * 只碰 `dependencies[packageName]` 这一个键，走同一把写队列；返回 `{ before, after, changed }`。
+ */
+async function setProfileDependency(profileDir, packageName, spec) {
+  const before = await specOf(profileDir, packageName)
+  const changed = await queuedWrite(async () => {
+    const manifest = await readManifest(profileDir)
+    const deps = { ...(manifest.dependencies ?? {}) }
+    if (deps[packageName] === spec) return false
+    deps[packageName] = spec
+    manifest.dependencies = deps
+    await writeManifest(profileDir, manifest)
+    return true
+  })
+  return { before, after: await specOf(profileDir, packageName), changed }
+}
+
 /** 卸载即撤销声明。 */
 async function undeclareProfileDependency(profileDir, packageName) {
   return queuedWrite(async () => {
@@ -305,5 +326,5 @@ async function applyDependencyBackfill(profileDir, options = {}) {
 export {
   DEFAULT_BUNDLES, addBundleToManifest, applyDependencyBackfill, declareProfileDependency,
   installedVersionOf, planDependencyBackfill, planDependencySpec, pinProfileDependency, removeBundleFromManifest,
-  specOf, syncLockFor, undeclareProfileDependency,
+  setProfileDependency, specOf, syncLockFor, undeclareProfileDependency,
 }

package/lib/server/domain/patch.js

@@ -153,7 +153,13 @@ function sanitizePatchText(text) {
     .replace(/\s+$/u, '') + '\n'
 }
 
-/** 解析用户补丁中 insert 块的 id → moduleName（name 字段）。 */
+/** 解析用户补丁中 insert 块的 id → moduleName（name 字段）。
+ *  ★ 2026-10-04 改错（真机发现，0.5.38）：`name:` 的值**加了引号才算**是错的 —— YAML 里
+ *    `name: dsh-whale-widget` 与 `name: 'dsh-whale-widget'` 完全等价，而本机真装的
+ *    `dsh-whale-widget`（插件市场里的真实第三方插件）写的正是**不带引号**的那种。
+ *    旧判据只认带引号的值 ⇒ 那一行在解析结果里**根本不存在**：补丁自愈看不见它、
+ *    装后校验看不见它、撤销安装也看不见它（"行明明在文件里，程序却说没有"）。
+ *    现在两种形态都认（末尾的行内注释也剥掉），解析结果只多不少。 */
 function parseInsertNames(text) {
   const map = new Map()
   const lines = text.split(/\r?\n/u)
@@ -166,8 +172,13 @@ function parseInsertNames(text) {
       const idMatch = line.match(/^\s+- id: ([A-Za-z0-9_.-]+)/u)
       if (idMatch) { curId = idMatch[1]; continue }
       if (curId !== null) {
-        const nameMatch = line.match(/^\s+name: ['"]([^'"]+)['"]/u)
-        if (nameMatch) { map.set(curId, nameMatch[1]); curId = null }
+        const nameMatch = line.match(/^\s+name:\s*(.+?)\s*$/u)
+        if (nameMatch) {
+          const raw = nameMatch[1].replace(/\s+#.*$/u, '').trim()
+          const value = /^(['"]).*\1$/u.test(raw) ? raw.slice(1, -1) : raw
+          if (value !== '') map.set(curId, value)
+          curId = null
+        }
       }
     }
   }

package/lib/server/domain/persist.js

@@ -0,0 +1,384 @@
+// L1 · domain —— persist.js（「下载即持久」的**唯一判据** + **唯一收口动作**；0.5.38 加法）
+//
+// 用户诉求原话（2026-10-04）：「能不能插件下载下来就不用 lock、重启也不会消失」。
+// 现场（desktop profile 的 dshmarket）：包确实下载了、node_modules 里有、bundle 行也挂着，
+// 但 `dependencies` 里没有条目 ⇒ 之后任何一次 pnpm 操作都把它当多余包清掉，
+// 而面板当时报的是「已安装并启用」——**装了没钉住**被报成了成功。
+//
+// 定案（本模块是唯一承担者，别处不许再各判一套）：
+//   「安装完成」= 三处齐备，缺一不可：
+//     ① `<profile>/package.json` 的 `dependencies` 里有该包，且 spec 与**磁盘真实形态**一致
+//        （`node_modules/<包名>` 是指向 plugin-src 的链接 → `link:`；真实目录 → 版本号；
+//         `file:`/`git+`/URL 来源 → 原样保留，绝不改写成版本号）；
+//     ② `<profile>/pnpm-lock.yaml` 里有该包的条目，且与 ① 的 spec 同一形态
+//        （link: 依赖必须也钉在 link:，版本号必须逐字相等）；
+//     ③ 重启后真的会被**挂载**：用户补丁里有它的 insert 行，或它已在 `dsh.profile.bundles` 里
+//        且它自己声明了 `dsh.bundle.patch`（bundle 层会装入它自己的行），或运行时已有行提供它。
+//   三者任一不成立 ⇒ `persisted:false` + `missing` 明细 + 结构化「一键钉住」动作 —— 面板**不许**报成功。
+//
+// 为什么判据必须集中在这一处（两处判据 = 下次框架/包管理器一变只有一处被修好）：
+//   · 读文件的三个入口全部复用既有唯一真源：`profileSpec` / `readInstalledVersion` / `lockVersion`
+//     （domain/selfupdate.js）、`linkSpecIsIntact`（domain/dep-source.js）、`parseInsertNames`
+//     （domain/patch.js）——本模块**不新写任何 lock / 清单 / 补丁解析器**。
+//   · 写入同样复用既有写入器：`pinProfileDependency`（link: 形态）/ `declareProfileDependency`
+//     （registry 探测决定形态）/ `reconcileLockfile`（lock 对账）/ `appendInsert`（补丁行）/
+//     `addBundleToManifest`（bundle 层）——本模块**不新造第二套写入**。
+//
+// 非 registry 来源的既有规矩（照旧，绝不违反）：`link:` / `file:` / `tgz` / git / URL 来源
+// **不经** registry 解析 —— 因此本模块的判据里**没有**任何 "registry 404" 判定：
+//   ① 只比"清单写成什么形态 vs 磁盘是什么形态"，② 只比"lock 里的条目 vs ① 的 spec 形态"。
+//
+// 分层：L1 domain —— 不认识 cordis ctx；IO 与四个写入器都可注入（便于离线单测跑正控/负控）。
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { PLUGIN_SRC_DIR, linkSpecFor, profileNameOf, linkSpecIsIntact } from './dep-source.js'
+import { isUnder } from '../infra/framework-root.js'
+import { addBundleToManifest, declareProfileDependency, pinProfileDependency, setProfileDependency } from './manifest.js'
+import { appendInsert, parseInsertNames } from './patch.js'
+import { deriveEntryId } from './runtime.js'
+import { lockVersion, profileSpec, readInstalledVersion, reconcileLockfile } from './selfupdate.js'
+import { dshHome, packageNameOf } from '../infra/paths.js'
+
+/** 三处缺口的**稳定名字**（面板文案与测试都按它们断言，不许改写）。 */
+const PERSIST_PARTS = ['dependency', 'lock', 'mount']
+
+/** 精确版本号形态（`1.2.3` / `0.0.1-rc1`）：只有它才要求与磁盘版本逐字相等。 */
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u
+/** 来源型 spec 前缀（协议）——这些形态**绝不**改写成版本号（改写等于丢来源）。 */
+const SOURCE_SPEC_RE = /^(?:link:|file:|git\+|git:|github:|https?:|workspace:|portal:)/u
+
+/** 读 profile 清单（读不到返回 null；绝不因为读不到就抛）。 */
+function readManifestSync(profileDir) {
+  try {
+    return JSON.parse(readFileSync(join(String(profileDir), 'package.json'), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** `dsh.profile.bundles`（读不到就空数组）。 */
+function readBundlesSync(profileDir) {
+  const manifest = readManifestSync(profileDir)
+  const bundles = manifest?.dsh?.profile?.bundles
+  return Array.isArray(bundles) ? bundles.filter((x) => typeof x === 'string' && x !== '') : []
+}
+
+/**
+ * 磁盘**真实形态**（不猜）：`node_modules/<包名>` 是指向别处的链接 → `link:<真实目标>`；
+ * 真实目录 → 版本号；都没有 → missing。
+ * Windows 的 junction 在 lstat 里同样是 symbolic link；`realpathSync` 拿到**规范化后的目标**
+ * （与 `linkSpecIsIntact` 的判据同一把尺子，因此"清单写的绝对路径"不必与磁盘逐字相同也算数）。
+ */
+function diskFormOf(profileDir, packageName) {
+  const dir = join(String(profileDir), 'node_modules', ...String(packageName).split('/'))
+  const version = readInstalledVersion(profileDir, packageName)
+  if (!existsSync(join(dir, 'package.json'))) return { form: 'missing', spec: null, version, target: null }
+  try {
+    if (lstatSync(dir).isSymbolicLink()) {
+      const target = realpathSync(dir)
+      return { form: 'link', spec: linkSpecFor(target), version, target }
+    }
+  } catch {}
+  return { form: 'version', spec: version, version, target: null }
+}
+
+/** ① 依赖声明：清单里的 spec 与磁盘真实形态是否一致。 */
+function dependencyPart({ profileDir, packageName }) {
+  const spec = profileSpec(profileDir, packageName)
+  const disk = diskFormOf(profileDir, packageName)
+  const out = { ok: false, spec, form: null, disk: { form: disk.form, version: disk.version }, reason: null }
+  if (spec === null) {
+    out.reason = 'package.json 的 dependencies 里没有这个条目（pnpm 会把它当多余包清掉）'
+    return out
+  }
+  const trimmed = spec.trim()
+  if (trimmed.startsWith('link:')) {
+    out.form = 'link'
+    if (disk.form !== 'link') {
+      out.reason = `清单是 ${trimmed}，但 node_modules/${packageName} 不是指向它的链接（磁盘上实际是 ${disk.form === 'missing' ? '不存在' : '真实目录'}）`
+      return out
+    }
+    if (!linkSpecIsIntact(profileDir, packageName, trimmed)) {
+      out.reason = `清单是 ${trimmed}，但链接当前不成立（目标不存在或指向别处）`
+      return out
+    }
+    out.ok = true
+    return out
+  }
+  if (SOURCE_SPEC_RE.test(trimmed)) {
+    // file: / git+ / URL / workspace: …：来源即事实，本地无法逐字校验 ⇒ 有条目即算就位（绝不改写成版本号）
+    out.form = 'source'
+    out.ok = true
+    return out
+  }
+  if (EXACT_VERSION_RE.test(trimmed)) {
+    out.form = 'version'
+    if (disk.version === null) {
+      out.reason = '清单写的是版本号，但 node_modules 里读不到该包的版本（没装或被还原）'
+      return out
+    }
+    if (disk.version !== trimmed) {
+      out.reason = `清单写 ${trimmed}，磁盘上是 ${disk.version} —— 两处对不上`
+      return out
+    }
+    out.ok = true
+    return out
+  }
+  // 版本范围（^1.2.3）或 dist-tag（latest/next）：registry 来源但非精确值 —— 有条目且装上了即算就位
+  out.form = 'range'
+  if (disk.version === null) {
+    out.reason = `清单写 ${trimmed}，但 node_modules 里读不到该包（没装或被还原）`
+    return out
+  }
+  out.ok = true
+  return out
+}
+
+/** ② lock 条目：与 ① 的 spec 同一形态（link: ↔ link:；精确版本 ↔ 逐字相等）。 */
+function lockPart({ profileDir, packageName, spec }) {
+  const entry = lockVersion(profileDir, packageName)
+  const out = { ok: false, entry: entry ?? null, reason: null }
+  if (entry === null || entry === undefined) {
+    out.reason = 'pnpm-lock.yaml 里没有这个包的条目（任何一次 pnpm 操作都可能把它还原/清掉）'
+    return out
+  }
+  const value = String(entry).trim()
+  const s = typeof spec === 'string' ? spec.trim() : ''
+  if (s.startsWith('link:')) {
+    if (value.startsWith('link:')) {
+      out.ok = true
+      return out
+    }
+    out.reason = `清单把该包钉在 ${s}，而 lock 里是 ${value}（对账后会被 pnpm 还原）`
+    return out
+  }
+  if (EXACT_VERSION_RE.test(s)) {
+    // lock 的 importer `version:` 对**带 peer 的**包会写成 `0.2.0-rc.2(@scope/peer@x)`（真机
+    // `@deepseek-ai/dsh-experimental-schedule-bundle` 就是这个形态）—— 前导版本号相等即算同版，
+    // 后缀是 pnpm 的 peer 解析记录，不是"另一个版本"。
+    const core = value.replace(/\(.*$/u, '').replace(/_[^_]*$/u, '').trim()
+    if (core === s || value === s) {
+      out.ok = true
+      return out
+    }
+    out.reason = `清单写 ${s}，lock 里是 ${value} —— 两处对不上`
+    return out
+  }
+  // 范围 / dist-tag / 来源型：lock 有条目即算就位（形态由 pnpm 自己解析，本地不猜）
+  out.ok = true
+  return out
+}
+
+/** ③ 挂载行：用户补丁 insert 行 / bundle 层 / 运行时已有行，三者任一成立即算会挂载。 */
+function mountPart({ profileDir, patchPath, packageName, patchText = null, bundles = null, entries = null }) {
+  const out = { ok: false, via: 'none', rowId: null, bundlePatch: null, reason: null }
+  // 运行时已有行提供它（例如聚合包里的行）：最直接的证据，先看
+  if (Array.isArray(entries)) {
+    for (const entry of entries) {
+      const moduleName = String(entry?.moduleName ?? '')
+      if (moduleName === packageName || packageNameOf(moduleName) === packageName) {
+        return { ...out, ok: true, via: 'live-entry', rowId: entry.rowId ?? entry.entryId ?? null }
+      }
+    }
+  }
+  // 用户补丁里的 insert 行
+  let text = patchText
+  if (typeof text !== 'string') {
+    try {
+      text = existsSync(patchPath) ? readFileSync(patchPath, 'utf8') : ''
+    } catch {
+      text = ''
+    }
+  }
+  for (const [id, name] of parseInsertNames(text)) {
+    if (String(name).trim() === packageName) return { ...out, ok: true, via: 'patch-row', rowId: id }
+  }
+  // bundle 层：只有"它自己声明了 dsh.bundle.patch"时框架才会装入它自己的行
+  const list = Array.isArray(bundles) ? bundles : readBundlesSync(profileDir)
+  if (list.includes(packageName)) {
+    const pkgPath = join(String(profileDir), 'node_modules', ...String(packageName).split('/'), 'package.json')
+    let rel = null
+    try {
+      rel = JSON.parse(readFileSync(pkgPath, 'utf8'))?.dsh?.bundle?.patch ?? null
+    } catch {
+      rel = null
+    }
+    if (typeof rel !== 'string' || rel === '') {
+      out.reason = `已在 dsh.profile.bundles 里，但该包没有声明 dsh.bundle.patch —— bundle 层不会装入任何行，需要一条 insert 行`
+      return out
+    }
+    const file = join(String(profileDir), 'node_modules', ...String(packageName).split('/'), rel)
+    if (!existsSync(file)) {
+      out.bundlePatch = file
+      out.reason = `dsh.profile.bundles 里有它，但它声明的 bundle 补丁文件不存在（${file}）`
+      return out
+    }
+    let rows = new Map()
+    try {
+      rows = parseInsertNames(readFileSync(file, 'utf8'))
+    } catch {
+      rows = new Map()
+    }
+    if (rows.size === 0) {
+      out.bundlePatch = file
+      out.reason = `bundle 补丁里读不到任何 insert 行（${rel}）—— 没有任何东西会被挂载`
+      return out
+    }
+    return { ...out, ok: true, via: 'bundle', rowId: [...rows.keys()][0], bundlePatch: file }
+  }
+  out.reason = '用户补丁里没有它的 insert 行，dsh.profile.bundles 里也没有它 —— 重启后不会被挂载'
+  return out
+}
+
+/**
+ * 持久化判据（**只读**，永不抛）：返回
+ * `{ persisted, packageName, missing, parts:{dependency,lock,mount}, note }`。
+ * 三个阶段各自读盘（不信任调用方传进来的 job 字段），missing 的顺序恒为 PERSIST_PARTS 的顺序。
+ */
+function persistReport({ profileDir, patchPath, packageName, entries = null, patchText = null, bundles = null }) {
+  const dep = dependencyPart({ profileDir, packageName })
+  const lock = lockPart({ profileDir, packageName, spec: dep.spec })
+  const mount = mountPart({ profileDir, patchPath, packageName, patchText, bundles, entries })
+  const parts = { dependency: dep, lock, mount }
+  const missing = PERSIST_PARTS.filter((key) => parts[key].ok !== true)
+  const report = {
+    persisted: missing.length === 0,
+    packageName,
+    missing,
+    parts,
+    actual: {
+      spec: dep.spec,
+      lockEntry: lock.entry,
+      mountVia: mount.via,
+      version: dep.disk.version,
+      inBundles: (Array.isArray(bundles) ? bundles : readBundlesSync(profileDir)).includes(packageName),
+    },
+  }
+  report.note = report.persisted ? null : persistNote(report)
+  return report
+}
+
+/** 缺口 → 人话（**如实**：说清实际是什么、缺的是哪一处、后果是什么）。 */
+function persistNote(report) {
+  const labels = { dependency: '① 清单 dependencies', lock: '② pnpm-lock.yaml', mount: '③ 挂载行（cordis.patch.yml / bundles）' }
+  const rows = report.missing.map((key) => `${labels[key]}：${report.parts[key].reason ?? '未就位'}`)
+  return `未持久化（重启或任何一次 pnpm 操作后可能消失）—— ${rows.join('；')}`
+}
+
+/** 结构化「一键钉住」动作（面板据此渲染执行框；命令只供展示/复制，执行侧只认 payload.action）。 */
+function suggestedPersistAction({ packageName, profile = null, profileDir = null, missing = [], reason = null } = {}) {
+  const name = profile ?? profileNameOf(profileDir)
+  const list = Array.isArray(missing) ? missing.filter((m) => typeof m === 'string' && m !== '') : []
+  return {
+    kind: 'persist-plugin',
+    label: '一键钉住（清单 + lock + 挂载行）',
+    command: `dsh-plugin-console: persist-plugin ${packageName}`,
+    payload: { action: 'persist-plugin', packageName, profile: name },
+    missing: list,
+    reason,
+  }
+}
+
+/**
+ * 收口动作（**唯一的写入入口**）：把 ①②③ 里缺的部分补齐，然后**读回磁盘**再判一次。
+ *   · ① 缺/形态不一致 → 按磁盘真实形态写：链接 → `pinProfileDependency`（link: 并物化到 plugin-src）；
+ *     真实目录 → `declareProfileDependency`（自带 registry 可解析性判定：非 registry 来源写 link:）；
+ *   · ② 缺/形态不一致 → `reconcileLockfile`（既有对账通道，argv/写回形态同安装路径）；
+ *   · ③ 缺 → `mode==='bundle'` 时补 `dsh.profile.bundles`；否则追加一条 insert 行（entry id 由
+ *     `deriveEntryId` 按既有规则产出）。`mode==='served'` 时**绝不写行**（已有行提供它，再写就是重复装配）。
+ * 返回 `{ persisted, before, after, missing, declared, lock, notes, suggested, note, rowId }`；
+ * 任何一步失败都**如实**留在 notes 里，绝不影响收口的返回值语义（persisted 只认最终读回结果）。
+ */
+async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'insert', taken = null, entries = null, registries = [], deps = {} } = {}) {
+  const pin = typeof deps.pin === 'function' ? deps.pin : pinProfileDependency
+  const declare = typeof deps.declare === 'function' ? deps.declare : declareProfileDependency
+  const setSpec = typeof deps.setSpec === 'function' ? deps.setSpec : setProfileDependency
+  const reconcile = typeof deps.reconcile === 'function' ? deps.reconcile : reconcileLockfile
+  const insert = typeof deps.insert === 'function' ? deps.insert : appendInsert
+  const addBundle = typeof deps.addBundle === 'function' ? deps.addBundle : addBundleToManifest
+  const notes = []
+  const before = persistReport({ profileDir, patchPath, packageName, entries })
+  let declared = null
+  let lock = null
+  let rowId = before.parts.mount.rowId
+  // ① 依赖声明（按磁盘真实形态写，绝不猜）
+  if (before.parts.dependency.ok !== true) {
+    const disk = diskFormOf(profileDir, packageName)
+    try {
+      if (disk.form === 'link' && isUnder(disk.target, join(dshHome(), PLUGIN_SRC_DIR))) {
+        // 目标已经在 plugin-src 里 → 走既有「钉住」（幂等：realpath 相同则不会重复物化）
+        const pinned = await pin(profileDir, packageName, {})
+        declared = { changed: pinned.changed === true, spec: pinned.after ?? null, form: 'link', lockSynced: null, lockNote: null, depNote: null, suggested: null }
+        notes.push(pinned.changed === true
+          ? `清单已按磁盘真实形态钉成 ${pinned.after}（node_modules 里就是指到这个目录的链接）`
+          : `清单里已是 ${pinned.after ?? '（无条目）'}（无需改动）`)
+      } else if (disk.form === 'link') {
+        // 目标是用户自己的位置（开发目录 / 别的盘）→ **原样写这条链接**，绝不复制成 plugin-src 的新拷贝
+        const wrote = await setSpec(profileDir, packageName, disk.spec)
+        declared = { changed: wrote.changed === true, spec: wrote.after ?? disk.spec, form: 'link', lockSynced: null, lockNote: null, depNote: null, suggested: null }
+        notes.push(`清单已按磁盘真实值写成 ${wrote.after ?? disk.spec}（该链接指向用户自己的位置，未做物化复制）`)
+      } else if (disk.form === 'version') {
+        declared = await declare(profileDir, packageName, disk.version, { registries })
+        if (declared.changed !== true) notes.push(`清单里已有这个包（实际是 ${declared.spec ?? disk.version}）`)
+        if (declared.depNote !== null && declared.depNote !== undefined) notes.push(declared.depNote)
+      } else {
+        notes.push(`node_modules 里读不到 ${packageName} —— 无法判断该写成什么形态，已跳过清单写回（绝不凭空猜一个 spec）`)
+      }
+    } catch (error) {
+      notes.push(`清单写回失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  // ② lock 对账
+  const mid = persistReport({ profileDir, patchPath, packageName, entries })
+  if (mid.parts.lock.ok !== true) {
+    try {
+      lock = await reconcile({ profileDir, packages: [{ name: packageName }], registries })
+      if (lock.lockNote !== null && lock.lockNote !== undefined) notes.push(lock.lockNote)
+      else if (lock.depNote !== null && lock.depNote !== undefined) notes.push(lock.depNote)
+    } catch (error) {
+      notes.push(`lock 对账失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+  } else if (declared !== null && declared.lockSynced === false && declared.lockNote !== null) {
+    notes.push(declared.lockNote)
+  }
+  // ③ 挂载行
+  const pre = persistReport({ profileDir, patchPath, packageName, entries })
+  let bundled = null
+  if (pre.parts.mount.ok !== true && mode !== 'served') {
+    try {
+      if (mode === 'bundle') {
+        bundled = await addBundle(profileDir, packageName)
+      } else {
+        const id = deriveEntryId(packageName, taken instanceof Set ? taken : new Set())
+        const row = await insert(patchPath, id, packageName)
+        rowId = id
+        if (row && row.changed === false && row.reason !== undefined) {
+          notes.push(`未新写补丁行（原因：${row.reason}）—— 由既有声明承担挂载`)
+        }
+      }
+    } catch (error) {
+      notes.push(`挂载行写入失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  const after = persistReport({ profileDir, patchPath, packageName, entries })
+  const suggested = after.persisted ? null : suggestedPersistAction({ packageName, profileDir, missing: after.missing, reason: after.note })
+  return {
+    persisted: after.persisted,
+    before,
+    after,
+    missing: after.missing,
+    parts: after.parts,
+    declared,
+    lock,
+    bundled,
+    rowId: after.parts.mount.rowId ?? rowId ?? null,
+    notes,
+    suggested,
+    note: after.note,
+  }
+}
+
+export {
+  PERSIST_PARTS, EXACT_VERSION_RE, SOURCE_SPEC_RE, readManifestSync, readBundlesSync, diskFormOf,
+  dependencyPart, lockPart, mountPart, persistReport, persistNote, suggestedPersistAction, ensurePersisted,
+}

package/lib/server/domain/plugin-actions.js

@@ -41,13 +41,14 @@ import { NPM_NAME_RE, suggestedAllowBuildsAction } from './dep-source.js'
 import { classifyInstallFailure, ignoredBuildsFrom } from './install-diagnose.js'
 import { runLockfileRepair } from './lockfile-health.js'
 import { pinProfileDependency, specOf } from './manifest.js'
+import { ensurePersisted } from './persist.js'
 import { lockVersion } from './selfupdate.js'
 import { overwritePreset } from './preset-source.js'
 import { buildPnpmEnv, pnpmAddArgs, runPnpmWithFallback, unknownPnpmOption } from '../infra/exec.js'
 
 const DEFAULT_REGISTRY = 'https://registry.npmmirror.com'
 /** 动作白名单（客户端只能给这些 kind；执行分支与 argv 全在服务端）。 */
-const ACTION_KINDS = ['pin-dependency', 'reconcile-lock', 'allow-builds', 'overwrite-preset']
+const ACTION_KINDS = ['pin-dependency', 'reconcile-lock', 'allow-builds', 'overwrite-preset', 'persist-plugin']
 /** 一旦出现这些键就整条拒绝：本接口不存在"传命令"的位置。 */
 const COMMAND_KEYS = ['command', 'cmd', 'argv', 'args', 'exec', 'execute', 'shell', 'script', 'run', 'spawn', 'bin', 'shellCommand']
 const OUTPUT_LIMIT = 4000
@@ -72,8 +73,8 @@ function parseActionRequest(body) {
     return { ok: false, status: 400, error: `未知动作 ${action}（只允许 ${ACTION_KINDS.join(' / ')}）` }
   }
   const packageName = typeof raw.packageName === 'string' ? raw.packageName.trim() : ''
-  if (action === 'pin-dependency') {
-    if (packageName === '') return { ok: false, status: 400, error: 'pin-dependency 需要 packageName' }
+  if (action === 'pin-dependency' || action === 'persist-plugin') {
+    if (packageName === '') return { ok: false, status: 400, error: `${action} 需要 packageName` }
     if (packageName.length > 214 || !NPM_NAME_RE.test(packageName)) return { ok: false, status: 400, error: 'packageName 不是合法的 npm 包名' }
   }
   // allow-builds 的 packageName 可省略（缺省 = 放行当前被忽略的全部）；给了就必须是合法 npm 名。
@@ -252,6 +253,44 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
       detail: applied,
     }
   }
+  if (parsed.action === 'persist-plugin') {
+    // 0.5.38 加法（用户诉求：「插件下载下来就不用 lock、重启也不会消失」）：把三处**一次补齐** ——
+    //   ① 清单 spec（按磁盘真实形态：链接 → link:；真实目录 → 版本号；非 registry 来源照旧不猜）
+    //   ② pnpm-lock.yaml 的条目（走既有对账通道）
+    //   ③ 挂载行（已在 dsh.profile.bundles 的补 dsh.profile.bundles；否则追加 insert 行）
+    // 与 pin-dependency 的边界：pin 只动"来源形态"这一件事（历史行为一个字不改），本动作是**收口**，
+    // 且只在"确实缺"时才写；两者共用同一批写入器（patch.js / manifest.js / selfupdate.js），没有第二套。
+    if (!isProfilePackage(profileDir, parsed.packageName)) {
+      return { ...base, ok: false, status: 400, error: `${parsed.packageName} 不在本 profile 的清单（dependencies / dsh.profile.bundles）里，拒绝改动（先安装）` }
+    }
+    if (!isInstalled(profileDir, parsed.packageName)) {
+      return { ...base, ok: false, status: 400, error: `${parsed.packageName} 没有装在当前 profile 的 node_modules 里，无法钉住（先安装）` }
+    }
+    const ensure = typeof deps.ensurePersisted === 'function' ? deps.ensurePersisted : ensurePersisted
+    let fixed = null
+    try {
+      fixed = await ensure({ profileDir, patchPath: join(profileDir, 'cordis.patch.yml'), packageName: parsed.packageName, mode: 'insert', registries })
+    } catch (error) {
+      return { ...base, ok: false, status: 200, error: `持久化收口失败：${error instanceof Error ? error.message : String(error)}` }
+    }
+    const after = fixed?.after ?? null
+    return {
+      ...base,
+      ok: fixed?.persisted === true,
+      partial: fixed?.persisted !== true && (after?.parts?.dependency?.ok === true || after?.parts?.lock?.ok === true),
+      exitCode: fixed?.persisted === true ? 0 : 1,
+      command: `dsh-plugin-console: persist-plugin ${parsed.packageName}`,
+      manifest: { before: fixed?.before?.actual?.spec ?? null, after: after?.actual?.spec ?? null, changed: fixed?.declared?.changed === true, pinned: after?.parts?.dependency?.form === 'link' },
+      lock: { entry: after?.actual?.lockEntry ?? null, synced: after?.parts?.lock?.ok === true },
+      patch: { rowId: fixed?.rowId ?? null, via: after?.actual?.mountVia ?? null },
+      notes: Array.isArray(fixed?.notes) ? fixed.notes : [],
+      reason: fixed?.persisted === true
+        ? `${parsed.packageName} 已持久化：清单（${after?.actual?.spec ?? '?'}）+ lock（${after?.actual?.lockEntry ?? '?'}）+ 挂载（${after?.actual?.mountVia ?? '?'}）`
+        : (fixed?.note ?? '仍有一处没就位'),
+      missing: Array.isArray(fixed?.missing) ? fixed.missing : [],
+      detail: { before: fixed?.before ?? null, after },
+    }
+  }
   if (parsed.action === 'reconcile-lock') {
     const view = await repair({ profileDir, registries: Array.isArray(registries) && registries.length > 0 ? registries : [registry] })
     const done = view?.action === 'repaired' || view?.action === 'noop'

package/lib/server/domain/selfupdate.js

@@ -72,8 +72,16 @@ function lockVersion(profileDir, name) {
     return null
   }
   for (let i = 0; i < lines.length; i += 1) {
-    const bare = lines[i].trim().replace(/^'|':?$/gu, '').replace(/'$/u, '')
-    if (bare === name || lines[i].trim() === `'${name}':`) {
+    const trimmed = lines[i].trim()
+    // 键形态三种都认（0.5.38 改错）：`name`、`'name':`（pnpm 对**含 `/`/`@`** 的包名加引号）、
+    // `name:`（pnpm 对**未加 scope** 的包名不加引号）。旧判据漏了第三种 ⇒ 未加 scope 的 `link:`
+    // 依赖在 importers 里明明有条目却读不出来（真机 desktop profile 的 `dshmarket` 就是：
+    // lock 的 35-37 行写着 `dshmarket: / specifier: link:… / version: link:../../plugin-src/dshmarket`，
+    // 而 `lockVersion()` 返回 null）——后果是面板永远报"没写进 pnpm-lock.yaml"、pin 永远 partial、
+    // 每次对账都白跑一次 `pnpm add`。真值一律从下面这一处读，别在调用方再补一套。
+    const bare = trimmed.replace(/^'|':?$/gu, '').replace(/'$/u, '')
+    const bareKey = trimmed.replace(/'$/u, '').replace(/:$/u, '')
+    if (bare === name || bareKey === name || trimmed === `'${name}':`) {
       for (let k = i + 1; k < Math.min(i + 8, lines.length); k += 1) {
         const m = /^\s*version:\s*(\S+)\s*$/u.exec(lines[k])
         if (m) return m[1]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.37",
+  "version": "0.5.38",
   "description": "DSH 框架升级安全与插件升级门控：一键升级、失败自动回滚、升级后回滚上版、旧插件不适配自动禁用；内置多源插件市场为发现层，插件源全部可自定义，可指向公司内网私有源 / 私有索引 / 本地 Git 仓库，纯内网离线可用 | Framework upgrade safety & plugin version gating for DSH, with a customizable multi-source plugin market: point every source at internal mirrors or a local file:// repo for intranet-only, offline installs.",
   "repository": {
     "type": "git",