@noob-stupid/dsh-plugin-console 0.5.40 → 0.5.41

package/README.md

@@ -303,9 +303,7 @@ Environment reminder: an accelerator/proxy that rewrites hosts makes the direct
 
 #### Development installs (`link:`)
 
-**Real install is the default.** Source-type packages (tarball URL / GitHub / local directory) hand
-their **real source spec** to the package manager (`pnpm add <spec>`) — dependencies and peers are
-guaranteed by pnpm, on the same channel as the official `dsh plugin add`.
+Ordinary installs go through the package manager (`pnpm add`); that is the baseline, not a feature here.
 
 `link:` is the separate, **explicit** route: mount a **local directory / plugin you are developing**
 directly into the profile.
@@ -313,7 +311,7 @@ directly into the profile.
 - **Source edits take effect immediately**: `node_modules/<name>` in the profile is a **link** to your
   local directory, not a copy — edit the source, refresh the page. No reinstall, no repackaging.
 - **Who it is for**: plugin authors, or anyone who wants to edit a plugin's source. If you just want
-  to *use* a plugin, the default real install is simpler.
+  to *use* a plugin, an ordinary install is simpler.
 - **What it pins**: the local artifact is written into the profile manifest `dependencies`
   (`link:<absolute path>`) and gets a matching entry in `pnpm-lock.yaml` — so lockfile health checks
   and rebuilds never treat it as an orphan, and it **survives restarts and instance updates**.

package/README.zh.md

@@ -238,14 +238,13 @@ git clone https://github.com/Noob-stupid/dsh-plugin-gating-hub /tmp/dsh-plugin-c
 
 #### 开发式安装（`link:`）
 
-**默认是真装。** 来源型的包（tarball URL / GitHub / 本地目录）会把**真实来源规格**交给包管理器
-（`pnpm add <spec>`）——依赖与 peer 由 pnpm 保证，与官方 `dsh plugin add` 同一条通道。
+普通安装走包管理器（`pnpm add`）—— 那是基线，不是这里的卖点。
 
 `link:` 是**显式**的另一条路：把**本地目录 / 正在开发的插件**直接挂进 profile。
 
 - **改源码即时生效**：profile 里的 `node_modules/<包名>` 是一条指向本地目录的**链接**，不是副本 ——
   改完源码刷新页面即可，无需重装、无需重新打包。
-- **适合谁**：插件作者，或想直接改某个插件源码的人。只想"装个插件来用"的话，默认的真装更省心。
+- **适合谁**：插件作者，或想直接改某个插件源码的人。只想"装个插件来用"的话，普通安装更省心。
 - **它钉住什么**：本地那份物会被写进 profile 清单的 `dependencies`（`link:<绝对路径>`），并在
   `pnpm-lock.yaml` 里留下对应条目 —— 所以「依赖锁体检 / 重建」不会把它当多余项清掉，
   **重启与实例更新后依然在**。

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

@@ -0,0 +1,45 @@
+// L1 · domain —— install-finalize.js（安装收口结果 → 作业字段的**唯一映射**；2026-10-06 从 install-job.js 搬出）
+//
+// 为什么单独成模块：install-job.js 贴着 600 行架构棘轮（tests/test-architecture-guard.mjs），而这块
+// 本来就是自洽的一块 —— 收口（domain/persist.js）返回什么，作业（`installJobView` 下发给面板）就怎么显示，
+// 中间**不许**再各判一套。搬移只搬移未改逻辑；0.5.41 只多一条：**真装失败 ⇒ 一键真装动作优先**
+// （link 回落让插件能加载，但用户要的那一步"依赖交给 pnpm"没成，必须能一键补上；三处齐备时也要下发）。
+//
+// `deps` 是**离线测试缝**（与 marketProbes/sourceDeps 同一风格）：正控/负控必须能确定性地让 lock 那一步
+// 失败（"故意让 lock 写入失败 ⇒ 必须报未持久化而不是成功"），生产调用方不传时形状与默认值一个字都不变。
+
+import { ensurePersisted } from './persist.js'
+import { sourcePersistOptions } from './source-spec.js'
+
+/**
+ * 收口 + 落到作业字段。返回 `ensurePersisted` 的完整结果（调用方按需再读）。
+ * 只写这些字段（与旧代码逐字一致）：`job.depNote` / `job.declared` / `job.entryId` / `job.persisted` /
+ * `job.persist` / `job.persistNote` / `job.suggestedAction`。
+ */
+async function finalizeInstallPersistence({
+  job, profileDir, patchPath, packageName, mode, taken = null, entries = null, registries = [],
+  source = null, deps = {},
+}) {
+  const persist = await ensurePersisted({
+    profileDir, patchPath, packageName, mode, taken, entries, registries, deps,
+    ...sourcePersistOptions(source),
+  })
+  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
+  const persistSuggested = persist.suggested ?? null
+  if (persistSuggested !== null
+    && (persistSuggested.kind === 'real-install' || job.suggestedAction === undefined || job.suggestedAction === null)) {
+    job.suggestedAction = persistSuggested
+  }
+  return persist
+}
+
+export { finalizeInstallPersistence }

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

@@ -18,7 +18,7 @@ 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 { ensurePersisted } from './persist.js'
+import { finalizeInstallPersistence } from './install-finalize.js'
 import { readPatchState, syncNameFromNote } from './patch.js'
 import { listEntries } from './runtime.js'
 import { detectSkillRepo, runSkillInstallJob } from './skills.js'
@@ -75,6 +75,10 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
   const patchPath = join(profileDir, 'cordis.patch.yml')
   let installedName = null
   let lastError = null
+  // 0.5.41 接线：这次成功装上的**来源**（`{ spec, origin, kind }`）—— 取样通道（curl tarball /
+  // GitHub release 资产）知道真实下载地址，收口那一步据此走 `pnpm add <spec>` 真装（依赖交给 pnpm）。
+  // registry 通道不填（既有流程一字不改）；git 通道也不填（它本来就是 pnpm 装的，清单里已是 pnpm 写的规格）。
+  let source = null
   // 加法优化：包已在 node_modules 且名字匹配时，不再重复安装/触发 EPERM，直接进入启用流程
   // （2026-09-27 搬进 install-verify.js#alreadyInstalledTarget：本文件贴着 600 行架构硬顶）
   const already = alreadyInstalledTarget(profileDir, name, job)
@@ -100,6 +104,9 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
           }
           if (racedInfo.boxNote) job.curlNote += `（盒子验证：${racedInfo.boxNote}）`
           job.integrity = racedInfo.integrity ?? null // ④ 下载物摘要校验结果（加法；见 install-verify.js）
