dsh-paoding 0.4.5 → 0.4.7

package/tools/lib/doctor.mjs

@@ -2,7 +2,8 @@
  * `dsh-paoding doctor` 的检查本体：只读体检，不动任何盘。与 health.mjs 的分工
  * ——healthCheck 管「这次保存/应用会怎样」（面向 preview / apply 响应与
  * --dry-run 报告的单次配置体检）；本模块管「这台机器装得正不正」（配置文件、
- * 预设安装轨道、托管声明行、孤儿工作区预设目录、版本标记、预设漂移六项环境
+ * 预设安装轨道、托管声明行（home + profile 层双层：托管块损坏 / 整文件解析 /
+ * 可疑坏行 / 行对账 / 层漂移）、孤儿工作区预设目录、版本标记、预设漂移六项环境
  * 对账），结果形状是人读导向的 { items: [{ status, label, detail }] }：
  *   status: 'ok' | 'warn' | 'error' | 'skip'（skip = 前置事实缺失，降级不炸——
  *   无 DSH_HOME / 无配置的干净机器上各项依此跳过）。
@@ -12,7 +13,8 @@
  * healthCheck 的 preset_drift 判定（同一份 dry-run 对比，不另立标准）。
  *
  * 依赖 config（loadConfig）/ yaml（loadYaml）/ alloc（autoAssignments）/
- * state（collectState）/ workspaces（assignSlugs / presetIdOf）/
+ * state（collectState）/ lifecycle（workspacePresetOrphans，孤儿目录判据与
+ * 清理侧同源）/
  * preset-system（轨道、托管块、标记）与 health（healthCheck）；被 cli 引用。
  * 零运行时依赖（node:fs / node:path / node:url）。
  */
@@ -22,19 +24,21 @@ import { loadConfig } from './config.mjs'
 import { loadYaml } from './yaml.mjs'
 import { autoAssignments } from './alloc.mjs'
 import { collectState } from './state.mjs'
-import { assignSlugs, presetIdOf } from './workspaces.mjs'
+import { workspacePresetOrphans } from './lifecycle.mjs'
 import {
   MANAGED_BEGIN,
   MANAGED_END,
   detectAgentRolesFlavor,
   detectHostVersionInfo,
   detectPresetSystem,
+  findSuspectPresetRows,
   isDeclarativeTriple,
   isPtcWorkerHost,
-  listOrchestratorPresetIds,
   parseGeneratorMarker,
   presetRolesFlavorOf,
   readHomePatchRows,
+  resolvePatchTargetLayer,
+  validatePatchYaml,
 } from './preset-system.mjs'
 import { healthCheck } from './health.mjs'
 
@@ -59,16 +63,6 @@ function managedMarkerLines(text) {
   )
 }
 
