@noob-stupid/dsh-plugin-console 0.5.55 → 0.5.57

package/lib/client.js

@@ -121,6 +121,20 @@ window.__ModuleLoader__.load({
 			hostedNoChannel: "本实例由桌面端外壳托管：框架升级与回滚请走桌面端（此处不可用）",
 			linksTitle: "开发式链接（link）：共 {n} 个，自足 {ready} 个 —— ✓ 自足 · · 缺东西（悬停看原因）",
 			healthSummary: "需要处理 {n} 类问题",
+			exemptGrantBtn: "授精确版本豁免",
+			devRootsTitle: "开发区根（只有这些根里的目录能钉住）",
+			devRootsNone: "（未登记）",
+			devRootAddPlaceholder: "注册新的开发区根（绝对路径，例如 D:\\my-plugins）",
+			devRootAddBtn: "注册根",
+			devRootAdded: "已注册（列表已刷新）",
+			pinDirPlaceholder: "要钉住的目录（必须在上面某个根里）",
+			pinPlanBtn: "先看会发生什么",
+			pinApplyBtn: "确认钉住",
+			pinAllowAgent: "允许 agent 自动钉住",
+			pinAllowAgentTitle: "默认关闭：勾选后，agent 发起的钉住才会被服务端接受",
+			pinPlanReady: "将把 {name} v{v} 钉成 link 依赖",
+			pinDone: "已钉住 {name}（清单已备份；若 pnpm 或验证失败已自动回滚）",
+			exemptGrantTitle: "把「这个精确版本」在「当前框架版本」上授权给框架（写入 profile 的 compatibility.json，先备份、写完读回验证）",
 			linksFailed: "开发式链接清单读取失败",
 			actionReconcileLabel: "重建 pnpm-lock.yaml",
 			actionRun: "执行",
@@ -715,6 +729,20 @@ window.__ModuleLoader__.load({
 			hostedNoChannel: "Hosted by the desktop shell: use the desktop app for framework upgrade and rollback (unavailable here)",
 			linksTitle: "Dev links (link:): {n} total, {ready} self-sufficient - checkmark = ready, dot = something missing (hover for why)",
 			healthSummary: "{n} issue type(s) need attention",
+			exemptGrantBtn: "Grant exact-version exemption",
+			devRootsTitle: "Dev roots (only directories inside these can be pinned)",
+			devRootsNone: "(none registered)",
+			devRootAddPlaceholder: "Register a dev root (absolute path, e.g. D:\\my-plugins)",
+			devRootAddBtn: "Add root",
+			devRootAdded: "Registered (list refreshed)",
+			pinDirPlaceholder: "Directory to pin (must be inside one of the roots above)",
+			pinPlanBtn: "Preview",
+			pinApplyBtn: "Pin it",
+			pinAllowAgent: "Allow agent-initiated pins",
+			pinAllowAgentTitle: "Off by default: once ticked, pins initiated by the agent are accepted",
+			pinPlanReady: "Will pin {name} v{v} as a link dependency",
+			pinDone: "Pinned {name} (manifest backed up; rolled back automatically if pnpm or verification failed)",
+			exemptGrantTitle: "Authorize this exact version on the current framework version (writes via compatibility.json in the profile, with backup and read-back verification)",
 			linksFailed: "Failed to read the dev-link inventory",
 			actionReconcileLabel: "Rebuild pnpm-lock.yaml",
 			actionRun: "Run",
@@ -4610,7 +4638,21 @@ window.__ModuleLoader__.load({
 							el("p", null,
 								t("skippedBundlesTitle").replace("{n}", String(state.data.skippedBundles.items.length))),
 							...state.data.skippedBundles.items.map((b) => el("p", { key: b.packageName, title: b.hint ?? undefined, style: { margin: "4px 0 0 12px" } },
-								"• " + b.packageName + (b.version ? " v" + b.version : "") + " — " + b.reason)),
+								"• " + b.packageName + (b.version ? " v" + b.version : "") + " — " + b.reason,
+								// ★ 0.5.56：把提示里的"三条出路"之一真正做成可点的动作。
+								//   过去控制台**只读** compatibility.json、从不写 ⇒ 那句提示等于把活推回用户。
+								//   只在能确定精确版本时才给按钮（写豁免必须按精确版本，否则框架会忽略）。
+								b.version
+									? el("button", {
+										type: "button",
+										style: { marginLeft: "8px", cursor: "pointer" },
+										title: t("exemptGrantTitle"),
+										onClick: () => {
+											call("/plugin-console/compat-exempt", { packageName: b.packageName, version: b.version })
+												.then(() => refresh(), () => {});
+										},
+									}, t("exemptGrantBtn"))
+									: null)),
 						)
 					: null,
 
@@ -6124,10 +6166,17 @@ window.__ModuleLoader__.load({
 			//   过去 link 钉住的插件与普通插件长得一模一样 —— 看不出指向哪、目标还在不在、
 			//   依赖/peer 齐不齐、垫片还在不在。这份清单让"看见"先成立。
 			const [links, setLinks] = react.useState(null);
+			// ★ 0.5.57：开发区根 + 钉住输入（用户决定：允许注册自己的根；不允许任意目录；agent 钉住需勾选、默认关）
+			const [devRoots, setDevRoots] = react.useState([]);
+			const [rootInput, setRootInput] = react.useState("");
+			const [pinInput, setPinInput] = react.useState("");
+			const [pinNote, setPinNote] = react.useState(null);
+			const [allowAgent, setAllowAgent] = react.useState(false);
 			const load = async () => {
 				try {
 					// link 清单：独立 try（拿不到时这块显示"读取失败"，绝不静默）
 				try { const lk = await call("/plugin-console/links"); if (lk !== null) setLinks(lk); } catch {}
+				try { const dr = await call("/plugin-console/dev-roots", { action: "list" }); if (dr !== null && Array.isArray(dr.roots)) setDevRoots(dr.roots); } catch {}
 				const data = await call("/plugin-console/compat-status");
 					if (data !== null) {
 						setStatus(data);
@@ -6279,9 +6328,70 @@ window.__ModuleLoader__.load({
 									+ (Array.isArray(x.foreignPeers) && x.foreignPeers.length > 0 ? "  · 异副本 " + x.foreignPeers.length : "")
 									+ (x.shims !== null && x.shims !== undefined ? "  · 垫片 " + String(x.shims.count ?? 0) : "")
 									+ (x.persisted !== null && x.persisted !== undefined && x.persisted.ok === false ? "  · 未持久化" : ""))))
+
 					: (links !== null && links.ok === false
 						? el("div", { style: { fontSize: "12px", marginTop: "4px", opacity: .8 } }, t("linksFailed") + "：" + String(links.error ?? "-"))
 						: null),
+				// ★ 0.5.57：开发区根与"按路径钉住" —— 把协作开发流真正接通。
+				//   规矩全部由服务端执行（domain/dev-roots.js 是"不许任意目录"的唯一执行点），
+				//   这里只负责：先规划给人看 → 再让人确认 → 才真写。
+				el("div", { style: { display: "flex", flexDirection: "column", gap: "4px", marginTop: "6px", paddingTop: "6px", borderTop: "1px solid var(--dsw-alias-border-secondary, rgba(127,127,127,.18))" } },
+					el("div", { style: { fontSize: "12px", fontWeight: 500 } }, t("devRootsTitle")),
+					el("div", { style: { fontSize: "12px", opacity: .8, marginLeft: "10px", wordBreak: "break-all" } }, devRoots.length === 0 ? t("devRootsNone") : devRoots.join("  ·  ")),
+					el("div", { style: { display: "flex", gap: "6px", marginLeft: "10px", flexWrap: "wrap" } },
+						el("input", {
+							type: "text", value: rootInput, placeholder: t("devRootAddPlaceholder"),
+							style: { flex: "1 1 240px", minWidth: "180px", fontSize: "12px", padding: "3px 6px" },
+							onChange: (e) => setRootInput(e.target.value),
+						}),
+						el("button", {
+							type: "button", className: styles.toggle, disabled: busy || rootInput.trim() === "",
+							onClick: async () => {
+								setBusy(true); setPinNote(null);
+								try {
+									const r = await call("/plugin-console/dev-roots", { action: "add", dir: rootInput.trim() });
+									if (r !== null) { setRootInput(""); setPinNote({ text: t("devRootAdded"), level: null }); await load(); }
+								} catch (error) { setPinNote({ text: String(error && error.message || error), level: "error" }); }
+								setBusy(false);
+							},
+						}, t("devRootAddBtn"))),
+					el("div", { style: { display: "flex", gap: "6px", marginLeft: "10px", flexWrap: "wrap" } },
+						el("input", {
+							type: "text", value: pinInput, placeholder: t("pinDirPlaceholder"),
+							style: { flex: "1 1 280px", minWidth: "200px", fontSize: "12px", padding: "3px 6px" },
+							onChange: (e) => setPinInput(e.target.value),
+						}),
+						// ③ 用户决定：agent 自动钉住要勾选、**默认关闭**
+						el("label", { style: { fontSize: "12px", display: "flex", alignItems: "center", gap: "4px" }, title: t("pinAllowAgentTitle") },
+							el("input", { type: "checkbox", checked: allowAgent, onChange: (e) => setAllowAgent(e.target.checked) }),
+							t("pinAllowAgent")),
+						el("button", {
+							type: "button", className: styles.toggle, disabled: busy || pinInput.trim() === "",
+							onClick: async () => {
+								setBusy(true); setPinNote(null);
+								try {
+									// 第一段：只规划，把"将要发生什么"给人看（人性化：不让人闭眼点）
+									const plan = await call("/plugin-console/pin-dev-dir", { dir: pinInput.trim(), confirm: false, allowAgent });
+									if (plan !== null && plan.ok === true) {
+										setPinNote({ text: fill(t("pinPlanReady"), [["name", String(plan.packageName)], ["v", String(plan.version ?? "?")]]) + " → " + (plan.steps || []).join("；"), level: null });
+									}
+								} catch (error) { setPinNote({ text: String(error && error.message || error), level: "error" }); }
+								setBusy(false);
+							},
+						}, t("pinPlanBtn")),
+						el("button", {
+							type: "button", className: styles.toggle, disabled: busy || pinInput.trim() === "",
+							onClick: async () => {
+								setBusy(true); setPinNote(null);
+								try {
+									// 第二段：真写（备份清单 → link: → pnpm 对齐 → 自足性 → 读回验证）
+									const r = await call("/plugin-console/pin-dev-dir", { dir: pinInput.trim(), confirm: true, allowAgent });
+									if (r !== null) { setPinNote({ text: fill(t("pinDone"), [["name", String(r.packageName ?? pinInput.trim())]]), level: null }); setPinInput(""); await load(); }
+								} catch (error) { setPinNote({ text: String(error && error.message || error), level: "error" }); }
+								setBusy(false);
+							},
+						}, t("pinApplyBtn"))),
+					pinNote === null ? null : el("div", { style: { fontSize: "12px", marginLeft: "10px", color: pinNote.level === "error" ? "#d33" : "inherit", wordBreak: "break-word" } }, pinNote.text)),
 				row("scan", t("safetyFpTitle"), fp.changed === true ? fill(t("safetyFpChanged"), [["reasons", (fp.reasons || []).join("；")]]) : t("safetyFpStable"), fp.changed === true ? el("button", { type: "button", className: styles.toggle, onClick: ack, disabled: busy }, t("safetyFpAck")) : null),
 				row("list", t("safetyBackfillTitle"), pending > 0 ? fill(t("safetyBackfillDesc"), [["n", pending]]) : t("safetyBackfillNone"), pending > 0 ? el("button", { type: "button", className: styles.toggle, disabled: busy, onClick: applyBackfill }, fill(t("safetyBackfillBtn"), [["n", pending]])) : null),
 				// 依赖锁体检 / 重建（2026-09-27 加法）：体检只读；重建必须用户点（服务端也只认显式 POST）。

package/lib/server/domain/compat-exempt.js

@@ -0,0 +1,127 @@
+// L1 · domain —— 兼容豁免的**写入**（0.5.56 加法：把"只读"补成"可操作"）
+//
+// 为什么需要：
+//   0.5.53 让"被框架跳过的 bundle"可见了，提示里写着三条出路（更新 / 授精确版本豁免 / 从 bundles 删掉），
+//   但控制台**只会读** `compatibility.json`，从不会写 —— 于是那句提示等于把活推回给用户：
+//   "你自己去编辑那个文件，格式自己查"。这就是半截活。
+//
+// 格式（与框架 `readProfileCompatibility` 逐字对齐，读错会静默失效）：
+//   {
+//     "@scope/pkg@1.2.3": ["0.2.1-rc.2", "0.2.1-rc.1"]      // 精确包版本 → 允许的精确 DSH 版本列表
+//   }
+//   · 键必须是**精确** `name@version`（框架用 isExactPluginVersion 校验，范围/前缀一律被忽略）
+//   · 值必须是精确版本字符串数组
+//   · 坏记录被框架**忽略**（不是致命）——所以写入方必须自己保证格式，否则"写了但没生效"且没人知道
+//
+// 纪律：
+//   · **绝不静默**：每一次写盘都先备份、写完**读回来验证**，验证不过就回滚并如实报错；
+//   · 只增删**指定那一条**，其余记录（含用户手写的）原样保留、键序不变；
+//   · 撤销 = 从该键的列表里去掉当前框架版本；列表空了才删键（不误伤同一包的其它授权）。
+//
+// 分层：L1 domain —— 收已解开的 profileDir，不认 ctx；不联网、不 spawn。
+import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { COMPATIBILITY_FILE, readCompatExemptions } from './bundle-veto.js'
+
+const readJsonSafe = (file) => {
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return null }
+}
+
+/** 精确版本判据（框架同义：不接受范围/前缀/空白）。 */
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u
+/** 精确 `name@version` 键。 */
+function isExactPackageVersionKey(key) {
+  if (typeof key !== 'string') return false
+  const at = key.lastIndexOf('@')
+  if (at <= 0) return false
+  return EXACT_VERSION_RE.test(key.slice(at + 1)) && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u.test(key.slice(0, at))
+}
+
+/**
+ * 规划一次豁免写入（**纯函数，不写盘**）。
+ *
+ * @param {object} p
+ * @param {string} p.profileDir profile 根目录
+ * @param {string} p.packageName 包名
+ * @param {string} p.version 该包的**精确**版本
+ * @param {string} p.frameworkVersion 要授权的**精确** DSH 版本
+ * @param {'grant'|'revoke'} [p.mode] grant=加一条授权（默认），revoke=撤销当前框架版本的授权
+ * @returns {{ ok: boolean, status: number, error: string|null, file: string, next: object|null,
+ *             changed: boolean, key: string|null, note: string|null }}
+ */
+function planExemption({ profileDir, packageName, version, frameworkVersion, mode = 'grant' } = {}) {
+  const file = typeof profileDir === 'string' && profileDir !== '' ? join(profileDir, COMPATIBILITY_FILE) : null
+  const base = { ok: false, status: 400, error: null, file, next: null, changed: false, key: null, note: null }
+  if (file === null) return { ...base, error: '拿不到 profile 目录，拒绝改动' }
+  if (typeof packageName !== 'string' || packageName === '') return { ...base, error: '缺少 packageName' }
+  if (typeof version !== 'string' || !EXACT_VERSION_RE.test(version)) {
+    return { ...base, error: `version 必须是精确版本（收到 ${JSON.stringify(version)}）；豁免按精确版本生效，范围没有意义` }
+  }
+  if (typeof frameworkVersion !== 'string' || !EXACT_VERSION_RE.test(frameworkVersion)) {
+    return { ...base, error: `拿不到精确的框架版本（收到 ${JSON.stringify(frameworkVersion)}）—— 拒绝写一条"授权了但不知道授权给谁"的记录` }
+  }
+  const key = `${packageName}@${version}`
+  if (!isExactPackageVersionKey(key)) return { ...base, error: `键 ${key} 不是合法的精确 name@version` }
+
+  // 现有文件：坏文件不覆盖（那是用户的文件，覆盖等于丢数据）
+  let current = {}
+  if (existsSync(file)) {
+    const parsed = readJsonSafe(file)
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ...base, status: 409, error: `${file} 已存在但不是合法对象；为避免覆盖你的文件，本动作已停止（请先手工修好或删掉它）` }
+    }
+    current = parsed
+  }
+  const next = { ...current }
+  const existing = Array.isArray(next[key]) ? next[key].filter((v) => typeof v === 'string') : []
+
+  if (mode === 'revoke') {
+    if (!existing.includes(frameworkVersion)) {
+      return { ...base, ok: true, status: 200, next: current, changed: false, key, note: `没有 ${key} → ${frameworkVersion} 的授权，无需撤销` }
+    }
+    const left = existing.filter((v) => v !== frameworkVersion)
+    if (left.length === 0) delete next[key]
+    else next[key] = left
+    return { ...base, ok: true, status: 200, next, changed: true, key, note: `已撤销 ${key} 对 ${frameworkVersion} 的授权` }
+  }
+
+  if (existing.includes(frameworkVersion)) {
+    return { ...base, ok: true, status: 200, next: current, changed: false, key, note: `${key} 已授权 ${frameworkVersion}，无需重复写入` }
+  }
+  next[key] = [...existing, frameworkVersion]
+  return { ...base, ok: true, status: 200, next, changed: true, key, note: `已授权 ${key} 在 ${frameworkVersion} 上使用` }
+}
+
+/**
+ * 执行写入：备份 → 原子写（临时文件 + rename）→ **读回来验证** → 失败则回滚。
+ * 绝不谎报成功：验证不过一律返回 ok:false 并把原因写清。
+ */
+function applyExemption(input) {
+  const plan = planExemption(input)
+  if (plan.ok !== true || plan.changed !== true) return plan
+  const { file, next, key } = plan
+  const backup = `${file}.bak-${Date.now()}`
+  try {
+    if (existsSync(file)) copyFileSync(file, backup)
+    const tmp = `${file}.tmp-${Date.now()}`
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    renameSync(tmp, file)
+  } catch (error) {
+    // 写失败：把备份放回去（有备份时），如实报
+    try { if (existsSync(backup)) copyFileSync(backup, file) } catch {}
+    return { ...plan, ok: false, status: 500, error: `写入 ${file} 失败：${error instanceof Error ? error.message : String(error)}`, backup }
+  }
+  // 读回来验证：框架读得出来的才算真的生效（"写了但没生效"是最坏的一种假绿）
+  const verify = readCompatExemptions(typeof input?.profileDir === 'string' ? input.profileDir : '')
+  const granted = Array.isArray(verify[key]) ? verify[key] : []
+  const want = input?.mode === 'revoke'
+    ? !granted.includes(input?.frameworkVersion)
+    : granted.includes(input?.frameworkVersion)
+  if (!want) {
+    try { if (existsSync(backup)) copyFileSync(backup, file) } catch {}
+    return { ...plan, ok: false, status: 500, error: `写入后验证失败（${file} 读回来不符合预期），已回滚`, backup }
+  }
+  return { ...plan, ok: true, backup }
+}
+
+export { EXACT_VERSION_RE, isExactPackageVersionKey, planExemption, applyExemption }

package/lib/server/domain/dev-roots.js

@@ -0,0 +1,147 @@
+// L1 · domain —— 开发区根（dev roots）：**"钉住任意目录"的安全边界**（0.5.57 加法）
+//
+// 用户 2026-10-15 的三个决定（原话）：
+//   ① 「允许」—— 允许注册自己的开发区根（不只 `~/.dsh/plugin-src`）；
+//   ② 「不允许」—— **不允许任意目录**：目标必须落在某个已注册的根里；
+//   ③ 「要，默认关闭」—— agent 自动钉住必须由用户勾选，且默认关闭。
+//
+// 本模块只负责 ①②：登记表 + **包含性判定**。③ 属于动作层的开关，见 domain/pin-dev-dir.js。
+//
+// 为什么包含性判定必须写在这里、且写得死板：
+//   它是"不许任意目录"这条决定的**唯一执行点**。写松了（比如只用 startsWith 字符串前缀），
+//   `C:\dev` 会命中 `C:\devil\evil`；用 realpath 才能挡掉"根里放一个指向别处的 junction"。
+//   三条都做到才算数：**realpath 归一 → Windows 大小写不敏感 → 路径分隔符边界**。
+//
+// 文件：`<DSH_HOME>/plugin-console/dev-roots.json`
+//   { "roots": ["C:\\Users\\x\\.dsh\\plugin-src", "D:\\my-dev"] }
+//   缺省 = 只有 `<DSH_HOME>/plugin-src`（用户现有 7 个 link 里 6 个就在这）。
+//
+// 分层：L1 domain —— 收 home（已解开的字符串），不认 ctx；不联网、不 spawn。
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve, sep } from 'node:path'
+
+const DEV_ROOTS_FILE = 'dev-roots.json'
+
+/** DSH 家目录（与其它模块同口径：优先 env，否则 ~/.dsh）。 */
+function homeDirOf(home) {
+  if (typeof home === 'string' && home !== '') return home
+  const env = process.env.DSH_HOME
+  return typeof env === 'string' && env !== '' ? env : join(homedir(), '.dsh')
+}
+
+/** 登记表文件路径。 */
+function devRootsFile(home) {
+  return join(homeDirOf(home), 'plugin-console', DEV_ROOTS_FILE)
+}
+
+/** 默认根：`<DSH_HOME>/plugin-src`（用户现有 link 目标绝大多数在这里）。 */
+function defaultDevRoot(home) {
+  return join(homeDirOf(home), 'plugin-src')
+}
+
+/** 归一化：realpath（存在时）→ 去尾分隔符 → Windows 大小写折叠。判等/包含都走它。 */
+function normalizePath(p) {
+  if (typeof p !== 'string' || p.trim() === '') return null
+  let out = resolve(p)
+  try { if (existsSync(out)) out = realpathSync(out) } catch {}
+  out = out.replace(/[\\/]+$/u, '')
+  return process.platform === 'win32' ? out.toLowerCase() : out
+}
+
+/** child 是否**严格位于** root 之内（不含 root 本身）。分隔符边界必须成立。 */
+function isInside(childNorm, rootNorm) {
+  if (childNorm === null || rootNorm === null) return false
+  if (childNorm === rootNorm) return false
+  return childNorm.startsWith(rootNorm.endsWith(sep) ? rootNorm : rootNorm + sep)
+}
+
+/**
+ * 读登记表。**缺省即默认根**；坏文件降级为默认根（并如实带 warnings，不假装一切正常）。
+ * @returns {{ roots: string[], warnings: string[], file: string }}
+ */
+function readDevRoots(home) {
+  const file = devRootsFile(home)
+  const fallback = { roots: [defaultDevRoot(home)], warnings: [], file }
+  if (!existsSync(file)) return fallback
+  let parsed = null
+  try { parsed = JSON.parse(readFileSync(file, 'utf8')) } catch (error) {
+    return { ...fallback, roots: [defaultDevRoot(home)], warnings: [`${file} 读不出来或不是合法 JSON（${error instanceof Error ? error.message : String(error)}）；已按默认根处理`] }
+  }
+  const list = parsed !== null && typeof parsed === 'object' && Array.isArray(parsed.roots) ? parsed.roots : null
+  if (list === null) return { ...fallback, warnings: [`${file} 缺少 roots 数组；已按默认根处理`] }
+  const roots = list.filter((x) => typeof x === 'string' && x !== '')
+  if (roots.length === 0) return fallback
+  return { roots, warnings: [], file }
+}
+
+/** 原子写登记表（备份 + 临时文件 + rename）。 */
+function writeDevRoots(home, roots) {
+  const file = devRootsFile(home)
+  mkdirSync(dirname(file), { recursive: true })
+  const tmp = `${file}.tmp-${Date.now()}`
+  writeFileSync(tmp, `${JSON.stringify({ roots }, null, 2)}\n`, 'utf8')
+  renameSync(tmp, file)
+  return file
+}
+
+/**
+ * 判定一个目录是否可以成为"开发区里的目标"。
+ *
+ * @returns {{ ok: boolean, reason: string|null, normalized: string|null, root: string|null }}
+ *   ok=false 时 reason 是**给人看的**一句话（面板直接显示）。
+ */
+function checkInsideDevRoots(home, candidate) {
+  const norm = normalizePath(candidate)
+  if (norm === null) return { ok: false, reason: '没有提供目录', normalized: null, root: null }
+  if (!existsSync(candidate)) return { ok: false, reason: `目录不存在：${candidate}`, normalized: norm, root: null }
+  let isDir = false
+  try { isDir = statSync(candidate).isDirectory() } catch {}
+  if (!isDir) return { ok: false, reason: `不是目录：${candidate}`, normalized: norm, root: null }
+  const { roots } = readDevRoots(home)
+  for (const root of roots) {
+    const rootNorm = normalizePath(root)
+    if (isInside(norm, rootNorm)) return { ok: true, reason: null, normalized: norm, root }
+  }
+  return {
+    ok: false,
+    reason: `不在任何已注册的开发区根里：${candidate}\n已注册：${roots.join(' / ')}\n（这是刻意的限制：只允许钉住开发区里的目录，不允许任意路径）`,
+    normalized: norm,
+    root: null,
+  }
+}
+
+/** 注册一个新根（必须存在、是目录、不与已有根重复/互相包含）。返回 { ok, error, roots, file }。 */
+function addDevRoot(home, dir) {
+  const norm = normalizePath(dir)
+  if (norm === null) return { ok: false, error: '没有提供目录', roots: readDevRoots(home).roots, file: devRootsFile(home) }
+  if (!existsSync(dir)) return { ok: false, error: `目录不存在：${dir}`, roots: readDevRoots(home).roots, file: devRootsFile(home) }
+  let isDir = false
+  try { isDir = statSync(dir).isDirectory() } catch {}
+  if (!isDir) return { ok: false, error: `不是目录：${dir}`, roots: readDevRoots(home).roots, file: devRootsFile(home) }
+  const current = readDevRoots(home)
+  const normRoots = current.roots.map((r) => normalizePath(r))
+  if (normRoots.includes(norm)) return { ok: true, error: null, roots: current.roots, file: current.file, note: '已经注册过了' }
+  for (const [i, rootNorm] of normRoots.entries()) {
+    if (isInside(norm, rootNorm) || isInside(rootNorm, norm)) {
+      return { ok: false, error: `与已注册的根重叠：${current.roots[i]}（不要嵌套注册，包含关系已覆盖）`, roots: current.roots, file: current.file }
+    }
+  }
+  const roots = [...current.roots, resolve(dir)]
+  return { ok: true, error: null, roots, file: writeDevRoots(home, roots) }
+}
+
+/** 取消注册（默认根不允许取消 —— 它是兜底，去掉会让人连自己现有的插件都钉不回来）。 */
+function removeDevRoot(home, dir) {
+  const norm = normalizePath(dir)
+  const current = readDevRoots(home)
+  const idx = current.roots.findIndex((r) => normalizePath(r) === norm)
+  if (idx < 0) return { ok: false, error: `未注册：${dir}`, roots: current.roots, file: current.file }
+  if (norm === normalizePath(defaultDevRoot(home))) {
+    return { ok: false, error: `默认根不能取消注册：${defaultDevRoot(home)}（它是兜底）`, roots: current.roots, file: current.file }
+  }
+  const roots = current.roots.filter((_, i) => i !== idx)
+  return { ok: true, error: null, roots, file: writeDevRoots(home, roots) }
+}
+
+export { DEV_ROOTS_FILE, homeDirOf, devRootsFile, defaultDevRoot, normalizePath, isInside, readDevRoots, writeDevRoots, checkInsideDevRoots, addDevRoot, removeDevRoot }

package/lib/server/domain/pin-dev-dir.js

@@ -0,0 +1,150 @@
+// L1 · domain —— 把"开发区里的某个目录"钉成一个 link 依赖（0.5.57 加法）
+//
+// 用户决定（2026-10-15 原话）：① 允许注册自己的开发区根；② **不允许任意目录**；③ agent 自动钉住要用户勾选，
+// 且**默认关闭**。本模块是 ②③ 的执行点：
+//   · 目标必须落在已注册的根里（判据在 domain/dev-roots.js，本模块**不重复实现**）；
+//   · `allowAgent` 必须显式为 true 才允许"由 agent 发起"的钉住（默认 false = 只接受用户显式请求）。
+//
+// 动作分两段，和仓库其它写动作一致：
+//   planPinDevDir  —— **纯只读**：校验 + 产出一份"将要发生什么"的清单（面板先给用户看，人性化）；
+//   applyPinDevDir —— 真的写：备份清单 → 写 `link:<dir>` → 跑 pnpm（可注入）→ **读回归属与 lock** →
+//                     失败即回滚清单并如实报错（绝不谎报"钉住了"）。
+//
+// 为什么必须读回验证：`link:` 的"钉住了"判据是**清单里该包是 link: 形式且 lock 跟上了**，
+//   不是"我写进去了"。pnpm 可能把绝对路径规范化、也可能因供应链闸/构建脚本失败而根本没写成。
+//
+// 分层：L1 domain —— 收已解开的 home/profileDir/deps；不认 ctx。pnpm 通过 deps.runInstall 注入（便于离线测试）。
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { checkInsideDevRoots } from './dev-roots.js'
+
+const readJsonSafe = (file) => {
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return null }
+}
+
+/** 该目录是不是一个 dsh 插件（有 dsh.bundle / dsh.client / dsh.profile 任一标记）。
+ *  与 install-job 的检测同口径（那套是"清单没有标志 ≠ 不是插件"的判据真源）。 */
+function dshMarkerOf(pkg) {
+  const dsh = pkg?.dsh
+  if (dsh === null || dsh === undefined || typeof dsh !== 'object') return null
+  for (const key of ['bundle', 'client', 'profile']) {
+    if (dsh[key] !== undefined && dsh[key] !== null) return key
+  }
+  return null
+}
+
+/**
+ * 规划一次钉住（**纯只读**）。
+ *
+ * @param {object} p
+ * @param {string} [p.home] DSH 家目录（读开发区登记表）
+ * @param {string} p.profileDir profile 根目录
+ * @param {string} p.dir 要钉的目录（绝对路径）
+ * @param {boolean} [p.allowAgent=false] 是否允许"由 agent 发起"（默认关闭，用户勾选后才 true）
+ * @param {boolean} [p.byAgent=false] 本次请求是否真的由 agent 发起
+ * @returns {{ ok: boolean, status: number, error: string|null, steps: string[],
+ *             packageName: string|null, version: string|null, spec: string|null,
+ *             current: string|null, marker: string|null, root: string|null, needsConfirm: boolean }}
+ */
+function planPinDevDir({ home = null, profileDir, dir, allowAgent = false, byAgent = false } = {}) {
+  const base = {
+    ok: false, status: 400, error: null, steps: [], packageName: null, version: null,
+    spec: null, current: null, marker: null, root: null, needsConfirm: true,
+  }
+  // ③ agent 发起必须被明确放行（默认关闭）
+  if (byAgent === true && allowAgent !== true) {
+    return { ...base, status: 403, error: '看起来是 agent 发起的钉住，但「允许 agent 自动钉住」这个开关是关着的（默认关闭）—— 请在面板里勾选后再试，或由你自己点按钮' }
+  }
+  if (typeof profileDir !== 'string' || profileDir === '') return { ...base, error: '拿不到 profile 目录，拒绝改动' }
+  // ② 必须落在已注册的开发区根里（唯一执行点）
+  const inside = checkInsideDevRoots(home, dir)
+  if (inside.ok !== true) return { ...base, status: 403, error: inside.reason }
+  // 必须是一份能读的 package.json
+  const pkgPath = join(dir, 'package.json')
+  if (!existsSync(pkgPath)) return { ...base, status: 400, error: `${dir} 里没有 package.json —— 这不是一个可安装的包` }
+  const pkg = readJsonSafe(pkgPath)
+  if (pkg === null || typeof pkg !== 'object') return { ...base, status: 400, error: `${pkgPath} 读不出来或不是合法 JSON` }
+  if (typeof pkg.name !== 'string' || pkg.name === '') return { ...base, status: 400, error: `${pkgPath} 没有 name 字段` }
+  const marker = dshMarkerOf(pkg)
+  if (marker === null) {
+    return { ...base, status: 400, error: `${pkg.name} 的 package.json 里没有 dsh.bundle / dsh.client / dsh.profile —— 它不是 dsh 插件，钉住它没有意义` }
+  }
+  const version = typeof pkg.version === 'string' ? pkg.version : null
+  // 现值（用于"改了没有"的判定与人性化预览）
+  const manifest = readJsonSafe(join(profileDir, 'package.json')) ?? {}
+  const deps = manifest.dependencies !== null && typeof manifest.dependencies === 'object' ? manifest.dependencies : {}
+  const current = typeof deps[pkg.name] === 'string' ? deps[pkg.name] : null
+  const spec = `link:${dir}`
+  const steps = [
+    `把 ${pkg.name} 的来源写成 ${spec}（清单 dependencies）`,
+    '跑一次 pnpm install --lockfile-only，让 pnpm-lock.yaml 与清单一致',
+    '补该插件的自足性（缺的 dependencies 交给 pnpm，框架 peer 走垫片）',
+    '读回归属与 lock 复核：只有两处都到位才算钉住',
+  ]
+  return { ...base, ok: true, status: 200, packageName: pkg.name, version, spec, current, marker, root: inside.root, steps }
+}
+
+/**
+ * 执行钉住。**失败即回滚清单**，绝不留半截状态、绝不谎报成功。
+ *
+ * @param {object} p — 同 planPinDevDir，外加：
+ * @param {(args: object) => Promise<{ ok: boolean, stderr?: string, note?: string }>} [p.runInstall]
+ *        注入的 pnpm 执行器（离线测试用）；缺省走真实 pnpm。
+ * @param {(args: object) => Promise<object>} [p.ensureSufficiency] 注入的自足性执行器
+ */
+async function applyPinDevDir({ home = null, profileDir, dir, allowAgent = false, byAgent = false, runInstall = null, ensureSufficiency = null } = {}) {
+  const plan = planPinDevDir({ home, profileDir, dir, allowAgent, byAgent })
+  if (plan.ok !== true) return { ...plan, changed: false, backup: null }
+  const manifestPath = join(profileDir, 'package.json')
+  const before = readFileSync(manifestPath, 'utf8')
+  const backup = `${manifestPath}.bak-pin-${Date.now()}`
+  try { writeFileSync(backup, before, 'utf8') } catch {}
+  const rollback = (reason) => {
+    try { writeFileSync(manifestPath, before, 'utf8') } catch {}
+    return { ...plan, ok: false, changed: false, status: 500, error: `${reason}\n（清单已回滚到改动前，backup: ${backup}）`, backup }
+  }
+  // ① 写清单
+  try {
+    const manifest = JSON.parse(before)
+    manifest.dependencies = manifest.dependencies !== null && typeof manifest.dependencies === 'object' ? manifest.dependencies : {}
+    manifest.dependencies[plan.packageName] = plan.spec
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+  } catch (error) {
+    return rollback(`写 profile 清单失败：${error instanceof Error ? error.message : String(error)}`)
+  }
+  // ② pnpm：lock 与清单对齐（失败即回滚）
+  let installNote = null
+  try {
+    const run = typeof runInstall === 'function' ? await runInstall({ profileDir, spec: plan.spec }) : { ok: true, skipped: true }
+    if (run?.ok !== true) {
+      return rollback(`pnpm 未能让 lock 与清单一致${run?.stderr ? `：${String(run.stderr).slice(0, 600)}` : ''}`)
+    }
+    installNote = run?.note ?? null
+  } catch (error) {
+    return rollback(`pnpm 执行失败：${error instanceof Error ? error.message : String(error)}`)
+  }
+  // ③ 自足性（失败不致命：如实记下，钉住本身已经成立）
+  let sufficiency = null
+  try {
+    if (typeof ensureSufficiency === 'function') sufficiency = await ensureSufficiency({ profileDir, packageName: plan.packageName })
+  } catch (error) {
+    sufficiency = { ok: false, note: error instanceof Error ? error.message : String(error) }
+  }
+  // ④ 读回验证：清单里必须是 link: 形式（pnpm 可能规范化路径，所以只认前缀）
+  const after = readJsonSafe(manifestPath)
+  const afterSpec = typeof after?.dependencies?.[plan.packageName] === 'string' ? after.dependencies[plan.packageName] : null
+  const linked = typeof afterSpec === 'string' && afterSpec.startsWith('link:')
+  if (!linked) return rollback(`写完读回发现清单里不是 link: 形式（实际 ${JSON.stringify(afterSpec)}）`)
+  return {
+    ...plan,
+    ok: true,
+    status: 200,
+    changed: true,
+    backup,
+    after: afterSpec,
+    note: installNote,
+    sufficiency: sufficiency === null ? null : { ok: sufficiency.ok === true, ready: sufficiency.ready === true, note: sufficiency.note ?? null, created: Array.isArray(sufficiency.created) ? sufficiency.created.length : 0 },
+  }
+}
+
+export { dshMarkerOf, planPinDevDir, applyPinDevDir }

package/lib/server/routes/index.js

@@ -30,7 +30,7 @@ import { routeEnrich, routeMarketIndex, routeRepo, routeSearch, routeSubpackages
 import { routeAdaptUnlock, routeAdaptUnlockAll, routeCleanResiduals, routeSelfUpdate, routeToggle, routeUninstall } from './plugins.js'
 import { routeSkillRemove, routeSkillToggle, routeSkillsInstalledGet } from './skills.js'
 import { routeGiteeOauthCallbackGet, routeGiteeOauthUrlGet, routeRegistryScan, routeSources, routeSourcesGet } from './sources.js'
-import { routeDetails, routeLinksGet, routeStateGet } from './state.js'
+import { routeCompatExempt, routeDetails, routeDevRoots, routeLinksGet, routePinDevDir, routeStateGet } from './state.js'
 
 const ROUTE_PREFIX = '/plugin-console'
 
@@ -38,6 +38,11 @@ const ROUTES_EARLY = [
   { methods: ['GET'], path: `${ROUTE_PREFIX}/state`, handler: routeStateGet },
   // link 开发式安装清单（0.5.54 加法）：纯只读，供面板渲染"已挂载 / 自足性 / 垫片 / 持久化"
   { methods: ['GET'], path: `${ROUTE_PREFIX}/links`, handler: routeLinksGet },
+  // 兼容豁免（0.5.56 加法）：把"被跳过的 bundle"的三条出路之一做成真正可点的动作
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-exempt`, handler: routeCompatExempt },
+  // 开发区根 + 钉住（0.5.57 加法）：允许注册自己的根；不允许任意目录；agent 发起需用户勾选（默认关）
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/dev-roots`, handler: routeDevRoots },
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/pin-dev-dir`, handler: routePinDevDir },
   { methods: ['GET'], path: `${ROUTE_PREFIX}/sources`, handler: routeSourcesGet },
   { methods: ['GET'], path: `${ROUTE_PREFIX}/gitee-oauth-url`, handler: routeGiteeOauthUrlGet },
   { methods: ['GET'], path: `${ROUTE_PREFIX}/gitee-oauth-callback`, handler: routeGiteeOauthCallbackGet },

package/lib/server/routes/state.js

@@ -11,6 +11,11 @@ import { readExtraBundleRows } from '../domain/install-job.js'
 import { bundleVetoList } from '../domain/bundle-veto.js'
 import { buildLinkInventory } from '../domain/link-inventory.js'
 import { buildInstallHealth } from '../domain/install-health.js'
+import { applyExemption } from '../domain/compat-exempt.js'
+import { addDevRoot, readDevRoots, removeDevRoot } from '../domain/dev-roots.js'
+import { applyPinDevDir, planPinDevDir } from '../domain/pin-dev-dir.js'
+import { reconcileLockfile } from '../domain/selfupdate.js'
+import { ensureLinkSelfSufficiency } from '../domain/link-self-sufficiency.js'
 import { readBundlesSync } from '../domain/persist.js'
 import { failedJobEvidence } from '../domain/install-verify.js'
 import { installJobView, readGithubAuth } from '../domain/install.js'
@@ -224,4 +229,104 @@ async function routeLinksGet(req, res, rc) {
   sendJson(res, 200, payload)
 }
 
-export { routeStateGet, routeDetails, routeLinksGet }
+/**
+ * POST /compat-exempt —— **写**一条精确版本豁免（0.5.56 加法）。
+ *
+ * 0.5.53 让"被框架跳过的 bundle"可见，并在提示里给了三条出路；但控制台只会**读** compatibility.json，
+ * 从不写 —— 那条提示等于把活推回用户（"你自己去编辑文件，格式自己查"）。本路由把那半截补上。
+ *
+ * 安全与纪律（与仓库其它写动作一致）：
+ *   · 只接受 { packageName, version, mode }，**不收任何路径** —— 文件位置由服务端按 profile 决定；
+ *   · 精确版本校验（范围/前缀一律拒），框架版本必须是**当前运行时**那个；
+ *   · 先备份 → 原子写 → **读回来验证**，验证不过即回滚并如实报错（绝不谎报成功）；
+ *   · 已有坏文件时**停止**而不是覆盖（那是用户的文件）。
+ */
+async function routeCompatExempt(req, res, rc) {
+  const ctx = rc.ctx
+  const body = rc.body ?? {}
+  let profileDir = null
+  try { profileDir = dirname(findPatchPath(ctx)) } catch {}
+  const frameworkVersion = typeof body.frameworkVersion === 'string' && body.frameworkVersion !== ''
+    ? body.frameworkVersion
+    : (() => { try { return currentFrameworkVersion(ctx) } catch { return null } })()
+  const result = applyExemption({
+    profileDir,
+    packageName: body.packageName,
+    version: body.version,
+    frameworkVersion,
+    mode: body.mode === 'revoke' ? 'revoke' : 'grant',
+  })
+  const payload = {
+    ok: result.ok === true,
+    changed: result.changed === true,
+    key: result.key ?? null,
+    note: result.note ?? null,
+    error: result.error ?? null,
+    backup: result.backup ?? null,
+  }
+  if (result.ok === true) sendJson(res, 200, payload)
+  else sendError(res, result.status ?? 400, payload.error ?? '豁免写入失败', payload)
+}
+
+/**
+ * POST /dev-roots —— 开发区根的登记表（0.5.57 加法）。
+ * 用户 2026-10-15 决定：「允许」注册自己的开发区根、「不允许」任意目录。
+ * 本路由只管登记表本身；**包含性判定**在 domain/dev-roots.js，是"不许任意目录"的唯一执行点。
+ * body: { action: 'list' | 'add' | 'remove', dir? }
+ */
+async function routeDevRoots(req, res, rc) {
+  const body = rc.body ?? {}
+  const action = body.action === 'add' ? 'add' : body.action === 'remove' ? 'remove' : 'list'
+  if (action === 'list') {
+    const r = readDevRoots(null)
+    sendJson(res, 200, { ok: true, roots: r.roots, warnings: r.warnings, file: r.file })
+    return
+  }
+  const result = action === 'add' ? addDevRoot(null, body.dir) : removeDevRoot(null, body.dir)
+  const payload = { ok: result.ok === true, roots: result.roots ?? [], file: result.file ?? null, note: result.note ?? null, error: result.error ?? null }
+  if (result.ok === true) sendJson(res, 200, payload)
+  else sendError(res, 400, result.error ?? '开发区根操作失败', payload)
+}
+
+/**
+ * POST /pin-dev-dir —— 把一个**开发区里的目录**钉成 link 依赖（0.5.57 加法）。
+ *
+ * 用户 2026-10-15 决定：① 允许注册自己的根；② 不允许任意目录；③ agent 自动钉住要用户勾选、**默认关闭**。
+ * 所以本路由有两段，都是刻意的：
+ *   { dir, confirm: false }（默认）→ **只规划**，返回"将要发生什么"的清单（面板先给人看）；
+ *   { dir, confirm: true }          → 真写（备份清单 → 写 link: → pnpm 对齐 lock → 自足性 → 读回验证）。
+ * `byAgent: true` 时服务端会检查 `allowAgent`（面板上的勾选，默认关），未放行一律 403。
+ */
+async function routePinDevDir(req, res, rc) {
+  const ctx = rc.ctx
+  const body = rc.body ?? {}
+  let profileDir = null
+  try { profileDir = dirname(findPatchPath(ctx)) } catch {}
+  const common = {
+    profileDir,
+    dir: body.dir,
+    byAgent: body.byAgent === true,
+    allowAgent: body.allowAgent === true,
+  }
+  if (body.confirm !== true) {
+    const plan = planPinDevDir(common)
+    if (plan.ok !== true) { sendError(res, plan.status ?? 400, plan.error ?? '钉住规划失败', { ok: false }); return }
+    sendJson(res, 200, { ok: true, applied: false, packageName: plan.packageName, version: plan.version, spec: plan.spec, current: plan.current, marker: plan.marker, root: plan.root, steps: plan.steps })
+    return
+  }
+  // 真写：pnpm 通过真实执行器（这里用 install.js 的既有通道，与安装流程同一套）
+  const runInstall = async ({ profileDir: pd }) => {
+    const r = await reconcileLockfile({ profileDir: pd })
+    return { ok: r?.lockUpdated === true || r?.ok === true, note: r?.note ?? null, stderr: r?.stderr ?? null }
+  }
+  const ensureSufficiency = async ({ profileDir: pd, packageName }) => ensureLinkSelfSufficiency({ profileDir: pd, packageName })
+  const result = await applyPinDevDir({ ...common, runInstall, ensureSufficiency })
+  const payload = {
+    ok: result.ok === true, applied: result.changed === true, packageName: result.packageName ?? null,
+    spec: result.spec ?? null, after: result.after ?? null, error: result.error ?? null,
+    backup: result.backup ?? null, note: result.note ?? null, sufficiency: result.sufficiency ?? null,
+  }
+  if (result.ok === true) sendJson(res, 200, payload)
+  else sendError(res, result.status ?? 400, result.error ?? '钉住失败', payload)
+}
+export { routeStateGet, routeDetails, routeLinksGet, routeCompatExempt, routeDevRoots, routePinDevDir }

package/package.json

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