@noob-stupid/dsh-plugin-console 0.5.25 → 0.5.26

package/lib/client.js

@@ -129,6 +129,12 @@ window.__ModuleLoader__.load({
 			actionAllowOk: "已写入放行项",
 			actionAllowFailed: "放行失败（文件未改动）",
 			actionAllowBackup: "备份",
+			// 2026-09-27 加法（0.5.26 修 F2）：预设装配**默认只补不覆盖**；出现同名冲突时多出这一个按钮。
+			// 短句进面板，长解释（含"会先整目录备份"）一律进悬浮 title。
+			actionOverwritePresetLabel: "覆盖该预设",
+			actionOverwritePresetLong: "只有你点它才会覆盖：先按记录的源码出处重新取一次仓库里的预设，把原目录**整份备份**成 <预设名>.bak-<时间戳>，再逐文件覆盖，写完读回核实（字节不一致会如实报告）。默认装配只补缺失文件、绝不覆盖你在用的同名预设。",
+			actionOverwritePresetOk: "已覆盖（原目录已备份）",
+			actionOverwritePresetFailed: "覆盖失败（文件未改动）",
 			safetyMode: "运行模式",
 			safetyModeManaged: "托管：框架升级与回滚由本控制台负责（默认，行为与之前一致）",
 			safetyModeManagedOn: "已切到托管模式：框架升级与回滚仍由本控制台负责",
@@ -663,6 +669,11 @@ window.__ModuleLoader__.load({
 			actionAllowOk: "Approval written",
 			actionAllowFailed: "Approval failed (file untouched)",
 			actionAllowBackup: "Backup",
+			// 2026-09-27 additive (0.5.26 F2): preset assembly is add-only by default; a same-name conflict shows this button.
+			actionOverwritePresetLabel: "Overwrite this preset",
+			actionOverwritePresetLong: "Nothing is overwritten until you click this: it re-fetches the preset from its recorded source repo, copies your whole current directory to <preset>.bak-<timestamp> first, then overwrites file by file and reads every file back to verify (a byte mismatch is reported, never hidden). By default assembly only adds missing files and never touches your same-name presets.",
+			actionOverwritePresetOk: "Overwritten (original backed up)",
+			actionOverwritePresetFailed: "Overwrite failed (files untouched)",
 			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",
@@ -5240,17 +5251,22 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 			// 只在**执行结果**说明"pnpm 因构建脚本未获批准而报错"时才出现（服务端下发 state.nextAction）；
 			// 平时一个像素都不多占。
 			const [allow, setAllow] = react.useState({ phase: "idle", text: null, level: null, title: null });
+			// 2026-09-27 加法（0.5.26 修 F2）：第三个显式动作的状态（「覆盖该预设」）。
+			// 只在服务端下发的 suggestedAction.kind === "overwrite-preset" 时出现（默认装配只补不覆盖）。
+			const [overwrite, setOverwrite] = react.useState({ phase: "idle", text: null, level: null, title: null });
 			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")
 					: action.kind === "allow-builds" ? t("actionAllowLabel")
-						: (typeof action.label === "string" && action.label !== "" ? action.label : String(action.kind ?? ""));
+						: action.kind === "overwrite-preset" ? t("actionOverwritePresetLabel")
+							: (typeof action.label === "string" && action.label !== "" ? action.label : String(action.kind ?? ""));
 			const allowAction = state.nextAction !== null && state.nextAction !== undefined && typeof state.nextAction === "object"
 				? state.nextAction
 				: (action.kind === "allow-builds" ? action : null);
 			const allowRunning = allow.phase === "running";
+			const overwriteRunning = overwrite.phase === "running";
 			const showAllow = allowAction !== null && typeof allowAction.command === "string" && allow.phase !== "done";
 			const run = () => {
 				if (running || action.payload === null || typeof action.payload !== "object") return;
@@ -5301,6 +5317,27 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 					(error) => setAllow({ phase: "error", text: (error !== null && typeof error.message === "string" && error.message !== "" ? error.message : t("actionAllowFailed")), level: "error", title: null }),
 				);
 			};
+			// 「覆盖该预设」：同样是**结构化动作**（只发 action.payload），服务端自己重新取源码 + 备份 + 覆盖 + 读回核实；
+			// 面板绝不拼命令、也绝不碰 .agent-presets。
+			const runOverwrite = () => {
+				if (overwriteRunning || action.payload === null || typeof action.payload !== "object") return;
+				setOverwrite({ phase: "running", text: t("actionRunning"), level: null, title: null });
+				callAction(action.payload).then(
+					(done) => {
+						const verdict = done?.ok === true ? t("actionOverwritePresetOk") : t("actionOverwritePresetFailed");
+						const parts = [verdict, typeof done?.reason === "string" ? done.reason : null, Array.isArray(done?.notes) && done.notes.length > 0 ? done.notes[0] : null].filter((s) => typeof s === "string" && s !== "");
+						setOverwrite({
+							phase: done?.ok === true ? "done" : "error",
+							text: parts.join(" · "),
+							level: done?.ok === true ? null : "warn",
+							title: [done?.file,
+								Array.isArray(done?.overwritten) && done.overwritten.length > 0 ? t("actionOverwritePresetLabel") + "：" + done.overwritten.join("、") : null,
+								typeof done?.backup === "string" ? t("actionAllowBackup") + "：" + done.backup : null].filter((s) => typeof s === "string" && s !== "").join("\n") || null,
+						});
+					},
+					(error) => setOverwrite({ phase: "error", text: (error !== null && typeof error.message === "string" && error.message !== "" ? error.message : t("actionOverwritePresetFailed")), level: "error", title: null }),
+				);
+			};
 			return el("div", { className: styles.detail, "data-suggested-action": String(action.kind ?? "") },
 				el("div", { className: styles.rowTop },
 					el("span", { className: styles.phase }, t("actionBoxTitle")),
@@ -5321,6 +5358,12 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 					showAllow
 						? el("button", { type: "button", className: styles.toggle, "data-allow-builds": "true", title: t("actionAllowLong"), disabled: allowRunning, onClick: runAllow }, allowRunning ? t("actionRunning") : t("actionAllowLabel"))
 						: null,
+					// ★ 0.5.26 加法（修 F2）：预设装配**默认只补不覆盖**，出现同名冲突时多出这一个按钮。
+					// 与上面同一个模式：只发结构化 payload（服务端自己重新取源码 + 备份 + 覆盖 + 读回核实），
+					// 面板绝不拼命令、也绝不写 .agent-presets。
+					action.kind === "overwrite-preset" && overwrite.phase !== "done"
+						? el("button", { type: "button", className: styles.toggle, "data-overwrite-preset": String(action.payload?.presetName ?? ""), title: t("actionOverwritePresetLong"), disabled: overwriteRunning, onClick: runOverwrite }, overwriteRunning ? t("actionRunning") : t("actionOverwritePresetLabel"))
+						: null,
 					el("span", {
 						className: styles.message,
 						"data-warn": state.level === "warn" ? "true" : undefined,
@@ -5333,7 +5376,14 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 						"data-warn": allow.level === "warn" ? "true" : undefined,
 						"data-error": allow.level === "error" ? "true" : undefined,
 						title: allow.title === null ? undefined : allow.title,
-					}, allow.text)));
+					}, allow.text)),
+				overwrite.text === null ? null : el("div", { className: styles.rowTop },
+					el("span", {
+						className: styles.message,
+						"data-warn": overwrite.level === "warn" ? "true" : undefined,
+						"data-error": overwrite.level === "error" ? "true" : undefined,
+						title: overwrite.title === null ? undefined : overwrite.title,
+					}, overwrite.text)));
 		}
 		
 		function PluginSafetyTab({ t }) {

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

@@ -0,0 +1,41 @@
+// L1 · domain —— bundle-refs.js（读**已装聚合包**的 bundle patch 引用清单）
+//
+// 为什么单开一个模块（0.5.26）：install.js 贴着 600 行架构硬顶（test-architecture-guard.mjs），
+// 而"从 node_modules/<pkg>/cordis.patch.yml 里读出 insert 行引用了哪些包名"是一块自洽的只读逻辑，
+// 装前校验（install-job 的注册前防线）与装后完整性保障都要用。抽出**只搬移未改逻辑**。
+//
+// 背景事故（2026-09-06）：装 dsh-desktop 类插件时其 bundle patch 引用了 `@deepseek-ai/dsh-root`
+// 等框架级行，那些包不在 profile node_modules → 注册后整服务启动崩溃。
+// 注册前先按本模块读出的引用逐个 `resolvePackageJson` 核实，缺失即拒绝注册。
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 读取聚合包 `cordis.patch.yml` 的 insert 行 name 列表（注册前校验用）。
+ *  解析形状与 install.js#ensureBundlePatchIntegrity 同构：`- insert:` 块下的
+ *  `- id: xxx` + 下一行 `      name: '包名'`。读不到（没装 / 没声明 dsh.bundle.patch / 文件缺失）
+ *  一律返回 `[]` —— 调用方据此判定"没有可核实的引用"，而不是把它当成错误。 */
+function readBundlePatchRefNames(profileDir, pkgName) {
+  try {
+    const pkgJsonPath = join(profileDir, 'node_modules', pkgName, 'package.json')
+    if (!existsSync(pkgJsonPath)) return []
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
+    const patchRel = pkg.dsh?.bundle?.patch
+    if (typeof patchRel !== 'string') return []
+    const text = readFileSync(join(profileDir, 'node_modules', pkgName, patchRel), 'utf8')
+    const names = []
+    const lines = text.split(/\r?\n/u)
+    let inInsert = false
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i]
+      if (/^- insert:\s*$/u.test(line)) { inInsert = true; continue }
+      if (/^- /u.test(line) && !/^ {4}- /u.test(line)) inInsert = false
+      if (!inInsert) continue
+      const nameM = (lines[i + 1] ?? '').match(/^ {6}name: ['"]([^'"]+)['"]\s*$/u)
+      if (nameM) names.push(nameM[1])
+    }
+    return names
+  } catch { return [] }
+}
+
+export { readBundlePatchRefNames }

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

@@ -10,7 +10,8 @@ import { maybeAutoAdaptCompat } from './compat.js'
 import { getReposDir } from './repoland.js'
 import { aiConsentFailureText, cleanupAttemptedCandidates } 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, readBundlePatchRefNames, readGithubAuth, syncAggregateSubpackageVersions } from './install.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 { classifyInstallFailure, retryPnpmOnce } from './install-diagnose.js'
 import { jobLog } from './jobs.js'
 import { gatePrivateRoot } from './repo-size.js'
