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

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

@@ -0,0 +1,417 @@
+// L1 · domain —— link-self-sufficiency.js（`link:` 依赖的**自足性**）
+//
+// 为什么需要它（2026-10-05/06 真机现场，ds-h-opencode-go 实测）：
+//   `link:` 只把**一个目录**挂进 profile —— pnpm 建完那条链接就结束了。可一个插件要能被
+//   `import` 起来，还差两样东西，而这两样**没有任何人负责**：
+//     ① 目标目录自己的 `dependencies`（插件通常不发 node_modules，作者的开发目录里才有）；
+//     ② 它声明过的**框架 peer**（`@deepseek-ai/*`）——目标目录在 profile 树**之外**时，
+//        Node 的解析链走不到 profile 的 node_modules，`import` 当场 `ERR_MODULE_NOT_FOUND`。
+//   真机症状就是"面板报安装成功、插件却一直是 [no-fiber]"：包在、链接在、就是加载不起来。
+//   现场实测（插件目录 = D:\…\plugin-src\dsh-opencode-go）：
+//     修前 `import()` 失败于 `Cannot find package 'opencode-go-pi-ai'`
+//     （而 `opencode-go-pi-ai` 的实体**早就装好**在 `.pnpm` 里，只是顶层链接被 pnpm 挪进了
+//      `node_modules/.ignored` —— 所以"补齐"必须包含"把已有实体接回可达位置"）。
+//
+// 三条硬规矩（本模块是它们的唯一承担者，别在别处再写一份判据）：
+//   ① **只补缺的**：目标存在/可解析 ⇒ 一个字节都不写（幂等；自足插件是 no-op）。
+//   ② **绝不覆盖**：目标位置上**已经有任何东西**（含悬空链接）就跳过并如实记 skipped。
+//   ③ **绝不因此拒绝安装**：任何失败都返回 `{ ready:false, note, action }` 并让安装继续 ——
+//      插件装上了但没就绪，是"如实报未就绪 + 给动作"，不是"安装失败"。
+//
+// 垫片根的形状沿用生态既有约定（与 `docs/http-endpoints` 之外的现场一致）：
+//   `<目标目录>/node_modules/@deepseek-ai/<包>`  →  `<DSH_HOME>/profiles/node_modules/@deepseek-ai/<包>`
+// 为什么必须**链接**而不是复制：Cordis service 类 / LLM error 类等靠**模块身份**相认
+// （`instanceof` / 单例注册表）；复制一份就是第二个类对象，宿主与插件会互相不认。
+// 链接指向的是同一份真实文件 ⇒ realpath 相同 ⇒ 身份共享（真机已验：
+// `realpath(插件侧) === realpath(profiles/node_modules 侧)`）。
+//
+// 记录的用途：垫片是**我们造的**，卸载时必须只清掉**我们造的**这些（`removeLinkSelfSufficiency`），
+// 记在 `<DSH_HOME>/plugin-console/link-self-sufficiency/<包名>.json`，删除前逐个核对
+// "它现在仍是指向当初那个目标的链接"——被人改过/换过的东西一律不碰。
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, rmdirSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { buildPnpmEnv, runPnpmWithFallback, unknownPnpmOption } from '../infra/exec.js'
+import { dshHome } from '../infra/paths.js'
+import { canonicalSourceSpec, sourceSpecTarget, suggestedPinAction } from './dep-source.js'
+
+/** 框架包的 scope：垫片只补这一族（peer 声明里也只有它需要"框架根"这一层）。 */
+const FRAMEWORK_SCOPE = '@deepseek-ai'
+
+/** 垫片根（框架安装时建立的、profile 共用的解析根）：`<DSH_HOME>/profiles/node_modules/@deepseek-ai`。 */
+function frameworkShimRoot(home) {
+  return join(home, 'profiles', 'node_modules', FRAMEWORK_SCOPE)
+}
+
+/** 记录目录/记录文件（一个包一份，便于卸载时精确定位）。 */
+function selfSufficiencyRecordDir(home) {
+  return join(home, 'plugin-console', 'link-self-sufficiency')
+}
+function recordFileNameOf(packageName) {
+  return `${String(packageName).replace(/[^A-Za-z0-9._-]+/gu, '_')}.json`
+}
+function selfSufficiencyRecordPath(home, packageName) {
+  return join(selfSufficiencyRecordDir(home), recordFileNameOf(packageName))
+}
+
+/** 读 JSON（读不到/坏文件都返回 null，绝不抛）。 */
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** 路径上**是否已经有东西**（含悬空链接）——"绝不覆盖"的判据必须用 lstat，不能用 exists。 */
+function pathTaken(p) {
+  try {
+    lstatSync(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 从 `startDir` 起按 Node 的规矩向上找 `node_modules/<包名>`（最多 12 层）。
+ * 为什么向上走而不是只看目标目录：目标目录若本身位于某个 profile 之内，
+ * 祖先链上的 node_modules **本来就能被 Node 解析到** —— 那时再补垫片就是多余写盘（违反规矩①）。
+ */
+function resolveFromDir(startDir, packageName, depth = 12) {
+  let current = startDir
+  for (let i = 0; i < depth; i += 1) {
+    const candidate = join(current, 'node_modules', ...String(packageName).split('/'))
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return null
+}
+
+/** 读 profile 清单里该包的 spec（读不到返回 null）。 */
+function manifestSpecOf(profileDir, packageName) {
+  const manifest = readJsonSafe(join(profileDir, 'package.json'))
+  const spec = manifest?.dependencies?.[packageName]
+  return typeof spec === 'string' && spec !== '' ? spec : null
+}
+
+/** 是否路径型来源（`link:` / `file:`）——只有这一族才有"目标目录"可补齐。 */
+function isPathSpec(spec) {
+  const canonical = canonicalSourceSpec(spec)
+  return typeof canonical === 'string' && /^(?:link:|file:)/u.test(canonical)
+}
+
+/**
+ * 只读判据：这个 `link:` 依赖当前**自足**吗？缺什么？能不能补？
+ * 纯读盘、零写盘、不联网 —— 调用方拿它决定要不要动手（以及向用户怎么如实汇报）。
+ * 返回 `{ applies, ready, target, targetExists, declaredDeps, declaredPeers, missingDeps,
+ *          missingPeers, shimmablePeers, unavailablePeers, note, action }`。
+ */
+function planLinkSelfSufficiency({ profileDir, packageName, spec = null, home = null } = {}) {
+  const base = {
+    applies: false, ready: true, profileDir, packageName, spec: null, target: null, targetExists: false,
+    declaredDeps: [], declaredPeers: [], missingDeps: [], missingPeers: [], shimmablePeers: [], unavailablePeers: [], foreignPeers: [],
+    note: null, action: null,
+  }
+  const homeDir = typeof home === 'string' && home !== '' ? home : dshHome()
+  const resolvedSpec = typeof spec === 'string' && spec !== '' ? spec : manifestSpecOf(profileDir, packageName)
+  if (resolvedSpec === null) return { ...base, reason: `${packageName}：清单里没有该依赖（或 spec 为空）—— 无需补齐` }
+  if (!isPathSpec(resolvedSpec)) {
+    return { ...base, spec: resolvedSpec, reason: `${packageName}：spec 不是路径型来源（${resolvedSpec}）—— 依赖与 peer 由包管理器保证，无需补齐` }
+  }
+  const target = sourceSpecTarget(profileDir, resolvedSpec)
+  if (target === null) return { ...base, spec: resolvedSpec, reason: `${packageName}：spec（${resolvedSpec}）解析不出目标目录 —— 无需补齐` }
+  const pkg = readJsonSafe(join(target, 'package.json'))
+  if (pkg === null) {
+    return {
+      ...base,
+      applies: true,
+      ready: false,
+      spec: resolvedSpec,
+      target,
+      targetExists: false,
+      note: `${packageName}：链接目标 ${target} 里没有 package.json —— 本地目录被移动/删除，或还从未安装过；垫片无从补起（未改动任何东西）`,
+      action: suggestedPinAction({ packageName, profileDir }),
+    }
+  }
+  const declaredDeps = Object.keys(pkg.dependencies ?? {})
+  const declaredPeers = Object.keys(pkg.peerDependencies ?? {})
+  const missingDeps = declaredDeps.filter((name) => resolveFromDir(target, name) === null)
+  const missingPeers = declaredPeers.filter((name) => resolveFromDir(target, name) === null)
+  const root = frameworkShimRoot(homeDir)
+  const shimmablePeers = []
+  const unavailablePeers = []
+  for (const name of missingPeers) {
+    const short = name.startsWith(`${FRAMEWORK_SCOPE}/`) ? name.slice(FRAMEWORK_SCOPE.length + 1) : null
+    if (short !== null && existsSync(join(root, short, 'package.json'))) shimmablePeers.push(name)
+    else unavailablePeers.push(name)
+  }
+  // 「能解析」不等于「解析到宿主那一份」：声明过的框架 peer 若解析到**别处**（例如某次 pnpm install
+  // 从 registry 自动装进来的一份），模块身份就不共享。这里**只报告、不动手** —— 绝不覆盖是硬规矩。
+  const foreignPeers = []
+  for (const name of declaredPeers) {
+    if (missingPeers.includes(name)) continue
+    const short = name.startsWith(`${FRAMEWORK_SCOPE}/`) ? name.slice(FRAMEWORK_SCOPE.length + 1) : null
+    if (short === null) continue
+    const rootPkg = join(root, short)
+    if (!existsSync(join(rootPkg, 'package.json'))) continue
+    const found = resolveFromDir(target, name)
+    try {
+      if (found !== null && realpathSync(found) !== realpathSync(rootPkg)) foreignPeers.push({ name, resolved: found, frameworkRoot: rootPkg })
+    } catch {
+      foreignPeers.push({ name, resolved: found, frameworkRoot: rootPkg })
+    }
+  }
+  const ready = missingDeps.length === 0 && missingPeers.length === 0
+  return {
+    ...base,
+    applies: true,
+    ready,
+    spec: resolvedSpec,
+    target,
+    targetExists: true,
+    declaredDeps,
+    declaredPeers,
+    missingDeps,
+    missingPeers,
+    shimmablePeers,
+    unavailablePeers,
+    foreignPeers,
+    note: ready
+      ? null
+      : `${packageName}：链接目标 ${target} 尚不自足 —— 缺依赖 [${missingDeps.join(', ')}]` +
+        `${missingPeers.length === 0 ? '' : `、缺框架 peer [${missingPeers.join(', ')}]`}`,
+    action: ready ? null : suggestedPinAction({ packageName, profileDir }),
+  }
+}
+
+/** 在**目标目录内**装它的 dependencies（pnpm install）。失败一律如实返回，绝不抛。
+ *
+ * ★ 绝不让 pnpm **自动装 peer**（pnpm 8+ 默认 `auto-install-peers=true`）—— 真机实测（2026-10-06）：
+ *   夹具声明 `@deepseek-ai/dsh-llm` 为 peer，跑 `pnpm install` 后 pnpm 从 **registry** 装了一份
+ *   `0.1.5-rc.3` 进目标目录，而宿主用的是它**自己那一份**（本机框架根 = 0.2.0-rc.2）。
+ *   两份不同的模块 ⇒ Cordis service / LLM error 的**类身份不共享** —— 正是"补了反而更糟"。
+ *   peer 的正确来源是**框架根垫片**（指向同一份真实文件），所以这里必须把自动装 peer 关掉，
+ *   分工才是干净的：**dependencies 交给 pnpm，peer 交给垫片**。
+ *   选项不认识（老 pnpm）时退回不带该选项重试一次 —— 与 infra/exec.js#runPnpmAdd 同一条规矩，
+ *   绝不让"加固"变成"跑不成"。 */
+async function installTargetDependencies({ target, deps = {} } = {}) {
+  const run = typeof deps.runPnpm === 'function' ? deps.runPnpm : runPnpmWithFallback
+  const unknownOption = typeof deps.unknownOption === 'function' ? deps.unknownOption : unknownPnpmOption
+  const timeoutMs = Number.isFinite(deps.timeoutMs) ? deps.timeoutMs : 180000
+  const execOpts = { cwd: target, timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024, env: buildPnpmEnv(null) }
+  const base = ['install', '--prefer-offline']
+  const attempts = [[...base, '--config.auto-install-peers=false'], base]
+  let lastError = null
+  for (const argv of attempts) {
+    try {
+      const out = await run(argv, { execOpts })
+      return { ok: true, error: null, argv, stdoutTail: String(out?.stdout ?? '').slice(-400) }
+    } catch (error) {
+      lastError = error
+      if (!unknownOption(String(error?.message ?? ''))) break
+    }
+  }
+  return {
+    ok: false,
+    error: String(lastError?.message ?? lastError).slice(0, 600),
+    argv: attempts[0],
+    exitCode: Number.isInteger(lastError?.code) ? lastError.code : null,
+  }
+}
+
+/** 建 peer 垫片（只补缺、绝不覆盖）。返回 `{ created, skipped }`。 */
+function createPeerShims({ target, peers, home, deps = {} }) {
+  const symlink = typeof deps.symlink === 'function' ? deps.symlink : (t, p) => symlinkSync(t, p, 'junction')
+  const root = frameworkShimRoot(home)
+  const created = []
+  const skipped = []
+  for (const name of peers) {
+    const short = String(name).slice(FRAMEWORK_SCOPE.length + 1)
+    const linkPath = join(target, 'node_modules', FRAMEWORK_SCOPE, short)
+    const targetPath = join(root, short)
+    if (pathTaken(linkPath)) { skipped.push({ name, link: linkPath, reason: 'occupied（已存在任何东西，含悬空链接）—— 不覆盖' }); continue }
+    if (!existsSync(join(targetPath, 'package.json'))) { skipped.push({ name, reason: `框架根里没有 ${short}（无法补）` }); continue }
+    try {
+      mkdirSync(dirname(linkPath), { recursive: true })
+      symlink(targetPath, linkPath)
+      created.push({ name, link: linkPath, target: targetPath })
+    } catch (error) {
+      skipped.push({ name, reason: `建链接失败：${String(error?.message ?? error).slice(0, 200)}` })
+    }
+  }
+  return { created, skipped }
+}
+
+/** 写记录（与既有记录取并集，绝不丢掉早先造过的垫片 —— 否则卸载会漏清）。 */
+function writeSelfSufficiencyRecord(home, packageName, created) {
+  if (created.length === 0) return null
+  const file = selfSufficiencyRecordPath(home, packageName)
+  const previous = readJsonSafe(file)
+  const known = Array.isArray(previous?.shims) ? previous.shims : []
+  const seen = new Set(known.map((s) => s?.link))
+  const merged = [...known]
+  for (const item of created) if (!seen.has(item.link)) merged.push({ name: item.name, link: item.link, target: item.target })
+  const record = { packageName, updatedAt: new Date().toISOString(), shims: merged }
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, 'utf8')
+    return file
+  } catch {
+    return null
+  }
+}
+
+/** 这次尝试的人话小结（空段自动跳过；只拼接、不覆盖 —— 覆盖就是谎报的来源）。 */
+function composeSelfSufficiencyNote({ packageName, installed, created, skipped, finalPlan }) {
+  const parts = []
+  if (installed !== null) {
+    parts.push(installed.ok === true
+      ? `${packageName}：已在链接目标内装齐 dependencies`
+      : `${packageName}：在链接目标内装 dependencies 失败（${installed.error}）`)
+  }
+  if (created.length > 0) parts.push(`已补框架 peer 垫片 ${created.length} 个（${created.map((c) => c.name).join(', ')}）`)
+  if (skipped.length > 0) parts.push(`跳过 ${skipped.length} 个（${skipped.map((s) => `${s.name}: ${s.reason}`).join('；')}）`)
+  if ((finalPlan?.foreignPeers ?? []).length > 0) parts.push(`注意：${finalPlan.foreignPeers.map((p) => `${p.name} 解析到别处（${p.resolved}），与框架根不是同一份 ⇒ 模块身份可能与宿主不共享（未改动，仅如实提示）`).join('；')}`)
+  if (finalPlan?.ready === true) parts.push('链接目标现已自足')
+  else if (finalPlan?.applies === true) {
+    const missing = [...(finalPlan.missingDeps ?? []), ...(finalPlan.missingPeers ?? [])]
+    parts.push(`仍未就绪：缺 ${missing.join(', ') || '（目标目录不可用）'}`)
+  }
+  return parts.length === 0 ? null : parts.join('；')
+}
+
+/**
+ * 让一个 `link:` 依赖自足（**安装主路径上的唯一入口**）。
+ * 顺序是刻意的：**先装依赖、后建垫片** —— `pnpm install` 会按 lock 修剪 node_modules，
+ * 先建垫片会被它顺手清掉。
+ * 返回 `{ ok, applies, ready, changed, installed, created, skipped, note, action, plan }`。
+ * `ok` 表示"这次尝试本身没出意外"，**不**表示插件一定可用；可用性看 `ready`。
+ * 任何情况都**不抛**：调用方（安装/钉住流程）绝不因为它而拒绝安装。
+ */
+async function ensureLinkSelfSufficiency({ profileDir, packageName, spec = null, home = null, deps = {} } = {}) {
+  const homeDir = typeof home === 'string' && home !== '' ? home : dshHome()
+  const empty = { ok: true, applies: false, ready: true, changed: false, installed: null, created: [], skipped: [], note: null, action: null }
+  try {
+    const plan = planLinkSelfSufficiency({ profileDir, packageName, spec, home: homeDir })
+    if (plan.applies !== true) return { ...empty, note: plan.reason, plan }
+    if (plan.ready === true) return { ...empty, applies: true, note: null, plan } // 规矩①：自足 ⇒ 零写盘
+    if (plan.targetExists !== true) return { ...empty, applies: true, ready: false, note: plan.note, action: plan.action, plan }
+
+    let installed = null
+    if (plan.missingDeps.length > 0) {
+      installed = await installTargetDependencies({ target: plan.target, deps })
+    }
+    const afterDeps = planLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home: homeDir })
+    const { created, skipped } = createPeerShims({ target: plan.target, peers: afterDeps.shimmablePeers, home: homeDir, deps })
+    if (created.length > 0) writeSelfSufficiencyRecord(homeDir, packageName, created)
+
+    const finalPlan = planLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home: homeDir })
+    return {
+      ok: true,
+      applies: true,
+      ready: finalPlan.ready === true,
+      changed: created.length > 0 || installed?.ok === true,
+      installed,
+      created,
+      skipped,
+      note: composeSelfSufficiencyNote({ packageName, installed, created, skipped, finalPlan }),
+      action: finalPlan.ready === true ? null : finalPlan.action,
+      plan: finalPlan,
+    }
+  } catch (error) {
+    // 规矩③：意外也只如实报，绝不把它变成安装失败
+    return { ...empty, 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()
+  const dir = selfSufficiencyRecordDir(homeDir)
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => ({ file: join(dir, f), record: readJsonSafe(join(dir, f)) }))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 删掉一个**链接本身**（不动它指向的目标）。
+ * ★ 这里踩过一次真坑（2026-10-06 本机实测）：Windows 上 `fs.rmSync(junction, {recursive:false})`
+ *   **一声不响地什么都不删**（不抛错、链接还在）—— 与 pnpm 改名被挡留下的 `*_tmp_*` 是同一族现场。
+ *   实测：`unlinkSync` 与 `rmdirSync` 都能删掉链接且目标存活；`rmSync` 两种写法都无效。
+ *   所以顺序是 unlink → rmdir，并逐个复核"真的没了"，删不掉如实上报（绝不谎报已清理）。
+ */
+function removeLinkEntry(link) {
+  for (const attempt of [() => unlinkSync(link), () => rmdirSync(link)]) {
+    try { attempt() } catch {}
+    if (!pathTaken(link)) return true
+  }
+  return !pathTaken(link)
+}
+
+/**
+ * 卸载时清掉**我们造的**垫片（卸载即撤销：与 `undeclareProfileDependency` 同一时机调用）。
+ * 只删"现在仍是指向当初记录目标的链接"的那些；被人改过/换成真实目录的一律保留并如实报。
+ * 返回 `{ removed, kept, note }`；不抛。
+ */
+function removeLinkSelfSufficiency({ packageName, home = null } = {}) {
+  const homeDir = typeof home === 'string' && home !== '' ? home : dshHome()
+  const file = selfSufficiencyRecordPath(homeDir, packageName)
+  const record = readJsonSafe(file)
+  const shims = Array.isArray(record?.shims) ? record.shims : []
+  const removed = []
+  const kept = []
+  for (const item of shims) {
+    const link = typeof item?.link === 'string' ? item.link : null
+    const target = typeof item?.target === 'string' ? item.target : null
+    if (link === null || target === null || !pathTaken(link)) { kept.push({ link, reason: '链接已不在（可能已被用户/其它工具处理）' }); continue }
+    let stillOurs = false
+    try {
+      stillOurs = lstatSync(link).isSymbolicLink() && readlinkSync(link) === target
+    } catch {
+      stillOurs = false
+    }
+    if (!stillOurs) { kept.push({ link, reason: '它现在不是指向当初目标的链接（已被改动）—— 不碰' }); continue }
+    if (removeLinkEntry(link)) removed.push(link)
+    else kept.push({ link, reason: '删除未生效（可能被占用）—— 保留' })
+  }
+  let recordRemoved = false
+  let recordEmptied = false
+  if (existsSync(file)) {
+    try { rmSync(file, { force: true }) } catch {}
+    recordRemoved = !existsSync(file)
+    if (!recordRemoved) {
+      // 删不掉时**退而求其次清空内容**（真机实测：`<DSH_HOME>/plugin-console/` 下的文件在本机
+      // 删除会静默落空 —— 与 `*_tmp_*`、junction 是同一族的 Windows 静默失败）。
+      // 不能留下指向**已删垫片**的陈旧条目：下一次清理会"找不到"而误报，也让人误以为东西还在。
+      try {
+        writeFileSync(file, `${JSON.stringify({ packageName, updatedAt: new Date().toISOString(), shims: [], note: '垫片已清理；文件本身删除未生效，已清空以免留下陈旧条目' }, null, 2)}\n`, 'utf8')
+        recordEmptied = (readJsonSafe(file)?.shims ?? null)?.length === 0
+      } catch { recordEmptied = false }
+    }
+  }
+  const note = removed.length === 0 && kept.length === 0
+    ? null
+    : `垫片清理：删除 ${removed.length} 个${kept.length === 0 ? '' : `，保留 ${kept.length} 个（${kept.map((k) => `${k.link}：${k.reason}`).join('；')}）`}` +
+      (recordRemoved || recordEmptied || !existsSync(file) ? '' : '；记录文件删除未生效且无法清空（已如实保留）')
+  return { removed, kept, recordRemoved, recordEmptied, note }
+}
+
+export {
+  FRAMEWORK_SCOPE,
+  frameworkShimRoot,
+  selfSufficiencyRecordDir,
+  selfSufficiencyRecordPath,
+  planLinkSelfSufficiency,
+  ensureLinkSelfSufficiency,
+  removeLinkSelfSufficiency,
+  listSelfSufficiencyRecords,
+  installTargetDependencies,
+  createPeerShims,
+  resolveFromDir,
+  isPathSpec,
+}

package/lib/server/domain/manifest.js

@@ -12,8 +12,11 @@
 
 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'
 import { reconcileLockfile } from './selfupdate.js'
 
@@ -108,10 +111,25 @@ async function specOf(profileDir, packageName) {
  *   · 本次没探到（网络/镜像不可达）      → 不敢替用户猜：仍按旧行为写版本号，但**如实记 note**
  *     并给出结构化「钉住」建议动作（面板可一键执行），绝不写成"已钉住"。
  * 返回 { form, spec, note, suggestion }；`spec` 为 null 表示"不要改清单"。
+ *
+ * 2026-10-06 加法 —— **来源型默认【真装】**（用户点名：「默认真装 + link 自足」）：
+ *   调用方**知道这个包的真实来源规格**时（tarball URL / `github:owner/repo` / 本地目录），
+ *   传 `sourceSpec` 进来，写回的就是**那个规格本身** —— 于是 `pnpm add <spec>` 由包管理器
+ *   保证依赖与 peer，与官方 `dsh plugin add` 同一条通道（`form: 'source'`）。
+ *   `link:` 退居**显式开发式安装**：仅在"拿不到真实来源规格"（或用户明确选择开发式）时使用，
+ *   由 `link-self-sufficiency.js` 补齐依赖与框架 peer 垫片根。
+ *   优先级刻意保持"registry 可解析 → 版本号"在最前：既有 registry 流程一字不改（不倒退）。
  */
-async function planDependencySpec({ profileDir, packageName, version, registries = [], probe = null, home = undefined, profile = null }) {
+async function planDependencySpec({ profileDir, packageName, version, registries = [], probe = null, home = undefined, profile = null, sourceSpec = null }) {
   const doProbe = typeof probe === 'function' ? probe : probeRegistryPackage
+  const realSpec = typeof sourceSpec === 'string' && sourceSpec.trim() !== '' ? sourceSpec.trim() : null
   const linkable = () => materializePackageForLink(profileDir, packageName, home === undefined ? {} : { home })
+  const asSource = () => ({
+    form: 'source',
+    spec: realSpec,
+    note: `${packageName}：按**真实来源规格**记录依赖（${realSpec}）—— 走 pnpm add <spec> 真装，依赖与 peer 由包管理器保证（与官方 dsh plugin add 同一通道）`,
+    suggestion: null,
+  })
   const asLink = (why) => {
     const dir = linkable()
     if (dir === null) {
@@ -137,6 +155,8 @@ async function planDependencySpec({ profileDir, packageName, version, registries
     result = { resolvable: false, hasVersion: false, tried: [error instanceof Error ? error.message : String(error)] }
   }
   if (result?.resolvable === true && result.hasVersion !== false) return { form: 'version', spec: version, note: null, suggestion: null }
+  // 来源型：调用方给了真实来源规格 ⇒ 默认真装（不写 link:）。拿不到真实规格才退回 link:。
+  if (probeFailureKind(result) === 'fetch-404' && realSpec !== null) return asSource()
   if (probeFailureKind(result) === 'fetch-404') {
     return asLink(result?.resolvable === true
       ? `registry 上没有 ${version} 这个版本（该包只在 GitHub release / 本地有）`
@@ -164,13 +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 } = options
-  const empty = { changed: false, version: null, spec: null, form: null, reason: null, lockSynced: false, lockNote: null, depNote: null, suggested: null }
+  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 (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, 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 })
-  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 ?? {}) }
@@ -182,13 +247,56 @@ async function declareProfileDependency(profileDir, packageName, version = null,
     await writeManifest(profileDir, manifest)
     return { changed: true }
   })
-  const out = { ...empty, changed: result.changed, version: resolved, spec: plan.spec, form: plan.form, depNote: plan.note, suggested: plan.suggestion }
+  // ★ link: 自足性（2026-10-06 加法）：写成 link: 之后立刻补齐 —— 目标目录内装它的 dependencies
+  // + 建框架 peer 垫片根。幂等（自足 ⇒ 零写盘）、绝不覆盖它自带的 node_modules、
+  // 失败只如实报未就绪 + 给动作 —— 安装主路径**不新增拒绝分支**。
+  const selfSufficiency = plan.form === 'link'
+    ? await ensureLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home })
+    : null
+  // 真装失败 ⇒ 结构化「一键真装」动作优先（此时"钉住/自足"类动作都不是用户想要的那一步）；
+  // 它的 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 })
-  return { ...out, ...synced, depNote: joinNotes(plan.note, synced.depNote), suggested: synced.suggested ?? plan.suggestion }
+  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(installNote, plan.note, selfSufficiency === null ? null : selfSufficiency.note, synced.depNote),
+    suggested: installAction ?? synced.suggested ?? (selfSufficiency === null ? null : selfSufficiency.action) ?? plan.suggestion,
+  }
+}
+
+/**
+ * 来源型**真装**（2026-10-06 加法）：把真实来源规格交给包管理器 —— `pnpm add <spec>` 进 profile，
+ * 与官方 `dsh plugin add` 同一条通道（依赖与 peer 由 pnpm 保证，我们不手铺）。
+ * 返回 `{ ok, spec, error }`，**绝不抛**：安装主路径不得新增拒绝分支。
+ */
+async function installSourceDependency({ profileDir, spec, registries = [], install = null, timeout = 180000 } = {}) {
+  const runner = typeof install === 'function' ? install : runPnpmAdd
+  const registry = (Array.isArray(registries) ? registries : []).find((r) => typeof r === 'string' && r.trim() !== '') ?? 'https://registry.npmmirror.com'
+  try {
+    await runner({ profileDir, spec, registry, timeout })
+    return { ok: true, spec, error: null }
+  } catch (error) {
+    return { ok: false, spec, error: String(error instanceof Error ? error.message : error).slice(0, 600) }
+  }
 }
 
 /** 多段说明拼接（空段自动跳过）：文案只做拼接，不覆盖 —— 覆盖就是"谎报"的来源。 */
