sillyspec 3.20.3 → 3.20.5

package/src/init.js

@@ -1,375 +1,470 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync } from 'fs';
-import { join, resolve, dirname, basename } from 'path';
-import { fileURLToPath } from 'url';
-import { homedir } from 'os';
-import { checkbox, confirm, input } from '@inquirer/prompts';
-import { ProgressManager } from './progress.js';
-import chalk from 'chalk';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// ── 递归复制目录 ──
-function copyDirSync(src, dst) {
-  mkdirSync(dst, { recursive: true });
-  for (const entry of readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    const srcPath = join(src, entry.name);
-    const dstPath = join(dst, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, dstPath);
-    } else if (entry.name.endsWith('.md')) {
-      writeFileSync(dstPath, readFileSync(srcPath));
-    }
-  }
-}
-
-// ── 元数据映射 ──
-
-
-
-const VALID_TOOLS = ['claude', 'claude_skills', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
-
-const TOOL_LABELS = {
-  claude: 'Claude Code',
-  claude_skills: 'Claude Skills',
-  cursor: 'Cursor',
-  openclaw: 'OpenClaw',
-  codex: 'OpenAI Codex (通过 AGENTS.md)',
-  gemini: 'Gemini CLI (通过 GEMINI.md)',
-  opencode: 'OpenCode (通过 INSTRUCTIONS.md)',
-};
-
-const INSTRUCTION_TOOLS = ['codex', 'gemini', 'opencode'];
-
-const INSTRUCTION_FILE_MAP = {
-  codex: 'AGENTS.md',
-  gemini: 'GEMINI.md',
-  opencode: 'INSTRUCTIONS.md',
-};
-
-const INJECTION_CONTENT = `## SillySpec — 规范驱动开发
-
-在执行开发任务时，遵循以下规范：
-
-### 代码规范
-- 写代码前先读取 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`（代码风格）和 \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`（架构）
-- 调用已有方法前，用 grep 确认方法存在，不许编造
-- 遵循 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\` 中的代码风格
-
-### 工作流程
-- 读取 \`.sillyspec/.runtime/progress.json\` 确认当前阶段（使用 \`sillyspec progress show\`）
-- 各阶段产出文件位于 \`.sillyspec/changes/<变更名>/\` 下
-`;
-
-// ── 注入指令文件 ──
-
-function injectInstructions(tool, projectDir) {
-  const fileName = INSTRUCTION_FILE_MAP[tool];
-  if (!fileName) return;
-  const filePath = join(projectDir, fileName);
-
-  // 文件不存在则创建
-  if (!existsSync(filePath)) {
-    writeFileSync(filePath, INJECTION_CONTENT);
-    return;
-  }
-
-  // 已存在 SillySpec 标记则跳过
-  const content = readFileSync(filePath, 'utf8');
-  if (content.includes('## SillySpec')) return;
-
-  // 追加到末尾
-  writeFileSync(filePath, content.trimEnd() + '\n\n' + INJECTION_CONTENT);
-}
-
-// ── 检测工具 ──
-
-function detectTools(projectDir) {
-  const found = [];
-  if (existsSync(join(projectDir, '.claude'))) found.push('claude');
-  if (existsSync(join(projectDir, '.claude', 'skills'))) found.push('claude_skills');
-  if (existsSync(join(projectDir, '.cursor'))) found.push('cursor');
-  if (existsSync(join(projectDir, '.openclaw'))) found.push('openclaw');
-  if (existsSync(join(projectDir, 'AGENTS.md'))) found.push('codex');
-  if (existsSync(join(projectDir, 'GEMINI.md'))) found.push('gemini');
-  if (existsSync(join(projectDir, 'INSTRUCTIONS.md'))) found.push('opencode');
-  if (found.length === 0) found.push('claude');
-  return found;
-}
-
-// ── TTY 工具函数 ──
-
-function isTTY() {
-  return process.stdin.isTTY && process.stdout.isTTY;
-}
-
-// ── 核心安装逻辑 ──
-
-async function doInstall(projectDir, tools, subprojects = []) {
-  // 创建基础目录
-  // .sillyspec/projects/    → 项目注册表
-  // .sillyspec/docs/<name>/ → 统一文档中心
-  // .sillyspec/knowledge/   → 跨项目共享知识库
-  // .sillyspec/.runtime/    → progress (gitignored)
-
-  // 注册当前项目到 projects/
-  const projectName = basename(projectDir) || 'project';
-  const projectsDir = join(projectDir, '.sillyspec', 'projects');
-  mkdirSync(projectsDir, { recursive: true });
-  const projectYamlPath = join(projectsDir, `${projectName}.yaml`);
-  if (!existsSync(projectYamlPath)) {
-    writeFileSync(projectYamlPath, `name: ${projectName}\npath: .\nstatus: active\n`);
-  }
-
-  // 创建 docs/<projectName>/scan/ 子目录（代码扫描结果）
-  const scanDir = join(projectDir, '.sillyspec', 'docs', projectName, 'scan');
-  mkdirSync(scanDir, { recursive: true });
-  const gitkeepPath = join(scanDir, '.gitkeep');
-  if (!existsSync(gitkeepPath)) writeFileSync(gitkeepPath, '');
-
-  // 创建 shared/workspace 目录
-  mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
-  mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });
-
-  // 创建知识库骨架
-  const knowledgeDir = join(projectDir, '.sillyspec', 'knowledge');
-  mkdirSync(knowledgeDir, { recursive: true });
-  const indexPath = join(knowledgeDir, 'INDEX.md');
-  if (!existsSync(indexPath)) {
-    writeFileSync(indexPath, `# Knowledge Index\n\n> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。\n> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。\n\n<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->\n<!-- 示例：mybatis-plus|分页|Page → pagination.md -->\n<!-- 示例：跨域|CORS|preflight → cors.md -->\n`);
-  }
-  const uncatPath = join(knowledgeDir, 'uncategorized.md');
-  if (!existsSync(uncatPath)) {
-    writeFileSync(uncatPath, `# 未分类知识\n\n> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。\n`);
-  }
-
-  // 创建 .sillyspec/.runtime/ 目录结构
-  const runtimeDir = join(projectDir, '.sillyspec', '.runtime');
-  for (const sub of ['artifacts', 'history', 'logs', 'templates']) {
-    mkdirSync(join(runtimeDir, sub), { recursive: true });
-  }
-
-  // 创建初始 progress.json
-  const progressPath = join(runtimeDir, 'progress.json');
-  if (!existsSync(progressPath)) {
-    const pm = new ProgressManager();
-    pm.init(projectDir);
-  }
-
-  // 创建初始 user-inputs.md
-  const inputsPath = join(runtimeDir, 'user-inputs.md');
-  if (!existsSync(inputsPath)) {
-    writeFileSync(inputsPath, '# 用户输入记录\n\n> 每步完成时由 AI 自动追加，记录用户所有原话。\n\n');
-  }
-
-  const gitignorePath = join(projectDir, '.gitignore');
-  const ignoreRules = ['.sillyspec/codebase/SCAN-RAW.md', '.sillyspec/local.yaml', '.sillyspec/.runtime/'];
-  if (existsSync(gitignorePath)) {
-    const content = readFileSync(gitignorePath, 'utf8');
-    let updated = content.trimEnd();
-    for (const rule of ignoreRules) {
-      if (!updated.includes(rule)) {
-        updated += '\n' + rule;
-      }
-    }
-    writeFileSync(gitignorePath, updated + '\n');
-  } else {
-    writeFileSync(gitignorePath, ignoreRules.join('\n') + '\n');
-  }
-
-  // 注入指令文件（codex/gemini/opencode）
-  for (let i = 0; i < tools.length; i++) {
-    const toolName = tools[i];
-    if (INSTRUCTION_TOOLS.includes(toolName)) {
-      injectInstructions(toolName, projectDir);
-    }
-  }
-
-  // 复制 skills 到 .claude/skills/（给 Claude Code 使用）
-  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
-  // 优先从 npm 包自带位置复制，其次从 ~/.agents/skills/
-  const npmSkillsDir = join(__dirname, '..', '.claude', 'skills');
-  const localSkillsDir = join(homedir(), '.agents', 'skills');
-  const skillsSource = existsSync(npmSkillsDir) ? npmSkillsDir : existsSync(localSkillsDir) ? localSkillsDir : null;
-  if (skillsSource) {
-    const sillyspecSkills = readdirSync(skillsSource).filter(f => f.startsWith('sillyspec-') && statSync(join(skillsSource, f)).isDirectory());
-    if (sillyspecSkills.length > 0) {
-      mkdirSync(claudeSkillsDir, { recursive: true });
-      for (const skill of sillyspecSkills) {
-        copyDirSync(join(skillsSource, skill), join(claudeSkillsDir, skill));
-      }
-      console.log(chalk.green('    ✓ Claude Code skills 已同步 (' + sillyspecSkills.length + ' 个)'));
-    }
-  } else {
-    console.log(chalk.yellow('    ⚠ 未找到 skills 目录，跳过 Claude Code skills 同步'));
-  }
-}
-
-// ── 安装完成总结 ──
-
-function showSummary(version, tools) {
-  const toolLabels = tools.map(t => TOOL_LABELS[t] || t);
-
-  console.log('');
-  console.log(chalk.green('  ═══════════════════════════════════════'));
-  console.log(chalk.green(`  ✅  SillySpec v${version} 安装完成！`));
-  console.log(chalk.green('  ═══════════════════════════════════════'));
-  console.log('');
-  console.log(`  已安装工具: ${chalk.cyan(toolLabels.join(', '))}`);
-  console.log('  📁 .sillyspec/ — 项目规范目录');
-  console.log('');
-  console.log('  下一步：使用 AI 技能开始工作');
-  console.log('    OpenClaw:    ' + chalk.bold('/sillyspec:brainstorm'));
-  console.log('    Claude Code: ' + chalk.bold('/sillyspec:brainstorm'));
-  console.log('');
-  console.log(chalk.dim('  💡 推荐安装 MCP 工具增强 AI 能力：sillyspec setup'));
-  console.log('');
-}
-
-// ── 读取版本号 ──
-
-export function getVersion() {
-  try {
-    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
-    return pkg.version;
-  } catch {
-    return '?.?.?';
-  }
-}
-
-// ── 主命令 ──
-
-export async function cmdInit(projectDir, options = {}) {
-  const { tool, interactive } = options;
-  const version = getVersion();
-
-  // ── 交互式模式（--interactive 或 -i）──
-  if (interactive && isTTY()) {
-    // 欢迎画面
-    console.log('');
-    console.log(chalk.cyan('🤪 SillySpec v' + version + ' — 规范驱动开发'));
-    console.log(chalk.cyan('  ===================================='));
-    console.log('');
-    console.log('  让 AI 像高级工程师一样工作：');
-    console.log('  先思考、先规划、先验证，再写代码。');
-    console.log('');
-    console.log(chalk.gray('  支持的 AI 工具：'));
-    console.log(chalk.gray('    Claude Code · Claude Skills · Cursor · Codex CLI · OpenCode · OpenClaw'));
-    console.log('');
-
-    // 工具多选
-    const detected = detectTools(projectDir);
-
-    const toolChoices = VALID_TOOLS.map(v => ({
-      name: `${TOOL_LABELS[v]}${v === 'claude' ? ' (推荐)' : ''}`,
-      value: v,
-      checked: detected.includes(v),
-    }));
-
-    const selectedTools = await checkbox({
-      message: '选择要安装的 AI 工具（空格选择，回车确认）',
-      choices: toolChoices,
-      validate: (answer) => answer.length > 0 || '至少选择一个工具',
-    });
-
-    // 子项目引导（始终执行）
-    let subprojects = [];
-    {
-      console.log('');
-      console.log(chalk.yellow('📋 添加子项目'));
-      console.log(chalk.dim('   子项目是工作区中的独立项目目录（如 frontend/、backend/）'));
-      console.log('');
-
-      const addMore = await confirm({ message: '现在添加子项目？', default: true });
-      if (addMore) {
-        let suggestions = [];
-        try {
-          const entries = readdirSync(projectDir, { withFileTypes: true });
-          suggestions = entries
-            .filter(e => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
-            .map(e => e.name)
-            .sort();
-        } catch {}
-
-        if (suggestions.length > 0) {
-          console.log('');
-          console.log(chalk.dim(`   检测到以下目录：${suggestions.join(', ')}`));
-          console.log('');
-        }
-
-        let adding = true;
-        while (adding) {
-          const name = await input({
-            message: '子项目名称（如 frontend，留空结束）',
-            default: suggestions.find(s => !subprojects.find(p => p.name === s)) || '',
-          });
-
-          if (!name.trim()) {
-            adding = false;
-            break;
-          }
-
-          const pathHint = suggestions.includes(name.trim()) ? `./${name.trim()}` : '';
-          const subPath = await input({
-            message: '子项目目录路径',
-            default: pathHint,
-          });
-
-          const role = await input({
-            message: '子项目描述（如 前端 - Vue3 + TypeScript）',
-            default: '',
-          });
-
-          let repo = '';
-          try {
-            const { execSync } = await import('child_process');
-            const absPath = resolve(projectDir, subPath.trim() || `./${name.trim()}`);
-            repo = execSync('git remote get-url origin', { cwd: absPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-          } catch {}
-
-          subprojects.push({ name: name.trim(), path: subPath.trim() || `./${name.trim()}`, role: role.trim(), repo });
-
-          const idx = suggestions.indexOf(name.trim());
-          if (idx >= 0) suggestions.splice(idx, 1);
-
-          const again = await confirm({ message: '继续添加子项目？', default: subprojects.length < suggestions.length });
-          if (!again) adding = false;
-        }
-      }
-    }
-
-    console.log('');
-    await doInstall(projectDir, selectedTools, subprojects);
-    showSummary(version, selectedTools);
-    return;
-  }
-
-  // ── 默认快速模式：检测 → 安装 → 结束 ──
-
-  let tools = [];
-  if (tool) {
-    if (!VALID_TOOLS.includes(tool)) {
-      console.error(`❌ 未知工具: ${tool}`);
-      console.error(`支持的工具: ${VALID_TOOLS.join(', ')}`);
-      process.exit(1);
-    }
-    tools = [tool];
-  } else {
-    tools = detectTools(projectDir);
-  }
-
-  await doInstall(projectDir, tools);
-
-  console.log('');
-  console.log(chalk.green(`  ✅ SillySpec v${version} 安装完成！`));
-  console.log('');
-  console.log('  📁 .sillyspec/ — 项目规范目录');
-  console.log('');
-  console.log('  下一步：使用 AI 技能开始工作');
-  console.log(`    OpenClaw:    ${chalk.bold('/sillyspec:brainstorm')}`);
-  console.log(`    Claude Code: ${chalk.bold('/sillyspec:brainstorm')}`);
-  console.log('');
-  console.log(chalk.dim('  💡 增强能力：sillyspec setup（安装 MCP 工具）'));
-  console.log('');
-}
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
+import { join, resolve, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { checkbox, confirm, input } from '@inquirer/prompts';
+import { ProgressManager } from './progress.js';
+import chalk from 'chalk';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ── .runtime/ 残留清理（平台模式防源码污染） ──
+// 平台模式（specRoot 指向外部）下，源码目录的 .sillyspec/.runtime/ 是旧残留，
+// 应让 specRoot 成为唯一运行时根。但若源码目录的 .sillyspec/ 本身就是该项目
+// 的 specDir（含真实资产），其 .runtime/ 里的 worktrees/、sillyspec.db、
+// global.json、gate-status.json 是真实工作状态，整删会摧毁 worktree meta、
+// 导致 depsStatus 恒为 unknown、branch already exists 死循环。
+// 详见 docs/sillyspec/runtime-cleanup-destroys-worktree-meta.md
+//
+// 策略：白名单保留权威状态，逐项删除可重建的缓存子项；未知子项默认保留（安全侧倾斜）。
+const RUNTIME_KEEP = new Set([
+  'worktrees',          // worktree 目录 + meta.json（worktree.js:17）
+  'sillyspec.db',       // SQLite 进度库（权威状态源，progress.js:7）
+  'global.json',        // 项目名/活跃变更缓存（progress.js:8）
+  'gate-status.json',   // worktree-guard 门禁状态（progress.js:9）
+  'contract-artifacts', // execute endpoint 契约（verify 阶段读取）
+  'execute-runs',       // task review 结果（task-review.js）
+]);
+
+/**
+ * 清理 .sillyspec/ 下的运行时残留，保留权威状态。
+ * 同时清理 local.yaml、codebase/（这些非权威，整删安全）。
+ * @param {string} legacyDir - 源码目录的 .sillyspec/ 路径
+ */
+export function cleanupRuntimeResidue(legacyDir) {
+  // local.yaml、codebase/ 非权威，整删
+  for (const residue of ['local.yaml', 'codebase']) {
+    const p = join(legacyDir, residue);
+    if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+  }
+  // .runtime/ 逐项清理，白名单保留
+  const runtimeDir = join(legacyDir, '.runtime');
+  if (existsSync(runtimeDir)) {
+    let entries = [];
+    try { entries = readdirSync(runtimeDir, { withFileTypes: true }); } catch {}
+    for (const entry of entries) {
+      if (RUNTIME_KEEP.has(entry.name)) continue;
+      const p = join(runtimeDir, entry.name);
+      try { rmSync(p, { recursive: true, force: true }) } catch {}
+    }
+  }
+}
+
+// ── 递归复制目录 ──
+function copyDirSync(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const srcPath = join(src, entry.name);
+    const dstPath = join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, dstPath);
+    } else if (entry.name.endsWith('.md')) {
+      writeFileSync(dstPath, readFileSync(srcPath));
+    }
+  }
+}
+
+// ── 元数据映射 ──
+
+
+
+const VALID_TOOLS = ['claude', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
+
+const TOOL_LABELS = {
+  claude: 'Claude Code',
+  cursor: 'Cursor',
+  openclaw: 'OpenClaw',
+  codex: 'OpenAI Codex (通过 AGENTS.md)',
+  gemini: 'Gemini CLI (通过 GEMINI.md)',
+  opencode: 'OpenCode (通过 INSTRUCTIONS.md)',
+};
+
+const INSTRUCTION_TOOLS = ['codex', 'gemini', 'opencode'];
+
+const INSTRUCTION_FILE_MAP = {
+  codex: 'AGENTS.md',
+  gemini: 'GEMINI.md',
+  opencode: 'INSTRUCTIONS.md',
+};
+
+const INJECTION_CONTENT = `## SillySpec — 规范驱动开发
+
+在执行开发任务时，遵循以下规范：
+
+### 代码规范
+- 写代码前先读取 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`（代码风格）和 \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`（架构）
+- 调用已有方法前，用 grep 确认方法存在，不许编造
+- 遵循 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\` 中的代码风格
+
+### 工作流程
+- 读取 sillyspec.db 确认当前阶段（使用 \`sillyspec progress show\`）
+- 各阶段产出文件位于 \`.sillyspec/changes/<变更名>/\` 下
+`;
+
+// ── 注入指令文件 ──
+
+function injectInstructions(tool, projectDir) {
+  const fileName = INSTRUCTION_FILE_MAP[tool];
+  if (!fileName) return;
+  const filePath = join(projectDir, fileName);
+
+  // 文件不存在则创建
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, INJECTION_CONTENT);
+    return;
+  }
+
+  // 已存在 SillySpec 标记则跳过
+  const content = readFileSync(filePath, 'utf8');
+  if (content.includes('## SillySpec')) return;
+
+  // 追加到末尾
+  writeFileSync(filePath, content.trimEnd() + '\n\n' + INJECTION_CONTENT);
+}
+
+// ── 检测工具 ──
+
+function detectTools(projectDir) {
+  const found = [];
+  if (existsSync(join(projectDir, '.claude'))) found.push('claude');
+  if (existsSync(join(projectDir, '.cursor'))) found.push('cursor');
+  if (existsSync(join(projectDir, '.openclaw'))) found.push('openclaw');
+  if (existsSync(join(projectDir, 'AGENTS.md'))) found.push('codex');
+  if (existsSync(join(projectDir, 'GEMINI.md'))) found.push('gemini');
+  if (existsSync(join(projectDir, 'INSTRUCTIONS.md'))) found.push('opencode');
+  if (found.length === 0) found.push('claude');
+  return found;
+}
+
+// ── TTY 工具函数 ──
+
+function isTTY() {
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+// ── 核心安装逻辑 ──
+
+async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
+  // specDir: 规范目录（默认 projectDir/.sillyspec）
+  // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
+  const spec = specDir || join(projectDir, '.sillyspec');
+
+  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
+  // 或 sillyspec.db（进度库），说明该项目本身就用 SillySpec 管理，整体删除会丢资产。
+  // 此时只清运行时残留，拒绝整删；确无资产时才视为旧残留清理。
+  const legacyDir = join(projectDir, '.sillyspec');
+  if (specDir && existsSync(legacyDir)) {
+    let hasChanges = false;
+    try {
+      const changesDir = join(legacyDir, 'changes');
+      if (existsSync(changesDir)) hasChanges = readdirSync(changesDir).length > 0;
+    } catch {}
+    let hasProjects = false;
+    try {
+      const projectsDir = join(legacyDir, 'projects');
+      if (existsSync(projectsDir)) hasProjects = readdirSync(projectsDir).length > 0;
+    } catch {}
+    const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+    if (hasChanges || hasProjects || hasDb) {
+      // 真实资产存在：拒绝整体删除，仅清理运行时残留
+      console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
+      console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
+      console.error('   本次仅清理运行时残留（.runtime/ 缓存、local.yaml、codebase/），保留 worktrees 与进度状态。');
+      cleanupRuntimeResidue(legacyDir);
+    } else {
+      // 无真实资产：确属旧版本残留，安全删除
+      try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
+      else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    }
+  }
+
+  // 创建基础目录
+  // spec/projects/    → 项目注册表
+  // spec/docs/<name>/ → 统一文档中心
+  // spec/knowledge/   → 跨项目共享知识库
+  // spec/.runtime/    → progress (gitignored)
+
+  // 注册当前项目到 projects/
+  const projectName = basename(projectDir) || 'project';
+  const projectsDir = join(spec, 'projects');
+  mkdirSync(projectsDir, { recursive: true });
+  const projectYamlPath = join(projectsDir, `${projectName}.yaml`);
+  if (!existsSync(projectYamlPath)) {
+    // path 相对于 specDir，跨平台可寻址
+    writeFileSync(projectYamlPath, `name: ${projectName}\npath: ${projectDir}\nstatus: active\n`);
+  }
+
+  // 创建 docs/<projectName>/scan/ 子目录（代码扫描结果）
+  const scanDir = join(spec, 'docs', projectName, 'scan');
+  mkdirSync(scanDir, { recursive: true });
+  const gitkeepPath = join(scanDir, '.gitkeep');
+  if (!existsSync(gitkeepPath)) writeFileSync(gitkeepPath, '');
+
+  // 复制 workflow 模板到 workflows/
+  const workflowsDir = join(spec, 'workflows');
+  const templatesDir = join(__dirname, '..', 'templates', 'workflows');
+  if (existsSync(templatesDir)) {
+    mkdirSync(workflowsDir, { recursive: true });
+    for (const file of readdirSync(templatesDir)) {
+      if (file.endsWith('.yaml')) {
+        const srcPath = join(templatesDir, file);
+        const dstPath = join(workflowsDir, file);
+        if (!existsSync(dstPath)) {
+          writeFileSync(dstPath, readFileSync(srcPath));
+        }
+      }
+    }
+  }
+
+  // 创建 shared/workspace 目录
+  mkdirSync(join(spec, 'shared'), { recursive: true });
+  mkdirSync(join(spec, 'workspace'), { recursive: true });
+
+  // 创建知识库骨架
+  const knowledgeDir = join(spec, 'knowledge');
+  mkdirSync(knowledgeDir, { recursive: true });
+  const indexPath = join(knowledgeDir, 'INDEX.md');
+  if (!existsSync(indexPath)) {
+    writeFileSync(indexPath, `# Knowledge Index\n\n> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。\n> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。\n\n<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->\n<!-- 示例：mybatis-plus|分页|Page → pagination.md -->\n<!-- 示例：跨域|CORS|preflight → cors.md -->\n`);
+  }
+  const uncatPath = join(knowledgeDir, 'uncategorized.md');
+  if (!existsSync(uncatPath)) {
+    writeFileSync(uncatPath, `# 未分类知识\n\n> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。\n`);
+  }
+
+  // 创建 .runtime/ 目录结构（全局状态）
+  const runtimeDir = join(spec, '.runtime');
+  for (const sub of ['artifacts', 'history', 'logs', 'templates']) {
+    mkdirSync(join(runtimeDir, sub), { recursive: true });
+  }
+
+  // 初始化 SQLite 数据库
+  const pm = new ProgressManager({ specDir: spec });
+  await pm.init(projectDir);
+
+  // .gitignore 只在 specDir 在项目内时才修改
+  const isExternalSpec = specDir && resolve(spec) !== resolve(projectDir, '.sillyspec');
+ if (!isExternalSpec) {
+    const gitignorePath = join(projectDir, '.gitignore');
+    const ignoreRules = ['.sillyspec/codebase/SCAN-RAW.md', '.sillyspec/local.yaml', '.sillyspec/.runtime/'];
+    if (existsSync(gitignorePath)) {
+      const content = readFileSync(gitignorePath, 'utf8');
+      let updated = content.trimEnd();
+      for (const rule of ignoreRules) {
+        if (!updated.includes(rule)) {
+          updated += '\n' + rule;
+        }
+      }
+      writeFileSync(gitignorePath, updated + '\n');
+    } else {
+      writeFileSync(gitignorePath, ignoreRules.join('\n') + '\n');
+    }
+  }
+
+  // 注入指令文件（codex/gemini/opencode）
+  for (let i = 0; i < tools.length; i++) {
+    const toolName = tools[i];
+    if (INSTRUCTION_TOOLS.includes(toolName)) {
+      injectInstructions(toolName, projectDir);
+    }
+  }
+
+  // 复制 skills 到各工具目录
+  const skillToolDirs = {
+    claude: '.claude/skills',
+    codex: '.codex/skills',
+    openclaw: '.openclaw/skills',
+    opencode: '.opencode/skills',
+  }
+  const skillsSource = join(__dirname, '..', '.claude', 'skills');
+  if (existsSync(skillsSource)) {
+    const sillyspecSkills = readdirSync(skillsSource).filter(f => f.startsWith('sillyspec-') && statSync(join(skillsSource, f)).isDirectory());
+    if (sillyspecSkills.length > 0) {
+      for (const [tool, dir] of Object.entries(skillToolDirs)) {
+        if (!tools.includes(tool)) continue
+        const targetDir = join(projectDir, dir)
+        mkdirSync(targetDir, { recursive: true })
+        for (const skill of sillyspecSkills) {
+          copyDirSync(join(skillsSource, skill), join(targetDir, skill))
+        }
+        console.log(chalk.green(`    ✓ ${TOOL_LABELS[tool]} skills 已同步 (${sillyspecSkills.length} 个)`))
+      }
+    }
+  } else {
+    console.log(chalk.yellow('    ⚠ 未找到 skills 目录（npm 包内无 .claude/skills/），跳过同步'));
+  }
+}
+
+// ── 安装完成总结 ──
+
+function showSummary(version, tools, specDir) {
+  const toolLabels = tools.map(t => TOOL_LABELS[t] || t);
+
+  console.log('');
+  console.log(chalk.green('  ═══════════════════════════════════════'));
+  console.log(chalk.green(`  ✅  SillySpec v${version} 安装完成！`));
+  console.log(chalk.green('  ═══════════════════════════════════════'));
+  console.log('');
+  console.log(`  已安装工具: ${chalk.cyan(toolLabels.join(', '))}`);
+  console.log(`  📁 规范目录: ${chalk.cyan(specDir || '.sillyspec')}`);
+  console.log('');
+  console.log('  下一步：使用 AI 技能开始工作');
+  console.log('    OpenClaw:    ' + chalk.bold('/sillyspec:brainstorm'));
+  console.log('    Claude Code: ' + chalk.bold('/sillyspec:brainstorm'));
+  console.log('');
+  console.log(chalk.dim('  💡 推荐安装 MCP 工具增强 AI 能力：sillyspec setup'));
+  console.log('');
+}
+
+// ── 读取版本号 ──
+
+export function getVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+  } catch {
+    return '?.?.?';
+  }
+}
+
+// ── 主命令 ──
+
+export async function cmdInit(projectDir, options = {}) {
+  const { tool, interactive, specDir } = options;
+  const version = getVersion();
+  const resolvedSpecDir = specDir ? resolve(specDir) : null;
+
+  // ── 交互式模式（--interactive 或 -i）──
+  if (interactive && isTTY()) {
+    // 欢迎画面
+    console.log('');
+    console.log(chalk.cyan('🤪 SillySpec v' + version + ' — 规范驱动开发'));
+    console.log(chalk.cyan('  ===================================='));
+    console.log('');
+    console.log('  让 AI 像高级工程师一样工作：');
+    console.log('  先思考、先规划、先验证，再写代码。');
+    console.log('');
+    console.log(chalk.gray('  支持的 AI 工具：'));
+    console.log(chalk.gray('    Claude Code · Claude Skills · Cursor · Codex CLI · OpenCode · OpenClaw'));
+    console.log('');
+
+    // 工具多选
+    const detected = detectTools(projectDir);
+
+    const toolChoices = VALID_TOOLS.map(v => ({
+      name: `${TOOL_LABELS[v]}${v === 'claude' ? ' (推荐)' : ''}`,
+      value: v,
+      checked: detected.includes(v),
+    }));
+
+    const selectedTools = await checkbox({
+      message: '选择要安装的 AI 工具（空格选择，回车确认）',
+      choices: toolChoices,
+      validate: (answer) => answer.length > 0 || '至少选择一个工具',
+    });
+
+    // 子项目引导（仅交互模式）
+    let subprojects = [];
+    {
+      console.log('');
+      console.log(chalk.yellow('📋 添加子项目'));
+      console.log(chalk.dim('   子项目是工作区中的独立项目目录（如 frontend/、backend/）'));
+      console.log('');
+
+      const addMore = await confirm({ message: '现在添加子项目？', default: true });
+      if (addMore) {
+        let suggestions = [];
+        try {
+          const entries = readdirSync(projectDir, { withFileTypes: true });
+          suggestions = entries
+            .filter(e => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+            .map(e => e.name)
+            .sort();
+        } catch {}
+
+        if (suggestions.length > 0) {
+          console.log('');
+          console.log(chalk.dim(`   检测到以下目录：${suggestions.join(', ')}`));
+          console.log('');
+        }
+
+        let adding = true;
+        while (adding) {
+          const name = await input({
+            message: '子项目名称（如 frontend，留空结束）',
+            default: suggestions.find(s => !subprojects.find(p => p.name === s)) || '',
+          });
+
+          if (!name.trim()) {
+            adding = false;
+            break;
+          }
+
+          const pathHint = suggestions.includes(name.trim()) ? `./${name.trim()}` : '';
+          const subPath = await input({
+            message: '子项目目录路径',
+            default: pathHint,
+          });
+
+          const role = await input({
+            message: '子项目描述（如 前端 - Vue3 + TypeScript）',
+            default: '',
+          });
+
+          let repo = '';
+          try {
+            const { execSync } = await import('child_process');
+            const absPath = resolve(projectDir, subPath.trim() || `./${name.trim()}`);
+            repo = execSync('git remote get-url origin', { cwd: absPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+          } catch {}
+
+          subprojects.push({ name: name.trim(), path: subPath.trim() || `./${name.trim()}`, role: role.trim(), repo });
+
+          const idx = suggestions.indexOf(name.trim());
+          if (idx >= 0) suggestions.splice(idx, 1);
+
+          const again = await confirm({ message: '继续添加子项目？', default: subprojects.length < suggestions.length });
+          if (!again) adding = false;
+        }
+      }
+    }
+
+    console.log('');
+    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir);
+    showSummary(version, selectedTools, resolvedSpecDir);
+    return;
+  }
+
+  // ── 默认快速模式：检测 → 安装 → 结束 ──
+
+  let tools = [];
+  if (tool) {
+    if (!VALID_TOOLS.includes(tool)) {
+      console.error(`❌ 未知工具: ${tool}`);
+      console.error(`支持的工具: ${VALID_TOOLS.join(', ')}`);
+      process.exit(1);
+    }
+    tools = [tool];
+  } else {
+    tools = detectTools(projectDir);
+  }
+
+  await doInstall(projectDir, tools, [], resolvedSpecDir);
+
+  console.log('');
+  console.log(chalk.green(`  ✅ SillySpec v${version} 安装完成！`));
+  console.log('');
+  const specDisplay = resolvedSpecDir || '.sillyspec';
+  console.log(`  📁 规范目录: ${chalk.cyan(specDisplay)}`);
+  console.log('');
+  console.log('  下一步：使用 AI 技能开始工作');
+  console.log(`    OpenClaw:    ${chalk.bold('/sillyspec:brainstorm')}`);
+  console.log(`    Claude Code: ${chalk.bold('/sillyspec:brainstorm')}`);
+  console.log('');
+  console.log(chalk.dim('  💡 增强能力：sillyspec setup（安装 MCP 工具）'));
+  console.log('');
+}