kld-sdd 2.7.8 → 2.8.0

package/lib/maintenance.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// 安装、升级、卸载共用的边界；业务文档和关联配置不属于可清理的工具文件。
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+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 posix(relative) {
+  return String(relative || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+const MANAGED_ROOT_TOOLS = new Set([
+  'apply-worktree-finish.cjs',
+  'context-client.cjs',
+  'kb-sync-identity.cjs',
+  'kb-upload.cjs',
+  'log.cjs',
+  'metrics-v3.cjs',
+  'openspec-shim.cjs',
+  'runtime-metadata.cjs',
+  'spec-root.cjs',
+]);
+
+const MANAGED_HOOK_TOOLS = new Set([
+  'commit-msg-runner.cjs',
+  'commit-msg-sdd-trailer.cjs',
+  'consistency-check-core.cjs',
+  'delivery-check.cjs',
+  'delivery-snapshot.cjs',
+  'pre-commit-consistency-check.cjs',
+  'pre-commit-sdd-check.cjs',
+  'pre-push-consistency-check.cjs',
+  'pre-push-sdd-check.cjs',
+]);
+
+function specPackageIgnoreLines() {
+  return [
+    ...[...MANAGED_ROOT_TOOLS].sort().map((name) => `/skywalk-sdd/${name}`),
+    '/skywalk-sdd/lib/',
+    '/skywalk-sdd/ontology/',
+    '/skywalk-sdd/reporting/',
+    '/skywalk-sdd/ci/github-actions-sdd.yml',
+    '/skywalk-sdd/ci/gitlab-ci-sdd.yml',
+    ...[...MANAGED_HOOK_TOOLS].sort().map((name) => `/skywalk-sdd/git-hooks/${name}`),
+    '/openspec-templates/',
+    '/openspec/kld-sdd操作手册.html',
+    '/_tmp_*',
+    '/*-start.log',
+  ];
+}
+
+/**
+ * 只识别能够由 kld-sdd 安装器重新生成的文件。
+ * 业务 Spec、项目身份、Hook 参数、KB 配置和历史数据都不属于工具文件。
+ */
+function isManagedSpecToolPath(relative) {
+  const rel = posix(relative);
+  if (rel === 'openspec/kld-sdd操作手册.html' || rel.startsWith('openspec-templates/')) return true;
+  if (rel.startsWith('skywalk-sdd/') && MANAGED_ROOT_TOOLS.has(rel.slice('skywalk-sdd/'.length))) return true;
+  if (/^skywalk-sdd\/(?:lib|ontology|reporting)\//.test(rel)) return true;
+  if (/^skywalk-sdd\/ci\/(?:github-actions-sdd|gitlab-ci-sdd)\.yml$/.test(rel)) return true;
+  const hookPrefix = 'skywalk-sdd/git-hooks/';
+  return rel.startsWith(hookPrefix) && MANAGED_HOOK_TOOLS.has(rel.slice(hookPrefix.length));
+}
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      error: String(result.stderr || result.stdout || 'git 命令失败').trim(),
+      output: '',
+    };
+  }
+  return { ok: true, output: String(result.stdout || '') };
+}
+
+/** 列出当前 Spec 包中仍被 Git 跟踪的安装器工具文件。 */
+function trackedManagedSpecTools(specRoot) {
+  const requestedRoot = path.resolve(specRoot);
+  const root = fs.existsSync(requestedRoot) ? fs.realpathSync(requestedRoot) : requestedRoot;
+  const top = git(root, ['rev-parse', '--show-toplevel']);
+  if (!top.ok) return { ok: false, specRoot: root, files: [], error: '当前 Spec 目录不在 Git 仓库中' };
+  const gitRoot = path.resolve(top.output.trim());
+  const rootRelative = posix(path.relative(gitRoot, root));
+  if (rootRelative.startsWith('../') || path.isAbsolute(rootRelative)) {
+    return { ok: false, specRoot: root, gitRoot, files: [], error: 'Spec 目录不属于检测到的 Git 仓库' };
+  }
+  const pathspec = rootRelative ? `${rootRelative}/` : '.';
+  const listed = git(gitRoot, ['ls-files', '-z', '--', pathspec]);
+  if (!listed.ok) return { ok: false, specRoot: root, gitRoot, files: [], error: listed.error };
+  const prefix = rootRelative ? `${rootRelative}/` : '';
+  const files = listed.output.split('\0').filter(Boolean).map(posix).flatMap((gitPath) => {
+    if (prefix && !gitPath.startsWith(prefix)) return [];
+    const relative = prefix ? gitPath.slice(prefix.length) : gitPath;
+    return isManagedSpecToolPath(relative) ? [{ gitPath, relative }] : [];
+  });
+  return { ok: true, specRoot: root, gitRoot, files };
+}
+
+/**
+ * 将安装器工具从 Git 索引移除，文件仍留在磁盘供本地运行。
+ * 调用方必须先把对应规则写入 Spec 根 .gitignore。
+ */
+function untrackManagedSpecTools(specRoot) {
+  const plan = trackedManagedSpecTools(specRoot);
+  if (!plan.ok || plan.files.length === 0) return plan;
+  for (let offset = 0; offset < plan.files.length; offset += 100) {
+    const batch = plan.files.slice(offset, offset + 100).map((file) => file.gitPath);
+    const removed = git(plan.gitRoot, ['update-index', '--force-remove', '--', ...batch]);
+    if (!removed.ok) return { ...plan, ok: false, error: removed.error };
+  }
+  return { ...plan, untracked: plan.files.length };
+}
+
+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,
+  specPackageIgnoreLines,
+  isManagedSpecToolPath,
+  trackedManagedSpecTools,
+  untrackManagedSpecTools,
+  samePath,
+  associationConflict,
+  workspaceCodeRepos,
+  maintenanceConflicts,
+};

