@noob-stupid/dsh-plugin-console 0.5.44 → 0.5.46

package/lib/client.js

@@ -458,6 +458,11 @@ window.__ModuleLoader__.load({
 			repoLandBusy: "克隆中…（大仓库可能较慢）",
 			repoLandDone: "已落地到：",
 			repoLandOpenFolder: "打开文件夹",
+			repoOpenDone: "已请求打开：",
+			repoOpenFailed: "打开文件夹失败：",
+			subpluginFound: "该仓库根目录没有清单，但插件在子目录 {dir}/ 下（{pkg}，标记：{markers}）—— 它不是「不是插件」，只是清单不在仓库根",
+			subpluginCopyDir: "复制子目录路径",
+			subpluginCopyName: "复制包名",
 			repoLandExists: "该仓库已存在，无需重复落地",
 			repoLandDirLabel: "保存路径",
 			repoLandSaveDir: "保存路径",
@@ -1018,6 +1023,11 @@ window.__ModuleLoader__.load({
 			repoLandBusy: "Cloning… (large repos may take a while)",
 			repoLandDone: "Landed at: ",
 			repoLandOpenFolder: "Open folder",
+			repoOpenDone: "Requested to open: ",
+			repoOpenFailed: "Failed to open folder: ",
+			subpluginFound: "This repository has no manifest at its root, but the plugin lives in the subdirectory {dir}/ ({pkg}, markers: {markers}) — it is not \"not a plugin\", the manifest is just not at the repository root",
+			subpluginCopyDir: "Copy subdirectory path",
+			subpluginCopyName: "Copy package name",
 			repoLandExists: "Already exists — nothing to clone",
 			repoLandDirLabel: "Save path",
 			repoLandSaveDir: "Save path",
@@ -2229,7 +2239,10 @@ window.__ModuleLoader__.load({
 				if (!window.confirm(t("repoLandRemoveConfirm").replace("{repo}", item.repo))) return;
 				try {
 					await call("/plugin-console/repo-remove", { path: item.path });
-				} catch {}
+				} catch (error) {
+					// 2026-10-13 改错：删不掉时旧代码 `catch {}` 静默吞掉，用户看到的是"点了没反应、仓库还在"。
+					setMessage(t("safetySwitchFailed") + "：" + (error && typeof error.message === "string" && error.message !== "" ? error.message : t("safetySwitchFailed")));
+				}
 				repoLandRefresh();
 			}
 			async function repoLandStart() {
@@ -2245,9 +2258,22 @@ window.__ModuleLoader__.load({
 				}
 				setRepoLandBusy(false);
 			}
-			async function repoLandOpenFolder() {
-				if (repoLandResult === null || repoLandResult.ok !== true) return;
-				try { await call("/plugin-console/repo-open", { path: repoLandResult.path }); } catch {}
+			/** 打开仓库落地目录（2026-10-13 改错：**成功与失败都必须有结果**）。
+			* 旧实现 `try { await call(...) } catch {}` —— 非 2xx（路径被守卫拒绝 / 目录不存在 /
+			* 文件管理器起不来）全被吞掉，用户只看到"点了没反应"（真机实测报告）。
+			* 现在：服务端回结构化状态 → 成功显示"已在文件管理器中打开：<path>"（服务端的 note 也带上），
+			* 失败把**原因原样**显示（守卫拒绝的原因、目录不存在、spawn 失败的系统原话）。
+			* 供「刚落地」按钮与「已落地列表」每行的按钮共用（两处行为必须一致，别再各写一遍）。 */
+			async function repoLandOpenFolder(target) {
+				const path = typeof target === "string" && target !== "" ? target : (repoLandResult && repoLandResult.path);
+				if (!path) return;
+				try {
+					const data = await call("/plugin-console/repo-open", { path });
+					const note = data && typeof data.note === "string" && data.note !== "" ? "（" + data.note + "）" : "";
+					setMessage(t("repoOpenDone") + (data && data.path ? data.path : path) + note);
+				} catch (error) {
+					setMessage(t("repoOpenFailed") + (error && typeof error.message === "string" && error.message !== "" ? error.message : t("safetySwitchFailed")));
+				}
 			}
 			const sectionRef = react.useRef(null);
 			const [compCardTop, setCompCardTop] = react.useState(null);
@@ -4804,7 +4830,7 @@ window.__ModuleLoader__.load({
 								? (repoLandResult.ok === true
 									? el("div", { className: styles.rowTop },
 										el("p", { className: styles.message, style: { flex: 1, minWidth: 0, wordBreak: "break-all" } }, t("repoLandDone") + repoLandResult.path),
-										el("button", { type: "button", className: styles.toggle, onClick: repoLandOpenFolder }, t("repoLandOpenFolder")))
+										el("button", { type: "button", className: styles.toggle, onClick: () => repoLandOpenFolder(repoLandResult.path) }, t("repoLandOpenFolder")))
 									: el("p", { className: styles.message, "data-error": "true" }, t("safetySwitchFailed") + "：" + (repoLandResult.error ?? "?")))
 								: null,
 							el("strong", { className: styles.name }, t("repoLandList") + "（" + repoLanded.length + "）"),
@@ -4814,7 +4840,7 @@ window.__ModuleLoader__.load({
 									repoLanded.map((item) =>
 										el("div", { key: item.repo, className: styles.rowTop },
 											el("strong", { className: styles.name, style: { flex: "1 1 auto" } }, item.repo),
-											el("button", { type: "button", className: styles.toggle, onClick: () => { call("/plugin-console/repo-open", { path: item.path }).catch(() => {}); } }, t("repoLandOpenFolder")),
+											el("button", { type: "button", className: styles.toggle, onClick: () => repoLandOpenFolder(item.path) }, t("repoLandOpenFolder")),
 											el("button", { type: "button", className: styles.trashBtn, title: t("repoLandRemoveConfirm"), "aria-label": t("repoLandRemoveConfirm"), onClick: () => repoLandRemove(item) }, "✕"))))
 							)))
 					: null,
@@ -5405,10 +5431,30 @@ window.__ModuleLoader__.load({
 								onClick: () => setDismissedFailures((prev) => ({ ...prev, [job.jobId]: true })),
 							}, "✕")),
 						el("p", { className: styles.message, "data-error": "true" }, job.error ?? ""),
+						// 子目录插件（2026-10-13 加法，真机 Fei2411/DeepSeek-Bot）：服务端已判定"插件在
+						// <子目录>/ 下"，这里把结论**单独显示**（不用用户从一整段报错里找路径），
+						// 并给出可复制的下一步（子目录路径 / 包名）。用 styles.message、不加新 class。
+						job.subplugin !== null && job.subplugin !== undefined
+							? el("p", { className: styles.message, "data-warn": "true" },
+								t("subpluginFound")
+									.replace("{dir}", String(job.subplugin.dir ?? "?"))
+									.replace("{pkg}", String(job.subplugin.packageName ?? "?"))
+									.replace("{markers}", Array.isArray(job.subplugin.markers) ? job.subplugin.markers.join(" / ") : "?"))
+							: null,
+						job.subplugin !== null && job.subplugin !== undefined && typeof job.subplugin.dir === "string" && job.subplugin.dir !== ""
+							? el("div", { className: styles.rowTop },
+								el("button", { type: "button", className: styles.toggle, onClick: () => copyInstallCommand(String(job.subplugin.dir)) }, t("subpluginCopyDir")),
+								typeof job.subplugin.packageName === "string" && job.subplugin.packageName !== ""
+									? el("button", { type: "button", className: styles.toggle, onClick: () => copyInstallCommand(String(job.subplugin.packageName)) }, t("subpluginCopyName"))
+									: null)
+							: null,
 						...diagLines(job).map(diagLineEl),
 						el("div", { className: styles.rowTop },
 							el("button", { type: "button", className: styles.toggle, onClick: () => startJob(job.repo, job.packageName, job.source ?? "github") }, t("retry")),
-							job.hint === "repo-land"
+							// 「仓库落地」一键克隆：hint=repo-land（旧结论）与 hint=subdir-plugin（插件在子目录里）
+							// 都要给 —— 后者的文案本身就写着"先按「仓库落地」克隆到本地查看该子目录"，
+							// 按钮若只在 repo-land 时渲染，那句话就指向一个不存在的入口。
+							job.hint === "repo-land" || job.hint === "subdir-plugin"
 								? el("button", { type: "button", className: styles.toggle, title: repoLandTitleText(), onClick: () => { setRepoLandOpen(true); repoLandEntry(job.repo); } }, t("repoLandEntry"))
 								: null)),
 				),

package/lib/server/domain/bundle-refs.js

@@ -9,7 +9,10 @@
 // 注册前先按本模块读出的引用逐个 `resolvePackageJson` 核实，缺失即拒绝注册。
 
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { DEFAULT_BUNDLES } from './install.js'
+import { resolvePackageJson } from '../infra/paths.js'
 
 /** 读取聚合包 `cordis.patch.yml` 的 insert 行 name 列表（注册前校验用）。
  *  解析形状与 install.js#ensureBundlePatchIntegrity 同构：`- insert:` 块下的
@@ -45,4 +48,41 @@ function readBundlePatchRefNames(profileDir, pkgName) {
   } catch { return [] }
 }
 
-export { readBundlePatchRefNames }
+/** 读取用户额外 bundle（非官方模板）的补丁插入行 id 与包名，用于"额外插件"判定。
+ * 2026-10-13 从 install-job.js 原样搬出（只搬移未改逻辑；那边贴着 600 行硬顶，
+ * 而这块与上面的 insert 行解析是同一件事），调用方经 install-job.js 的 re-export 取用，
+ * 对外导出名与行为一字未变（tests/test-architecture-guard 的接线断言要求导出名仍在）。 */
+async function readExtraBundleRows(profileDir) {
+  const rows = new Set()
+  try {
+    const manifest = JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'))
+    const bundles = manifest.dsh?.profile?.bundles ?? []
+    for (const pkg of bundles) {
+      if (DEFAULT_BUNDLES.includes(pkg)) continue
+      try {
+        const pk = resolvePackageJson(pkg, profileDir)
+        const dir = dirname(pk ?? join(profileDir, 'node_modules', ...String(pkg).split('/'), 'package.json'))
+        const text = await readFile(join(dir, 'cordis.patch.yml'), 'utf8')
+        const lines = text.split(/\r?\n/u)
+        let inInsert = false
+        for (let index = 0; index < lines.length; index += 1) {
+          const line = lines[index]
+          if (/^- insert:\s*$/u.test(line)) {
+            inInsert = true
+            continue
+          }
+          if (/^- /u.test(line)) inInsert = false
+          if (!inInsert) continue
+          const idMatch = line.match(/^ {4}- id: ([A-Za-z0-9_.-]+)\s*$/u)
+          if (!idMatch) continue
+          rows.add(idMatch[1])
+          const nameMatch = (lines[index + 1] ?? '').match(/^ {6}name: ['"]([^'"]+)['"]\s*$/u)
+          if (nameMatch) rows.add(nameMatch[1])
+        }
+      } catch {}
+    }
+  } catch {}
+  return rows
+}
+
+export { readBundlePatchRefNames, readExtraBundleRows }

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

@@ -2,22 +2,22 @@
 // 分层 Step 8c-2 从 lib/index.js 搬出；形参由 ctx 收窄为 ports（调用方注入的窄接口），只搬移未改逻辑。
 // 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
 
-import { readFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { aiRepair } from './ai-run.js'
 import { maybeAutoAdaptCompat } from './compat.js'
 import { getReposDir } from './repoland.js'
 import { aiConsentFailureText, cleanupAttemptedCandidates, pnpmRemove } from './install-cleanup.js'
 import { GIT_CHANNEL_BUDGET_MS, GIT_MIN_ATTEMPT_MS, GIT_SPEC_TIMEOUT_MS, gitChannelBudgetMs, noteChannel, formatBudgetMs, tryGitChannel } from './git-channel.js'
-import { DEFAULT_BUNDLES, AI_CONSENT_TIMEOUT_MS, PNPM_INSTALL_TIMEOUT_MS, addBundleToManifest, backfillMissingDeps, curlManualInstall, detectBundleOnly, ensureBundlePatchIntegrity, githubReleaseInstall, pnpmInstall, raceInstallChannels, readGithubAuth, syncAggregateSubpackageVersions } from './install.js'
-import { readBundlePatchRefNames } from './bundle-refs.js' // 0.5.26 搬家：install.js 贴着 600 行硬顶
+import { AI_CONSENT_TIMEOUT_MS, PNPM_INSTALL_TIMEOUT_MS, addBundleToManifest, backfillMissingDeps, curlManualInstall, detectBundleOnly, ensureBundlePatchIntegrity, githubReleaseInstall, pnpmInstall, raceInstallChannels, readGithubAuth, syncAggregateSubpackageVersions } from './install.js'
+import { readBundlePatchRefNames, readExtraBundleRows } from './bundle-refs.js' // re-export（0.5.46 搬入；0.5.26 已搬 readBundlePatchRefNames）
 import { classifyInstallFailure, retryPnpmOnce } from './install-diagnose.js'
 import { jobLog } from './jobs.js'
 import { gatePrivateRoot } from './repo-size.js'
 import { tryPresetSourceChannel } from './preset-source.js'
 import { settlePresetOutcome } from './preset-in-package.js'
 import { alreadyInstalledTarget, verifyInstalledEntry } from './install-verify.js'
-import { applyNpmNameHint, expandSubpackageCandidates, fetchRepoPackage, fetchRepoPackageEx, fetchSubpackageNames, npmNameHintForRepo, packageProbeErrorText, subpackageCandidates } from './market.js'
+import { applyNpmNameHint, expandSubpackageCandidates, fetchRepoPackage, fetchRepoPackageEx, fetchSubdirPlugins, fetchSubpackageNames, npmNameHintForRepo, packageProbeErrorText, subpackageCandidates } from './market.js'
+import { decideNoRootManifest } from './subdir-detect.js'
 import { finalizeInstallPersistence } from './install-finalize.js'
 import { readPatchState, syncNameFromNote } from './patch.js'
 import { listEntries } from './runtime.js'
@@ -222,6 +222,7 @@ async function runInstallJob(job, ports, deps = {}) {
     fetchRepoPackage,
     fetchRepoPackageEx,
     fetchSubpackageNames,
+    fetchSubdirPlugins,
     subpackageCandidates,
     npmNameHint: npmNameHintForRepo,
     ...(deps.marketProbes ?? {}),
@@ -287,17 +288,31 @@ async function runInstallJob(job, ports, deps = {}) {
       const { pkg, reason } = rootProbe
       if (pkg === null) {
         // 无 package.json：先探测是否技能仓库（含 SKILL.md）→ 自动转技能安装；
-        // 否则标记 hint=repo-land，前端给出「仓库落地」一键入口（克隆到本地目录）。
+        // 2026-10-13 改错（用户实测 Fei2411/DeepSeek-Bot）：**根目录没有清单 ≠ 这个仓库不是插件**。
+        // 真机该仓库根目录只有 docs/ + ds-bot/，而 ds-bot/package.json 同时带 dsh.client 与
+        // dsh.bundle.patch —— 旧代码在这里直接下"不是插件"的结论，结论错、也没给用户下一步。
+        // 现在先向下扫 1–2 层子目录（与 fetchSubpackageNames 的路径口径一致）：
+        //   · 扫到带 dsh 标记的清单 → 明说"插件在 <子目录>/ 下"并给出可复制的安装写法；
+        //   · 扫完确实没有 → 保持旧结论，但文案补上"已检查根目录与 N 层子目录"（诚实）。
         const skillProbe = await detectSkillRepo(job.repo, branch)
         if (skillProbe.hasSkill) {
           job.kind = 'skill'
           await runSkillInstallJob(job, ports)
           return
         }
+        const decided = await decideNoRootManifest({
+          repo: job.repo,
+          branch,
+          reason,
+          probe: probes.fetchSubdirPlugins,
+          baseText: packageProbeErrorText(job.repo, branch, reason),
+          source: job.source,
+        })
         job.status = 'failed'
-        job.hint = 'repo-land'
-        // 文案区分「抓取超时/不可达」与「真的没有」——旧代码两者共用一个出口，报错永远说"文件不存在"
-        job.error = packageProbeErrorText(job.repo, branch, reason)
+        job.hint = decided.hint
+        job.error = decided.error
+        job.subplugin = decided.subplugin
+        if (decided.hint === 'subdir-plugin') return
         job.probeReason = reason
         return
       }
@@ -562,37 +577,9 @@ async function runInstallJob(job, ports, deps = {}) {
     job.finishedAt = Date.now()
   }
 }
-/** 读取用户额外 bundle（非官方模板）的补丁插入行 id 与包名，用于"额外插件"判定。 */
-async function readExtraBundleRows(profileDir) {
-  const rows = new Set()
-  try {
-    const manifest = JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'))
-    const bundles = manifest.dsh?.profile?.bundles ?? []
-    for (const pkg of bundles) {
-      if (DEFAULT_BUNDLES.includes(pkg)) continue
-      try {
-        const pk = resolvePackageJson(pkg, profileDir)
-        const dir = dirname(pk ?? join(profileDir, 'node_modules', ...String(pkg).split('/'), 'package.json'))
-        const text = await readFile(join(dir, 'cordis.patch.yml'), 'utf8')
-        const lines = text.split(/\r?\n/u)
-        let inInsert = false
-        for (let index = 0; index < lines.length; index += 1) {
-          const line = lines[index]
-          if (/^- insert:\s*$/u.test(line)) {
-            inInsert = true
-            continue
-          }
-          if (/^- /u.test(line)) inInsert = false
-          if (!inInsert) continue
-          const idMatch = line.match(/^ {4}- id: ([A-Za-z0-9_.-]+)\s*$/u)
-          if (!idMatch) continue
-          rows.add(idMatch[1])
-          const nameMatch = (lines[index + 1] ?? '').match(/^ {6}name: ['"]([^'"]+)['"]\s*$/u)
-          if (nameMatch) rows.add(nameMatch[1])
-        }
-      } catch {}
-    }
-  } catch {}
-  return rows
-}
-export { runInstallJob, pnpmRemove, readExtraBundleRows, cleanupAttemptedCandidates, aiConsentFailureText, tryCandidateChannels, channelImpls, RELEASE_CHANNEL_BUDGET, GIT_CHANNEL_BUDGET_MS, GIT_SPEC_TIMEOUT_MS, GIT_MIN_ATTEMPT_MS, gitChannelBudgetMs, noteChannel, formatBudgetMs }
+/** 读取用户额外 bundle（非官方模板）的补丁插入行 id 与包名，用于"额外插件"判定。
+ * 实现在 domain/bundle-refs.js（2026-10-13 搬出，只搬移未改逻辑：那边与 insert 行解析同属一件事，
+ * 这边腾出 600 行硬顶）；这里保留同名 re-export —— **对外导出名与调用点一个字都没变**。 */
+export { readExtraBundleRows }
+
+export { runInstallJob, pnpmRemove, cleanupAttemptedCandidates, aiConsentFailureText, tryCandidateChannels, channelImpls, RELEASE_CHANNEL_BUDGET, GIT_CHANNEL_BUDGET_MS, GIT_SPEC_TIMEOUT_MS, GIT_MIN_ATTEMPT_MS, gitChannelBudgetMs, noteChannel, formatBudgetMs }

package/lib/server/domain/install.js

@@ -536,6 +536,10 @@ function installJobView(job) {
     suiteNote: job.suiteNote ?? null, repoSize: job.repoSize ?? null,
     ...presetJobView(job),
     hint: job.hint ?? null,
+    // 子目录插件识别结果（2026-10-13 加法，真机 Fei2411/DeepSeek-Bot：插件在 ds-bot/ 而不是仓库根）。
+    // 下发结构化字段而不只是塞进 error 文案：面板要能**单独把它显示出来**（插件在哪个子目录、
+    // 包名、哪些 dsh 标记），用户才不用从一整段报错里找路径。老客户端忽略该字段（纯加法）。
+    subplugin: job.subplugin ?? null,
     // 子包级/套装级进度（2026-09-20 真装实测缺口：11 个子包的聚合仓库跑了 19 分钟，面板只显示
     // "安装中"，用户不知道在装第几个、还剩几个）。子包通道来自 install-job.js 候选循环维护的
     // candidateXxx；套装通道来自 suite.js 维护的 suiteProgress（clone/装配两阶段）。

package/lib/server/domain/market.js

@@ -5,6 +5,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { detectSkillRepo } from './skills.js'
+import { dshMarkersOf } from './subdir-detect.js'
 import { FETCH_OK, FETCH_UNREACHABLE, GITHUB_API, curlJson, curlText, fetchJsonUrl, githubJson, looksLikeGitmodules, rawTextFetch, rawTextWithFallback } from '../infra/http.js'
 import { ENRICH_CACHE_FILE, baseDirOf, marketIndexCacheFile, resolvePackageJson } from '../infra/paths.js'
 
@@ -379,7 +380,11 @@ function subpackageBranchOrder(branch, defaults = ['main', 'master']) {
   return [...new Set(merged.map((b) => b.trim()))]
 }
 
-/** 单个分支上读子包列表（git trees 递归 + 并行读 package.json 的 name）。 */
+/** 单个分支上读子包列表（git trees 递归 + 并行读 package.json 的 name）。
+ * 2026-10-13 加法：每行多带一个 `markers`（该清单里的 `dsh.bundle` / `dsh.client` 标记，见
+ * subdir-detect.dshMarkersOf）——**零额外网络请求**（package.json 本来就要读来取 name），
+ * 让上层能回答"这个子目录是不是 DSH 插件"，而不是只知道"这里有个包"。
+ * 老调用方（只读 name）签名与语义一字未变（多一个字段属纯加法）。 */
 async function fetchSubpackageNamesOnBranch(repo, branch, auth, { ghJson, rawText }) {
   try {
     const data = await ghJson(`${GITHUB_API}/repos/${repo}/git/trees/${encodeURIComponent(branch)}?recursive=1`, undefined, auth)
@@ -392,7 +397,7 @@ async function fetchSubpackageNamesOnBranch(repo, branch, auth, { ghJson, rawTex
       if (bodyText === null) return null
       try {
         const pkg = JSON.parse(bodyText)
-        if (pkg && typeof pkg.name === 'string') return { dir: path.split('/')[1], path: path.split('/').slice(0, -1).join('/'), name: pkg.name }
+        if (pkg && typeof pkg.name === 'string') return { dir: path.split('/')[1], path: path.split('/').slice(0, -1).join('/'), name: pkg.name, markers: dshMarkersOf(pkg) }
       } catch {}
       return null
     }))
@@ -402,6 +407,32 @@ async function fetchSubpackageNamesOnBranch(repo, branch, auth, { ghJson, rawTex
   }
 }
 
+/** 仓库子目录插件识别（2026-10-13 加法，真机 `Fei2411/DeepSeek-Bot`）：
+ * 根目录没有 package.json 时**向下找** `dsh` 插件（1–2 层，与上面的路径口径一致）。
+ * 返回 `[{ path, name, markers }]`，path 为相对仓库根的目录（如 `ds-bot`）。
+ * 分支按 `subpackageBranchOrder`（已拿到的默认分支打头，再回退 main/master）。
+ * **失败与"确实没有"必须分得开**：扫描抛错/读不到 → 返回 `null`（"没读到"）；
+ * 扫完确实一个都没有 → 返回 `[]`（"没有"）。上层文案据此决定是"未发现"还是
+ * "子目录这一轮没能完整读到，结论只覆盖读到的部分"（`decideNoRootManifest` 的 scanFailed）。
+ * deps 只为单测注入，生产调用不传；**原样透传给 fetchSubpackageNames**（同一个 deps 袋子：
+ * `{ githubJson, rawText }` 走真实现，或 `{ fetchSubpackageNames: 桩 }` 整体替换）——
+ * 上一版用 `deps.fetchDeps` 又包了一层，结果单测的桩拿到空袋子（`rawText is not a function`）。 */
+async function fetchSubdirPlugins(repo, branch, auth = null, deps = {}) {
+  const fetchNames = typeof deps.fetchSubpackageNames === 'function' ? deps.fetchSubpackageNames : fetchSubpackageNames
+  let list = null
+  try {
+    list = await fetchNames(repo, branch, auth, deps)
+  } catch {
+    return null
+  }
+  if (!Array.isArray(list)) return null
+  return list
+    .filter((item) => item !== null && typeof item === 'object' && typeof item.name === 'string' && item.name !== '')
+    .map((item) => ({ path: String(item.path ?? item.dir ?? ''), name: item.name, markers: Array.isArray(item.markers) ? item.markers : [] }))
+    .filter((item) => item.path !== '')
+    .slice(0, 12)
+}
+
 /** 从市场索引里查这个仓库的**首选 npm 包名**（批次 C-⑪，2026-09-27 加法）。
  * 数据源与 /market-index 完全一致：routes/market.js 每次成功拉到索引都会写一份落盘缓存
  * （infra/paths.marketIndexCacheFile），这里读它 —— 与内存缓存等价、且跨重启有效。
@@ -460,12 +491,30 @@ async function expandSubpackageCandidates({ repo, branch = 'main', auth = null,
     .slice(0, limit)
 }
 
+// ── 子包探针的出网回落值收口（可注入 + 红线保险；2026-10-13）────────────────────────────
+// 为什么要有这一层：`test-subdir-plugin.mjs` 的"全程离线"是靠**把桩塞进 deps 袋子**保证的，
+// 而 `fetchSubpackageNames` 在 deps 缺项时会**回落到真实现**（下面的 githubJson /
+// rawTextWithFallback）—— 一旦哪天桩的袋子没接上（本文件已有一次前科：上一版用 deps.fetchDeps
+// 多包了一层，单测的桩拿到空袋子），测试会**先真的发出 GitHub 请求**、然后才红。
+// 那不算守卫（"真出网了也只是事后报错"）。所以把这两个回落值收成**唯一可注入点**：
+//   ① 注入缝：单测 `__setSubpkgProbeDefaults({ ghJson, rawText })` 换成**会抛的 tripwire**
+//      ⇒ 真有代码走到出网，当场红，且一个请求都发不出去（预防，不是事后取证）；
+//   ② 生产不注入（null）⇒ 回落值与改动前逐字相同（githubJson / rawTextWithFallback），行为零变化。
+// 与 routes/components.js 的 `__setOpenFolderSpawn` 同一套做法（那边管进程，这边管出网）。
+let probeEgressDefaults = null
+
+/** 单测注入子包探针的出网回落值：传对象 = 打桩（**不发任何真实请求**）；传 null = 还原生产实现。 */
+function __setSubpkgProbeDefaults(deps) {
+  probeEgressDefaults = deps !== null && typeof deps === 'object' ? deps : null
+  return probeEgressDefaults !== null
+}
+
 /** 服务端列出仓库子包（git trees 递归 + 并行读 package.json 的 name）。
  * branch 可以是**单个分支名**（老调用点不变）或**分支数组**（按序试）；两种形态都会自动
  * 追加 main / master 兜底（见 subpackageBranchOrder）。deps 只为单测注入，生产调用不传。 */
 async function fetchSubpackageNames(repo, branch, auth, deps = {}) {
-  const ghJson = deps.githubJson ?? githubJson
-  const rawText = deps.rawText ?? rawTextWithFallback
+  const ghJson = deps.githubJson ?? probeEgressDefaults?.ghJson ?? githubJson
+  const rawText = deps.rawText ?? probeEgressDefaults?.rawText ?? rawTextWithFallback
   for (const b of subpackageBranchOrder(branch)) {
     // eslint-disable-next-line no-await-in-loop
     const subs = await fetchSubpackageNamesOnBranch(repo, b, auth, { ghJson, rawText })
@@ -489,4 +538,4 @@ async function subpackageCandidates(repo, branch, auth) {
 
 const ENRICH_CACHE_TTL = 24 * 60 * 60 * 1000
 
-export { readEnrichCache, writeEnrichCache, enrichItemOne, enrichItems, normalizePlatformItems, githubRepoInfo, fetchRepoPackage, fetchRepoPackageEx, packageProbeErrorText, searchNpmPackages, searchSubpackageItems, parseRepoFromUrl, hasDirectNameHit, summarizeReadme, readPluginDetails, fetchSubpackageNames, fetchSubpackageNamesOnBranch, subpackageBranchOrder, subpackageCandidates, expandSubpackageCandidates, npmNameHintForRepo, applyNpmNameHint, ENRICH_CACHE_TTL }
+export { readEnrichCache, writeEnrichCache, enrichItemOne, enrichItems, normalizePlatformItems, githubRepoInfo, fetchRepoPackage, fetchRepoPackageEx, packageProbeErrorText, searchNpmPackages, searchSubpackageItems, parseRepoFromUrl, hasDirectNameHit, summarizeReadme, readPluginDetails, fetchSubpackageNames, fetchSubpackageNamesOnBranch, fetchSubdirPlugins, subpackageBranchOrder, subpackageCandidates, expandSubpackageCandidates, npmNameHintForRepo, applyNpmNameHint, ENRICH_CACHE_TTL, __setSubpkgProbeDefaults }

package/lib/server/domain/subdir-detect.js

@@ -0,0 +1,152 @@
+// L1 · domain —— subdir-detect.js（仓库子目录插件识别）
+//
+// 为什么单开一个文件：install-job.js 已经贴着 600 行硬顶（tests/test-architecture-guard.mjs 断言），
+// 而"根目录没有 package.json 时向下扫子目录"是一块自洽的只读逻辑，搬出来还能独立单测。
+//
+// 真机现场（2026-10-13 用户实测）：`Fei2411/DeepSeek-Bot`（topics 含 dsh-plugin）根目录**没有**
+// package.json —— 但 `ds-bot/package.json` 同时声明了 `dsh.client` 与 `dsh.bundle.patch`，
+// 是不折不扣的 DSH 插件。旧判定只看仓库根，于是给用户一句"不是插件"，
+// 既不准（结论错）也不给路（没有下一步）。判据：**向下扫 1–2 层**（`<dir>/package.json`、
+// `<dir>/<sub>/package.json`，与 fetchSubpackageNames 的路径口径完全一致），
+// 命中带 dsh 标记的清单就明说"插件在 <子目录>/ 下"，扫完确实没有才保持旧结论 ——
+// 且文案必须补上"已检查根目录与 N 层子目录"（诚实：让用户知道我们看过哪里）。
+//
+// 分层：本文件属 L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+
+/** 清单里的 DSH 插件标记（`dsh.bundle` / `dsh.client` 任一）。
+ * 判据与官方安装器一致：`dsh.bundle.patch` 说明是 bundle 层包（其 cordis.patch.yml 会被组合进树），
+ * `dsh.client` 说明带 UI 入口 —— 两者任一即"这是给 DSH 用的包"。
+ * 纯函数（单测覆盖）：JSON 解析失败、`dsh` 不是对象、字段类型不对，一律返回 []，绝不抛。 */
+function dshMarkersOf(pkg) {
+  const out = []
+  try {
+    if (pkg === null || typeof pkg !== 'object') return out
+    const dsh = pkg.dsh
+    if (dsh !== null && typeof dsh === 'object') {
+      if (typeof dsh.bundle?.patch === 'string' && dsh.bundle.patch !== '') out.push('dsh.bundle.patch')
+      if (dsh.client !== null && dsh.client !== undefined) out.push('dsh.client')
+    }
+  } catch {
+    return []
+  }
+  return out
+}
+
+/** 读一段 package.json 文本（已从网络/磁盘拿到）→ 归一化的包信息。
+ * 返回 `{ name, markers, privateRoot }`；解析失败或没有合法名字返回 null
+ * （"读到了但不算包"与"没读到"是两件事，这里只管前者，调用方负责后者）。 */
+function describeDshManifest(text) {
+  try {
+    const pkg = JSON.parse(text)
+    if (pkg === null || typeof pkg !== 'object') return null
+    if (typeof pkg.name !== 'string' || pkg.name === '') return null
+    return { name: pkg.name, markers: dshMarkersOf(pkg), privateRoot: pkg.private === true }
+  } catch {
+    return null
+  }
+}
+
+/** 把"已知子包清单"（各行含 path / name / markers）折成**用户可读的结论**（纯函数，单测覆盖）。
+ *
+ * `subs` 形态与 market.js 的 `fetchSubdirPlugins` 返回值一致：
+ * `[{ path: 'ds-bot', name: 'ds-bot', markers: ['dsh.client', 'dsh.bundle.patch'] }, …]`
+ *
+ * 返回：
+ *   · found=true  → `{ dir, packageName, markers, checkedDirs }`（插件在哪个子目录）
+ *   · found=false → `{ checkedDirs }`（真扫过这些目录，一个 dsh 清单都没有）
+ * `checkedDirs` 永远如实列出**本次真的读到清单的那些目录**（没读到的用 `scanned` 计数带过），
+ * 这样文案里那句"已检查 N 层子目录"是有据可查的，而不是一句空话。 */
+function pickSubdirPlugin(subs) {
+  const list = (Array.isArray(subs) ? subs : []).filter((s) => s !== null && typeof s === 'object')
+  const checkedDirs = list.map((s) => String(s.path ?? s.dir ?? '')).filter((d) => d !== '')
+  const hit = list.find((s) => Array.isArray(s.markers) && s.markers.length > 0)
+  if (hit === undefined) return { found: false, checkedDirs }
+  return {
+    found: true,
+    dir: String(hit.path ?? hit.dir ?? ''),
+    packageName: typeof hit.name === 'string' && hit.name !== '' ? hit.name : String(hit.path ?? '').split('/').pop(),
+    markers: [...hit.markers],
+    checkedDirs,
+  }
+}
+
+/** 命中子目录插件时的用户可读结论（纯函数，单测覆盖）。
+ * 要点（对应用户实测的质疑"它不是 DSH 插件吗"）：
+ *   ① 先**纠正结论** —— 这不是"不是插件"，而是"插件不在根目录"；
+ *   ② 给出**子目录路径**与**包名**，以及标记来源（dsh.bundle.patch / dsh.client）—— 判据可核验；
+ *   ③ 给出**可复制的下一步**（按包名安装）；并**如实说明**"从子目录直接装"当前不支持
+ *      （git 通道只装仓库根包，见 domain/git-channel.js 的核实逻辑）—— 不假装支持。 */
+function subdirPluginText(repo, branch, pick, source = 'github') {
+  const dir = String(pick?.dir ?? '')
+  const pkgName = String(pick?.packageName ?? '')
+  const markers = Array.isArray(pick?.markers) ? pick.markers.join('、') : ''
+  return `仓库 ${repo}（${branch} 分支）根目录没有 package.json，但**插件在子目录 ${dir}/ 下**`
+    + `（${dir}/package.json 声明了 DSH 标记：${markers}）。`
+    + `它就是 DSH 插件，只是清单不在仓库根——${pkgName === '' ? '该子包的包名没能读到' : `包名是 ${pkgName}`}。`
+    + `下一步：${pkgName === '' ? '先按「仓库落地」克隆到本地查看该子目录，' : `该包若已发布到 npm，可直接安装：dsh plugin --profile <你的 profile> add ${pkgName}；否则`}`
+    + `本控制台暂不支持"从子目录直接安装"（git 通道只装仓库根包，装了也是根包而不是 ${dir}/），`
+    + `可把该子目录并进一个独立仓库或等作者发布 npm 包后再装。`
+}
+
+/** 扫完根目录与子目录都没找到插件时的用户可读结论（纯函数，单测覆盖）。
+ * 与 packageProbeErrorText 的分工：那个只管"根目录为什么没读到"（超时/非法/确实没有），
+ * 这里补上**本次到底检查了哪里**（子目录层数 + 读到清单的目录名），
+ * 让"不是插件"这个结论有据可查，而不是一句没有出处的断言。
+ *
+ * `scanFailed`（2026-10-13 补）：子目录这一轮**没能扫成**（探针抛错 / 返回非数组 / 根本没给探针）时，
+ * 结论句必须从"未发现声明 dsh 标记的 package.json"降级成"只覆盖读到的部分" ——
+ * 否则一次网络限流就会变成一句比事实更强的断言（"没有"≠"没读到"）。
+ * `reason` 是根清单探测的原因码：`FETCH_UNREACHABLE`（'unreachable'）同理降级。 */
+function notPluginText(repo, branch, reason, checkedCount, subCount, baseText = '', scanFailed = false) {
+  const head = baseText !== '' ? baseText.replace(/。$/u, '') : `仓库 ${repo}（${branch} 分支）不是可安装的插件`
+  const partial = scanFailed || reason === 'unreachable' || subCount > checkedCount
+  const scope = `已检查根目录与 2 层子目录（本次读到清单的子目录 ${checkedCount} 个`
+    + `${subCount > checkedCount ? `，另有 ${subCount - checkedCount} 个目录清单没读到（可能是网络受限，不代表不存在）` : ''}）`
+  const verdict = partial
+    ? '；子目录这一轮没能完整读到，所以"没有 dsh 插件"这条结论只覆盖读到的部分'
+    : '，未发现声明 dsh 标记的 package.json'
+  return `${head}。${scope}${verdict}。`
+}
+
+/** 根目录没有清单时**唯一**的结论出口（纯函数，单测覆盖）：把扫描结果折成
+ * 服务端 job 上要写的那几个字段（hint / error / subplugin），调用方（install-job）只剩赋值。
+ * 为什么要把出口收成一个函数：两个分支必须**互斥且都给出路** —— 命中子目录插件时文案说
+ * "插件在 <子目录>/ 下 + 下一步"，没命中时文案必须补"已检查根目录与 2 层子目录"（诚实）。
+ * 任何"分支走错一句话"的变异都会被 tests/test-subdir-plugin.mjs 抓住。
+ * `probe`（可选）负责真去扫 —— 注入缝与 install-job 的 marketProbes 同一套语义：
+ * 传桩函数即可离线断言"扫到了什么就说什么"，生产调用传真的 fetchSubdirPlugins。
+ * 探针**抛错或返回非数组**（含 fetchSubdirPlugins 的"扫描失败 → null"契约）⇒ `scanFailed=true`：
+ * 结论照旧给，但文案降级为"只覆盖读到的部分"（"没读到"绝不冒充"没有"）。 */
+async function decideNoRootManifest({ repo, branch, reason, subScan = null, probe = null, baseText = '', source = 'github' } = {}) {
+  let scan = []
+  let scanFailed = false
+  if (Array.isArray(subScan)) {
+    scan = subScan
+  } else if (typeof probe === 'function') {
+    try {
+      const result = await probe(repo, branch)
+      if (Array.isArray(result)) scan = result
+      else scanFailed = true
+    } catch {
+      scanFailed = true
+    }
+  } else {
+    // 没给探针 = 这一轮根本没扫过子目录 —— 不许假装"检查过了"
+    scanFailed = true
+  }
+  const pick = pickSubdirPlugin(scan)
+  if (pick.found === true) {
+    return {
+      hint: 'subdir-plugin',
+      subplugin: { dir: pick.dir, packageName: pick.packageName, markers: pick.markers, checkedDirs: pick.checkedDirs },
+      error: subdirPluginText(repo, branch, pick, source),
+    }
+  }
+  return {
+    hint: 'repo-land',
+    subplugin: null,
+    error: notPluginText(repo, branch, reason, pick.checkedDirs.length, Array.isArray(scan) ? scan.length : 0, baseText, scanFailed),
+  }
+}
+
+export { dshMarkersOf, describeDshManifest, pickSubdirPlugin, subdirPluginText, notPluginText, decideNoRootManifest }

package/lib/server/routes/components.js

@@ -1,8 +1,8 @@
 // L2 · routes —— 组件与仓库落地（/components · /component/* · /repo-*）
 // 分层 Step 8b：从 lib/index.js 的 handle() 原样搬出（只搬移未改逻辑；缩进保持原样）
 
-import { existsSync, mkdirSync } from 'node:fs'
-import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, statSync } from 'node:fs'
+import { spawn } from 'node:child_process'
 import { join } from 'node:path'
 import { compFind, compStart, compStatus, compStop, compUiUrl, compUpsert, findComponents } from '../domain/components.js'
 import { getReposDir, listLandedRepos, setReposDir } from '../domain/repoland.js'
@@ -151,6 +151,159 @@ async function routeRepoRemove(req, res, rc) {
     return
 }
 
+/** 「打开文件夹」用的文件管理器（Windows=explorer.exe；macOS=open；其余=xdg-open）。 */
+function openFolderBin() {
+  if (process.platform === 'win32') return 'explorer.exe'
+  return process.platform === 'darwin' ? 'open' : 'xdg-open'
+}
+
+// ── 唯一进程创建点（可注入 + 默认安全；2026-10-13 两次事故记录）──────────────────────────
+// 事故一（0.5.45）：上一批测试为了覆盖"成功路径"直接调真路由 ⇒ 真的起了 explorer.exe，而夹具路径
+// 当时不存在 ⇒ 用户桌面弹出 Windows「位置不可用」对话框。
+// 事故二（0.5.46 施工中）：又弹了一次 —— 根因是**默认不安全**：那时"默认真 spawn，只靠外部设
+// DSH_OPEN_FOLDER_NO_SPAWN=1 才拦得住"，任何人/任何 CI 不带那个变量跑测试就会重新踩到。
+// ⇒ 现在把语义**反过来**：真 spawn 必须**显式 opt-in**，缺席时的默认结局是**被拒绝**（不是弹窗）。
+// 进程创建只此一处，四重防线：
+//   ① 注入缝：单测 `__setOpenFolderSpawn(stub)` 换成桩（一次进程都不建）；
+//   ② 保险丝：`DSH_OPEN_FOLDER_NO_SPAWN=1` 时**绝不**走到 spawn —— 如实返回结构化拒绝
+//      （不是静默跳过：调用方照旧把这条原因报给用户）；
+//   ③ **默认安全（opt-in）**：回落到真 `defaultSpawn` 需要 `allowRealSpawn:true` 或
+//      `DSH_OPEN_FOLDER_ALLOW_REAL_SPAWN=1`；两者都没有 ⇒ 结构化拒绝。生产的 routeRepoOpen 是
+//      唯一的 opt-in 调用方 —— 于是"测试漏了注入"的默认结局是**红/被拒**，而不是弹用户一个窗口；
+//   ④ 计数：真实 spawn 调用次数可读，测试断言恒为 0；`__openFolderSelfCheck()` 是计数器的正控
+//      （真的起一次**不弹任何窗口**的进程，证明计数不是死的 —— 桩自校验，本仓既有做法）。
+let injectedSpawn = null
+let realSpawnCalls = 0
+
+/** 真 spawn 的**显式 opt-in**（默认拒绝；见 openFolderVerified 第 ③ 条）。 */
+function realSpawnOptIn(allowRealSpawn) {
+  return allowRealSpawn === true || process.env.DSH_OPEN_FOLDER_ALLOW_REAL_SPAWN === '1'
+}
+
+function defaultSpawn(bin, args, options) {
+  realSpawnCalls += 1
+  return spawn(bin, args, options)
+}
+
+/** 单测注入启动桩：传函数 = 打桩（**不创建任何进程**）；传 null = 还原生产实现。 */
+function __setOpenFolderSpawn(fn) {
+  injectedSpawn = typeof fn === 'function' ? fn : null
+  return injectedSpawn !== null
+}
+
+/** 真实子进程创建次数（测试断言本套跑完仍为 0）。 */
+function __openFolderRealSpawnCalls() {
+  return realSpawnCalls
+}
+
+/** 计数器正控（桩自校验）：用**生产同一个** defaultSpawn 起一次 node -e ""（无窗口、无副作用），
+ * 返回它是否被计数到。返回 false ⇒ 计数桩坏了，测试必须据此响亮失败，而不是拿 0 当"没启动过"。 */
+async function __openFolderSelfCheck() {
+  const before = realSpawnCalls
+  try {
+    const child = defaultSpawn(process.execPath, ['-e', ''], { windowsHide: true, stdio: 'ignore' })
+    child.on('error', () => {})
+    await new Promise((resolve) => { child.on('exit', resolve); setTimeout(resolve, 2000) })
+  } catch {
+    return { ok: false, counted: realSpawnCalls - before }
+  }
+  return { ok: realSpawnCalls - before === 1, counted: realSpawnCalls - before }
+}
+
+/** 路径能否"打开文件夹"：存在且是目录（文件也给开，交给文件管理器处理）。
+ * 返回 null 表示可以打开，否则是给用户看的原因（不抛）。 */
+function openFolderPathIssue(target) {
+  try {
+    const st = statSync(target)
+    return st.isDirectory() || st.isFile() ? null : `${target} 既不是文件也不是目录`
+  } catch (error) {
+    const code = error?.code ?? ''
+    if (code === 'ENOENT') return `目录不存在：${target}（可能已被删除或改名，请刷新落地列表）`
+    return `读不到该路径：${target}（${error instanceof Error ? error.message : String(error)}）`
+  }
+}
+
+/** 打开文件夹的**可判定**执行器（2026-10-13 改错，用户实测「点了没反应」）：
+ * 旧实现是 `execFile('explorer.exe', [target], {detached:true}).unref()` —— **即发即忘**：
+ *   ① 没有 error 监听（spawn 失败如 ENOENT 是**异步** 'error' 事件，try/catch 抓不到，
+ *      实测：`spawn('不存在的.exe')` 在 try 块内不抛，一个 tick 后才在 error 事件里出现）；
+ *   ② 立刻回 `{ok:true}` —— 失败也报成功（假绿），用户拿不到任何判据；
+ *   ③ 客户端又把非 2xx 统一吞掉（`catch {}`）⇒ 用户那边**一个字都看不到**。
+ * 现在：启动后**等它的结局**再回话（对象只描述观察到的事实）：
+ *   · 'error'（ENOENT/EACCES…）→ ok:false + 系统原话（这就是"失败必须说出来"的正身）；
+ *   · 'exit' → ok:true，退出码与用时**如实带上**（真机 explorer.exe 把请求交给已有 shell 进程后
+ *     自己退出，退出码常是 1；这是委派而非失败，所以不判红，但也绝不谎称"窗口已打开"）；
+ *   · 超时仍在跑 → ok:true 且注明"未在 Nms 内退出"。
+ * 判据（本仓口径）：宁可红也不报假绿；静默一律不许。 */
+function openFolderVerified({ target, bin = null, spawnFn = null, launchWaitMs = 1200, allowRealSpawn = false } = {}) {
+  const started = Date.now()
+  return new Promise((resolve) => {
+    // ② 保险丝：测试红线。**先于任何进程创建**判定，且如实说明被拦下的原因。
+    if (process.env.DSH_OPEN_FOLDER_NO_SPAWN === '1') {
+      resolve({
+        ok: false,
+        reason: 'spawn-guard',
+        durationMs: Date.now() - started,
+        error: '测试红线：本进程禁止真的启动文件管理器（DSH_OPEN_FOLDER_NO_SPAWN=1）',
+      })
+      return
+    }
+    // ③ **默认安全**（2026-10-13 第二次事故后收紧）：回落到**底层真 spawn**（defaultSpawn）需要
+    //    **显式 opt-in**；注入桩（spawnFn / __setOpenFolderSpawn）不在此列（调用方自担，且不建进程）。
+    //    为什么必须这样：旧形态是"默认真 spawn，靠外部设 DSH_OPEN_FOLDER_NO_SPAWN 才拦住"——
+    //    任何一条测试路径漏了注入（或忘了设那个环境变量）就会真的起 explorer.exe 指到夹具目录，
+    //    在用户桌面弹出「位置不可用」（真机第二次事故）。现在"漏了注入"的默认结局是**被拒绝**，
+    //    不是弹窗。生产的 routeRepoOpen 是本函数**唯一**的 opt-in 调用方（它代表"用户点了按钮"）。
+    const injected = typeof spawnFn === 'function' ? spawnFn : injectedSpawn
+    if (injected === null && !realSpawnOptIn(allowRealSpawn)) {
+      resolve({
+        ok: false,
+        reason: 'spawn-guard',
+        durationMs: Date.now() - started,
+        error: '测试红线：本进程默认禁止真的启动文件管理器 —— 真 spawn 需显式 opt-in（openFolderVerified({allowRealSpawn:true}) 或 DSH_OPEN_FOLDER_ALLOW_REAL_SPAWN=1）',
+      })
+      return
+    }
+    const launch = injected ?? defaultSpawn
+    const command = typeof bin === 'string' && bin !== '' ? bin : openFolderBin()
+    let child = null
+    try {
+      // stdio:'ignore' —— 不建管道（旧 execFile 默认管道 + unref 会留下未 unref 的 pipe 句柄），
+      // detached:true 让文件管理器窗口在插件宿主退出后依然在。
+      child = launch(command, [target], { windowsHide: true, detached: true, stdio: 'ignore' })
+    } catch (error) {
+      resolve({ ok: false, reason: 'spawn-throw', durationMs: Date.now() - started, error: error instanceof Error ? error.message : String(error) })
+      return
+    }
+    let done = false
+    const finish = (payload) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      resolve({ durationMs: Date.now() - started, ...payload })
+    }
+    const timer = setTimeout(() => finish({
+      ok: true,
+      reason: 'launched',
+      exited: false,
+      note: `已向 ${command} 发出打开请求，进程在 ${launchWaitMs}ms 内未退出（窗口通常已弹出）`,
+    }), launchWaitMs)
+    child.on('error', (error) => finish({
+      ok: false,
+      reason: 'spawn-error',
+      code: error?.code ?? null,
+      error: error instanceof Error ? error.message : String(error),
+    }))
+    child.on('exit', (code, signal) => finish({
+      ok: true,
+      reason: 'exited',
+      code,
+      note: `${command} 进程已退出（exit ${code ?? '?'}${signal ? `/${signal}` : ''}，用时 ${Date.now() - started}ms）—— 请求已交给系统文件管理器`,
+    }))
+    try { child.unref?.() } catch {}
+  })
+}
+
 async function routeRepoOpen(req, res, rc) {
   const ctx = rc.ctx
   const url = rc.url
@@ -161,19 +314,41 @@ async function routeRepoOpen(req, res, rc) {
     const rootNorm = getReposDir().replace(/[\\/]+$/u, '')
     const tNorm = target.replace(/[\\/]+$/u, '')
     if (!tNorm.startsWith(rootNorm) || tNorm === rootNorm) {
-      sendError(res, 400, '路径不在仓库落地目录内')
+      // 守卫照旧（只允许落地目录内的路径），但**必须说清为什么被拒** ——
+      // 旧实现只回一句 400，客户端又把它吞了 ⇒ 用户看到的就是"点了没反应"。
+      sendError(res, 400, `为安全起见只能打开仓库落地目录内的路径：${target || '（空路径）'} 不在 ${getReposDir()} 内`)
       return
     }
     if (!existsSync(target)) {
-      sendError(res, 404, `目录不存在：${target}`)
+      sendError(res, 404, `目录不存在：${target}（可能已被删除或改名，请刷新落地列表）`)
       return
     }
-    try {
-      execFile('explorer.exe', [target], { windowsHide: true, detached: true }).unref()
-      sendJson(res, 200, { ok: true })
-    } catch (error) {
-      sendError(res, 500, `打开失败：${error instanceof Error ? error.message : String(error)}`)
+    const issue = openFolderPathIssue(target)
+    if (issue !== null) {
+      sendError(res, 400, `无法打开：${issue}`)
+      return
+    }
+    // 启动点是注入缝（单测经 rc.deps.openFolderLauncher 打桩，**绝不真的起文件管理器**）；
+    // 生产 routeDeps 不带这个键 ⇒ 走 openFolderVerified 的实现。
+    const launch = typeof rc.deps?.openFolderLauncher === 'function' ? rc.deps.openFolderLauncher : openFolderVerified
+    // 生产唯一的 opt-in 调用方：用户点了「打开文件夹」按钮，才允许回落到真 spawn。
+    const result = await launch({ target, bin: openFolderBin(), allowRealSpawn: true })
+    if (result.ok !== true) {
+      sendError(res, 500, `打开文件夹失败：${result.error ?? result.reason}（命令：${openFolderBin()} ${target}）`)
+      return
     }
+    // 如实回结构化状态：成功也带证据（用时/退出码/note），前端据此显示结果而不是静默。
+    sendJson(res, 200, {
+      ok: true,
+      path: target,
+      target,
+      action: 'open-folder',
+      via: openFolderBin(),
+      reason: result.reason,
+      durationMs: result.durationMs ?? null,
+      exitCode: typeof result.code === 'number' ? result.code : null,
+      note: typeof result.note === 'string' ? result.note : '',
+    })
     return
 }
 
@@ -258,4 +433,4 @@ async function routeComponentStatus(req, res, rc) {
     return
 }
 
-export { routeComponents, routeRepoClone, routeRepoList, routeRepoLandConfig, routeRepoRemove, routeRepoOpen, routeComponentAutostart, routeComponentStart, routeComponentStop, routeComponentStatus }
+export { routeComponents, routeRepoClone, routeRepoList, routeRepoLandConfig, routeRepoRemove, routeRepoOpen, routeComponentAutostart, routeComponentStart, routeComponentStop, routeComponentStatus, openFolderBin, openFolderVerified, __setOpenFolderSpawn, __openFolderRealSpawnCalls, __openFolderSelfCheck }

package/lib/server/routes/framework.js

@@ -1,10 +1,10 @@
 // L2 · routes —— 框架（/framework-check · /check-update · /framework-upgrade · /framework-rollback · /framework-upgrade-status · /framework-relaunch · /compat-gate · /restart）
 // 分层 Step 8b：从 lib/index.js 的 handle() 原样搬出（只搬移未改逻辑；缩进保持原样）
 
-import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, rmSync } from 'node:fs'
 import { writeFile } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, join, resolve, basename } from 'node:path'
 import { tmpdir } from 'node:os'
 import { createRequire } from 'node:module'
 import { readCompatGate, writeCompatGate } from '../domain/compat.js'
@@ -460,14 +460,56 @@ async function routeRestart(req, res, rc) {
 }
 
 /** 清掉「最近一次升级/回滚记录」（2026-09-25 用户要求）：记录常驻是设计，但用户要能一键关掉。
- *  只删状态文件与心跳（不动日志，日志仍可在 ~/.dsh/plugin-console 里查）。 */
+ *  只删状态文件与心跳（不动日志，日志仍可在 ~/.dsh/plugin-console 里查）。
+ *  2026-10-11 改错：删除失败**如实上报**（500 + 每个文件的原因 + removed/failed 明细），
+ *  不再像旧实现那样吞掉异常还回 ok:true —— 静默失败一律不许（见函数内注释与
+ *  tests/test-framework-status-clear.mjs 的正控/负控）。 */
+/** 删文件失败时给用户看的一句话原因（code + 系统原文，便于判因）。 */
+function explainRemoveError(error) {
+  const code = typeof error?.code === 'string' && error.code !== '' ? error.code : 'UNKNOWN'
+  const text = (error instanceof Error ? error.message : String(error ?? '')).split('\n')[0].trim()
+  return text === '' ? code : `${code}: ${text}`
+}
+
+/** 删除时文件已不在 = 目标达成（不计失败）；其余错误一律算失败。 */
+function removeTargetGone(error) {
+  return error?.code === 'ENOENT'
+}
+
 async function routeFrameworkStatusClear(req, res, rc) {
   const dir = join(dshHome(), 'plugin-console')
   const state = join(dir, 'fw-upgrade-state.txt')
+  const io = rc.deps?.fs ?? { existsSync, rmSync } // 注入缝：负控要能造出真实的删除失败
   const removed = []
+  const failed = []
   for (const f of [state, `${state}.hb`]) {
-    try { if (existsSync(f)) { rmSync(f, { force: true }); removed.push(basename(f)) } } catch {}
+    let present = false
+    try { present = io.existsSync(f) === true } catch (error) { failed.push({ file: basename(f), reason: explainRemoveError(error) }); continue }
+    if (!present) continue
+    try {
+      io.rmSync(f, { force: true })
+      removed.push(basename(f))
+    } catch (error) {
+      // 2026-10-11 改错：这里原来是 `catch {}` + 无条件 ok:true —— 静默失败。
+      // 先前的真实现状更糟：rmSync/basename 没 import ⇒ 每轮都抛 ReferenceError、被空 catch 吞掉，
+      // 路由照样回 200 {"ok":true,"removed":[]}，标记文件一个都没删（用户以为清掉了）。
+      // 判据（用户红线）：宁可红，也不报假的绿 —— 删除失败必须如实上报原因。
+      if (removeTargetGone(error)) { removed.push(basename(f)); continue }
+      failed.push({ file: basename(f), reason: explainRemoveError(error) })
+    }
+  }
+  if (failed.length > 0) {
+    // 如实上报：500 + 每个文件的原因 + 与成功路径同形的 removed/status 字段（客户端不必猜）。
+    sendJson(res, 500, {
+      ok: false,
+      error: `清除升级记录失败：${failed.map((x) => `${x.file}（${x.reason}）`).join('、')}`,
+      removed,
+      failed,
+      status: 'clear-failed',
+      message: null,
+    })
+    return
   }
-  sendJson(res, 200, { ok: true, removed, status: 'idle', message: null })
+  sendJson(res, 200, { ok: true, removed, failed, status: 'idle', message: null })
 }
 export { refuseWhenShellHosted, refuseWhenPlatformUnsupported, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart }

package/package.json

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