@noob-stupid/dsh-plugin-console 0.5.19 → 0.5.21

package/lib/client.js

@@ -110,6 +110,18 @@ window.__ModuleLoader__.load({
 			safetyLockNoRebuild: "当前不需要重建",
 			safetyLockCheckBtn: "体检",
 			safetyLockRepairBtn: "重建 lock（显式）",
+			// 2026-09-27 加法：安装结果旁的「建议动作」执行框（短句进面板，长解释进悬浮 title）
+			actionBoxTitle: "建议动作",
+			actionPinLabel: "钉住该依赖（按 link: 记录）",
+			actionReconcileLabel: "重建 pnpm-lock.yaml",
+			actionRun: "执行",
+			actionCopy: "复制",
+			actionCopied: "已复制命令",
+			actionRunning: "执行中…",
+			actionOk: "执行成功",
+			actionPartial: "部分成功（清单已改，lock 未对齐）",
+			actionFailed: "执行失败",
+			actionLongTitle: "控制台按白名单动作在自己的进程里执行（只认 pin-dependency / reconcile-lock 这类内置动作，绝不接受自定义命令字符串）；命令仅供展示与复制。",
 			safetyMode: "运行模式",
 			safetyModeManaged: "托管：框架升级与回滚由本控制台负责（默认，行为与之前一致）",
 			safetyModeManagedOn: "已切到托管模式：框架升级与回滚仍由本控制台负责",
@@ -624,6 +636,17 @@ window.__ModuleLoader__.load({
 			safetyLockNoRebuild: "No rebuild needed right now",
 			safetyLockCheckBtn: "Check",
 			safetyLockRepairBtn: "Rebuild lock (explicit)",
+			actionBoxTitle: "Suggested action",
+			actionPinLabel: "Pin this dependency (record as link:)",
+			actionReconcileLabel: "Rebuild pnpm-lock.yaml",
+			actionRun: "Run",
+			actionCopy: "Copy",
+			actionCopied: "Command copied",
+			actionRunning: "Running…",
+			actionOk: "Done",
+			actionPartial: "Partly done (manifest updated, lock not aligned)",
+			actionFailed: "Failed",
+			actionLongTitle: "The console runs a whitelisted action inside its own process (only built-in kinds such as pin-dependency / reconcile-lock; a custom command string is never accepted). The command itself is display/copy only.",
 			safetyMode: "Operating mode",
 			safetyModeManaged: "Managed: this console owns framework upgrade and rollback (default, unchanged behaviour)",
 			safetyModeManagedOn: "Switched to managed: framework upgrade and rollback stay with this console",
@@ -1166,6 +1189,27 @@ window.__ModuleLoader__.load({
 			}
 			return data;
 		}
+		/** 执行「建议动作」：与 call() 的关键差别 ——**服务端把"动作失败"也当结果返回**
+		 *  （`{ ok:false, partial:true, exitCode, reason, stderr }`），而 call() 的统一约定会把
+		 *  `data.ok === false` 抛成一句没信息量的 "HTTP 200"（真机体验：失败原因看不见）。
+		 *  所以这里直接读响应体，只把"协议级失败（HTTP != 2xx / 网络异常）"当错误抛。 */
+		async function callAction(payload) {
+			const response = await fetch("/plugin-console/run-suggested", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(payload),
+			});
+			let data = null;
+			try { data = await response.json(); } catch {}
+			if (!response.ok) {
+				throw new Error(data !== null && typeof data.error === "string" && data.error !== "" ? data.error : "HTTP " + response.status);
+			}
+			return data ?? {};
+		}
+		/** 复制到剪贴板：抽成函数便于离线渲染测试断言；失败**绝不抛**（无权限/老浏览器时只是没复制上）。 */
+		function copyToClipboard(text) {
+			try { void navigator.clipboard.writeText(String(text)); return true } catch { return false }
+		}
 		/** 重启服务（按钮 / 工具项 / 自更新后共用）：服务端在「本实例由桌面端外壳托管」等场景会**拒绝**
 		 *  并回结构化短句 —— 必须把它显示出来，否则按钮看起来是「点了没反应」（旧实现把错误吞掉了）。 */
 		function restartServiceViaServer(setMessage, options) {
@@ -2835,6 +2879,10 @@ window.__ModuleLoader__.load({
 									}
 									if (data.bundle) {
 										setRestartHint(true);
+									} else if (data.suggestedAction !== null && data.suggestedAction !== undefined) {
+										// 有建议动作时不自动刷新页面（2026-09-27 加法）：旧行为 2.5 秒后 reload，
+										// 用户根本来不及点「执行」；这里改成给一个"请刷新"的可见提示。
+										setReloadHint(true);
 									} else {
 										// 安装成功：自动刷新页面，让插件立即出现在列表里（可见的成功反馈）
 										setReloadHint(true);
@@ -4752,6 +4800,9 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 				// 安装诊断卡（2026-09-26 加法）：只有**装成功但装后校验 / 摘要校验有问题**的作业才出现
 				// （无问题时 diagCardEl 返回 null，不占版面）。数据只用本地 jobs 状态，不新增任何接口字段。
 				Object.values(jobs).filter((job) => job.status === "done").map((job) => diagCardEl(job)),
+				// 建议动作执行框（2026-09-27 加法）：只在安装结果里带了 suggestedAction 时出现（否则返回 null，不占版面）
+				Object.values(jobs).filter((job) => job.status === "done" && job.suggestedAction !== null && job.suggestedAction !== undefined)
+					.map((job) => el(SuggestedActionBox, { key: "act-" + job.jobId, job: job, t: t })),
 				Object.entries(suiteReports).map(([jobId, report]) =>
 					el("div", { key: "suite-" + jobId, className: styles.detail },
 						el("p", { className: styles.status }, t("suiteComponentType") + "："),
@@ -5138,6 +5189,68 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 		//   它没有开放任何子插槽；官方 settings.plugins.tab 的 owner props 也是空的（没有切兄弟 tab 的 API）。
 		//   所以做法是「就地抽屉」，而不是往别人的 DOM 里注入（注入会在对方更新时碎掉）。
 		//   原 tab（id=console）与悬浮面板一行未动。
+		/** 「建议动作」执行框（2026-09-27 加法，用户明确要求）：安装结果旁的一个**小**框 ——
+		 * 一句短说明 + 等宽只读命令 + 「执行」「复制」+ 执行中状态 + 结果/错误回显 + 可关闭。
+		 * 边界（与服务端同一条）：面板只发**结构化动作**（`suggestedAction.payload`），
+		 * 命令字符串仅用于展示/复制；服务端只认白名单动作类型（见 domain/plugin-actions.js）。
+		 * 只用既有 styles.*（detail / rowTop / phase / name / message / note / toggle / trashBtn），
+		 * 不新增徽章、不新增独立面板 —— 长解释一律进悬浮 title。 */
+		function SuggestedActionBox({ job, t }) {
+			const [state, setState] = react.useState({ phase: "idle", text: null, level: null, title: null, closed: false });
+			const action = job === null || job === undefined ? null : (job.suggestedAction ?? null);
+			if (action === null || typeof action.command !== "string" || state.closed === true) return null;
+			const running = state.phase === "running";
+			const label = action.kind === "pin-dependency" ? t("actionPinLabel")
+				: action.kind === "reconcile-lock" ? t("actionReconcileLabel")
+					: (typeof action.label === "string" && action.label !== "" ? action.label : String(action.kind ?? ""));
+			const run = () => {
+				if (running || action.payload === null || typeof action.payload !== "object") return;
+				setState({ phase: "running", text: t("actionRunning"), level: null, title: null, closed: false });
+				callAction(action.payload).then(
+					(done) => {
+						const verdict = done?.ok === true ? t("actionOk") : done?.partial === true ? t("actionPartial") : t("actionFailed");
+						const parts = [verdict];
+						if (typeof done?.reason === "string" && done.reason !== "") parts.push(done.reason);
+						const raw = typeof done?.stderr === "string" && done.stderr.trim() !== "" ? done.stderr.trim() : "";
+						if (raw !== "") parts.push(raw.split("\n").slice(-1)[0]);
+						setState({
+							phase: done?.ok === true ? "done" : "error",
+							text: parts.join(" · "),
+							level: done?.ok === true ? null : "warn",
+							title: [done?.command, typeof done?.exitCode === "number" ? "exitCode=" + done.exitCode : null, done?.stdout, raw].filter((s) => typeof s === "string" && s !== "").join("\n") || null,
+							closed: false,
+						});
+					},
+					(error) => setState({ phase: "error", text: (error !== null && typeof error.message === "string" && error.message !== "" ? error.message : t("actionFailed")), level: "error", title: null, closed: false }),
+				);
+			};
+			const copy = () => {
+				if (copyToClipboard(action.command)) setState({ phase: state.phase, text: t("actionCopied"), level: null, title: null, closed: false });
+			};
+			return el("div", { className: styles.detail, "data-suggested-action": String(action.kind ?? "") },
+				el("div", { className: styles.rowTop },
+					el("span", { className: styles.phase }, t("actionBoxTitle")),
+					el("strong", { className: styles.name, title: t("actionLongTitle") }, label),
+					el("button", {
+						type: "button", className: styles.trashBtn, title: t("closeModal"), "aria-label": t("closeModal"),
+						onClick: () => setState({ phase: "idle", text: null, level: null, title: null, closed: true }),
+					}, "✕")),
+				el("code", {
+					className: styles.note,
+					title: t("actionLongTitle"),
+					style: { fontFamily: "ui-monospace,SFMono-Regular,Menlo,monospace", fontSize: "12px", wordBreak: "break-all", userSelect: "text" },
+				}, action.command),
+				el("div", { className: styles.rowTop },
+					el("button", { type: "button", className: styles.toggle, disabled: running, onClick: run }, running ? t("actionRunning") : t("actionRun")),
+					el("button", { type: "button", className: styles.toggle, onClick: copy }, t("actionCopy")),
+					el("span", {
+						className: styles.message,
+						"data-warn": state.level === "warn" ? "true" : undefined,
+						"data-error": state.level === "error" ? "true" : undefined,
+						title: state.title === null ? undefined : state.title,
+					}, state.text ?? "")));
+		}
+		
 		function PluginSafetyTab({ t }) {
 			const [open, setOpen] = react.useState(false);
 			const [status, setStatus] = react.useState(null);
@@ -5349,6 +5462,9 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 		exports.NS = NS;
 		exports.apply = apply;
 		exports.inject = inject;
+		// 仅测试用导出（tests/test-plugin-actions.mjs 的离线渲染断言：用假 React 真渲染这个组件，
+		// 断言"有/无 suggestedAction、执行中、成功、失败、中英切换"五种情形的 DOM 结构）。
+		exports.SuggestedActionBox = SuggestedActionBox;
 		return module.exports;
 	}
 });

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

@@ -20,7 +20,7 @@
 //      不经 tarball 完整性校验，lock 删掉重建、node_modules 清空重装都稳定通过。
 
 import { existsSync, rmSync, mkdirSync, realpathSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 import { copyTree } from '../infra/fsx.js'
 import { fetchJsonUrl } from '../infra/http.js'
 import { dshHome } from '../infra/paths.js'
@@ -28,6 +28,16 @@ import { dshHome } from '../infra/paths.js'
 /** 物化目录的根（与用户 issue 里手工规避用的 `/root/.dsh/plugin-src/...` 同一位置）。 */
 const PLUGIN_SRC_DIR = 'plugin-src'
 
+/** profile 目录名（`…/profiles/web` → `web`）：只用于**回显**给用户看的动作载荷，
+ *  服务端**绝不**按它挑目录（永远按当前实例的 profile 目录施工）。 */
+function profileNameOf(profileDir) {
+  try {
+    return typeof profileDir === 'string' && profileDir !== '' ? basename(profileDir) : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * registry 能否解析该包的指定版本（按顺序多源尝试，任一源可解析即通过）。
  * 404 / 网络失败都归为「不可解析」——调用方据此决定**绝不写裸版本号**。
@@ -123,4 +133,51 @@ function linkSpecIsIntact(profileDir, packageName, spec) {
   }
 }
 
-export { PLUGIN_SRC_DIR, probeRegistryPackage, materializePackageForLink, linkSpecFor, linkSpecIsIntact }
+/**
+ * 探测失败的性质（纯函数，**唯一真源**）：能从 `tried` 文本里认出 404 就是「registry 查无此包」，
+ * 否则算「网络/镜像不可达」——两者对写回决策的意义完全不同（前者必须走 link:，后者只是本次没探到）。
+ * lockfile-health.js 的 probeVerdict 与 manifest.js 的写回判据都调它，避免两处正则各写一份。
+ */
+function probeFailureKind(probe) {
+  const tried = Array.isArray(probe?.tried) ? probe.tried.join(' | ') : ''
+  if (/HTTP 404|Not Found|E404|is not in the npm registry/iu.test(tried)) return 'fetch-404'
+  return 'network-timeout'
+}
+
+/** 包的 npm 名字法判据（与 routes/install.js 的入参校验同一形状，供动作载荷校验复用）。 */
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u
+
+/**
+ * 给用户的**结构化建议动作**（2026-09-27 加法，用户明确要求）：
+ * 面板不再只显示一句"请执行 xxx"，而是拿到一个可执行的结构体 —— `{ kind, label, command, payload }`。
+ * 安全语义（写死，配套测试见 tests/test-plugin-actions.mjs）：
+ *   · `command` **只供展示/复制**，服务端执行时**只认 payload.action 这个白名单类型**，argv 自己拼；
+ *   · payload 里只有动作类型 + 包名 + 版本 + profile 名（回显用），**没有任何命令字符串**位置。
+ */
+function suggestedPinAction({ packageName, version = null, profileDir = null, profile = null, home = undefined, reason = null } = {}) {
+  const dir = join(home ?? dshHome(), PLUGIN_SRC_DIR, ...String(packageName).split('/'))
+  const spec = linkSpecFor(dir)
+  const name = profile ?? profileNameOf(profileDir)
+  return {
+    kind: 'pin-dependency',
+    label: '钉住该依赖（按 link: 记录）',
+    // 展示用命令：与执行器同一份 argv 形状（服务端执行时自己拼，绝不采用客户端回传的字符串）
+    command: `pnpm add ${spec} --registry https://registry.npmmirror.com`,
+    payload: { action: 'pin-dependency', packageName, version, profile: name },
+    reason,
+  }
+}
+
+/** `reconcile-lock` 的建议动作（只重写 pnpm-lock.yaml，argv 由 lockfile-health.repairArgsFor 唯一产出）。 */
+function suggestedReconcileAction({ profileDir = null, profile = null, reason = null } = {}) {
+  const name = profile ?? profileNameOf(profileDir)
+  return {
+    kind: 'reconcile-lock',
+    label: '重建 pnpm-lock.yaml（只写 lock）',
+    command: 'pnpm install --lockfile-only --no-frozen-lockfile --registry https://registry.npmmirror.com',
+    payload: { action: 'reconcile-lock', profile: name },
+    reason,
+  }
+}
+
+export { PLUGIN_SRC_DIR, NPM_NAME_RE, probeRegistryPackage, probeFailureKind, materializePackageForLink, linkSpecFor, linkSpecIsIntact, profileNameOf, suggestedPinAction, suggestedReconcileAction }

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

@@ -214,6 +214,14 @@ async function runInstallJob(job, ports, deps = {}) {
   }
   const jobBudgetMs = Number.isFinite(deps.jobBudgetMs) && deps.jobBudgetMs > 0 ? deps.jobBudgetMs : 8 * 60 * 1000
   const aiConsentTimeoutMs = Number.isFinite(deps.aiConsentTimeoutMs) && deps.aiConsentTimeoutMs > 0 ? deps.aiConsentTimeoutMs : AI_CONSENT_TIMEOUT_MS
+  /** 「安装即声明」的收尾（三个调用点共用一个出口）：清单写回结果 → job 上的可见字段。
+   *  depNote / suggestedAction 也在这里落地：面板必须能看见"清单里**实际**写成了什么"，以及"没写成时点哪个按钮"。 */
+  const applyDeclared = (declared) => {
+    if (declared.changed) job.declared = declared.version
+    if (declared.depNote !== null) job.depNote = declared.depNote
+    if (declared.suggested !== null) job.suggestedAction = declared.suggested
+    if (declared.lockSynced === false && declared.lockNote !== null) job.lockNote = declared.lockNote
+  }
   try {
     job.stage = 'preparing'
     // 2026-09-06 事故（室友机器）：对 deepseek-ai/deepseek-harness（框架本体仓库）点安装会按 bundle 规则
@@ -479,6 +487,8 @@ async function runInstallJob(job, ports, deps = {}) {
       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，
@@ -507,30 +517,23 @@ async function runInstallJob(job, ports, deps = {}) {
       } else {
         job.bundleNote = (job.bundleNote ? job.bundleNote + '；' : '') + `${installedName} 已由已安装聚合包提供，仅更新包本身，不再注册重复行`
       }
-      // 安装即声明（2026-09-24）：装到哪版就把它写进 profile 清单的 dependencies，
-      // **并立刻同步 pnpm-lock.yaml**（declareProfileDependency 内部已含对账）——只写清单不写 lock
-      // 会让之后任何 pnpm 操作硬失败（ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS）。
-      // 对账失败只记 note，不让已经装好的包变成"安装失败"。
-      const declaredBundle = await declareProfileDependency(profileDir, installedName)
-      if (declaredBundle.changed) job.declared = declaredBundle.version
-      if (declaredBundle.lockSynced === false && declaredBundle.lockNote !== null) job.lockNote = declaredBundle.lockNote
+      // 安装即声明（2026-09-24）：装到哪版就写进 profile 清单并立刻同步 lock —— 只写清单不写 lock 会让
+      // 之后任何 pnpm 操作硬失败（ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS）。2026-09-27：写回**形态**由
+      // registry 可解析性决定（非 registry 包写 link:，见 manifest.js#planDependencySpec），故必须传 registries。
+      applyDeclared(await declareProfileDependency(profileDir, installedName, null, { registries }))
       job.status = 'done'
       return
     }
     if (alreadyServed) {
       job.note = `${installedName} 已由已安装条目提供，仅更新包本身，不重复注册`
-      const declaredServed = await declareProfileDependency(profileDir, installedName)
-      if (declaredServed.changed) job.declared = declaredServed.version
-      if (declaredServed.lockSynced === false && declaredServed.lockNote !== null) job.lockNote = declaredServed.lockNote
+      applyDeclared(await declareProfileDependency(profileDir, installedName, null, { registries }))
       job.status = 'done'
       return
     }
     const entryId = deriveEntryId(installedName, taken)
     await appendInsert(patchPath, entryId, installedName)
     job.entryId = entryId
-    const declared = await declareProfileDependency(profileDir, installedName)
-    if (declared.changed) job.declared = declared.version
-    if (declared.lockSynced === false && declared.lockNote !== null) job.lockNote = declared.lockNote
+    applyDeclared(await declareProfileDependency(profileDir, installedName, null, { registries }))
     job.status = 'done'
   } catch (error) {
     job.status = 'failed'

package/lib/server/domain/lockfile-health.js

@@ -20,7 +20,7 @@
 // 分层：本模块属于 L1 domain —— 不认识 cordis ctx，IO 一律以参数注入（便于离线单测）。
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { probeRegistryPackage } from './dep-source.js'
+import { probeFailureKind, probeRegistryPackage } from './dep-source.js'
 import { classifyInstallFailure, hintForKind } from './install-diagnose.js'
 import { buildPnpmEnv, runPnpmWithFallback } from '../infra/exec.js'
 import { semverRangeMatch } from '../infra/semver.js'
@@ -34,6 +34,19 @@ const PROBE_TIMEOUT_MS = 8000
 const REPAIR_TIMEOUT_MS = 180000
 const DEP_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies']
 
+/**
+ * spec 是不是**非 registry 来源**（`link:` / `file:` / `workspace:` / `portal:` / URL / git / 别名）。
+ * 2026-09-27 改错（与 0.5.20 的写回规则配套）：这类依赖**不经 registry 解析**，所以"registry 上 404"
+ * 对它们毫无信息量 —— 体检不能拿它判问题，重建更不能被它拦下。真实现场：desktop profile 的两个
+ * `@dsh-external/*` 按新规则钉成 `link:` 之后，体检仍按包名去 registry 探，报 `fetch-404` 并把重建
+ * **永久**挡在门外（`repair.applicable=false`），而 lock 其实完全一致。
+ * 与 `specSatisfiedBy` 共用同一份判据（唯一真源，避免两处各写一条正则）。
+ */
+function isSourceSpec(spec) {
+  return typeof spec === 'string'
+    && /^(?:link|file|workspace|portal|npm|git\+|git:|github:|gitlab:|bitbucket:|https?:)/iu.test(spec.trim())
+}
+
 /** 重建 lock 的 argv（纯函数，唯一产出点）：只重写 lock，不碰 node_modules；
  *  `--no-frozen-lockfile` 是必需的（我们的 pnpm env 带 CI=true，pnpm 在 CI 下默认 frozen-lockfile，
  *  不加它就只会得到 `ERR_PNPM_OUTDATED_LOCKFILE` —— 正是要修的那个症状）。
@@ -111,7 +124,7 @@ function parseLockImporters(lockText) {
  *  · 非 registry 来源（link:/file:/git+/http…）→ 交给 specifier 相等判定，这里恒 true。 */
 function specSatisfiedBy(spec, version) {
   if (typeof spec !== 'string' || spec === '') return true
-  if (/^(?:link|file|workspace|portal|npm|git\+|git:|github:|https?:)/iu.test(spec)) return true
+  if (isSourceSpec(spec)) return true
   if (typeof version !== 'string' || version === '') return false
   if (/^[\^~]?\d/u.test(spec) || /^(?:>=|>|=|<=|<)\s*\d/u.test(spec)) return semverRangeMatch(version, spec)
   return version === spec
@@ -151,7 +164,9 @@ function diffLockfile({ manifestText, lockText, installed = {} } = {}) {
       state = 'version-mismatch'
     }
     const onDisk = installed[dep.name] ?? null
-    if (onDisk !== null && locked.version !== null && onDisk !== locked.version) {
+    // 来源型 spec（link:/file:/URL/git）没有"版本号相等"可比：按盘上版本号与 lock 里的
+    // `link:../../…` 比，必然"漂移"（假阳性）。两个方向都判来源（spec 或 lock 解析任一是来源）。
+    if (onDisk !== null && locked.version !== null && !isSourceSpec(dep.spec) && !isSourceSpec(locked.version) && onDisk !== locked.version) {
       drift.push({ name: dep.name, installed: onDisk, lockVersion: locked.version })
     }
     deps.push({ name: dep.name, spec: dep.spec, section: dep.section, lockSpecifier: locked.specifier, lockVersion: locked.version, state })
@@ -183,11 +198,12 @@ function freshReleases(name, meta, { now = Date.now(), hours = RELEASE_AGE_HOURS
   return ageHours >= 0 && ageHours < hours ? [{ name, version: latest, publishedAt: time[latest], ageHours: Math.round(ageHours * 10) / 10 }] : []
 }
 
-/** registry 探测结论 → 分类（纯函数）：能从 tried 文本里认出 404 就点名 404，否则算"不可达"。 */
+/** registry 探测结论 → 分类（纯函数）：能从 tried 文本里认出 404 就点名 404，否则算"不可达"。
+ *  2026-09-27：判据搬进 domain/dep-source.js#probeFailureKind（写回决策与体检共用同一份正则——两处
+ *  各写一份的结果是"一处改了另一处不知道"，而这两处对 404 的判定必须永远一致）。本函数保留为
+ *  兼容导出，行为逐字不变（tests/test-lockfile-health.mjs ⑥ 仍按原名断言）。 */
 function probeVerdict(probe) {
-  const tried = Array.isArray(probe?.tried) ? probe.tried.join(' | ') : ''
-  if (/HTTP 404|Not Found|E404|is not in the npm registry/iu.test(tried)) return 'fetch-404'
-  return 'network-timeout'
+  return probeFailureKind(probe)
 }
 
 /** manifest 的 spec 里能确定"就是这一个版本"时取出来（用于探测"这个版本在不在 registry 上"）。 */
@@ -249,8 +265,10 @@ async function runLockfileCheck({
   const diff = diffLockfile({ manifestText: manifestText ?? '', lockText, installed })
   const manifest = readManifestDeps(manifestText ?? '')
 
-  // ① 依赖能不能在 registry 上解析（404 要点名；不可达与 404 分开说）
-  const probes = await Promise.all((manifest.ok ? manifest.deps : []).map(async (dep) => {
+  // ① 依赖能不能在 registry 上解析（404 要点名；不可达与 404 分开说）。
+  //    **来源型 spec 跳过探测**（2026-09-27 改错）：link:/file:/URL/git 本来就不经 registry 解析。
+  const sourceSpecDeps = (manifest.ok ? manifest.deps : []).filter((dep) => isSourceSpec(dep.spec)).map((dep) => dep.name)
+  const probes = await Promise.all((manifest.ok ? manifest.deps : []).filter((dep) => !isSourceSpec(dep.spec)).map(async (dep) => {
     const result = await probe(dep.name, probeList, {
       version: exactVersionOf(dep.spec),
       timeoutMs: PROBE_TIMEOUT_MS,
@@ -315,6 +333,8 @@ async function runLockfileCheck({
     lockfile: { present: diff.lockfilePresent, parsed: diff.lockfileParsed, entries: diff.deps.filter((d) => d.lockVersion !== null).length },
     problems,
     packages404: name404,
+    // 非 registry 来源的依赖（link:/file:/URL/git）：明确列出来，说明"为什么没探测它们"
+    sourceLinked: sourceSpecDeps,
     outdated: {
       lockfileMissing: !diff.lockfilePresent,
       missing: diff.missing,
@@ -421,6 +441,7 @@ export {
   diffLockfile,
   exactVersionOf,
   freshReleases,
+  isSourceSpec,
   parseLockImporters,
   problemLines,
   probeVerdict,

package/lib/server/domain/manifest.js

@@ -12,6 +12,7 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { linkSpecFor, materializePackageForLink, probeFailureKind, probeRegistryPackage, suggestedPinAction } from './dep-source.js'
 import { queuedWrite } from '../infra/fsx.js'
 import { resolvePackageJson } from '../infra/paths.js'
 import { reconcileLockfile } from './selfupdate.js'
@@ -82,6 +83,73 @@ async function removeBundleFromManifest(profileDir, bundlePkg) {
   })
 }
 
+/** 读 profile 清单里某包的 spec（读不到返回 null）。 */
+async function specOf(profileDir, packageName) {
+  try {
+    const manifest = await readManifest(profileDir)
+    const spec = manifest?.dependencies?.[packageName]
+    return typeof spec === 'string' && spec !== '' ? spec : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * **写回形态判定**（2026-09-27 改错，这是"清单里留下裸版本号 → 下次 pnpm 操作 404"的根修）。
+ *
+ * 修的是什么：`declareProfileDependency` 过去无条件把**磁盘上的版本号**写进 `dependencies`
+ * （注释写着"装到哪版就写哪版"）——对 release 通道 / curl 手铺 / git 装配来的包，npm registry 上
+ * **根本没有这个包**。面板当时显示安装成功，直到任何一次 pnpm 操作按清单解析才炸 `ERR_PNPM_FETCH_404`；
+ * 真机证据：desktop profile 里 `@dsh-external/dsh-graded-mode: 0.0.1-rc1`（npmmirror 与 npmjs 双双 404）。
+ *
+ * 判据（与 lockfile 对账的 planWriteback 同一套语义，绝不两处各判一套）：
+ *   · registry 上**查得到这个包的这个版本** → 写版本号（原行为，回归不变）；
+ *   · 查无此包 / 查无此版本（404）      → 物化到 `<DSH_HOME>/plugin-src/<包名>` 并写 `link:<绝对路径>`；
+ *   · 本次没探到（网络/镜像不可达）      → 不敢替用户猜：仍按旧行为写版本号，但**如实记 note**
+ *     并给出结构化「钉住」建议动作（面板可一键执行），绝不写成"已钉住"。
+ * 返回 { form, spec, note, suggestion }；`spec` 为 null 表示"不要改清单"。
+ */
+async function planDependencySpec({ profileDir, packageName, version, registries = [], probe = null, home = undefined, profile = null }) {
+  const doProbe = typeof probe === 'function' ? probe : probeRegistryPackage
+  const linkable = () => materializePackageForLink(profileDir, packageName, home === undefined ? {} : { home })
+  const asLink = (why) => {
+    const dir = linkable()
+    if (dir === null) {
+      return {
+        form: 'unknown',
+        spec: null,
+        note: `${packageName}：${why}，但 node_modules 里找不到可物化的已装副本 —— 已跳过写回（未改动清单，避免留下指向不存在 npm 版本的裸版本号）`,
+        suggestion: null,
+      }
+    }
+    const link = linkSpecFor(dir)
+    return {
+      form: 'link',
+      spec: link,
+      note: `${packageName}：${why}，清单已按 link: 形式记录（${link}）—— 不经 npm registry 解析、不经 tarball 完整性校验，pnpm 重建 lock 也能装上`,
+      suggestion: null,
+    }
+  }
+  let result = null
+  try {
+    result = await doProbe(packageName, registries, { version })
+  } catch (error) {
+    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 }
+  if (probeFailureKind(result) === 'fetch-404') {
+    return asLink(result?.resolvable === true
+      ? `registry 上没有 ${version} 这个版本（该包只在 GitHub release / 本地有）`
+      : 'npm registry 查无此包（该包只存在于 GitHub release 或本地）')
+  }
+  return {
+    form: 'unknown',
+    spec: version,
+    note: `${packageName}：本次没能确认 registry 可解析性（网络/镜像不可达），先按版本号 ${version} 写入；若该包确实不在 npm 上，请执行下面的「钉住」动作改成 link:（否则下次 pnpm 操作会 404）`,
+    suggestion: suggestedPinAction({ packageName, version, profileDir, profile }),
+  }
+}
+
 /**
  * 安装即声明：把包写进 profile 清单的 `dependencies`。
  *
@@ -89,38 +157,89 @@ async function removeBundleFromManifest(profileDir, bundlePkg) {
  *   · 官方「设置 → 插件」的**已安装**分区只显示清单里声明过的包 —— 我们手铺的包在那里看不见；
  *   · 任何一次 pnpm 操作都会按清单 + lock 重装，未声明的包会被**还原/清掉**；
  *   · 连我们自己的「清理残余」也按「有没有被声明」判孤儿 —— 判据病根也在这里。
- * @returns {{ changed: boolean, version: string|null, reason: string|null, lockSynced: boolean, lockNote: string|null }}
+ *
+ * 2026-09-27 改错（见 planDependencySpec 注释）：写进去的形态**按 registry 可解析性决定**，
+ * 并且写完**总是**做一次 lock 对账（对齐时零成本：reconcileLockfile 只在漂移时才跑 pnpm）。
+ * @returns {{ changed: boolean, version: string|null, spec: string|null, form: string|null, reason: string|null,
+ *             lockSynced: boolean, lockNote: string|null, depNote: string|null, suggested: object|null }}
  */
-async function declareProfileDependency(profileDir, packageName, version = null, { syncLock = true } = {}) {
+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 resolved = typeof version === 'string' && version !== '' ? version : await installedVersionOf(profileDir, packageName)
+  if (resolved === null) return { ...empty, 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 }
   const result = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
-    const resolved = typeof version === 'string' && version !== '' ? version : await installedVersionOf(profileDir, packageName)
-    if (resolved === null) return { changed: false, version: null, reason: '读不到已安装版本', needsLockSync: false }
     const deps = { ...(manifest.dependencies ?? {}) }
-    if (deps[packageName] === resolved) return { changed: false, version: resolved, reason: null, needsLockSync: false }
-    deps[packageName] = resolved
+    if (deps[packageName] === plan.spec) return { changed: false }
+    deps[packageName] = plan.spec
     manifest.dependencies = deps
     await writeManifest(profileDir, manifest)
-    return { changed: true, version: resolved, reason: null, needsLockSync: true }
+    return { changed: true }
   })
-  if (result.needsLockSync !== true || syncLock !== true) return { ...result, lockSynced: false, lockNote: null }
+  const out = { ...empty, changed: result.changed, version: resolved, spec: plan.spec, form: plan.form, depNote: plan.note, suggested: plan.suggestion }
+  if (syncLock !== true) return out
   // **写完清单必须把 lock 拉齐**（2026-09-24 CI 实测）：只写清单不写 lock → 清单/lock 不一致 →
   // 之后任何 pnpm 操作都会硬失败（ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS）。
   // 放在写队列**之外**执行（对账本身会跑 pnpm，不该占着清单写锁）；失败只记 note，不让安装失败。
-  return { ...(await syncLockFor(profileDir, [packageName])), changed: true, version: result.version, reason: null }
+  const synced = await syncLockFor(profileDir, [packageName], { registries, home, profile })
+  return { ...out, ...synced, depNote: joinNotes(plan.note, synced.depNote), suggested: synced.suggested ?? plan.suggestion }
+}
+
+/** 多段说明拼接（空段自动跳过）：文案只做拼接，不覆盖 —— 覆盖就是"谎报"的来源。 */
+function joinNotes(...notes) {
+  const list = notes.filter((note) => typeof note === 'string' && note.trim() !== '')
+  return list.length === 0 ? null : list.join('；')
 }
 
 /** 声明之后同步 lock：用仓库既有的对账通道；失败如实回报，不假装成功。 */
-async function syncLockFor(profileDir, names) {
+async function syncLockFor(profileDir, names, options = {}) {
   try {
-    const { reconcileLockfile } = await import('./selfupdate.js')
-    await reconcileLockfile({ profileDir, packages: names.map((name) => ({ name })) })
-    return { lockSynced: true, lockNote: null }
+    const lock = await reconcileLockfile({
+      profileDir,
+      packages: names.map((name) => ({ name })),
+      registries: Array.isArray(options.registries) ? options.registries : [],
+      ...(options.home === undefined ? {} : { home: options.home }),
+    })
+    return {
+      lockSynced: lock.lockUpdated === true,
+      lockNote: lock.lockNote,
+      depNote: lock.depNote,
+      suggested: Array.isArray(lock.suggestedActions) && lock.suggestedActions.length > 0 ? lock.suggestedActions[0] : null,
+    }
   } catch (error) {
-    return { lockSynced: false, lockNote: `lock 对账失败：${error instanceof Error ? error.message : String(error)}` }
+    return { lockSynced: false, lockNote: `lock 对账失败：${error instanceof Error ? error.message : String(error)}`, depNote: null, suggested: null }
   }
 }
 
+/**
+ * 「钉住」动作的核心（POST /plugin-console/run-suggested 的 pin-dependency 分支）：
+ * 把这个包在清单里钉成 `link:<DSH_HOME>/plugin-src/<包名>`（需要时先把已装副本物化过去）。
+ * 只碰清单，不跑 pnpm（lock/node_modules 的对齐由动作执行器随后显式跑一次 pnpm add 完成）。
+ * 返回 { ok, spec, before, after, changed, dir }；物化不出来时**抛错**（绝不写指向不存在目录的 link:）。
+ */
+async function pinProfileDependency(profileDir, packageName, options = {}) {
+  const { home = undefined } = options
+  const dir = materializePackageForLink(profileDir, packageName, home === undefined ? {} : { home })
+  if (dir === null) throw new Error(`${packageName}：node_modules 里没有可物化的已装副本，无法钉住（已中止，未改动清单）`)
+  const spec = linkSpecFor(dir)
+  const before = await specOf(profileDir, packageName)
+  const changed = await queuedWrite(async () => {
+    const manifest = await readManifest(profileDir)
+    const deps = { ...(manifest.dependencies ?? {}) }
+    if (deps[packageName] === spec) return false
+    deps[packageName] = spec
+    manifest.dependencies = deps
+    await writeManifest(profileDir, manifest)
+    return true
+  })
+  const after = await specOf(profileDir, packageName)
+  return { ok: after === spec, spec, before, after, changed, dir }
+}
+
 /** 卸载即撤销声明。 */
 async function undeclareProfileDependency(profileDir, packageName) {
   return queuedWrite(async () => {
@@ -165,19 +284,26 @@ async function planDependencyBackfill(profileDir) {
   return { candidates, skipped }
 }
 
-/** 执行补声明：逐条写入清单（每条独立走写队列，一条失败不影响其它）。 */
-async function applyDependencyBackfill(profileDir) {
+/** 执行补声明：逐条写入清单（每条独立走写队列，一条失败不影响其它）。
+ * 2026-09-27：补声明同样按 registry 可解析性决定形态（补声明也曾把 release 专属包写成裸版本号 →
+ * 下次 pnpm 操作 404）。`options` 直接透传给 declareProfileDependency（registries/probe 注入）。 */
+async function applyDependencyBackfill(profileDir, options = {}) {
   const { candidates, skipped } = await planDependencyBackfill(profileDir)
   const declared = []
+  const notes = []
+  const suggested = []
   for (const item of candidates) {
-    const result = await declareProfileDependency(profileDir, item.name, item.version)
-    if (result.changed) declared.push({ name: item.name, version: result.version })
+    const result = await declareProfileDependency(profileDir, item.name, item.version, options)
+    if (result.changed) declared.push({ name: item.name, version: result.version, spec: result.spec, form: result.form })
     else skipped.push({ name: item.name, reason: result.reason ?? '无需改动' })
+    if (result.depNote !== null) notes.push(result.depNote)
+    if (result.suggested !== null) suggested.push(result.suggested)
   }
-  return { declared, skipped }
+  return { declared, skipped, depNote: notes.length === 0 ? null : notes.join('；'), suggestedActions: suggested }
 }
 
 export {
   DEFAULT_BUNDLES, addBundleToManifest, applyDependencyBackfill, declareProfileDependency,
-  installedVersionOf, planDependencyBackfill, removeBundleFromManifest, syncLockFor, undeclareProfileDependency,
+  installedVersionOf, planDependencyBackfill, planDependencySpec, pinProfileDependency, removeBundleFromManifest,
+  specOf, syncLockFor, undeclareProfileDependency,
 }

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

@@ -0,0 +1,208 @@
+// L1 · domain —— plugin-actions.js（**结构化建议动作的执行器**：白名单动作 + 服务端自拼 argv）
+//
+// 为什么单开一个模块（2026-09-27 加法 + 改错，用户明确要求「可执行的钉住/修复动作框」）：
+//   · 面板过去只给一句文案（"要钉住请执行：dsh plugin … add …"），用户得自己开终端抄命令，
+//     抄错一个字符就是另一种事故；而**让面板自由执行命令**又是绝不能开的口子。
+//   · 所以接口只接受**结构化的动作类型 + 目标**（`{ action, packageName, version, profile }`），
+//     命令行的每一个参数都由本模块的 ACTION_SPECS 自己拼 —— 客户端**没有任何位置**能传命令字符串。
+//     出现 command/cmd/argv/args/exec/shell/script/run/spawn/bin 任一字段即 400（配套测试钉死）。
+//   · `profile` 字段**只作回显**：服务端一律按当前实例的 profile 目录施工（绝不按请求体挑目录）。
+//
+// 动作表（唯一真源，新增动作必须同时进这张表与测试）：
+//   · pin-dependency：把清单里的该包钉成 `link:<DSH_HOME>/plugin-src/<包名>`，再跑一次
+//     `pnpm add <link:…>` 把 lock / node_modules 对齐（argv 由 infra/exec.js#pnpmAddArgs 产出）；
+//   · reconcile-lock：只重写 pnpm-lock.yaml，复用 lockfile-health 的 repair（argv 由 repairArgsFor
+//     唯一产出，**不带**任何绕过供应链闸的开关）。
+//
+// 供应链闸的一次性放宽（写清代价，绝不静默）：pnpm 11 的 `minimumReleaseAge` 默认 24h，
+// 本控制台自己刚发的版本 (<24h) 会让**任何** lockfile 校验失败 —— 连"把本地 link: 记进 lock"都做不成。
+// 处理：第一次**原样跑**（不带任何放宽）；只有当失败原因**确定**是 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION
+// 时，才为**这一条命令**追加 `--config.minimumReleaseAge=0` 重试一次，并在结果里显式回报
+// `relaxedReleaseAge: true`（面板原样展示）。绝不写进任何配置文件、绝不用它绕过错配的包名/版本。
+//
+// 分层：L1 domain —— 不认识 cordis ctx，IO/执行器一律可注入（便于离线单测）。
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { NPM_NAME_RE } from './dep-source.js'
+import { runLockfileRepair } from './lockfile-health.js'
+import { pinProfileDependency, specOf } from './manifest.js'
+import { lockVersion } from './selfupdate.js'
+import { buildPnpmEnv, pnpmAddArgs, runPnpmWithFallback } from '../infra/exec.js'
+
+const DEFAULT_REGISTRY = 'https://registry.npmmirror.com'
+/** 动作白名单（客户端只能给这些 kind；执行分支与 argv 全在服务端）。 */
+const ACTION_KINDS = ['pin-dependency', 'reconcile-lock']
+/** 一旦出现这些键就整条拒绝：本接口不存在"传命令"的位置。 */
+const COMMAND_KEYS = ['command', 'cmd', 'argv', 'args', 'exec', 'execute', 'shell', 'script', 'run', 'spawn', 'bin', 'shellCommand']
+const OUTPUT_LIMIT = 4000
+
+/** 校验并翻译成结构化请求。返回 { ok, error, status, action, packageName, version, profile }。 */
+function parseActionRequest(body) {
+  const raw = body !== null && typeof body === 'object' ? body : {}
+  for (const key of COMMAND_KEYS) {
+    if (key in raw) {
+      return { ok: false, status: 400, error: `不接受客户端传来的命令字符串（字段 ${key} 非法）：本接口只认结构化动作，命令行由服务端自己拼` }
+    }
+  }
+  const action = typeof raw.action === 'string' ? raw.action.trim() : ''
+  if (action === '') return { ok: false, status: 400, error: '缺少 action（只允许 pin-dependency / reconcile-lock）' }
+  if (!ACTION_KINDS.includes(action)) {
+    return { ok: false, status: 400, error: `未知动作 ${action}（只允许 ${ACTION_KINDS.join(' / ')}）` }
+  }
+  const packageName = typeof raw.packageName === 'string' ? raw.packageName.trim() : ''
+  if (action === 'pin-dependency') {
+    if (packageName === '') return { ok: false, status: 400, error: 'pin-dependency 需要 packageName' }
+    if (packageName.length > 214 || !NPM_NAME_RE.test(packageName)) return { ok: false, status: 400, error: 'packageName 不是合法的 npm 包名' }
+  }
+  const version = typeof raw.version === 'string' && raw.version.length <= 120 ? raw.version : null
+  const profile = typeof raw.profile === 'string' && raw.profile.length <= 64 ? raw.profile : null
+  return { ok: true, error: null, status: 200, action, packageName: packageName === '' ? null : packageName, version, profile }
+}
+
+/** 该包是否属于当前 profile（已声明在 dependencies / devDependencies / optionalDependencies 或
+ *  `dsh.profile.bundles` 里）。**安全边界**：动作只对该 profile 自己认得的包生效，
+ *  请求体说了不算（包名由客户端给，但"这个包属不属于这个 profile"必须服务端自己读盘判定）。 */
+function isProfilePackage(profileDir, packageName) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'))
+    for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+      if (manifest?.[section] !== null && typeof manifest?.[section] === 'object' && packageName in manifest[section]) return true
+    }
+    const bundles = manifest?.dsh?.profile?.bundles
+    return Array.isArray(bundles) && bundles.includes(packageName)
+  } catch {
+    return false
+  }
+}
+
+/** 目标包是否已落在该 profile 的 node_modules 里（pin 的物理前提）。 */
+function isInstalled(profileDir, packageName) {
+  return existsSync(join(profileDir, 'node_modules', ...String(packageName).split('/'), 'package.json'))
+}
+
+function tail(text, limit = OUTPUT_LIMIT) {
+  const s = typeof text === 'string' ? text : String(text ?? '')
+  return s.length <= limit ? s : s.slice(-limit)
+}
+
+/** 供应链闸判据（只认 pnpm 自己的错误码/文案；认不出就绝不放宽）。 */
+function isReleaseAgeBlock(message) {
+  return /ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|minimumReleaseAge/iu.test(String(message ?? ''))
+}
+
+/** 跑一次 pnpm（原样），必要时**只对这一条命令**放宽供应链闸并如实标记。
+ *  返回 { ok, exitCode, stdout, stderr, relaxedReleaseAge, error }。 */
+async function runAddWithReleaseAgeRetry({ profileDir, spec, registry, runAdd, timeoutMs = 180000 }) {
+  const argv = pnpmAddArgs(spec, registry)
+  const execOpts = { cwd: profileDir, timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024, env: buildPnpmEnv(registry) }
+  const attempt = async (args) => {
+    try {
+      const out = await runAdd(args, { execOpts })
+      return { ok: true, exitCode: 0, stdout: tail(out?.stdout), stderr: tail(out?.stderr), error: null }
+    } catch (error) {
+      return {
+        ok: false,
+        exitCode: Number.isInteger(error?.code) ? error.code : 1,
+        stdout: tail(error?.stdout),
+        stderr: tail(error?.stderr ?? error?.message ?? String(error)),
+        error: error instanceof Error ? error : new Error(String(error)),
+      }
+    }
+  }
+  const first = await attempt(argv)
+  // 放宽条件**必须同时**成立：第一次真的失败了，且失败原因确定是供应链闸（文案/错误码认得出）
+  const blocked = !first.ok && (isReleaseAgeBlock(first.stderr) || isReleaseAgeBlock(String(first.error?.message ?? '')))
+  if (!blocked) return { ...first, relaxedReleaseAge: false }
+  const retried = await attempt([...argv, '--config.minimumReleaseAge=0'])
+  return { ...retried, relaxedReleaseAge: true }
+}
+
+/**
+ * 执行一个结构化建议动作（**唯一入口**，路由只做鉴权/取 profileDir）。
+ * 返回统一形状：{ ok, status, action, packageName, exitCode, command, stdout, stderr, relaxedReleaseAge,
+ *                manifest: { before, after, changed, pinned }, lock: { entry, synced }, notes, reason, hint, detail }
+ * `ok` = 目标状态**真的**达成（pin：清单是 link: **且** lock 里也有该 link 条目）；只达成一半时
+ * `partial: true` 并如实说明哪一半没成 —— 绝不把"写了一半"报成成功。
+ */
+async function runSuggestedAction({ body, profileDir, registries = [], deps = {} } = {}) {
+  const parsed = parseActionRequest(body)
+  if (parsed.ok !== true) return { ok: false, status: parsed.status, action: null, error: parsed.error }
+  const registry = (Array.isArray(registries) ? registries : []).find((r) => typeof r === 'string' && r.trim() !== '') ?? DEFAULT_REGISTRY
+  const runAdd = typeof deps.runAdd === 'function' ? deps.runAdd : runPnpmWithFallback
+  const pin = typeof deps.pin === 'function' ? deps.pin : pinProfileDependency
+  const repair = typeof deps.repair === 'function' ? deps.repair : runLockfileRepair
+  const base = {
+    ok: false, status: 200, action: parsed.action, packageName: parsed.packageName, profile: parsed.profile,
+    registry, exitCode: null, command: null, stdout: '', stderr: '', relaxedReleaseAge: false,
+    manifest: null, lock: null, notes: [], reason: null, hint: null, detail: null,
+  }
+  if (parsed.action === 'reconcile-lock') {
+    const view = await repair({ profileDir, registries: Array.isArray(registries) && registries.length > 0 ? registries : [registry] })
+    const done = view?.action === 'repaired' || view?.action === 'noop'
+    return {
+      ...base,
+      ok: done,
+      exitCode: view?.action === 'failed' ? 1 : 0,
+      command: view?.command ?? null,
+      stderr: tail(view?.stderrTail),
+      notes: [view?.reason].filter((n) => typeof n === 'string'),
+      reason: view?.reason ?? null,
+      hint: view?.hint ?? null,
+      detail: view ?? null,
+      lock: { entry: null, synced: view?.action === 'repaired' || view?.action === 'noop' },
+    }
+  }
+  // pin-dependency
+  if (!isProfilePackage(profileDir, parsed.packageName)) {
+    return { ...base, ok: false, status: 400, error: `${parsed.packageName} 不在本 profile 的清单（dependencies / dsh.profile.bundles）里，拒绝改动` }
+  }
+  if (!isInstalled(profileDir, parsed.packageName)) {
+    return { ...base, ok: false, status: 400, error: `${parsed.packageName} 没有装在当前 profile 的 node_modules 里，无法钉住（先安装）` }
+  }
+  const before = await specOf(profileDir, parsed.packageName)
+  let pinned = null
+  try {
+    pinned = await pin(profileDir, parsed.packageName, {})
+  } catch (error) {
+    return { ...base, ok: false, status: 200, manifest: { before, after: before, changed: false, pinned: false }, reason: error instanceof Error ? error.message : String(error) }
+  }
+  const argv = pnpmAddArgs(pinned.spec, registry)
+  const run = await runAddWithReleaseAgeRetry({ profileDir, spec: pinned.spec, registry, runAdd, timeoutMs: deps.timeoutMs })
+  const after = await specOf(profileDir, parsed.packageName)
+  const entry = lockVersion(profileDir, parsed.packageName)
+  const lockSynced = typeof entry === 'string' && entry.startsWith('link:')
+  // "钉住了"的判据：清单里该包**是 link: 形式**（不要求与计划的绝对路径逐字相同 —— pnpm 自己也可能把它
+  // 规范化成相对路径，那同样是"不经 registry 解析"的来源型 spec，判据见 domain/dep-source.js#linkSpecIsIntact）
+  const pinnedOk = typeof after === 'string' && after.startsWith('link:')
+  const manifests = { before, after, changed: before !== after, planned: pinned.spec, pinned: pinnedOk }
+  const notes = []
+  if (run.relaxedReleaseAge) notes.push('本机 pnpm 的 24h 供应链闸（minimumReleaseAge）拦下了这次 lock 校验，已**仅对这一条命令**追加 --config.minimumReleaseAge=0 重试一次（有安全代价，未写进任何配置文件）。')
+  // 三种"pnpm 那一步没跑成"的形态都如实记一句（2026-09-27 真机桌面端实例实测：corepack 在该进程里
+  // 解析不到 → pnpm 那一步失败，而清单/lock 其实已达成目标；只留 stderr 会让用户自己猜发生了什么）
+  if (!run.ok) {
+    notes.push(manifests.pinned
+      ? (lockSynced
+        ? `pnpm 那一步没跑完（exitCode=${run.exitCode}，原始输出见 stderr）：清单与 lock 已经是 link:，目标状态已达成。`
+        : `清单已钉住（下次 pnpm 操作不会再 404），但 lock 没能对齐（exitCode=${run.exitCode}）：见 stderr。`)
+      : `清单与 lock 都没改成功（exitCode=${run.exitCode}）：见 stderr（原始输出已原样回显）。`)
+  }
+  return {
+    ...base,
+    // 只有"清单真的是 link: **且** lock 里也有这条 link"才算成功；只成一半时 partial=true 并如实说明
+    ok: manifests.pinned && lockSynced,
+    partial: manifests.pinned && !lockSynced,
+    exitCode: run.exitCode,
+    command: `pnpm ${argv.join(' ')}`,
+    stdout: run.stdout,
+    stderr: run.stderr,
+    relaxedReleaseAge: run.relaxedReleaseAge,
+    manifest: manifests,
+    lock: { entry: entry ?? null, synced: lockSynced },
+    notes,
+    reason: manifests.pinned
+      ? (lockSynced ? `${parsed.packageName} 已钉住：清单与 pnpm-lock.yaml 都指向 link:${pinned.dir}` : `${parsed.packageName} 的清单已钉住，lock 未对齐`)
+      : `${parsed.packageName} 的清单写回未生效（实际是 ${after ?? '（无该条目）'}）`,
+  }
+}
+
+export { ACTION_KINDS, COMMAND_KEYS, DEFAULT_REGISTRY, OUTPUT_LIMIT, isProfilePackage, isReleaseAgeBlock, parseActionRequest, runAddWithReleaseAgeRetry, runSuggestedAction }

package/lib/server/domain/selfupdate.js

@@ -12,7 +12,7 @@
 //            ③ 回读核实 readInstalledVersion / lockVersion；都不匹配才回落手铺文件，且**必须**带 lockNote 警告。
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { linkSpecFor, linkSpecIsIntact, materializePackageForLink, probeRegistryPackage } from './dep-source.js'
+import { linkSpecFor, linkSpecIsIntact, materializePackageForLink, probeRegistryPackage, suggestedPinAction } from './dep-source.js'
 import { pnpmInstall } from './install.js'
 import { fetchJsonUrl } from '../infra/http.js'
 import { runPnpmWithFallback } from '../infra/exec.js'
@@ -239,36 +239,46 @@ async function reconcileLockfile({ profileDir, packageName = null, packages = nu
   }))
   const sourcePinned = (v) => typeof v === 'string' && SOURCE_PINNED_RE.test(v.trim())
   const urlPinned = (v) => typeof v === 'string' && /^https?:/u.test(v.trim())
-  /** 缺陷②指纹：manifest 声明裸版本号、lock 却把该包解析到一个 URL —— pnpm 静默改写留下的状态。 */
-  const misrecorded = (r) => typeof r.spec === 'string' && EXACT_VERSION_RE.test(r.spec.trim()) && urlPinned(r.lock)
+  /** 缺陷②指纹：manifest 声明裸版本号、lock 却把该包解析到一个 URL —— pnpm 静默改写留下的状态。
+   *  2026-09-27 扩展（真机证据，desktop profile）：**不止 URL** —— `dependencies` 写 `0.0.1-rc1`
+   *  而 lock 的 importer 把同一个包钉在 `link:…`，同样是"两处对不上"的静默遗留态（清单里那个
+   *  裸版本号在 registry 上根本不存在，lock 一重建就 ERR_PNPM_FETCH_404）。来源一律算指纹。 */
+  const misrecorded = (r) => typeof r.spec === 'string' && EXACT_VERSION_RE.test(r.spec.trim()) && sourcePinned(r.lock)
   /** manifest 里仍是 tarball URL：虽然 lock 能解析，但 pnpm 10 重写 lock 会丢 integrity（实测），
    *  必须**主动**规整成 link: 形式 —— 否则「删 lock / 清 node_modules / 换机」就装不回来。 */
   const urlSpec = (r) => typeof r.spec === 'string' && /^https?:/u.test(r.spec.trim())
   /** 来源钉住的包没有「版本号相等」可比：link 依赖要看链接是否**真的**还在（release 通道更新会把
    *  node_modules/<包名> 换成真实目录，此时必须重新物化 + 重放 link:，否则下次 pnpm 操作会还原版本）；
-   *  其余来源（git+/file:/URL）只要有解析且包装着即视为对齐。 */
+   *  其余来源（git+/file:/URL）只要有解析且包装着即视为对齐。
+   *  ★ 2026-09-27 改错：link: 依赖还必须**在 lock 里有那条 link 条目**才算对齐。旧判据只看"链接还在"，
+   *  于是「清单是 link:、node_modules 是链接、但 lock 里根本没有这个依赖」也被判成对齐 → `lockUpdated`
+   *  报 true（谎报"已写进 lock"），而 lock 一重建就丢依赖。真机复现路径：先手动把 node_modules 换成指向
+   *  plugin-src 的链接（或上一次对账刚建好链接），再走一次声明 —— pnpm add 根本不会被调用。 */
   const aligned = (r) => {
     if (r.installed === null) return false
-    if (typeof r.spec === 'string' && r.spec.startsWith('link:')) return linkSpecIsIntact(profileDir, r.name, r.spec)
+    if (typeof r.spec === 'string' && r.spec.startsWith('link:')) {
+      return linkSpecIsIntact(profileDir, r.name, r.spec)
+        && typeof r.lock === 'string' && r.lock.trim().startsWith('link:')
+    }
     return r.installed === r.lock || sourcePinned(r.lock)
   }
   const driftedOf = (rows) => rows.filter((r) => r.installed === null || !aligned(r) || misrecorded(r) || urlSpec(r))
 
   const depNotes = []
-  // 物化 + link: 计划（registry 查无此包时唯一安全的写回形式）
+  // 物化 + link: 计划（registry 查无此包时唯一安全的写回形式）。
+  // ★ 2026-09-27 改错：这里**只产出"打算写什么"和"为什么"**，不再抢先断言"已按 link: 形式记录依赖"——
+  //   旧版在 pnpm add 之前就把这句写进 depNote，于是"写回失败/被后一步覆盖"时面板仍然报"已钉住"，
+  //   而磁盘上留着的是裸版本号（真机 desktop profile 的实际状态）。最终文案一律在写回之后**读回真实值**再生成。
   const linkPlan = (row, why) => {
     const dir = materializePackageForLink(profileDir, row.name, home === null ? {} : { home })
     if (dir === null) {
       return {
         spec: null,
+        reason: why,
         note: `${row.name}：${why}，但 node_modules 里找不到可物化的已装副本 —— 已跳过 lock 对齐（**未改动 package.json**，避免留下指向不存在 npm 版本的裸版本号）`,
       }
     }
-    const link = linkSpecFor(dir)
-    return {
-      spec: link,
-      note: `${row.name}：${why}，已按 link: 形式记录依赖（${link}）—— 不经 npm registry 解析、不经 tarball 完整性校验，pnpm 重建 lock 也能装上`,
-    }
+    return { spec: linkSpecFor(dir), reason: why, note: null }
   }
   /** 决定单个漂移包该以什么 spec 写回。spec=null 表示跳过（不碰 manifest）。 */
   const planWriteback = async (row) => {
@@ -281,19 +291,25 @@ async function reconcileLockfile({ profileDir, packageName = null, packages = nu
       // link: 规格：链接可能已被 release/curl 通道的"先删再铺"打断 → 先把新副本刷进 plugin-src 再重放
       if (spec.trim().startsWith('link:')) {
         const dir = materializePackageForLink(profileDir, name, home === null ? {} : { home })
-        return { spec: dir === null ? spec.trim() : linkSpecFor(dir), note: null }
+        return { spec: dir === null ? spec.trim() : linkSpecFor(dir), reason: null, note: null }
       }
-      return { spec: spec.trim(), note: null } // git+ / file: / 别名 原样重放（幂等，来源不变）
+      return { spec: spec.trim(), reason: null, note: null } // git+ / file: / 别名 原样重放（幂等，来源不变）
+    }
+    // ①′ 清单写裸版本号、lock 却把该包钉在**来源**上（URL/link/git）：pnpm 静默改写的遗留态。
+    //     按 lock 的来源重放（来源绝不降级成版本号），而不是"registry 能解析就换回版本号"——
+    //     后者等于把用户/前一步刻意钉住的来源丢掉，且 lock 重建时会指向 registry 上并不存在的版本。
+    if (misrecorded(row) && typeof row.lock === 'string' && row.lock.trim().startsWith('link:')) {
+      return linkPlan(row, `pnpm-lock.yaml 里把该包钉在 link:（${row.lock.trim()}）而清单里是版本号 ${spec.trim()} —— 两处对不上，按来源重放`)
     }
     // ② dist-tag（latest/next…）：registry 来源，但**保留标签**（钉成版本号会悄悄失去升级语义）
     if (typeof spec === 'string' && DIST_TAG_RE.test(spec.trim())) {
       const probeTag = await probeRegistryPackage(name, registries, { fetchJson })
-      if (probeTag.resolvable) return { spec: `${name}@${spec.trim()}`, note: null }
+      if (probeTag.resolvable) return { spec: `${name}@${spec.trim()}`, reason: null, note: null }
       return linkPlan(row, 'npm registry 查无此包（该包只存在于 GitHub release）')
     }
     // ③ 版本号或没有条目 → 先探 registry：**这个版本**可解析才允许写版本号
     const probe = await probeRegistryPackage(name, registries, { version: installed, fetchJson })
-    if (probe.resolvable && probe.hasVersion) return { spec: `${name}@${installed}`, note: null }
+    if (probe.resolvable && probe.hasVersion) return { spec: `${name}@${installed}`, reason: null, note: null }
     // ④ registry 查无此包（或查无此版本）→ 只存在于 GitHub release → 物化 + link:
     return linkPlan(row, probe.resolvable ? `registry 上没有 ${installed} 这个版本` : 'npm registry 查无此包（该包只存在于 GitHub release）')
   }
@@ -302,13 +318,14 @@ async function reconcileLockfile({ profileDir, packageName = null, packages = nu
   let drifted = driftedOf(rows)
   const errors = []
   let method = null
+  const planned = []
   if (drifted.length > 0) {
     // 只对"能读到实际版本"的包做对齐；读不到的（目录都没有）无法对账，留给 lockNote
     const specs = []
     for (const row of drifted) {
       if (row.installed === null) continue
       const plan = await planWriteback(row)
-      if (plan.note !== null) depNotes.push(plan.note)
+      planned.push({ name: row.name, installed: row.installed, spec: plan.spec, reason: plan.reason ?? null, note: plan.note ?? null })
       if (plan.spec !== null) specs.push(plan.spec)
     }
     if (specs.length > 0) {
@@ -322,6 +339,25 @@ async function reconcileLockfile({ profileDir, packageName = null, packages = nu
     rows = snap()
     drifted = driftedOf(rows)
   }
+  // ★ 文案一律按**实际写入形态**生成（读回清单再描述）——"计划写 link:"与"清单里真是 link:"
+  //   是两件事：pnpm add 失败、或后续某一步又把 spec 覆盖成版本号时，绝不能报"已钉住"。
+  const suggestedActions = []
+  for (const item of planned) {
+    const actual = profileSpec(profileDir, item.name)
+    if (item.spec === null) {
+      if (item.note !== null) depNotes.push(item.note)
+      continue
+    }
+    if (actual === item.spec) {
+      if (item.spec.startsWith('link:') && item.reason !== null) {
+        depNotes.push(`${item.name}：${item.reason}，已按 link: 形式记录依赖（${actual}）—— 不经 npm registry 解析、不经 tarball 完整性校验，pnpm 重建 lock 也能装上`)
+      }
+      continue
+    }
+    const why = `${item.name}：${item.reason ?? '该包在 npm registry 上解析不到'}；计划写入 ${item.spec}，但清单里实际是 ${actual ?? '（没有这个条目）'} —— 写回**未生效**${errors.length > 0 ? `（${errors.join('；')}）` : ''}`
+    depNotes.push(`${why}。请执行「钉住」动作或手动执行：${command(item.name, item.installed)}`)
+    suggestedActions.push(suggestedPinAction({ packageName: item.name, version: item.installed, profileDir, reason: why }))
+  }
   const lockUpdated = drifted.length === 0
   return {
     method,
@@ -333,8 +369,11 @@ async function reconcileLockfile({ profileDir, packageName = null, packages = nu
     lockNote: lockUpdated
       ? null
       : `${drifted.length} 个包没写进 pnpm-lock.yaml（${drifted.map((r) => `${r.name}：装了 ${r.installed ?? '未知'}／lock 里是 ${r.lock ?? '未记录'}`).join('；')}）：之后任何 pnpm 操作（开关插件、dsh plugin add/remove）都可能把它们还原。要钉住请执行：${command(drifted[0].name, drifted[0].installed)}`,
-    // 非常规来源（link:）写回时的**用户可见**说明：绝不静默（缺陷②的隐蔽性正是"装完看不出问题"）
+    // 非常规来源（link:）写回时的**用户可见**说明：绝不静默（缺陷②的隐蔽性正是"装完看不出问题"）。
+    // 文案由上面的"读回真实值"步骤产出，因此永远不会出现"面板说已钉住、磁盘上仍是版本号"。
     depNote: depNotes.length > 0 ? depNotes.join('；') : null,
+    // 结构化建议动作（2026-09-27 加法）：面板可一键「执行」（服务端只认白名单动作，argv 自己拼）
+    suggestedActions,
     command: drifted.length > 0 ? command(drifted[0].name, drifted[0].installed) : command(rows[0]?.name ?? '', rows[0]?.installed ?? null),
     errors,
   }

package/lib/server/domain/sources.js

@@ -233,6 +233,17 @@ function orderedRegistries(sources) {
   return [...list.filter((r) => r.primary), ...list.filter((r) => !r.primary)].map((r) => r.url)
 }
 
+/** 主源优先的 registry 列表（2026-09-27 加法）：所有"要探测/解析 registry"的通道共用一个口径
+ *  （用户可在「源管理」里改配置；读不到配置时退回镜像源，绝不返回空数组——空数组会让探测静默退化）。 */
+function preferredRegistries() {
+  try {
+    const list = orderedRegistries(readSources())
+    return Array.isArray(list) && list.length > 0 ? list : ['https://registry.npmmirror.com']
+  } catch {
+    return ['https://registry.npmmirror.com']
+  }
+}
+
 function createGiteeOAuthState() {
   const state = globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
   const now = Date.now()
@@ -346,4 +357,4 @@ const GITEE_AUTH_URL = 'https://gitee.com/oauth/authorize'
 
 const GITEE_TOKEN_URL = 'https://gitee.com/oauth/token'
 const DEFAULT_SEARCH = 'dsh-plugin'
-export { readSources, writeSources, maskSources, readSourceSecrets, writeSourceSecrets, isAllowedSourceUrl, isAllowedGitSourceUrl, readGiteeConfig, giteeStatusView, orderedRegistries, createGiteeOAuthState, consumeGiteeOAuthState, DEFAULT_SOURCES, GITEE_OAUTH_STATES, gitCloneUrls, gitCloneCandidates, GITEE_AUTH_URL, GITEE_TOKEN_URL, DEFAULT_SEARCH }
+export { readSources, writeSources, maskSources, readSourceSecrets, writeSourceSecrets, isAllowedSourceUrl, isAllowedGitSourceUrl, readGiteeConfig, giteeStatusView, orderedRegistries, preferredRegistries, createGiteeOAuthState, consumeGiteeOAuthState, DEFAULT_SOURCES, GITEE_OAUTH_STATES, gitCloneUrls, gitCloneCandidates, GITEE_AUTH_URL, GITEE_TOKEN_URL, DEFAULT_SEARCH }

package/lib/server/routes/actions.js

@@ -0,0 +1,32 @@
+// L2 · routes —— 结构化建议动作（POST /plugin-console/run-suggested，2026-09-27 加法）
+//
+// 为什么要有它：安装结果卡片会下发 `job.suggestedAction = { kind, label, command, payload }`
+// （见 domain/install-job.js 与 domain/dep-source.js#suggestedPinAction），用户要求能**直接点执行**，
+// 而不是自己抄一条命令去终端跑。
+//
+// 安全语义（写死，配套测试 tests/test-plugin-actions.mjs 与 tests/test-route-inventory.mjs）：
+//   · 请求体只认 `{ action, packageName, version, profile }`；`command`/`argv`/`shell`… 任一出现即 400，
+//     命令行**全部**由 domain/plugin-actions.js 的白名单动作自己拼；
+//   · `profile` 只作回显 —— profileDir 一律取当前实例（profileDirOf）的目录，**绝不**按请求体挑目录；
+//   · 动作只对"本 profile 自己清单里的包"生效（服务端读盘判定，不信客户端）。
+import { runSuggestedAction } from '../domain/plugin-actions.js'
+import { preferredRegistries } from '../domain/sources.js'
+import { sendError, sendJson } from '../infra/httpd.js'
+import { profileDirOf } from '../infra/paths.js'
+
+async function routeRunSuggested(req, res, rc) {
+  const profileDir = profileDirOf(rc.ctx)
+  if (typeof profileDir !== 'string' || profileDir === '') {
+    sendError(res, 400, '无法定位 profile 目录（读不到 cordis.yml 的 include 条目）')
+    return
+  }
+  const result = await runSuggestedAction({ body: rc.body, profileDir, registries: preferredRegistries() })
+  if (result.ok === false && result.status === 400) {
+    sendError(res, 400, result.error)
+    return
+  }
+  const { status, error, ...view } = result
+  sendJson(res, 200, { ok: result.ok === true, ...view, ...(typeof error === 'string' ? { error } : {}) })
+}
+
+export { routeRunSuggested }

package/lib/server/routes/compat.js

@@ -15,6 +15,7 @@ import { dirname } from 'node:path'
 import { compareFingerprint, computeFingerprint, readCompatMode, readFingerprint, readRollbackRecord, stampFingerprint, writeCompatMode } from '../domain/compat-state.js'
 import { currentFrameworkVersion } from '../domain/framework.js'
 import { applyDependencyBackfill, planDependencyBackfill } from '../domain/manifest.js'
+import { preferredRegistries } from '../domain/sources.js'
 import { reconcileLockfile } from '../domain/selfupdate.js'
 import { sendError, sendJson } from '../infra/httpd.js'
 import { baseDirOf, profileDirOf, resolvePackageJson } from '../infra/paths.js'
@@ -93,16 +94,26 @@ async function routeDeclareInstalled(req, res, rc) {
   const profileDir = profileDirOf(rc.ctx)
   try {
     if (mode === 'apply') {
-      const result = await applyDependencyBackfill(profileDir)
+      // 2026-09-27：补声明同样按 registry 可解析性决定写回形态（非 registry 包写 link:），
+      // 且必须传**用户配置的** registry 列表 —— 否则探测只用默认源，自定义源/备源形同虚设。
+      const registries = preferredRegistries()
+      const result = await applyDependencyBackfill(profileDir, { registries })
       // 关键：只写清单不写 lock → 之后任何 pnpm 操作都会因清单/lock 不一致失败（2026-09-24 CI 实测）
       let lockNote = null
-      try { await reconcileLockfile({ profileDir }) } catch (error) { lockNote = `lock 对账失败：${error instanceof Error ? error.message : String(error)}` }
+      let suggestedAction = Array.isArray(result.suggestedActions) && result.suggestedActions.length > 0 ? result.suggestedActions[0] : null
+      try {
+        const lock = await reconcileLockfile({ profileDir, registries })
+        if (lock.lockNote !== null) lockNote = lock.lockNote
+        if (Array.isArray(lock.suggestedActions) && lock.suggestedActions.length > 0) suggestedAction = lock.suggestedActions[0]
+      } catch (error) { lockNote = `lock 对账失败：${error instanceof Error ? error.message : String(error)}` }
       sendJson(res, 200, {
         ok: true,
         mode,
         declared: result.declared,
         skipped: result.skipped,
         lockNote,
+        depNote: result.depNote ?? null,
+        suggestedAction,
         note: result.declared.length === 0
           ? '没有需要补声明的插件'
           : `已补声明 ${result.declared.length} 项 —— 它们现在会出现在官方/第三方插件页的「已安装」里，也不会再被 pnpm 还原`,

package/lib/server/routes/index.js

@@ -13,6 +13,7 @@ import { DEFAULT_SEARCH } from '../domain/sources.js'
 import { runSuiteInstallJob } from '../domain/suite.js'
 import { readBody, sendError } from '../infra/httpd.js'
 import { routeAiConsent, routeAiEmpowerCancel, routeAiEmpowerList, routeAiEmpowerPlan, routeAiEmpowerRun, routeAiEmpowerStatus } from './ai.js'
+import { routeRunSuggested } from './actions.js'
 import { routeComponentAutostart, routeComponentStart, routeComponentStatus, routeComponentStop, routeComponents, routeRepoClone, routeRepoLandConfig, routeRepoList, routeRepoOpen, routeRepoRemove } from './components.js'
 import { routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled } from './compat.js'
 import { routeFrameworkUpgrade } from './framework-upgrade.js'
@@ -132,6 +133,8 @@ const ROUTES = [
   // 依赖锁体检与重建（2026-09-27 加法）：check 纯只读；repair 必须由用户显式调用
   { methods: ['POST'], path: `${ROUTE_PREFIX}/lockfile-check`, handler: routeLockfileCheck },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/lockfile-repair`, handler: routeLockfileRepair },
+  // 结构化建议动作（2026-09-27 加法）：只认白名单动作类型，argv 由服务端自拼（绝不接受命令字符串）
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/run-suggested`, handler: routeRunSuggested },
 
 ]
 

package/lib/server/routes/install.js

@@ -114,7 +114,14 @@ async function routeInstallStatus(req, res, rc) {
       sendError(res, 404, '没有这个安装任务')
       return
     }
-    sendJson(res, 200, { ok: true, ...installJobView(job) })
+    sendJson(res, 200, {
+      ok: true,
+      ...installJobView(job),
+      // 结构化建议动作（2026-09-27 加法，向后兼容）：老客户端忽略该字段；
+      // 新客户端在安装结果卡片里渲染「执行 / 复制」小框（POST /plugin-console/run-suggested）。
+      // 放这里而不是 install.js#installJobView：那个模块已贴着 600 行架构棘轮（见 test-architecture-guard.mjs）。
+      suggestedAction: job.suggestedAction ?? null,
+    })
     return
 }
 

package/package.json

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