@@ -204,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 {
@@ -241,7 +350,10 @@ async function pinProfileDependency(profileDir, packageName, options = {}) {
     return true
   })
   const after = await specOf(profileDir, packageName)
-  return { ok: sameSourceSpec(profileDir, after, spec), spec, before, after, changed, dir }
+  // ★ link: 自足性（2026-10-06 加法）：钉住是"显式开发式安装"的入口，钉完立刻补齐
+  // （目标目录内装 dependencies + 框架 peer 垫片根）。幂等、绝不覆盖、失败只如实报。
+  const selfSufficiency = await ensureLinkSelfSufficiency({ profileDir, packageName, spec, home })
+  return { ok: sameSourceSpec(profileDir, after, spec), spec, before, after, changed, dir, selfSufficiency }
 }
 
 /**
@@ -266,9 +378,11 @@ async function setProfileDependency(profileDir, packageName, spec) {
   return { before, after: await specOf(profileDir, packageName), changed }
 }
 
-/** 卸载即撤销声明。 */
-async function undeclareProfileDependency(profileDir, packageName) {
-  return queuedWrite(async () => {
+/** 卸载即撤销声明（并清掉**我们造的** link 垫片 —— 卸载即净）。
+ *  `options.home` 必须与当初 `declareProfileDependency` 用的 home 一致（生产两边都不传 = `dshHome()`）；
+ *  只有隔离测试才会传私有 home —— 传错不会误删（记录读不到 ⇒ 无事发生），但也清不掉。 */
+async function undeclareProfileDependency(profileDir, packageName, options = {}) {
+  const result = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
     const deps = { ...(manifest.dependencies ?? {}) }
     if (!(packageName in deps)) return { changed: false }
@@ -277,6 +391,12 @@ async function undeclareProfileDependency(profileDir, packageName) {
     await writeManifest(profileDir, manifest)
     return { changed: true }
   })
+  // 2026-10-06 加法：link 自足性造的垫片是我们加的，卸载时只清**我们造的**那些
+  // （记录里逐个核对"现在仍是指向当初目标的链接"，被人改过的一律不碰）。清不掉只如实报。
+  const shims = removeLinkSelfSufficiency({ packageName, home: options.home ?? null })
+  // 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 }
 }
 
 /**
@@ -330,6 +450,6 @@ async function applyDependencyBackfill(profileDir, options = {}) {
 
 export {
   DEFAULT_BUNDLES, addBundleToManifest, applyDependencyBackfill, declareProfileDependency,
-  installedVersionOf, planDependencyBackfill, planDependencySpec, pinProfileDependency, removeBundleFromManifest,
+  installedVersionOf, installSourceDependency, planDependencyBackfill, planDependencySpec, pinProfileDependency, removeBundleFromManifest,
   setProfileDependency, specOf, syncLockFor, undeclareProfileDependency,
 }