kld-sdd 2.7.8 → 2.8.0

package/bin/kld-sdd-init.js

@@ -1,45 +1,681 @@
 #!/usr/bin/env node
 
 /**
- * KLD SDD 项目初始化工具
- * 一键配置团队标准化开发环境，内置 openSpec 模版
+ * KLD SDD CLI 入口
+ *
+ * 职责边界：
+ * - bin/（本文件）：命令行参数解析、帮助/版本输出、交互式输入（编辑器选择）、子命令路由
+ * - lib/：纯业务逻辑，只接收解析后的选项对象，不读取 process.argv
  *
  * 子命令:
  *   (无参数)     运行项目初始化
  *   log          SDD Telemetry CLI（记录阶段事件、查询指标）
  *   link-spec    将代码仓关联到本地 spec clone（git config sdd.specPath）
  *   sync-repos   工作目录下发现新增代码仓并轻量接入（不装 skills）
+ *   uninstall    卸载 SDD 产物（渐进式：先预览工具范围，最后确认执行）
  */
 
+'use strict';
+
 const path = require('path');
-const args = process.argv.slice(2);
+const { listToolProfileIds, buildToolConfigs } = require('../lib/tool-profiles');
+const { MODE, OP, modeLabel } = require('../lib/uninstall');
+const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+const { specSourceLabel } = specDetect;
+// spec 候选单选交互（唯一实现，与 lib/init.js 共用）
+const { selectSpecRoot: selectSpecChoice } = require('../lib/spec-choice');
 