package/lib/managed-hook-hashes.json

@@ -0,0 +1,24 @@
+{
+  "pre-commit": [
+    "497f012da027df5c26af3c501126e9a1c26276b038ee3b1edaaf5ab4401aa95c",
+    "7322d9aecafb497a5f40171a6bd7daeaadd7d2056b4a253cb0ee1a128faea36e",
+    "8fcdd74a3d2afaa823f9038c477c9dfd6fe53e2bccbe48cecd01535794862e4a",
+    "c8546c6c96adc3ecc32a15a689c59189543c2454f47998c46fbd5a0bf810cf30",
+    "e3b6776af51df76ff04b528152d0049a6c45d94d96a19bd2bc5ca2cc9786b22c"
+  ],
+  "pre-push": [
+    "405debb5e6f9186e95b727e6013b06ef3e06c598b6d2b96678d34554d3530e8c",
+    "461abd16663757c5a092103ac2ecae8453891c0c817d1c763369e0cdd0a8ec7b",
+    "80f710ff647ce8b216fb1c081fb3e22f6ee8be25847b6d02921668ba83fb1965",
+    "d49eb8794fde4b0d7847a876cc7083d161b290a44990ff8a036c2ebb8a00ec21",
+    "e6e125cbf9d7424c01b249ce03197cef9e1923ed2974a53656084488a0de60c4",
+    "ebf628481ae93ac0c4c6649b204449f6825291dc6b6550a71563bebec1f3ad92"
+  ],
+  "commit-msg": [
+    "15083d5165bff965ab2feba9a55dfedcecd54cb577c06fd11f4d1b9672d978b6",
+    "3b0ee15f5a126d159e14c5a3681cb7820cbf9c5e0c134ee6812053bc34330b85",
+    "6db7adbf17905bf14915d7e57a3c5ac46030ee3282fea5d5b211c80065406d48",
+    "9c5a86761b36d71b655f804a822eff675a244175799736c803e1f7379c638609",
+    "fc390776720393f100712fa02d5e143c2927fbb0d605a4a0242824ff7ea84574"
+  ]
+}

