@noob-stupid/dsh-plugin-console 0.5.77 → 0.5.87

package/lib/server/domain/install-jobs-store.js

@@ -0,0 +1,72 @@
+// L1 · domain —— 安装/更新作业的**持久化**（0.5.83）
+//
+// 今天排障最大的障碍：installJobs 是**内存表**，宿主一重启就清空 ——
+//   用户点了更新、作业卡住或失败，重启后我**查不到它到底干了什么**（本次连"版本号有没有传下去"都只能靠猜）。
+// 与「待重启徽章」同一个病根（那个已用 pending-restart.json 修好）。
+//
+// 本模块把**已结束**的作业（done / failed）追加到 <DSH_HOME>/plugin-console/install-jobs.json：
+//   · 只保留最近 N 条（默认 50），文件不会无限增长；
+//   · 只记**诊断需要的字段**，不复制整个 job（避免把大对象/敏感信息落盘）；
+//   · 任何异常都吞掉并降级为"没有持久记录"（绝不因为写日志失败影响安装本身）。
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { dshHome } from '../infra/paths.js'
+
+const INSTALL_JOBS_FILE = 'install-jobs.json'
+const KEEP = 50
+
+function installJobsPath(home = undefined) {
+  return join(home ?? dshHome(), 'plugin-console', INSTALL_JOBS_FILE)
+}
+
+/** 只挑诊断需要的字段（多余的一律不落盘）。 */
+function pickJobFields(job) {
+  if (job === null || typeof job !== 'object') return null
+  const id = typeof job.id === 'string' ? job.id : (typeof job.jobId === 'string' ? job.jobId : null)
+  if (id === null) return null
+  return {
+    jobId: id,
+    packageName: typeof job.packageName === 'string' ? job.packageName : null,
+    repo: typeof job.repo === 'string' ? job.repo : null,
+    status: typeof job.status === 'string' ? job.status : null,
+    stage: typeof job.stage === 'string' ? job.stage : null,
+    version: typeof job.version === 'string' ? job.version : null,
+    // ★ 0.5.87：目标版本（上一行）与**真正落盘的版本**是两件事 —— 真机 2026-10-18 就是
+    // "version=0.2.1-rc.2、盘上还是 0.1.6-alpha.1"却记成 done，事后没人能从这条记录里看出没落地。
+    installedVersion: typeof job.installedVersion === 'string' ? job.installedVersion : null,
+    error: typeof job.error === 'string' ? job.error.slice(0, 500) : null,
+    source: typeof job.source === 'string' ? job.source : null,
+    startedAt: Number.isFinite(Number(job.startedAt)) ? Number(job.startedAt) : null,
+    finishedAt: Number.isFinite(Number(job.finishedAt)) ? Number(job.finishedAt) : Date.now(),
+  }
+}
+
+function readInstallJobs({ home = undefined } = {}) {
+  try {
+    const raw = JSON.parse(readFileSync(installJobsPath(home), 'utf8'))
+    const list = raw !== null && typeof raw === 'object' && Array.isArray(raw.items) ? raw.items : []
+    return list.filter((x) => x !== null && typeof x === 'object' && typeof x.jobId === 'string')
+  } catch { return [] }
+}
+
+/**
+ * 记录一条**已结束**的作业；进行中的不写（否则每次轮询都写盘）。
+ * @returns {{ saved: boolean, reason?: string }}
+ */
+function recordInstallJob(job, { home = undefined } = {}) {
+  const picked = pickJobFields(job)
+  if (picked === null) return { saved: false, reason: 'job 形状不可识别' }
+  if (picked.status !== 'done' && picked.status !== 'failed') return { saved: false, reason: '作业尚未结束' }
+  try {
+    const prev = readInstallJobs({ home }).filter((x) => x.jobId !== picked.jobId)
+    const items = [...prev, picked].slice(-KEEP)
+    const file = installJobsPath(home)
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, `${JSON.stringify({ items }, null, 2)}\n`, 'utf8')
+    return { saved: true }
+  } catch (error) {
+    return { saved: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export { INSTALL_JOBS_FILE, installJobsPath, readInstallJobs, recordInstallJob }

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

@@ -0,0 +1,65 @@
+// L1 · domain —— install-version.js（「更新到的到底是哪一版」的**唯一判据**；2026-10-18 新增，纯加法）
+//
+// 真机缺陷（2026-10-18，用户实测，父任务已确认现场）：
+//   点「更新并适配」`@deepseek-ai/dsh-experimental-auto-review`（0.1.6-alpha.1 → 0.2.1-rc.2），
+//   请求体显式带 `version: "0.2.1-rc.2"`，作业跑完**报 done、version=0.2.1-rc.2、error=null**，
+//   而磁盘与清单**都还是 0.1.6-alpha.1**。
+//   根因不是"版本号没传下去"，而是**没人核对最终落地的是不是目标版本**：
+//   该包在 registry 上的 `dist-tags.latest` 恰好就是旧版 0.1.6-alpha.1（rc 版从不打 latest），
+//   于是"按最新版下载"的通道（curl）把**旧版**铺回 node_modules，凡是"按名报成功"的判据都看不出异常。
+//
+// 本模块只做一件此前没人做的事：**把请求里点名的版本与磁盘上真实的版本比一比**。
+// 为什么不塞进 install-verify.js：那个模块的契约是"只提示、绝不改成功判定"（见它的顶部硬规矩①），
+// 而这里的结论**必须能否决一次成功**——两者语义相反，放一个文件里迟早会被下一个人混用。
+//
+// 三条硬规矩：
+//   ① 只读：只读 node_modules/<包名>/package.json 的 version 字段，绝不写盘、绝不改动清单；
+//   ② 只对"点名了版本"的请求生效（`job.version` 为空 = 照旧按 latest，判据恒 null，行为一字不变）；
+//   ③ 绝不猜：读不到版本时 actual 记 null，**不**据此报"不是目标版本"以外的任何结论（见 versionMissText）。
+import { readInstalledVersion } from './selfupdate.js'
+
+/** 这次作业**点名**要装的那个版本（没有点名 / 不是点名的那个包 ⇒ null）。
+ *
+ * 为什么必须逐字比包名：`job.version` 是"目标包的目标版本"，而候选循环里的 `name` 可能是自动展开出的
+ * 任意子包（聚合仓库）。给子包套用父候选的版本号＝给一个根本没发布这个版本号的包下精确规格，
+ * 会把"本来能装"变成"404 装不上"（与 domain/install-channels.js 顶部 ① 条同一条理由）。
+ * 版本号只对**用户点名的那一件**成立 —— 传进来的 name 必须与 job.packageName 逐字相等。 */
+function targetVersionOf(job, name) {
+  const version = typeof job?.version === 'string' ? job.version.trim() : ''
+  if (version === '' || typeof name !== 'string' || name === '') return null
+  return name === job.packageName ? version : null
+}
+
+/**
+ * 磁盘上真实的版本 vs 目标版本（**只读**，永不抛）。
+ * 返回 null 表示"无需/无法判定"：
+ *   · 没点名版本（按 latest 装的请求）—— 既有流程一字不动；
+ *   · 磁盘上就是目标版本 —— 通道这次真的把版本装对了。
+ * 返回 `{ kind:'version-miss', packageName, expected, actual, channel }` 表示**没装上目标版本**。
+ * `channel` 由调用方填（哪个通道声称装上了），只用于如实告知，不参与判定。
+ */
+function versionMissOf(profileDir, name, job, channel = null) {
+  const expected = targetVersionOf(job, name)
+  if (expected === null) return null
+  const actual = readInstalledVersion(profileDir, name)
+  if (actual === expected) return null
+  return {
+    kind: 'version-miss',
+    packageName: name,
+    expected,
+    actual: typeof actual === 'string' && actual !== '' ? actual : null,
+    channel: typeof channel === 'string' && channel !== '' ? channel : null,
+  }
+}
+
+/** 一句话如实说清"哪一版没装上、盘上现在是什么"（作业 error / 通道备注共用一份文案）。 */
+function versionMissText(miss) {
+  if (miss === null || typeof miss !== 'object') return null
+  const actual = miss.actual === null || miss.actual === undefined ? '（磁盘上读不到版本）' : String(miss.actual)
+  const via = miss.channel === null || miss.channel === undefined ? '' : `${miss.channel} 通道`
+  return `目标版本 ${miss.expected} 没有装上：${via === '' ? '本次' : via}落地的是 ${actual}`
+    + '（多半是镜像的 dist-tags.latest 还指着旧版，按"最新版"下载就会拿到它）。'
+    + '已保留磁盘上现有的这一版、清单未改动；可换源后重试，或稍等镜像同步。'
+}
+
+export { targetVersionOf, versionMissOf, versionMissText }

package/lib/server/domain/install.js

@@ -16,6 +16,8 @@ import { downloadReleaseArtifact, releaseInstallTarget, selectReleaseInstall } f
 import { verifyTarballDigest } from './install-verify.js'
 import { presetJobView } from './preset-install.js'
 import { readBundlePatchRefNames } from './bundle-refs.js'
+// 盒子验证（装前静态校验）2026-10-18 搬进 install-box.js（本文件贴着 600 行硬顶）；名字与语义一字未变。
+import { parseBundlePatchRefs, verifyPackageBox } from './install-box.js'
 
 /** bundle 包判定：声明 dsh.bundle 的包一律按官方 `dsh plugin add` 行为追加为
  * profile bundle 层（其 cordis.patch.yml 的插入行在下次启动时组合进树）。
@@ -198,11 +200,19 @@ async function curlManualInstall(profileDir, packageName, registries, signal = n
  * 修法：补上第三个出口 —— 两条通道都 settle（无论成败）即刻收工；同时把定时器清掉，
  * 否则每次竞速都会留下一个 120 秒的挂起定时器，拖住进程退出。
  * 第 4 个参数是可选注入（单测用：把两条通道换成桩，才能离线断言"都失败 → 立刻收工"的时延语义；
- * capMs 也只是给单测缩短兜底时长，生产一律用默认 120 秒）。 */
-async function raceInstallChannels(profileDir, name, registries, impls = {}) {
+ * capMs 也只是给单测缩短兜底时长，生产一律用默认 120 秒）。
+ *
+ * ★ 0.5.87 改错（真机 2026-10-18）：第 1 个规格参数**同时喂给两条腿**是错的 —— pnpm 要的是
+ * `name@version`，而 curl 要的是**裸包名 + 目标版本**（`pkg@1.2.3` 对 curl 是非法包名，必然 404）。
+ * 第 5 个参数是可选扩展 `{ packageName, exactVersion }`：给了就按它跑 curl 腿（没给则与旧行为逐字相同：
+ * 用 `name` 当包名、不传版本 ⇒ 取 dist-tags.latest）。旧调用点与旧单测一个都不用改。 */
+async function raceInstallChannels(profileDir, name, registries, impls = {}, opts = {}) {
   const runPnpm = typeof impls.pnpmInstall === 'function' ? impls.pnpmInstall : pnpmInstall
   const runCurl = typeof impls.curlManualInstall === 'function' ? impls.curlManualInstall : curlManualInstall
   const capMs = Number.isFinite(impls.capMs) && impls.capMs > 0 ? impls.capMs : 120000
+  // curl 腿的包名/版本（见上方 ★）：只认非空字符串，其余一律回落旧形态
+  const curlName = typeof opts.packageName === 'string' && opts.packageName !== '' ? opts.packageName : name
+  const curlVersion = typeof opts.exactVersion === 'string' && opts.exactVersion !== '' ? opts.exactVersion : null
   const controller = new AbortController()
   const signal = controller.signal
   const pnpmTask = (async () => {
@@ -219,7 +229,7 @@ async function raceInstallChannels(profileDir, name, registries, impls = {}) {
     throw lastError ?? new Error('pnpm 通道失败')
   })()
   const curlTask = (async () => {
-    const info = await runCurl(profileDir, name, registries, signal)
+    const info = await runCurl(profileDir, curlName, registries, signal, curlVersion)
     return { channel: 'curl', info }
   })()
   const waitSuccess = (promise) => promise.then((value) => ({ value }), () => new Promise(() => {}))
@@ -236,73 +246,6 @@ async function raceInstallChannels(profileDir, name, registries, impls = {}) {
   }
 }
 
-/**
- * 盒子实验验证：解压后的包目录先通过静态校验再允许覆盖正式位置。
- * - package.json 必须可解析且 name 与安装目标一致
- * - main / exports 入口文件必须真实存在（防"装上了但加载即崩"）
- * - bundle patch（cordis.patch.yml）引用的包必须已就位（防聚合包引用缺失崩溃）
- * 失败抛错 → 调用方保留旧版本（安装不中断服务）。
- */
-function verifyPackageBox(pkgPath, profileDir, packageName, refCheckRoot = null) {
-  const note = []
-  const pkgRaw = readFileSync(join(pkgPath, 'package.json'), 'utf8')
-  const pkg = JSON.parse(pkgRaw)
-  if (pkg.name !== packageName) {
-    throw new Error(`盒子验证失败：包名不符（tarball 内为 ${pkg.name}，期望 ${packageName}），已保留旧版本`)
-  }
-  // 入口存在性：main 字段 / exports.'.'（字符串或对象 default）指向的文件必须存在
-  let entry = typeof pkg.main === 'string' ? pkg.main : null
-  if (entry === null && pkg.exports && typeof pkg.exports === 'object') {
-    const dot = pkg.exports['.'] ?? pkg.exports['./package.json'] === undefined ? pkg.exports['.'] : null
-    if (typeof dot === 'string') entry = dot
-    else if (dot && typeof dot === 'object') entry = typeof dot.default === 'string' ? dot.default : null
-  }
-  if (entry !== null) {
-    const entryPath = join(pkgPath, ...entry.split('/'))
-    if (!existsSync(entryPath)) {
-      throw new Error(`盒子验证失败：入口文件缺失（${entry}），已保留旧版本`)
-    }
-  }
-  // bundle patch 引用预检：引用的包必须已存在于目标 node_modules（防聚合包半更新崩溃）。
-  // refCheckRoot 指定检查根（宿主插件在根层 node_modules，与 profile 层不同）。
-  const checkRoot = refCheckRoot ?? join(profileDir, 'node_modules')
-  try {
-    const patchRel = pkg.dsh?.bundle?.patch
-    if (typeof patchRel === 'string') {
-      const bundlePatch = join(pkgPath, patchRel)
-      if (existsSync(bundlePatch)) {
-        const refs = parseBundlePatchRefs(readFileSync(bundlePatch, 'utf8'))
-        const missingRefs = refs.filter((r) => !existsSync(join(checkRoot, r.name)))
-        if (missingRefs.length > 0) {
-          note.push(`bundle 引用缺失：${missingRefs.map((r) => r.name).join('、')}（安装后由聚合完整性检查补齐/禁用）`)
-        }
-        if (refs.length > 0) note.push(`bundle 引用 ${refs.length} 个已就位`)
-      }
-    }
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith('盒子验证失败')) throw error
-  }
-  return { note: note.length > 0 ? note.join('；') : null }
-}
-
-/** 解析 bundle patch（cordis.patch.yml）的 insert 引用列表（id + 包名）。 */
-function parseBundlePatchRefs(text) {
-  const refs = []
-  const lines = text.split(/\r?\n/u)
-  let inInsert = false
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i]
-    if (/^- insert:\s*$/u.test(line)) { inInsert = true; continue }
-    if (/^- /u.test(line) && !/^ {4}- /u.test(line)) inInsert = false
-    if (!inInsert) continue
-    const idM = line.match(/^ {4}- id: ([A-Za-z0-9_.-]+)\s*$/u)
-    if (!idM) continue
-    const nameM = (lines[i + 1] ?? '').match(/^ {6}name: ['"]([^'"]+)['"]\s*$/u)
-    if (nameM) refs.push({ id: idM[1], name: nameM[1] })
-  }
-  return refs
-}
-
 /**
  * 捆绑依赖补装（事故教训：dsh-web-ui-all 更新后 17 个捆绑依赖缺失 → 服务加载崩溃）：
  * curl/GitHub 通道只解压主包，这里逐个补装直接依赖（pnpm → curl 依次尝试）。
@@ -513,7 +456,11 @@ function installJobView(job) {
     entryId: job.entryId ?? null,
     bundle: job.bundle ?? false,
     ai: job.ai ?? false,
-    aiNote: job.aiNote ?? null,
+    aiNote: job.aiNote ?? null, version: job.version ?? null, // ★ 0.5.82：目标版本一并投影
+    // ★ 0.5.87（真机 2026-10-18）：上面那个是**请求点名的目标版本**，不等于装上了什么 ——
+    // 本次真正落到磁盘的版本 + 版本闸的结论（`versionMiss` 非空 ⇒ 目标版本没装上，作业必为 failed）。
+    // 面板拿到这两项才分得清"更新到 0.2.1-rc.2"与"报了个目标版本号、盘上还是旧版"。
+    installedVersion: job.installedVersion ?? null, versionMiss: job.versionMiss ?? null,
     subpackages: job.subpackages ?? null,
     source: job.source ?? 'github',
     curlNote: job.curlNote ?? null,

package/lib/server/domain/link-inventory.js

@@ -19,7 +19,7 @@
 //   · 任何单个包出问题都**不抛**，如实降级成该行的一个字段（一份清单不能因为一行坏掉就整体消失）。
 //
 // 分层：L1 domain —— 不认识 cordis ctx；home / profileDir / patchPath 全部由调用方解开后传入。
-import { readFileSync } from 'node:fs'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { canonicalSourceSpec, sourceSpecTarget } from './dep-source.js'
 import { planLinkSelfSufficiency, listSelfSufficiencyRecords } from './link-self-sufficiency.js'
@@ -29,6 +29,34 @@ const readJsonSafe = (file) => {
   try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return null }
 }
 
+/** 该目录里不参与"改动时间"的条目（`node_modules` 上万文件、`.git` 每次操作都在动，两者都不代表"我在改这个插件"）。 */
+const MTIME_IGNORED_ENTRIES = new Set(['node_modules', '.git'])
+
+/**
+ * 目标目录的**改动时间**（ISO；拿不到就是 null，绝不编造）。
+ *
+ * 为什么不是只取目录本身：**Windows 上改文件内容不会更新目录的 mtime**（只有增删条目才会），
+ *   只取目录会让人看到"我明明刚改过、时间还是上周" —— 而这个字段的用途恰恰是「这是不是我正在改的那个」。
+ * 为什么不做递归：`node_modules` 动辄上万文件，一次递归会把 `/links` 拖慢一个数量级；
+ *   浅扫（目录 + 它**直接下一层**，跳过 node_modules/.git）已经覆盖 package.json / 入口文件 /
+ *   `src` 这类常见改动点的 mtime，成本是一次 readdir + N 次 stat。
+ * 拿不到（目录被删/无权限）一律 null，由面板渲染成「—」。
+ */
+function targetMtimeOf(dir) {
+  let newest = 0
+  try { newest = statSync(dir).mtimeMs } catch { return null }
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return new Date(newest).toISOString() }
+  for (const entry of entries) {
+    if (MTIME_IGNORED_ENTRIES.has(entry.name)) continue
+    try {
+      const when = statSync(join(dir, entry.name)).mtimeMs
+      if (when > newest) newest = when
+    } catch {}
+  }
+  return new Date(newest).toISOString()
+}
+
 /** 路径型来源（`link:` / `file:`）—— 只有这一族是"开发式安装"，才有目标目录可体检。 */
 const PATH_SPEC_RE = /^(?:link:|file:)/u
 
