@hunterzheng/kld-sdd 2.4.19

package/lib/init.js

@@ -0,0 +1,1124 @@
+/**
+ * KLD SDD 初始化核心逻辑
+ *
+ * 功能：
+ * 1. 检测并自动安装 openspec
+ * 2. 执行 openspec init 生成基础结构
+ * 3. 部署 opsx skills
+ * 4. 复制标准文档模版到项目
+ * 5. 更新 .gitignore
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const readline = require('readline');
+const os = require('os');
+const {
+  SKILLS_BUNDLE_NAME,
+  OPSX_SKILL_DIRS,
+  renderTemplate
+} = require('./skills-bundle');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+// 工具类型配置
+const TOOL_CONFIGS = {
+  cursor: {
+    name: 'Cursor',
+    configDir: '.cursor',
+    commandsDir: '.cursor/commands',
+    opsxDir: '.cursor/commands/opsx',
+    skillsDir: '.cursor/skills',
+    agentType: 'cursor'
+  },
+  claude: {
+    name: 'Claude Code',
+    configDir: '.claude',
+    commandsDir: '.claude/commands',
+    opsxDir: '.claude/commands/opsx',
+    skillsDir: '.claude/skills',
+    agentType: 'claude-code'
+  },
+  codebuddy: {
+    name: 'CodeBuddy',
+    configDir: '.codebuddy',
+    commandsDir: '.codebuddy/commands',
+    opsxDir: '.codebuddy/commands/opsx',
+    skillsDir: '.codebuddy/skills',
+    agentType: 'codebuddy'
+  },
+  qoder: {
+    name: 'Qoder',
+    configDir: '.qoder',
+    commandsDir: '.qoder/commands',
+    opsxDir: '.qoder/commands/opsx',
+    skillsDir: '.qoder/skills',
+    agentType: 'qoder'
+  },
+  opencode: {
+    name: 'OpenCode',
+    configDir: '.opencode',
+    commandsDir: '.opencode/commands',
+    opsxDir: '.opencode/commands/opsx',
+    skillsDir: '.opencode/skills',
+    agentType: 'opencode',
+    // opencode 原生命令使用 command/（单数），需要额外清理
+    nativeCommandDir: '.opencode/command'
+  },
+  kunlunzhima: {
+    name: 'KunlunZhima',
+    configDir: '.kunlunzhima',
+    commandsDir: '.kunlunzhima/commands',
+    opsxDir: '.kunlunzhima/commands/opsx',
+    skillsDir: '.kunlunzhima/skills',
+    agentType: 'kunlunzhima'
+  },
+  workbuddy: {
+    name: 'WorkBuddy',
+    configDir: '.workbuddy',
+    commandsDir: '.workbuddy/commands',
+    opsxDir: '.workbuddy/commands/opsx',
+    skillsDir: '.workbuddy/skills',
+    agentType: 'workbuddy'
+  },
+  codex: {
+    name: 'Codex',
+    configDir: '.agents',
+    commandsDir: '.agents/commands',
+    opsxDir: '.agents/commands/opsx',
+    skillsDir: '.agents/skills',
+    agentType: 'codex'
+  }
+};
+
+/**
+ * 询问用户选择
+ */
+function ask(question) {
+  return new Promise(resolve => {
+    rl.question(question, answer => resolve(answer.trim()));
+  });
+}
+
+/**
+ * 从命令行参数读取指定编辑器
+ * 支持：--tool codex、--tool=codex、--tool cursor,codex、--tool all
+ */
+function parseSelectedTools(args) {
+  const toolArgIndex = args.findIndex(arg => arg === '--tool' || arg.startsWith('--tool='));
+  if (toolArgIndex === -1) return null;
+
+  const rawValue = args[toolArgIndex] === '--tool'
+    ? args[toolArgIndex + 1]
+    : args[toolArgIndex].slice('--tool='.length);
+
+  if (!rawValue) {
+    throw new Error('缺少 --tool 参数值，请指定编辑器名称');
+  }
+
+  const normalized = rawValue.trim().toLowerCase();
+  if (normalized === 'all' || normalized === '全部') {
+    return Object.keys(TOOL_CONFIGS);
+  }
+
+  const selected = normalized.split(',').map(item => item.trim()).filter(Boolean);
+  const invalid = selected.filter(tool => !TOOL_CONFIGS[tool]);
+  if (invalid.length > 0) {
+    throw new Error(`不支持的编辑器: ${invalid.join(', ')}。可用值: ${Object.keys(TOOL_CONFIGS).join(', ')}, all`);
+  }
+
+  return selected;
+}
+
+/**
+ * 让用户选择编辑器
+ * 无效输入时重新询问，不允许默认
+ */
+async function selectEditor() {
+  const mapping = {
+    '1': ['cursor'],
+    '2': ['claude'],
+    '3': ['codebuddy'],
+    '4': ['qoder'],
+    '5': ['opencode'],
+    '6': ['kunlunzhima'],
+    '7': ['workbuddy'],
+    '8': ['codex'],
+    '9': ['cursor', 'claude', 'codebuddy', 'qoder', 'opencode', 'kunlunzhima', 'workbuddy', 'codex']
+  };
+
+  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 = mapping[answer];
+    
+    if (!selected) {
+      console.log(`❌ 无效选项 "${answer}"，请输入 1-9 之间的数字\n`);
+      continue;  // 重新循环询问
+    }
+    
+    const names = selected.map(k => TOOL_CONFIGS[k].name).join(', ');
+    console.log(`✓ 已选择: ${names}\n`);
+    return selected;
+  }
+}
+
+/**
+ * 检查命令是否可用
+ */
+function commandExists(command) {
+  try {
+    if (os.platform() === 'win32') {
+      execSync(`where ${command}`, { stdio: 'ignore' });
+    } else {
+      execSync(`which ${command}`, { stdio: 'ignore' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 获取包安装路径
+ */
+function getPackagePath() {
+  // 尝试多种方式找到包的路径
+  try {
+    // 方式1：通过 require.resolve 找到包位置
+    const mainPath = require.resolve('../package.json');
+    return path.dirname(mainPath);
+  } catch {
+    // 方式2：使用当前文件位置
+    return path.resolve(__dirname, '..');
+  }
+}
+
+/**
+ * 获取模版路径
+ */
+function getTemplatePath() {
+  const pkgPath = getPackagePath();
+  return path.join(pkgPath, 'templates', 'openspec');
+}
+
+/**
+ * 自动安装 openspec
+ */
+async function installOpenspec() {
+  console.log('📦 openspec 未安装，正在自动安装...');
+  
+  const npmCmd = os.platform() === 'win32' ? 'npm.cmd' : 'npm';
+  const openspecPkg = '@fission-ai/openspec@latest';
+  
+  try {
+    // 尝试全局安装
+    console.log(`   正在执行: npm install -g ${openspecPkg}`);
+    execSync(`${npmCmd} install -g ${openspecPkg}`, { 
+      stdio: 'inherit',
+      timeout: 180000
+    });
+    console.log('✅ openspec 安装完成');
+    return true;
+  } catch (error) {
+    console.log('❌ 全局安装失败，尝试本地安装...');
+    
+    try {
+      // 本地安装到当前项目
+      const cwd = process.cwd();
+      execSync(`${npmCmd} install ${openspecPkg}`, { 
+        cwd,
+        stdio: 'inherit',
+        timeout: 180000
+      });
+      console.log('✅ openspec 本地安装完成');
+      return true;
+    } catch (localError) {
+      console.log(`❌ 安装失败，请手动安装: npm install -g ${openspecPkg}`);
+      return false;
+    }
+  }
+}
+
+/**
+ * 执行 openspec init
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+async function runOpenspecInit(selectedTools = []) {
+  console.log('🚀 正在运行 openspec init...');
+  
+  // 检查 openspec 是否安装
+  if (!commandExists('openspec')) {
+    const shouldInstall = await ask('openspec 未安装，是否自动安装? (y/n): ');
+    if (shouldInstall === 'y' || shouldInstall === 'Y') {
+      const installed = await installOpenspec();
+      if (!installed) {
+        console.log('⚠️  跳过 openspec 初始化，继续应用模版...');
+        return false;
+      }
+    } else {
+      console.log('⚠️  跳过 openspec 安装，继续应用模版...');
+      return false;
+    }
+  }
+  
+  try {
+    // openspec CLI 支持的工具列表（kunlunzhima 等自定义工具不在其中）
+    const openspecSupportedTools = ['cursor', 'claude', 'codebuddy', 'qoder', 'opencode'];
+    
+    // 过滤出 openspec 支持的工具
+    const supportedTools = selectedTools.filter(t => openspecSupportedTools.includes(t));
+    const unsupportedTools = selectedTools.filter(t => !openspecSupportedTools.includes(t));
+    
+    if (unsupportedTools.length > 0) {
+      const names = unsupportedTools.map(k => TOOL_CONFIGS[k]?.name || k).join(', ');
+      console.log(`   ℹ️  ${names} 不在 openspec 支持列表中，将单独创建目录结构`);
+    }
+    
+    // 构建工具参数：只传递 openspec 支持的工具
+    // 当没有支持的工具时，使用 --tools none 创建基础目录结构
+    const toolsArg = supportedTools.length > 0 
+      ? `--tools ${supportedTools.join(',')}` 
+      : '--tools none';
+    
+    // 执行 openspec init，传入支持的工具（或 none）
+    const cmd = `openspec init ${toolsArg} --force`.trim();
+    console.log(`   执行: ${cmd}`);
+    execSync(cmd, { stdio: 'inherit' });
+    
+    console.log('✅ openspec 初始化完成');
+    return true;
+  } catch (error) {
+    console.log('⚠️  openspec init 执行失败，继续应用模版...');
+    return false;
+  }
+}
+
+/**
+ * 递归复制目录
+ */
+function copyDir(source, target) {
+  if (!fs.existsSync(target)) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+  
+  const files = fs.readdirSync(source);
+  for (const file of files) {
+    const srcPath = path.join(source, file);
+    const tgtPath = path.join(target, file);
+    
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+      copyDir(srcPath, tgtPath);
+    } else {
+      fs.copyFileSync(srcPath, tgtPath);
+    }
+  }
+}
+
+function copyDirRendered(source, target, config, toolKey) {
+  if (!fs.existsSync(target)) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  const files = fs.readdirSync(source);
+  for (const file of files) {
+    const srcPath = path.join(source, file);
+    const tgtPath = path.join(target, file);
+
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+      copyDirRendered(srcPath, tgtPath, config, toolKey);
+    } else {
+      const rendered = renderTemplate(fs.readFileSync(srcPath, 'utf8'), config, toolKey);
+      fs.writeFileSync(tgtPath, rendered, 'utf8');
+    }
+  }
+}
+
+/** OpenSpec init 生成的 4 个官方 slash command（KLD-SDD 使用 skills，不保留 command） */
+const NATIVE_OPSX_CMDS_HYPHEN = [
+  'opsx-propose.md',
+  'opsx-apply.md',
+  'opsx-archive.md',
+  'opsx-explore.md'
+];
+const NATIVE_OPSX_CMDS_SLASH = ['propose.md', 'apply.md', 'archive.md', 'explore.md'];
+
+/**
+ * SDD 自定义 command 标记（init 不部署；用户手动维护时保留）
+ */
+function isSddCustomCommand(content) {
+  return content.includes('# SDD') || content.includes('skywalk-sdd/log.cjs');
+}
+
+/**
+ * 清理原生 openspec 命令，所有编辑器与 Cursor 行为一致：初始化时删除官方 command。
+ * 同时清理 openspec 遗留的 JSON 文件。
+ *
+ * 覆盖 TOOL_CONFIGS 中的全部编辑器（cursor/claude/codebuddy/qoder/opencode/kunlunzhima/workbuddy/codex），
+ * 与 Cursor 行为一致：初始化时删除 OpenSpec 官方 command，仅保留 skills。
+ *
+ * openspec 对不同工具生成的目录结构：
+ * - Cursor: commands/opsx-*.md（根目录，连字符）
+ * - Claude/CodeBuddy/Qoder 等: commands/opsx/*.md（opsx 子目录）
+ * - OpenCode: command/opsx-*.md（command 单数目录，整目录删除）
+ *
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function cleanupNativeOpenspecCommands(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🗑  正在清理原生 openspec 命令（所有编辑器与 Cursor 一致，仅保留 skills）...');
+
+  const cwd = process.cwd();
+
+  for (const toolKey of selectedTools) {
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config) continue;
+    
+    const configDir = path.join(cwd, config.configDir);
+    if (!fs.existsSync(configDir)) continue;
+
+    // 处理 commands/ 目录（复数，标准目录）
+    const commandsDir = path.join(configDir, 'commands');
+    if (fs.existsSync(commandsDir)) {
+      // 删除 JSON 文件（openspec 安装的遗留）
+      const allFiles = fs.readdirSync(commandsDir);
+      let deletedJson = 0;
+      for (const file of allFiles) {
+        const filePath = path.join(commandsDir, file);
+        if (file.endsWith('.json') && fs.statSync(filePath).isFile()) {
+          fs.unlinkSync(filePath);
+          deletedJson++;
+        }
+      }
+      if (deletedJson > 0) {
+        console.log(`   🗑  ${config.name}: 删除 ${deletedJson} 个 JSON 命令文件`);
+      }
+
+      // 删除 commands/ 根目录下的原生 opsx-* 命令（Cursor 等，与 Claude 行为一致）
+      let deletedCmds = 0;
+      for (const file of fs.readdirSync(commandsDir)) {
+        const isNativeHyphen = NATIVE_OPSX_CMDS_HYPHEN.includes(file) || /^opsx-.*\.md$/i.test(file);
+        if (!isNativeHyphen) continue;
+        const filePath = path.join(commandsDir, file);
+        if (!fs.statSync(filePath).isFile()) continue;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (isSddCustomCommand(content)) continue;
+        fs.unlinkSync(filePath);
+        deletedCmds++;
+      }
+      if (deletedCmds > 0) {
+        console.log(`   ✓ ${config.name}: 删除 ${deletedCmds} 个原生 opsx-* 命令（commands/）`);
+      }
+
+      // 删除 commands/opsx/ 子目录下的官方命令（Claude/CodeBuddy/Qoder 等，与 Cursor 一致无条件删除）
+      const opsxDir = path.join(commandsDir, 'opsx');
+      if (fs.existsSync(opsxDir)) {
+        let deletedOpsxCmds = 0;
+        for (const file of NATIVE_OPSX_CMDS_SLASH) {
+          const filePath = path.join(opsxDir, file);
+          if (!fs.existsSync(filePath)) continue;
+          const content = fs.readFileSync(filePath, 'utf-8');
+          if (isSddCustomCommand(content)) continue;
+          fs.unlinkSync(filePath);
+          deletedOpsxCmds++;
+        }
+        if (deletedOpsxCmds > 0) {
+          console.log(`   ✓ ${config.name}: 删除 ${deletedOpsxCmds} 个原生命令（commands/opsx/）`);
+        }
+        // 子目录为空则移除
+        if (fs.readdirSync(opsxDir).length === 0) {
+          fs.rmdirSync(opsxDir);
+        }
+      }
+    }
+
+    // 处理 command/ 目录（单数，opencode 特有）
+    if (config.nativeCommandDir) {
+      const nativeDir = path.join(cwd, config.nativeCommandDir);
+      if (fs.existsSync(nativeDir)) {
+        // 删除整个 command/ 目录（全是原生命令）
+        fs.rmSync(nativeDir, { recursive: true, force: true });
+        console.log(`   🗑  ${config.name}: 删除原生 command/ 目录`);
+      }
+    }
+  }
+
+  console.log('✅ 原生 openspec 命令清理完成');
+  return true;
+}
+
+/**
+ * 清理旧版嵌套 bundle（skills/kld-sdd/opsx-*）
+ * Claude Code 只识别 skills/<skill-name>/SKILL.md 一层，嵌套 bundle 无法被 / 菜单发现
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function cleanupLegacyBundledOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🧹 正在清理旧版嵌套 skills/kld-sdd/ bundle...');
+
+  const cwd = process.cwd();
+
+  for (const toolKey of selectedTools) {
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config || !config.skillsDir) continue;
+
+    const bundledDir = path.join(cwd, config.skillsDir, SKILLS_BUNDLE_NAME);
+    if (fs.existsSync(bundledDir)) {
+      fs.rmSync(bundledDir, { recursive: true, force: true });
+      console.log(`   🗑  ${config.name}: 删除嵌套 bundle ${SKILLS_BUNDLE_NAME}/`);
+    }
+
+    const legacySdd = path.join(cwd, config.skillsDir, 'opsx-sdd');
+    if (fs.existsSync(legacySdd)) {
+      fs.rmSync(legacySdd, { recursive: true, force: true });
+      console.log(`   🗑  ${config.name}: 删除旧版 opsx-sdd/`);
+    }
+  }
+
+  console.log('✅ 旧版嵌套 bundle 清理完成');
+  return true;
+}
+
+/**
+ * 部署 SDD opsx skills
+ * 模板源：templates/skills/kld-sdd/（源码组织）
+ * 部署目标：.claude/skills/opsx-<name>/SKILL.md（扁平一层，Claude Code 可识别）
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🎯 正在部署 opsx skills...');
+  
+  const pkgPath = getPackagePath();
+  const cwd = process.cwd();
+  
+  const skillsTemplatePath = path.join(pkgPath, 'templates', 'skills', SKILLS_BUNDLE_NAME);
+  
+  if (!fs.existsSync(skillsTemplatePath)) {
+    console.log(`⚠️  SDD skills 模板目录不存在: ${skillsTemplatePath}`);
+    return false;
+  }
+  
+  // 获取 bundle 内所有 skill 目录
+  const skillDirs = fs.readdirSync(skillsTemplatePath).filter(d => {
+    return fs.statSync(path.join(skillsTemplatePath, d)).isDirectory();
+  });
+  
+  if (skillDirs.length === 0) {
+    console.log('⚠️  没有找到任何 skill 模板');
+    return false;
+  }
+  
+  for (const toolKey of selectedTools) {
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config || !config.skillsDir) continue;
+    
+    const targetSkillsDir = path.join(cwd, config.skillsDir);
+    
+    // 确保 skills 目录存在
+    if (!fs.existsSync(targetSkillsDir)) {
+      fs.mkdirSync(targetSkillsDir, { recursive: true });
+    }
+    
+    console.log(`   部署 ${config.name} 的 opsx skills（${skillDirs.length} 个，扁平到 ${config.skillsDir}/）...`);
+    
+    for (const skillDir of skillDirs) {
+      const sourceDir = path.join(skillsTemplatePath, skillDir);
+      const targetDir = path.join(targetSkillsDir, skillDir);
+      
+      if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+      }
+      
+      if (fs.existsSync(sourceDir)) {
+        copyDirRendered(sourceDir, targetDir, config, toolKey);
+        console.log(`     ✓ ${skillDir}/`);
+      }
+    }
+  }
+  
+  console.log('✅ opsx skills 部署完成');
+  return true;
+}
+
+/**
+ * 部署 Claude Code Hook Pack（可选增强）
+ * Hook 只调用 skywalk-sdd/log.cjs，不写私有日志，不替代 OPSX 模板采集。
+ */
+function hookCommandText(hook) {
+  const args = Array.isArray(hook.args) ? hook.args : [];
+  return [hook.command, ...args].filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function isSddClaudeHook(hook) {
+  const text = hookCommandText(hook);
+  return /(?:^|\s|["'])\.claude[\\/]+hooks[\\/]+sdd-(?:prompt|pre-tool|post-tool|stop|apply-gate|apply-test-gate|skill-apply-gate)\.(?:cjs|js)(?=$|\s|["'])/i.test(text) ||
+    /(?:^|\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.test(text);
+}
+
+function sameHookCommand(left, right) {
+  return hookCommandText(left) === hookCommandText(right) &&
+    String(left.type || '') === String(right.type || '');
+}
+
+function removeManagedSddHooks(entries) {
+  return entries
+    .map(entry => {
+      if (!Array.isArray(entry.hooks)) {
+        return entry;
+      }
+      return {
+        ...entry,
+        hooks: entry.hooks.filter(hook => !isSddClaudeHook(hook)),
+      };
+    })
+    .filter(entry => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
+}
+
+function deployClaudeHookPack(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  if (!selectedTools.includes('claude')) {
+    return true;
+  }
+
+  console.log('🪝 正在部署 Claude Code SDD Hook Pack...');
+
+  const pkgPath = getPackagePath();
+  const cwd = process.cwd();
+  const hookTemplateDir = path.join(pkgPath, 'templates', 'hooks', 'claude');
+  const hookSourceDir = path.join(hookTemplateDir, 'hooks');
+  const settingsTemplatePath = path.join(hookTemplateDir, 'settings.json');
+
+  if (!fs.existsSync(hookSourceDir) || !fs.existsSync(settingsTemplatePath)) {
+    console.log(`   ⚠️  Claude Hook 模板缺失: ${hookTemplateDir}`);
+    return false;
+  }
+
+  const claudeDir = path.join(cwd, '.claude');
+  const targetHookDir = path.join(claudeDir, 'hooks');
+  if (!fs.existsSync(targetHookDir)) {
+    fs.mkdirSync(targetHookDir, { recursive: true });
+  }
+
+  copyDir(hookSourceDir, targetHookDir);
+  console.log('   ✓ 部署 .claude/hooks/sdd-*.cjs');
+
+  const targetSettingsPath = path.join(claudeDir, 'settings.json');
+  const templateSettings = JSON.parse(fs.readFileSync(settingsTemplatePath, 'utf8'));
+  let existingSettings = {};
+  if (fs.existsSync(targetSettingsPath)) {
+    try {
+      existingSettings = JSON.parse(fs.readFileSync(targetSettingsPath, 'utf8'));
+    } catch {
+      const backupPath = `${targetSettingsPath}.backup`;
+      fs.copyFileSync(targetSettingsPath, backupPath);
+      console.log(`   ℹ️  settings.json 不是合法 JSON，已备份到 ${backupPath}`);
+      existingSettings = {};
+    }
+  }
+
+  existingSettings.hooks = existingSettings.hooks || {};
+  for (const [eventName, entries] of Object.entries(templateSettings.hooks || {})) {
+    existingSettings.hooks[eventName] = removeManagedSddHooks(existingSettings.hooks[eventName] || []);
+    for (const entry of entries) {
+      const templateHooks = entry.hooks || [];
+      const exists = existingSettings.hooks[eventName].some(existingEntry => {
+        const existingHooks = existingEntry.hooks || [];
+        return templateHooks.every(templateHook => {
+          return existingHooks.some(existingHook => sameHookCommand(existingHook, templateHook));
+        });
+      });
+      if (!exists) {
+        existingSettings.hooks[eventName].push(entry);
+      }
+    }
+  }
+
+  fs.writeFileSync(targetSettingsPath, JSON.stringify(existingSettings, null, 2) + '\n', 'utf8');
+  console.log('   ✓ 合并 .claude/settings.json hooks 配置');
+  console.log('✅ Claude Code SDD Hook Pack 已就绪（可选增强，核心采集仍由 OPSX skills 完成）');
+  return true;
+}
+
+/**
+ * 清理原生 openspec-* skills（防止残留）
+ * 仅负责删除 openspec init 产生的原生 skills。
+ * 
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function cleanupNativeOpenspecSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🧹 正在清理原生 openspec-* skills...');
+
+  const cwd = process.cwd();
+
+  // 原生 openspec-* skills（需要删除）
+  const nativeSkillsToRemove = [
+    'openspec-propose',
+    'openspec-apply-change',
+    'openspec-archive-change',
+    'openspec-explore'
+  ];
+
+  for (const toolKey of selectedTools) {
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config || !config.skillsDir) continue;
+    
+    const skillsDir = path.join(cwd, config.skillsDir);
+    if (!fs.existsSync(skillsDir)) continue;
+
+    let removed = 0;
+    for (const nativeSkill of nativeSkillsToRemove) {
+      const nativeSkillDir = path.join(skillsDir, nativeSkill);
+      if (fs.existsSync(nativeSkillDir)) {
+        fs.rmSync(nativeSkillDir, { recursive: true, force: true });
+        removed++;
+      }
+    }
+    if (removed > 0) {
+      console.log(`   🗑  ${config.name}: 删除 ${removed} 个原生 openspec-* skills`);
+    }
+  }
+
+  console.log('✅ 原生 skills 清理完成');
+  return true;
+}
+
+/**
+ * 复制标准文档模版到项目
+ */
+function copyTemplatesToProject() {
+  console.log('📄 正在复制标准文档模版到项目...');
+  
+  const pkgPath = getPackagePath();
+  const templatePath = path.join(pkgPath, 'templates', 'openspec');
+  const cwd = process.cwd();
+  const targetDir = path.join(cwd, 'openspec-templates');
+  
+  if (!fs.existsSync(templatePath)) {
+    console.log(`⚠️  模版源目录不存在: ${templatePath}`);
+    return false;
+  }
+  
+  // 创建目标目录
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  
+  // 复制模版文件
+  copyDir(templatePath, targetDir);
+  
+  console.log(`✅ 标准文档模版已复制到: ${targetDir}`);
+  console.log('   包含文件:');
+  const files = fs.readdirSync(targetDir);
+  files.forEach(file => {
+    console.log(`     - ${file}`);
+  });
+  
+  return true;
+}
+
+/**
+ * 初始化全局 overview.md 到 openspec/specs/ 目录
+ * overview.md 是全局架构约束，所有 Capability 的设计都必须遵守
+ */
+function initGlobalOverview() {
+  console.log('🌐 正在初始化全局架构约束 (overview.md)...');
+  
+  const pkgPath = getPackagePath();
+  const overviewSource = path.join(pkgPath, 'templates', 'openspec', 'overview.md');
+  const cwd = process.cwd();
+  const targetDir = path.join(cwd, 'openspec', 'specs');
+  const targetFile = path.join(targetDir, 'overview.md');
+  
+  // 检查源文件是否存在
+  if (!fs.existsSync(overviewSource)) {
+    console.log(`⚠️  overview.md 源文件不存在: ${overviewSource}`);
+    return false;
+  }
+  
+  // 创建目标目录
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  
+  // 检查目标文件是否已存在
+  if (fs.existsSync(targetFile)) {
+    // 读取现有文件，检查是否需要更新
+    const existingContent = fs.readFileSync(targetFile, 'utf-8');
+    const newContent = fs.readFileSync(overviewSource, 'utf-8');
+    
+    if (existingContent === newContent) {
+      console.log('   ✓ overview.md 已是最新版本，跳过');
+      return true;
+    }
+    
+    // 备份现有文件
+    const backupFile = path.join(targetDir, 'overview.md.backup');
+    fs.copyFileSync(targetFile, backupFile);
+    console.log(`   ℹ️  已备份现有 overview.md 到 ${backupFile}`);
+  }
+  
+  // 复制 overview.md
+  fs.copyFileSync(overviewSource, targetFile);
+  
+  console.log(`✅ 全局架构约束已初始化: ${targetFile}`);
+  console.log('   ℹ️  此文件定义了全局数据字典、接口规范、共享实体等约束');
+  console.log('   ℹ️  执行 opsx-design 或 opsx-task 时会自动读取此文件');
+  
+  return true;
+}
+
+/**
+ * 部署 SDD Telemetry 数据目录
+ * 创建本地数据目录用于存储事件和活跃状态（最终报告落 openspec/changes/<change>/reports/，不再写 skywalk-sdd/reports/）
+ */
+function deployTelemetryDataDir() {
+  console.log('📊 正在初始化 SDD Telemetry 数据目录...');
+
+  const pkgPath = getPackagePath();
+  const cwd = process.cwd();
+  const dataDir = path.join(cwd, 'skywalk-sdd');
+
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
+  }
+
+  // 创建本地数据目录（事件和活跃状态存储；报告落 change 子目录，不在此创建）
+  const eventsDir = path.join(dataDir, 'events');
+  const stateDir = path.join(dataDir, 'state');
+  if (!fs.existsSync(eventsDir)) {
+    fs.mkdirSync(eventsDir, { recursive: true });
+    console.log('   ✓ 创建 skywalk-sdd/events/ 数据目录');
+  }
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+    console.log('   ✓ 创建 skywalk-sdd/state/ 活跃阶段状态目录');
+  }
+
+  // 部署项目内 Telemetry CLI（不依赖 npm 发布）
+  const telemetrySrc = path.join(pkgPath, 'skywalk-sdd', 'index.cjs');
+  const telemetryDst = path.join(dataDir, 'log.cjs');
+  if (fs.existsSync(telemetrySrc)) {
+    fs.copyFileSync(telemetrySrc, telemetryDst);
+    console.log('   ✓ 部署 skywalk-sdd/log.cjs（本地 Telemetry CLI）');
+  } else {
+    console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
+  }
+
+  const worktreeFinishSrc = path.join(pkgPath, 'skywalk-sdd', 'apply-worktree-finish.cjs');
+  const worktreeFinishDst = path.join(dataDir, 'apply-worktree-finish.cjs');
+  if (fs.existsSync(worktreeFinishSrc)) {
+    fs.copyFileSync(worktreeFinishSrc, worktreeFinishDst);
+    console.log('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
+  }
+
+  console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics');
+  console.log('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
+  console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
+  return true;
+}
+
+function installGitHookShim(cwd, hookName, scriptPath) {
+  const hooksDir = path.join(cwd, '.git', 'hooks');
+  if (!fs.existsSync(hooksDir)) {
+    return;
+  }
+
+  const hookPath = path.join(hooksDir, hookName);
+  const marker = 'KLD SDD quality gate';
+  const shim = [
+    '#!/bin/sh',
+    `# ${marker}`,
+    `if [ -f "${scriptPath}" ]; then`,
+    `  node "${scriptPath}" "$@"`,
+    'fi',
+    '',
+  ].join('\n');
+
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf8');
+    if (existing.includes(marker)) {
+      console.log(`   ✓ .git/hooks/${hookName} 已包含 SDD 质量门禁`);
+    } else {
+      console.log(`   ℹ️  .git/hooks/${hookName} 已存在，已保留不覆盖；可手动调用 ${scriptPath}`);
+    }
+    return;
+  }
+
+  fs.writeFileSync(hookPath, shim, 'utf8');
+  try {
+    fs.chmodSync(hookPath, 0o755);
+  } catch {
+    // Windows 上 chmod 可能没有实际效果，不影响 Git Bash 执行文本 hook。
+  }
+  console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁`);
+}
+
+/**
+ * 部署 Git hooks / CI 兜底模板
+ * 这些脚本只做质量门禁和 CI 补充记录，不替代 OPSX 主采集链路。
+ */
+function deployQualityGateTemplates() {
+  console.log('🧰 正在部署 SDD Git hooks / CI 兜底模板...');
+
+  const pkgPath = getPackagePath();
+  const cwd = process.cwd();
+  const dataDir = path.join(cwd, 'skywalk-sdd');
+  const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
+  const ciTemplateDir = path.join(pkgPath, 'templates', 'ci');
+  const targetGitHooksDir = path.join(dataDir, 'git-hooks');
+  const targetCiDir = path.join(dataDir, 'ci');
+
+  if (fs.existsSync(gitHooksTemplateDir)) {
+    copyDir(gitHooksTemplateDir, targetGitHooksDir);
+    console.log('   ✓ 部署 skywalk-sdd/git-hooks/');
+  } else {
+    console.log(`   ⚠️  Git hooks 模板缺失: ${gitHooksTemplateDir}`);
+  }
+
+  if (fs.existsSync(ciTemplateDir)) {
+    copyDir(ciTemplateDir, targetCiDir);
+    console.log('   ✓ 部署 skywalk-sdd/ci/');
+  } else {
+    console.log(`   ⚠️  CI 模板缺失: ${ciTemplateDir}`);
+  }
+
+  installGitHookShim(cwd, 'pre-commit', 'skywalk-sdd/git-hooks/pre-commit-sdd-check.cjs');
+  installGitHookShim(cwd, 'pre-push', 'skywalk-sdd/git-hooks/pre-push-sdd-check.cjs');
+
+  console.log('✅ Git hooks / CI 兜底模板已就绪');
+  return true;
+}
+
+/**
+ * 检测当前项目已初始化的 AI 编辑器
+ */
+function detectTools() {
+  const detected = [];
+  const cwd = process.cwd();
+  for (const [key, config] of Object.entries(TOOL_CONFIGS)) {
+    if (fs.existsSync(path.join(cwd, config.configDir))) {
+      detected.push(key);
+    }
+  }
+  return detected;
+}
+
+/**
+ * 创建 / 更新 .gitignore
+ */
+function updateGitignore() {
+  const cwd = process.cwd();
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const requiredLines = [
+    '.cursor/commands/personal-*',
+    '.claude/commands/personal-*',
+    '.codebuddy/commands/personal-*',
+    '.qoder/commands/personal-*',
+    '.kunlunzhima/commands/personal-*',
+    '.workbuddy/commands/personal-*',
+    '.agents/commands/personal-*',
+    'skywalk-sdd/events/',
+    'skywalk-sdd/state/',
+    '.worktrees/'
+  ];
+
+  const sddConfig = `
+# KLD SDD AI 编辑器个人配置（请勿提交）
+.cursor/commands/personal-*
+.claude/commands/personal-*
+.codebuddy/commands/personal-*
+.qoder/commands/personal-*
+.kunlunzhima/commands/personal-*
+.workbuddy/commands/personal-*
+.agents/commands/personal-*
+
+# SDD Telemetry 数据（本地度量，可选提交；最终报告落 openspec/changes/<change>/reports/ 随 change 提交）
+skywalk-sdd/events/
+skywalk-sdd/state/
+
+# SDD Apply 隔离 worktree（本地临时目录）
+.worktrees/
+`;
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    if (!content.includes('KLD SDD')) {
+      fs.appendFileSync(gitignorePath, sddConfig);
+      console.log('✅ 已更新 .gitignore');
+    } else {
+      const missingLines = requiredLines.filter(line => !content.includes(line));
+      if (missingLines.length > 0) {
+        fs.appendFileSync(gitignorePath, `\n# KLD SDD 补充忽略规则\n${missingLines.join('\n')}\n`);
+        console.log('✅ 已补充 .gitignore');
+      }
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, sddConfig.trim());
+    console.log('✅ 已创建 .gitignore');
+  }
+}
+
+/**
+ * 显示帮助信息
+ */
+function showHelp() {
+  console.log(`
+KLD SDD 项目初始化工具
+
+用法:
+  kld-sdd-init [选项]
+  npx kld-sdd [选项]
+
+选项:
+  -h, --help       显示帮助信息
+  -v, --version    显示版本号
+  --skip-openspec  跳过 openspec init 步骤
+  --skip-template  跳过复制内置模版
+  --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
+
+示例:
+  kld-sdd-init                 # 完整初始化流程
+  kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
+  kld-sdd-init --tool codex    # 仅部署 Codex 配置
+`);
+}
+
+/**
+ * 主函数
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  
+  // 解析参数
+  if (args.includes('-h') || args.includes('--help')) {
+    showHelp();
+    rl.close();
+    return;
+  }
+  
+  if (args.includes('-v') || args.includes('--version')) {
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    rl.close();
+    return;
+  }
+  
+  const skipOpenspec = args.includes('--skip-openspec');
+  const skipTemplate = args.includes('--skip-template');
+
+  console.log('╔════════════════════════════════════════╗');
+  console.log('║     KLD SDD 项目初始化工具             ║');
+  console.log('║     内置 openSpec 标准模版             ║');
+  console.log('╚════════════════════════════════════════╝');
+  console.log();
+
+  // 0. 选择编辑器
+  let selectedTools;
+  try {
+    selectedTools = parseSelectedTools(args) || await selectEditor();
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
+    rl.close();
+    return;
+  }
+
+  // 1. 运行 openspec init（传入用户选择的工具）
+  if (!skipOpenspec) {
+    await runOpenspecInit(selectedTools);
+  }
+
+  if (!skipTemplate) {
+    // 2. 清理原生 openspec 命令（删除 opsx-*.md，避免命名混淆）
+    cleanupNativeOpenspecCommands(selectedTools);
+
+    // 3. 清理旧版嵌套 skills/kld-sdd/ bundle（Claude Code 无法识别二层目录）
+    cleanupLegacyBundledOpsxSkills(selectedTools);
+
+    // 3.1 部署 SDD opsx skills（扁平到 .claude/skills/opsx-*/）
+    deployOpsxSkills(selectedTools);
+    
+    // 3.2 清理原生 openspec-* skills（防止残留）
+    cleanupNativeOpenspecSkills(selectedTools);
+
+    // 3.3 部署 Claude Code Hook Pack（可选增强）
+    deployClaudeHookPack(selectedTools);
+
+    // 5. 部署 SDD Telemetry 数据目录
+    deployTelemetryDataDir();
+
+    // 5.1 部署 Git hooks / CI 兜底模板
+    deployQualityGateTemplates();
+
+    // 6. 复制标准文档模版到项目（供参考）
+    copyTemplatesToProject();
+    
+    // 7. 初始化全局架构约束 (overview.md)
+    initGlobalOverview();
+  }
+
+  // 7. 更新 .gitignore
+  updateGitignore();
+
+  const selectedNames = selectedTools.map(t => TOOL_CONFIGS[t].name).join(', ');
+
+  console.log();
+  console.log('╔════════════════════════════════════════╗');
+  console.log('║     ✅ 初始化完成！                   ║');
+  console.log('╚════════════════════════════════════════╝');
+  console.log();
+  console.log(`已为以下编辑器生成配置: ${selectedNames}`);
+  console.log();
+  console.log('已生成/覆盖:');
+  console.log('  🌐 openspec/specs/overview.md     # 全局架构约束（数据字典、接口规范）');
+  console.log('  📄 openspec-templates/           # 标准文档模版（参考用）');
+  console.log('  🎯 .*/skills/opsx-*/              # SDD skills（扁平一层）');
+  if (selectedTools.includes('claude')) {
+    console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
+  }
+  console.log('  📊 skywalk-sdd/                  # SDD Telemetry 数据目录');
+  console.log('  🧰 skywalk-sdd/git-hooks/        # Git hooks 质量门禁模板');
+  console.log('  🧪 skywalk-sdd/ci/               # CI 兜底采集模板');
+  console.log();
+  
+  // 统一的 skill 格式说明
+  console.log('可用 skills（opsx-* 系列，10 个 SDD skills）:');
+  console.log('  opsx-propose   - 创建业务意图文档（Why）');
+  console.log('  opsx-spec      - 创建技术契约文档（What）');
+  console.log('  opsx-design    - 创建技术实现方案（How）');
+  console.log('  opsx-task      - 拆解AI编码任务（Do）');
+  console.log('  opsx-check     - 质量门禁检查（Verify）');
+  console.log('  opsx-apply     - 申请变更实施（Apply）');
+  console.log('  opsx-test      - 执行单元测试（Test）');
+  console.log('  opsx-archive   - 归档变更（Archive）');
+  console.log('  opsx-explore   - 浏览变更状态（Explore）');
+  console.log('  opsx-knowledge - 业务知识库检索（辅助）');
+    
+  console.log();
+  console.log('后续步骤:');
+  console.log('  1. 激活 opsx-propose skill，输入变更名称开始创建文档');
+  console.log('  2. 按顺序执行 propose → spec → design → task');
+  console.log('  3. 激活 opsx-check 验证文档质量');
+  console.log('  4. 激活 opsx-apply 申请实施，opsx-archive 归档完成');
+  console.log();
+  console.log('📊 SDD Telemetry（嵌入在 skill 流程中，自动执行，无需配置）：');
+  console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
+  console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=. 查看四维度指标');
+  console.log();
+
+  rl.close();
+}
+
+module.exports = { main, detectTools, getTemplatePath, selectEditor };