package/lib/settings-merge.js

@@ -1,19 +1,40 @@
 /**
- * Conservative merge for CodeBuddy .codebuddy/settings.json hooks.
+ * 编辑器 settings.json 中 SDD 受管 hook 的识别、合并与摘除。
+ *
+ * 策略归属：`.claude/settings.json` 与 `.codebuddy/settings.json` 都是**用户配置** → MERGE。
+ * - 安装：保留用户未知字段与自定义 hook，只剔除并重装 SDD 受管 hook（幂等）
+ * - 卸载：只摘除 SDD 受管 hook，文件其余内容原样保留
+ *
+ * 两个 provider 的 hook 判定集中在此模块，保证「装得进去的一定摘得掉」。
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
+const { STRATEGY, ACTION, deployFile } = require('./deploy-strategy');
+
+/** CodeBuddy 受管 hook：$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/sdd-*.cjs */
+const SDD_CODEBUDDY_HOOK_COMMAND_RE = /(?:^|\s|["'])\$?CODEBUDDY_PROJECT_DIR[\\/]+\.codebuddy[\\/]+hooks[\\/]+sdd-[\w-]+\.cjs(?=$|\s|["'])/i;
+
+/** Claude 受管 hook：.claude/hooks/sdd-*.cjs（含 ${CLAUDE_PROJECT_DIR} 形式） */
+const SDD_CLAUDE_HOOK_COMMAND_RE = /(?:^|\s|["'])(?:\$\{CLAUDE_PROJECT_DIR\}[\\/]+)?\.claude[\\/]+hooks[\\/]+sdd-(?:prompt|pre-tool|post-tool|stop|apply-gate|apply-test-gate|skill-apply-gate)\.(?:cjs|js)(?=$|\s|["'])/i;
 
-const SDD_HOOK_COMMAND_RE = /(?:^|\s|["'])\$?CODEBUDDY_PROJECT_DIR[\\/]+\.codebuddy[\\/]+hooks[\\/]+sdd-[\w-]+\.cjs(?=$|\s|["'])/i;
+const PROVIDERS = Object.freeze({
+  CLAUDE: 'claude',
+  CODEBUDDY: 'codebuddy',
+});
 
 function hookCommandText(hook) {
   const args = Array.isArray(hook.args) ? hook.args : [];
   return [hook.command, ...args].filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
 }
 
-function isSddCodebuddyHook(hook) {
-  return SDD_HOOK_COMMAND_RE.test(hookCommandText(hook));
+/** 判断单个 hook 是否 SDD 受管（按 provider 选择判定规则） */
+function isSddHook(hook, provider) {
+  const text = hookCommandText(hook);
+  if (provider === PROVIDERS.CLAUDE) return SDD_CLAUDE_HOOK_COMMAND_RE.test(text);
+  return SDD_CODEBUDDY_HOOK_COMMAND_RE.test(text);
 }
 
 function sameHookCommand(left, right) {
@@ -21,36 +42,56 @@ function sameHookCommand(left, right) {
     String(left.type || '') === String(right.type || '');
 }
 
-function removeManagedSddHooks(entries) {
-  return entries
+/**
+ * 从 hook 条目数组中剔除 SDD 受管 hook，保留用户自定义条目。
+ * 条目内 hooks 被清空时整条移除。
+ */
+function removeManagedHooks(entries, provider) {
+  return (entries || [])
     .map(entry => {
       if (!Array.isArray(entry.hooks)) {
         return entry;
       }
       return {
         ...entry,
-        hooks: entry.hooks.filter(hook => !isSddCodebuddyHook(hook)),
+        hooks: entry.hooks.filter(hook => !isSddHook(hook, provider)),
       };
     })
     .filter(entry => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
 }
 
-function mergeCodebuddySettings(settingsPath, templateSettings) {
-  const displayPath = path.basename(settingsPath);
-  let originalBytes = '';
-  if (fs.existsSync(settingsPath)) {
-    originalBytes = fs.readFileSync(settingsPath, 'utf8');
+/**
+ * 纯计算：摘除 settings 对象中全部 SDD 受管 hook（卸载路径）。
+ * 返回新对象，不修改入参；hooks 变空时保留空对象结构，避免下游读取报错。
+ */
+function stripManagedHooks(settings, provider) {
+  const next = { ...settings };
+  if (!next.hooks || typeof next.hooks !== 'object') {
+    return next;
+  }
+  const hooks = {};
+  for (const [eventName, entries] of Object.entries(next.hooks)) {
+    hooks[eventName] = removeManagedHooks(entries, provider);
   }
+  next.hooks = hooks;
+  return next;
+}
 
+/**
+ * 纯计算：把模板 hooks 合并进已有配置，保留用户未知字段与自定义 hook。
+ *
+ * @param {string|null} existingRaw 现有 settings.json 原文（不存在传 null）
+ * @param {object} templateSettings 模板 settings 对象
+ * @param {string} [provider] 受管 hook 归属，默认 codebuddy
+ * @returns {{ok: true, merged: object} | {ok: false, error: string}}
+ */
+function computeMergedSettings(existingRaw, templateSettings, provider = PROVIDERS.CODEBUDDY) {
   let existingSettings = {};
-  if (originalBytes) {
+  if (existingRaw) {
     try {
-      existingSettings = JSON.parse(originalBytes);
+      existingSettings = JSON.parse(existingRaw);
     } catch {
-      return {
-        ok: false,
-        error: `${displayPath} 不是合法 JSON，请修复后重试（路径: ${settingsPath}）`,
-      };
+      return { ok: false, error: '不是合法 JSON' };
     }
   }
 
@@ -58,7 +99,7 @@ function mergeCodebuddySettings(settingsPath, templateSettings) {
   merged.hooks = merged.hooks || {};
 
   for (const [eventName, entries] of Object.entries(templateSettings.hooks || {})) {
-    merged.hooks[eventName] = removeManagedSddHooks(merged.hooks[eventName] || []);
+    merged.hooks[eventName] = removeManagedHooks(merged.hooks[eventName], provider);
     for (const entry of entries) {
       const templateHooks = entry.hooks || [];
       const exists = merged.hooks[eventName].some(existingEntry => {
@@ -73,13 +114,49 @@ function mergeCodebuddySettings(settingsPath, templateSettings) {
     }
   }
 
-  fs.writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
-  return { ok: true };
+  return { ok: true, merged };
+}
+
+/**
+ * 从模板文件部署 settings.json（用户配置 → MERGE）。
+ * 所有写盘经 deploy-strategy，非法 JSON 时 fail-closed 并保持原字节不变。
+ *
+ * @returns {{ok: boolean, action?: string, error?: string}}
+ */
+function mergeCodebuddySettingsFromTemplate(sourcePath, targetPath) {
+  const displayPath = path.basename(targetPath);
+  let templateSettings;
+  try {
+    templateSettings = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+  } catch (error) {
+    return { ok: false, error: `模板 ${displayPath} 无法解析: ${error.message}` };
+  }
+
+  const result = deployFile(sourcePath, targetPath, {
+    strategy: STRATEGY.MERGE,
+    label: displayPath,
+    mergeFn: ({ readTarget }) => {
+      const computed = computeMergedSettings(readTarget(), templateSettings, PROVIDERS.CODEBUDDY);
+      if (!computed.ok) {
+        return {
+          ok: false,
+          error: `${displayPath} 不是合法 JSON，请修复后重试（路径: ${targetPath}）`,
+        };
+      }
+      fs.writeFileSync(targetPath, JSON.stringify(computed.merged, null, 2) + '\n', 'utf8');
+      return { ok: true, action: ACTION.MERGED };
+    },
+  });
+
+  if (!result.ok) {
+    return { ok: false, error: result.message };
+  }
+  return { ok: true, action: result.action };
 }
 
 module.exports = {
-  mergeCodebuddySettings,
-  isSddCodebuddyHook,
-  hookCommandText,
-  removeManagedSddHooks,
+  PROVIDERS,
+  mergeCodebuddySettingsFromTemplate,
+  computeMergedSettings,
+  stripManagedHooks,
 };

package/lib/skills-bundle.js

@@ -2,6 +2,8 @@
  * SDD skills bundle 共享配置与模板渲染
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
 
@@ -16,7 +18,7 @@ const POWERSHELL_TABOOS = [
   '',
   '> - **PowerShell 禁忌**（Windows 用户必读）:',
   '>   - 禁止 `| cat`（PowerShell 将 cat 解释为 Get-Content，不接受管道输入）→ 直接执行命令',
-  '>   - 禁止 `node -e "..."` 内联脚本（PowerShell 对 `||`/`{}`/`()` 有特殊解析，导致 JS 语法被破坏）→ 用 `write_to_file` 创建临时 `.cjs` 脚本执行后删除',
+  '>   - 禁止 `node -e "..."` 内联脚本（PowerShell 对 `||`/`{}`/`()` 有特殊解析，导致 JS 语法被破坏）→ 用 `write_to_file` 创建临时脚本执行后删除；脚本**必须 `.cjs` 后缀、只用 `require`**（项目 package.json 声明 `type: module` 时 `.js` 会被误判 ESM 报 ERR_REQUIRE_ESM）',
   '>   - 禁止 cmd.exe 语法（如 `for /L %i in (1,1,N) do ...`）→ PowerShell 不支持，改用逐个 `execute_command` 调用或 PowerShell `foreach`',
   '>   - 警告 CLIXML：PowerShell 捕获 `node`/`npx` 子进程输出时可能包装为 `#< CLIXML <Objs...>` 格式 → 检测到 CLIXML 时以文件系统实际产物为准，忽略 stdout',
   '>   - 禁止 `curl`（PowerShell 将 curl 别名为 Invoke-WebRequest）→ HTTP 请求走 `context-client.cjs` / `kb-upload.cjs`，或用 `Invoke-RestMethod`',
@@ -38,6 +40,7 @@ const OPSX_SKILL_DIRS = [
   // Engineering KB 依赖技能（随 init 部署；propose/spec/archive 硬依赖）
   'opsx-kb-config',
   'opsx-ontology-query',
+  'opsx-ontology-ingest',
   'opsx-kb-ingest',
   // Spec 一致性校验技能
   'opsx-consistency-check',
@@ -120,6 +123,7 @@ const KUNLUN_SLASH_COMMANDS = [
   'archive',
   'explore',
   'ontology-query',
+  'ontology-ingest',
   'kb-ingest',
   'kb-config',
   'consistency-check',
@@ -186,10 +190,6 @@ module.exports = {
   OPSX_SKILL_METADATA,
   buildOpsxSkillMetadata,
   commandNameFromSkillDir,
-  displayNameFromCommandName,
-  parseSkillFrontmatter,
   renderTemplate,
-  replaceProfileTokens,
-  transformKunlunSlashCommands,
   validateRenderedContent,
 };

package/lib/spec-choice.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * spec 候选的单选交互 —— init / uninstall / sync-repos 三个场景**共用**。
+ *
+ * 为什么需要用户裁决：判据无法区分「当前项目的 spec 仓」与「用户手动复制的
+ * 备份」（如 `erp-sdd-specs copy`）—— 二者都命中。故由用户单选，而不是静默
+ * 挑一个：挑错的代价是 init 把内容灌进错误目录、uninstall 删错仓、
+ * sync-repos 把错误路径写进每个代码仓的 `git config`。
+ *
+ * 归属 lib/ 而非 bin/：init 的交互发生在 `lib/init.js#main()` 内部，uninstall
+ * 与 sync-repos 的交互在 bin/ 层。放在 lib/ 使两侧都能复用，且依赖方向正确
+ *（bin → lib，不反向）。
+ *
+ * 交互约定（三个场景一致）：
+ * - 0 个候选 → 返回 undefined（调用方决定「要求输入路径」还是「报错退出」）
+ * - 1 个候选 → 确认（回车默认 Y）
+ * - N 个候选 → 列出（标注来源）让用户单选
+ *
+ * 实现约束：候选信息必须**并入 question 字符串**，不能靠提问前的 console.log。
+ * readline 重绘提示行时会发 \x1b[0J（清除光标之后内容），会把前置输出抹掉，
+ * 导致用户看不到自己在确认哪个目录。
+ */
+
+const { specSourceLabel } = require('../skywalk-sdd/ontology/spec-detect.cjs');
+
+/**
+ * 让用户在 spec 候选集合中单选。
+ *
+ * @param {{ask: (q: string) => Promise<string>}} prompt readline 会话（只需 ask）
+ * @param {Array<{abs: string, name: string, source: string, tier?: number}>} candidates
+ *        候选集合（由 spec-detect 枚举，已按 tier 排序）
+ * @param {{actionLabel?: string}} [options]
+ *        actionLabel：提问文案里的动作词（默认「卸载」；init 用「使用」、
+ *        sync-repos 用「接入」）
+ * @returns {Promise<string|null|undefined>}
+ *          string=选中的绝对路径；null=用户拒绝/取消；undefined=无候选
+ */
+async function selectSpecRoot(prompt, candidates, options = {}) {
+  if (!candidates || candidates.length === 0) return undefined;
+  const action = options.actionLabel || '卸载';
+
+  if (candidates.length === 1) {
+    const only = candidates[0];
+    const question = [
+      `\n🔍 检测到 spec 仓库: ${only.name}  [${specSourceLabel(only.source)}]`,
+      `   位置: ${only.abs}`,
+      `是否${action}该 spec 仓库？(Y=是 / n=重新选择，默认 Y): `,
+    ].join('\n');
+    while (true) {
+      const answer = await prompt.ask(question);
+      const normalized = String(answer || '').trim().toLowerCase();
+      if (!normalized || normalized === 'y' || normalized === 'yes') return only.abs;
+      if (normalized === 'n' || normalized === 'no') break;
+      console.log(`❌ 无效输入 "${answer}"，请输入 Y 或 n`);
+    }
+    // 拒绝唯一候选 → 无其它候选可选，交由调用方决定后续（重新选择 / 输入路径）
+    return null;
+  }
+
+  while (true) {
+    const question = [
+      `\n检测到多个 spec 仓库，请选择要${action}的一个:`,
+      ...candidates.map(
+        (c, i) => `  ${i + 1}. ${c.name}  [${specSourceLabel(c.source)}]\n     ${c.abs}`,
+      ),
+      '  0. 取消',
+      `\n请输入选项 (0-${candidates.length}): `,
+    ].join('\n');
+
+    const answer = await prompt.ask(question);
+    const trimmed = String(answer || '').trim();
+    if (trimmed === '0' || /^(q|quit|exit)$/i.test(trimmed)) return null;
+
+    const index = Number(trimmed);
+    if (Number.isInteger(index) && index >= 1 && index <= candidates.length) {
+      const chosen = candidates[index - 1];
+      console.log(`✓ 已选择: ${chosen.name}\n`);
+      return chosen.abs;
+    }
+    console.log(`❌ 无效选项 "${answer}"，请输入 0-${candidates.length} 之间的数字\n`);
+  }
+}
+
+module.exports = { selectSpecRoot };

package/lib/tool-profiles.js

@@ -3,6 +3,8 @@
  * Single source of truth for per-agent paths and capabilities.
  */
 
+'use strict';
+
 const path = require('path');
 
 const TOOL_PROFILES = Object.freeze({
@@ -272,7 +274,5 @@ module.exports = {
   getToolProfile,
   listToolProfileIds,
   validateToolProfiles,
-  isSafeRelativePath,
   buildToolConfigs,
-  DEFAULT_TOOL_DISPLAY_NAMES,
 };