@@ -78,6 +106,10 @@ function buildLinkInventory({ profileDir, patchPath = null, entries = null, home
       spec,
       target: null,
       targetExists: false,
+      // ★ 0.5.87 加法：目标目录的最后修改时间（ISO 字符串；拿不到就是 null，由面板渲染成「—」）。
+      //   为什么需要：开发者常常同时有 plugin-src 下的好几个副本，「这是不是我正在改的那个」
+      //   只能靠时间判断。**绝不编造**：stat 失败一律 null，不写 0、不写当前时间。
+      targetMtime: null,
       version: null,
       ready: null,
       missingDeps: [],
@@ -104,8 +136,13 @@ function buildLinkInventory({ profileDir, patchPath = null, entries = null, home
       item.foreignPeers = plan.foreignPeers ?? []
       item.note = plan.note ?? plan.reason ?? null
       if (item.target !== null && item.targetExists) {
-        const pkg = readJsonSafe(join(item.target, 'package.json'))
-        item.version = typeof pkg?.version === 'string' ? pkg.version : null
+        // 版本与修改时间各自独立 try：读 package.json 坏掉不该连"文件是什么时候动的"也一并丢掉，
+        // 反之 stat 失败也不该吞掉版本号。
+        try {
+          const pkg = readJsonSafe(join(item.target, 'package.json'))
+          item.version = typeof pkg?.version === 'string' ? pkg.version : null
+        } catch {}
+        try { item.targetMtime = targetMtimeOf(item.target) } catch { item.targetMtime = null }
       }
     } catch (error) {
       item.error = error instanceof Error ? error.message : String(error)
@@ -139,4 +176,4 @@ function isLinkTargetOfProfile(profileDir, candidate) {
   return false
 }
 
-export { PATH_SPEC_RE, pathDepsOf, buildLinkInventory, isLinkTargetOfProfile }
+export { PATH_SPEC_RE, MTIME_IGNORED_ENTRIES, targetMtimeOf, pathDepsOf, buildLinkInventory, isLinkTargetOfProfile }

package/lib/server/domain/link-self-sufficiency.js

@@ -327,6 +327,72 @@ async function ensureLinkSelfSufficiency({ profileDir, packageName, spec = null,
   }
 }
 
+/**
+ * **定点**补齐：只做用户点的那一件事（0.5.87 加法，给面板的 [补齐依赖] / [造垫片] 两个按钮）。
+ *
+ * 与 `ensureLinkSelfSufficiency` 的关系：那个是**安装主路径**上的"缺什么补什么"（全做，别改它）；
+ * 本函数是"点哪个按钮做哪件事"的定点版。两条出路本来就不是一回事 ——
+ *   · `deps`  = 在链接目标里跑 pnpm install（补 dependencies）；
+ *   · `shims` = 只建框架 peer 垫片（绝不跑 pnpm、绝不联网）；
+ *   · `all`   = 两件都做（等价于主路径的顺序：先依赖、后垫片，因为 pnpm install 会修剪 node_modules）。
+ * 为什么必须分开：共用一份实现会让 [造垫片] 顺手跑一次 pnpm install —— 那是**用户没要求的写盘**；
+ * 反之 [补齐依赖] 顺手建垫片则会让"只补依赖"变成两种副作用。
+ *
+ * 判据与写盘全部复用同族函数（planLinkSelfSufficiency / installTargetDependencies /
+ * createPeerShims / writeSelfSufficiencyRecord / composeSelfSufficiencyNote），**不新写**任何判据。
+ * 任何情况都**不抛**；`ok` = 这次尝试本身没出意外，`ready` 才是"现在自足了吗"。
+ */
+async function repairLinkTarget({ profileDir, packageName, kind = 'all', spec = null, home = null, deps = {} } = {}) {
+  const homeDir = typeof home === 'string' && home !== '' ? home : dshHome()
+  const wanted = kind === 'deps' ? 'deps' : kind === 'shims' ? 'shims' : 'all'
+  const empty = { ok: true, kind: wanted, applies: false, ready: true, changed: false, installed: null, created: [], skipped: [], note: null, plan: null }
+  try {
+    const plan = planLinkSelfSufficiency({ profileDir, packageName, spec, home: homeDir })
+    if (plan.applies !== true) return { ...empty, note: plan.reason, plan }
+    if (plan.targetExists !== true) return { ...empty, applies: true, ready: false, note: plan.note, plan }
+    // 幂等 + 不谎报：该做的那件事**本来就没有对象**时，如实说"没有可补的"，一个字节都不写。
+    if (wanted === 'deps' && plan.missingDeps.length === 0) {
+      return { ...empty, applies: true, ready: plan.ready === true, note: `${packageName}：没有缺的 dependencies（依赖已齐，未改动任何东西）`, plan }
+    }
+    if (wanted === 'shims' && plan.shimmablePeers.length === 0) {
+      const why = plan.missingPeers.length === 0
+        ? '没有缺的框架 peer（未改动任何东西）'
+        : `缺的 peer 都不在框架根里、造不出垫片（${plan.unavailablePeers.join(', ')}）—— 未改动任何东西`
+      return { ...empty, applies: true, ready: plan.ready === true, note: `${packageName}：${why}`, plan }
+    }
+    if (wanted === 'all' && plan.ready === true) {
+      return { ...empty, applies: true, ready: true, note: `${packageName}：链接目标已自足（未改动任何东西）`, plan }
+    }
+    let installed = null
+    if (wanted !== 'shims' && plan.missingDeps.length > 0) installed = await installTargetDependencies({ target: plan.target, deps })
+    let created = []
+    let skipped = []
+    if (wanted !== 'deps') {
+      // 顺序与安装主路径一致：先依赖、后垫片（pnpm install 会把先建好的垫片修剪掉）
+      const afterDeps = planLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home: homeDir })
+      const shimmed = createPeerShims({ target: plan.target, peers: afterDeps.shimmablePeers, home: homeDir, deps })
+      created = shimmed.created
+      skipped = shimmed.skipped
+      if (created.length > 0) writeSelfSufficiencyRecord(homeDir, packageName, created)
+    }
+    const finalPlan = planLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home: homeDir })
+    return {
+      ok: true,
+      kind: wanted,
+      applies: true,
+      ready: finalPlan.ready === true,
+      changed: created.length > 0 || installed?.ok === true,
+      installed,
+      created,
+      skipped,
+      note: composeSelfSufficiencyNote({ packageName, installed, created, skipped, finalPlan }),
+      plan: finalPlan,
+    }
+  } catch (error) {
+    return { ...empty, ok: false, applies: true, ready: false, note: `${packageName}：补齐时出错（${String(error?.message ?? error).slice(0, 300)}）`, plan: null }
+  }
+}
+
 /** 列出全部自足性记录（报告/体检用；读不到就是空数组）。 */
 function listSelfSufficiencyRecords({ home = null } = {}) {
   const homeDir = typeof home === 'string' && home !== '' ? home : dshHome()
@@ -408,6 +474,7 @@ export {
   selfSufficiencyRecordPath,
   planLinkSelfSufficiency,
   ensureLinkSelfSufficiency,
+  repairLinkTarget,
   removeLinkSelfSufficiency,
   listSelfSufficiencyRecords,
   installTargetDependencies,