-if (args[0] === 'log') {
-  // Telemetry CLI 模式
-  require('../skywalk-sdd/index.js').main();
-} else if (args[0] === 'link-spec') {
-  const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
-  const pathArg = args.find((item) => item.startsWith('--path='));
-  const projectArg = args.find((item) => item.startsWith('--project='));
-  const positional = args.slice(1).find((item) => !item.startsWith('--'));
+const args = cliArgs();
+const command = args[0];
+
+/** 统一的失败出口：stderr + 非零退出码 */
+function fail(message) {
+  console.error(`❌ ${message}`);
+  process.exit(1);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// CLI 输入层：参数解析 / 交互输入 / 帮助输出
+// 只做「字符串 → 选项对象」的转换，不落盘、不执行业务。
+// ═══════════════════════════════════════════════════════════════
+
+/** verbose 环境变量名（与 --verbose 等价） */
+const VERBOSE_ENV = 'KLD_SDD_VERBOSE';
+
+/** 取子命令及其后的参数（去掉 node 与脚本路径） */
+function cliArgs(argv = process.argv) {
+  return argv.slice(2);
+}
+
+function hasFlag(argv, ...names) {
+  return names.some((name) => argv.includes(name));
+}
+
+/**
+ * 输出详细度判定
+ * 触发条件：argv 含 --verbose，或 KLD_SDD_VERBOSE 为 1/true（大小写不敏感）
+ * 注意：-v 已被 --version 占用，不复用
+ */
+function isVerbose(argv, env) {
+  const list = Array.isArray(argv) ? argv : cliArgs();
+  const envVars = env && typeof env === 'object' ? env : process.env;
+  if (list.includes('--verbose')) return true;
+  const value = envVars[VERBOSE_ENV];
+  return typeof value === 'string' && /^(1|true)$/i.test(value);
+}
+
+/** 读取 --tool / --tool= 的原始值；未出现返回 null */
+function readToolArg(argv) {
+  const index = argv.findIndex((arg) => arg === '--tool' || arg.startsWith('--tool='));
+  if (index === -1) return null;
+  return argv[index] === '--tool' ? argv[index + 1] : argv[index].slice('--tool='.length);
+}
+
+/**
+ * 解析 --tool，返回编辑器 id 数组；未指定返回 null
+ * 支持：--tool codex、--tool=codex、--tool cursor,codex、--tool all
+ */
+function parseToolOption(argv) {
+  const rawValue = readToolArg(argv);
+  if (rawValue === null) return null;
+  if (!rawValue) {
+    throw new Error('缺少 --tool 参数值，请指定编辑器名称');
+  }
+
+  const allTools = listToolProfileIds();
+  const normalized = String(rawValue).trim().toLowerCase();
+  if (normalized === 'all' || normalized === '全部') {
+    return allTools;
+  }
+
+  const selected = normalized.split(',').map((item) => item.trim()).filter(Boolean);
+  const invalid = selected.filter((tool) => !allTools.includes(tool));
+  if (invalid.length > 0) {
+    throw new Error(`不支持的编辑器: ${invalid.join(', ')}。可用值: ${allTools.join(', ')}, all`);
+  }
+
+  return selected;
+}
+
+/**
+ * 解析 --spec-path（相对/绝对路径字符串）；未指定返回 null。
+ * 路径语义校验（必须落在当前目录内）属业务逻辑，由 lib 完成。
+ */
+function parseSpecPathOption(argv) {
+  const index = argv.findIndex(
+    (arg) => arg === '--spec-path' || arg.startsWith('--spec-path='),
+  );
+  if (index === -1) return null;
+
+  const rawValue = argv[index] === '--spec-path'
+    ? argv[index + 1]
+    : argv[index].slice('--spec-path='.length);
+
+  if (!rawValue || rawValue.startsWith('--')) {
+    throw new Error('缺少 --spec-path 参数值，请指定 spec 仓库目录（相对或绝对路径）');
+  }
+  return rawValue.trim();
+}
+
+/** kld-sdd [选项] */
+function parseInitArgs(argv = cliArgs(), env = process.env) {
+  const tools = parseToolOption(argv);
+  return {
+    help: hasFlag(argv, '-h', '--help'),
+    version: hasFlag(argv, '-v', '--version'),
+    verbose: isVerbose(argv, env),
+    skipOpenspec: argv.includes('--skip-openspec'),
+    skipTemplate: argv.includes('--skip-template'),
+    repairGit: argv[0] === 'repair-git' || argv.includes('--repair-git'),
+    applyRepair: argv.includes('--apply'),
+    json: argv.includes('--json'),
+    tools,
+    // 显式给了 --tool 即自动化场景：lib 据此抑制 spec 路径的交互询问
+    hasToolArg: tools !== null,
+    specPath: parseSpecPathOption(argv),
+  };
+}
+
+/**
+ * kld-sdd uninstall [选项]
+ *
+ * 卸载产物与编辑器无关（8 个编辑器的产物全量扫描），工作目录固定为当前目录，
+ * 故不提供 --tool / --project：仅卸载当前范围的工具，目录由 cwd 决定。
+ *
+ * --spec-path 用于无人值守场景：多候选（如用户复制的备份）时无法自动判定，
+ * 需显式指定要卸载的 spec 仓库。
+ */
+function parseUninstallArgs(argv = cliArgs()) {
+  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: MODE.TOOLS_ONLY,
+    dryRun: argv.includes('--dry-run'),
+    yes: hasFlag(argv, '--yes', '-y'),
+    help: hasFlag(argv, '-h', '--help'),
+  };
+}
+
+/**
+ * kld-sdd sync-repos [选项]
+ *
+ * --spec-path 用于无人值守场景：多候选（如用户复制的备份）时无法自动判定，
+ * 需显式指定要接入的 spec 仓库（与 uninstall 同名参数语义一致）。
+ */
+function parseSyncReposArgs(argv = cliArgs()) {
+  const projectArg = argv.find((item) => item.startsWith('--project='));
+  return {
+    workspaceRoot: path.resolve(projectArg ? projectArg.slice('--project='.length) : '.'),
+    onlyNew: !argv.includes('--all'),
+    specPath: parseSpecPathOption(argv),
+    yes: hasFlag(argv, '--yes', '-y'),
+  };
+}
+
+/** kld-sdd link-spec [选项] */
+function parseLinkSpecArgs(argv = cliArgs()) {
+  const pathArg = argv.find((item) => item.startsWith('--path='));
+  const projectArg = argv.find((item) => item.startsWith('--project='));
+  const positional = argv.slice(1).find((item) => !item.startsWith('--'));
   const specPath = pathArg ? pathArg.slice('--path='.length) : positional;
   const projectRoot = path.resolve(projectArg ? projectArg.slice('--project='.length) : '.');
   if (!specPath) {
-    console.error('用法: kld-sdd link-spec --path=<spec-clone> [--project=.]');
-    process.exit(1);
+    throw new Error('用法: kld-sdd link-spec --path=<spec-clone> [--project=.]');
   }
-  const result = sddConfig.setSpecPath(projectRoot, specPath);
-  if (!result.ok) {
-    console.error(`❌ ${result.message}`);
+  return { specPath, projectRoot };
+}
+
+/** 编辑器交互选择菜单映射（1-9） */
+const EDITOR_CHOICES = Object.freeze({
+  '1': ['cursor'],
+  '2': ['claude'],
+  '3': ['codebuddy'],
+  '4': ['qoder'],
+  '5': ['opencode'],
+  '6': ['kunlunzhima'],
+  '7': ['workbuddy'],
+  '8': ['codex'],
+  '9': listToolProfileIds(),
+});
+
+/**
+ * 让用户选择编辑器（交互式 CLI 输入，非参数解析）
+ * 无效输入时重新询问，不允许默认
+ */
+async function selectEditor(options = {}) {
+  const toolConfigs = buildToolConfigs();
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: options.input || process.stdin,
+    output: options.output || process.stdout,
+  });
+  const ask = (question) => new Promise(
+    (resolve) => rl.question(question, (answer) => resolve(String(answer).trim())),
+  );
+
+  try {
+    while (true) {
+      console.log('\n请选择您使用的 AI 编辑器:');
+      console.log('  1. Cursor');
+      console.log('  2. Claude Code');
+      console.log('  3. CodeBuddy');
+      console.log('  4. Qoder');
+      console.log('  5. OpenCode');
+      console.log('  6. KunlunZhima');
+      console.log('  7. WorkBuddy');
+      console.log('  8. Codex');
+      console.log('  9. 全部（为所有编辑器生成 skills）');
+
+      const answer = await ask('请输入选项 (1-9): ');
+      const selected = EDITOR_CHOICES[answer];
+
+      if (!selected) {
+        console.log(`❌ 无效选项 "${answer}"，请输入 1-9 之间的数字\n`);
+        continue; // 重新循环询问
+      }
+
+      const names = selected.map((k) => toolConfigs[k].name).join(', ');
+      console.log(`✓ 已选择: ${names}\n`);
+      return selected.slice();
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * 打开 readline 交互会话，返回 { ask, close }
+ * 卸载的「方式选择 / 计划预览 / 确认」全部在本文件完成（CLI 输入层职责）。
+ */
+function openPrompt(options = {}) {
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: options.input || process.stdin,
+    output: options.output || process.stdout,
+  });
+  return {
+    ask: (question) => new Promise(
+      (resolve) => rl.question(question, (answer) => resolve(String(answer).trim())),
+    ),
+    close: () => rl.close(),
+  };
+}
+
+/** 打印卸载头部信息 */
+function printUninstallHeader(cwd, specRoot, mode, dryRun) {
+  console.log('');
+  console.log(`🗑  KLD SDD 卸载 · ${modeLabel(mode)}`);
+  console.log(`   工作目录: ${cwd}`);
+  if (specRoot) console.log(`   Spec 包裹包: ${specRoot}`);
+  if (dryRun) console.log('   模式: 预演（不落盘）');
+  console.log('');
+}
+
+/**
+ * 打印计划预览：按操作类型分组，避免逐条刷屏。
+ * 每类最多列 5 条，其余折叠为计数；KEEP 项只列文件名与原因。
+ */
+function printPlanPreview(plan) {
+  const dels = plan.ops.filter((o) => o.op !== OP.KEEP);
+  const keeps = plan.ops.filter((o) => o.op === OP.KEEP);
+
+  const OP_LABELS = {
+    [OP.DELETE_DIR]: '删除目录',
+    [OP.DELETE_FILE]: '删除文件',
+    [OP.STRIP_HOOKS]: '摘除受管 hook（文件其余配置保留）',
+    [OP.STRIP_GITIGNORE]: '摘除 .gitignore 的 SDD 块（其余行保留）',
+    [OP.UNLINK_GIT_CONFIG]: '清除 git config sdd.specPath',
+  };
+
+  const byOp = new Map();
+  for (const item of dels) {
+    if (!byOp.has(item.op)) byOp.set(item.op, []);
+    byOp.get(item.op).push(item);
+  }
+
+  console.log(`📋 计划预览：待处理 ${dels.length} 项，保留 ${keeps.length} 项`);
+  console.log('');
+  for (const [op, items] of byOp) {
+    console.log(`  ${OP_LABELS[op] || op}（${items.length} 项）:`);
+    for (const item of items.slice(0, 5)) console.log(`    - ${item.target}`);
+    if (items.length > 5) console.log(`    … 其余 ${items.length - 5} 项`);
+    console.log('');
+  }
+  if (keeps.length) {
+    console.log(`  ✅ 保留（${keeps.length} 项）:`);
+    for (const item of keeps) console.log(`    - ${path.basename(item.target)}（${item.reason}）`);
+    console.log('');
+  }
+  for (const w of plan.warnings) console.log(`  ⚠️  ${w}`);
+  if (plan.warnings.length) console.log('');
+}
+
+/**
+ * 选择 spec 包裹包（单选）。
+ *
+ * 实现已收敛到 `lib/spec-choice.js#selectSpecRoot`（init / uninstall /
+ * sync-repos 三个场景共用的唯一交互实现）。此处仅作转发，保持 bin 层的
+ * 导出面不变（既有测试与 `runUninstall` 依赖）。
+ *
+ * @param {{ask: Function}} prompt readline 会话
+ * @param {Array<{abs: string, name: string, source: string, tier?: number}>} candidates
+ * @param {{actionLabel?: string}} [options] actionLabel 用于提问文案（默认「卸载」）
+ * @returns {Promise<string|null|undefined>} 选中的绝对路径；null=用户取消；undefined=无候选
+ */
+async function selectSpecRoot(prompt, candidates, options = {}) {
+  return selectSpecChoice(prompt, candidates, options);
+}
+
+/** 显示卸载帮助信息 */
+function showUninstallHelp() {
+  console.log(`
+KLD SDD 工具卸载
+
+用法:
+  kld-sdd uninstall                 # 选择 Spec → 预览范围 → 确认
+  kld-sdd uninstall --dry-run       # 只看计划，不修改文件
+  kld-sdd uninstall --yes --spec-path <dir>  # 明确范围后用于脚本
+
+仅删除可识别的 SDD Skills、运行脚本、只读模板与受管 Hook。
+始终保留 openspec/ 全部文档、KB 配置、项目身份、历史数据、多仓关联和 Git 历史。
+自定义 Hook、规则、未知文件与隐私忽略规则保留。不提供全量删除模式。
+
+-h, --help         显示本帮助
+--spec-path <dir>  指定目标 Spec；多个候选时必须选择，备份不受影响
+--dry-run          只预览
+-y, --yes          确认工具卸载；非交互执行必须提供
+
+升级不需要先卸载：重新运行 init 覆盖工具文件，保留已有文档及配置。
+`);
+}
+
+/** 显示初始化帮助信息 */
+function showInitHelp() {
+  console.log(`
+KLD SDD 项目初始化工具
+
+用法:
+  kld-sdd-init [选项]
+  npx kld-sdd [选项]
+  kld-sdd sync-repos           # 工作目录下发现新增代码仓并轻量接入（多 spec 候选时单选）
+  kld-sdd repair-git           # 检查并清理旧 Spec 仓的工具跟踪噪声（默认只预览）
+  kld-sdd uninstall [选项]     # 卸载 SDD 产物（渐进式：预览工具范围 → 确认）
+  kld-sdd uninstall --help     # 查看工具卸载与保留范围
+
+选项:
+  -h, --help       显示帮助信息
+  -v, --version    显示版本号
+  --verbose        输出每个安装文件/目录的明细日志（默认仅摘要，亦可用 KLD_SDD_VERBOSE=1）
+  --skip-openspec  跳过 openspec init 步骤
+  --skip-template  跳过复制内置模版
+  --repair-git     检查 Spec 仓中被 Git 跟踪的安装器工具（默认只预览）
+  --apply          与 --repair-git 同用：保留本地文件，仅从 Git 索引移除工具
+  --json           --repair-git 输出机器可读 JSON，供托盘健康检查使用
+  --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
+  --spec-path <dir> 指定 spec 包裹包目录（必须是当前目录的子目录）。
+                    不指定时（交互终端）：自动检测已有 spec 目录（目录名 *-sdd-specs，
+                    或 modules.yaml + sdd.config.yaml + openspec/changes + openspec/specs/overview.md 齐全），
+                    检测到则询问是否使用；未检测到则要求输入相对路径（回车用默认 <当前目录名>-sdd-specs）。
+                    例: 在 erp-klny-all 下 --spec-path erp-sdd-specs
+
+工作区模式（在个人工作目录执行）:
+  - skills / 编辑器配置只部署一次到当前工作目录
+  - 自动发现子目录 Git 仓库
+  - spec 仓：modules.yaml / openspec 模板 / 文档门禁
+  - 代码仓：仅 commit-msg Hook + .sdd.yaml + link-spec（不装 skills）
+  - Trailer 数据仍在代码 commit 时由 Hook 写入
+
+示例:
+  kld-sdd-init                 # 完整初始化流程
+  kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
+  kld-sdd-init --tool codex    # 仅部署 Codex 配置
+  kld-sdd-init --spec-path erp-sdd-specs  # 指定 spec 目录（当前目录的子目录）
+  kld-sdd repair-git --spec-path=.          # 预览旧仓工具跟踪问题
+  kld-sdd repair-git --apply --spec-path=.  # 一次迁出工具，文件仍留在磁盘
+  kld-sdd sync-repos           # 新代码仓加入后同步接入
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 子命令路由：解析参数后调用 lib/ 业务实现
+// ═══════════════════════════════════════════════════════════════
+
+function resolveRepairSpecRoot(parsed, cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  if (parsed.specPath) {
+    const explicit = path.resolve(root, parsed.specPath);
+    if (!specDetect.isSpecPackageRoot(explicit)) {
+      throw new Error(`指定目录不是有效的 Spec 包裹包: ${explicit}`);
+    }
+    return explicit;
+  }
+  if (specDetect.isSpecPackageRoot(root)) return root;
+  const candidates = specDetect.detectSpecCandidatesWithGit(root);
+  if (candidates.length === 1) return candidates[0].abs;
+  if (candidates.length === 0) throw new Error('未发现 Spec 包裹包，请用 --spec-path=<dir> 指定');
+  throw new Error(`发现 ${candidates.length} 个 Spec 包裹包，请用 --spec-path=<dir> 指定，不自动猜测`);
+}
+
+function runGitRepair(parsed) {
+  const init = require('../lib/init');
+  const maintenance = require('../lib/maintenance');
+  const specRoot = resolveRepairSpecRoot(parsed);
+  const plan = maintenance.trackedManagedSpecTools(specRoot);
+  if (!plan.ok) throw new Error(plan.error);
+
+  if (!parsed.applyRepair) {
+    const payload = {
+      mode: 'preview',
+      specRoot,
+      trackedToolCount: plan.files.length,
+      trackedTools: plan.files.map((file) => file.relative),
+      businessFilesAffected: 0,
+    };
+    if (parsed.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    console.log(`🧹 Spec Git 清洁度检查: ${path.basename(specRoot)}`);
+    console.log(`   被 Git 跟踪的可再生成工具: ${plan.files.length} 个`);
+    for (const file of plan.files.slice(0, 8)) console.log(`   - ${file.relative}`);
+    if (plan.files.length > 8) console.log(`   … 其余 ${plan.files.length - 8} 个`);
+    console.log('   业务 Spec、配置、项目身份与 Hook 参数: 不处理');
+    if (plan.files.length) console.log('   执行 --repair-git --apply 可一次迁出工具；不会删除磁盘文件。');
+    return;
+  }
+
+  const existingBefore = plan.files.filter((file) => require('fs').existsSync(path.join(specRoot, file.relative)));
+  init.updateGitignore(specRoot, { specPackage: true });
+  const result = maintenance.untrackManagedSpecTools(specRoot);
+  if (!result.ok) throw new Error(result.error);
+  const payload = {
+    mode: 'applied',
+    specRoot,
+    untrackedToolCount: result.files.length,
+    filesRemainOnDisk: existingBefore.every((file) => require('fs').existsSync(path.join(specRoot, file.relative))),
+    retainedLocalToolCount: existingBefore.length,
+    alreadyMissingToolCount: result.files.length - existingBefore.length,
+    businessFilesAffected: 0,
+  };
+  if (parsed.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(`✅ 已将 ${result.files.length} 个安装器工具移出 Git 跟踪，现存的 ${existingBefore.length} 个本地文件全部保留`);
+  if (payload.alreadyMissingToolCount) console.log(`   ℹ️ 其中 ${payload.alreadyMissingToolCount} 个文件在修复前已从磁盘删除`);
+  console.log('   请审阅一次 git status 并提交迁移；以后升级不再污染业务改动列表。');
+}
+
+async function runInit() {
+  let parsed;
+  try {
+    parsed = parseInitArgs(args);
+  } catch (error) {
+    fail(error.message);
+    return;
+  }
+
+  if (parsed.help) {
+    showInitHelp();
+    return;
+  }
+
+  if (parsed.version) {
+    console.log(require('../package.json').version);
+    return;
+  }
+
+  if (parsed.repairGit) {
+    try {
+      runGitRepair(parsed);
+    } catch (error) {
+      fail(`Git 清洁度修复失败: ${error.message}`);
+    }
+    return;
+  }
+
+  const init = require('../lib/init');
+  init.setVerbose(parsed.verbose);
+
+  try {
+    await init.main({
+      tools: parsed.tools,
+      selectTools: selectEditor,
+      hasToolArg: parsed.hasToolArg,
+      specPath: parsed.specPath,
+      skipOpenspec: parsed.skipOpenspec,
+      skipTemplate: parsed.skipTemplate,
+    });
+  } catch (error) {
+    fail(`初始化失败: ${error.message}`);
+  }
+}
+
+/**
+ * 卸载（渐进式）：方式选择 → 计划预览 → 确认执行。
+ *
+ * 交互编排全部在本函数（CLI 输入层）；仅选择 Spec、预览工具范围并确认：
+ * - buildUninstallPlan  纯计算计划，不落盘
+ * - main                按给定计划执行，无交互
+ *
+ * 非交互场景（管道 / CI / --dry-run / --yes）自动退化为直接执行。
+ */
+async function runUninstall(argv = args, deps = {}) {
+  let opts;
+  try {
+    opts = parseUninstallArgs(argv);
+  } catch (error) {
+    fail(error.message);
+    return;
+  }
+
+  if (opts.help) {
+    showUninstallHelp();
+    return;
+  }
+
+  const uninstall = require('../lib/uninstall');
+  const { buildUninstallPlan, main: runUninstallPlan, listSpecCandidatesForUninstall } = uninstall;
+  // 工作目录固定为 cwd；deps.cwd 仅供测试注入（避免测试改全局 cwd）
+  const cwd = deps.cwd ? path.resolve(deps.cwd) : opts.cwd;
+  const { dryRun } = opts;
+  let mode = opts.mode;
+
+  // 交互依赖可注入（测试用）：默认走真实 readline 与 process.stdin.isTTY
+  const promptFactory = deps.openPrompt || openPrompt;
+  const isTTY = deps.isTTY !== undefined ? Boolean(deps.isTTY) : Boolean(process.stdin.isTTY);
+
+  // 交互能力判定：
+  // - --dry-run 语义是「只看不改」，不弹菜单
+  // - --yes 表示无人值守，跳过全部询问
+  // - 无 TTY（管道 / CI）同样跳过询问
+  const canPrompt = isTTY && !dryRun && !opts.yes;
+
+  // 候选枚举：结构判据无法区分「当前项目的 spec 仓」与「用户复制的备份」
+  //（如 `erp-sdd-specs copy` 结构标记齐全），故由用户单选裁决。
+  // 显式 --spec-path 时跳过枚举（调用方已指定）。
+  let specRoot = opts.specPath ? path.resolve(cwd, opts.specPath) : undefined;
+  const candidates = specRoot ? [] : listSpecCandidatesForUninstall(cwd);
+
+  if (!specRoot && candidates.length > 1 && !canPrompt) {
+    // 无人值守 + 多候选：不猜，报错要求显式指定（猜错 = 不可逆数据丢失）。
+    // 抛错而非 process.exit：由 route() 统一转成非零退出码，测试也可断言。
+    const lines = [
+      `❌ 检测到 ${candidates.length} 个 spec 仓库，无法自动判定要卸载哪一个：`,
+      ...candidates.map((c) => `   - ${c.abs}`),
+      '   请用 --spec-path=<dir> 显式指定，或在交互终端中运行以手动选择。',
+    ];
+    for (const line of lines) console.error(line);
+    throw new Error('多个 spec 仓库候选，需 --spec-path 显式指定');
+  }
+
+  if (!specRoot && !canPrompt && candidates.length === 1) specRoot = candidates[0].abs;
+  const prompt = canPrompt ? promptFactory() : null;
+
+  // 步骤 1：spec 仓库选择（多候选 → 用户单选；单候选 → 确认）
+  // 必须在生成计划之前完成，保证预览列出的是用户真正要卸载的那一个。
+  try {
+    if (prompt && !specRoot) {
+      const chosenSpec = await selectSpecRoot(prompt, candidates);
+      if (chosenSpec === null) {
+        console.log('已取消');
+        return;
+      }
+      if (chosenSpec) specRoot = chosenSpec;
+    }
+
+    // 步骤 2：生成计划（纯计算，用于空产物判定与预览）
+    let planned = buildUninstallPlan({ cwd, mode, specRoot });
+
+    if (planned.plan.ops.length === 0) {
+      printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
+      console.log('ℹ️  未发现需要处理的 SDD 产物（可能未初始化或已卸载）');
+      return;
+    }
+
+    if (!prompt) {
+      if (!dryRun && !opts.yes) throw new Error('非交互卸载需要 --yes；可先用 --dry-run 预览');
+      printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
+      if (dryRun) printPlanPreview(planned.plan);
+      // 已打印过预览（含警告）时不重复；直接执行时由 lib 打印
+      const result = runUninstallPlan({ cwd, mode, dryRun, plan: planned.plan, showWarnings: !dryRun });
+      if (!result.ok) throw new Error(result.errors.join('; '));
+      return;
+    }
+
+    // 步骤 4：计划预览
+    printUninstallHeader(cwd, planned.specRoot, mode, dryRun);
+    printPlanPreview(planned.plan);
+
+    // 步骤 5：确认执行
+    const dels = planned.plan.ops.filter((o) => o.op !== OP.KEEP).length;
+    const answer = await prompt.ask(`将处理 ${dels} 项，此操作不可撤销。确认执行? (y/N): `);
+    if (!/^y(es)?$/i.test(answer)) {
+      console.log('已取消');
+      return;
+    }
+    console.log('');
+
+    // 交互路径：警告已由 printPlanPreview 打印过，不再重复
+    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();
+  }
+}
+
+/**
+ * sync-repos：工作区新增代码仓后轻量接入。
+ *
+ * spec 定位与 init / uninstall 同契约：多候选时让用户单选，**不静默挑一个**。
+ * 这里尤其重要 —— 本命令会把 spec 根路径写进每个代码仓的
+ * `git config sdd.specPath`，挑错等于污染全部代码仓的关联关系。
+ *
+ * 交互能力判定与 uninstall 一致：无 TTY / 非交互时不询问；
+ * 此时多候选直接报错，要求用 --spec-path 显式指定。
+ */
+async function runSyncRepos() {
+  const { syncWorkspaceRepos, listSpecCandidatesForInit } = require('../lib/init');
+  const opts = parseSyncReposArgs(args);
+
+  let specRoot = opts.specPath ? path.resolve(opts.specPath) : undefined;
+  const candidates = specRoot ? [] : listSpecCandidatesForInit(opts.workspaceRoot);
+  const canPrompt = Boolean(process.stdin.isTTY) && !opts.yes;
+
+  // 多候选 + 无法询问：不猜（猜错不可逆 —— 写错的是每个代码仓的 git config）
+  if (!specRoot && candidates.length > 1 && !canPrompt) {
+    const lines = [
+      `❌ 检测到 ${candidates.length} 个 spec 仓库，无法自动判定要接入哪一个：`,
+      ...candidates.map((c) => `   - ${c.abs}  [${specSourceLabel(c.source)}]`),
+      '   请用 --spec-path=<dir> 显式指定，或在交互终端中运行以手动选择。',
+    ];
+    for (const line of lines) console.error(line);
     process.exit(1);
   }
-  console.log(`✅ 已设置 git config --local sdd.specPath = ${result.path}`);
-} else if (args[0] === 'sync-repos') {
-  const { syncWorkspaceRepos } = require('../lib/init');
-  const projectArg = args.find((item) => item.startsWith('--project='));
-  const workspaceRoot = path.resolve(projectArg ? projectArg.slice('--project='.length) : '.');
-  const all = args.includes('--all');
-  const result = syncWorkspaceRepos(workspaceRoot, { onlyNew: !all });
+
+  // 单选（0 个候选 → undefined；1 个 → 确认；N 个 → 列出选择）
+  if (!specRoot && candidates.length > 0 && canPrompt) {
+    const prompt = openPrompt();
+    try {
+      const chosen = await selectSpecRoot(prompt, candidates, { actionLabel: '接入' });
+      if (chosen === null) {
+        console.log('已取消');
+        return;
+      }
+      if (chosen) specRoot = chosen;
+    } finally {
+      prompt.close();
+    }
+  }
+
+  const result = syncWorkspaceRepos(opts.workspaceRoot, {
+    onlyNew: opts.onlyNew,
+    specRoot,
+  });
+
   if (!result.ok && result.attached.length === 0 && (!result.layout || !result.layout.specRepo)) {
     process.exit(1);
   }
@@ -50,15 +686,63 @@ if (args[0] === 'log') {
     process.exit(1);
   }
   console.log(`✅ sync-repos 完成，接入 ${result.attached.length} 个代码仓`);
-} else if (args[0] === 'auth') {
-  // 登录体系已随 2.7.0 移除：仅保留 deprecation 提示，不进入 init 向导
-  console.log('ℹ️  auth 子命令已于 2.7.0 移除：使用统计按本机 git 身份（user.name/user.email）上报，无需绑定。');
-  process.exit(0);
-} else {
-  // 正常初始化模式
-  const { main } = require('../lib/init');
-  main().catch(error => {
-    console.error('❌ 初始化失败:', error.message);
-    process.exit(1);
-  });
 }
+
+function runLinkSpec() {
+  let opts;
+  try {
+    opts = parseLinkSpecArgs(args);
+  } catch (error) {
+    fail(error.message);
+    return;
+  }
+
+  const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
+  const result = sddConfig.setSpecPath(opts.projectRoot, opts.specPath);
+  if (!result.ok) {
+    fail(result.message);
+    return;
+  }
+  console.log(`✅ 已设置 git config --local sdd.specPath = ${result.path}`);
+}
+
+/**
+ * 子命令路由（仅在被当作入口脚本执行时触发）。
+ *
+ * require.main 守卫：使本文件可被测试 require 以复用卸载编排函数，
+ * 而不产生「加载即执行」的副作用。
+ */
+function route() {
+  if (command === 'uninstall') {
+    // 卸载模式：默认只删工具内容，保留用户配置与运行时数据
+    runUninstall().catch((error) => fail(error.message));
+  } else if (command === 'log') {
+    // Telemetry CLI 模式（运行时入口为 index.cjs，部署到用户仓后改名为 log.cjs）
+    require('../skywalk-sdd/index.cjs').main();
+  } else if (command === 'link-spec') {
+    runLinkSpec();
+  } else if (command === 'sync-repos') {
+    // 与 uninstall 一致：异步失败统一转成 stderr + 非零退出码
+    runSyncRepos().catch((error) => fail(error.message));
+  } else if (command === 'auth') {
+    // 登录体系已随 2.7.0 移除：仅保留 deprecation 提示，不进入 init 向导
+    console.log('ℹ️  auth 子命令已于 2.7.0 移除：使用统计按本机 git 身份（user.name/user.email）上报，无需绑定。');
+    process.exit(0);
+  } else {
+    // 正常初始化模式
+    runInit();
+  }
+}
+
+if (require.main === module) {
+  route();
+}
+
+module.exports = {
+  route,
+  runUninstall,
+  parseUninstallArgs,
+  printPlanPreview,
+  selectSpecRoot,
+  showUninstallHelp,
+};