@jspg-ai/coding-bb 0.0.1

package/cbb/lib/install/init.js

@@ -0,0 +1,1875 @@
+#!/usr/bin/env node
+
+/**
+ * OpenSpec Shared Standards 安装脚本
+ *
+ * 将AI 编码规范与工作流套件安装到目标项目中。
+ * 支持工具：Claude Code (.claude/rules/)、Qoder (.qoder/rules/)
+ *
+ * 使用方式：
+ *   npm install -g @jspg-ai/coding-bb  # 首次使用
+ *   npm install -g @jspg-ai/coding-bb
+ *   cd your-project && cbb init
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+const yaml = require('js-yaml');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+
+// 目标项目根目录：默认取当前 cwd，init() / initWorkspace() 可在调用前覆盖。
+// 注意：使用 let 而非 const 是为了让 cbb setup 能在拉好仓库后把目标目录
+// 切到仓库根，再复用 init() 的完整安装流程，而无需把 TARGET_DIR 透传到所有 helper。
+let TARGET_DIR = process.cwd();
+
+// 清单文件：记录本包管理的所有路径，用于区分本包文件和用户自建文件
+const MANIFEST_DIR = '.cbb';
+const MANIFEST_FILE = path.join(MANIFEST_DIR, '.managed-by-cbb');
+const LAST_TOOLS_FILE = path.join(MANIFEST_DIR, '.last-tools');
+
+// 适配器
+const adapters = [
+  require('./claude-code'),
+  require('./qoder'),
+];
+
+// superpowers 部署白名单：仅装 openspec 工作流硬依赖 + 方法论基底（源仓库仍保留全量 14 个，
+// 供 cbb update --upstream-superpowers 维护；砍掉的与 openspec 工作流重叠或属低频场景）
+const SUPERPOWERS_WHITELIST = [
+  'writing-plans',                  // openspec apply：生成 plan.md（schema.yaml 引用）
+  'subagent-driven-development',    // openspec apply：执行 plan.md（schema.yaml 引用）
+  'executing-plans',                // writing-plans 的无子代理 fallback 执行器
+  'finishing-a-development-branch', // subagent-driven-development 收尾
+  'requesting-code-review',         // openspec verify：MANDATORY 代码审查
+  'test-driven-development',        // TDD 计划结构 + TDD Evidence 方法论基底
+];
+
+// worktree 扩展 skills 部署到沙箱的白名单：init/extend 只在 workspace 根执行
+// （由 installWorkspaceConfig 部署），沙箱内只需 push（推送）与 close（关闭）
+const SANDBOX_WORKTREE_SKILLS = ['openspec-push-worktrees', 'openspec-close-worktree'];
+
+// 装到沙箱的 tools skills：cbb-wiki-ops 装用户级（与项目无关），Java 工具不装
+const SANDBOX_TOOLS_SKILLS = ['cbb-design-to-wiki'];
+
+// settings.json hook 工具
+const settingsManager = require('../utils/settings');
+
+// 清单驱动的文件清理决策（保护用户文档 CLAUDE.md / AGENTS.md 等）
+const { pathsToDelete, protectedKeptPaths } = require('./cleanup');
+
+// .gitignore 条目决策（纯函数：检测/写入/卸载移除）
+const gitignore = require('../utils/gitignore');
+
+// 业务空间配置（cbb setup 命令专用）
+const workspaces = require('./workspaces');
+
+// 业务空间选择 UI（cbb setup 命令专用，inquirer 风格 checkbox）
+const checkbox = require('../utils/checkbox');
+
+// 版本工具（cbb setup 升级确认 + check-update 共用）
+const version = require('../utils/version');
+
+// Superpowers skills 管理（内置集成 + cbb update --upstream-superpowers）
+const superpowers = require('../superpowers');
+
+// OpenSpec 工作流管理（内置集成 + cbb update --upstream-openspec）
+const openspec = require('../openspec');
+
+// ── 颜色与输出辅助 ──────────────────────────────────────
+
+const { COLOR, COLOR_ENABLED, c, log, section, field, LOG_STYLES } = require('../utils/output');
+
+// 检测是否已安装（清单文件存在即视为已安装）
+function detectExistingInstall() {
+  return fs.existsSync(path.join(TARGET_DIR, MANIFEST_FILE));
+}
+
+// ── 清单管理 ──────────────────────────────────────────────
+
+/** 读取清单，返回 Set<path> */
+function readManifest() {
+  const manifestPath = path.join(TARGET_DIR, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return new Set();
+  const data = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  return new Set(data.paths || []);
+}
+
+/** 写入清单 */
+function writeManifest(paths, selectedAdapters) {
+  const manifestDir = path.join(TARGET_DIR, MANIFEST_DIR);
+  fs.mkdirSync(manifestDir, { recursive: true });
+  const manifestPath = path.join(TARGET_DIR, MANIFEST_FILE);
+  const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+
+  // 读取现有清单，保留未选中适配器的版本
+  let existingAdapterVersions = {};
+  let existingGlobalVersion = null;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      if (existing.adapterVersions && typeof existing.adapterVersions === 'object') {
+        existingAdapterVersions = existing.adapterVersions;
+      }
+      existingGlobalVersion = existing.version || null;
+    } catch (_) { /* ignore parse errors */ }
+  }
+
+  // 首次迁移：旧清单无 adapterVersions 时，用旧全局 version 为未选中的适配器补齐
+  if (Object.keys(existingAdapterVersions).length === 0 && existingGlobalVersion) {
+    adapters.forEach(a => {
+      if (!selectedAdapters.some(sa => sa.name === a.name)) {
+        existingAdapterVersions[a.name] = existingGlobalVersion;
+      }
+    });
+  }
+
+  // 合并：选中的适配器写入新版本，未选中的保持不变
+  const adapterVersions = { ...existingAdapterVersions };
+  selectedAdapters.forEach(adapter => {
+    adapterVersions[adapter.name] = pkg.version;
+  });
+
+  const data = {
+    version: pkg.version,
+    adapterVersions,
+    paths: [...paths].sort()
+  };
+  fs.writeFileSync(manifestPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/** 读取上次选择的工具列表，返回 Set<adapterName> */
+function readLastTools() {
+  const filePath = path.join(TARGET_DIR, LAST_TOOLS_FILE);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    return new Set(data.tools || []);
+  } catch (_) {
+    return null;
+  }
+}
+
+/** 保存本次选择的工具列表 */
+function saveLastTools(selectedAdapters) {
+  const dirPath = path.join(TARGET_DIR, MANIFEST_DIR);
+  fs.mkdirSync(dirPath, { recursive: true });
+  const filePath = path.join(TARGET_DIR, LAST_TOOLS_FILE);
+  const data = { tools: selectedAdapters.map(a => a.name) };
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/** 删除文件或目录 */
+function removePath(targetPath) {
+  if (!fs.existsSync(targetPath)) return;
+  if (fs.statSync(targetPath).isDirectory()) {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  } else {
+    fs.unlinkSync(targetPath);
+  }
+}
+
+/**
+ * 安全删除目标路径（文件或目录）
+ * 在清单中 → 直接删除（本包旧版本）
+ * 不在清单中 → 先备份再删除（用户自建）
+ */
+function safeRemove(targetPath, managedPaths) {
+  if (!fs.existsSync(targetPath)) return;
+  const relativePath = path.relative(TARGET_DIR, targetPath).replace(/\\/g, '/');
+
+  if (managedPaths.has(relativePath)) {
+    // 本包旧版本 → 直接删除
+    removePath(targetPath);
+  } else {
+    // 用户自建 → 先备份
+    const backupPath = generateBackupPath(targetPath);
+    if (fs.statSync(targetPath).isDirectory()) {
+      fs.cpSync(targetPath, backupPath, { recursive: true });
+    } else {
+      fs.copyFileSync(targetPath, backupPath);
+    }
+    log(`备份 ${relativePath} → ${path.basename(backupPath)}`, 'success');
+    removePath(targetPath);
+  }
+}
+
+// ── 交互式选择工具 ─────────────────────────────────────────
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function selectTools(isUpgrade) {
+  const action = isUpgrade ? '升级' : '安装';
+
+  // 读取上次选择的工具：有记录则预选上次选择，首次安装则全部不选
+  const lastTools = readLastTools();
+  const preSelected = lastTools
+    ? adapters.map((a, i) => lastTools.has(a.name) ? i : -1).filter(i => i >= 0)
+    : [];
+
+  // checkbox 多选：
+  //   - 不切换 → 确认当前选择
+  //   - 取消某项 → 只装剩下的
+  //   - 全部不选 → 提示后回退全部
+  const selectedIdx = await checkbox.promptCheckbox({
+    header: `🔧  选择要${action}的 AI 工具（空格切换，回车确认）`,
+    items: adapters.map(a => ({
+      label: c('cyan', a.displayName),
+    })),
+    preSelected,
+  });
+
+  let result;
+  if (selectedIdx.size === 0) {
+    log(`未选择任何工具，默认全部${action}`, 'warn');
+    result = adapters;
+  } else {
+    // 转成有序适配器数组（按原始顺序）
+    result = [...selectedIdx]
+      .sort((a, b) => a - b)
+      .map(i => adapters[i]);
+  }
+
+  // 保存本次选择，供下次运行时预选
+  saveLastTools(result);
+  return result;
+}
+
+// ── 分发核心规则 ──────────────────────────────────────────────
+
+function deployCoreRules(adapter, isUpgrade, managedPaths) {
+  const rulesSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'dev-standards', 'rules');
+  const rulesDest = path.join(TARGET_DIR, adapter.rulesDir);
+  const action = isUpgrade ? '更新' : '安装';
+
+  const coreRules = ['cbb-coding-rule.md', 'cbb-priority.md', 'cbb-ai-behavior.md'];
+
+  // 确保目标目录存在
+  fs.mkdirSync(rulesDest, { recursive: true });
+
+  // 复制核心规则文件
+  coreRules.forEach(f => {
+    const srcPath = path.join(rulesSrc, f);
+    const destPath = path.join(rulesDest, f);
+    if (fs.existsSync(srcPath)) {
+      // 同名文件存在时直接覆盖
+      removePath(destPath);
+
+      fs.writeFileSync(destPath, fs.readFileSync(srcPath, 'utf-8'));
+    }
+  });
+
+}
+
+// ── YAML 配置合并 ─────────────────────────────────────────
+
+function mergeConfig(ourYaml, userYaml) {
+  const ours = yaml.load(ourYaml);
+  const user = yaml.load(userYaml) || {};
+
+  // schema: 本包覆盖
+  // context: 本包覆盖（单字符串字段）
+  // rules: 字段级合并，冲突以本包为准
+  const merged = { ...ours };
+  if (user.rules) {
+    merged.rules = {
+      ...user.rules,
+      ...ours.rules,
+    };
+  }
+
+  return yaml.dump(merged, { lineWidth: -1 });
+}
+
+// ── 备份文件命名 ──────────────────────────────────────────
+
+/**
+ * 生成备份文件路径
+ * 格式：config.yaml.YYYYMMDD_NN
+ * - 同一日期下序号递增
+ * - 序号超过 99 时覆盖最新的备份文件
+ * - 新日期从 01 开始
+ */
+function generateBackupPath(filePath) {
+  const dir = path.dirname(filePath);
+  const baseName = path.basename(filePath);
+  const today = new Date().toISOString().slice(0, 10).replace(/-/g, ''); // YYYYMMDD
+  const prefix = `${baseName}.${today}_`;
+
+  // 扫描目录，找出今天的备份文件
+  let maxSeq = 0;
+  if (fs.existsSync(dir)) {
+    const files = fs.readdirSync(dir);
+    const pattern = new RegExp(`^${prefix}(\\d{2})$`);
+    for (const f of files) {
+      const match = f.match(pattern);
+      if (match) {
+        const seq = parseInt(match[1], 10);
+        if (seq > maxSeq) maxSeq = seq;
+      }
+    }
+  }
+
+  // 计算下一个序号
+  let nextSeq = maxSeq + 1;
+  if (nextSeq > 99) {
+    // 超过 99 则覆盖最新的备份文件
+    nextSeq = 99;
+  }
+
+  const seqStr = String(nextSeq).padStart(2, '0');
+  return path.join(dir, `${prefix}${seqStr}`);
+}
+
+// ── 部署 Skills ──────────────────────────────────────────────
+
+function deploySkills(adapter, isUpgrade, managedPaths, srcDir, filter) {
+  const skillsDir = adapter.skillsDir;
+  if (!skillsDir || !fs.existsSync(srcDir)) return { count: 0, names: [] };
+
+  const skillsDest = path.join(TARGET_DIR, skillsDir);
+
+  // 不再删除整个目录，只处理同名的 skill 子目录
+  fs.mkdirSync(skillsDest, { recursive: true });
+
+  // 复制技能目录
+  const skillDirs = fs.readdirSync(srcDir)
+    .filter(f => fs.statSync(path.join(srcDir, f)).isDirectory())
+    .filter(f => !filter || filter.includes(f));
+
+  skillDirs.forEach(skillName => {
+    const destDir = path.join(skillsDest, skillName);
+    removePath(destDir);
+    fs.cpSync(path.join(srcDir, skillName), destDir, { recursive: true });
+  });
+
+  return { count: skillDirs.length, names: skillDirs };
+}
+
+// ── 部署 Commands ──────────────────────────────────────────────
+
+function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
+  const commandsDir = adapter.commandsDir;
+  if (!commandsDir || !fs.existsSync(srcDir)) return { count: 0, names: [] };
+
+  const commandsDest = path.join(TARGET_DIR, commandsDir);
+
+  fs.mkdirSync(commandsDest, { recursive: true });
+
+  // 读取所有 .md 文件（command 是扁平文件，不像 skill 是子目录）
+  const commandFiles = fs.readdirSync(srcDir)
+    .filter(f => f.endsWith('.md') && fs.statSync(path.join(srcDir, f)).isFile())
+    .filter(f => !filter || filter.includes(f));
+
+  commandFiles.forEach(f => {
+    const srcPath = path.join(srcDir, f);
+    const destPath = path.join(commandsDest, f);
+    removePath(destPath);
+    fs.copyFileSync(srcPath, destPath);
+  });
+
+  return { count: commandFiles.length, names: commandFiles };
+}
+
+// ── 设置 OpenSpec 工作流 ──────────────────────────────────
+
+function setupOpenSpec(isUpgrade, managedPaths) {
+  const schemasSrcs = [
+    path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
+  ];
+  const schemasDest = path.join(TARGET_DIR, 'openspec', 'schemas');
+
+  // 安装 schema：本包提供的直接覆盖，非本包的不动
+  // 收集所有源目录的 schema 名称
+  const ourSchemaNames = new Set();
+  schemasSrcs.forEach(src => {
+    if (fs.existsSync(src)) {
+      fs.readdirSync(src).filter(f => fs.statSync(path.join(src, f)).isDirectory())
+        .forEach(f => ourSchemaNames.add(f));
+    }
+  });
+
+  if (ourSchemaNames.size > 0) {
+    fs.mkdirSync(schemasDest, { recursive: true });
+
+    // 处理目标目录中已有的 schema
+    if (fs.existsSync(schemasDest)) {
+      const existingNames = fs.readdirSync(schemasDest)
+        .filter(f => fs.statSync(path.join(schemasDest, f)).isDirectory());
+
+      existingNames.forEach(name => {
+        const dest = path.join(schemasDest, name);
+        const relativePath = `openspec/schemas/${name}`;
+
+        if (ourSchemaNames.has(name)) {
+          // 本包 schema → 直接删除后覆盖（无论是否在清单中）
+          removePath(dest);
+        } else if (managedPaths.has(relativePath)) {
+          // 清单中有但本包不再提供 → 清理旧版本
+          removePath(dest);
+          log(`移除已废弃的 openspec/schemas/${name}/`, 'success');
+        }
+        // 非本包且不在清单中 → 不动（用户自建）
+      });
+    }
+
+    // 复制本包 schema（从所有源目录）
+    schemasSrcs.forEach(src => {
+      if (!fs.existsSync(src)) return;
+      fs.readdirSync(src).filter(f => fs.statSync(path.join(src, f)).isDirectory())
+        .forEach(name => {
+          const srcPath = path.join(src, name);
+          const dest = path.join(schemasDest, name);
+          fs.cpSync(srcPath, dest, { recursive: true });
+          log(`安装 openspec/schemas/${name}/`, 'success');
+        });
+    });
+  }
+
+  // 处理用户项目的 openspec/config.yaml
+  const configSrc = path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'config.yaml');
+  const configDest = path.join(TARGET_DIR, 'openspec', 'config.yaml');
+
+  if (!fs.existsSync(configSrc)) return;
+
+  fs.mkdirSync(path.dirname(configDest), { recursive: true });
+  const ourContent = fs.readFileSync(configSrc, 'utf-8');
+
+  if (fs.existsSync(configDest)) {
+    // 合并：rules 字段级合并，其余以本包为准
+    const userContent = fs.readFileSync(configDest, 'utf-8');
+    const merged = mergeConfig(ourContent, userContent);
+    fs.writeFileSync(configDest, merged);
+    log('合并 openspec/config.yaml', 'success');
+  } else {
+    fs.writeFileSync(configDest, ourContent);
+    log('创建 openspec/config.yaml', 'success');
+  }
+
+  // 输出已安装的 schema 和可用命令
+  if (fs.existsSync(schemasDest)) {
+    const defaultSchema = yaml.load(fs.readFileSync(configDest, 'utf-8')).schema;
+    const installedSchemas = fs.readdirSync(schemasDest).filter(name => {
+      return fs.statSync(path.join(schemasDest, name)).isDirectory();
+    });
+
+    log(`已安装工作流：${installedSchemas.join(', ')}（默认: ${defaultSchema}）`);
+  }
+}
+
+// ── .gitignore 管理 ───────────────────────────────────────
+
+function updateGitignore() {
+  const gitignorePath = path.join(TARGET_DIR, '.gitignore');
+
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  }
+
+  // 已含某目录（带/不带尾斜杠均认可）则跳过；新增无尾斜杠形式（.claude / .qoder）
+  const toAdd = gitignore.entriesToAdd(content);
+  if (toAdd.length === 0) return; // 全部已存在
+
+  // 新增条目用空行与现有内容分隔，另起一行开始
+  fs.writeFileSync(gitignorePath, gitignore.appendEntries(content, toAdd));
+  log(`添加 ${toAdd.join(', ')} 到 .gitignore`, 'success');
+}
+
+/** 从 .gitignore 中移除本包添加的条目（新旧版本写入的形式均覆盖） */
+function cleanupGitignore() {
+  const gitignorePath = path.join(TARGET_DIR, '.gitignore');
+
+  if (!fs.existsSync(gitignorePath)) return;
+
+  const content = fs.readFileSync(gitignorePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+  const filtered = gitignore.filterManaged(lines);
+
+  if (filtered.length === lines.length) return; // 无需变更
+
+  // 避免文件末尾堆积空行
+  const newContent = filtered.join('\n').replace(/\n{3,}/g, '\n\n');
+  fs.writeFileSync(gitignorePath, newContent.endsWith('\n') ? newContent : newContent + '\n');
+  log(`从 .gitignore 移除 ${gitignore.GITIGNORE_RULES.map(r => r.add).join(', ')}`, 'success');
+}
+
+// ── OpenSpec CLI 自动安装/升级 ──────────────────────────────
+
+const OPENSPEC_PKG = '@fission-ai/openspec';
+const OPENSPEC_REGISTRY = 'https://registry.npmmirror.com';
+
+/**
+ * 确保 OpenSpec CLI 已安装且为最新版本。
+ * 未安装或版本非最新时自动执行 npm install -g，无需用户确认。
+ */
+async function ensureOpenSpecCli() {
+  // 1. 获取当前版本（未安装时 currentVersion = null）
+  let currentVersion = null;
+  try {
+    currentVersion = execSync('openspec --version', { stdio: 'pipe', timeout: 10000 })
+      .toString().trim().replace(/^v/, '');
+  } catch (_) {}
+
+  // 2. 查询最新版本（网络失败则跳过检测，视为无法判断）
+  let latestVersion = null;
+  try {
+    latestVersion = execSync(
+      `npm view ${OPENSPEC_PKG} version --registry ${OPENSPEC_REGISTRY}`,
+      { stdio: 'pipe', timeout: 15000 }
+    ).toString().trim();
+  } catch (_) {}
+
+  // 3. 判断是否需要安装/升级
+  const needInstall = !currentVersion;
+  const needUpgrade = currentVersion && latestVersion
+    && version.compareVersions(latestVersion, currentVersion) > 0;
+
+  if (!needInstall && !needUpgrade) {
+    log(`OpenSpec CLI: v${currentVersion} (最新)`, 'success');
+    return;
+  }
+
+  // 4. 执行安装/升级
+  const action = needInstall ? '安装' : '升级';
+  const detail = needInstall
+    ? `→ v${latestVersion || 'latest'}`
+    : `v${currentVersion} → v${latestVersion}`;
+  log(`${action} OpenSpec CLI (${detail})...`, 'info');
+
+  try {
+    execSync(
+      `npm install -g ${OPENSPEC_PKG}@latest --registry ${OPENSPEC_REGISTRY}`,
+      { stdio: 'pipe', timeout: 120000 }
+    );
+    log(`OpenSpec CLI ${action}完成`, 'success');
+  } catch (err) {
+    log(`OpenSpec CLI ${action}失败: ${err.message}`, 'error');
+    log(`请手动执行: npm install -g ${OPENSPEC_PKG}@latest --registry ${OPENSPEC_REGISTRY}`, 'warn');
+  }
+}
+
+/**
+ * 检测用户级 superpowers 安装（插件或 npx skills add -g），
+ * 发现重复时交互确认是否卸载；-y 模式仅警告不自动操作。
+ */
+async function detectUserLevelSuperpowers(selectedAdapters, yes = false) {
+  const homeDir = os.homedir();
+  const conflicts = []; // { adapter, source, uninstallHint }
+  // 动态拼接所有技能名，避免使用集合名（npx skills remove 无法匹配集合实体）
+  const skillNames = superpowers.EXPECTED_SKILLS.join(' ');
+
+  for (const adapter of (selectedAdapters || [])) {
+    if (!adapter.skillsDir) continue;
+
+    // 检查 1: Claude Code 插件注册表（claude skills install superpowers）
+    if (adapter.name === 'claude-code') {
+      const pluginsFile = path.join(homeDir, '.claude', 'plugins', 'installed_plugins.json');
+      if (fs.existsSync(pluginsFile)) {
+        try {
+          const data = JSON.parse(fs.readFileSync(pluginsFile, 'utf-8'));
+          if (Object.keys(data.plugins || {}).some(n => n.startsWith('superpowers'))) {
+            conflicts.push({
+              adapter,
+              source: `~/.claude/plugins/ (插件注册)`,
+              uninstallHint: `npx skills remove ${skillNames} -g -y`,
+            });
+          }
+        } catch (_) { /* ignore */ }
+      }
+    }
+
+    // 检查 2: 用户级 skills 目录中的标志性 skill（取白名单中的技能名）
+    //   来源可能是 npx skills add obra/superpowers -g（Claude Code / Qoder 通用）
+    const markerSkills = SUPERPOWERS_WHITELIST.slice(0, 2);
+    const userSkillsDir = path.join(homeDir, adapter.skillsDir);
+    if (fs.existsSync(userSkillsDir)) {
+      for (const marker of markerSkills) {
+        const markerPath = path.join(userSkillsDir, marker);
+        try {
+          if (fs.existsSync(markerPath) && fs.statSync(markerPath).isDirectory()) {
+            // 避免与插件检测重复（同一适配器只报一次）
+            if (!conflicts.some(c => c.adapter.name === adapter.name)) {
+              conflicts.push({
+                adapter,
+                source: `${adapter.skillsDir}/ (npx skills add -g)`,
+                uninstallHint: `npx skills remove ${skillNames} -g -y`,
+              });
+            }
+            break;
+          }
+        } catch (_) { /* ignore */ }
+      }
+    }
+  }
+
+  if (conflicts.length === 0) return;
+
+  console.log('');
+  log('检测到用户级 superpowers 安装，会与项目级 skills 重复加载：', 'warn');
+  conflicts.forEach(c => {
+    log(`${c.adapter.displayName}: ${c.source}`, 'warn');
+  });
+
+  // -y 模式：仅警告，不操作用户环境
+  if (yes) {
+    log('--yes 模式下不自动操作用户环境，请手动卸载：', 'info');
+    conflicts.forEach(c => log(`${c.uninstallHint}`, 'info'));
+    return;
+  }
+
+  // 交互模式：询问是否卸载
+  console.log('');
+  console.log('  建议卸载用户级 superpowers，由本包统一管理，避免版本不一致和 skill 重复。');
+  const answer = await ask('是否现在卸载用户级 superpowers？(y/N): ');
+  if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+    log('已跳过，请稍后手动卸载：', 'info');
+    conflicts.forEach(c => log(`${c.uninstallHint}`, 'info'));
+    return;
+  }
+
+  // 执行卸载
+  for (const c of conflicts) {
+    log(`执行: ${c.uninstallHint}`, 'info');
+    try {
+      execSync(c.uninstallHint, { stdio: 'inherit', timeout: 30000 });
+      // 卸载后检查用户级 skills 目录是否还有残留
+      const userSkillsDir = path.join(os.homedir(), c.adapter.skillsDir);
+      const markerSkills = SUPERPOWERS_WHITELIST.slice(0, 2);
+      const remaining = markerSkills.filter(m => {
+        try { return fs.existsSync(path.join(userSkillsDir, m)); } catch (_) { return false; }
+      });
+      if (remaining.length > 0) {
+        log(`${c.adapter.displayName}: 卸载命令已执行，但仍有残留 skill 目录`, 'warn');
+        log(`请手动删除: ${userSkillsDir}`, 'info');
+      } else {
+        log(`${c.adapter.displayName} 用户级 superpowers 已卸载`, 'success');
+      }
+    } catch (err) {
+      log(`卸载命令执行失败: ${err.message}`, 'error');
+      log(`请手动执行: ${c.uninstallHint}`, 'warn');
+    }
+  }
+}
+
+// ── 主流程 ────────────────────────────────────────────────
+
+async function init(targetDir, options = {}) {
+  const { yes = false } = options;
+
+  // 允许调用方指定目标目录（cbb setup 在拉好仓库后切到仓库根调用）。
+  // 不传则保持模块级 TARGET_DIR（即调用 init 时的 cwd）。
+  if (targetDir) TARGET_DIR = targetDir;
+
+  // 检测是否已安装
+  const isUpgrade = detectExistingInstall();
+  const action = isUpgrade ? '升级' : '安装';
+  const managedPaths = readManifest();
+  const newPaths = new Set();
+
+  console.log(`\n  🚀 ${action} @jspg-ai/coding-bb...\n`);
+
+  // 先选适配器：后续的前置依赖检测仅针对所选适配器，避免误导（如选了 Qoder 却提示安装 Claude Code 的 Superpowers）
+  // 非交互模式判断：显式 -y/--yes 或 stdin 非 TTY（pipe/ignore）均视为非交互
+  const isNonInteractive = yes || !process.stdin.isTTY;
+  if (yes && process.stdin.isTTY) {
+    log('--yes 非交互模式，已默认选中所有适配器', 'info');
+  }
+  const selectedAdapters = isNonInteractive ? adapters : await selectTools(isUpgrade);
+
+  // 前置依赖检测（放在选适配器之后，只检测与所选工具相关的依赖）
+  await ensureOpenSpecCli();
+
+  // 分发核心规则到各工具目录
+  console.log(`\n  📦 ${action}核心编码规范...`);
+  selectedAdapters.forEach(adapter => {
+    deployCoreRules(adapter, isUpgrade, managedPaths);
+    newPaths.add(`${adapter.rulesDir}/cbb-coding-rule.md`);
+    newPaths.add(`${adapter.rulesDir}/cbb-priority.md`);
+    newPaths.add(`${adapter.rulesDir}/cbb-ai-behavior.md`);
+  });
+  log(`核心规则 → ${selectedAdapters.map(a => a.rulesDir).join(', ')} (2 个文件)`, 'success');
+
+  // 安装 Skills（支持 skills 的适配器）
+  const skillsAdapters = selectedAdapters.filter(a => a.skillsDir);
+  if (skillsAdapters.length > 0) {
+    console.log(`\n  🔧 ${action}按需加载 Skills...`);
+    const standardsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'dev-standards', 'skills');
+    const openspecExtendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
+    const extendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'tools');
+
+    const skillsDests = skillsAdapters.map(a => a.skillsDir);
+    let stdCount = 0, osCount = 0, extCount = 0;
+    skillsAdapters.forEach(adapter => {
+      // 通用编码规范 Skills（cbb/dev-standards/skills）
+      const stdResult = deploySkills(adapter, isUpgrade, managedPaths, standardsSkillsSrc);
+      if (stdResult.count > 0) {
+        stdCount = stdResult.count;
+        stdResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+      }
+      // 官方 OpenSpec Skills（openspec/skills/）不部署——工作流入口统一为 /opsx:* 斜杠命令
+      //（openspec/commands/ 在下方 Commands 段部署），避免双形态重复
+      // worktree 扩展 Skills：沙箱内只需 push / close（init/extend 由 workspace 根的子集安装）
+      const osExtResult = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, SANDBOX_WORKTREE_SKILLS);
+      if (osExtResult.count > 0) {
+        osCount = osExtResult.count;
+        osExtResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+      }
+      // 工具 Skills：仅 cbb-design-to-wiki（设计文档发布属 openspec 设计阶段动作）
+      const extResult = deploySkills(adapter, isUpgrade, managedPaths, extendsSkillsSrc, SANDBOX_TOOLS_SKILLS);
+      if (extResult.count > 0) {
+        extCount = extResult.count;
+        extResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+      }
+    });
+    if (stdCount > 0) log(`规范 Skills → ${skillsDests.join(', ')} (${stdCount} 个)`, 'success');
+    if (osCount > 0) log(`worktree Skills → ${skillsDests.join(', ')} (${osCount} 个)`, 'success');
+    if (extCount > 0) log(`扩展 Skills → ${skillsDests.join(', ')} (${extCount} 个)`, 'success');
+
+    // 部署 Superpowers Skills（白名单：openspec 工作流依赖 + 方法论基底）
+    const superpowersSkillsSrc = superpowers.SUPERPOWERS_SKILLS_DIR;
+    let spCount = 0;
+    if (fs.existsSync(superpowersSkillsSrc)) {
+      skillsAdapters.forEach(adapter => {
+        const spResult = deploySkills(adapter, isUpgrade, managedPaths, superpowersSkillsSrc, SUPERPOWERS_WHITELIST);
+        if (spResult.count > 0) {
+          spCount = spResult.count;
+          spResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+        }
+      });
+      if (spCount > 0) log(`Superpowers Skills → ${skillsDests.join(', ')} (${spCount}/${superpowers.getSkillCount()} 个，白名单)`, 'success');
+    } else {
+      log('superpowers/skills/ 目录不存在，跳过 Superpowers Skills 部署', 'warn');
+      log('可运行 cbb update --upstream-superpowers 下载最新 skills', 'warn');
+    }
+
+    // 检测用户级 superpowers 安装，避免与项目级重复导致 skill 冲突
+    await detectUserLevelSuperpowers(selectedAdapters, yes);
+  }
+
+  // 安装 Commands（官方 12 个 + worktree 扩展；worktree 命令仅装 close/push，
+  // init/extend 只在 workspace 根使用，由 installWorkspaceConfig 部署）
+  const commandsAdapters = selectedAdapters.filter(a => a.commandsDir);
+  if (commandsAdapters.length > 0) {
+    console.log(`\n  ⚡ ${action} Commands...`);
+    const commandsBaseSrc = path.join(SHARED_STANDARDS_DIR, 'openspec', 'commands');
+    const commandsExtendsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'commands');
+    const cmdFilter = ['close.md', 'push.md'];
+
+    const cmdDests = commandsAdapters.map(a => a.commandsDir);
+    let cmdCount = 0;
+    commandsAdapters.forEach(adapter => {
+      let adapterCmdCount = 0;
+      // 官方 Commands（openspec/commands/）— 始终部署
+      const baseResult = deployCommands(adapter, isUpgrade, managedPaths, commandsBaseSrc);
+      if (baseResult.count > 0) {
+        adapterCmdCount += baseResult.count;
+        baseResult.names.forEach(name => newPaths.add(`${adapter.commandsDir}/${name}`));
+      }
+      // worktree 扩展 Commands（cbb/worktrees/commands/）
+      const extResult = deployCommands(adapter, isUpgrade, managedPaths, commandsExtendsSrc, cmdFilter);
+      if (extResult.count > 0) {
+        adapterCmdCount += extResult.count;
+        extResult.names.forEach(name => newPaths.add(`${adapter.commandsDir}/${name}`));
+      }
+      cmdCount = Math.max(cmdCount, adapterCmdCount);
+    });
+    if (cmdCount > 0) log(`Commands → ${cmdDests.join(', ')} (${cmdCount} 个)`, 'success');
+  }
+
+  // 设置 OpenSpec 工作流
+  console.log(`\n  📋 设置 OpenSpec 工作流...`);
+  const schemasSrcs = [
+    path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
+  ];
+  schemasSrcs.forEach(src => {
+    if (fs.existsSync(src)) {
+      fs.readdirSync(src).filter(f => fs.statSync(path.join(src, f)).isDirectory())
+        .forEach(name => newPaths.add(`openspec/schemas/${name}`));
+    }
+  });
+  setupOpenSpec(isUpgrade, managedPaths);
+  newPaths.add('openspec/config.yaml');
+
+  // 写入自动版本检查 hook
+  const hookAdapters = selectedAdapters.filter(a => a.settingsFile && a.hookEvents);
+  if (hookAdapters.length > 0) {
+    console.log(`\n  🔔 配置自动版本检查...`);
+    const command = settingsManager.getCheckUpdateCommand();
+    hookAdapters.forEach(adapter => {
+      // 用户级 settings 用绝对路径，不写入项目清单
+      const settingsPath = adapter.settingsFileIsUserLevel
+        ? adapter.settingsFile
+        : path.join(TARGET_DIR, adapter.settingsFile);
+      settingsManager.addHooks(settingsPath, command, adapter.hookEvents);
+      // 清理旧版本遗留的 SessionStart hook（现已仅安装 UserPromptSubmit）
+      if (settingsManager.removeLegacyHooks(settingsPath)) {
+        log(`清理 ${adapter.displayName} 遗留的 SessionStart hook`, 'success');
+      }
+      if (!adapter.settingsFileIsUserLevel) newPaths.add(adapter.settingsFile);
+    });
+    log(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join(', ')} (${hookAdapters[0].hookEvents.join(', ')})`, 'success');
+  }
+
+  // 升级时清理旧路径（在旧清单中但不在新路径集中）。
+  // 注意：CLAUDE.md / AGENTS.md 等用户文档受保护，即使旧清单里有也不删除。
+  if (isUpgrade) {
+    const oldPaths = pathsToDelete(managedPaths, newPaths);
+    if (oldPaths.length > 0) {
+      section('🧹', `清理上一版本残留（${oldPaths.length} 个）`);
+      // 先全部删除
+      oldPaths.forEach(oldPath => {
+        const targetPath = path.join(TARGET_DIR, oldPath);
+        if (fs.existsSync(targetPath)) removePath(targetPath);
+      });
+      // 再展示列表：超过 5 个则折叠为汇总，避免输出过长
+      const MAX_DISPLAY = 5;
+      oldPaths.slice(0, MAX_DISPLAY).forEach(p => log(`  ${p}`, 'dim'));
+      if (oldPaths.length > MAX_DISPLAY) {
+        log(`  ... 还有 ${oldPaths.length - MAX_DISPLAY} 个`, 'dim');
+      }
+    }
+
+    const kept = protectedKeptPaths(managedPaths, newPaths);
+    if (kept.length > 0) {
+      section('🛡️', '保留用户文档');
+      kept.forEach(k => {
+        log(`  ${k}（本包已不再管理，文件可能含用户内容，未删除）`, 'warn');
+      });
+    }
+
+    // 清理旧版本遗留的 skills/node_modules/（v1.0.4-zjc.14 起 koffi 改为从全局位置加载）
+    skillsAdapters.forEach(adapter => {
+      const legacyNodeModules = path.join(TARGET_DIR, adapter.skillsDir, 'node_modules');
+      if (fs.existsSync(legacyNodeModules)) {
+        removePath(legacyNodeModules);
+        log(`清理遗留 ${adapter.skillsDir}/node_modules/`, 'success');
+      }
+    });
+  }
+
+  // 写入清单
+  writeManifest(newPaths, selectedAdapters);
+
+  // 更新 .gitignore
+  updateGitignore();
+
+  // 完成摘要
+  console.log(`\n  ✅ ${action}完成！\n`);
+
+  if (yes) {
+    console.log(c('dim', '  （使用 --yes 非交互模式，已默认选中所有适配器）'));
+  }
+
+  // 适配器映射（单行）
+  const adapterSummary = selectedAdapters.map(a => `${a.displayName} → ${a.rulesDir}/`).join(' | ');
+  console.log(`  ${adapterSummary}`);
+
+  // OpenSpec 摘要（单行）
+  const schemasDest = path.join(TARGET_DIR, 'openspec', 'schemas');
+  let schemaCount = 0;
+  let defaultSchema = '';
+  if (fs.existsSync(schemasDest)) {
+    const configPath = path.join(TARGET_DIR, 'openspec', 'config.yaml');
+    if (fs.existsSync(configPath)) {
+      defaultSchema = yaml.load(fs.readFileSync(configPath, 'utf-8')).schema || '';
+    }
+    schemaCount = fs.readdirSync(schemasDest).filter(name =>
+      fs.statSync(path.join(schemasDest, name)).isDirectory()
+    ).length;
+  }
+  console.log(`  OpenSpec → openspec/config.yaml + ${schemaCount} 个工作流${defaultSchema ? ` (${defaultSchema} 默认)` : ''}`);
+
+  // 附加组件（单行）
+  const hasSkills = selectedAdapters.some(a => a.skillsDir);
+  const hasCommands = selectedAdapters.some(a => a.commandsDir);
+  const hasHooks = selectedAdapters.some(a => a.settingsFile && a.hookEvents);
+  const extras = [];
+  if (hasSkills) extras.push('Skills');
+  if (hasCommands) extras.push('Commands');
+  if (hasHooks) extras.push('版本检查 hook');
+  if (extras.length > 0) {
+    console.log(`  ${extras.join(' / ')} 已配置`);
+  }
+  console.log('');
+}
+
+/**
+ * 为 workspace 根目录安装 AI 配置子集（由 cbb setup 调用）。
+ *
+ * 只装 worktree 生命周期管理（init/extend/close/push）+ openspec 运行时配置，
+ * 不装 base 工作流、编码规范、superpowers、版本检查 hook--这些属于 sandbox worktree
+ * 内的开发配置，由 worktree 内 `cbb init --yes` 完整模式安装。在 workspace 根目录
+ * （主分支）装 base 工作流会诱导绕过 worktree 直接在主分支做需求开发。
+ */
+async function installWorkspaceConfig(targetDir, options = {}) {
+  const { yes = false } = options;
+  if (targetDir) TARGET_DIR = targetDir;
+
+  const isUpgrade = detectExistingInstall();
+  const action = isUpgrade ? '升级' : '安装';
+  const managedPaths = readManifest();
+  const newPaths = new Set();
+
+  console.log(`\n  🚀 ${action} workspace AI 配置（worktree 管理子集）...\n`);
+
+  const isNonInteractive = yes || !process.stdin.isTTY;
+  if (yes && process.stdin.isTTY) {
+    log('--yes 非交互模式，已默认选中所有适配器', 'info');
+  }
+  const selectedAdapters = isNonInteractive ? adapters : await selectTools(isUpgrade);
+  await ensureOpenSpecCli();
+
+  // 只装 worktree 生命周期管理 Skills（init/extend/close/push）
+  const skillsAdapters = selectedAdapters.filter(a => a.skillsDir);
+  if (skillsAdapters.length > 0) {
+    console.log(`\n  🔧 ${action} worktree 管理 Skills...`);
+    const openspecExtendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
+    const osExtFilter = ['openspec-init-worktree', 'openspec-extend-worktree', 'openspec-close-worktree', 'openspec-push-worktrees'];
+    const skillsDests = skillsAdapters.map(a => a.skillsDir);
+    let count = 0;
+    skillsAdapters.forEach(adapter => {
+      const r = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, osExtFilter);
+      if (r.count > 0) {
+        count += r.count;
+        r.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+      }
+    });
+    if (count > 0) log(`worktree 管理 Skills → ${skillsDests.join(', ')} (${count} 个)`, 'success');
+  }
+
+  // 只装 worktree 管理 Commands（init/extend/close/push）
+  const commandsAdapters = selectedAdapters.filter(a => a.commandsDir);
+  if (commandsAdapters.length > 0) {
+    console.log(`\n  ⚡ ${action} worktree 管理 Commands...`);
+    const commandsExtendsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'commands');
+    const cmdFilter = ['init.md', 'extend.md', 'close.md', 'push.md'];
+    const cmdDests = commandsAdapters.map(a => a.commandsDir);
+    let count = 0;
+    commandsAdapters.forEach(adapter => {
+      const r = deployCommands(adapter, isUpgrade, managedPaths, commandsExtendsSrc, cmdFilter);
+      if (r.count > 0) {
+        count += r.count;
+        r.names.forEach(name => newPaths.add(`${adapter.commandsDir}/${name}`));
+      }
+    });
+    if (count > 0) log(`worktree 管理 Commands → ${cmdDests.join(', ')} (${count} 个)`, 'success');
+  }
+
+  // 设置 OpenSpec 工作流（config.yaml + schemas）
+  console.log(`\n  📋 设置 OpenSpec 工作流...`);
+  const schemasSrcs = [
+    path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
+  ];
+  schemasSrcs.forEach(src => {
+    if (fs.existsSync(src)) {
+      fs.readdirSync(src).filter(f2 => fs.statSync(path.join(src, f2)).isDirectory())
+        .forEach(name => newPaths.add(`openspec/schemas/${name}`));
+    }
+  });
+  setupOpenSpec(isUpgrade, managedPaths);
+  newPaths.add('openspec/config.yaml');
+
+  // 升级时清理旧路径（workspace 曾装过的 base 工作流等不属于此子集，删除）
+  if (isUpgrade) {
+    const oldPaths = pathsToDelete(managedPaths, newPaths);
+    if (oldPaths.length > 0) {
+      section('🧹', `清理上一版本残留（${oldPaths.length} 个）`);
+      oldPaths.forEach(oldPath => {
+        const targetPath = path.join(TARGET_DIR, oldPath);
+        if (fs.existsSync(targetPath)) removePath(targetPath);
+      });
+      const MAX_DISPLAY = 5;
+      oldPaths.slice(0, MAX_DISPLAY).forEach(p => log(`  ${p}`, 'dim'));
+      if (oldPaths.length > MAX_DISPLAY) log(`  ... 还有 ${oldPaths.length - MAX_DISPLAY} 个`, 'dim');
+    }
+    const kept = protectedKeptPaths(managedPaths, newPaths);
+    if (kept.length > 0) {
+      section('🛡️', '保留用户文档');
+      kept.forEach(k => log(`  ${k}（本包已不再管理，文件可能含用户内容，未删除）`, 'warn'));
+    }
+    (skillsAdapters || []).forEach(adapter => {
+      const legacyNodeModules = path.join(TARGET_DIR, adapter.skillsDir, 'node_modules');
+      if (fs.existsSync(legacyNodeModules)) {
+        removePath(legacyNodeModules);
+        log(`清理遗留 ${adapter.skillsDir}/node_modules/`, 'success');
+      }
+    });
+  }
+
+  writeManifest(newPaths, selectedAdapters);
+  updateGitignore();
+
+  console.log(`\n  ✅ ${action}完成！\n`);
+  const adapterSummary = selectedAdapters.map(a => `${a.displayName} → ${a.skillsDir}/`).join(' | ');
+  console.log(`  ${adapterSummary}`);
+  console.log('  workspace 子集：worktree 管理 Skills/Commands + openspec 配置（不含 base 工作流/编码规范/superpowers）');
+  console.log('');
+}
+
+// ── cbb setup 命令 ──────────────────────────────────────
+
+/**
+ * 若 targetDir 已安装（.cbb/.managed-by-cbb 存在），输出当前版本号
+ * 并尝试从 registry 查询最新版本，让用户确认是否继续。
+ *  - 用户输入 n / no → 返回 false（调用方决定是跳过还是退出）
+ *  - 未安装 / 查询失败 / 用户确认 → 返回 true
+ */
+async function confirmUpgradeIfInstalled(targetDir) {
+  const installed = version.readInstalledVersion(targetDir);
+  if (!installed) return true; // 未安装：不提示，直接继续
+
+  // 根据当前包版本（而非已安装版本）决定查询哪个 tag：
+  // 反查当前版本所属的 dist-tag（如 zjc / beta / latest），不依赖版本号格式
+  const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+  let tag = 'latest';
+  try {
+    tag = await version.findTagForVersion(pkg.version) || 'latest';
+  } catch (_) {
+    // 网络失败静默降级：使用 latest
+  }
+
+  let latest = null;
+  try {
+    latest = await version.fetchLatest(tag);
+  } catch (_) {
+    // 网络失败静默降级：latest 保持 null
+  }
+
+  section('📦', '检测到已安装版本');
+  field('当前', `v${installed}`, 'cyan');
+  if (latest && version.compareVersions(latest, installed) > 0) {
+    field('最新', `v${latest}`, 'green');
+    console.log('');
+  } else if (latest) {
+    field('最新', `v${latest}`, 'gray');
+    console.log(c('gray', '  （已是最新，无需升级）'));
+    console.log('');
+    // 已是最新，但仍询问一次确认，避免用户误以为没生效
+    latest = null;
+  } else {
+    field('最新', c('yellow', '无法检查（网络异常）'));
+    console.log('');
+  }
+
+  const prompt = latest
+    ? `是否升级到 v${latest}？(Y/n): `
+    : '是否重新安装？(Y/n): ';
+  const answer = await ask(prompt);
+  if (answer && answer.toLowerCase() === 'n') {
+    log('已取消安装/升级', 'warn');
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 检查业务空间根目录下是否有 CONFIG.json（init-worktree 技能依赖）。
+ * 不存在时，将包内样例文件复制为 CONFIG.json，提示用户编辑为实际配置。
+ */
+function ensureWorkspaceConfig(targetDir, workspaceName) {
+  const configPath = path.join(targetDir, 'CONFIG.json');
+  if (fs.existsSync(configPath)) {
+    log(`工作空间「${workspaceName}」的 CONFIG.json 已存在，跳过初始化`, 'success');
+    return;
+  }
+
+  // 复制样例文件作为 CONFIG.json
+  const samplePath = path.join(SHARED_STANDARDS_DIR, workspaces.SAMPLE_CONFIG);
+  fs.copyFileSync(samplePath, configPath);
+  log(`工作空间「${workspaceName}」未找到 CONFIG.json，已从样例文件复制`, 'warn');
+  log('请编辑 CONFIG.json，将示例 apps 替换为实际关联应用', 'warn');
+}
+
+/**
+ * 读取 CONFIG.json 中的应用列表，将关联应用代码 clone/fetch 到 .code/ 目录。
+ * 首次 clone（耗时较长），后续 fetch --all（秒级更新）。
+ * 这是基准代码，init-worktree 技能后续只做轻量 fetch 检查。
+ */
+function syncAppRepos(targetDir) {
+  const configPath = path.join(targetDir, 'CONFIG.json');
+  if (!fs.existsSync(configPath)) return;
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (e) {
+    log('CONFIG.json 解析失败，跳过应用代码拉取', 'warn');
+    return;
+  }
+
+  const apps = config.apps;
+  if (!Array.isArray(apps) || apps.length === 0) {
+    log('CONFIG.json 中 apps 为空，跳过 .code/ 拉取', 'dim');
+    return;
+  }
+
+  const codeDir = path.join(targetDir, '.code');
+  fs.mkdirSync(codeDir, { recursive: true });
+
+  let ok = 0, fail = 0;
+  apps.forEach(app => {
+    if (!app.name || !app.repo) {
+      log(`应用 "${app.name || '(未知)'}" 缺少 name 或 repo，跳过`, 'warn');
+      fail++;
+      return;
+    }
+
+    const appDir = path.join(codeDir, app.name);
+    if (fs.existsSync(path.join(appDir, '.git'))) {
+      // 已存在：fetch 更新
+      try {
+        execSync('git fetch --all -q', { cwd: appDir, stdio: 'pipe', timeout: 60000 });
+        log(`${app.name}: 代码已更新（fetch --all）`, 'success');
+        ok++;
+      } catch (e) {
+        log(`${app.name}: fetch 失败（离线或无权限，使用本地已有代码）`, 'warn');
+        ok++; // 不算失败，用本地代码
+      }
+    } else {
+      // 不存在：clone
+      try {
+        execSync(`git clone -q "${app.repo}" "${appDir}"`, { stdio: 'pipe', timeout: 180000 });
+        log(`${app.name}: 代码已拉取（clone）`, 'success');
+        ok++;
+      } catch (e) {
+        log(`${app.name}: clone 失败 — ${app.repo}`, 'error');
+        fail++;
+      }
+    }
+  });
+
+  if (fail > 0) {
+    log(`应用代码拉取完成（成功 ${ok}，失败 ${fail}）`, 'warn');
+  } else {
+    log(`应用代码已就绪（${ok} 个应用 → .code/）`, 'success');
+  }
+}
+
+/**
+ * 读取远程默认分支名（如 "main" / "master" / "develop"）。
+ * 用 symbolic-ref refs/remotes/origin/HEAD 探测；取不到返回 null。
+ * 参照 cbb/worktrees/skills/openspec-init-worktree/scripts/create-branches.js:47。
+ */
+function getRemoteDefaultBranch(cwd) {
+  try {
+    const out = execSync('git symbolic-ref --quiet refs/remotes/origin/HEAD', {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 10000,
+    });
+    const ref = out.trim(); // 例: "refs/remotes/origin/main"
+    const prefix = 'refs/remotes/origin/';
+    return ref.startsWith(prefix) ? ref.slice(prefix.length) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 在「子目录已存在且匹配」分支同步工作空间仓库到远程默认分支的最新。
+ * 流程：fetch → 检测默认分支 → 必要时切换分支 → fast-forward merge。
+ * 任一步失败都抛出，由调用方走错误路径中止整个 cbb setup。
+ */
+function syncWorkspaceRepo(targetDir) {
+  // 1. fetch
+  try {
+    execSync('git fetch --all -q', {
+      cwd: targetDir,
+      stdio: 'pipe',
+      timeout: 60000,
+    });
+  } catch (e) {
+    log(`git fetch 失败：${e.message}`, 'error');
+    log(`请检查网络或 ${targetDir}/ 的 remote 凭证后重试`, 'error');
+    throw e;
+  }
+
+  // 2. 检测远程默认分支（不假设是 master / main）
+  const defaultBranch = getRemoteDefaultBranch(targetDir);
+  if (!defaultBranch) {
+    log(`无法探测 ${targetDir}/ 的远程默认分支（refs/remotes/origin/HEAD 未设置）`, 'error');
+    log(`请在该目录执行 \`git remote set-head origin --auto\` 后重试`, 'error');
+    throw new Error('DEFAULT_BRANCH_UNKNOWN');
+  }
+
+  // 3. 必要时切换到默认分支
+  const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {
+    cwd: targetDir,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10000,
+  }).trim();
+  if (currentBranch !== defaultBranch) {
+    log(`本地当前分支 ${currentBranch} ≠ 远程默认分支 ${defaultBranch}，正在切换...`, 'warn');
+    try {
+      execSync(`git checkout -q "${defaultBranch}"`, {
+        cwd: targetDir,
+        stdio: 'pipe',
+        timeout: 30000,
+      });
+    } catch (e) {
+      log(`git checkout ${defaultBranch} 失败：${e.message}`, 'error');
+      log(`请手动切换分支后重试`, 'error');
+      throw e;
+    }
+  }
+
+  // 4. fast-forward merge 到 origin/<默认分支>
+  try {
+    execSync(`git merge --ff-only -q "origin/${defaultBranch}"`, {
+      cwd: targetDir,
+      stdio: 'pipe',
+      timeout: 60000,
+    });
+    log(`已同步 ${path.basename(targetDir)}/ 到 origin/${defaultBranch} 最新（fast-forward）`, 'success');
+  } catch (e) {
+    log(`git merge --ff-only origin/${defaultBranch} 失败：${e.message}`, 'error');
+    log(`本地 ${targetDir}/ 与远程分叉或有未提交改动，请手动处理后重试`, 'error');
+    throw e;
+  }
+}
+
+/**
+ * 处理单个业务空间：展示详情 → 计算子目录 → 检测/克隆 → CONFIG.json → 拉取应用代码 → 升级询问 → init()。
+ * 失败时不抛出也不退出，返回结果对象供调用方汇总。
+ * @returns {Promise<{ok: boolean, error?: string, message?: string, subdir?: string, skipped?: boolean}>}
+ */
+async function initSingleWorkspace(w) {
+  // 1. 展示所选业务空间（单行摘要）
+  console.log(`${c('cyan', '开始配置')} ${c('yellow', w.businessLine)}/${c('bold', w.name)}...`);
+
+  // 2. 计算仓库子目录名（来自 repo URL 的最后一段）
+  const subdirName = workspaces.extractRepoBasename(w.repo);
+  if (!subdirName) {
+    log(`无法从仓库地址 "${w.repo}" 提取目录名`, 'error');
+    return { ok: false, error: 'EXTRACT_FAILED' };
+  }
+
+  const parentDir = process.cwd();
+  const targetDir = path.join(parentDir, subdirName);
+
+  // 3. 检查子目录：复用 / 报错 / 克隆
+  let wasCloned = false;
+  if (fs.existsSync(targetDir)) {
+    const detection = workspaces.detectRepo(targetDir, w.repo);
+    if (detection.state === 'matched') {
+      log(`子目录 ${c('cyan', subdirName + '/')} 已存在且匹配，正在同步远程最新...`, 'info');
+      try {
+        syncWorkspaceRepo(targetDir);
+      } catch (e) {
+        return { ok: false, error: 'PULL_FAILED', message: e.message };
+      }
+    } else {
+      const remoteList = detection.remotes.length
+        ? detection.remotes.map(r => `        ${c('gray', r.name + ':')} ${r.url}`).join('\n')
+        : `        ${c('gray', '（该目录尚未配置 remote）')}`;
+      log(
+        `子目录 ${c('cyan', subdirName + '/')} 已存在但不是所选业务空间 "${w.name}" 的仓库：`,
+        'error',
+      );
+      console.log(remoteList);
+      console.log(`        ${c('gray', '期望 remote:')} ${w.repo}`);
+      console.log('');
+      log('请删除该子目录后重试，或在另一个父目录中运行本命令。', 'warn');
+      return { ok: false, error: 'DIR_MISMATCH' };
+    }
+  } else {
+    console.log(`⏳ 正在克隆仓库到 ${c('cyan', subdirName + '/')} ...`);
+    try {
+      // 在 parentDir 下克隆，git 会自动创建 subdirName 子目录
+      execSync(`git clone "${w.repo}"`, {
+        cwd: parentDir,
+        stdio: 'pipe',
+        timeout: 180000,
+      });
+    } catch (e) {
+      log(`git clone 失败：${e.message}`, 'error');
+      log('请检查：1) 仓库地址是否正确  2) 是否已配置 SSH key 或 GitLab 访问凭证', 'warn');
+      return { ok: false, error: 'CLONE_FAILED', message: e.message };
+    }
+    wasCloned = true;
+    log(`已克隆到 ${c('cyan', subdirName + '/')}`, 'success');
+  }
+
+  // 4. 检查 CONFIG.json（init-worktree 技能依赖），不存在则复制样例文件
+  ensureWorkspaceConfig(targetDir, w.name);
+
+  // 5. 校验 CONFIG.json 格式，不合法则中断并撤销本空间初始化
+  const configPath = path.join(targetDir, 'CONFIG.json');
+  const configValidation = workspaces.validateWorkspaceConfig(configPath);
+  if (!configValidation.valid) {
+    log(`CONFIG.json 校验失败：${configValidation.message}`, 'error');
+    // 撤销本次克隆，使工作空间回到初始状态，用户配好 CONFIG.json 后可重新执行
+    if (wasCloned && fs.existsSync(targetDir)) {
+      removePath(targetDir);
+      log(`已撤销本次克隆（${subdirName}/），请配好 CONFIG.json 后重新执行 cbb setup`, 'warn');
+    } else {
+      log('请修正 CONFIG.json 后重新执行 cbb setup', 'warn');
+    }
+    const samplePath = path.join(SHARED_STANDARDS_DIR, workspaces.SAMPLE_CONFIG);
+    log(`参考格式：${samplePath}`, 'info');
+    return { ok: false, error: 'CONFIG_INVALID', message: configValidation.message };
+  }
+  log('CONFIG.json 校验通过', 'success');
+
+  // 6. 拉取关联应用代码到 .code/（基准代码，首次 clone，后续 fetch 更新）
+  syncAppRepos(targetDir);
+
+  // 7. 若已安装，提示当前版本并询问是否继续；用户拒绝则跳过本 workspace
+  const shouldInstall = await confirmUpgradeIfInstalled(targetDir);
+  if (!shouldInstall) {
+    return { ok: false, error: 'USER_CANCELLED', skipped: true };
+  }
+
+  // 7. 安装 workspace AI 配置子集（worktree 管理技能/命令 + openspec 配置，不含 base 工作流）
+  try {
+    await installWorkspaceConfig(targetDir, { yes: true });
+    return { ok: true, subdir: subdirName };
+  } catch (e) {
+    log(`初始化 ${subdirName} 失败：${e.message}`, 'error');
+    return { ok: false, error: 'INIT_FAILED', message: e.message };
+  }
+}
+
+/** 把 initSingleWorkspace 的 error 码翻译成可读的中文描述 */
+function describeBatchError(r) {
+  switch (r.error) {
+    case 'EXTRACT_FAILED':  return '无法从仓库地址提取目录名';
+    case 'DIR_MISMATCH':    return '子目录已存在但不是该业务空间的仓库';
+    case 'CLONE_FAILED':    return `git clone 失败：${r.message || ''}`.trim();
+    case 'PULL_FAILED':     return `工作空间仓库同步失败：${r.message || ''}`.trim();
+    case 'CONFIG_INVALID':  return `CONFIG.json 不合法：${r.message || ''}`.trim();
+    case 'USER_CANCELLED':  return '用户取消升级';
+    case 'INIT_FAILED':     return `初始化失败：${r.message || ''}`.trim();
+    default:                return r.error || '未知错误';
+  }
+}
+
+/** 批量处理结束后输出汇总报告（成功项绿色、失败项红色） */
+function printBatchSummary(results) {
+  const ok = results.filter(r => r.ok);
+  const failed = results.filter(r => !r.ok);
+
+  section('📊', `处理汇总（成功 ${ok.length}/${results.length}）`);
+  ok.forEach(r => {
+    log(`${c('cyan', (r.subdir || '?') + '/')}  ${r.w.name}（${r.w.businessLine}）`, 'success');
+  });
+  failed.forEach(r => {
+    log(`${r.w.name}（${r.w.businessLine}）：${describeBatchError(r)}`, 'error');
+  });
+  if (failed.length > 0) {
+    console.log('');
+    log(`${failed.length} 个业务空间处理失败，请按上述提示排查`, 'warn');
+  }
+}
+
+/**
+ * 初始化业务空间工作目录（cbb setup 命令）。
+ *
+ * 流程：安装用户级组件（幂等）→ 检测当前目录 → 加载配置 → checkbox 多选
+ *       → 确认目标目录 → 依次处理每个选中的 workspace。
+ * 单个 workspace 失败不影响后续。
+ */
+async function setupWorkspace() {
+  // 首次运行：安装用户级组件（hook / cbb-wiki-ops，幂等，已装则跳过）
+  await setupUserLevelComponents();
+
+  // 0. 检测当前目录是否为 git 仓库
+  const parentDir = process.cwd();
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: parentDir,
+      stdio: 'pipe',
+      timeout: 5000,
+    });
+    log('当前目录是 Git 仓库，不支持在此执行 cbb setup。', 'error');
+    log('请在非 Git 仓库的目录下运行（例如新建空文件夹后执行）。', 'warn');
+    process.exit(1);
+  } catch (_) {
+    // 非 git 仓库，继续
+  }
+
+  // 1. 加载业务空间配置
+  let list;
+  try {
+    list = workspaces.loadWorkspaces();
+  } catch (e) {
+    log(e.message, 'error');
+    process.exit(1);
+  }
+
+  // 2. checkbox 多选（inquirer 风格：↑↓ 移动、空格 切换、a 全选、Enter 确认）
+  const selectedIdx = await checkbox.promptCheckbox({
+    header: '📦  选择要初始化的业务空间（多选用空格切换）',
+    items: list.map(w => ({
+      label: `${c('yellow', '[' + w.businessLine + ']')} ${w.name}`,
+      hint: w.repo,
+    })),
+  });
+
+  if (selectedIdx.size === 0) {
+    log('未选择任何业务空间，已退出', 'warn');
+    process.exit(0);
+  }
+
+  // 转成有序数组（按原始顺序）
+  const selected = [...selectedIdx]
+    .sort((a, b) => a - b)
+    .map(i => list[i]);
+
+  // 3. 批量展示所选业务空间
+  section('✓', `已选择 ${selected.length} 个业务空间`);
+  selected.forEach((w, i) => {
+    console.log(`  ${c('cyan', String(i + 1) + '.')} ${c('yellow', '[' + w.businessLine + ']')} ${w.name}`);
+    console.log(`        ${c('gray', w.repo)}`);
+  });
+  console.log('');
+
+  // 4. 展示目标目录并让用户确认
+  section('📁', '业务空间将创建在以下目录');
+  console.log(`  ${c('cyan', parentDir)}`);
+  console.log('');
+  const answer = await ask(`${c('yellow', '?')} 是否将上述业务空间创建在此目录？(Y/n) `);
+  if (answer.toLowerCase() === 'n' || answer.toLowerCase() === 'no') {
+    log('已取消，未创建任何业务空间。', 'warn');
+    process.exit(0);
+  }
+  console.log('');
+
+  // 5. 依次处理每个 workspace；任一失败不影响后续
+  const results = [];
+  for (let i = 0; i < selected.length; i++) {
+    const w = selected[i];
+    section('📦', `[${i + 1}/${selected.length}] ${w.name}`);
+    console.log('');
+    const result = await initSingleWorkspace(w);
+    results.push({ w, ...result });
+    console.log('');
+  }
+
+  // 5. 汇总报告（已移除）
+}
+
+// ── 用户级组件 ────────────────────────────────────────────
+
+/**
+ * 安装用户级组件（与项目无关的内容，一次安装全局可用，幂等）。
+ *
+ * - 清单：~/.cbb/.user-components 记录本包管理的用户级路径
+ * - 内容：check-update hook（settings 由 settingsManager 幂等管理）+ 工具 skills（cbb-wiki-ops）
+ */
+const USER_MANIFEST_FILE = path.join(os.homedir(), '.cbb', '.user-components');
+// 装到用户级的工具 skills（与具体项目无关，任何会话都可能用到）
+const USER_LEVEL_SKILLS = ['cbb-wiki-ops'];
+
+async function setupUserLevelComponents() {
+  const home = os.homedir();
+  const srcDir = path.join(SHARED_STANDARDS_DIR, 'cbb', 'tools');
+  if (!fs.existsSync(srcDir)) return;
+
+  const managed = new Set();
+  const manifestDir = path.dirname(USER_MANIFEST_FILE);
+  fs.mkdirSync(manifestDir, { recursive: true });
+  if (fs.existsSync(USER_MANIFEST_FILE)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(USER_MANIFEST_FILE, 'utf-8'));
+      (data.paths || []).forEach(p => managed.add(p));
+    } catch (_) { /* ignore parse errors */ }
+  }
+
+  section('🏠', '检查用户级组件（~/.claude/、~/.qoder/）');
+
+  const skillAdapters = adapters.filter(a => a.skillsDir);
+  skillAdapters.forEach(adapter => {
+    USER_LEVEL_SKILLS.forEach(skillName => {
+      const src = path.join(srcDir, skillName);
+      if (!fs.existsSync(src)) return;
+      const dest = path.join(home, adapter.skillsDir, skillName);
+      removePath(dest);
+      fs.cpSync(src, dest, { recursive: true });
+      managed.add(`${adapter.skillsDir}/${skillName}`);
+    });
+  });
+  log(`工具 Skills → ${skillAdapters.map(a => `~/${a.skillsDir}/`).join(', ')} (${USER_LEVEL_SKILLS.length} 个)`, 'success');
+
+  // check-update hook（settingsManager 幂等：已有 _managedBy: cbb 标记则不重复写入）
+  const hookAdapters = adapters.filter(a => a.settingsFile && a.hookEvents);
+  if (hookAdapters.length > 0) {
+    const command = settingsManager.getCheckUpdateCommand();
+    hookAdapters.forEach(adapter => {
+      settingsManager.addHooks(adapter.settingsFile, command, adapter.hookEvents);
+      settingsManager.removeLegacyHooks(adapter.settingsFile);
+    });
+    log(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join(', ')}`, 'success');
+  }
+
+  const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+  fs.writeFileSync(USER_MANIFEST_FILE, JSON.stringify({
+    version: pkg.version,
+    paths: [...managed],
+  }, null, 2));
+}
+
+/**
+ * cbb update：按现有安装模式升级当前目录内容 + 用户级组件。
+ *
+ * 安装模式判定：清单含 rules 路径 → 完整模式（worktree 沙箱/单项目），
+ * 否则为 workspace 子集模式（空间根，只装 worktree 管理 + openspec 配置）。
+ */
+async function updateInstalled() {
+  await setupUserLevelComponents();
+
+  const manifest = readManifest();
+  if (manifest.size === 0) {
+    log('当前目录未检测到安装记录。初始化业务空间请用: cbb setup', 'error');
+    process.exit(1);
+  }
+
+  const isFullInstall = [...manifest].some(p =>
+    adapters.some(a => p.startsWith(`${a.rulesDir}/`))
+  );
+
+  if (isFullInstall) {
+    log('检测到完整模式安装，升级开发配置（rules + skills + commands + 工作流）...', 'info');
+    await init(undefined, {});
+  } else {
+    log('检测到 workspace 子集模式，升级 worktree 管理 + openspec 配置...', 'info');
+    await installWorkspaceConfig(undefined, {});
+  }
+}
+
+// ── 卸载 ──────────────────────────────────────────────────
+
+/**
+ * 智能卸载 config.yaml：
+ * - 反向合并：移除本包注入的字段，保留用户自有字段
+ * - 纯本包内容（无用户字段）→ 删除文件
+ */
+function uninstallConfigYaml(managedPaths) {
+  const configDest = path.join(TARGET_DIR, 'openspec', 'config.yaml');
+  const configSrc = path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'config.yaml');
+
+  if (!fs.existsSync(configDest) || !fs.existsSync(configSrc)) return false;
+  if (!managedPaths.has('openspec/config.yaml')) return false;
+
+  const ours = yaml.load(fs.readFileSync(configSrc, 'utf-8'));
+  const current = yaml.load(fs.readFileSync(configDest, 'utf-8'));
+
+  if (!current || typeof current !== 'object') return false;
+
+  // 移除本包覆盖的标量字段（schema, context 等）
+  const oursKeys = Object.keys(ours);
+  oursKeys.forEach(key => {
+    if (key === 'rules') return; // rules 单独处理
+    if (current[key] !== undefined) {
+      delete current[key];
+    }
+  });
+
+  // 移除本包注入的 rules 条目
+  if (ours.rules && typeof ours.rules === 'object') {
+    if (current.rules && typeof current.rules === 'object') {
+      Object.keys(ours.rules).forEach(key => {
+        delete current.rules[key];
+      });
+      // rules 对象变空则移除
+      if (Object.keys(current.rules).length === 0) {
+        delete current.rules;
+      }
+    }
+  }
+
+  // 检查是否有用户内容剩余
+  if (Object.keys(current).length === 0) {
+    return false; // 无用户内容，标记删除
+  }
+
+  // 保留用户字段
+  const remaining = yaml.dump(current, { lineWidth: -1 });
+  fs.writeFileSync(configDest, remaining);
+  log('config.yaml: 移除本包字段，保留用户配置', 'success');
+  return true; // 已处理，跳过通用删除
+}
+
+/**
+ * 卸载用户级组件（cbb-wiki-ops 等工具 skills + 版本检查 hook）。
+ * 按 ~/.cbb/.user-components 清单精确删除，不影响用户自装内容；
+ * ~/.cbb 目录不动（可能含用户自己的 wiki-config.json）。
+ */
+async function uninstallUserLevelComponents() {
+  if (!fs.existsSync(USER_MANIFEST_FILE)) {
+    log('未检测到用户级组件安装记录', 'warn');
+    return;
+  }
+  let paths = [];
+  try {
+    paths = JSON.parse(fs.readFileSync(USER_MANIFEST_FILE, 'utf-8')).paths || [];
+  } catch (_) { /* ignore parse errors */ }
+
+  let removed = 0;
+  paths.forEach(relPath => {
+    const target = path.join(os.homedir(), relPath);
+    if (fs.existsSync(target)) {
+      removePath(target);
+      log(`移除 ~/${relPath}`, 'success');
+      removed++;
+    }
+  });
+
+  // 移除版本检查 hook（保留用户其余配置）
+  adapters.forEach(adapter => {
+    if (!adapter.settingsFile || !adapter.hookEvents) return;
+    if (settingsManager.removeHooks(adapter.settingsFile, adapter.hookEvents)) {
+      log(`${adapter.settingsFile}: 移除版本检查 hook，保留用户配置`, 'success');
+    }
+  });
+
+  removePath(USER_MANIFEST_FILE);
+  log(`用户级组件已卸载（${removed} 个文件/目录）`, 'success');
+}
+
+async function uninstall() {
+  const manifestPath = path.join(TARGET_DIR, MANIFEST_FILE);
+  const manifestDir = path.join(TARGET_DIR, MANIFEST_DIR);
+
+  if (!fs.existsSync(manifestPath)) {
+    log('未检测到安装记录，无需卸载', 'warn');
+    return;
+  }
+
+  const managedPaths = readManifest();
+
+  // 确认卸载
+  console.log('\n🗑  卸载 @jspg-ai/coding-bb...\n');
+  const answer = await ask('确认卸载？此操作将移除本包管理的所有文件 (y/N): ');
+  if (answer.toLowerCase() !== 'y') {
+    log('已取消卸载');
+    return;
+  }
+
+  // 是否同时卸载用户级组件（工具 skills + 版本检查 hook，作用于 ~/.claude 等用户目录）
+  let removeUserLevel = false;
+  if (fs.existsSync(USER_MANIFEST_FILE)) {
+    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder 下的工具 skills + 版本检查 hook）？(y/N): ');
+    removeUserLevel = answerUser.toLowerCase() === 'y' || answerUser.toLowerCase() === 'yes';
+  }
+
+  // 智能处理 config.yaml（保留用户内容）
+  const configHandled = uninstallConfigYaml(managedPaths);
+
+  // 构建跳过集合（已被智能处理的路径）
+  const skippedPaths = new Set();
+  if (configHandled) skippedPaths.add('openspec/config.yaml');
+
+  // 智能处理 settings.json（hook 属用户级组件，仅在确认卸载用户级时移除；保留用户配置）
+  adapters.forEach(adapter => {
+    if (!adapter.settingsFile || !adapter.hookEvents) return;
+    const settingsPath = adapter.settingsFileIsUserLevel
+      ? adapter.settingsFile
+      : path.join(TARGET_DIR, adapter.settingsFile);
+    // 项目级：需在清单中才处理
+    if (!adapter.settingsFileIsUserLevel && !managedPaths.has(adapter.settingsFile)) return;
+    if (removeUserLevel && settingsManager.removeHooks(settingsPath, adapter.hookEvents)) {
+      log(`${adapter.settingsFile}: 移除版本检查 hook，保留用户配置`, 'success');
+    }
+    // 清理旧版本遗留的 SessionStart hook（无版本差异，无条件清理）
+    if (settingsManager.removeLegacyHooks(settingsPath)) {
+      log(`${adapter.settingsFile}: 清理遗留 SessionStart hook`, 'success');
+    }
+    skippedPaths.add(adapter.settingsFile);
+  });
+
+  // 删除清单中记录的所有路径。
+  // 注意：CLAUDE.md / AGENTS.md 等用户文档受保护，即使旧清单里有也不删除。
+  let removed = 0;
+  pathsToDelete(managedPaths, skippedPaths).forEach(relativePath => {
+    const targetPath = path.join(TARGET_DIR, relativePath);
+    if (fs.existsSync(targetPath)) {
+      removePath(targetPath);
+      log(`移除 ${relativePath}`, 'success');
+      removed++;
+    }
+  });
+  protectedKeptPaths(managedPaths, skippedPaths).forEach(kept => {
+    log(`保留 ${kept}（可能含用户自有内容，请按需手动删除）`, 'warn');
+  });
+
+  // 清理可能变空的父目录（从深到浅）
+  const dirsToCheck = new Set();
+  managedPaths.forEach(relativePath => {
+    let dir = path.dirname(relativePath);
+    while (dir && dir !== '.') {
+      dirsToCheck.add(dir);
+      dir = path.dirname(dir);
+    }
+  });
+  // 按深度排序，深层先处理
+  [...dirsToCheck].sort((a, b) => b.split('/').length - a.split('/').length).forEach(dir => {
+    const fullPath = path.join(TARGET_DIR, dir);
+    if (fs.existsSync(fullPath) && fs.readdirSync(fullPath).length === 0) {
+      removePath(fullPath);
+      log(`清理空目录 ${dir}/`, 'success');
+    }
+  });
+
+  // 删除清单文件和 .va 目录
+  removePath(manifestDir);
+  log('移除安装记录', 'success');
+
+  // 清理 .gitignore
+  cleanupGitignore();
+
+  // 卸载用户级组件（如已确认）
+  if (removeUserLevel) {
+    console.log('');
+    await uninstallUserLevelComponents();
+  }
+
+  console.log(`\n✅ 卸载完成！共移除 ${removed} 个文件/目录\n`);
+}
+
+// ── CLI 入口 ──────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const command = args[0];
+const restArgs = args.slice(1);
+
+switch (command) {
+  case 'setup': {
+    setupWorkspace().catch(err => {
+      log(err.message, 'error');
+      process.exit(1);
+    });
+    break;
+  }
+  case 'update': {
+    const upstreamSuperpowers = restArgs.includes('--upstream-superpowers');
+    const upstreamOpenspec = restArgs.includes('--upstream-openspec');
+    if (upstreamSuperpowers || upstreamOpenspec) {
+      // 维护者选项：从 GitHub 拉取上游原生内容到本包源仓库（发布流程用）
+      if (upstreamSuperpowers) {
+        superpowers.fetchLatestSkills().then(result => {
+          if (result.skipped) {
+            log(`superpowers skills 已是最新 (${result.sha.slice(0, 8)})`, 'success');
+          }
+          const validation = superpowers.validateSkills();
+          if (!validation.valid) {
+            if (validation.missing.length > 0) log(`缺少 skills: ${validation.missing.join(', ')}`, 'error');
+            if (validation.incomplete.length > 0) log(`不完整 skills: ${validation.incomplete.join(', ')}`, 'error');
+            process.exit(1);
+          }
+          log(`skills 完整性校验通过 (${superpowers.getSkillCount()} 个)`, 'success');
+        }).catch(err => {
+          log(`更新失败: ${err.message}`, 'error');
+          process.exit(1);
+        });
+      }
+      if (upstreamOpenspec) {
+        openspec.fetchLatestOpenSpec().then(result => {
+          if (!result.skipped) {
+            const validation = openspec.validateDeployed();
+            if (!validation.valid) {
+              log(`部署不完整,缺失: ${validation.missing.join(', ')}`, 'error');
+              process.exit(1);
+            }
+            log(`openspec 工作流完整性校验通过`, 'success');
+          } else {
+            const validation = openspec.validateDeployed();
+            if (!validation.valid) {
+              log(`本地 openspec 工作流不完整,请重新运行 cbb update --upstream-openspec:`, 'error');
+              for (const m of validation.missing) log(`  - 缺失 ${m}`, 'error');
+              process.exit(1);
+            }
+            log(`openspec 工作流完整性校验通过`, 'success');
+          }
+        }).catch(err => {
+          log(`更新失败: ${err.message}`, 'error');
+          process.exit(1);
+        });
+      }
+    } else {
+      updateInstalled().catch(err => {
+        log(err.message, 'error');
+        process.exit(1);
+      });
+    }
+    break;
+  }
+  case 'init': {
+    const yes = restArgs.includes('-y') || restArgs.includes('--yes');
+    init(undefined, { yes }).catch(err => {
+      log(err.message, 'error');
+      process.exit(1);
+    });
+    break;
+  }
+  case 'uninstall':
+    uninstall().catch(err => {
+      log(err.message, 'error');
+      process.exit(1);
+    });
+    break;
+  case 'check-update':
+    require('../utils/check-update.js');
+    break;
+  case 'wp':
+    require('../wiki/index.js').publish(restArgs);
+    break;
+  case 'wiki':
+    require('../wiki/cli.js').run(restArgs);
+    break;
+  case 'help':
+  case '-h':
+  case '--help':
+  case undefined:
+    showHelp();
+    break;
+  default:
+    log(`未知命令: ${command}`, 'error');
+    showHelp();
+    process.exit(1);
+}
+
+function showHelp() {
+  const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+  console.log(`
+@jspg-ai/coding-bb v${pkg.version} — AI Coding Agent 统一行为准则与工作流
+
+快速开始：
+  cbb setup              初始化业务空间（克隆仓库 + 配置工作流，首次运行自动安装用户级组件）
+  cbb update             更新已安装内容（用户级 + 当前空间/项目）
+  cbb uninstall          卸载（交互确认范围）
+
+内部命令（由流程自动调用，无需手动执行）：
+  cbb init --yes         worktree 沙箱内安装开发配置（init-worktree Step 4 自动调用）
+  cbb check-update       版本检查（hook 每日自动触发）
+
+Agent 命令（AI 通过技能调用，请勿手动执行）：
+  cbb wiki / cbb wp      Wiki 查询与发布
+
+维护者选项（发布流程用）：
+  cbb update --upstream-superpowers    从 GitHub 拉取最新 superpowers skills 到源仓库
+  cbb update --upstream-openspec       从 GitHub 拉取最新 OpenSpec 工作流到源仓库
+
+90% 的场景只需要：cbb setup
+
+前提条件（首次使用执行一次）：
+  npm install -g @jspg-ai/coding-bb
+`);
+}