@noob-stupid/dsh-plugin-console 0.5.18 → 0.5.20

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, 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

@@ -21,10 +21,9 @@ import { deriveEntryId, listEntries } from './runtime.js'
 import { detectSkillRepo, runSkillInstallJob } from './skills.js'
 import { orderedRegistries, readSources } from './sources.js'
 import { reconcileLockfile } from './selfupdate.js'
-import { probeGitmodules, resolveInstallKind, runSuiteInstallJob } from './suite.js'
+import { fetchRepoMeta, runSuiteInstallJob, shouldRunSuiteInstall } from './suite.js'
 import { buildPnpmEnv, execFileAsync, runPnpmWithFallback } from '../infra/exec.js'
 import { cleanupStalePackageDir, startTrashCleanup, trashScanRoots } from '../infra/fsx.js'
-import { GITHUB_API, META_BUDGET_MS, curlJson, githubJson } from '../infra/http.js'
 import { findPatchPath, packageNameOf, resolvePackageJson } from '../infra/paths.js'
 
 /** release 通道的候选预算（issue #3）：release 通道现在按包名反查发布仓库，**每个候选**至少一次
@@ -215,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 规则
@@ -242,10 +249,11 @@ async function runInstallJob(job, ports, deps = {}) {
       }
     }
     if (candidates.length === 0) {
-      // 套装兜底：submodule 聚合仓库（根 .gitmodules 内容校验通过）→ 自动转套装安装，不依赖前端标记。
-      // 判据是**内容**（resolveInstallKind），不是"探测非 null"：后者会把代理/CDN 对不存在文件回的
-      // 2xx 空 body、垃圾页当成套装（2026-09-19 用户反馈的「未找到 .gitmodules」事故根因）。
-      if (resolveInstallKind(job.kind, await probeGitmodules(job.repo)) === 'suite') {
+      // 套装判定（0.5.19 改错，唯一入口在 suite.js 的 shouldRunSuiteInstall）：**先看根包是否已发布**，
+      // 再按 .gitmodules 的**内容**判是否套装（不是"探测非 null"：代理/CDN 对不存在的文件会回 2xx 空 body、
+      // 垃圾页，2026-09-19「未找到 .gitmodules」事故的口径不变）。根包/子包任一已发布到 registry 时优先
+      // 插件通道 —— 真机 dsh-web：429 MB 套装克隆 vs 5.97 MB 的子包 @linxin666/dsh-web-all。
+      if (await shouldRunSuiteInstall(job, probes) === true) {
         job.kind = 'suite'
         const suiteResult = await runSuiteInstallJob(job, ports)
     // 套装装配出的普通插件是 copyTree 铺进去的（不在 lock 里）→ 同样对账，避免之后被 pnpm 还原/清理
@@ -263,20 +271,15 @@ async function runInstallJob(job, ports, deps = {}) {
         // clone 后才发现没有 .gitmodules（探测假阳性 / 仓库已重构）→ 回落普通安装，不给用户一个失败
         if (suiteResult?.notASuite !== true) return
         job.kind = 'plugin'
-        job.suiteNote = '探测到的 .gitmodules 与仓库实际内容不符（不是 submodule 套装仓库），已自动回落普通插件安装'
+        job.suiteNote = suiteResult?.reason ?? '探测到的 .gitmodules 与仓库实际内容不符（不是 submodule 套装仓库），已自动回落普通插件安装'
       }
-      // 兜底：宿主端自行拉取仓库元数据（githubJson 与 curl 竞速 + 8s 超时降级）。8s 而非旧值 3s：
-      // IPv6 无路由时单条通道就要 5.4s，3s 预算必输 → branch 恒为 main（2026-09-20 另一位用户实测）。
-      const meta = await Promise.race([
-        Promise.any([
-          githubJson(`${GITHUB_API}/repos/${job.repo}`),
-          curlJson(`${GITHUB_API}/repos/${job.repo}`, 12000, {}, { ipv4: true }),
-        ]),
-        new Promise((resolve) => setTimeout(() => resolve(null), META_BUDGET_MS)),
-      ]).catch(() => null)
+      // 仓库元数据（默认分支）探测搬进 suite.js 的 fetchRepoMeta（githubJson 与 curl 竞速 + 8s 降级，
+      // 黑洞期不卡 40s；8s 而非 3s 的理由见那里的注释）。套装判定时已经探过一次 → 这里复用缓存，不重复联网。
+      const meta = job.repoMeta !== undefined ? job.repoMeta : await fetchRepoMeta(job.repo)
       const branch = meta?.default_branch ?? 'main'
       job.defaultBranch = branch // 批次 B-⑥：后续读子包一律以它打头（默认分支是 dev 的仓库不再读不到子包）
-      const { pkg, reason } = await probes.fetchRepoPackageEx(job.repo, branch)
+      const rootProbe = job.rootPkgProbe !== undefined ? job.rootPkgProbe : await probes.fetchRepoPackageEx(job.repo, branch)
+      const { pkg, reason } = rootProbe
       if (pkg === null) {
         // 无 package.json：先探测是否技能仓库（含 SKILL.md）→ 自动转技能安装；
         // 否则标记 hint=repo-land，前端给出「仓库落地」一键入口（克隆到本地目录）。
@@ -306,7 +309,7 @@ async function runInstallJob(job, ports, deps = {}) {
         // private: true，但 main/dev 各有 22 个子包目录。失败原因是当时市场索引源全挂、网络受限，
         // subpackageCandidates() 读不到列表 —— 旧代码只有"有没有子包"一个出口，把**没读到**
         // 报成了**不存在**，直接把用户带偏。教训：探测失败必须与确定性结论分开表达。
-        let subs = await probes.subpackageCandidates(job.repo, branch)
+        let subs = job.subpackageProbe !== undefined ? job.subpackageProbe : await probes.subpackageCandidates(job.repo, branch)
         if (subs.length === 0) {
           // 读不到时先换一条分支重试：meta 探测失败时 branch 恒为 main，而默认分支为 dev 的仓库
           // （本例 dsh-web 就是 dev 为默认分支）main 上的子包布局可能不同/为空；
@@ -484,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，
@@ -512,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'
@@ -183,11 +183,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 上"）。 */

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,
 }