kld-sdd 2.7.8-4 → 2.7.8-5

package/README.md

@@ -6,6 +6,30 @@ KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语
 
 日常提交默认只保留本地关联 Hook；Apply 自动执行代码/Spec 检查、真实测试与交付验证。旧项目升级、备份回退、多仓和 CI 边界见 [Git Hook 调整说明](USABILITY.md#2026-09-10git-hook-收缩与交付验证)。
 
+## 工具更新与卸载
+
+**更新不需要先卸载。** 在原工作目录重新运行安装器，覆盖运行脚本、Skills 和只读模板；Spec 文档、KB 绑定、项目身份、历史数据、用户配置和自定义 Hook 保留。先确认目标编辑器及 Spec 目录，完成后检查实际部署版本。下载失败不启动安装；执行中断后可以重跑补齐，不承诺整个项目的事务回滚。
+
+```bash
+# 选择包含本次修复的新发布版本，在原工作目录更新
+npx kld-sdd@<新版版本号> --tool=cursor --spec-path=team-sdd-specs --skip-openspec
+
+# 卸载只有工具一种方式；可以先看计划
+npx kld-sdd@<新版版本号> uninstall --dry-run
+npx kld-sdd@<新版版本号> uninstall
+```
+
+卸载不再提供全量删除，旧 `--purge` 参数会报错退出。`openspec/`（含活动变更、归档和规格）、KB 配置、身份、历史数据、`.sdd.yaml`、`.sdd-spec-root`、`.sdd-workspace.yaml`、Git 关联和隐私忽略规则始终保留。工具目录内的未知文件和自建规则也保留；Git Hook 只有完整匹配受管版本时才删除。预览后文件改变需要重新预览。
+
+多仓注意：
+
+- 升级沿用已有清单，只维护登记的代码仓；多个 Spec 和备份不会互相接入。新代码仓通过 `kld-sdd sync-repos` 明确接入，追加清单时保留注释、自定义字段和原有记录。
+- 本地路径、团队远程声明或工作区清单冲突时，先停止更新并提示核对，不自动换绑。
+- 从单个代码仓卸载时，工作目录外的共享 Spec 工具保留。从 worktree 卸载时，共用的 Git Hook 保留，应从主仓库管理。
+- 旧平铺 `skywalk-sdd/` 只清理已知工具，历史数据原位保留，不自动合并两份项目身份或运行状态。
+
+以上行为需要使用包含本次改动的新版本；修改此源码不会改变已经发布的 npm 包。安装包通过 `sddMaintenance.toolOnly: 1` 声明该维护契约，托盘据此避免用旧安装器处理存在已知清理风险的布局。
+
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

package/bin/kld-sdd-init.js

@@ -12,7 +12,7 @@
  *   log          SDD Telemetry CLI（记录阶段事件、查询指标）
  *   link-spec    将代码仓关联到本地 spec clone（git config sdd.specPath）
  *   sync-repos   工作目录下发现新增代码仓并轻量接入（不装 skills）
- *   uninstall    卸载 SDD 产物（渐进式：先选方式，再预览计划，最后确认执行）
+ *   uninstall    卸载 SDD 产物（渐进式：先预览工具范围，最后确认执行）
  */
 
 'use strict';
@@ -136,19 +136,19 @@ function parseInitArgs(argv = cliArgs(), env = process.env) {
  * kld-sdd uninstall [选项]
  *
  * 卸载产物与编辑器无关（8 个编辑器的产物全量扫描），工作目录固定为当前目录，
- * 故不提供 --tool / --project：卸载范围由「方式选择」决定，目录由 cwd 决定。
+ * 故不提供 --tool / --project：仅卸载当前范围的工具，目录由 cwd 决定。
  *
  * --spec-path 用于无人值守场景：多候选（如用户复制的备份）时无法自动判定，
  * 需显式指定要卸载的 spec 仓库。
  */
 function parseUninstallArgs(argv = cliArgs()) {
-  const purge = argv.includes('--purge');
+  if (argv.some(arg => arg === '--purge' || arg.startsWith('--purge=') || arg === '--full' || arg.startsWith('--mode'))) {
+    throw new Error('已取消全量删除，仅支持卸载工具；Spec 文档、配置与历史数据始终保留');
+  }
   return {
     cwd: process.cwd(),
     specPath: parseSpecPathOption(argv),
-    mode: purge ? MODE.FULL : MODE.TOOLS_ONLY,
-    // 是否显式指定了方式：未指定且未跳过交互时，进入渐进式方式选择
-    modeExplicit: purge,
+    mode: MODE.TOOLS_ONLY,
     dryRun: argv.includes('--dry-run'),
     yes: hasFlag(argv, '--yes', '-y'),
     help: hasFlag(argv, '-h', '--help'),
@@ -325,78 +325,26 @@ async function selectSpecRoot(prompt, candidates, options = {}) {
   return selectSpecChoice(prompt, candidates, options);
 }
 
-/**
- * 渐进式选择卸载方式。
- * 默认「1 卸载工具内容」为保守选项，回车即安全；无效输入重新询问。
- *
- * @returns {Promise<string|null>} MODE 之一；null 表示用户取消
- */
-async function selectUninstallMode(prompt) {
-  while (true) {
-    // 选项文本并入 question：readline 重绘提示行会发 \x1b[0J（清除光标之后内容），
-    // 提问前的 console.log 会被抹掉，导致用户看不到选项。
-    const question = [
-      '请选择卸载方式:',
-      '  1. 卸载工具内容（默认，保留用户配置与运行时数据）',
-      '     删除 编辑器 skills / hook 脚本 / skywalk-sdd 工具脚本 / 文档模版',
-      '     保留 modules.yaml、sdd.config.yaml、.sdd.yaml、events/、state/',
-      '  2. 全量卸载（含用户配置、运行时数据与文档工作区）',
-      '     在「1」的基础上，额外删除上述用户配置、历史度量数据与 openspec/ 整目录',
-      '     ⚠️  openspec/ 内含 changes/ 变更提案与 specs/ 业务规格文档，将一并删除',
-      '  0. 取消',
-      '\n请输入选项 (0-2，直接回车=1): ',
-    ].join('\n');
-
-    const answer = await prompt.ask(question);
-    if (answer === '' || answer === '1') return MODE.TOOLS_ONLY;
-    if (answer === '2') return MODE.FULL;
-    if (answer === '0' || /^(q|quit|exit)$/i.test(answer)) return null;
-    console.log(`❌ 无效选项 "${answer}"，请输入 0-2 之间的数字\n`);
-  }
-}
-
 /** 显示卸载帮助信息 */
 function showUninstallHelp() {
   console.log(`
-KLD SDD 卸载工具
+KLD SDD 工具卸载
 
 用法:
-  kld-sdd uninstall               # 渐进式交互（推荐）：选方式 → 预览计划 → 确认
-  kld-sdd uninstall [选项]        # 非交互：显式给出方式与确认
+  kld-sdd uninstall                 # 选择 Spec → 预览范围 → 确认
+  kld-sdd uninstall --dry-run       # 只看计划，不修改文件
+  kld-sdd uninstall --yes --spec-path <dir>  # 明确范围后用于脚本
 
-选项:
-  -h, --help       显示本帮助
-  --purge          全量卸载（含用户配置与运行时数据）；不指定则只卸载工具内容
-  --dry-run        预演，打印计划预览但不落盘（不进入交互）
-  --spec-path <dir> 显式指定要卸载的 spec 仓库（无人值守时多候选必须指定）
-  -y, --yes        跳过最后的执行确认（CI / 脚本用）
-
-说明:
-  卸载在「当前目录」执行，产物范围为全部 8 个编辑器（cursor, claude, codebuddy,
-  qoder, opencode, kunlunzhima, workbuddy, codex），无需也无法指定编辑器。
-  卸载范围由方式选择（工具内容 / 全量）决定。需在目标项目目录下执行本命令。
-
-  交互流程：spec 仓库选择 → 卸载方式选择 → 计划预览 → 确认执行。
-  若检测到多个 spec 仓库（例如您手动复制了一份备份），会列出候选让您单选；
-  无人值守（--yes / 无 TTY）时多候选会直接报错，请用 --spec-path 指定。
-
-两种方式的区别:
-  工具内容卸载（默认）:
-    删除  编辑器 skills（opsx-* / tdd-* / openspec-*）、sdd-*.cjs hook 脚本、
-          hook-gate-core.cjs、skywalk-sdd/ 工具脚本、openspec-templates/、操作手册
-    保留  settings.json 文件本身（仅摘除 SDD 受管 hook）、modules.yaml、
-          sdd.config.yaml、.sdd.yaml、.sdd-spec-root、skywalk-sdd/events/ 与 state/、
-          openspec/ 文档工作区
-  全量卸载（--purge）:
-    在「工具内容卸载」基础上，额外删除上述保留项中的用户配置、历史度量数据，
-    以及 openspec/ 整目录（含 changes/ 变更提案、specs/ 业务规格与 overview.md、
-    config.yaml）。执行前会打印待删目录与文件数，需二次确认。
+仅删除可识别的 SDD Skills、运行脚本、只读模板与受管 Hook。
+始终保留 openspec/ 全部文档、KB 配置、项目身份、历史数据、多仓关联和 Git 历史。
+自定义 Hook、规则、未知文件与隐私忽略规则保留。不提供全量删除模式。
 
-示例:
-  kld-sdd uninstall                          # 交互式，最常用（在项目目录下执行）
-  kld-sdd uninstall --dry-run                # 只看计划
-  kld-sdd uninstall --purge --dry-run        # 全量预演
-  kld-sdd uninstall --purge --yes            # 全量执行，不询问
+-h, --help         显示本帮助
+--spec-path <dir>  指定目标 Spec；多个候选时必须选择，备份不受影响
+--dry-run          只预览
+-y, --yes          确认工具卸载；非交互执行必须提供
+
+升级不需要先卸载：重新运行 init 覆盖工具文件，保留已有文档及配置。
 `);
 }
 
@@ -409,8 +357,8 @@ KLD SDD 项目初始化工具
   kld-sdd-init [选项]
   npx kld-sdd [选项]
   kld-sdd sync-repos           # 工作目录下发现新增代码仓并轻量接入（多 spec 候选时单选）
-  kld-sdd uninstall [选项]     # 卸载 SDD 产物（渐进式：选方式 → 预览 → 确认）
-  kld-sdd uninstall --help     # 查看卸载选项与两种方式的区别
+  kld-sdd uninstall [选项]     # 卸载 SDD 产物（渐进式：预览工具范围 → 确认）
+  kld-sdd uninstall --help     # 查看工具卸载与保留范围
 
 选项:
   -h, --help       显示帮助信息
@@ -484,7 +432,7 @@ async function runInit() {
 /**
  * 卸载（渐进式）：方式选择 → 计划预览 → 确认执行。
  *
- * 交互编排全部在本函数（CLI 输入层）；lib/uninstall 只提供纯计算与执行：
+ * 交互编排全部在本函数（CLI 输入层）；仅选择 Spec、预览工具范围并确认：
  * - buildUninstallPlan  纯计算计划，不落盘
  * - main                按给定计划执行，无交互
  *
@@ -524,7 +472,7 @@ async function runUninstall(argv = args, deps = {}) {
   // 候选枚举：结构判据无法区分「当前项目的 spec 仓」与「用户复制的备份」
   //（如 `erp-sdd-specs copy` 结构标记齐全），故由用户单选裁决。
   // 显式 --spec-path 时跳过枚举（调用方已指定）。
-  let specRoot = opts.specPath ? path.resolve(opts.specPath) : undefined;
+  let specRoot = opts.specPath ? path.resolve(cwd, opts.specPath) : undefined;
   const candidates = specRoot ? [] : listSpecCandidatesForUninstall(cwd);
 
   if (!specRoot && candidates.length > 1 && !canPrompt) {
@@ -539,6 +487,7 @@ async function runUninstall(argv = args, deps = {}) {
     throw new Error('多个 spec 仓库候选，需 --spec-path 显式指定');
   }
 
+  if (!specRoot && !canPrompt && candidates.length === 1) specRoot = candidates[0].abs;
   const prompt = canPrompt ? promptFactory() : null;
 
   // 步骤 1：spec 仓库选择（多候选 → 用户单选；单候选 → 确认）
@@ -563,31 +512,15 @@ async function runUninstall(argv = args, deps = {}) {
     }
 
     if (!prompt) {
+      if (!dryRun && !opts.yes) throw new Error('非交互卸载需要 --yes；可先用 --dry-run 预览');
       printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
       if (dryRun) printPlanPreview(planned.plan);
       // 已打印过预览（含警告）时不重复；直接执行时由 lib 打印
-      runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: !dryRun });
+      const result = runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: !dryRun });
+      if (!result.ok) throw new Error(result.errors.join('; '));
       return;
     }
 
-    // 步骤 3：方式选择（已显式 --purge 则跳过）
-    if (!opts.modeExplicit) {
-      const chosen = await selectUninstallMode(prompt);
-      if (chosen === null) {
-        console.log('已取消');
-        return;
-      }
-      if (chosen !== mode) {
-        mode = chosen;
-        planned = buildUninstallPlan({ cwd, mode, specRoot });
-        if (planned.plan.ops.length === 0) {
-          printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
-          console.log('ℹ️  未发现需要处理的 SDD 产物（可能未初始化或已卸载）');
-          return;
-        }
-      }
-    }
-
     // 步骤 4：计划预览
     printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
     printPlanPreview(planned.plan);
@@ -602,7 +535,8 @@ async function runUninstall(argv = args, deps = {}) {
     console.log('');
 
     // 交互路径：警告已由 printPlanPreview 打印过，不再重复
-    runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: false });
+    const result = runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: false });
+    if (!result.ok) throw new Error(result.errors.join('; '));
   } finally {
     if (prompt) prompt.close();
   }
@@ -724,7 +658,6 @@ module.exports = {
   runUninstall,
   parseUninstallArgs,
   printPlanPreview,
-  selectUninstallMode,
   selectSpecRoot,
   showUninstallHelp,
 };

package/lib/init.js

@@ -31,6 +31,7 @@ const {
 const { deployCodebuddyHookPack } = require('./deploy-codebuddy-hooks');
 const { PROVIDERS, computeMergedSettings } = require('./settings-merge');
 const workspaceLayout = require('./workspace-layout');
+const maintenance = require('./maintenance');
 const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
 // spec 判据与候选枚举的唯一入口（tier 分级 + 排序）
 const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
@@ -336,6 +337,7 @@ function copyDirRendered(source, target, config, toolKey) {
   return deployDir(source, target, {
     strategy: STRATEGY.OVERWRITE,
     render: (srcPath, tgtPath) => {
+      if (path.basename(srcPath) === 'config.json' && fs.existsSync(tgtPath)) return fs.readFileSync(tgtPath, 'utf8');
       const rendered = renderTemplate(fs.readFileSync(srcPath, 'utf8'), config, toolKey, profile);
       validateRenderedContent(rendered, profile, tgtPath);
       return rendered;
@@ -1077,6 +1079,9 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
+  const conflict = maintenance.associationConflict(cwd, specRoot);
+  if (conflict) return { ok: false, repo: label, message: conflict };
+
   console.log(`🔗 轻量接入代码仓（本地关联 Hook）: ${label}`);
 
   const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
@@ -1347,13 +1352,20 @@ function removeOuterSkywalk(anchorDir) {
       return { ok: true, removed: true, mode: 'symlink' };
     }
     if (st.isDirectory()) {
-      fs.rmSync(outer, { recursive: true, force: true });
-      console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd/（实体在包裹包）');
-      return { ok: true, removed: true, mode: 'directory' };
+      // 旧目录可能存有 KB 身份、待上报事件和用户文件，不能整目录删除。
+      for (const file of maintenance.runtimeToolFiles(outer)) fs.unlinkSync(file);
+      const prune = dir => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory() && !['events', 'state'].includes(entry.name)) prune(path.join(dir, entry.name));
+        }
+        if (!fs.readdirSync(dir).length) fs.rmdirSync(dir);
+      };
+      prune(outer);
+      const retained = fs.existsSync(outer);
+      console.log(retained ? '   ℹ️ 旧 skywalk-sdd/ 的配置、历史数据和未知文件已保留；仅清理工具脚本' : '   ✓ 已清理根目录旧工具脚本');
+      return { ok: true, removed: !retained, retained, mode: 'directory' };
     }
-    fs.unlinkSync(outer);
-    console.log('   ✓ 已移除 Git/工作区根多余的 skywalk-sdd');
-    return { ok: true, removed: true, mode: 'file' };
+    return { ok: true, removed: false, skipped: true }; // 同名用户文件不处理
   } catch (err) {
     console.log(`   ⚠️  未能移除根目录 skywalk-sdd/: ${err.message}`);
     return { ok: false, message: err.message };
@@ -1505,6 +1517,9 @@ function syncWorkspaceRepos(workspaceRoot = process.cwd(), options = {}) {
     console.log(`🆕 待接入新仓: ${filteredTargets.map((c) => c.name).join(', ') || '(无)'}`);
   }
 
+  const conflicts = maintenance.maintenanceConflicts(root, specRootAbs, codeRepos);
+  if (conflicts.length) return { ok: false, attached: [], failed: conflicts, layout, specRoot: specRootAbs, message: conflicts.map(c => c.repo + ': ' + c.message).join('; ') };
+
   const attached = [];
   const failed = [];
   for (const repo of filteredTargets) {
@@ -1513,7 +1528,9 @@ function syncWorkspaceRepos(workspaceRoot = process.cwd(), options = {}) {
     else failed.push(result);
   }
 
-  // 刷新清单（spec 指向用户确认的那个；代码仓排除 spec 包自身）
+  if (failed.length) return { ok: false, attached, failed, layout, specRoot: specRootAbs };
+
+  // 显式 sync-repos 成功后才刷新清单
   const layoutForFile = {
     ...layout,
     specRepo: { name: specName, abs: specRootAbs },
@@ -1614,6 +1631,12 @@ async function main(options = {}) {
     }
   }
 
+  if (specPackage) {
+    if (layout.isWorkspace) layout.codeRepos = maintenance.workspaceCodeRepos(workspaceRoot, specPackage.abs, layout, { respectManifest: true });
+    const conflicts = maintenance.maintenanceConflicts(workspaceRoot, specPackage.abs, layout.isWorkspace ? layout.codeRepos : []);
+    if (conflicts.length) throw new Error('未更新工具：' + conflicts.map(c => c.repo + ': ' + c.message).join('; '));
+  }
+
   if (layout.isWorkspace) {
     // 显示层同步过滤：用户交互选择的 spec 目录可能原被分类为代码仓
     const displayCodeRepos = specPackage
@@ -1650,18 +1673,18 @@ async function main(options = {}) {
         if (!layout.specRepo || path.resolve(layout.specRepo.abs) !== path.resolve(specPackage.abs)) {
           layout.specRepo = { name: specPackage.name, abs: specPackage.abs };
         }
-        layout.codeRepos = layout.codeRepos.filter(
-          (c) => path.resolve(c.abs) !== path.resolve(specPackage.abs),
-        );
+        layout.codeRepos = maintenance.workspaceCodeRepos(workspaceRoot, specPackage.abs, layout, { respectManifest: true });
       }
 
       console.log();
       console.log('🔗 正在为子代码仓做轻量接入（不安装 skills）...');
       for (const repo of layout.codeRepos) {
-        attachCodeRepoLite(repo.abs, specPackage.abs);
+        const result = attachCodeRepoLite(repo.abs, specPackage.abs);
+        if (!result.ok) throw new Error(`${repo.name}: ${result.message}`);
       }
-      const wsFile = workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
-      console.log(`✅ 工作区清单: ${wsFile}`);
+      const savedWorkspace = workspaceLayout.loadWorkspaceFile(workspaceRoot);
+      const wsFile = savedWorkspace.ok ? savedWorkspace.path : workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
+      console.log(`✅ 工作区清单${savedWorkspace.ok ? '已保留（新增仓用 sync-repos 接入）' : ''}: ${wsFile}`);
     } else {
       // 单仓：Git 根只放代码 + skills + Hook；SDD 内容进统一包裹子目录
       const isGit = workspaceLayout.isGitRepo(workspaceRoot);
@@ -1684,7 +1707,7 @@ async function main(options = {}) {
         if (linked.ok) {
           console.log(`   ✓ sdd.specPath = ${linked.path}`);
         } else {
-          console.log(`   ⚠️  未能写入 sdd.specPath: ${linked.message}`);
+          throw new Error(`未能写入 sdd.specPath: ${linked.message}`);
         }
       } else {
         // 非 Git 目录：仍创建包裹包，便于随后 git init
@@ -1713,7 +1736,7 @@ async function main(options = {}) {
   // 7. 更新工作目录 .gitignore
   updateGitignore(workspaceRoot);
 
-  // 8. 收尾：无论前面是否走过 symlink/旧副本路径，强制清掉工作区/Git 根多余 skywalk-sdd/
+  // 8. 收尾：清理可识别的旧工具，保留历史配置和数据
   if (specPackage && fs.existsSync(specPackage.abs)) {
     writeSddSpecRootHint(workspaceRoot, specPackage.abs);
   }

package/lib/maintenance.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// 安装、升级、卸载共用的边界；业务文档和关联配置不属于可清理的工具文件。
+const fs = require('fs');
+const path = require('path');
+const sdd = require('../skywalk-sdd/ontology/sdd-config.cjs');
+const layout = require('./workspace-layout');
+const detect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+const pkg = path.resolve(__dirname, '..');
+
+function filesUnder(root, prefix = '') {
+  if (!fs.existsSync(root) || !fs.lstatSync(root).isDirectory()) return [];
+  return fs.readdirSync(root).flatMap(name => {
+    const file = path.join(root, name);
+    const rel = path.join(prefix, name);
+    const stat = fs.lstatSync(file);
+    return stat.isDirectory() ? filesUnder(file, rel) : stat.isFile() ? [rel] : [];
+  });
+}
+
+function regularFileWithin(root, relative) {
+  const parts = relative.split(path.sep);
+  if (path.isAbsolute(relative) || parts.includes('..')) return false;
+  let target = root;
+  if (!fs.existsSync(root) || !fs.lstatSync(root).isDirectory()) return false;
+  for (let i = 0; i < parts.length; i++) {
+    target = path.join(target, parts[i]);
+    const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (!stat || stat.isSymbolicLink() || (i < parts.length - 1 && !stat.isDirectory())) return false;
+    if (i === parts.length - 1) return stat.isFile();
+  }
+  return false;
+}
+
+function runtimeToolFiles(root) {
+  const names = filesUnder(path.join(pkg, 'skywalk-sdd'))
+    .filter(rel => /\.(cjs|js|json)$/.test(rel) && !/^(events|state)[/\\]/.test(rel) && path.basename(rel) !== 'project-identity.json')
+    .map(rel => rel === 'index.cjs' ? 'log.cjs' : rel);
+  names.push(path.join('lib', 'scale-thresholds.json'));
+  for (const name of filesUnder(path.join(pkg, 'templates/git-hooks'))) {
+    if (name.endsWith('.cjs')) names.push(path.join('git-hooks', name));
+  }
+  return [...new Set(names)].filter(rel => regularFileWithin(root, rel)).map(rel => path.join(root, rel));
+}
+
+function samePath(a, b) {
+  const canonical = value => fs.existsSync(value) ? fs.realpathSync(value) : path.resolve(value);
+  return canonical(a) === canonical(b);
+}
+
+// 返回冲突原因，不自动迁移已有关系；明确换仓应通过 link-spec / 配置处理。
+function associationConflict(repo, spec) {
+  const bindings = [sdd.gitConfig(repo, 'sdd.specPath')];
+  const hint = path.join(repo, '.sdd-spec-root');
+  if (fs.existsSync(hint)) bindings.push(fs.readFileSync(hint, 'utf8').trim());
+  if (bindings.some(value => value && !samePath(path.resolve(repo, value), spec))) {
+    return '已有本地 Spec 关联指向其他目录，请先核对关联';
+  }
+  const yaml = sdd.loadSddYaml(repo);
+  if (fs.existsSync(yaml.path) && !yaml.ok) return '已有 .sdd.yaml 无法解析，请先修复配置';
+  if (yaml.ok && yaml.layout === 'mono') {
+    if (yaml.spec_path ? !samePath(path.resolve(repo, yaml.spec_path), spec) : !bindings.some(value => value && samePath(path.resolve(repo, value), spec))) return '此仓使用独立的单仓 Spec 配置';
+  }
+  if (yaml.ok && yaml.spec_repository && !yaml.spec_repository.includes('gitlab.example.com:biz/xxx-sdd-specs.git')) {
+    const remote = sdd.gitRemoteUrl(spec);
+    if (!remote || !sdd.remotesMatch(yaml.spec_repository, remote)) return '.sdd.yaml 的 Spec 远程仓库与所选目录不一致';
+  }
+  return null;
+}
+
+function workspaceCodeRepos(root, spec, current = layout.detectWorkspaceLayout(root), options = {}) {
+  const excluded = new Set(detect.detectSpecCandidatesWithGit(root).map(c => path.resolve(c.abs)));
+  excluded.add(path.resolve(spec));
+  const candidates = current.codeRepos.filter(repo => !excluded.has(path.resolve(repo.abs)));
+  const saved = options.respectManifest && layout.loadWorkspaceFile(root);
+  if (!saved || !saved.ok) return candidates;
+  const declared = saved.data.code_repos.map(value => path.resolve(root, value.replace(/^(["'])(.*)\1$/, '$2')));
+  const missing = declared.filter(dir => !candidates.some(repo => samePath(repo.abs, dir)));
+  if (missing.length) throw new Error('多仓清单包含未发现或非代码仓目录，请先核对 .sdd-workspace.yaml：' + missing.map(p => path.basename(p)).join('、'));
+  return candidates.filter(repo => declared.some(dir => samePath(dir, repo.abs)));
+}
+
+function maintenanceConflicts(root, spec, repos) {
+  const failures = [];
+  const saved = layout.loadWorkspaceFile(root);
+  if (saved.ok && saved.data.spec_path && !samePath(path.resolve(root, saved.data.spec_path), spec)) {
+    failures.push({ repo: path.basename(root), message: '.sdd-workspace.yaml 指向其他 Spec，升级不会重新绑定' });
+  }
+  for (const repo of [{ abs: root, name: path.basename(root) }, ...repos]) {
+    const message = associationConflict(repo.abs, spec);
+    if (message) failures.push({ repo: repo.name, message });
+  }
+  return failures;
+}
+
+module.exports = { filesUnder, regularFileWithin, runtimeToolFiles, samePath, associationConflict, workspaceCodeRepos, maintenanceConflicts };

package/lib/uninstall.js

@@ -1,27 +1,4 @@
-/**
- * KLD SDD 卸载
- *
- * 与 init 共用同一套「产物归属」判定，方向相反：
- * - 工具产物（安装时 OVERWRITE）→ 删除
- * - 用户配置（安装时 SKIP_IF_EXISTS）→ 默认保留，仅 --purge 才删
- * - MERGE 类（settings.json）→ 只摘除 SDD 受管 hook，文件其余内容原样保留
- * - MARKER 类（.git/hooks）→ 只删含受管标记的，非受管 hook 保留
- * - APPEND_LINES（.gitignore）→ 只摘除 SDD 块，其余行保留
- * - 运行时数据（events/state）→ 默认保留（含用户历史度量），仅 --purge 才删
- * - 团队/项目配置（project-identity.json、git-hooks/hooks.config）→ 默认保留。
- *   二者都不是「工具可重置」的产物：前者是团队共享的 KB 身份（需提交 Git），
- *   后者是项目级门禁参数（init 用 SKIP_IF_EXISTS 保护），重跑 init 不得重置。
- *
- * 两种模式：
- * - MODE.TOOLS_ONLY（默认）：只删工具产物，保留全部用户配置与数据
- * - MODE.FULL（--purge）：连用户配置与运行时数据一并删除
- *
- * 安全约束：
- * - 任何删除前先经 scope 白名单校验（只允许操作 SDD 自有目录 / 受管标记文件）
- * - --dry-run 只打印计划，不落盘
- * - 删除文件后清理变空的目录，但不删除用户可能仍有内容的目录
- */
-
+/** 只卸载可识别的 SDD 工具；文档、配置、数据和仓库关联始终保留。 */
 'use strict';
 
 const fs = require('fs');
@@ -29,7 +6,10 @@ const path = require('path');
 
 const { isManagedBridgeFile } = require('./command-bridge');
 const { PROVIDERS, stripManagedHooks } = require('./settings-merge');
-const { DEFAULT_HOOK_MARKER } = require('./deploy-strategy');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const maintenance = require('./maintenance');
+const packageRoot = path.resolve(__dirname, '..');
 const { getToolProfile, listToolProfileIds, buildToolConfigs } = require('./tool-profiles');
 const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
 const workspaceLayout = require('./workspace-layout');
@@ -40,17 +20,12 @@ const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
 const MODE = Object.freeze({
   /** 只删工具内容，保留用户配置与运行时数据 */
   TOOLS_ONLY: 'tools-only',
-  /** 全量删除，含用户配置与运行时数据 */
-  FULL: 'full',
 });
 
 /** 操作类型（用于计划与摘要） */
 const OP = Object.freeze({
   DELETE_FILE: 'delete-file',
-  DELETE_DIR: 'delete-dir',
   STRIP_HOOKS: 'strip-hooks',
-  STRIP_GITIGNORE: 'strip-gitignore',
-  UNLINK_GIT_CONFIG: 'unlink-git-config',
   KEEP: 'keep',
 });
 
@@ -90,263 +65,78 @@ function listFilesRecursive(dir) {
   return out;
 }
 
-/**
- * 规划：编辑器专属产物（skills / commands / hooks / rules）
- *
- * 策略：
- * - `skillsDir/opsx-*` 与 `openspec-sync-specs` 等 SDD skill 目录 → 整体删（工具产物）
- * - `opsxCommandsDir/*.md` → 只删含 BRIDGE_MARKER 的
- * - `configDir/hooks/sdd-*.cjs` + `hook-gate-core.cjs` → 删（工具产物）
- * - `configDir/settings.json` → 摘除受管 hook（保留文件）
- */
+/** 按随包工具文件清单逐文件清理，未知文件和用户添加的文件不删。 */
+function planOwnedFiles(plan, source, target, reason) {
+  for (const rel of maintenance.filesUnder(source)) {
+    // Skill 的本地检索配置可能包含连接信息，不作为工具脚本清理。
+    if (path.basename(rel) === 'config.json') continue;
+    if (maintenance.regularFileWithin(target, rel)) addOp(plan, OP.DELETE_FILE, path.join(target, rel), reason);
+  }
+}
+
 function planProfileArtifacts(plan, toolKey, cwd) {
   const profile = getToolProfile(toolKey);
   const config = buildToolConfigs()[toolKey];
   if (!config) return;
-
-  // 1) skills：SDD 部署的 skill 目录（opsx-* + openspec-sync-specs/update-change + tdd-*）
   if (profile.skillsDir) {
-    const skillsDir = path.join(cwd, profile.skillsDir);
-    if (fs.existsSync(skillsDir)) {
-      for (const name of fs.readdirSync(skillsDir)) {
-        const target = path.join(skillsDir, name);
-        if (!fs.statSync(target).isDirectory()) continue;
-        if (!/^(opsx-|openspec-(sync-specs|update-change)$)|^tdd-/.test(name)) continue;
-        addOp(plan, OP.DELETE_DIR, target, `${config.name} SDD skill 目录`);
-      }
-    }
+    planOwnedFiles(plan, path.join(packageRoot, 'templates/skills/kld-sdd'), path.join(cwd, profile.skillsDir), `${config.name} SDD skill 文件`);
   }
-
-  // 2) Kunlun command bridge：只删含受管标记的
   if (profile.requiresCommandBridge && profile.opsxCommandsDir) {
-    const opsxDir = path.join(cwd, profile.opsxCommandsDir);
-    for (const file of listFilesRecursive(opsxDir)) {
-      if (!file.endsWith('.md')) continue;
-      const content = fs.readFileSync(file, 'utf8');
-      if (isManagedBridgeFile(content)) {
-        addOp(plan, OP.DELETE_FILE, file, 'SDD command bridge（受管标记）');
-      } else {
-        addOp(plan, OP.KEEP, file, '非 SDD 受管命令，保留');
-      }
+    const root = path.join(cwd, profile.opsxCommandsDir);
+    for (const rel of maintenance.filesUnder(root)) {
+      if (!rel.endsWith('.md') || !maintenance.regularFileWithin(cwd, path.relative(cwd, path.join(root, rel)))) continue;
+      const file = path.join(root, rel);
+      if (isManagedBridgeFile(fs.readFileSync(file, 'utf8'))) addOp(plan, OP.DELETE_FILE, file, 'SDD command bridge');
     }
   }
-
-  // 3) Hook 脚本目录（claude / codebuddy）
   if (profile.hookProvider && profile.hookProvider !== 'none') {
-    const hooksDir = path.join(cwd, profile.configDir, 'hooks');
-    for (const file of listFilesRecursive(hooksDir)) {
-      const base = path.basename(file);
-      if (/^sdd-[\w-]+\.cjs$/.test(base) || base === 'hook-gate-core.cjs') {
-        addOp(plan, OP.DELETE_FILE, file, `${config.name} SDD hook 脚本`);
-      }
-    }
-
-    // 4) settings.json：摘除受管 hook
-    const settingsPath = path.join(cwd, profile.configDir, 'settings.json');
-    if (fs.existsSync(settingsPath)) {
-      addOp(plan, OP.STRIP_HOOKS, settingsPath, `${config.name} settings.json 摘除 SDD 受管 hook`);
-    }
-  }
-
-  // 5) rules 目录（cursor .cursor/rules 等）中的 SDD 规则
-  if (profile.rulesDir) {
-    const rulesDir = path.join(cwd, profile.rulesDir);
-    for (const file of listFilesRecursive(rulesDir)) {
-      const base = path.basename(file);
-      if (/^(sdd|opsx)[\w.-]*\.(md|mdc)$/i.test(base)) {
-        addOp(plan, OP.DELETE_FILE, file, `${config.name} SDD rules`);
-      }
-    }
-  }
-}
-
-/**
- * 规划：spec 仓 `skywalk-sdd/git-hooks/` 目录（混合归属）
- *
- * init 侧 `ensureSpecGitHooks` 对同一目录用了两套策略：
- * - `*.cjs`      工具产物 → OVERWRITE
- * - `hooks.config` 用户配置 → SKIP_IF_EXISTS
- *
- * 卸载侧必须按同一判据逐项处理，否则「装进去的删不掉」或
- * 「用户配置被静默重置」二者必居其一。
- */
-function planSpecGitHooks(plan, hooksDir) {
-  for (const name of fs.readdirSync(hooksDir)) {
-    const target = path.join(hooksDir, name);
-    let st;
-    try {
-      st = fs.statSync(target);
-    } catch {
-      continue;
-    }
-    if (st.isDirectory()) {
-      addOp(plan, OP.DELETE_DIR, target, 'SDD 运行时（工具内容）');
-      continue;
-    }
-    if (name === 'hooks.config') {
-      addOp(plan, OP.KEEP, target, '项目级门禁配置（init 用 SKIP_IF_EXISTS 保护），保留');
-      continue;
-    }
-    addOp(plan, OP.DELETE_FILE, target, 'SDD Git hook 脚本（工具产物）');
+    planOwnedFiles(plan, path.join(packageRoot, 'templates/hooks', profile.hookProvider, 'hooks'), path.join(cwd, profile.configDir, 'hooks'), `${config.name} SDD hook`);
+    const relative = path.join(profile.configDir, 'settings.json');
+    if (maintenance.regularFileWithin(cwd, relative)) addOp(plan, OP.STRIP_HOOKS, path.join(cwd, relative), '仅摘除 SDD 受管 hook');
   }
+  // rules 由用户或 Agent 编写，不因名称带 sdd/opsx 就删除。
 }
 
-/**
- * 规划：spec 仓内容
- *
- * 工具产物：skywalk-sdd/（除下方保留项）、openspec-templates/、操作手册
- * 用户配置：modules.yaml、sdd.config.yaml、kb-state.json（仅 FULL 删）
- * 团队/项目配置：project-identity.json、git-hooks/hooks.config（两种模式都保留）
- * 文档工作区：openspec/（仅 FULL 整目录删）
- *
- * 注意：spec 仓自身的 `.git/hooks`（init 用 deployQualityGateTemplates 装的
- * commit-msg / pre-commit / pre-push）由 buildUninstallPlan 调用 planCodeRepo
- * 统一处理，保证「装得进去的一定摘得掉」，且与代码仓用同一套受管标记判据。
- */
-function planSpecPackage(plan, specRoot, options) {
+function planSpecPackage(plan, specRoot) {
   if (!specRoot || !fs.existsSync(specRoot)) return;
-
-  const skywalkDir = path.join(specRoot, 'skywalk-sdd');
-  if (fs.existsSync(skywalkDir)) {
-    if (options.mode === MODE.FULL) {
-      // 透明性：project-identity.json 是团队共享的 KB 身份（已提交 spec 仓 Git），
-      // 全量卸载会一并清除，需重跑 /opsx-kb-config 并重新提交。先单独列出，
-      // 让用户在预览里明确看到「团队配置将被清除」——比静默随目录消失可审计。
-      // 顺序必须在 DELETE_DIR 之前，否则父目录先被删、该项会被跳过。
-      const identity = path.join(skywalkDir, 'project-identity.json');
-      if (fs.existsSync(identity)) {
-        addOp(plan, OP.DELETE_FILE, identity, 'KB 项目身份（团队共享，需重跑 /opsx-kb-config 并重新提交）');
-      }
-      addOp(plan, OP.DELETE_DIR, skywalkDir, 'SDD 运行时（含 events/state 数据）');
-    } else {
-      // 工具内容删除：删工具脚本，保留运行时数据与用户/团队配置。
-      //
-      // 保留项判据是「重跑 init 能不能恢复」：
-      // - events/、state/        运行时数据（用户历史度量），init 不重建内容
-      // - project-identity.json  团队共享的 KB 身份，由 /opsx-kb-config 写、
-      //                          需提交 spec 仓 Git，删掉等于毁掉团队配置
-      // - git-hooks/hooks.config 项目级门禁参数（business_code_exts/strict/
-      //                          warn_only），init 用 SKIP_IF_EXISTS 保护，
-      //                          随目录一起删会让重跑 init 静默重置用户设置
-      const keepItems = new Map([
-        ['events', '运行时数据（度量），保留'],
-        ['state', '运行时数据（状态），保留'],
-        ['project-identity.json', 'KB 项目身份（团队共享，保留）'],
-      ]);
-      for (const name of fs.readdirSync(skywalkDir)) {
-        const target = path.join(skywalkDir, name);
-        if (keepItems.has(name)) {
-          addOp(plan, OP.KEEP, target, keepItems.get(name));
-          continue;
-        }
-        // git-hooks/ 是混合目录：*.cjs 是工具产物（OVERWRITE），
-        // hooks.config 是用户配置（SKIP_IF_EXISTS）→ 逐项判定，不整目录删。
-        if (name === 'git-hooks' && fs.statSync(target).isDirectory()) {
-          planSpecGitHooks(plan, target);
-          continue;
-        }
-        const st = fs.statSync(target);
-        addOp(plan, st.isDirectory() ? OP.DELETE_DIR : OP.DELETE_FILE, target, 'SDD 运行时（工具内容）');
-      }
-    }
-  }
-
-  const templatesDir = path.join(specRoot, 'openspec-templates');
-  if (fs.existsSync(templatesDir)) {
-    addOp(plan, OP.DELETE_DIR, templatesDir, '只读文档模板');
-  }
-
-  const manual = path.join(specRoot, 'openspec', 'kld-sdd操作手册.html');
-  if (fs.existsSync(manual)) {
-    addOp(plan, OP.DELETE_FILE, manual, 'SDD 操作手册');
+  for (const file of maintenance.runtimeToolFiles(path.join(specRoot, 'skywalk-sdd'))) {
+    addOp(plan, OP.DELETE_FILE, file, 'SDD 运行工具');
   }
-
-  // 用户产物
-  for (const name of ['modules.yaml', 'sdd.config.yaml']) {
+  planOwnedFiles(plan, path.join(packageRoot, 'templates/openspec'), path.join(specRoot, 'openspec-templates'), 'SDD 只读模板');
+  for (const name of ['openspec', 'modules.yaml', 'sdd.config.yaml', 'kb-state.json', 'skywalk-sdd/events', 'skywalk-sdd/state', 'skywalk-sdd/project-identity.json', 'skywalk-sdd/git-hooks/hooks.config']) {
     const target = path.join(specRoot, name);
-    if (!fs.existsSync(target)) continue;
-    if (options.mode === MODE.FULL) {
-      addOp(plan, OP.DELETE_FILE, target, 'SDD 用户配置');
-    } else {
-      addOp(plan, OP.KEEP, target, '用户配置，保留');
-    }
-  }
-
-  // KB 绑定状态（含 API Key 与 spaceId/kbId，由 opsx-kb-config 写入 spec 仓根）。
-  // 与 skywalk-sdd/project-identity.json 同属 KB 配置，全量模式下须一并清除，
-  // 否则会留下「身份文件已删、绑定状态还在」的不一致中间态。
-  const kbState = path.join(specRoot, 'kb-state.json');
-  if (fs.existsSync(kbState)) {
-    if (options.mode === MODE.FULL) {
-      addOp(plan, OP.DELETE_FILE, kbState, 'KB 绑定状态（含 API Key）');
-    } else {
-      addOp(plan, OP.KEEP, kbState, 'KB 绑定状态（含 API Key），保留');
-    }
-  }
-
-  // openspec/ 是 SDD 的文档工作区（changes/ 变更提案、specs/ 规格与全局契约 overview.md、
-  // config.yaml），全部由 SDD 工具链创建与消费。
-  // 工具内容模式：不纳入计划（用户配置与文档内容一律保留）。
-  // 全量模式：整目录删除 —— 全量的语义就是「清空 SDD 在该仓的全部痕迹」，
-  //           不对单个文件做内容判定，避免残留半套目录结构。
-  if (options.mode === MODE.FULL) {
-    const openspecDir = path.join(specRoot, 'openspec');
-    if (fs.existsSync(openspecDir)) {
-      addOp(plan, OP.DELETE_DIR, openspecDir, 'SDD 文档工作区（changes/specs/config.yaml）');
-      warn(plan, `即将删除 SDD 文档工作区（含 changes/ 与 specs/ 内的业务文档）: ${openspecDir}`);
-    }
+    if (fs.existsSync(target)) addOp(plan, OP.KEEP, target, '项目文档、配置或历史数据');
   }
+  // 即使没有文档，也不删除 Spec 仓根目录及 .git。
+  addOp(plan, OP.KEEP, specRoot, 'Spec 仓库目录');
 }
 
-/**
- * 规划：代码仓 / 工作区根产物
- *
- * - `.sdd.yaml`、`.sdd-spec-root`、`.sdd-workspace.yaml` → 用户配置，仅 FULL 删
- * - `.git/hooks/{commit-msg,pre-commit,pre-push}` → 只删含受管标记的
- * - `.gitignore` → 摘除 SDD 块
- * - `git config --local sdd.specPath` → 删除
- */
-function planCodeRepo(plan, repoRoot, options) {
+function planCodeRepo(plan, repoRoot) {
   if (!repoRoot || !fs.existsSync(repoRoot)) return;
-
-  for (const name of ['.sdd.yaml', '.sdd-spec-root', '.sdd-workspace.yaml']) {
+  for (const name of ['.sdd.yaml', '.sdd-spec-root', '.sdd-workspace.yaml', '.gitignore']) {
     const target = path.join(repoRoot, name);
-    if (!fs.existsSync(target)) continue;
-    if (options.mode === MODE.FULL) {
-      addOp(plan, OP.DELETE_FILE, target, 'SDD 用户配置');
-    } else {
-      addOp(plan, OP.KEEP, target, '用户配置，保留');
-    }
+    if (fs.existsSync(target)) addOp(plan, OP.KEEP, target, '保留关联配置与隐私数据忽略规则');
   }
-
-  // Git hooks：只删含受管标记的
-  const hooksDir = path.join(repoRoot, '.git', 'hooks');
+  // 与安装器一样尊重 Hook 管理器、worktree 和自定义 Hook。
+  if (!workspaceLayout.isGitRepo(repoRoot) || sddConfig.gitConfig(repoRoot, 'core.hooksPath')) return;
+  const known = require('./managed-hook-hashes.json');
   for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
-    const target = path.join(hooksDir, name);
-    if (!fs.existsSync(target)) continue;
-    let content = '';
+    let target;
     try {
-      content = fs.readFileSync(target, 'utf8');
-    } catch {
+      const value = execFileSync('git', ['rev-parse', '--git-path', `hooks/${name}`], { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+      target = path.resolve(repoRoot, value);
+    } catch { continue; }
+    if (!target.startsWith(path.resolve(repoRoot) + path.sep)) {
+      addOp(plan, OP.KEEP, target, '其他 worktree 共用的 Git Hook；请从主仓库管理');
       continue;
     }
-    if (content.includes(DEFAULT_HOOK_MARKER)) {
-      addOp(plan, OP.DELETE_FILE, target, 'SDD shell hook（受管标记）');
-    } else {
-      addOp(plan, OP.KEEP, target, '非 SDD 受管 hook，保留');
-    }
-  }
-
-  const gitignore = path.join(repoRoot, '.gitignore');
-  if (fs.existsSync(gitignore) && fs.readFileSync(gitignore, 'utf8').includes(GITIGNORE_MARKER)) {
-    addOp(plan, OP.STRIP_GITIGNORE, gitignore, '摘除 SDD 忽略块');
-  }
-
-  if (workspaceLayout.isGitRepo(repoRoot)) {
-    const specPath = sddConfig.gitConfig(repoRoot, 'sdd.specPath');
-    if (specPath) {
-      addOp(plan, OP.UNLINK_GIT_CONFIG, repoRoot, `git config --local sdd.specPath = ${specPath}`);
-    }
+    const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile() || !fs.lstatSync(path.dirname(target)).isDirectory()) continue;
+    const hash = content => crypto.createHash('sha256').update(content).digest('hex');
+    const current = hash(fs.readFileSync(target));
+    const template = hash(fs.readFileSync(path.join(packageRoot, 'templates/git-hooks', name)));
+    if (current === template || (known[name] || []).includes(current)) addOp(plan, OP.DELETE_FILE, target, '完整匹配已发布的 SDD Hook');
+    else addOp(plan, OP.KEEP, target, '自定义或未知 Hook，请自行审阅其中的 SDD 调用');
   }
 }
 
@@ -356,19 +146,21 @@ function planCodeRepo(plan, repoRoot, options) {
  * @param {object} options
  * @param {string} options.cwd 工作目录（代码仓 / 工作区根）
  * @param {string[]} [options.tools] 要卸载的编辑器，缺省=全部
- * @param {string} [options.mode] MODE.TOOLS_ONLY（默认）| MODE.FULL
+ * @param {string} [options.mode] MODE.TOOLS_ONLY（唯一支持的方式）
  * @param {string} [options.specRoot] 已确认的 spec 包裹包目录（CLI 交互层选定后传入）；
  *   缺省时仅按权威来源（.sdd-spec-root → git config）保守定位
  * @returns {{ok: boolean, plan: object, specRoot: string|null, message?: string}}
  */
 function buildUninstallPlan(options = {}) {
   const cwd = path.resolve(options.cwd || process.cwd());
-  const mode = options.mode === MODE.FULL ? MODE.FULL : MODE.TOOLS_ONLY;
+  if (options.mode && options.mode !== MODE.TOOLS_ONLY) throw new Error('仅支持工具卸载；不允许删除 Spec 文档、配置和历史数据');
+  const mode = MODE.TOOLS_ONLY;
   const tools = Array.isArray(options.tools) && options.tools.length
     ? options.tools
     : listToolProfileIds();
 
   const plan = createPlan(cwd);
+  plan.tools = tools;
 
   // 编辑器专属产物：工作区根 / 当前目录
   for (const toolKey of tools) {
@@ -384,11 +176,18 @@ function buildUninstallPlan(options = {}) {
     : resolveSpecRootForUninstall(cwd);
   if (specRoot) {
     plan.specRoot = path.resolve(specRoot);
-    planSpecPackage(plan, specRoot, { mode });
+    const relative = path.relative(cwd, specRoot);
+    const sharedExternal = relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative);
+    if (sharedExternal) {
+      addOp(plan, OP.KEEP, specRoot, '工作目录外的共享 Spec，仅卸载当前代码仓工具');
+      warn(plan, '共享 Spec 位于当前目录之外，运行工具与文档均保留；如需卸载共享工具，请从所属工作区操作');
+    } else {
+      planSpecPackage(plan, specRoot);
+      planCodeRepo(plan, specRoot);
+    }
     // spec 仓自身的 .git/hooks（init 装的 commit-msg / pre-commit / pre-push）
     // 是工具产物，须摘除 —— 与代码仓共用同一套受管标记判据，
     // 非受管 hook 与 .git 其余内容一律保留。
-    planCodeRepo(plan, specRoot, { mode });
   } else {
     warn(plan, '未定位到 spec 包裹包：spec 侧产物（skywalk-sdd/、openspec/ 等）未纳入计划');
   }
@@ -409,10 +208,30 @@ function buildUninstallPlan(options = {}) {
     if (specRoot) specDirs.add(path.resolve(specRoot));
     for (const repo of layout.codeRepos) {
       if (specDirs.has(path.resolve(repo.abs))) continue;
-      planCodeRepo(plan, repo.abs, { mode });
+      if (!specRoot || maintenance.associationConflict(repo.abs, specRoot)) {
+        warn(plan, `保留代码仓 ${repo.name}：未确认属于所选 Spec`);
+        continue;
+      }
+      const linked = sddConfig.gitConfig(repo.abs, 'sdd.specPath');
+      const yaml = sddConfig.loadSddYaml(repo.abs);
+      if (!linked && !yaml.ok) continue;
+      planCodeRepo(plan, repo.abs);
     }
   }
 
+  // 不沿中间符号链接删除文件；同一个文件仅处理一次。
+  const seen = new Set();
+  plan.ops = plan.ops.filter(item => {
+    const key = item.op + ':' + item.target;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    if (item.op === OP.KEEP) return true;
+    const root = specRoot && item.target.startsWith(path.resolve(specRoot) + path.sep) ? path.resolve(specRoot) : cwd;
+    // Git worktree 的 hooks 位于 common git dir，已单独校验完整内容。
+    if (item.reason !== '完整匹配已发布的 SDD Hook' && !maintenance.regularFileWithin(root, path.relative(root, item.target))) return false;
+    item.digest = crypto.createHash('sha256').update(fs.readFileSync(item.target)).digest('hex');
+    return true;
+  });
   return { ok: true, plan, specRoot: specRoot || null, mode };
 }
 
@@ -527,187 +346,56 @@ function providerFromSettingsPath(settingsPath) {
   return /\.claude[\\/]/.test(settingsPath) ? PROVIDERS.CLAUDE : PROVIDERS.CODEBUDDY;
 }
 
-/**
- * 执行卸载计划
- *
- * @param {object} plan buildUninstallPlan 产出的 plan
- * @param {object} [options]
- * @param {boolean} [options.dryRun] 只打印，不落盘
- * @param {function} [options.log] 日志输出函数
- * @returns {{ok: boolean, applied: number, skipped: number, errors: string[]}}
- */
+/** 执行前重新校验白名单和文件快照，拒绝旧全量计划以及预览后的变更。 */
 function applyUninstallPlan(plan, options = {}) {
-  const dryRun = Boolean(options.dryRun);
   const log = typeof options.log === 'function' ? options.log : console.log;
   const errors = [];
+  if (!plan || !plan.root || !Array.isArray(plan.ops)) return { ok: false, applied: 0, skipped: 0, errors: ['卸载计划无效，请重新预览'] };
+  const fresh = buildUninstallPlan({ cwd: plan.root, specRoot: plan.specRoot, tools: plan.tools }).plan;
+  const allowed = new Map(fresh.ops.filter(item => item.op !== OP.KEEP).map(item => [item.op + ':' + item.target, item]));
+  for (const item of plan.ops) {
+    if (item.op === OP.KEEP) continue;
+    const current = allowed.get(item.op + ':' + item.target);
+    if (!current || !item.digest || current.digest !== item.digest) errors.push(`${item.target}: 范围或内容已变化，请重新预览`);
+  }
+  if (errors.length) return { ok: false, applied: 0, skipped: 0, errors };
   let applied = 0;
   let skipped = 0;
-
   for (const item of plan.ops) {
-    if (item.op === OP.KEEP) {
-      skipped += 1;
-      log(`   · 保留 ${path.basename(item.target)}（${item.reason}）`);
-      continue;
-    }
-
+    if (item.op === OP.KEEP) { skipped++; continue; }
     try {
-      switch (item.op) {
-        case OP.DELETE_FILE:
-          if (fs.existsSync(item.target)) {
-            if (!dryRun) fs.unlinkSync(item.target);
-            applied += 1;
-            log(`   ${dryRun ? '将删除' : '✓ 已删除'} 文件 ${item.target}`);
-          }
-          break;
-
-        case OP.DELETE_DIR:
-          if (fs.existsSync(item.target)) {
-            const count = listFilesRecursive(item.target).length;
-            if (!dryRun) fs.rmSync(item.target, { recursive: true, force: true });
-            applied += 1;
-            log(`   ${dryRun ? '将删除' : '✓ 已删除'} 目录 ${item.target}（${count} 文件）`);
-          }
-          break;
-
-        case OP.STRIP_HOOKS: {
-          if (!fs.existsSync(item.target)) break;
-          if (dryRun) {
-            applied += 1;
-            log(`   将摘除 ${item.target} 中的 SDD 受管 hook（保留其余配置）`);
-            break;
-          }
-          const res = stripSettingsHooks(item.target, providerFromSettingsPath(item.target));
-          if (!res.ok) {
-            errors.push(`${item.target}: ${res.error}`);
-            log(`   ⚠️  ${item.target}: ${res.error}`);
-          } else if (res.changed) {
-            applied += 1;
-            log(`   ✓ 已摘除 ${item.target} 中的 SDD 受管 hook`);
-          } else {
-            // 无受管 hook 可摘 → 计为保留，保证重复卸载 applied 归零（幂等）
-            skipped += 1;
-            log(`   · 保留 ${item.target}（无 SDD 受管 hook）`);
-          }
-          break;
-        }
-
-        case OP.STRIP_GITIGNORE: {
-          if (!fs.existsSync(item.target)) break;
-          if (dryRun) {
-            applied += 1;
-            log(`   将摘除 ${item.target} 中的 SDD 忽略块（保留其余行）`);
-            break;
-          }
-          const res = stripGitignoreBlock(item.target);
-          if (res.changed) {
-            fs.writeFileSync(item.target, res.next, 'utf8');
-            applied += 1;
-            log(`   ✓ 已摘除 ${item.target} 中的 SDD 忽略块（${res.removed} 行）`);
-          } else {
-            skipped += 1;
-            log(`   · 保留 ${item.target}（无 SDD 块可摘）`);
-          }
-          break;
-        }
-
-        case OP.UNLINK_GIT_CONFIG: {
-          if (dryRun) {
-            applied += 1;
-            log('   将删除 git config --local sdd.specPath');
-            break;
-          }
-          const res = sddConfig.unsetSpecPath(item.target);
-          if (!res.ok) {
-            errors.push(`${item.target}: ${res.message || '删除 sdd.specPath 失败'}`);
-            log('   ⚠️  删除 git config --local sdd.specPath 失败');
-          } else if (res.removed) {
-            applied += 1;
-            log('   ✓ 已删除 git config --local sdd.specPath');
-          } else {
-            // 配置项本就不存在 → 保留，保证幂等
-            skipped += 1;
-            log('   · 保留 git config（sdd.specPath 本就不存在）');
-          }
-          break;
-        }
-
-        default:
-          break;
+      // 执行时再检查一次，不接受被替换为链接的文件。
+      const stat = fs.lstatSync(item.target);
+      if (!stat.isFile() || crypto.createHash('sha256').update(fs.readFileSync(item.target)).digest('hex') !== item.digest) throw new Error('文件已变化，请重新预览');
+      if (options.dryRun) { log(`   将处理 ${item.target}`); applied++; continue; }
+      if (item.op === OP.DELETE_FILE) { fs.unlinkSync(item.target); applied++; }
+      else if (item.op === OP.STRIP_HOOKS) {
+        const result = stripSettingsHooks(item.target, providerFromSettingsPath(item.target));
+        if (!result.ok) throw new Error(result.error);
+        if (result.changed) applied++; else skipped++;
       }
-    } catch (error) {
-      errors.push(`${item.target}: ${error.message}`);
-      log(`   ⚠️  ${item.target}: ${error.message}`);
-    }
+    } catch (error) { errors.push(`${item.target}: ${error.message}`); }
   }
-
-  // 清理变空的目录：仅清理由本计划删除行为导致的空壳目录。
-  //
-  // 两条安全边界（缺一不可）：
-  // 1) 绝不清理 plan.root（工作目录）及其祖先 —— 候选父目录是逐级向上收集的，
-  //    没有这道闸门时，一个空的工作目录会被 rmdir 掉，甚至连带其父目录。
-  // 2) KEEP 项（如 skywalk-sdd/events、state）即使变空也必须保留，
-  //    否则会把用户明确要保留的运行时数据目录一并抹掉。
-  if (!dryRun) {
-    const rootAbs = plan.root ? path.resolve(plan.root) : null;
-    const protectedDirs = new Set(
-      plan.ops.filter(i => i.op === OP.KEEP).map(i => path.resolve(i.target)),
-    );
-
-    const isProtected = (dir) => {
-      const abs = path.resolve(dir);
-      // 工作目录本身及其祖先目录不可清理
-      if (rootAbs && (abs === rootAbs || rootAbs.startsWith(abs + path.sep))) return true;
-      if (protectedDirs.has(abs)) return true;
-      // 祖先目录被保护时，其子目录同样不可清理
-      for (const keep of protectedDirs) {
-        if (keep.startsWith(abs + path.sep)) return true;
-      }
-      return false;
-    };
-
-    const candidates = new Set();
-    for (const item of plan.ops) {
-      if (item.op !== OP.DELETE_FILE && item.op !== OP.DELETE_DIR) continue;
+  // 只收起因工具文件删除而变空的目录；根目录、Spec、数据目录保持原样。
+  if (!options.dryRun) {
+    const roots = [plan.root, plan.specRoot].filter(Boolean).map(p => path.resolve(p));
+    const kept = plan.ops.filter(i => i.op === OP.KEEP).map(i => path.resolve(i.target));
+    for (const item of plan.ops.filter(i => i.op === OP.DELETE_FILE && !i.target.includes(`${path.sep}.git${path.sep}`))) {
       let dir = path.dirname(item.target);
-      // 逐级向上收集候选父目录（深度优先，先深后浅）
-      for (let i = 0; i < 4 && dir && dir !== path.dirname(dir); i += 1) {
-        candidates.add(dir);
-        dir = path.dirname(dir);
-      }
-    }
-
-    const ordered = [...candidates].sort((a, b) => b.length - a.length);
-    for (const dir of ordered) {
-      if (isProtected(dir)) continue;
-      if (!fs.existsSync(dir) || !isEmptyDir(dir)) continue;
-      try {
+      while (roots.some(root => dir.startsWith(root + path.sep)) && !roots.includes(dir)) {
+        if (kept.some(p => p === dir || p.startsWith(dir + path.sep))) break;
+        if (!isEmptyDir(dir)) break;
         fs.rmdirSync(dir);
-      } catch { /* 目录非空或权限不足，忽略 */ }
-    }
-
-    // spec 仓目录本身：产物清空后若已无任何文件（含 .git 内），一并删除。
-    // 判据是「递归无文件」而非「无子项」——.git/ 即使只剩空目录结构也算残留。
-    // 有文件则保留：目录名由用户 --spec-path 指定，工具不擅自删非空目录。
-    const specAbs = plan.specRoot ? path.resolve(plan.specRoot) : null;
-    if (specAbs && fs.existsSync(specAbs) && isProtected(specAbs) === false) {
-      if (listFilesRecursive(specAbs).length === 0) {
-        try {
-          fs.rmSync(specAbs, { recursive: true, force: true });
-          applied += 1;
-          log(`   ✓ 已删除 spec 仓目录 ${specAbs}（无残留文件）`);
-        } catch { /* 权限不足等，忽略 */ }
+        dir = path.dirname(dir);
       }
     }
   }
-
   return { ok: errors.length === 0, applied, skipped, errors };
 }
 
 /** 卸载方式的中文标签（供 CLI 层复用，避免文案漂移） */
-function modeLabel(mode) {
-  return mode === MODE.FULL
-    ? '全量卸载（含用户配置与运行时数据）'
-    : '工具内容卸载（保留用户配置）';
+function modeLabel() {
+  return '卸载工具（保留 Spec 文档、配置与历史数据）';
 }
 
 /**
@@ -719,7 +407,7 @@ function modeLabel(mode) {
  * @param {object} [opts]
  * @param {string} [opts.cwd]    工作目录（代码仓 / 工作区根），缺省 process.cwd()
  * @param {string[]} [opts.tools] 要卸载的编辑器 id 列表，缺省=全部
- * @param {string} [opts.mode]   MODE.TOOLS_ONLY（默认）| MODE.FULL
+ * @param {string} [opts.mode]   MODE.TOOLS_ONLY（唯一支持的方式）
  * @param {boolean} [opts.dryRun] 只打印计划，不落盘
  * @param {object} [opts.plan]   复用调用方已算好的计划（避免重复计算）
  * @param {boolean} [opts.showWarnings] 是否打印 plan.warnings，缺省 true
@@ -727,7 +415,8 @@ function modeLabel(mode) {
  */
 function main(opts = {}) {
   const cwd = opts.cwd || process.cwd();
-  const mode = opts.mode === MODE.FULL ? MODE.FULL : MODE.TOOLS_ONLY;
+  if (opts.mode && opts.mode !== MODE.TOOLS_ONLY) throw new Error('仅支持工具卸载');
+  const mode = MODE.TOOLS_ONLY;
 
   const plan = opts.plan || buildUninstallPlan({ cwd, tools: opts.tools, mode }).plan;
   const result = applyUninstallPlan(plan, { dryRun: Boolean(opts.dryRun) });
@@ -740,7 +429,7 @@ function main(opts = {}) {
   }
 
   console.log('');
-  console.log(`✅ 完成：处理 ${result.applied} 项，保留 ${result.skipped} 项`);
+  console.log(`${result.ok ? '✅ 完成' : '❌ 未完整卸载'}：处理 ${result.applied} 项，保留 ${result.skipped} 项`);
   if (result.errors.length) {
     console.log(`⚠️  ${result.errors.length} 项失败：`);
     for (const e of result.errors) console.log(`   - ${e}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-4",
+  "version": "2.7.8-5",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "lib/init.js",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "bench:check": "node test/benchmark-check.cjs",
-    "test": "node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/spec-detect.cjs && node test/workspace-layout.cjs && node test/sync-repos-spec-choice.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/deploy-strategy.cjs && node test/uninstall.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs test/runtime/usage-reporter.test.cjs test/runtime/usage-reporting.test.cjs test/runtime/git-identity.test.cjs test/runtime/kb-state-location.test.cjs && node test/runtime/metrics-v3.test.cjs && node test/runtime/fixback.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
+    "test": "node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/spec-detect.cjs && node test/workspace-layout.cjs && node test/sync-repos-spec-choice.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/deploy-strategy.cjs && node test/uninstall.cjs && node --test test/maintenance.test.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs test/runtime/usage-reporter.test.cjs test/runtime/usage-reporting.test.cjs test/runtime/git-identity.test.cjs test/runtime/kb-state-location.test.cjs && node test/runtime/metrics-v3.test.cjs && node test/runtime/fixback.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
   },
   "keywords": [
     "kld",
@@ -46,5 +46,8 @@
     "skywalk-sdd/kb-sync-identity.cjs",
     "README.md",
     "USABILITY.md"
-  ]
+  ],
+  "sddMaintenance": {
+    "toolOnly": 1
+  }
 }

package/skywalk-sdd/ontology/workspace-layout.cjs

@@ -167,7 +167,25 @@ function writeWorkspaceFile(workspaceRoot, layout) {
     '',
   ];
   const filePath = path.join(workspaceRoot, WORKSPACE_FILE);
-  fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+  if (fs.existsSync(filePath)) {
+    // sync-repos 只追加新仓；既有行、注释、自定义字段和暂时离线的仓库保留。
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const saved = parseWorkspaceYaml(raw);
+    if (!saved.spec_path || path.resolve(workspaceRoot, saved.spec_path) !== path.resolve(workspaceRoot, specRel)) {
+      throw new Error('已有多仓清单的 Spec 指向不一致，请先核对配置');
+    }
+    const known = new Set(saved.code_repos.map(rel => path.resolve(workspaceRoot, rel.replace(/^(["'])(.*)\1$/, '$2'))));
+    const additions = codeRels.filter(rel => !known.has(path.resolve(workspaceRoot, rel)));
+    if (!additions.length) return filePath;
+    const newline = raw.includes('\r\n') ? '\r\n' : '\n';
+    const existing = raw.split(/\r?\n/);
+    const header = existing.findIndex(line => /^code_repos:\s*(?:#.*)?$/.test(line));
+    if (header < 0) throw new Error('已有多仓清单缺少 code_repos 列表，请先修复配置');
+    existing.splice(header + 1, 0, ...additions.map(rel => `  - ${rel}`));
+    fs.writeFileSync(filePath, existing.join(newline), 'utf8');
+  } else {
+    fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+  }
   return filePath;
 }