kld-sdd 2.4.7

package/lib/init.js

@@ -0,0 +1,906 @@
+/**
+ * KLD SDD 初始化核心逻辑
+ *
+ * 功能：
+ * 1. 检测并自动安装 openspec
+ * 2. 执行 openspec init 生成基础结构
+ * 3. 覆盖 opsx 命令（9个独立命令）
+ * 4. 部署 opsx skills
+ * 5. 复制标准文档模版到项目
+ * 6. 更新 .gitignore
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const readline = require('readline');
+const os = require('os');
+
+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'
+  },
+  claude: {
+    name: 'Claude Code',
+    configDir: '.claude',
+    commandsDir: '.claude/commands',
+    opsxDir: '.claude/commands/opsx',
+    skillsDir: '.claude/skills'
+  },
+  codebuddy: {
+    name: 'CodeBuddy',
+    configDir: '.codebuddy',
+    commandsDir: '.codebuddy/commands',
+    opsxDir: '.codebuddy/commands/opsx',
+    skillsDir: '.codebuddy/skills'
+  },
+  qoder: {
+    name: 'Qoder',
+    configDir: '.qoder',
+    commandsDir: '.qoder/commands',
+    opsxDir: '.qoder/commands/opsx',
+    skillsDir: '.qoder/skills'
+  },
+  opencode: {
+    name: 'OpenCode',
+    configDir: '.opencode',
+    commandsDir: '.opencode/commands',
+    opsxDir: '.opencode/commands/opsx',
+    skillsDir: '.opencode/skills',
+    // opencode 原生命令使用 command/（单数），需要额外清理
+    nativeCommandDir: '.opencode/command'
+  },
+  kunlunzhima: {
+    name: 'KunlunZhima',
+    configDir: '.kunlunzhima',
+    commandsDir: '.kunlunzhima/commands',
+    opsxDir: '.kunlunzhima/commands/opsx',
+    skillsDir: '.kunlunzhima/skills'
+  },
+  workbuddy: {
+    name: 'WorkBuddy',
+    configDir: '.workbuddy',
+    commandsDir: '.workbuddy/commands',
+    opsxDir: '.workbuddy/commands/opsx',
+    skillsDir: '.workbuddy/skills'
+  },
+  codex: {
+    name: 'Codex',
+    configDir: '.agents',
+    commandsDir: '.agents/commands',
+    opsxDir: '.agents/commands/opsx',
+    skillsDir: '.agents/skills'
+  }
+};
+
+/**
+ * 询问用户选择
+ */
+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. 全部（为所有编辑器生成命令）');
+    
+    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);
+    }
+  }
+}
+
+/**
+ * 清理原生 openspec 命令（opsx-*.md），避免与 opsx:* 命令混淆
+ * 同时清理 openspec 遗留的 JSON 文件
+ * 
+ * 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 命令（避免与 opsx:* 命令混淆）...');
+
+  const cwd = process.cwd();
+  // 原生 openspec 根目录命令文件（使用连字符，与 opsx:* 冒号命令混淆）
+  const nativeCmds = ['opsx-propose.md', 'opsx-apply.md', 'opsx-archive.md', 'opsx-explore.md'];
+
+  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 和其他工具都可能有）
+      let deletedCmds = 0;
+      for (const cmd of nativeCmds) {
+        const filePath = path.join(commandsDir, cmd);
+        if (fs.existsSync(filePath)) {
+          fs.unlinkSync(filePath);
+          deletedCmds++;
+        }
+      }
+      if (deletedCmds > 0) {
+        console.log(`   ✓ ${config.name}: 删除 ${deletedCmds} 个原生 opsx-* 命令（commands/）`);
+      }
+
+      // 删除 commands/opsx/ 子目录下的原生命令（Claude/CodeBuddy/Qoder）
+      const opsxDir = path.join(commandsDir, 'opsx');
+      if (fs.existsSync(opsxDir)) {
+        const opsxFiles = fs.readdirSync(opsxDir);
+        let deletedOpsxCmds = 0;
+        // 只删除原生的 4 个命令，保留其他可能存在的文件
+        const nativeOpsxCmds = ['propose.md', 'apply.md', 'archive.md', 'explore.md'];
+        for (const file of nativeOpsxCmds) {
+          const filePath = path.join(opsxDir, file);
+          if (fs.existsSync(filePath)) {
+            // 检查是否是原生命令（不含 YAML frontmatter 中的 SDD 标记）
+            const content = fs.readFileSync(filePath, 'utf-8');
+            if (!content.includes('# SDD') && !content.includes('OPSX:')) {
+              fs.unlinkSync(filePath);
+              deletedOpsxCmds++;
+            }
+          }
+        }
+        if (deletedOpsxCmds > 0) {
+          console.log(`   ✓ ${config.name}: 删除 ${deletedOpsxCmds} 个原生命令（commands/opsx/）`);
+        }
+      }
+    }
+
+    // 处理 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;
+}
+
+/**
+ * 覆盖 opsx 命令（9 个 SDD 工作流命令）
+ * 所有编辑器统一使用 templates/opsx-commands/ 下的 SDD 命令模板
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function overrideOpsxCommands(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🔧 正在覆盖 opsx 命令...');
+  
+  const pkgPath = getPackagePath();
+  const cwd = process.cwd();
+  
+  // 统一使用 opsx-commands 模板（9 个 SDD 命令，log 为内部自动触发）
+  const sddCommands = ['propose.md', 'spec.md', 'design.md', 'task.md', 'check.md', 'apply.md', 'test.md', 'archive.md', 'explore.md'];
+  const templatePath = path.join(pkgPath, 'templates', 'opsx-commands');
+  
+  if (!fs.existsSync(templatePath)) {
+    console.log(`⚠️  SDD 命令模板目录不存在: ${templatePath}`);
+    return false;
+  }
+  
+  // 为用户选择的每个编辑器部署命令
+  for (const toolKey of selectedTools) {
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config) continue;
+    
+    const configDir = path.join(cwd, config.configDir);
+    const targetOpsxDir = path.join(cwd, config.opsxDir);
+    
+    // 自动创建配置目录
+    if (!fs.existsSync(configDir)) {
+      console.log(`   自动创建 ${config.name} 配置目录...`);
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    
+    // 确保 opsx 命令目录存在
+    if (!fs.existsSync(targetOpsxDir)) {
+      fs.mkdirSync(targetOpsxDir, { recursive: true });
+    }
+    
+    console.log(`   覆盖 ${config.name} 的 opsx 命令（9 个 SDD 命令）...`);
+    
+    // 复制所有 SDD 命令到 opsx 目录
+    for (const cmd of sddCommands) {
+      const sourceFile = path.join(templatePath, cmd);
+      const targetFile = path.join(targetOpsxDir, cmd);
+      
+      if (fs.existsSync(sourceFile)) {
+        fs.copyFileSync(sourceFile, targetFile);
+        console.log(`     ✓ ${cmd}`);
+      }
+    }
+  }
+  
+  console.log('✅ opsx 命令覆盖完成');
+  return true;
+}
+
+/**
+ * 部署 SDD opsx skills（9 个技能文件）
+ * 从 templates/skills/ 目录复制到各编辑器的 skills 目录
+ * @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');
+  
+  if (!fs.existsSync(skillsTemplatePath)) {
+    console.log(`⚠️  SDD skills 模板目录不存在: ${skillsTemplatePath}`);
+    return false;
+  }
+  
+  // 获取所有 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} 个）...`);
+    
+    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 });
+      }
+      
+      const skillFile = path.join(sourceDir, 'SKILL.md');
+      if (fs.existsSync(skillFile)) {
+        fs.copyFileSync(skillFile, path.join(targetDir, 'SKILL.md'));
+        console.log(`     ✓ ${skillDir}`);
+      }
+    }
+  }
+  
+  console.log('✅ 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 数据目录
+ * 创建本地数据目录用于存储事件和报告
+ */
+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 });
+  }
+
+  // 创建本地数据目录（事件和报告存储）
+  const eventsDir = path.join(dataDir, 'events');
+  const reportsDir = path.join(dataDir, 'reports');
+  if (!fs.existsSync(eventsDir)) {
+    fs.mkdirSync(eventsDir, { recursive: true });
+    console.log('   ✓ 创建 skywalk-sdd/events/ 数据目录');
+  }
+  if (!fs.existsSync(reportsDir)) {
+    fs.mkdirSync(reportsDir, { recursive: true });
+    console.log('   ✓ 创建 skywalk-sdd/reports/ 报告目录');
+  }
+
+  // 部署项目内 Telemetry CLI（不依赖 npm 发布）
+  const telemetrySrc = path.join(pkgPath, 'skywalk-sdd', 'index.js');
+  const telemetryDst = path.join(dataDir, 'log.js');
+  if (fs.existsSync(telemetrySrc)) {
+    fs.copyFileSync(telemetrySrc, telemetryDst);
+    console.log('   ✓ 部署 skywalk-sdd/log.js（本地 Telemetry CLI）');
+  } else {
+    console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
+  }
+
+  console.log('   ✓ 调用方式: node skywalk-sdd/log.js start|end|metrics');
+  console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
+  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/reports/'
+  ];
+
+  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 数据（本地度量，可选提交）
+skywalk-sdd/events/
+skywalk-sdd/reports/
+`;
+
+  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，直接部署命令
+  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. 部署 SDD opsx 命令（根据编辑器类型使用不同模板）
+    overrideOpsxCommands(selectedTools);
+
+    // 4. 部署 SDD opsx skills
+    deployOpsxSkills(selectedTools);
+    
+    // 4.1 清理原生 openspec-* skills（防止残留）
+    cleanupNativeOpenspecSkills(selectedTools);
+
+    // 5. 部署 SDD Telemetry 数据目录
+    deployTelemetryDataDir();
+
+    // 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('  🔧 .*/commands/opsx/             # 9 个 SDD 命令');
+  console.log('  📊 skywalk-sdd/                  # SDD Telemetry 数据目录');
+  console.log();
+  
+  // 统一的命令格式说明
+  console.log('可用命令（/opsx:* 系列，9 个 SDD 命令）:');;
+  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();
+  console.log('后续步骤:');
+  console.log('  1. 运行 /opsx:propose <变更名称> 开始创建文档');
+  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（嵌入在命令流程中，自动执行，无需配置）：');
+  console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
+  console.log('  - 运行 node skywalk-sdd/log.js metrics --project=. 查看四维度指标');
+  console.log();
+
+  rl.close();
+}
+
+module.exports = { main, detectTools, getTemplatePath, selectEditor };