+          // 0.5.41：curl tarball 是**取样通道**（物是解压铺进去的，不是包管理器装的）——
+          // 真实来源规格（registry tarball URL）带回收口。registry 可解析时收口仍写版本号（不倒退）。
+          source = { spec: racedInfo.sourceSpec ?? null, origin: 'sampled', kind: 'registry-tarball' }
         }
       }
     } catch (raceError) {
@@ -126,6 +133,8 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
       job.curlNote = `已通过 curl 通道安装 v${info.version}${stillMissing.length > 0 ? `（依赖仍未补齐：${stillMissing.join('、')}，网络恢复后建议重新安装）` : '（捆绑依赖已补齐）'}`
       if (info.boxNote) job.curlNote += `（盒子验证：${info.boxNote}）`
       job.integrity = info.integrity ?? null // ④ 下载物摘要校验结果（加法；见 install-verify.js）
+      // 0.5.41：同上（取样通道 ⇒ 带真实 tarball URL 回去真装）
+      source = { spec: info.sourceSpec ?? null, origin: 'sampled', kind: 'registry-tarball' }
     } catch (curlError) {
       lastError = curlError
     }
@@ -144,6 +153,9 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
         const from = typeof info.sourceNote === 'string' && info.sourceNote !== '' ? `（来源：${info.sourceNote}）` : ''
         job.curlNote = `已通过 GitHub release 通道安装 v${info.version ?? '?'}${from}${stillMissing.length > 0 ? `（依赖仍未补齐：${stillMissing.join('、')}，网络恢复后建议重新安装）` : '（捆绑依赖已补齐）'}`
         if (info.boxNote) job.curlNote += `（盒子验证：${info.boxNote}）`
+        // 0.5.41 接线（**本轮的核心**）：GitHub release 资产（tarball URL）是取样通道 —— 把真实下载
+        // 地址带回给收口，由 `pnpm add <url>` 真装（依赖与 peer 交给包管理器，与官方 dsh plugin add 同效）。
+        source = { spec: info.sourceSpec ?? null, origin: 'sampled', kind: 'github-release' }
       } catch (ghError) {
         lastError = ghError
       }
@@ -186,7 +198,7 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
     installedName = retry.installedName ?? installedName
     if (retry.error != null) lastError = retry.error
   }
-  if (installedName !== null) return { installedName, lastError }
+  if (installedName !== null) return { installedName, lastError, source }
   // Windows 原子替换失败（陈旧目录 / _tmp_ 残留）是 EPERM 类错误的根因：
   // 清理后用主源重试一次（把 AI 人工修复经验自动化，减少 AI 兜底触发）
   if (/EPERM|EACCES|rename/i.test(String(lastError?.message ?? ''))) {
@@ -356,6 +368,8 @@ async function runInstallJob(job, ports, deps = {}) {
     for (const id of [...patch.inserts, ...patch.disables, ...patch.forced]) taken.add(id)
     let installedName = null
     let lastError = null
+    // 0.5.41：成功后由哪个**来源**装上的（`{ spec, origin, kind } | null`）—— 一路传到收口那一步
+    let installedSource = null
     let expanded = false
     // 可配置软件源：主→备依次尝试（默认 npmmirror → npmjs，可增删自定义/内网源）
     const registries = orderedRegistries(readSources())
@@ -401,7 +415,7 @@ async function runInstallJob(job, ports, deps = {}) {
       })
       installedName = attempt.installedName
       lastError = attempt.lastError
-      if (installedName !== null) break
+      if (installedName !== null) { installedSource = attempt.source ?? null; break }
     }
     // 预设收口（D-③ 源码装配成功 / D-⑥ 落地物里带预设）：能按预设收口就直接 return —— 见 preset-in-package.js
     // （这两条路都**没有 node_modules 插件**，写补丁行/声明依赖会让补丁行指向无入口模块 → 启动崩溃）。
@@ -430,7 +444,13 @@ async function runInstallJob(job, ports, deps = {}) {
         // 不能让用户面对"面板说失败、磁盘上却留了半个包和 _tmp_ 残留"的糊涂账。
         const leftovers = cleanupAttemptedCandidates(profileDir, candidates)
         job.leftovers = leftovers
+        // ★ 失败路径 B 的文案（0.5.41 加法）：**只有如实失败 + 原因**。取样/下载本身失败时磁盘上
+        // 什么都没有 ⇒ 没有任何东西可挂 ⇒ 面板**绝不**出现"回落成功 / 已安装 / 已启用"之类说法。
+        // 这里把最后一次的真实失败原因接在既有文案之后（不改写、不掩盖），并保留既有诊断分类（可重试动作
+        // 由面板的「重试」按钮与 diagnosis.hint 承担）。
+        const reason = typeof lastError?.message === 'string' && lastError.message !== '' ? lastError.message : null
         job.error = aiConsentFailureText(decision, leftovers, aiConsentTimeoutMs)
+          + (reason === null ? '' : `；最后一次失败原因：${reason}`)
       }
       return
     }
@@ -469,24 +489,28 @@ async function runInstallJob(job, ports, deps = {}) {
     } catch {}
     // lock 对账（2026-09-21，用户报告的自更新缺陷同源）：主包 + 本次被补装/对齐的聚合子包一起核对，
     // 一次 pnpm add 把漂移的包全写进 lock；对不上就留 lockNote，让面板如实告知（不假装成功）。
+    // ★ 0.5.41：本次装上的包**有真实来源规格**时（取样通道 = curl/release 资产），这里的对账要**让开**：
+    //   它只会按"registry 查无此包"的老判据写成 link:（还顺手复制进 plugin-src、留一句"已按 link: 形式记录"），
+    //   而紧接着的收口会用真实来源规格（`pnpm add <spec>` 真装）把它声明对 —— 两处不再打架。
     try {
       // 同一个离线测试缝（见下方 `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,
-      })
-      job.lockUpdated = lock.lockUpdated
-      job.lockVersion = lock.lockVersion
-      job.lockMethod = lock.method
-      job.lockPackages = lock.packages
-      if (lock.lockNote !== null) job.lockNote = lock.lockNote
-      // 非常规来源（link:）写回说明：必须让用户看见（缺陷②最阴的地方就是"装完完全看不出问题"）
-      if (lock.depNote !== null) job.depNote = lock.depNote
-      // 写回没生效时的**结构化**建议动作（加法；老客户端忽略该字段，向后兼容）
-      if (Array.isArray(lock.suggestedActions) && lock.suggestedActions.length > 0) job.suggestedAction = lock.suggestedActions[0]
+      const lockPackages = [installedName, ...syncedNames]
+        .filter((name) => !(installedSource !== null && typeof installedSource.spec === 'string' && installedSource.spec !== '' && name === installedName))
+        .map((name) => ({ name }))
+      if (lockPackages.length > 0) {
+        const lock = await reconcile({ profileDir, packages: lockPackages, registries })
+        job.lockUpdated = lock.lockUpdated
+        job.lockVersion = lock.lockVersion
+        job.lockMethod = lock.method
+        job.lockPackages = lock.packages
+        if (lock.lockNote !== null) job.lockNote = lock.lockNote
+        // 非常规来源（link:）写回说明：必须让用户看见（缺陷②最阴的地方就是"装完完全看不出问题"）
+        if (lock.depNote !== null) job.depNote = lock.depNote
+        // 写回没生效时的**结构化**建议动作（加法；老客户端忽略该字段，向后兼容）
+        if (Array.isArray(lock.suggestedActions) && lock.suggestedActions.length > 0) job.suggestedAction = lock.suggestedActions[0]
+      }
     } catch {}
     job.stage = 'configuring'
     // 2026-09-06 事故（i18n 更新变重复行）：@linxin666/dsh-i18n 声明了 dsh.bundle.patch，