@@ -339,11 +340,14 @@ async function runInstallJob(job, ports, deps = {}) {
       const rootPkg = await probes.fetchRepoPackage(job.repo, 'main')
       if (rootPkg !== null && rootPkg.private === true) {
         subpackageMode = true
-        // 上游分支同一道判据（批次 D-①）：按仓库体积决定源码通道能不能走
-        await gatePrivateRoot(job, noteChannel, sourceDeps)
+        await gatePrivateRoot(job, noteChannel, sourceDeps) // 批次 D-①：按仓库体积决定源码通道
         const subs = await probes.subpackageCandidates(job.repo, 'main', readGithubAuth().token)
         if (subs.length > 0) {
-          candidates = [...subs.filter((name) => !candidates.includes(name)), ...candidates]
+          // ★ D-⑤（真机验证发现的**第二个根因**）：用户**明确点的那一件**必须排最前 —— 卡片子包列表每件的
+          // 按钮发 `{repo, packageName}`；旧代码把自动展开的子包统统排在它前面，第一件装成（或`已装在本地`
+          // 命中）就 break：**点第三件装的却是第一件**。只有"没给包名"时才该聚合包优先（那条路不经过这里）。
+          const requested = candidates.filter((n) => typeof n === 'string' && n !== '')
+          candidates = [...requested, ...subs.filter((name) => !requested.includes(name))]
           job.subpackages = subs
         }
       }

package/lib/server/domain/install.js

@@ -14,6 +14,8 @@ import { fetchJsonUrl } from '../infra/http.js'
 import { dshHome, resolvePackageJson } from '../infra/paths.js'
 import { downloadReleaseArtifact, releaseInstallTarget, selectReleaseInstall } from './release-source.js'
 import { verifyTarballDigest } from './install-verify.js'
+import { presetJobView } from './preset-install.js'
+import { readBundlePatchRefNames } from './bundle-refs.js'
 
 /** bundle 包判定：声明 dsh.bundle 的包一律按官方 `dsh plugin add` 行为追加为
  * profile bundle 层（其 cordis.patch.yml 的插入行在下次启动时组合进树）。
@@ -418,30 +420,9 @@ async function githubReleaseInstall(profileDir, repo, packageName, options = {})
  * （cordis.patch.yml）引用的包未安装 → 服务加载崩溃。
  * 读已装包的 bundle patch → 检查每个 insert 引用的包是否存在 → 缺失补装（pnpm/curl）→
  * 仍缺则在用户 patch 层自动禁用该行（防崩兜底）+ 返回报告供面板提示。
+ * 注：`readBundlePatchRefNames`（读 insert 引用清单）0.5.26 搬进 domain/bundle-refs.js ——
+ * 本文件贴着 600 行架构硬顶，而那块是自洽的只读逻辑；这里 re-export 保持接口不变。
  */
-/** 读取聚合包 cordis.patch.yml 的 insert 行 name 列表（注册前校验用）。 */
-function readBundlePatchRefNames(profileDir, pkgName) {
-  try {
-    const pkgJsonPath = join(profileDir, 'node_modules', pkgName, 'package.json')
-    if (!existsSync(pkgJsonPath)) return []
-    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
-    const patchRel = pkg.dsh?.bundle?.patch
-    if (typeof patchRel !== 'string') return []
-    const text = readFileSync(join(profileDir, 'node_modules', pkgName, patchRel), 'utf8')
-    const names = []
-    const lines = text.split(/\r?\n/u)
-    let inInsert = false
-    for (let i = 0; i < lines.length; i += 1) {
-      const line = lines[i]
-      if (/^- insert:\s*$/u.test(line)) { inInsert = true; continue }
-      if (/^- /u.test(line) && !/^ {4}- /u.test(line)) inInsert = false
-      if (!inInsert) continue
-      const nameM = (lines[i + 1] ?? '').match(/^ {6}name: ['"]([^'"]+)['"]\s*$/u)
-      if (nameM) names.push(nameM[1])
-    }
-    return names
-  } catch { return [] }
-}
 
 async function ensureBundlePatchIntegrity(profileDir, pkgName, userPatchPath, transientAllow = []) {
   const report = { checked: 0, installed: [], disabled: [], missing: [], pending: [] }
@@ -544,8 +525,11 @@ function installJobView(job) {
     skillDir: job.skillDir ?? null,
     skillNote: job.skillNote ?? null,
     suiteReport: job.suiteReport ?? null,
-    // 预设装配结果（2026-09-27 批次 D-③ 加法）：落盘路径 + "新建会话时选择" + 每个预设的合并/备份明细
-    suiteNote: job.suiteNote ?? null, presetNote: job.presetNote ?? null, presetInstalled: job.presetInstalled ?? null, presetSource: job.presetSource ?? null, repoSize: job.repoSize ?? null,
+    // 预设装配结果（2026-09-27 批次 D-③ 加法；0.5.26 起"预设那几项"整簇搬进
+    // preset-install.js#presetJobView —— 本文件贴着 600 行架构硬顶，且"预设通道要下发什么"
+    // 本来就该跟它的产出者放在一起）。套装备注与仓库体积仍是本文件的老字段，照旧在这里下发。
+    suiteNote: job.suiteNote ?? null, repoSize: job.repoSize ?? null,
+    ...presetJobView(job),
     hint: job.hint ?? null,
     // 子包级/套装级进度（2026-09-20 真装实测缺口：11 个子包的聚合仓库跑了 19 分钟，面板只显示
     // "安装中"，用户不知道在装第几个、还剩几个）。子包通道来自 install-job.js 候选循环维护的

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

@@ -17,6 +17,10 @@
 //     **补上具体包名**的构建放行项（domain/allow-builds.js：改前备份 + 写后读回核实 + 只动那几行）。
 //     它**不跑任何命令**，更不下载/执行脚本 —— 只影响"pnpm 下次安装是否还会因未批准而报错"。
 //     只有用户自己点「允许这些构建脚本」才会走到这里（绝不自动放行）。
+//   · overwrite-preset（0.5.26 加法，修 F2 的"出路"）：预设装配**默认只补不覆盖**，
+//     用户在面板上点「覆盖该预设」才走到这里 —— 按记录的源码出处**重新取一次源码**，
+//     先整目录备份、再覆盖、写后读回核实（domain/preset-source.js#overwritePreset）。
+//     它同样**不接受任何命令字符串**，也不跑 pnpm：只取源码 + 写 `.agent-presets/<name>`。
 //
 // 等待预算（2026-09-27 真机实测后的改错）：放行之后**第一次**安装会真的执行那些脚本
 // （cloudflared 下二进制、cpu-features/ssh2 走 node-gyp 原生编译；本机实测 18m59.6s 才结束，exitCode=0）。
@@ -38,11 +42,12 @@ import { classifyInstallFailure, ignoredBuildsFrom } from './install-diagnose.js
 import { runLockfileRepair } from './lockfile-health.js'
 import { pinProfileDependency, specOf } from './manifest.js'
 import { lockVersion } from './selfupdate.js'
+import { overwritePreset } from './preset-source.js'
 import { buildPnpmEnv, pnpmAddArgs, runPnpmWithFallback, unknownPnpmOption } from '../infra/exec.js'
 
 const DEFAULT_REGISTRY = 'https://registry.npmmirror.com'
 /** 动作白名单（客户端只能给这些 kind；执行分支与 argv 全在服务端）。 */
-const ACTION_KINDS = ['pin-dependency', 'reconcile-lock', 'allow-builds']
+const ACTION_KINDS = ['pin-dependency', 'reconcile-lock', 'allow-builds', 'overwrite-preset']
 /** 一旦出现这些键就整条拒绝：本接口不存在"传命令"的位置。 */
 const COMMAND_KEYS = ['command', 'cmd', 'argv', 'args', 'exec', 'execute', 'shell', 'script', 'run', 'spawn', 'bin', 'shellCommand']
 const OUTPUT_LIMIT = 4000
@@ -75,9 +80,18 @@ function parseActionRequest(body) {
   if (action === 'allow-builds' && packageName !== '' && (packageName.length > 214 || !NPM_NAME_RE.test(packageName))) {
     return { ok: false, status: 400, error: 'packageName 不是合法的 npm 包名' }
   }
+  // overwrite-preset 用 presetName（**预设目录名**，不是 npm 包名）：必须是非空、无路径分隔符的短名字。
+  // 这里只做**形状**校验；"这个预设到底存不存在 / 是不是本控制台装的"由执行体自己读盘判定（客户端说了不算）。
+  const rawPreset = typeof raw.presetName === 'string' ? raw.presetName.trim() : ''
+  if (action === 'overwrite-preset') {
+    if (rawPreset === '') return { ok: false, status: 400, error: 'overwrite-preset 需要 presetName' }
+    if (rawPreset.length > 120 || rawPreset === '.' || rawPreset === '..' || /[\\/]/u.test(rawPreset) || /[\u0000-\u001f]/u.test(rawPreset)) {
+      return { ok: false, status: 400, error: 'presetName 不是合法的预设目录名（不得含路径分隔符或控制字符）' }
+    }
+  }
   const version = typeof raw.version === 'string' && raw.version.length <= 120 ? raw.version : null
   const profile = typeof raw.profile === 'string' && raw.profile.length <= 64 ? raw.profile : null
-  return { ok: true, error: null, status: 200, action, packageName: packageName === '' ? null : packageName, version, profile }
+  return { ok: true, error: null, status: 200, action, packageName: packageName === '' ? null : packageName, version, profile, presetName: rawPreset === '' ? null : rawPreset }
 }
 
 /** 该包是否属于当前 profile（已声明在 dependencies / devDependencies / optionalDependencies 或
@@ -206,6 +220,38 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
       detail: applied,
     }
   }
+  if (parsed.action === 'overwrite-preset') {
+    // ★ 0.5.26 加法（修 F2 的"出路"那一半）：预设装配**默认只补不覆盖**，覆盖必须由用户显式点这个动作。
+    // 执行体在 domain/preset-source.js#overwritePreset：按记录**重新取一次源码** → 先整目录备份 →
+    // 覆盖 → 写后读回核实。本动作**不认识任何命令字符串**（COMMAND_KEYS 已在最前面拦掉），
+    // 也不跑 pnpm —— 只做"取源码 + 写 `.agent-presets/<name>`"这一件事。
+    const overwrite = typeof deps.overwritePreset === 'function' ? deps.overwritePreset : overwritePreset
+    let applied = null
+    try {
+      applied = await overwrite({ presetName: parsed.presetName, deps: deps.overwriteDeps ?? {} })
+    } catch (error) {
+      return { ...base, ok: false, status: 200, error: `覆盖预设失败：${error instanceof Error ? error.message : String(error)}` }
+    }
+    return {
+      ...base,
+      ok: applied?.ok === true,
+      status: applied?.status ?? 200,
+      exitCode: applied?.ok === true ? 0 : 1,
+      // 展示/复制的命令 = 本控制台自己的等价入口（**本动作不执行任何命令行**；服务端只取源码 + 写文件）
+      command: `dsh-plugin-console: overwrite-preset ${parsed.presetName}`,
+      presetName: parsed.presetName,
+      changed: (applied?.overwritten?.length ?? 0) + (applied?.added?.length ?? 0) > 0,
+      added: Array.isArray(applied?.added) ? applied.added : [],
+      overwritten: Array.isArray(applied?.overwritten) ? applied.overwritten : [],
+      backup: applied?.backup ?? null,
+      verified: applied?.verified ?? null,
+      file: applied?.dest ?? null,
+      notes: [applied?.note].filter((n) => typeof n === 'string' && n !== ''),
+      reason: applied?.ok === true ? applied.reason : (applied?.error ?? '覆盖失败（文件未改动）'),
+      error: applied?.ok === true ? undefined : (applied?.error ?? null),
+      detail: applied,
+    }
+  }
   if (parsed.action === 'reconcile-lock') {
     const view = await repair({ profileDir, registries: Array.isArray(registries) && registries.length > 0 ? registries : [registry] })
     const done = view?.action === 'repaired' || view?.action === 'noop'

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

@@ -0,0 +1,360 @@
+// L1 · domain —— preset-install.js（预设**装配**：只补不覆盖 / 显式覆盖 / 校验 / 备份 / 读回核实）
+//
+// 为什么单开一个模块（0.5.26 改错 F2 + F3 + F4，独立对抗式复核抓到）：
+//   · **F2**：`assemblePreset` 旧语义是"已存在同名预设 → 整目录备份 + 逐文件**合并覆盖**"。
+//     真机一次装配改写了 3 个在用预设、**11 个文件**（router-standard 4 个，含 `agent.cordis.yml`）。
+//     它有备份、有逐条报告（不静默），但**与上游 `install.ps1` 的语义相反** ——
+//     上游是「预设已存在 → 请先手动删除」= **跳过**。默认写别人的文件就是错的方向。
+//     新语义：**默认只补缺失文件，绝不覆盖已存在的同名文件**；覆盖必须由用户**显式**点
+//     「覆盖该预设」（白名单动作 `overwrite-preset`）才发生，且改前整目录备份 + 写后读回核实。
+//   · **F3**：装配前必须校验 `agent.cordis.yml` 可解析（见 preset-yaml.js）——
+//     旧代码把非法 YAML 覆盖到原本可用的文件上（`overwritten=["agent.cordis.yml"]`），
+//     下次新建会话挂载这个预设就报错。校验不通过 → **跳过该文件并如实报告，绝不写**。
+//   · **F4**：同一毫秒的两次装配会生成**同一个**备份路径（`<name>.bak-<Date.now()>`），
+//     第二次把第一次的备份覆盖掉 → 用户以为有两个回滚点，其实只剩一个。
+//     新语义：备份路径加唯一后缀（`-2`、`-3`… 直到不冲突），两次装配的备份**各自完整**。
+//
+// 与 preset-source.js 的分工：那边负责"把源码取下来"（稀疏 clone / git 定位 / 网络），
+// 这边只负责"往 `.agent-presets` 里写"（判据 / 校验 / 备份 / 核实）—— 写盘路径全项目只有这一处。
+//
+// 分层：L1 domain —— 不认识 cordis ctx；时间戳与 IO 可注入（便于离线断言）。
+
+import { createHash } from 'node:crypto'
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, relative, sep } from 'node:path'
+import { dshHome } from '../infra/paths.js'
+import { validateAgentConfig } from './preset-yaml.js'
+
+/** 预设的判别文件（框架发现预设看的就是这个：`<presetsRoot>/<name>/agent.cordis.yml`）。 */
+const PRESET_MARKER_FILES = ['agent.cordis.yml', 'agent.cordis.yaml']
+/** 预设清单（可选，面板文案用）。 */
+const PRESET_MANIFEST_FILE = 'preset.yml'
+/** 记录"每个已装配预设的源码出处"的文件（`overwrite-preset` 动作据此重新取源码）。
+ *  为什么不放 `<presetsRoot>` 里：那里是**框架**读的目录，多一个非预设文件会污染预设列表。 */
+const PRESET_SOURCE_RECORD_LIMIT = 80
+
+function presetSourcesFile(home = undefined) {
+  return join(home ?? dshHome(), 'plugin-console', 'preset-sources.json')
+}
+
+function sha256Of(text) {
+  return createHash('sha256').update(typeof text === 'string' ? text : String(text ?? ''), 'utf8').digest('hex')
+}
+
+/** 目录树里的文件清单（相对路径 + 字节数）——只读，best-effort，绝不抛。 */
+function listTreeFiles(root, { maxDepth = 8 } = {}) {
+  const out = []
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return
+    let entries = []
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      const child = join(dir, e.name)
+      try {
+        if (e.isDirectory()) walk(child, depth + 1)
+        else if (e.isFile()) out.push({ rel: relative(root, child).split(sep).join('/'), bytes: statSync(child).size })
+      } catch {}
+    }
+  }
+  walk(String(root), 0)
+  return out
+}
+
+/** 备份路径：`<dest>.bak-<timeValue>`，已存在就自增后缀直到不冲突（**F4**）。
+ *  旧实现直接 `${dest}.bak-${now()}` —— 同一毫秒的两次装配拿到同一个路径，
+ *  第二次 `copyTree` 把第一次的备份**覆盖**掉：用户以为有两个回滚点，其实只剩一个。 */
+function uniqueBackupPath(dest, timeValue) {
+  const base = `${dest}.bak-${timeValue}`
+  if (!existsSync(base)) return base
+  for (let n = 2; n < 1000; n += 1) {
+    const candidate = `${base}-${n}`
+    if (!existsSync(candidate)) return candidate
+  }
+  return `${base}-${Date.now()}`
+}
+
+/** 读回核实（**写后必做**）：每个本该落盘的文件都真的在盘上、且字节与源一致。
+ *  返回 { ok, checked, mismatched[] }；读不到/不一致都算不通过（绝不"写没写成"靠假设）。 */
+function verifyWrittenFiles(dest, srcDir, rels) {
+  const mismatched = []
+  for (const rel of rels) {
+    const target = join(dest, ...String(rel).split('/'))
+    const source = join(srcDir, ...String(rel).split('/'))
+    try {
+      if (!existsSync(target)) { mismatched.push(`${rel}（写后不存在）`); continue }
+      if (!readFileSync(target).equals(readFileSync(source))) mismatched.push(`${rel}（字节与源不一致）`)
+    } catch (error) {
+      mismatched.push(`${rel}（读回失败：${error instanceof Error ? error.message : String(error)}）`)
+    }
+  }
+  return { ok: mismatched.length === 0, checked: rels.length, mismatched }
+}
+
+/**
+ * 装配一个预设到 `<presetsRoot>/<name>`（**唯一实现**）。
+ *
+ * 两种模式（`overwrite` 必须由**用户显式动作**打开，安装路径永不传 true）：
+ *   · 默认（`overwrite !== true`）：**只补缺失文件**。已存在且内容不同的同名文件一律**不写**，
+ *     逐个记进 `conflicts` 并在 note 里点名，提示"如需覆盖，请点「覆盖该预设」"。
+ *     这个模式**不建备份**：一个字节都不改，建备份只会让用户以为目录被改过。
+ *   · `overwrite: true`：先整目录备份（唯一路径）→ 再按文件合并（新增 + 覆盖同名）→ 写后读回核实。
+ *
+ * F3 校验（两种模式都做）：源里的 `agent.cordis.yml/.yaml` 必须通过结构校验；
+ * 不通过 → **这个文件不写**，进 `skippedInvalid` 并如实报告（其它文件照常）。
+ *
+ * 返回 { ok, name, dest, backup, mode, added, skipped, overwritten, identical, conflicts,
+ *        skippedInvalid, verified, verifiedConfig, hashes, bytes, files, note, error }。
+ */
+function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now, overwrite = false, verify = true } = {}) {
+  const root = presetsRoot ?? join(dshHome(), '.agent-presets')
+  const presetName = String(name ?? basename(srcDir)).trim()
+  if (presetName === '' || presetName === '.' || /[\\/]/u.test(presetName)) {
+    return { ok: false, name: presetName, dest: null, error: `预设目录名不合法：${JSON.stringify(name)}` }
+  }
+  const dest = join(root, presetName)
+  const srcFiles = listTreeFiles(srcDir)
+  if (srcFiles.length === 0) return { ok: false, name: presetName, dest, error: `源目录里没有任何文件：${srcDir}` }
+  const bytes = srcFiles.reduce((sum, f) => sum + f.bytes, 0)
+  const existed = existsSync(dest)
+
+  // ── F3 校验（**写盘之前**）：预设的判别文件必须结构合法，否则绝不写 ──────────────────────
+  const skippedInvalid = []
+  const invalidConfig = []
+  for (const file of srcFiles) {
+    if (!PRESET_MARKER_FILES.includes(file.rel)) continue
+    let text = null
+    try { text = readFileSync(join(srcDir, ...file.rel.split('/')), 'utf8') } catch { text = null }
+    if (text === null) { invalidConfig.push({ rel: file.rel, problems: ['读不到内容'] }); continue }
+    const verdict = validateAgentConfig(text)
+    if (verdict.ok !== true) invalidConfig.push({ rel: file.rel, problems: verdict.problems })
+  }
+  if (invalidConfig.length > 0) {
+    for (const bad of invalidConfig) skippedInvalid.push({ rel: bad.rel, problems: bad.problems })
+  }
+  /** 预设的判别文件被拦下 = 这个预设**装不成**（框架发现预设看的就是它）→ 整个预设拒绝，
+   *  不做半成品（只铺 preset.yml/脚本、没有配置）—— 那种目录会让用户以为装上了，实际挂载不了。
+   *  这是**加法**：旧代码会把非法 YAML 直接覆盖上去，比"不装"更糟。 */
+  const markerBlocked = skippedInvalid.length > 0
+  if (markerBlocked) {
+    return {
+      ok: false, name: presetName, dest, existed, mode: overwrite === true ? 'overwrite' : 'add-only',
+      error: `预设配置未通过结构校验，拒绝装配（绝不写坏现有预设）：${skippedInvalid.map((s) => `${s.rel}（${s.problems[0]}）`).join('；')}`,
+      added: [], skipped: [], overwritten: [], identical: [], conflicts: [], skippedInvalid,
+      verified: null, verifiedConfig: null, hashes: [], bytes, files: srcFiles.map((f) => f.rel),
+      note: `预设 ${presetName} **未装配**：${skippedInvalid.length} 个预设配置文件未通过结构校验（${skippedInvalid.map((s) => s.rel).join('、')}），`
+        + '已跳过未写入 —— 避免把原本可用的预设写坏；现有文件一个字节都没动',
+    }
+  }
+
+  // ── 备份（**只在真要覆盖时**）：改前整目录复制；备份失败就不合并（绝不在没备份的情况下覆盖）──
+  let backup = null
+  if (existed && overwrite === true) {
+    backup = uniqueBackupPath(dest, now())
+    try {
+      copyTreeStrict(dest, backup)
+    } catch (error) {
+      return {
+        ok: false, name: presetName, dest, existed, mode: 'overwrite', backup: null,
+        error: `已存在同名预设且备份失败（绝不在没备份的情况下覆盖）：${error instanceof Error ? error.message : String(error)}`,
+        conflicts: srcFiles.map((f) => f.rel), added: [], skipped: [], overwritten: [], identical: [], skippedInvalid, verified: null, bytes,
+      }
+    }
+  }
+
+  mkdirSync(root, { recursive: true })
+  const added = []
+  const skipped = []
+  const overwritten = []
+  const identical = []
+  const written = []
+  for (const file of srcFiles) {
+    const from = join(srcDir, ...file.rel.split('/'))
+    const target = join(dest, ...file.rel.split('/'))
+    const had = existsSync(target)
+    if (had) {
+      let same = false
+      try { same = readFileSync(target).equals(readFileSync(from)) } catch { same = false }
+      if (same) { identical.push(file.rel); continue }
+      // ★ F2 的核心：默认**不覆盖**用户在用同名预设里的任何文件
+      if (overwrite !== true) { skipped.push(file.rel); continue }
+    }
+    try {
+      mkdirSync(dirname(target), { recursive: true })
+      writeFileSync(target, readFileSync(from))
+      written.push(file.rel)
+    } catch (error) {
+      return {
+        ok: false, name: presetName, dest, existed, mode: overwrite === true ? 'overwrite' : 'add-only', backup,
+        error: `合并 ${file.rel} 失败：${error instanceof Error ? error.message : String(error)}`,
+        added, skipped, overwritten, identical, conflicts: skipped, skippedInvalid, verified: null, bytes,
+      }
+    }
+    if (had) overwritten.push(file.rel)
+    else added.push(file.rel)
+  }
+
+  // ── 写后读回核实（只在真的写了东西时）────────────────────────────────────────────────
+  const verified = verify === true && written.length > 0 ? verifyWrittenFiles(dest, srcDir, written) : null
+  const destConfigValid = PRESET_MARKER_FILES.some((f) => existsSync(join(dest, f)))
+    ? PRESET_MARKER_FILES.map((f) => (existsSync(join(dest, f)) ? validateAgentConfig(readFileSync(join(dest, f), 'utf8')) : null)).find((v) => v !== null) ?? { ok: true }
+    : { ok: false, problems: ['目标目录里没有 agent.cordis.yml/.yaml'] }
+  const mode = overwrite === true ? 'overwrite' : 'add-only'
+
+  const noteParts = []
+  if (existed !== true) {
+    noteParts.push(`预设 ${presetName} 已装配到 ${dest}（新增 ${added.length} 个文件）`)
+  } else if (mode === 'overwrite') {
+    // 逐条点名被覆盖的文件（旧实现有这句，改错时不能丢：用户要知道**具体哪几个文件**被动过）
+    noteParts.push(`预设 ${presetName}：已按你的显式要求**覆盖**（原目录整份备份到 ${backup}；本次覆盖 ${overwritten.length} 个、新增 ${added.length} 个、内容一致 ${identical.length} 个）`
+      + (overwritten.length > 0 ? `（被覆盖的：${overwritten.slice(0, 6).join('、')}${overwritten.length > 6 ? ' 等' : ''}）` : ''))
+  } else {
+    noteParts.push(`预设 ${presetName}：**默认只补缺失文件、不覆盖**（本次新增 ${added.length} 个）`)
+    if (skipped.length > 0) {
+      noteParts.push(`已存在同名预设，其中 ${skipped.length} 个同名文件内容与你手上的不同，**已原样保留未动**：${skipped.slice(0, 6).join('、')}`
+        + `${skipped.length > 6 ? ' 等' : ''} —— 如需用仓库里的版本覆盖，请点「覆盖该预设」（会先把原目录整份备份）`)
+    }
+    if (identical.length > 0) noteParts.push(`另有 ${identical.length} 个文件与你手上的内容一致，未改动`)
+  }
+  if (skippedInvalid.length > 0) {
+    noteParts.push(`${skippedInvalid.length} 个预设配置文件**未通过结构校验、已跳过未写入**：`
+      + skippedInvalid.map((s) => `${s.rel}（${s.problems[0]}）`).join('、'))
+  }
+  if (skipped.length > 0) {
+    noteParts.push(`${skipped.length} 个同名文件因默认"只补不覆盖"而保留了你手上的版本`)
+  }
+  if (verified !== null && verified.ok !== true) {
+    noteParts.push(`⚠️ 写后读回核实不通过：${verified.mismatched.join('、')}`)
+  }
+  const result = {
+    ok: true,
+    name: presetName,
+    dest,
+    backup,
+    existed,
+    mode,
+    added,
+    skipped,
+    overwritten,
+    identical,
+    conflicts: skipped,
+    skippedInvalid,
+    verified,
+    verifiedConfig: destConfigValid,
+    hashes: written.map((rel) => ({ rel, sha256: sha256Of(readFileSync(join(dest, ...rel.split('/')))) })),
+    bytes,
+    files: srcFiles.map((f) => f.rel),
+    note: noteParts.join('；'),
+  }
+  // ok 的判据：真写成的文件都通过了读回核实 + 落盘后的配置结构合法。
+  // 两点必须说清，否则"改错"会变成"动不动报失败"：
+  //   · 一个文件都没写（内容全一致）**不是失败** —— 那是幂等重装的正常结局（verified 为 null）；
+  //   · 默认模式下"跳过同名冲突文件"**不是失败** —— 那正是"只补不覆盖"的设计目的，
+  //     但要靠 note 里逐条点名 + `skipped` 字段让面板看得见（绝不静默）。
+  const writtenOk = written.length === 0 || (verified !== null && verified.ok === true)
+  result.ok = writtenOk && destConfigValid.ok === true
+  if (!result.ok) {
+    result.error = writtenOk !== true
+      ? `写后读回核实不通过：${(verified?.mismatched ?? []).join('、')}`
+      : `落盘后的预设配置未通过结构校验：${(destConfigValid.problems ?? []).join('；')}`
+  }
+  return result
+}
+
+/** 逐文件复制目录树（不用 fs.cpSync：见 infra/fsx.js#copyTree 的本环境 EIO 说明）。
+ *  与 fsx.copyTree 的差别：这里**先清掉**同名的旧备份残留（绝不会发生，uniqueBackupPath 已保证），
+ *  并在复制后清掉只读位，保证备份可删可读。 */
+function copyTreeStrict(src, dest) {
+  mkdirSync(dest, { recursive: true })
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const from = join(src, entry.name)
+    const to = join(dest, entry.name)
+    if (entry.isDirectory()) { copyTreeStrict(from, to); continue }
+    if (!entry.isFile()) continue
+    copyFileSync(from, to)
+    try { chmodSync(to, 0o666) } catch {}
+  }
+  return dest
+}
+
+// ── 源码出处记录（`overwrite-preset` 动作据此重新取源码）──────────────────────────────
+
+/** 读全部记录（读不到/坏文件 → 空对象，绝不抛）。 */
+function readPresetSources(home = undefined) {
+  try {
+    const parsed = JSON.parse(readFileSync(presetSourcesFile(home), 'utf8'))
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/** 记下"这个预设是从哪个仓库的哪个子目录装配来的"（唯一写盘点，由装配路径调用）。
+ *  只记**可重新定位源码**的最小信息：repo / candidateName / subdir / sparse。 */
+function recordPresetSource(entries, { home = undefined, now = Date.now } = {}) {
+  const list = Array.isArray(entries) ? entries.filter((e) => e !== null && typeof e === 'object' && typeof e.name === 'string' && e.name !== '') : []
+  if (list.length === 0) return { ok: false, written: 0 }
+  const all = readPresetSources(home)
+  const at = new Date(typeof now === 'function' ? now() : now).toISOString()
+  for (const e of list) {
+    all[e.name] = {
+      repo: typeof e.repo === 'string' ? e.repo : null,
+      candidateName: typeof e.candidateName === 'string' ? e.candidateName : null,
+      subdir: typeof e.subdir === 'string' ? e.subdir : null,
+      sparse: e.sparse === true,
+      dest: typeof e.dest === 'string' ? e.dest : null,
+      at,
+    }
+  }
+  // 只保留最近 N 条（防无限增长）：对象键顺序 = 插入顺序，从最老的开始丢
+  const names = Object.keys(all)
+  for (const name of names.slice(0, Math.max(0, names.length - PRESET_SOURCE_RECORD_LIMIT))) delete all[name]
+  try {
+    mkdirSync(dirname(presetSourcesFile(home)), { recursive: true })
+    writeFileSync(presetSourcesFile(home), JSON.stringify(all, null, 2), 'utf8')
+    return { ok: true, written: list.length, file: presetSourcesFile(home) }
+  } catch (error) {
+    return { ok: false, written: 0, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/** 取一个预设记下的源码出处（没有 → null）。 */
+function presetSourceOf(name, home = undefined) {
+  const all = readPresetSources(home)
+  const hit = all[String(name ?? '').trim()]
+  return hit !== null && typeof hit === 'object' ? hit : null
+}
+
+/** 面板的「覆盖该预设」显式动作（**结构化**，与 pin-dependency / allow-builds 同一套安全语义）：
+ *  `command` 只供展示/复制；执行侧只认 `payload.action` 白名单类型，`presetName` 由服务端自己校验
+ *  （必须真的是 `<DSH_HOME>/.agent-presets/<name>` 下已存在的目录，客户端说了不算）。 */
+function suggestedOverwritePresetAction({ presetName, repo = null, reason = null } = {}) {
+  const name = typeof presetName === 'string' ? presetName.trim() : ''
+  return {
+    kind: 'overwrite-preset',
+    label: '覆盖该预设（先用仓库版本覆盖，自动整目录备份）',
+    command: `dsh-plugin-console: overwrite-preset ${name}`,
+    payload: { action: 'overwrite-preset', presetName: name, repo: typeof repo === 'string' && repo !== '' ? repo : null },
+    reason,
+  }
+}
+
+/** 面板视图里的**预设字段簇**（0.5.26 加法）：`installJobView` 只做一行展开。
+ *  为什么放这里：`domain/install.js` 贴着 600 行架构硬顶（test-architecture-guard.mjs），
+ *  而"预设这条通道要下发什么"本来就属于本模块 —— 字段与它的产出者放在一起，才不会漂移。 */
+function presetJobView(job) {
+  const j = job ?? {}
+  return {
+    presetNote: j.presetNote ?? null,
+    presetInstalled: j.presetInstalled ?? null,
+    presetSource: j.presetSource ?? null,
+    // 默认只补不覆盖：出现同名冲突时下发的**显式**「覆盖该预设」动作（老客户端忽略该字段，向后兼容）
+    suggestedAction: j.suggestedAction ?? null,
+    presetOverwriteCandidates: j.presetOverwriteCandidates ?? null,
+  }
+}
+
+export {
+  PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, PRESET_SOURCE_RECORD_LIMIT,
+  assemblePreset, copyTreeStrict, listTreeFiles, presetJobView, presetSourceOf, presetSourcesFile,
+  readPresetSources, recordPresetSource, sha256Of, suggestedOverwritePresetAction, uniqueBackupPath, verifyWrittenFiles,
+}

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

@@ -7,29 +7,30 @@
 //   于是第三件连一次机会都没有；而"添加并启用"这条路上，按包名的通道（registry/curl/release）
 //   对它必然是 404 —— 缺的就是"从仓库里把那一个目录取下来，按预设装配"这条能力。
 //
-// 本模块提供三件事（**唯一实现**，套装路径与候选路径共用，绝不复制粘贴第二套）：
+// 本模块提供三件事：
 //   ① findPresetDirs / isPresetDir —— 预设目录识别（从 suite.js **原样搬来**，suite.js 改为 re-export）
-//   ② assemblePreset —— 装配一个预设到 `<DSH_HOME>/.agent-presets/<name>`（**已存在同名预设时
-//      绝不静默覆盖**：先整目录备份，再逐文件合并；同名不同内容的逐条报告）
-//   ③ fetchPresetSource / tryPresetSourceChannel —— 稀疏取源码（`--filter=blob:none --sparse`
+//   ② fetchPresetSource / tryPresetSourceChannel —— 稀疏取源码（`--filter=blob:none --sparse`
 //      + `git sparse-checkout set <subdir>`；不支持时降级普通 clone）并装配
+//   ③ 装配本身（assemblePreset / 校验 / 备份 / 读回核实）**已搬到 domain/preset-install.js**
+//      （0.5.26 改错 F2+F3+F4：默认改为"只补不覆盖"、写前校验、备份路径唯一）。
+//      本模块只做 re-export，既有调用方与测试一个字都不用改 —— 写盘逻辑全项目只有一份。
 //
 // 进程管理一律复用 repoland.js 的 runGitArgs / gitCloneRepo（kill-tree + wait-for-exit + `.tryN` +
 // `.trash-*` 降级）—— 本模块**不新造任何进程管理**。
 
-import { existsSync, readFileSync, readdirSync, mkdirSync, statSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join, relative, sep } from 'node:path'
+import { existsSync, readFileSync, readdirSync, mkdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { gitCloneRepo, runGitArgs } from './repoland.js'
 import { noteChannel } from './git-channel.js'
 import { evaluateSourceChannel } from './repo-size.js'
-import { copyTree, disposeDir } from '../infra/fsx.js'
+import { disposeDir } from '../infra/fsx.js'
 import { dshHome } from '../infra/paths.js'
+import {
+  PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, assemblePreset, listTreeFiles,
+  presetSourceOf, recordPresetSource, suggestedOverwritePresetAction,
+} from './preset-install.js'
 
-/** 预设的判别文件（框架发现预设看的就是这个：`~/.dsh/.agent-presets/<name>/agent.cordis.yml`）。 */
-const PRESET_MARKER_FILES = ['agent.cordis.yml', 'agent.cordis.yaml']
-/** 预设清单（可选，面板文案用）。 */
-const PRESET_MANIFEST_FILE = 'preset.yml'
 /** git 只读命令（ls-tree / show / sparse-checkout）的超时：都是元数据或单个 blob。 */
 const GIT_READ_TIMEOUT_MS = 60000
 
@@ -84,88 +85,6 @@ function readPresetManifest(dir) {
   }
 }
 
-/** 目录树里的文件清单（相对路径 + 字节数）——只读，best-effort，绝不抛。 */
-function listTreeFiles(root, { maxDepth = 8 } = {}) {
-  const out = []
-  const walk = (dir, depth) => {
-    if (depth > maxDepth) return
-    let entries = []
-    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
-    for (const e of entries) {
-      const child = join(dir, e.name)
-      try {
-        if (e.isDirectory()) walk(child, depth + 1)
-        else if (e.isFile()) out.push({ rel: relative(root, child).split(sep).join('/'), bytes: statSync(child).size })
-      } catch {}
-    }
-  }
-  walk(String(root), 0)
-  return out
-}
-
-/** 装配一个预设到 `<presetsRoot>/<name>`（**唯一实现**）。
- * 已存在同名预设时**绝不静默覆盖**：
- *   ① 先把原目录整份备份成 `<name>.bak-<ts>`（备份失败就**不合并**，如实报冲突）；
- *   ② 再逐文件合并：源里有、目标里没有的算「新增」；两边都有且内容不同的算「覆盖」并逐条列出
- *      （内容相同的算「一致」，只在统计里体现，不刷屏）。
- * 这是**加法**：旧代码（suite.js 里那三行）是 `rmSync(dest)` + `copyTree` —— 用户手上的同名预设
- * 会被无声抹掉（真机 `.agent-presets` 下就有 router-standard / router-spec / router-react 三个在用）。
- * 返回 { ok, name, dest, backup, added, overwritten, identical, conflicts, bytes, note }。 */
-function assemblePreset(srcDir, name, { presetsRoot = null, now = Date.now } = {}) {
-  const root = presetsRoot ?? join(dshHome(), '.agent-presets')
-  const presetName = String(name ?? basename(srcDir)).trim()
-  if (presetName === '' || presetName === '.' || /[\\/]/u.test(presetName)) {
-    return { ok: false, name: presetName, dest: null, error: `预设目录名不合法：${JSON.stringify(name)}` }
-  }
-  const dest = join(root, presetName)
-  const srcFiles = listTreeFiles(srcDir)
-  if (srcFiles.length === 0) return { ok: false, name: presetName, dest, error: `源目录里没有任何文件：${srcDir}` }
-  const bytes = srcFiles.reduce((sum, f) => sum + f.bytes, 0)
-  let backup = null
-  const existed = existsSync(dest)
-  if (existed) {
-    backup = `${dest}.bak-${now()}`
-    try {
-      copyTree(dest, backup)
-    } catch (error) {
-      return {
-        ok: false,
-        name: presetName,
-        dest,
-        error: `已存在同名预设且备份失败（绝不在没备份的情况下覆盖）：${error instanceof Error ? error.message : String(error)}`,
-        conflicts: srcFiles.map((f) => f.rel),
-      }
-    }
-  }
-  mkdirSync(root, { recursive: true })
-  const added = []
-  const overwritten = []
-  const identical = []
-  for (const file of srcFiles) {
-    const from = join(srcDir, ...file.rel.split('/'))
-    const target = join(dest, ...file.rel.split('/'))
-    const had = existsSync(target)
-    let same = false
-    if (had) {
-      try { same = readFileSync(target).equals(readFileSync(from)) } catch { same = false }
-    }
-    if (same) { identical.push(file.rel); continue }
-    try {
-      mkdirSync(dirname(target), { recursive: true })
-      writeFileSync(target, readFileSync(from))
-    } catch (error) {
-      return { ok: false, name: presetName, dest, backup, error: `合并 ${file.rel} 失败：${error instanceof Error ? error.message : String(error)}` }
-    }
-    if (had) overwritten.push(file.rel)
-    else added.push(file.rel)
-  }
-  const note = existed
-    ? `预设 ${presetName}：已存在同名预设，原目录已备份到 ${backup}；本次合并新增 ${added.length} 个、覆盖 ${overwritten.length} 个同名文件、内容一致 ${identical.length} 个`
-      + (overwritten.length > 0 ? `（被覆盖的：${overwritten.slice(0, 6).join('、')}${overwritten.length > 6 ? ' 等' : ''}）` : '')
-    : `预设 ${presetName} 已装配到 ${dest}（新增 ${added.length} 个文件）`
-  return { ok: true, name: presetName, dest, backup, added, overwritten, identical, conflicts: overwritten, bytes, files: srcFiles.map((f) => f.rel), note }
-}
-
 /** 跑一条 git 命令并取回 stdout（ls-tree/show 要的就是输出）。仍然走 repoland 的 runGitArgs：
  * 那边已经把停滞判据 + kill-tree + wait-for-exit 做完了，这里只转发（`stdout` 由 runGitArgs 采集）。 */
 function gitCapture(argv, { cwd, timeout, runGit = null } = {}) {
@@ -299,30 +218,64 @@ async function tryPresetSourceChannel({ job, name, source = 'github', limit = 4,
     const skipped = Math.max(0, presets.length - limit)
     for (const p of presets.slice(0, limit)) {
       // eslint-disable-next-line no-await-in-loop
+      // overwrite **永不**在这里为真：安装路径必须走"只补不覆盖"的默认语义。
+      // 覆盖只能由用户显式点「覆盖该预设」→ 白名单动作 overwrite-preset 触发（见 plugin-actions.js）。
       const report = assemblePreset(p, basename(p), { presetsRoot, ...(deps.now === undefined ? {} : { now: deps.now }) })
       reports.push({ ...report, manifest: readPresetManifest(p), sparse: fetched.sparse === true, subdir: fetched.subdir })
     }
     const failed = reports.filter((r) => r.ok !== true)
     if (job !== null && job !== undefined) {
+      // 面板可读的结构化结果。0.5.26 加法：mode / skipped / skippedInvalid / verified ——
+      // 「默认只补不覆盖」必须**在数据里看得见**（跳过了哪几个同名文件、为什么），不能只在 note 里叙述。
       job.presetInstalled = reports.map((r) => ({
         name: r.name, dest: r.dest, ok: r.ok === true, added: r.added?.length ?? 0, overwritten: r.overwritten?.length ?? 0,
         identical: r.identical?.length ?? 0, backup: r.backup ?? null, bytes: r.bytes ?? 0, error: r.error ?? null,
         marker: r.ok === true ? 'agent.cordis.yml' : null, subdir: r.subdir ?? null, sparse: r.sparse === true,
+        mode: r.mode ?? null, existed: r.existed === true,
+        skipped: Array.isArray(r.skipped) ? r.skipped : [],
+        skippedInvalid: Array.isArray(r.skippedInvalid) ? r.skippedInvalid : [],
+        verified: r.verified === null || r.verified === undefined ? null : r.verified.ok === true,
       }))
       job.presetSource = { repo, subdir: fetched.subdir, sparse: fetched.sparse === true, downgraded: fetched.downgraded === true, root: fetched.root }
+      // 源码出处落盘：`overwrite-preset` 动作据此**重新取源码**（临时 clone 目录在 finally 里已清理，
+      // 所以"仅靠内存里的路径"是做不到的）。只记 repo / 候选名 / 子目录，不记任何路径或凭据。
+      try {
+        recordPresetSource(reports.filter((r) => r.ok === true).map((r) => ({
+          name: r.name, repo, candidateName, subdir: fetched.subdir, sparse: fetched.sparse === true, dest: r.dest,
+        })), { home: deps.home, now: deps.now })
+      } catch {}
+      // 同名冲突 / 校验跳过 → 给面板一个**显式**的「覆盖该预设」按钮（结构化动作，见 plugin-actions.js）。
+      // 只在真的有冲突时出现；用户不点，一个字节都不会被覆盖。
+      const conflicted = reports.filter((r) => r.ok === true && ((r.skipped?.length ?? 0) > 0 || (r.skippedInvalid?.length ?? 0) > 0))
+      if (conflicted.length > 0 && job.suggestedAction === undefined) {
+        const first = conflicted[0]
+        job.suggestedAction = suggestedOverwritePresetAction({
+          presetName: first.name,
+          repo,
+          reason: `预设 ${first.name} 已存在同名文件（${(first.skipped ?? []).join('、') || '配置未通过校验'}），本次**按默认语义保留了你手上的版本**；如需用仓库版本覆盖，点这个按钮（会先把原目录整份备份）`,
+        })
+        job.presetOverwriteCandidates = conflicted.map((r) => r.name)
+      }
     }
     if (failed.length > 0 && failed.length === reports.length) {
       return { handled: true, installed: false, error: new Error(`预设装配失败：${failed[0].error}`), presets: reports }
     }
     const okNames = reports.filter((r) => r.ok === true).map((r) => r.name)
-    // 只要**建过备份**就必须说（哪怕本次一个文件都没覆盖）——否则用户不知道多了一个 .bak 目录，
-    // 也不知道"这次其实什么都没改"。
-    const merged = reports.filter((r) => r.ok === true && typeof r.backup === 'string' && r.backup !== '')
+    const skippedFiles = reports.reduce((sum, r) => sum + (r.skipped?.length ?? 0), 0)
+    const invalidFiles = reports.reduce((sum, r) => sum + (r.skippedInvalid?.length ?? 0), 0)
+    const backedUp = reports.filter((r) => r.ok === true && typeof r.backup === 'string' && r.backup !== '')
     const note = `预设已装配：${okNames.join('、')}（落盘 ${presetsRoot}；**新建会话时选择**）`
       + (fetched.sparse === true ? '；源码用稀疏取源码（--filter=blob:none --sparse + sparse-checkout set），只取该子包目录' : '')
       + (skipped > 0 ? `；该仓库还有 ${skipped} 个预设本次未装配（单次上限 ${limit} 个）` : '')
-      + (merged.length > 0
-        ? `；已存在同名预设 ${merged.map((r) => r.name).join('、')}：原目录已备份（${merged.map((r) => r.backup).join('、')}），本次按文件合并（覆盖 ${merged.reduce((s, r) => s + r.overwritten.length, 0)} 个、内容一致 ${merged.reduce((s, r) => s + r.identical.length, 0)} 个）`
+      // 默认语义必须在面板上说清（用户要先知道"你的文件没被动过"，才谈得上要不要覆盖）
+      + (skippedFiles > 0
+        ? `；**预设装配默认只补不覆盖**：${skippedFiles} 个同名文件与你手上的内容不同，已原样保留未动 —— 如需覆盖，请点「覆盖该预设」（会先把原目录整份备份）`
+        : '')
+      + (invalidFiles > 0
+        ? `；${invalidFiles} 个预设配置文件未通过结构校验（非法 YAML），**已跳过未写入**（避免把原本可用的预设写坏）`
+        : '')
+      + (backedUp.length > 0
+        ? `；已存在同名预设 ${backedUp.map((r) => r.name).join('、')}：原目录已备份（${backedUp.map((r) => r.backup).join('、')}），本次覆盖 ${backedUp.reduce((s, r) => s + r.overwritten.length, 0)} 个、内容一致 ${backedUp.reduce((s, r) => s + r.identical.length, 0)} 个`
         : '')
       + (failed.length > 0 ? `；${failed.length} 个预设装配失败：${failed.map((r) => `${r.name}（${r.error}）`).join('、')}` : '')
     return { handled: true, installed: true, name: candidateName, presets: reports, note }
@@ -332,8 +285,89 @@ async function tryPresetSourceChannel({ job, name, source = 'github', limit = 4,
   }
 }
 
+/** 「覆盖该预设」的**执行体**（0.5.26 加法，修 F2；只由显式动作 `overwrite-preset` 调用）。
+ *
+ * 为什么需要它：默认语义改成"只补不覆盖"之后，用户必须有**一条明确的出路**才能拿到仓库版本。
+ * 这条出路不能靠"临时 clone 目录"——那个目录在 tryPresetSourceChannel 的 finally 里已经清理了，
+ * 所以要**按记录重新取一次源码**（记录见 preset-install.js#recordPresetSource），再走
+ * `assemblePreset(..., { overwrite: true })`（先整目录备份 → 覆盖 → 写后读回核实）。
+ *
+ * 安全边界（与 allow-builds / pin-dependency 同一套，配套断言钉死）：
+ *   · 只认**已存在**于 `<presetsRoot>/<name>` 的目录，名字由服务端校验（客户端说了不算）；
+ *   · 只有**记过源码出处**的预设才能覆盖（没记录 = 不是本控制台装的 → 让它走正常安装流程）；
+ *   · 源码通道体积门禁照旧（巨仓不放行）；取源码走既有 gitCloneRepo（不新造进程管理）；
+ *   · 本函数**不执行任何客户端传来的字符串**，也不接受任何命令参数。
+ *
+ * 返回 { ok, status, name, backup, overwritten, added, identical, verified, note, error, reason }。 */
+async function overwritePreset({ presetName, deps = {} } = {}) {
+  const raw = String(presetName ?? '').trim()
+  // 目录名判据与 assemblePreset 完全一致（含"不得含路径分隔符"），这里先做一次**便宜**的拒绝
+  if (raw === '' || raw === '.' || raw === '..' || /[\\/]/u.test(raw)) {
+    return { ok: false, status: 400, name: raw, error: `预设名不合法：${JSON.stringify(presetName)}` }
+  }
+  const presetsRoot = deps.presetsRoot ?? join(dshHome(), '.agent-presets')
+  const dest = join(presetsRoot, raw)
+  if (!existsSync(dest)) {
+    return { ok: false, status: 400, name: raw, error: `预设 ${raw} 不存在（${dest}），没有可覆盖的对象 —— 本动作只改已存在的预设` }
+  }
+  const home = deps.home
+  const explicitRepo = typeof deps.repo === 'string' && deps.repo.trim() !== '' ? deps.repo.trim() : null
+  const record = presetSourceOf(raw, home)
+  const repo = explicitRepo ?? (typeof record?.repo === 'string' && record.repo !== '' ? record.repo : null)
+  if (repo === null) {
+    return {
+      ok: false, status: 400, name: raw,
+      error: `没有 ${raw} 的源码出处记录（它可能不是本控制台装配的）。请用市场卡片重新安装这个预设，安装后即可覆盖。`,
+    }
+  }
+  const candidateName = (typeof record?.candidateName === 'string' && record.candidateName !== '') ? record.candidateName : `dsh-${raw}`
+  const source = typeof deps.source === 'string' && deps.source !== '' ? deps.source : 'github'
+  const gate = await evaluateSourceChannel(repo, deps.sizeDeps ?? {})
+  if (gate.allow !== true) {
+    return { ok: false, status: 400, name: raw, repo, error: `覆盖需要重新取源码，但源码通道不可用：${gate.note}` }
+  }
+  const tmpRoot = deps.tmpRoot ?? join(tmpdir(), `dsh-preset-overwrite-${raw}-${Date.now()}`)
+  const destClone = join(tmpRoot, 'repo')
+  try { mkdirSync(tmpRoot, { recursive: true }) } catch {}
+  try {
+    const fetched = await fetchPresetSource({ repo, candidateName, dest: destClone, source, timeout: deps.cloneTimeoutMs, deps: deps.fetchDeps ?? {} })
+    if (fetched.ok !== true) {
+      return { ok: false, status: 200, name: raw, repo, error: `重新取源码失败：${fetched.error}` }
+    }
+    const subDir = join(fetched.root, ...String(fetched.subdir).split('/'))
+    const found = findPresetDirs(subDir, 2)
+    if (found.length === 0 && isPresetDir(subDir)) found.push(subDir)
+    // 优先取**同名**的那个预设目录（一个子包里可能有多个预设）
+    const pick = found.find((p) => basename(p) === raw) ?? found[0] ?? null
+    if (pick === null) {
+      return { ok: false, status: 200, name: raw, repo, error: `仓库 ${repo} 的 ${fetched.subdir} 里没有找到预设目录` }
+    }
+    // 覆盖的永远是**用户点名的那一个**名字（不是源目录的 basename）：用户点的是哪个就改哪个
+    const report = assemblePreset(pick, raw, { presetsRoot, overwrite: true, ...(deps.now === undefined ? {} : { now: deps.now }) })
+    if (report.ok !== true) {
+      return { ok: false, status: 200, name: raw, repo, backup: report.backup ?? null, error: report.error ?? '覆盖失败（文件未改动）', report }
+    }
+    // 覆盖后刷新源码出处记录（时间戳更新；repo/子目录可能与旧记录不同）
+    try {
+      recordPresetSource([{ name: raw, repo, candidateName, subdir: fetched.subdir, sparse: fetched.sparse === true, dest: report.dest }], { home, now: deps.now })
+    } catch {}
+    return {
+      ok: true, status: 200, name: raw, repo, dest: report.dest,
+      backup: report.backup, added: report.added, overwritten: report.overwritten, identical: report.identical,
+      skippedInvalid: report.skippedInvalid, verified: report.verified, bytes: report.bytes, hashes: report.hashes,
+      mode: 'overwrite', note: report.note, error: null,
+      reason: `已用仓库 ${repo} 的版本覆盖预设 ${raw}（覆盖 ${report.overwritten.length} 个文件`
+        + `${report.overwritten.length > 0 ? `：${report.overwritten.slice(0, 6).join('、')}${report.overwritten.length > 6 ? ' 等' : ''}` : ''}`
+        + `、新增 ${report.added.length} 个；原目录已备份到 ${report.backup}）`,
+    }
+  } finally {
+    try { disposeDir(tmpRoot) } catch {}
+  }
+}
+
 export {
   PRESET_MARKER_FILES, PRESET_MANIFEST_FILE, GIT_READ_TIMEOUT_MS,
   findPresetDirs, isPresetDir, looksLikePresetPackageName, readPresetManifest, listTreeFiles,
   assemblePreset, locateSubpackageViaGit, fetchPresetSource, gitCapture, tryPresetSourceChannel,
-}
+  overwritePreset,
+}

package/lib/server/domain/preset-yaml.js

@@ -0,0 +1,165 @@
+// L1 · domain —— preset-yaml.js（预设配置 agent.cordis.yml 的**结构校验**；0.5.26 加法，修 F3）
+//
+// 为什么要有它（真机缺陷 F3，2026-09-27 独立对抗式复核抓到）：
+//   预设装配会把源仓库里的 `agent.cordis.yml` 覆盖到用户 `~/.dsh/.agent-presets/<预设>/` 下。
+//   一旦取到的内容**不是可用的配置**（空文件、被截断、带 tab 缩进、引号没闭合…），
+//   覆盖就把**原本可用**的预设写坏了 —— 复核报告里的现场就是 `overwritten=["agent.cordis.yml"]`，
+//   下次新建会话挂载这个预设时报错，而用户完全不知道是自己点的那次「安装」干的。
+//   修法（改错）：**写盘之前**先做结构校验；不通过就**跳过这一个文件并如实报告**，绝不写坏。
+//
+// ⚠️ 判据宽严的分寸（为什么不用"顶层必须是 mapping"这类严格判据）：
+//   框架的 agent 预设是**顶层 services 列表**（`- id: …` / `name: …` / `config:`），
+//   里面还合法地使用 `!!js` 自定义标签、`>-` 折叠块、`|-` 字面块、注释与空行。
+//   严格的通用 YAML 校验器（或"顶层必须是 mapping"）会把**真文件**判成非法 → 于是"修 F3"变成
+//   "所有预设都装不上"，那是把缺陷换了个方向。所以这里只钉**能确证损坏**的形态（全部可离线判定）：
+//     ① 空内容 / 全是注释与空行 —— 没有任何配置行，框架挂载它等于空预设；
+//     ② 行首缩进里出现 **tab** —— YAML 明确禁止用 tab 做缩进（框架的解析器必然报错）；
+//     ③ 明显**未闭合的引号**（引号从头到尾用反斜杠转义、真正的解析器能容忍跨行，这里只抓最常见的截断）；
+//     ④ 缩进**跳级**（父级还没打开一个映射/序列就多缩进）—— 截断与坏编辑的典型形状。
+//   `!!js` / 块标量 / 注释 / CRLF 一律按合法处理（见 passesStructure 的分支注释）。
+//
+// 分层：L1 domain —— 纯函数，无 IO、无 ctx、不抛（解析失败是正常结局，调用方按"不通过"处理）。
+
+/** 缩进宽度（空格数；tab 会在这里被单独判掉，不参与计数）。 */
+function indentOf(line) {
+  const m = String(line).match(/^[ \t]*/u)
+  return m === null ? 0 : m[0].length
+}
+
+/** 这一行的缩进里有没有 tab（YAML 禁止；框架解析器会直接报错）。 */
+function hasTabIndent(line) {
+  return /^[ \t]*\t/u.test(String(line))
+}
+
+/** 去掉行尾注释后的"有效内容"（只处理**不在引号里**的 `#`；`#` 前必须有空白或行首）。
+ *  例：`name: '@deepseek-ai/dsh-persona'  # 注释` → `name: '@deepseek-ai/dsh-persona'`。 */
+function stripTrailingComment(line) {
+  const text = String(line)
+  let quote = null
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i]
+    if (quote !== null) {
+      if (ch === '\\') { i += 1; continue }
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"') { quote = ch; continue }
+    if (ch === '#' && (i === 0 || /\s/u.test(text[i - 1]))) return text.slice(0, i)
+  }
+  return text
+}
+
+/** 值里的引号是否闭合（只判**单个标量内**的成对性；跨行的引号在 YAML 里合法，故不跨行判）。 */
+function quotesBalanced(value) {
+  const text = String(value)
+  let quote = null
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i]
+    if (quote === null) {
+      if (ch === "'" || ch === '"') quote = ch
+      continue
+    }
+    if (quote === '"' && ch === '\\') { i += 1; continue }
+    if (ch === quote) {
+      // YAML 的单引号转义是 `''`（两个单引号），要一起吃掉
+      if (quote === "'" && text[i + 1] === "'") { i += 1; continue }
+      quote = null
+    }
+  }
+  return quote === null
+}
+
+/** 块标量指示符（`|`、`>`、`|-`、`>+2`、`|2-`…）。返回 null 表示不是块标量。
+ *  只有**整个值**就是指示符时才认（`> something` 是普通标量，不是块头），否则会把普通行误判成块。 */
+function blockScalarIndicator(value) {
+  const text = String(value).trim()
+  const m = text.match(/^([|>])([+-]?\d*|\d*[+-]?)$/u)
+  return m === null ? null : m[0]
+}
+
+/**
+ * 结构校验（**纯函数**，永不抛）。返回 `{ ok, problems: string[] }`。
+ * 只判"能确证损坏"的形态（见本文件顶部 ①~④），宁松勿误杀 —— 误杀的代价是预设装不上。
+ */
+function validateAgentConfig(text) {
+  const source = typeof text === 'string' ? text : String(text ?? '')
+  const problems = []
+  const lines = source.split(/\r?\n/u)
+  const significant = []
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i]
+    if (raw.trim() === '') continue
+    if (/^\s*#/u.test(raw)) continue
+    significant.push({ line: i + 1, raw, indent: indentOf(raw), at: i })
+  }
+  // ① 空内容 / 全是注释与空行
+  if (significant.length === 0) {
+    problems.push('没有任何配置行（空文件，或只有注释与空行）—— 框架挂载它等于空预设')
+    return { ok: false, problems }
+  }
+  /** 块标量（`>-` / `|` 等）的内容由框架按字面读，**不是** YAML 结构 —— 必须整段跳过，
+   *  否则 persona 那种多行散文会被逐行当成"非法条目"（误杀三个真机预设，2026-09-27 实测）。
+   *  结束判据：出现缩进 **小于等于** 块首行缩进的非空行（或文件结束）。 */
+  const blockScalarEnd = (startIdx, parentIndent) => {
+    let end = startIdx
+    for (let i = startIdx + 1; i < lines.length; i += 1) {
+      const line = lines[i]
+      if (line.trim() === '') { end = i; continue }
+      if (indentOf(line) > parentIndent) { end = i; continue }
+      break
+    }
+    return end
+  }
+  const stack = []   // 已打开的父级：{ indent, opensNested }
+  let skipThrough = -1
+  for (const item of significant) {
+    if (item.at <= skipThrough) continue
+    // ② tab 缩进
+    if (hasTabIndent(item.raw)) {
+      problems.push(`第 ${item.line} 行的缩进里有 tab（YAML 禁止用 tab 缩进）`)
+      continue
+    }
+    const content = stripTrailingComment(item.raw).replace(/\s+$/u, '')
+    if (content.trim() === '') continue
+    const body = item.raw.slice(item.indent)
+    // ④ 缩进跳级：比当前父级深、但父级没有"还能放子项"的位置
+    while (stack.length > 0 && item.indent < stack[stack.length - 1].indent) stack.pop()
+    const parent = stack.length > 0 ? stack[stack.length - 1] : null
+    if (parent !== null && item.indent > parent.indent && parent.opensNested !== true) {
+      problems.push(`第 ${item.line} 行缩进 ${item.indent} 空格，但上一层的 \`${parent.label}\` 不接受子项（缩进跳级/文件被截断）`)
+    }
+    if (body.startsWith('- ') || body === '-') {
+      stack.push({ indent: item.indent, opensNested: true, label: body.slice(0, 40) })
+      continue
+    }
+    const kv = body.match(/^("[^"]*"|'[^']*'|[^\s:#][^:]*?)\s*:\s*(.*)$/u)
+    if (kv === null) {
+      problems.push(`第 ${item.line} 行不是合法的 YAML 条目（既不是 \`- \` 序列项，也不是 \`键: 值\`）：${body.slice(0, 60)}`)
+      continue
+    }
+    const value = kv[2].trim()
+    // ③ 未闭合的引号（只在单行内判；`#` 已剥掉，行尾也不会再有注释）
+    if (!quotesBalanced(value)) {
+      problems.push(`第 ${item.line} 行的值里有未闭合的引号：${value.slice(0, 60)}`)
+    }
+    const isBlock = blockScalarIndicator(value) !== null
+    if (isBlock) skipThrough = blockScalarEnd(item.at, item.indent)
+    stack.push({ indent: item.indent, opensNested: value === '' || isBlock, label: `${kv[1].trim()}:` })
+  }
+  return { ok: problems.length === 0, problems }
+}
+
+/** 校验一个**目录里**的 agent 配置文件（写盘前的调用点用这个）。
+ *  返回 `{ ok, file, problems }`；目录里没有 agent.cordis.yml/.yaml 时 ok=true / file=null（不是预设，不归这里管）。 */
+function validateAgentConfigDir(dir, { readFile = null } = {}) {
+  const read = typeof readFile === 'function' ? readFile : null
+  for (const name of ['agent.cordis.yml', 'agent.cordis.yaml']) {
+    const text = read === null ? null : read(name)
+    if (text === null || text === undefined) continue
+    const result = validateAgentConfig(text)
+    return { ...result, file: name }
+  }
+  return { ok: true, file: null, problems: [] }
+}
+
+export { validateAgentConfig, validateAgentConfigDir, stripTrailingComment, quotesBalanced, blockScalarIndicator, hasTabIndent, indentOf }

package/lib/server/domain/repo-size.js

@@ -37,17 +37,36 @@ function formatRepoSize(sizeKb) {
  *   · state='known' 且 sizeKb >  阈值 → **仍禁**，note 必须含体积、原因与出路（仓库落地 / 本地镜像）
  *   · state='unknown'（探测失败/超时/404）→ **保守但不沉默**：保持禁令 + note 说明"尺寸未知，已保守跳过"
  * 返回的 note 一律非空 —— 静默跳过正是这次事故的另一半（用户什么都看不到）。 */
-function sourceChannelGate({ state = 'unknown', sizeKb = null } = {}, thresholdMb = GIT_MAX_REPO_MB) {
+function sourceChannelGate(options = {}, thresholdMb = GIT_MAX_REPO_MB) {
+  // ⚠️ 这里**故意不用解构默认值**（旧代码是 `{ state = 'unknown', sizeKb = null } = {}`）：
+  // 解构的 `= null` 会在"键存在但值是 undefined"时也填上 null，于是**原始值被抹掉**——
+  // 而本次改错要判的恰恰是"读到的到底是什么"，note 里必须分得出 null / undefined / 空串 / false。
+  const raw = options !== null && typeof options === 'object' ? options : {}
+  const provided = Object.prototype.hasOwnProperty.call(raw, 'sizeKb')
+  const state = raw.state === undefined ? 'unknown' : raw.state
+  const rawSize = provided ? raw.sizeKb : null
+  const sizeKb = rawSize
   const limit = Number.isFinite(Number(thresholdMb)) && Number(thresholdMb) >= 1 ? Number(thresholdMb) : GIT_MAX_REPO_MB
   const kb = Number(sizeKb)
-  const known = state === 'known' && Number.isFinite(kb) && kb >= 0
+  // 判据必须落在**原始值**上：旧代码写的是 `Number(sizeKb)` 之后再判有限性，于是
+  // `sizeKb: null` → `Number(null) === 0` → 有限且 ≥ 0 → **被当成 0 MB 放行**（`undefined` 同理 → NaN→
+  // 有限性为假，那条反倒是禁的；真正漏的是 null / '' / false / [] 这些"能转成 0"的值）。
+  // 0 KB 只有在**真的是数字 0**时才是合法尺寸（空仓库；见边界断言），"读不到尺寸"绝不能伪装成 0。
+  const numericSize = typeof rawSize === 'number' && Number.isFinite(rawSize) && rawSize >= 0
+  const known = state === 'known' && numericSize
   if (!known) {
+    // state='known' 但尺寸不是有限数 = 上游给了自相矛盾的结论（探测层不会这样产出）。
+    // 这时必须**如实说清**并保守跳过；旧文案会把它说成"探测失败/超时/404"，与真实原因不符。
+    const contradiction = state === 'known'
+    const shown = provided ? String(rawSize) : 'undefined（未提供）'
     return {
       allow: false,
       state: 'unknown',
       sizeKb: null,
       limitMb: limit,
-      note: '仓库体积未知（GitHub 元数据探测失败/超时/404）：已**保守跳过**源码通道（git / archive / 稀疏取源码），避免白拉一个可能几百 MB 的仓库。请重试；或改用「仓库落地」把仓库克隆到本地目录后安装。',
+      note: contradiction
+        ? `仓库体积读到的不是有效数字（state=known 但 sizeKb=${shown}）：已**保守跳过**源码通道（git / archive / 稀疏取源码）—— 尺寸读不出来时绝不能当成 0 MB 放行。请重试；或改用「仓库落地」把仓库克隆到本地目录后安装。`
+        : '仓库体积未知（GitHub 元数据探测失败/超时/404）：已**保守跳过**源码通道（git / archive / 稀疏取源码），避免白拉一个可能几百 MB 的仓库。请重试；或改用「仓库落地」把仓库克隆到本地目录后安装。',
     }
   }
   if (kb <= limit * 1024) {

package/lib/server/infra/fsx.js

@@ -119,12 +119,34 @@ function waitGone(dir, timeoutMs) {
   })
 }
 
+/** 外部删除兜底该用哪条命令（**判据唯一真源**，异步/同步两个兜底共用）。
+ *
+ * 真机缺陷（0.5.25 及以前，2026-09-27 定位）：`clean-residuals` 清的陈旧
+ * `fw-quarantine.json.applied-*` 是**文件**，而 shell 兜底一律用 `rmdir /s /q <path>` ——
+ * `rmdir` 在 Windows 上只能删**目录**，对文件返回 `exit=267 The directory name is invalid`，
+ * 于是"`rmSync` 一次瞬时失败"被兜底放大成**用户可见的「有 1 项没能删除」误报**（文件其实好好的）。
+ * 判据：文件 → `del /f /q`；目录 → `rmdir /s /q`；已经不在了 → 视为已达成（**不是失败**）。
+ * `lstatSync` 而不是 `statSync`：悬空符号链接本身也要能被删掉。
+ * 读不出类型（竞态/权限）→ 走目录形态：目录树是这套兜底原本唯一服务的对象，保持旧行为不倒退。
+ * 注意：`del` / `rmdir` 都是 cmd.exe 的**内建命令**，只能经 `cmd.exe /c` 调用，没有对应的可执行文件。 */
+function shellDeleteCommand(dir) {
+  if (!existsSync(dir)) return { kind: 'gone', argv: null, method: 'already-gone' }
+  let isDirectory = true
+  try { isDirectory = lstatSync(dir).isDirectory() } catch { isDirectory = true }
+  return isDirectory
+    ? { kind: 'dir', argv: ['rmdir', '/s', '/q', dir], method: 'rmdir' }
+    : { kind: 'file', argv: ['del', '/f', '/q', dir], method: 'del' }
+}
+
 /** 外部删除兜底：实测本机 PowerShell/.NET 能删掉 Node `rmSync` 静默删不掉的树。 */
 async function removeViaShell(dir, timeoutMs = 120000) {
   try {
     if (process.platform === 'win32') {
-      await execFileAsync('cmd.exe', ['/c', 'rmdir', '/s', '/q', dir], { windowsHide: true, timeout: timeoutMs })
-      return { ok: true, method: 'rmdir' }
+      const target = shellDeleteCommand(dir)
+      if (target.kind === 'gone') return { ok: true, method: target.method }
+      await execFileAsync('cmd.exe', ['/c', ...target.argv], { windowsHide: true, timeout: timeoutMs })
+      // `del` 对"文件已被别处删掉"会返回 0 又不报错，这里不再多判；调用方仍会核实目标是否消失
+      return { ok: true, method: target.method }
     }
     await execFileAsync('rm', ['-rf', '--', dir], { timeout: timeoutMs })
     return { ok: true, method: 'rm' }
@@ -179,12 +201,16 @@ function sleepSync(ms) {
   } catch {}
 }
 
-/** 外部删除兜底（同步版）：实测本机 `cmd /c rmdir /s /q` 能删掉 Node `rmSync` 静默删不掉的树。 */
+/** 外部删除兜底（同步版）：实测本机 `cmd /c rmdir /s /q` 能删掉 Node `rmSync` 静默删不掉的树。
+ *  目标类型判据与异步版**同一份**（shellDeleteCommand）：文件用 `del /f /q`、目录用 `rmdir /s /q` ——
+ *  旧实现对文件用 `rmdir` 只会拿到 exit=267，把"其实删得掉"的文件报成删不掉（见 shellDeleteCommand 注释）。 */
 function removeViaShellSync(dir, timeoutMs = 120000) {
   try {
     if (process.platform === 'win32') {
-      execFileSync('cmd.exe', ['/c', 'rmdir', '/s', '/q', dir], { windowsHide: true, timeout: timeoutMs, stdio: 'ignore' })
-      return { ok: true, method: 'rmdir' }
+      const target = shellDeleteCommand(dir)
+      if (target.kind === 'gone') return { ok: true, method: target.method }
+      execFileSync('cmd.exe', ['/c', ...target.argv], { windowsHide: true, timeout: timeoutMs, stdio: 'ignore' })
+      return { ok: true, method: target.method }
     }
     execFileSync('rm', ['-rf', '--', dir], { timeout: timeoutMs, stdio: 'ignore' })
     return { ok: true, method: 'rm' }
@@ -395,4 +421,4 @@ function startTrashCleanup(opts = {}) {
   }
 }
 
-export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, removeDirVerifiedWithRetry, removeViaShellSync, sleepSync, clearReadonly, waitGone, removeViaShell, writeQueue, isLockFailure, trashPathFor, disposeDir, disposeNote, trashScanRoots, findTrashDirs, cleanupTrashDirs, startTrashCleanup, TRASH_PREFIX, TRASH_RE, TRASH_CLEAN_LIMIT, TRASH_CLEAN_ITEM_MS }
+export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, removeDirVerifiedWithRetry, removeViaShellSync, sleepSync, clearReadonly, waitGone, removeViaShell, shellDeleteCommand, writeQueue, isLockFailure, trashPathFor, disposeDir, disposeNote, trashScanRoots, findTrashDirs, cleanupTrashDirs, startTrashCleanup, TRASH_PREFIX, TRASH_RE, TRASH_CLEAN_LIMIT, TRASH_CLEAN_ITEM_MS }

package/package.json

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