-/** 孤儿工作区预设目录对账：配置 workspaces 键组统一过 assignSlugs（与生成层
- * 同源，slug 稳定），得到「配置在册」的 presetId 集合；目录有、名册无 → 孤儿。 */
-function workspacePresetOrphans(dshHome, config) {
-  const dirs = listOrchestratorPresetIds(dshHome).filter((id) => id !== 'orchestrator')
-  if (dirs.length === 0) return { dirs, orphans: [] }
-  const wsPaths = Object.keys(config?.workspaces ?? {})
-  const inRegister = new Set([...assignSlugs(wsPaths).values()].map(presetIdOf))
-  return { dirs, orphans: dirs.filter((id) => !inRegister.has(id)) }
-}
-
 /**
  * 跑全套 doctor 检查。参数（全可缺省，干净机器上逐项降级）：
  *   - dshHome / configFile：DSH 家目录与配置文件路径。
@@ -127,43 +121,99 @@ export async function runDoctor({ dshHome, configFile, profile = null, state = n
     }
   }
 
-  // ── 3. 声明行托管块（~/.dsh/cordis.patch.yml）────────────────────────────
-  // readHomePatchRows 对损坏块自捕返 []，读不出「损坏」——这里直接扫标记行补一道：
-  // 有 BEGIN 没 END = 托管块损坏，所有托管写盘都会被拒绝。
-  let patchText = null
-  try {
-    patchText = readFileSync(path.join(dshHome, 'cordis.patch.yml'), 'utf8')
-  } catch (err) {
-    if (err?.code === 'ENOENT') add('skip', '声明行托管块', 'cordis.patch.yml 不存在（尚无声明行；目录轨宿主也不需要）')
-    else add('skip', '声明行托管块', `cordis.patch.yml 读取失败（${err?.message ?? err}），跳过该项`)
-  }
-  if (patchText !== null) {
+  // ── 3. 声明行托管块（home + 目标 profile 层 patch 双层对账）───────────────
+  // 层判定与写盘侧同一条链（resolvePatchTargetLayer：config 可用时按
+  // patch_layer / profile 键，否则按环境自动——compat 壳 → profile 层）。
+  // 每层四查：托管块损坏（error，既有口径）→ 整文件 YAML 解析（error：compat
+  // 壳压平的坏行会让宿主在任何插件代码运行前死掉，dsh-maoying#1）→ 可疑坏行
+  // （warn，只点名行号不删）→ 行对账（目录轨残留 / 孤儿行，既有口径）。最后
+  // 层漂移：托管块只落在非目标层 → warn（下次自愈 / 保存会写目标层并撤遗留）。
+  const layerTarget = resolvePatchTargetLayer(dshHome, { config })
+  const layerEntries = [
+    { layer: 'home', profileName: null, patchFile: path.join(dshHome, 'cordis.patch.yml') },
+    { layer: 'profile', profileName: layerTarget.profileName, patchFile: layerTarget.patchPath },
+  ]
+  const seenPatchFiles = new Set()
+  let blockLayerSeen = null
+  for (const entry of layerEntries) {
+    if (seenPatchFiles.has(entry.patchFile)) continue // 目标 profile 恰为 'web' 时与 home 同文件，不双报
+    seenPatchFiles.add(entry.patchFile)
+    let patchText = null
+    try {
+      patchText = readFileSync(entry.patchFile, 'utf8')
+    } catch (err) {
+      // home 层缺失维持既有 skip 口径（干净机器各项依此跳过）；profile 层缺失
+      // 是常态（非 compat 壳 / 从未迁移过），静默。
+      if (entry.layer === 'home' && err?.code === 'ENOENT') {
+        add('skip', '声明行托管块', 'cordis.patch.yml 不存在（尚无声明行；目录轨宿主也不需要）')
+      } else if (err?.code !== 'ENOENT') {
+        add('skip', '声明行托管块', `${entry.patchFile} 读取失败（${err?.message ?? err}），跳过该层`)
+      }
+      continue
+    }
+    const layerName = entry.layer === 'home' ? '' : `（profile 层 ${entry.patchFile}）`
     const markers = managedMarkerLines(patchText)
     const hasBegin = markers.has(MANAGED_BEGIN)
     const hasEnd = markers.has(MANAGED_END)
+    if (hasBegin) blockLayerSeen = blockLayerSeen ?? entry.layer
     if (hasBegin && !hasEnd) {
-      add('error', '声明行托管块', '托管块损坏（只有起始标记没有结束标记）：补回结束标记或删除整块，否则面板保存 / 自愈都会拒绝写盘')
-    } else {
+      add('error', '声明行托管块', `${layerName}托管块损坏（只有起始标记没有结束标记）：补回结束标记或删除整块，否则面板保存 / 自愈都会拒绝写盘`)
+    }
+    // 整文件 YAML 解析（宿主 yaml 包口径，与写盘校验 validatePatchYaml 同源；
+    // yaml 包缺失退内置子集解析器——lenient，只兜 gross 损坏挡不住坏缩进）。
+    const parseVerdict = validatePatchYaml(dshHome, patchText)
+    if (!parseVerdict.ok) {
+      add(
+        'error',
+        'patch 文件解析',
+        `${entry.patchFile} 无法解析：${parseVerdict.message}——宿主启动会直接失败。请删除坏行或从 .bak-1 备份恢复` +
+          '（Android compat 壳重写 patch 压平坏行的特征参见 dsh-maoying#1）',
+      )
+    }
+    // 可疑坏行（maoying 坏行形状）：warn 点名行号，只诊断不删——删行可能踩
+    // 用户手写内容，修复交给人或清理侧的行级手术。
+    const suspects = findSuspectPresetRows(patchText)
+    if (suspects.length > 0) {
+      const lineNos = suspects.map((s) => s.lineNo).join('、')
+      add(
+        'warn',
+        '声明行可疑行',
+        `${entry.patchFile} 第 ${lineNos} 行检出可疑声明行（如 "- id: ${suspects[0].id}"——id 含空白或非 ASCII，` +
+          '形如 compat 壳把显示名压平进 id 位产生的坏行，宿主 YAML 解析会失败，参见 dsh-maoying#1）' +
+          '——请删除坏行或从 .bak-1 备份恢复后重试',
+      )
+    }
+    // 行对账（损坏块时 readHomePatchRows 自捕返空数组——损坏已单独报，这里
+    // 只在块结构完好时做逐行对账，避免损坏块上报出误导性的「无声明行」）。
+    if (!hasBegin || hasEnd) {
       let rows = []
       try {
-        rows = readHomePatchRows(dshHome)
+        rows = readHomePatchRows(dshHome, { layer: entry.layer, profileName: entry.profileName ?? 'web' })
       } catch {
         rows = []
       }
       if (rows.length === 0) {
-        add('ok', '声明行托管块', hasBegin ? '托管块存在但无声明行' : 'cordis.patch.yml 无托管块（目录轨宿主无需声明行）')
+        add('ok', '声明行托管块', hasBegin ? `${layerName}托管块存在但无声明行` : `${entry.layer === 'home' ? '' : `${entry.patchFile} `}无托管块（目录轨宿主无需声明行）`)
       } else {
         const orphans = rows.filter((row) => row.presetId && !existsSync(path.join(dshHome, '.agent-presets', row.presetId)))
         if (track === 'directory') {
-          add('warn', '声明行托管块', `检出 ${rows.length} 条声明行，但宿主是目录轨（≤ 0.1.6）——残留声明行会让 profile 启动失败，重启 DSH 触发自愈撤下`)
+          add('warn', '声明行托管块', `${layerName}检出 ${rows.length} 条声明行，但宿主是目录轨（≤ 0.1.6）——残留声明行会让 profile 启动失败，重启 DSH 触发自愈撤下`)
         } else if (orphans.length > 0) {
-          add('warn', '声明行托管块', `孤儿声明行（指向已删目录）：${orphans.map((o) => o.rowId).join('、')}——重启 DSH 自愈会撤下，或重新应用一次同步`)
+          add('warn', '声明行托管块', `${layerName}孤儿声明行（指向已删目录）：${orphans.map((o) => o.rowId).join('、')}——重启 DSH 自愈会撤下，或重新应用一次同步`)
         } else {
-          add('ok', '声明行托管块', `${rows.length} 条声明行均指向存在的预设目录`)
+          add('ok', '声明行托管块', `${layerName}${rows.length} 条声明行均指向存在的预设目录`)
         }
       }
     }
   }
+  if (blockLayerSeen !== null && blockLayerSeen !== layerTarget.layer) {
+    add(
+      'warn',
+      'patch 层漂移',
+      `声明行托管块在 ${blockLayerSeen} 层，当前判定目标层是 ${layerTarget.layer}（${layerTarget.patchPath}）` +
+        '——下次自愈 / 保存会写目标层并撤下这层的遗留块（compat 壳迁移行为，参见 dsh-maoying#1）',
+    )
+  }
 
   // ── 4. 孤儿工作区预设目录（.agent-presets/orchestrator-*）─────────────────
   if (!configUsable && existsSync(configFile)) {

package/tools/lib/lifecycle.mjs

@@ -0,0 +1,333 @@
+/**
+ * 生命周期清理共享层 —— `dsh-paoding uninstall` 与 `doctor --fix` 共用的落盘
+ * 清理原语。两者清理的东西同源（cordis.patch.yml 托管块、.agent-presets 下的
+ * orchestrator* 预设目录、.generator-version 标记），判别口径也与 doctor 只读
+ * 体检同源（孤儿目录 = workspacePresetOrphans，孤儿声明行 = presetId 指向的
+ * 目录已不存在），本模块把「怎么删」收敛在一处，两个命令只决定「删哪些」。
+ *
+ * 备份纪律：一次清理调用对每个 patch 文件（home 层 cordis.patch.yml 与各
+ * profile 层 profiles/<name>/cordis.patch.yml——compat 壳把托管块搬进 profile
+ * 层，见 managedBlockStateAll）至多备份一份 .bak-1（首次写盘前拷贝，已有同名
+ * 备份覆盖——只保「本次改动前」的原貌），同一次调用里对同一文件的后续写不再
+ * 覆盖这份首备。配置文件 dsh-paoding.config.yml 是用户数据，只有 uninstall
+ * --purge 才动，删除前列在计划里。
+ *
+ * 依赖 preset-system（托管块手术与轨道原语）/ workspaces（slug 名册）/
+ * config（loadConfig）；被 doctor / cli 引用。绝不触碰插件包自身目录——包
+ * 本体的卸载通道只有 dsh plugin remove（bin 入口注释同款口径）。
+ */
+import { copyFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { loadConfig } from './config.mjs'
+import { assignSlugs, presetIdOf } from './workspaces.mjs'
+import {
+  MANAGED_BEGIN,
+  MANAGED_END,
+  listOrchestratorPresetIds,
+  presetRowId,
+  readHomePatchRows,
+  stripHomePatchRows,
+} from './preset-system.mjs'
+
+/** cordis.patch.yml 写前备份的后缀（只保一份，重复清理覆盖上一份）。 */
+export const PATCH_BACKUP_SUFFIX = '.bak-1'
+
+/** 生成器标记文件名：位置固定在 .agent-presets/orchestrator/ 里（api-core
+ * ensurePresetInstalled 与 doctor 版本标记项同址），随基础预设目录同生同灭。 */
+export const GENERATOR_MARKER_NAME = '.generator-version'
+
+/** 生成器标记文件的完整路径（位置以 preset-system / api-core 的代码为准）。 */
+export function generatorMarkerPath(dshHome) {
+  return path.join(dshHome, '.agent-presets', 'orchestrator', GENERATOR_MARKER_NAME)
+}
+
+/**
+ * 写前备份：把 file 原样拷成 `${file}${PATCH_BACKUP_SUFFIX}`（已存在则覆盖，
+ * 只保最近一份）。file 不存在返回 null（没得备份，也不造空备份）；拷贝失败
+ * 上抛——备份失败宁可中止清理，不做无备份的破坏性写。
+ */
+export function backupBeforeWrite(file) {
+  if (!existsSync(file)) return null
+  const backupPath = `${file}${PATCH_BACKUP_SUFFIX}`
+  copyFileSync(file, backupPath)
+  return backupPath
+}
+
+/**
+ * cordis.patch.yml 里庖丁托管块的在场状态：{ present, corrupt }。present 按
+ * 起始标记行判断（与 doctor 声明行托管块项同一读法）；有起始没结束 = 损坏，
+ * 此时任何托管写盘都会被 preset-system 拒绝，清理方只能降级成「需手工」。
+ * 文件缺失 / 读不了 → 全 false（无可清理）。
+ */
+export function managedBlockState(dshHome) {
+  let text = null
+  try {
+    text = readFileSync(path.join(dshHome, 'cordis.patch.yml'), 'utf8')
+  } catch {
+    return { present: false, corrupt: false }
+  }
+  const marks = new Set(String(text).split(/\r?\n/).map((l) => l.trim()))
+  const present = marks.has(MANAGED_BEGIN)
+  return { present, corrupt: present && !marks.has(MANAGED_END) }
+}
+
+/**
+ * 全层托管块在场状态（managedBlockState 的双层版；managedBlockState 本身保持
+ * 只报 home 层的旧口径不动）：home 层恒在列表首位（文件缺失 present=false），
+ * 其后是 profiles/<name>/cordis.patch.yml 里真实存在的每一层。每项
+ * { layer: 'home'|'profile', profileName: null|<name>, patchFile, present,
+ * corrupt }。compat 壳把托管块搬进 profile 层后，uninstall / doctor --fix
+ * 必须两层都过一遍，否则卸载会在 home 层空转、profile 层残留整块声明行。
+ */
+export function managedBlockStateAll(dshHome) {
+  const entries = [{ layer: 'home', profileName: null, patchFile: path.join(dshHome, 'cordis.patch.yml') }]
+  try {
+    for (const name of readdirSync(path.join(dshHome, 'profiles')).sort()) {
+      const patchFile = path.join(dshHome, 'profiles', name, 'cordis.patch.yml')
+      if (existsSync(patchFile)) entries.push({ layer: 'profile', profileName: name, patchFile })
+    }
+  } catch { /* 无 profiles 目录：只有 home 层 */ }
+  return entries.map((entry) => {
+    let text = null
+    try {
+      text = readFileSync(entry.patchFile, 'utf8')
+    } catch {
+      return { ...entry, present: false, corrupt: false }
+    }
+    const marks = new Set(String(text).split(/\r?\n/).map((l) => l.trim()))
+    const present = marks.has(MANAGED_BEGIN)
+    return { ...entry, present, corrupt: present && !marks.has(MANAGED_END) }
+  })
+}
+
+/** managedBlockStateAll 条目 → preset-system 手术 opts（home 层恒 home 口径）。 */
+const layerOptsOf = (entry) => ({ layer: entry.layer, profileName: entry.profileName ?? 'web' })
+
+/**
+ * 配置文件对账读法（doctor 配置文件项同一判据）：缺失返回 { config: null,
+ * exists: false, usable: false }；存在但解析失败 → { exists: true, usable:
+ * false }（此时宁可当孤儿全量处理也不敢对账的目录一律不动，见
+ * workspacePresetOrphans 的调用方约束）；存在且可解析 → config 原样。
+ */
+export function loadConfigForReconcile(configFile, yamlMod) {
+  if (!existsSync(configFile)) return { config: null, exists: false, usable: false }
+  try {
+    return { config: loadConfig(configFile, yamlMod), exists: true, usable: true }
+  } catch {
+    return { config: null, exists: true, usable: false }
+  }
+}
+
+/**
+ * 孤儿工作区预设目录对账（doctor「工作区预设目录」项同源判据，从 doctor 移植
+ * 到这里供清理侧复用）：配置 workspaces 键组统一过 assignSlugs（与生成层同源，
+ * slug 稳定）得到「配置在册」的 presetId 集合；目录有、名册无 → 孤儿。基础
+ * orchestrator 永不算孤儿（启动自愈会重装它）。注意调用方约束：configFile
+ * 存在但不可解析时不要调用（doctor 该项直接降级 skip，清理侧同样必须跳过，
+ * 详见 loadConfigForReconcile）。
+ */
+export function workspacePresetOrphans(dshHome, config) {
+  const dirs = listOrchestratorPresetIds(dshHome).filter((id) => id !== 'orchestrator')
+  if (dirs.length === 0) return { dirs, orphans: [] }
+  const wsPaths = Object.keys(config?.workspaces ?? {})
+  const inRegister = new Set([...assignSlugs(wsPaths).values()].map(presetIdOf))
+  return { dirs, orphans: dirs.filter((id) => !inRegister.has(id)) }
+}
+
+/**
+ * 孤儿声明行（doctor「声明行托管块」项同一判据）：托管块里 presetId 指向的
+ * .agent-presets 目录已不存在的行。含本机历史遗留的旧 insert（如指向早已
+ * 不存在的 paoding-config-ui 的声明行）——判据只认「目录没了」，不认行名。
+ * presetId 解析不出的行不在此列（doctor 不点名它，清理侧也不动它，交给用户）。
+ * 托管块损坏时返回空数组（损坏块只能整块手工处理，行级手术做不了）。
+ * 双层扫描：home 与各 profile 层的孤儿行并集（rowId 去重——同一 preset 的行
+ * 理论上只在一层，两层都在场时清理侧会逐层各撤一遍）。
+ */
+export function orphanManagedRows(dshHome) {
+  const seen = new Set()
+  const out = []
+  for (const entry of managedBlockStateAll(dshHome)) {
+    if (!entry.present || entry.corrupt) continue
+    for (const row of readHomePatchRows(dshHome, layerOptsOf(entry))) {
+      const key = `${entry.layer}:${row.rowId}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      if (row.presetId && !existsSync(path.join(dshHome, '.agent-presets', row.presetId))) out.push(row)
+    }
+  }
+  return out
+}
+
+/**
+ * 清理执行器（uninstall 与 doctor --fix 共用，别在外面另拼删盘逻辑）：
+ *   - stripBlock: true → 整块摘除托管块（uninstall；含起止标记与块前空行分隔）
+ *   - pruneRowIds: 撤指定 rowId 的声明行段（doctor --fix 的孤儿行清理）
+ *   - removeDirIds: 删指定 orchestrator* 预设目录（rmSync 逐个，单目录失败不
+ *     拖垮其余）；声明行轨上被删目录的声明行同步撤下（目录与行同生同灭，与
+ *     generateAndInstall 的孤儿回收口径一致）
+ *   - 删完目录后 .generator-version 若仍在（理论上随基础目录已走，防御性兜底）
+ *     一并删除并在结果里注明
+ * 备份纪律见模块头：对每个 patch 文件（home / 各 profile 层）的首次写前备份
+ * .bak-1，之后不再覆盖；backupPath 兼容旧字段（首个备份），backupPaths 列全。
+ * 托管块手术双层循环（managedBlockStateAll：compat 壳把块搬进 profile 层后，
+ * 只清 home 层的旧卸载会空转），损坏块不碰：preset-system 会拒绝写盘，降级
+ * 给调用方报需手工。返回结构化结果（字段见实现），全程不 throw——单步失败
+ * 折进对应字段，由调用方决定退出码与文案。
+ */
+export function cleanupPaodingArtifacts(dshHome, { stripBlock = false, pruneRowIds = [], removeDirIds = [] } = {}) {
+  const result = {
+    backupPath: null, // 旧字段：首个写前备份（向后兼容 cli 打印）
+    backupPaths: [], // 本次实际落下的全部备份（每层 patch 至多一份）
+    blockPresent: false,
+    blockCorrupt: false,
+    blockRemoved: false,
+    prunedRowIds: [],
+    markerRemoved: false,
+    removedDirs: [],
+    dirFailures: [],
+  }
+
+  const layers = managedBlockStateAll(dshHome)
+  result.blockPresent = layers.some((l) => l.present)
+  result.blockCorrupt = layers.filter((l) => l.present).some((l) => l.corrupt)
+  const prunedSeen = new Set()
+
+  const backupDone = new Set()
+  const backupOnce = (patchFile) => {
+    if (backupDone.has(patchFile)) return
+    backupDone.add(patchFile)
+    const backupPath = backupBeforeWrite(patchFile)
+    if (backupPath !== null) {
+      result.backupPaths.push(backupPath)
+      if (result.backupPath === null) result.backupPath = backupPath
+    }
+  }
+
+  // 1) 托管块手术（逐层；损坏块不碰：preset-system 会拒绝写盘，降级给调用方报需手工）
+  for (const entry of layers.filter((l) => l.present && !l.corrupt)) {
+    const opts = layerOptsOf(entry)
+    const rowsOnDisk = readHomePatchRows(dshHome, opts).map((r) => r.rowId)
+    if (stripBlock) {
+      backupOnce(entry.patchFile)
+      if (stripHomePatchRows(dshHome, null, opts)) result.blockRemoved = true
+    } else if (pruneRowIds.length > 0) {
+      const present = pruneRowIds.filter((id) => rowsOnDisk.includes(id))
+      if (present.length > 0) {
+        backupOnce(entry.patchFile)
+        // stripHomePatchRows 返回 true = 指定段确已撤下；块里本来就没有的 id
+        // 不算撤（present 已过滤），不虚报。同一 rowId 两层都在场时各撤一遍，
+        // 结果里只记一次（Set 去重）。
+        if (stripHomePatchRows(dshHome, present, opts)) for (const id of present) prunedSeen.add(id)
+      }
+    }
+  }
+  result.prunedRowIds = [...prunedSeen]
+
+  // 2) 预设目录删除 + 声明行同步（目录先删，行后撤——与孤儿回收同序；行逐层清）
+  if (removeDirIds.length > 0) {
+    for (const id of removeDirIds) {
+      const dir = path.join(dshHome, '.agent-presets', id)
+      try {
+        rmSync(dir, { recursive: true, force: true })
+        result.removedDirs.push(id)
+      } catch (err) {
+        result.dirFailures.push({ id, error: err?.message ?? String(err) })
+      }
+    }
+    const removedIds = new Set(result.removedDirs)
+    for (const entry of layers.filter((l) => l.present && !l.corrupt)) {
+      const opts = layerOptsOf(entry)
+      const danglingRowIds = readHomePatchRows(dshHome, opts)
+        .filter((r) => r.presetId && removedIds.has(r.presetId))
+        .map((r) => r.rowId)
+      if (danglingRowIds.length > 0) {
+        backupOnce(entry.patchFile)
+        stripHomePatchRows(dshHome, danglingRowIds, opts)
+      }
+    }
+  }
+
+  // 3) 版本标记兜底：正常随基础 orchestrator 目录一起删；防御目录删除整体失败
+  //（dirFailures）或外部摆了非常规布局时补一手，保证「卸载后无标记残留」。
+  const markerPath = generatorMarkerPath(dshHome)
+  if (existsSync(markerPath)) {
+    try {
+      rmSync(markerPath, { force: true })
+      result.markerRemoved = true
+    } catch { /* 删不掉就留着：dirFailures / 保留提示里已能解释现场 */ }
+  }
+
+  return result
+}
+
+/**
+ * 卸载计划（只读侦察，不落盘）：给确认提示、非 TTY 防呆打印与「无事可做」
+ * 判定共用。不加载配置文件内容（卸载不依赖配置语义），只看存在性。
+ * blockPresent / blockCorrupt / blockRowCount 聚合双层（compat 壳的 profile 层
+ * 托管块也算在场）；patchFile 保留 home 层路径的旧字段口径，patchFiles 列出
+ * 各层实际在场托管块的文件（供调用方点名 profile 层残留）。
+ */
+export function planUninstall({ dshHome, configFile } = {}) {
+  const layers = managedBlockStateAll(dshHome)
+  const markerPath = generatorMarkerPath(dshHome)
+  let blockRowCount = 0
+  for (const entry of layers.filter((l) => l.present && !l.corrupt)) {
+    blockRowCount += readHomePatchRows(dshHome, layerOptsOf(entry)).length
+  }
+  return {
+    dshHome,
+    configFile,
+    patchFile: path.join(dshHome, 'cordis.patch.yml'),
+    patchFiles: layers.filter((l) => l.present).map((l) => l.patchFile),
+    blockPresent: layers.some((l) => l.present),
+    blockCorrupt: layers.filter((l) => l.present).some((l) => l.corrupt),
+    blockRowCount,
+    presetDirs: listOrchestratorPresetIds(dshHome),
+    markerPath,
+    markerExists: existsSync(markerPath),
+    configExists: existsSync(configFile),
+    configBackups: listConfigBackupFiles(configFile),
+  }
+}
+
+/**
+ * 配置文件的备份兄弟文件（`dsh-paoding.config.yml.bak*`，用户或历史工具手工
+ * 留的）：--purge 时连这些一起删；默认保留时提示里点名数量。
+ */
+export function listConfigBackupFiles(configFile) {
+  const dir = path.dirname(configFile)
+  const base = path.basename(configFile)
+  let names = []
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return []
+  }
+  return names
+    .filter((name) => name.startsWith(`${base}.bak`))
+    .sort()
+    .map((name) => path.join(dir, name))
+}
+
+/** --purge 的配置删除：配置文件 + 全部 .bak* 备份逐个删，返回实际删掉的路径。 */
+export function removeConfigAndBackups(configFile) {
+  const removed = []
+  for (const file of [configFile, ...listConfigBackupFiles(configFile)]) {
+    try {
+      rmSync(file, { force: true })
+      removed.push(file)
+    } catch { /* 删不掉就留着，由调用方在收尾提示里交代 */ }
+  }
+  return removed
+}
+
+/** .agent-presets 下与庖丁无关的残留目录名（如用户自制 preset），卸载后提示「未动」。 */
+export function foreignPresetDirsRemaining(dshHome) {
+  let names = []
+  try {
+    names = readdirSync(path.join(dshHome, '.agent-presets'))
+  } catch {
+    return []
+  }
+  return names.filter((name) => !/^orchestrator(-[a-z0-9-]+)?$/.test(name)).sort()
+}