@@ -495,11 +519,11 @@ 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（别处不许再各判一套）。
+    // 安装收口（0.5.38 判据 / 0.5.41 接线）：**一次动作内**把该插件钉住 —— ① 清单 spec
+    // ② pnpm-lock.yaml 条目 ③ 挂载行（cordis.patch.yml 的 insert 行 / dsh.profile.bundles 的 bundle 层）。
+    // 判据与写入的唯一承担者是 domain/persist.js；结果 → 作业字段的唯一映射在 domain/install-finalize.js
+    // （本轮把"本次装上的**真实来源规格**"一并带进去：取样通道 ⇒ `pnpm add <spec>` 真装；真装失败 ⇒
+    // 回落 link: 并如实报「已装上（link 方式）· 真装失败：… · 可一键真装」）。
     let mode = 'insert'
     if (await detectBundleOnly(profileDir, installedName)) {
       mode = 'bundle'
@@ -526,23 +550,10 @@ async function runInstallJob(job, ports, deps = {}) {
       mode = 'served'
       job.note = `${installedName} 已由已安装条目提供，仅更新包本身，不重复注册`
     }
-    // `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
-    }
+    await finalizeInstallPersistence({
+      job, profileDir, patchPath, packageName: installedName, mode, taken, entries: listEntries(ports), registries,
+      source: installedSource, deps: deps.persistDeps ?? {},
+    })
     job.status = 'done'
   } catch (error) {
     job.status = 'failed'

package/lib/server/domain/install.js

@@ -181,7 +181,7 @@ async function curlManualInstall(profileDir, packageName, registries, signal = n
     try {
       writeFileSync(join(target, '.dsh-installed-at'), String(Date.now()), 'utf8')
     } catch {}
-    return { version, missingDeps, boxNote: box.note, integrity }
+    return { version, missingDeps, boxNote: box.note, integrity, sourceSpec: tarball }
   } finally {
     rmSync(tmp, { recursive: true, force: true })
   }
@@ -360,10 +360,14 @@ async function githubReleaseInstall(profileDir, repo, packageName, options = {})
     const tgz = join(tmp, 'pkg.tgz')
     let version = null
     let sourceNote = null
+    // 0.5.41 接线：把**真实下载地址**带回给调用方（收口那一步据此走 `pnpm add <url>` 真装：
+    // 依赖与 peer 交给包管理器，而不是只挂一个目录 —— 见 domain/manifest.js#declareProfileDependency）。
+    let downloadUrl = null
     if (plan.ok) {
       const url = plan.asset?.browser_download_url
       if (typeof url !== 'string' || url === '') throw new Error(`GitHub 通道：asset ${plan.file} 没有下载地址（接口未返回 browser_download_url）`)
       await downloadReleaseArtifact(url, tgz, { bin })
+      downloadUrl = url
       version = plan.version ?? null
       sourceNote = `${plan.repo} 的 release ${plan.release?.tag_name ?? '（无 tag）'} 的资产 ${plan.file}`
     } else if (plan.sourceFallback !== null) {
@@ -371,7 +375,8 @@ async function githubReleaseInstall(profileDir, repo, packageName, options = {})
       const tag = plan.sourceFallback.tag
       // codeload 官方源码 tarball（已验证本机可用 200）。GitHub 黑洞期由上层通道兜底
       // （pnpm/git 通道），此处失败即报错保留旧版本。
-      await downloadReleaseArtifact(`https://codeload.github.com/${srcRepo}/tar.gz/refs/tags/${encodeURIComponent(tag)}`, tgz, { bin })
+      downloadUrl = `https://codeload.github.com/${srcRepo}/tar.gz/refs/tags/${encodeURIComponent(tag)}`
+      await downloadReleaseArtifact(downloadUrl, tgz, { bin })
       version = String(tag).replace(/^v/iu, '')
       sourceNote = `${srcRepo} 的 release ${tag} 源码 tarball（该仓库没有任何与包名匹配的资产）`
     } else {
@@ -409,7 +414,7 @@ async function githubReleaseInstall(profileDir, repo, packageName, options = {})
     try {
       writeFileSync(join(target, '.dsh-installed-at'), String(Date.now()), 'utf8')
     } catch {}
-    return { version, missingDeps, boxNote: box.note, source: 'github', sourceNote }
+    return { version, missingDeps, boxNote: box.note, source: 'github', sourceNote, sourceSpec: downloadUrl }
   } finally {
     rmSync(tmp, { recursive: true, force: true })
   }

package/lib/server/domain/manifest.js

@@ -12,8 +12,9 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { linkSpecFor, materializePackageForLink, probeFailureKind, probeRegistryPackage, sameSourceSpec, suggestedPinAction } from './dep-source.js'
+import { canonicalSourceSpec, linkSpecFor, materializePackageForLink, probeFailureKind, probeRegistryPackage, sameSourceSpec, suggestedPinAction } from './dep-source.js'
 import { ensureLinkSelfSufficiency, removeLinkSelfSufficiency } from './link-self-sufficiency.js'
+import { composeSourceInstallNote, forgetSourceSpec, isLinkSourceSpec, isRealInstallSpec, recordSourceSpec, suggestedRealInstallAction } from './source-spec.js'
 import { queuedWrite } from '../infra/fsx.js'
 import { runPnpmAdd } from '../infra/exec.js'
 import { resolvePackageJson } from '../infra/paths.js'
@@ -183,21 +184,58 @@ async function planDependencySpec({ profileDir, packageName, version, registries
  *             lockSynced: boolean, lockNote: string|null, depNote: string|null, suggested: object|null }}
  */
 async function declareProfileDependency(profileDir, packageName, version = null, options = {}) {
-  const { syncLock = true, registries = [], probe = null, home = undefined, profile = null, sourceSpec = null, installSource = null } = options
+  const { syncLock = true, registries = [], probe = null, home = undefined, profile = null, sourceSpec = null, installSource = null, sourceOrigin = null, sourceKind = null } = options
   const empty = { changed: false, version: null, spec: null, form: null, reason: null, lockSynced: false, lockNote: null, depNote: null, suggested: null, sourceInstall: null, selfSufficiency: null }
   const realSpec = typeof sourceSpec === 'string' && sourceSpec.trim() !== '' ? sourceSpec.trim() : null
+  const homeOpt = home === undefined ? {} : { home }
+  // `link:` 规格 = **显式开发式安装**（本地目录的正常路径）：**不**交给 pnpm 真装，
+  // 直接走既有 link: 路径 + 自足补齐（判据 C：本地目录不涉及下载，link: 就是它的正常形态）。
+  const linkSource = realSpec !== null && isLinkSourceSpec(realSpec)
+  const installSpec = realSpec !== null && linkSource !== true && isRealInstallSpec(realSpec) ? realSpec : null
   // ★ 来源型默认【真装】（2026-10-06 加法）：给了真实来源规格、而磁盘上还没有这个包时，
   // **先真装**（pnpm add <spec>，依赖/peer 交给包管理器）；装失败也**不拒绝** ——
   // 如实记 sourceInstall 后继续走既有判定（退回 link: 并由自足性补齐）。
   let sourceInstall = null
-  if (realSpec !== null && await installedVersionOf(profileDir, packageName) === null) {
-    sourceInstall = await installSourceDependency({ profileDir, spec: realSpec, registries, install: installSource })
+  if (installSpec !== null && await installedVersionOf(profileDir, packageName) === null) {
+    sourceInstall = await installSourceDependency({ profileDir, spec: installSpec, registries, install: installSource })
+    recordSourceSpec({ packageName, spec: installSpec, kind: sourceKind, install: sourceInstall, ...homeOpt })
   }
   const resolved = typeof version === 'string' && version !== '' ? version : await installedVersionOf(profileDir, packageName)
-  if (resolved === null) return { ...empty, sourceInstall, reason: '读不到已安装版本' }
+  if (resolved === null) {
+    // ★ 失败路径 B（取样/下载本身失败 ⇒ 物不在盘上）：只有如实失败 + 原因，**绝不**出现
+    // "已装上 / 回落成功 / 已安装"之类说法（判据：回落只对"物已在盘上"成立）。
+    const reason = sourceInstall !== null && sourceInstall.ok !== true
+      ? `真装失败：${sourceInstall.error}；磁盘上没有任何副本 —— 无可挂载（清单未改动）`
+      : '读不到已安装版本'
+    return { ...empty, sourceInstall, reason, depNote: composeSourceInstallNote({ packageName, install: sourceInstall }) ?? reason }
+  }
   // 探测/物化放在写锁**之外**（网络探测最长 8 秒，占着清单写锁会堵住其它写）
-  const plan = await planDependencySpec({ profileDir, packageName, version: resolved, registries, probe, home, profile, sourceSpec: realSpec })
-  if (plan.spec === null) return { ...empty, version: resolved, form: plan.form, reason: plan.note, depNote: plan.note, suggested: plan.suggestion }
+  let plan = linkSource
+    ? {
+        form: 'link',
+        spec: canonicalSourceSpec(realSpec),
+        note: `${packageName}：按**显式开发式安装**记录（${realSpec}）—— 不经 npm registry 解析，依赖与框架 peer 由 link 自足性补齐`,
+        suggestion: null,
+      }
+    : await planDependencySpec({ profileDir, packageName, version: resolved, registries, probe, home, profile, sourceSpec: installSpec })
+  // ★ 本轮接线（2026-10-06）：盘上那份是**取样通道**铺的（curl / GitHub release 资产 / 源码装配），
+  // 而不是包管理器装的 —— 而 registry 又查无此包（plan 判成来源型）⇒ **补一次真装**，
+  // 把依赖交给 pnpm（与官方 dsh plugin add 同一条通道）。
+  // 真装失败 ⇒ 回落既有 `link:` 路径：**回落只对"物已在盘上"成立**，这里正是（resolved 非空）。
+  if (installSpec !== null && sourceInstall === null && sourceOrigin === 'sampled' && plan.form === 'source') {
+    sourceInstall = await installSourceDependency({ profileDir, spec: installSpec, registries, install: installSource })
+    recordSourceSpec({ packageName, spec: installSpec, kind: sourceKind, install: sourceInstall, ...homeOpt })
+    if (sourceInstall.ok !== true) {
+      plan = await planDependencySpec({ profileDir, packageName, version: resolved, registries, probe, home, profile, sourceSpec: null })
+    }
+  }
+  const installNote = composeSourceInstallNote({ packageName, install: sourceInstall, plan })
+  if (plan.spec === null) {
+    return {
+      ...empty, version: resolved, form: plan.form, reason: plan.note, sourceInstall,
+      depNote: joinNotes(installNote, plan.note), suggested: plan.suggestion,
+    }
+  }
   const result = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
     const deps = { ...(manifest.dependencies ?? {}) }
@@ -215,17 +253,33 @@ async function declareProfileDependency(profileDir, packageName, version = null,
   const selfSufficiency = plan.form === 'link'
     ? await ensureLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home })
     : null
-  const out = { ...empty, changed: result.changed, version: resolved, spec: plan.spec, form: plan.form, depNote: plan.note, suggested: plan.suggestion, sourceInstall, selfSufficiency }
+  // 真装失败 ⇒ 结构化「一键真装」动作优先（此时"钉住/自足"类动作都不是用户想要的那一步）；
+  // 它的 payload 里**没有** spec —— 规格由服务端从记录里读（见 domain/source-spec.js）。
+  const installAction = sourceInstall !== null && sourceInstall.ok !== true
+    ? suggestedRealInstallAction({ packageName, spec: sourceInstall.spec, profile, profileDir, reason: sourceInstall.error })
+    : null
+  const out = {
+    ...empty, changed: result.changed, version: resolved, spec: plan.spec, form: plan.form,
+    depNote: joinNotes(installNote, plan.note),
+    // 优先级：真装失败的「一键真装」> 自足性动作 > 计划里的建议（与 syncLock:false 的旧行为逐字一致）
+    suggested: installAction ?? (selfSufficiency === null ? null : selfSufficiency.action) ?? plan.suggestion,
+    sourceInstall, selfSufficiency,
+  }
   if (syncLock !== true) return out
   // **写完清单必须把 lock 拉齐**（2026-09-24 CI 实测）：只写清单不写 lock → 清单/lock 不一致 →
   // 之后任何 pnpm 操作都会硬失败（ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS）。
   // 放在写队列**之外**执行（对账本身会跑 pnpm，不该占着清单写锁）；失败只记 note，不让安装失败。
-  const synced = await syncLockFor(profileDir, [packageName], { registries, home, profile })
+  const synced = await syncLockFor(profileDir, [packageName], {
+    registries, home, profile,
+    // 0.5.41：刚真装出来的 **tarball URL** 是来源事实 ⇒ 告诉对账"别把它规整回 link:"
+    // （否则收口最后一步会把自己刚写下的真实来源规格改掉，用户看到的是"真装了但清单里是 link:"）。
+    keepUrlSpecs: plan.form === 'source' && /^https?:/u.test(String(plan.spec ?? '')) ? [packageName] : [],
+  })
   return {
     ...out,
     ...synced,
-    depNote: joinNotes(plan.note, selfSufficiency === null ? null : selfSufficiency.note, synced.depNote),
-    suggested: synced.suggested ?? (selfSufficiency === null ? null : selfSufficiency.action) ?? plan.suggestion,
+    depNote: joinNotes(installNote, plan.note, selfSufficiency === null ? null : selfSufficiency.note, synced.depNote),
+    suggested: installAction ?? synced.suggested ?? (selfSufficiency === null ? null : selfSufficiency.action) ?? plan.suggestion,
   }
 }
 
@@ -258,6 +312,7 @@ async function syncLockFor(profileDir, names, options = {}) {
       profileDir,
       packages: names.map((name) => ({ name })),
       registries: Array.isArray(options.registries) ? options.registries : [],
+      ...(Array.isArray(options.keepUrlSpecs) && options.keepUrlSpecs.length > 0 ? { keepUrlSpecs: options.keepUrlSpecs } : {}),
       ...(options.home === undefined ? {} : { home: options.home }),
     })
     return {
@@ -339,7 +394,9 @@ async function undeclareProfileDependency(profileDir, packageName, options = {})
   // 2026-10-06 加法：link 自足性造的垫片是我们加的，卸载时只清**我们造的**那些
   // （记录里逐个核对"现在仍是指向当初目标的链接"，被人改过的一律不碰）。清不掉只如实报。
   const shims = removeLinkSelfSufficiency({ packageName, home: options.home ?? null })
-  return { ...result, shimsRemoved: shims.removed, shimsKept: shims.kept, selfSufficiencyNote: shims.note }
+  // 2026-10-06 接线：来源规格记录同样"卸载即撤销" —— 否则下一次安装会拿旧规格去真装（来源早已变了）。
+  const sourceRecord = forgetSourceSpec({ packageName, home: options.home ?? null })
+  return { ...result, shimsRemoved: shims.removed, shimsKept: shims.kept, selfSufficiencyNote: shims.note, sourceSpecForgotten: sourceRecord.removed || sourceRecord.emptied }
 }
 
 /**

package/lib/server/domain/persist.js

@@ -290,10 +290,16 @@ function suggestedPersistAction({ packageName, profile = null, profileDir = null
  *   · ② 缺/形态不一致 → `reconcileLockfile`（既有对账通道，argv/写回形态同安装路径）；
  *   · ③ 缺 → `mode==='bundle'` 时补 `dsh.profile.bundles`；否则追加一条 insert 行（entry id 由
  *     `deriveEntryId` 按既有规则产出）。`mode==='served'` 时**绝不写行**（已有行提供它，再写就是重复装配）。
+ *
+ * 2026-10-06 接线（0.5.41）：`sourceSpec` / `sourceOrigin` 由**安装通道**一路传进来 ——
+ * 取样通道（curl / GitHub release 资产 / 源码装配）装的包，真实来源规格在这里被交给
+ * `declareProfileDependency({sourceSpec, sourceOrigin:'sampled'})` ⇒ `pnpm add <spec>` 真装，
+ * 依赖与 peer 由包管理器保证；真装失败则回落既有 `link:` 路径并**如实**报
+ * 「已装上（link 方式）· 真装失败：… · 可一键真装」（回落只对"物已在盘上"成立）。
  * 返回 `{ 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 = {} } = {}) {
+async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'insert', taken = null, entries = null, registries = [], deps = {}, sourceSpec = null, sourceOrigin = null, sourceKind = null } = {}) {
   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
@@ -322,7 +328,17 @@ async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'ins
         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 })
+        // 来源型（安装通道知道真实来源规格）：把规格一并交给写入层 —— 由它决定"真装 / link:"
+        // （0.5.41 接线；没传规格时形状与默认值一个字都不变）。
+        // `deps.installSource` / `deps.syncLock` 是**离线测试缝**（与 deps.pin / deps.declare 同一风格）：
+        // 正控/负控要能确定性地让"包管理器那一步"成功或失败、并让 lock 那一步不跑真 pnpm，
+        // 生产调用方不传时用的就是真实 `pnpm add` 与真实 lock 对账。
+        declared = await declare(profileDir, packageName, disk.version, {
+          registries,
+          ...(typeof sourceSpec === 'string' && sourceSpec !== '' ? { sourceSpec, sourceOrigin, sourceKind } : {}),
+          ...(typeof deps.installSource === 'function' ? { installSource: deps.installSource } : {}),
+          ...(deps.syncLock === false ? { syncLock: false } : {}),
+        })
         if (declared.changed !== true) notes.push(`清单里已有这个包（实际是 ${declared.spec ?? disk.version}）`)
         if (declared.depNote !== null && declared.depNote !== undefined) notes.push(declared.depNote)
       } else {
@@ -336,7 +352,15 @@ async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'ins
   const mid = persistReport({ profileDir, patchPath, packageName, entries })
   if (mid.parts.lock.ok !== true) {
     try {
-      lock = await reconcile({ profileDir, packages: [{ name: packageName }], registries })
+      // 0.5.41：本次带来的是 **tarball URL** 来源规格（刚真装过）⇒ 不许对账把它规整回 link:
+      // （判据与 manifest.js#declareProfileDependency 的同一套：只有这一段来源型接线会点名 keepUrlSpecs）。
+      const keepUrlSpecs = (typeof sourceSpec === 'string' && /^https?:/u.test(sourceSpec.trim()))
+        || (declared !== null && declared !== undefined && declared.form === 'source' && /^https?:/u.test(String(declared.spec ?? '')))
+        ? [packageName] : []
+      lock = await reconcile({
+        profileDir, packages: [{ name: packageName }], registries,
+        ...(keepUrlSpecs.length > 0 ? { keepUrlSpecs } : {}),
+      })
       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) {
@@ -377,7 +401,15 @@ async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'ins
     after.note = after.persisted ? null : persistNote(after)
     lockVerdict = { verified: lock.lockVerified, reason }
   }
-  const suggested = after.persisted ? null : suggestedPersistAction({ packageName, profileDir, missing: after.missing, reason: after.note })
+  // 0.5.41 接线：真装失败时写入层会下发「一键真装」动作 —— 它优先于"钉住"（此时用户要的是真装那一步）；
+  // 只有三处都没就位时仍按老规矩给「一键钉住」（收口更根本）。老客户端忽略该字段，向后兼容。
+  const declaredAction = declared !== null && declared !== undefined && declared.suggested !== null && declared.suggested !== undefined
+    ? declared.suggested
+    : null
+  const suggested = after.persisted
+    ? declaredAction
+    : suggestedPersistAction({ packageName, profileDir, missing: after.missing, reason: after.note })
+  const sourceInstall = declared !== null && declared !== undefined && declared.sourceInstall !== undefined ? declared.sourceInstall : null
   return {
     persisted: after.persisted,
     before,
@@ -392,6 +424,7 @@ async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'ins
     notes,
     suggested,
     note: after.note,
+    sourceInstall,
   }
 }
 

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

@@ -37,18 +37,21 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { applyAllowBuilds, pendingApprovedBuilds, readWorkspaceApprovals } from './allow-builds.js'
-import { NPM_NAME_RE, suggestedAllowBuildsAction } from './dep-source.js'
+import { NPM_NAME_RE, sameSourceSpec, 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 { isRealInstallSpec, readSourceSpec, recordSourceSpec } from './source-spec.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', 'persist-plugin']
+/** 动作白名单（客户端只能给这些 kind；执行分支与 argv 全在服务端）。
+ *  0.5.41 登记（加法，不改既有动作）：`real-install` —— 来源型安装的"出路"：真装失败（回落 link:）后
+ *  一键把**记录里的真实来源规格**再交给包管理器（`pnpm add <spec>`）。规格只从服务端记录读。 */
+const ACTION_KINDS = ['pin-dependency', 'reconcile-lock', 'allow-builds', 'overwrite-preset', 'persist-plugin', 'real-install']
 /** 一旦出现这些键就整条拒绝：本接口不存在"传命令"的位置。 */
 const COMMAND_KEYS = ['command', 'cmd', 'argv', 'args', 'exec', 'execute', 'shell', 'script', 'run', 'spawn', 'bin', 'shellCommand']
 const OUTPUT_LIMIT = 4000
@@ -73,7 +76,7 @@ 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' || action === 'persist-plugin') {
+  if (action === 'pin-dependency' || action === 'persist-plugin' || action === 'real-install') {
     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 包名' }
   }
@@ -307,6 +310,66 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
       lock: { entry: null, synced: view?.action === 'repaired' || view?.action === 'noop' },
     }
   }
+  if (parsed.action === 'real-install') {
+    // ★ 0.5.41 加法（来源型"一键真装"）：把**服务端记录里的真实来源规格**再交给包管理器装一次
+    //   （`pnpm add <spec>`）—— 依赖与 peer 由 pnpm 保证，与官方 `dsh plugin add` 同一条通道。
+    //   为什么规格必须从记录读：动作接口只接受 `{ action, packageName, profile }`，客户端**没有位置**
+    //   传 spec 字符串（否则等于开了"任意来源/任意命令"的口子）；记录由安装时写入（domain/source-spec.js）。
+    if (!isProfilePackage(profileDir, parsed.packageName)) {
+      return { ...base, ok: false, status: 400, error: `${parsed.packageName} 不在本 profile 的清单（dependencies / dsh.profile.bundles）里，拒绝改动（先安装）` }
+    }
+    const record = readSourceSpec({ packageName: parsed.packageName, home: deps.home ?? null })
+    if (record === null || isRealInstallSpec(record.spec) !== true) {
+      return {
+        ...base, ok: false, status: 400,
+        error: `没有 ${parsed.packageName} 的来源规格记录（或记录的规格不能真装）：本动作只重放**这个实例装过的来源型包**的真实规格（tarball URL / git 族 / file:），registry 版本号与 link: 不在其列`,
+      }
+    }
+    const before = await specOf(profileDir, parsed.packageName)
+    const run = await runAddWithReleaseAgeRetry({ profileDir, spec: record.spec, registry, runAdd, timeoutMs: ACTION_ADD_TIMEOUT_MS })
+    const after = await specOf(profileDir, parsed.packageName)
+    const entry = lockVersion(profileDir, parsed.packageName)
+    const failure = run.ok === true ? null : classifyInstallFailure(`${run.stderr}\n${String(run.error?.message ?? '')}`)
+    const ignored = failure?.kind === 'ignored-builds'
+    const ignoredBuilds = ignored === true ? ignoredBuildsFrom(run.stderr) : []
+    // 真装结果记回记录（面板/报告据此看到"最近一次真装成没成"）——写失败只影响记录，绝不影响本次结论。
+    recordSourceSpec({
+      packageName: parsed.packageName,
+      spec: record.spec,
+      kind: record.kind ?? null,
+      install: { ok: run.ok === true, error: run.ok === true ? null : String(run.error?.message ?? run.stderr ?? '').slice(0, 600) },
+      home: deps.home ?? null,
+    })
+    // 与 pin 分支同一口径（A-② 语义）：清单里的 spec 已经是那条真实来源规格 ⇒ 目标状态已达成；
+    // ERR_PNPM_IGNORED_BUILDS 这类报错一个脚本都不执行、也不影响加载，不算"没装上"。
+    const reached = sameSourceSpec(profileDir, after, record.spec)
+    const ok = run.ok === true || (ignored === true && reached)
+    const notes = []
+    if (run.relaxedReleaseAge) notes.push('本机 pnpm 的 24h 供应链闸（minimumReleaseAge）拦下了这次真装，已**仅对这一条命令**追加 --config.minimumReleaseAge=0 重试一次（有安全代价，未写进任何配置文件）。')
+    if (ignored === true) notes.push(IGNORED_BUILDS_REACHED_NOTE)
+    if (run.ok !== true && reached) notes.push(`pnpm 那一步没跑完（exitCode=${run.exitCode}），但清单里的 spec 已经是这条真实来源规格（${after}）—— 目标状态已达成，原始输出见 stderr。`)
+    return {
+      ...base,
+      kind: ignored === true ? 'ignored-builds' : 'real-install',
+      ignoredBuilds,
+      nextAction: ignored === true ? suggestedAllowBuildsAction({ packages: ignoredBuilds, profile: parsed.profile, reason: 'pnpm 因构建脚本未获批准而报错' }) : null,
+      ok,
+      partial: ok !== true && reached,
+      exitCode: run.exitCode,
+      command: `pnpm ${pnpmAddArgs(record.spec, registry).join(' ')}`,
+      stdout: run.stdout,
+      stderr: run.stderr,
+      relaxedReleaseAge: run.relaxedReleaseAge,
+      spec: record.spec,
+      manifest: { before, after, changed: before !== after, planned: record.spec, pinned: reached },
+      lock: { entry: entry ?? null, synced: typeof entry === 'string' && entry !== '' },
+      notes,
+      failureKind: failure?.kind ?? null,
+      reason: ok === true
+        ? `${parsed.packageName} 已按真实来源规格真装：${record.spec}（依赖与 peer 由包管理器保证）`
+        : `真装没跑成（exitCode=${run.exitCode}）：${record.spec} —— 清单当前是 ${after ?? '（无该条目）'}，原始输出见 stderr`,
+    }
+  }
   // pin-dependency
   if (!isProfilePackage(profileDir, parsed.packageName)) {
     return { ...base, ok: false, status: 400, error: `${parsed.packageName} 不在本 profile 的清单（dependencies / dsh.profile.bundles）里，拒绝改动` }

package/lib/server/domain/selfupdate.js

@@ -331,7 +331,7 @@ async function settleImporterEntries({ profileDir, items = [], deps = {}, regist
  *       查无此包（404）→ 物化到 `<DSH_HOME>/plugin-src/<包名>` 并写 `link:<绝对路径>`，同时回 depNote；
  *       连物化都做不到 → **跳过对齐且不碰 package.json**，只记 note。
  */
-async function reconcileLockfile({ profileDir, packageName = null, packages = null, registries = [], pnpmAdd = pnpmInstall, execOpts = {}, fetchJson = fetchJsonUrl, home = null, deps = {} } = {}) {
+async function reconcileLockfile({ profileDir, packageName = null, packages = null, registries = [], pnpmAdd = pnpmInstall, execOpts = {}, fetchJson = fetchJsonUrl, home = null, deps = {}, keepUrlSpecs = [] } = {}) {
   const targets = Array.isArray(packages)
     ? packages.filter((p) => p && typeof p.name === 'string' && p.name !== '')
     : (packageName === null ? [] : [{ name: packageName, version: null }])
@@ -375,7 +375,14 @@ async function reconcileLockfile({ profileDir, packageName = null, packages = nu
     }
     return r.installed === r.lock || sourcePinned(r.lock)
   }
-  const driftedOf = (rows) => rows.filter((r) => r.installed === null || !aligned(r) || misrecorded(r) || urlSpec(r))
+  // 0.5.41 加法：**刚按真实来源规格真装过**的包（tarball URL）**不算漂移** —— 那个 URL 是用户可见的
+  // 来源事实，lock 里的解析记录也正是 pnpm 自己在那次 `pnpm add <url>` 里写下的（带 integrity）。
+  // 这条口子只对调用方**点名**的包生效（调用方 = 刚刚真装它的那条路，见 manifest.js / persist.js），
+  // 其余任何 URL 形态照旧走下面的"URL → link:"规整（那条保护是给"pnpm 静默改写/来源不确定"的历史状态）。
+  const keepUrls = new Set((Array.isArray(keepUrlSpecs) ? keepUrlSpecs : []).filter((n) => typeof n === 'string' && n !== ''))
+  const driftedOf = (rows) => rows
+    .filter((r) => !(keepUrls.has(r.name) && typeof r.spec === 'string' && /^https?:/u.test(r.spec.trim())))
+    .filter((r) => r.installed === null || !aligned(r) || misrecorded(r) || urlSpec(r))
 
   const depNotes = []
   // 物化 + link: 计划（registry 查无此包时唯一安全的写回形式）。

package/lib/server/domain/source-spec.js

@@ -0,0 +1,212 @@
+// L1 · domain —— source-spec.js（**来源型安装的"真实来源规格"记录** + 一键真装动作；2026-10-06 接线）
+//
+// 为什么需要它（本轮的接线缺口）：0.5.40 已经把能力做进了写入层 —— `declareProfileDependency({sourceSpec})`
+// 会把**真实来源规格**写回清单，并由 `installSourceDependency` 走 `pnpm add <spec>` 真装（依赖与 peer
+// 交给包管理器，与官方 `dsh plugin add` 同一条通道）。但**生产路径上没有一个调用方传过 sourceSpec**：
+// curl / GitHub release 这些"取样通道"把包铺进 `node_modules` 之后，收口那一步只知道"磁盘上有个真实目录"，
+// 于是按老的 registry 404 判据写成 `link:`（复制到 plugin-src + 链接）——依赖还是没人管。
+// 本轮把"这个包是从哪个来源装来的"从通道一路传到收口，并在两处留下可核对的东西：
+//   ① **记录**（本模块）：`<DSH_HOME>/plugin-console/source-specs/<包名>.json` —— 记下真实来源规格与
+//      最近一次真装结果。用途是让「一键真装」动作能**服务端自己**取到规格：动作接口只接受
+//      `{ action, packageName, profile }`，客户端**没有位置**传 spec 字符串（否则等于开了任意命令的口子）。
+//   ② **文案与动作**（本模块是唯一承担者）：真装成功 / 真装失败的两种如实说法 + 结构化「一键真装」动作。
+//
+// 失败路径的语义（写死在这里，别处不许再解释一遍 —— 用户点名要求）：
+//   A) 取样/下载**成功**、包管理器安装**失败** ⇒ 磁盘上确实有那份物化副本 ⇒ 允许回落既有 `link:`
+//      路径（插件至少能加载）⇒ 文案必须含「已装上（link 方式）」+「真装失败：<原因>」+「可一键真装」。
+//   B) 取样/下载**本身失败** ⇒ 磁盘上什么都没有 ⇒ **没有任何东西可挂** ⇒ 只能如实失败
+//      （原因 + 重试）；**严禁**出现"回落成功 / 已安装 / 已启用"之类说法。
+//   C) 本地目录：不涉及下载 ⇒ `link:` 是它的正常路径（+ 既有自足补齐）。
+//   判据一句话：**回落只对"物已在盘上"成立；物不在盘上就只有如实失败**。
+//
+// 分层：L1 domain —— 不认识 cordis ctx；home 可注入（隔离测试用私有 DSH_HOME），一切失败都不抛。
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { dshHome } from '../infra/paths.js'
+import { canonicalSourceSpec, profileNameOf } from './dep-source.js'
+
+/** 记录目录（与 link-self-sufficiency 记录同族，都在 `<DSH_HOME>/plugin-console/` 下）。 */
+const SOURCE_SPEC_DIR = 'source-specs'
+
+/** `link:` = 显式开发式安装（本地目录的正常路径），**不**交给 pnpm 真装（见 C）。 */
+const LINK_SPEC_RE = /^link:/u
+
+/** 可以交给 `pnpm add <spec>` 的**来源型**规格（tarball URL / git 族 / file: / 别名协议）。
+ *  刻意**不含**版本号、版本范围、dist-tag：那些是 registry 路径，写回形态由既有判据决定（不倒退）。 */
+const REAL_INSTALLABLE_RE = /^(?:https?:|git\+|git:|github:|gitlab:|bitbucket:|file:|workspace:|portal:|npm:|jsr:)/u
+
+/** 记录目录 / 记录文件（一个包一份，便于一键真装与卸载清理精确定位）。 */
+function sourceSpecRecordDir(home = null) {
+  return join(typeof home === 'string' && home !== '' ? home : dshHome(), 'plugin-console', SOURCE_SPEC_DIR)
+}
+function recordFileNameOf(packageName) {
+  return `${String(packageName).replace(/[^A-Za-z0-9._-]+/gu, '_')}.json`
+}
+function sourceSpecRecordPath(home, packageName) {
+  return join(sourceSpecRecordDir(home), recordFileNameOf(packageName))
+}
+
+/** 读 JSON（读不到/坏文件都返回 null，绝不抛）。 */
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** 这个规格该不该交给包管理器**真装**（`link:` 不算：那是显式开发式安装）。 */
+function isRealInstallSpec(spec) {
+  const canonical = canonicalSourceSpec(spec)
+  if (canonical === null || canonical === '') return false
+  if (LINK_SPEC_RE.test(canonical)) return false
+  return REAL_INSTALLABLE_RE.test(canonical)
+}
+
+/** 这个规格是不是 `link:`（显式开发式安装 / 本地目录的正常路径）。 */
+function isLinkSourceSpec(spec) {
+  const canonical = canonicalSourceSpec(spec)
+  return canonical !== null && LINK_SPEC_RE.test(canonical)
+}
+
+/**
+ * 安装通道带回的「来源」（`{ spec, origin, kind }`）→ `ensurePersisted` 的入参。
+ * 空/没有规格 ⇒ **空对象**（调用方的形状与默认值与接线前逐字一致）；有规格 ⇒ 三个字段一次给全，
+ * 收口才好判"这份物是取样通道铺的（sampled）还是包管理器装的（pnpm）"。
+ */
+function sourcePersistOptions(source) {
+  if (source === null || source === undefined || typeof source !== 'object') return {}
+  const spec = typeof source.spec === 'string' && source.spec !== '' ? source.spec : null
+  if (spec === null) return {}
+  return { sourceSpec: spec, sourceOrigin: source.origin ?? null, sourceKind: source.kind ?? null }
+}
+
+/** 读某包的来源规格记录（没有/坏文件返回 null）。 */
+function readSourceSpec({ packageName, home = null } = {}) {
+  if (typeof packageName !== 'string' || packageName === '') return null
+  const record = readJsonSafe(sourceSpecRecordPath(home, packageName))
+  if (record === null || typeof record !== 'object') return null
+  if (typeof record.spec !== 'string' || record.spec === '') return null
+  return record
+}
+
+/** 列出全部记录（体检/报告用）。 */
+function listSourceSpecs({ home = null } = {}) {
+  const dir = sourceSpecRecordDir(home)
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => ({ file: join(dir, f), record: readJsonSafe(join(dir, f)) }))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 记下某包的真实来源规格（安装时写；**幂等**：规格与最近一次真装结论都没变 ⇒ 一个字节都不写）。
+ * `install` 传 `installSourceDependency` 的返回值（`{ ok, spec, error }`）时，最近一次结论一并记下。
+ * 返回 `{ ok, changed, file, record }`；任何失败都只如实返回，**绝不抛**（安装主路径不许被它带崩）。
+ */
+function recordSourceSpec({ packageName, spec, kind = null, install = null, home = null } = {}) {
+  const empty = { ok: false, changed: false, file: null, record: null }
+  if (typeof packageName !== 'string' || packageName === '') return empty
+  const canonical = canonicalSourceSpec(spec)
+  if (canonical === null || canonical === '') return empty
+  const file = sourceSpecRecordPath(home, packageName)
+  const installSummary = install === null || install === undefined
+    ? null
+    : { ok: install.ok === true, error: typeof install.error === 'string' && install.error !== '' ? install.error.slice(0, 600) : null }
+  try {
+    const previous = readJsonSafe(file)
+    const sameSpec = typeof previous?.spec === 'string' && canonicalSourceSpec(previous.spec) === canonical
+    const sameInstall = installSummary === null
+      ? true
+      : previous?.lastInstall?.ok === installSummary.ok && (previous?.lastInstall?.error ?? null) === installSummary.error
+    if (sameSpec && sameInstall) return { ok: true, changed: false, file, record: previous }
+    const record = {
+      packageName,
+      spec: canonical,
+      kind: typeof kind === 'string' && kind !== '' ? kind : (previous?.kind ?? null),
+      recordedAt: new Date().toISOString(),
+      ...(installSummary === null ? {} : { lastInstall: { ...installSummary, at: new Date().toISOString() } }),
+    }
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, 'utf8')
+    return { ok: true, changed: true, file, record }
+  } catch (error) {
+    return { ...empty, file, reason: String(error?.message ?? error).slice(0, 300) }
+  }
+}
+
+/**
+ * 忘掉某包的来源规格记录（**卸载即撤销**，与 `undeclareProfileDependency` 同一时机调用）。
+ * 删不掉时**退而求其次清空内容**（Windows 上 `<DSH_HOME>/plugin-console/` 下删除会静默落空，
+ * 与 junction / `*_tmp_*` 同族）—— 绝不留下指向已卸载包的陈旧规格。
+ */
+function forgetSourceSpec({ packageName, home = null } = {}) {
+  if (typeof packageName !== 'string' || packageName === '') return { removed: false, emptied: false, file: null }
+  const file = sourceSpecRecordPath(home, packageName)
+  if (!existsSync(file)) return { removed: false, emptied: false, file }
+  try { rmSync(file, { force: true }) } catch {}
+  if (!existsSync(file)) return { removed: true, emptied: false, file }
+  let emptied = false
+  try {
+    writeFileSync(file, `${JSON.stringify({ packageName, forgotten: true, spec: null, note: '记录已作废；文件本身删除未生效，已清空以免留下陈旧规格' }, null, 2)}\n`, 'utf8')
+    emptied = readJsonSafe(file)?.spec === null
+  } catch { emptied = false }
+  return { removed: false, emptied, file }
+}
+
+/**
+ * 结构化「一键真装」动作（与 `suggestedPinAction` 同一套安全语义）：
+ * `command` 只供展示/复制；执行侧只认 `payload.action`，**规格由服务端从记录里读**，
+ * payload 里没有 spec / 命令字符串的位置。
+ */
+function suggestedRealInstallAction({ packageName, spec = null, profile = null, profileDir = null, reason = null } = {}) {
+  const name = profile ?? profileNameOf(profileDir)
+  const shown = canonicalSourceSpec(spec) ?? '<来源规格>'
+  return {
+    kind: 'real-install',
+    label: '一键真装（交给包管理器装依赖）',
+    command: `pnpm add ${shown} --registry https://registry.npmmirror.com`,
+    payload: { action: 'real-install', packageName, profile: name },
+    reason,
+  }
+}
+
+/**
+ * 真装结果 → 如实说法（**唯一承担者**）。三种形态各自把该说的话说完，绝不覆盖、绝不美化：
+ *   · 成功：说清"按真实来源规格真装、依赖与 peer 由包管理器保证"；
+ *   · 失败 + 已回落 `link:`：说清「已装上（link 方式）· 真装失败：<原因> · 可一键真装」；
+ *   · 失败 + 盘上什么都没有：说清"无可挂载（未改动清单）"——**不出现**任何"已装上"字样。
+ */
+function composeSourceInstallNote({ packageName, install, plan = null } = {}) {
+  if (install === null || install === undefined || typeof install.ok !== 'boolean') return null
+  const spec = typeof install.spec === 'string' && install.spec !== '' ? install.spec : null
+  if (install.ok === true) {
+    return `${packageName}：已按真实来源规格真装（pnpm add ${spec ?? '（规格缺失）'}）—— 依赖与 peer 由包管理器保证（与官方 dsh plugin add 同一条通道）`
+  }
+  const error = typeof install.error === 'string' && install.error !== '' ? install.error : '（原因未记录）'
+  if (plan?.form === 'link' && typeof plan.spec === 'string' && plan.spec !== '') {
+    return `${packageName}：已装上（link 方式）· 真装失败：${error} · 已按 link: 记录（${plan.spec}），缺失依赖由 link 自足性尽力补齐 · 可一键真装`
+  }
+  if (plan !== null && typeof plan?.spec === 'string' && plan.spec !== '') {
+    return `${packageName}：真装失败：${error}；已按现有形态记录（${plan.spec}）· 可一键真装`
+  }
+  return `${packageName}：真装失败：${error}；磁盘上没有任何副本 —— 无可挂载（未改动清单）`
+}
+
+export {
+  SOURCE_SPEC_DIR,
+  REAL_INSTALLABLE_RE,
+  sourceSpecRecordDir,
+  sourceSpecRecordPath,
+  isRealInstallSpec,
+  isLinkSourceSpec,
+  sourcePersistOptions,
+  readSourceSpec,
+  listSourceSpecs,
+  recordSourceSpec,
+  forgetSourceSpec,
+  suggestedRealInstallAction,
+  composeSourceInstallNote,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.40",
+  "version": "0.5.41",
   "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",