@jspg-ai/coding-bb 0.0.2-beta.29 → 0.0.3-beta.12

package/cbb/lib/install/init.js

@@ -4,12 +4,13 @@
  * OpenSpec Shared Standards 安装脚本
  *
  * 将AI 编码规范与工作流套件安装到目标项目中。
- * 支持工具：Claude Code (.claude/rules/)、Qoder (.qoder/rules/)、opencode (.opencode/rules/)
+ * 支持工具：Claude Code (.claude/rules/)、Qoder (.qoder/rules/)、opencode (.opencode/rules/)、
+ *          WorkBuddy/CodeBuddy (.codebuddy/rules/)、TraeWork/TraeCode (.trae/rules/)
  *
  * 使用方式：
  *   npm install -g @jspg-ai/coding-bb  # 首次使用
- *   npm install -g @jspg-ai/coding-bb
- *   cd your-project && cbbm init
+ *   cbb setup                          # 初始化业务空间（空间根全量安装）
+ *   cbb update                         # 就地升级已安装目录
  */
 
 const fs = require('fs');
@@ -40,7 +41,7 @@ function execCmd(file, args, opts = {}) {
 
 const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
 
-// 目标项目根目录：默认取当前 cwd，init() / initWorkspace() 可在调用前覆盖。
+// 目标项目根目录：默认取当前 cwd，init() 可在调用前覆盖。
 // 注意：使用 let 而非 const 是为了让 cbb setup 能在拉好仓库后把目标目录
 // 切到仓库根，再复用 init() 的完整安装流程，而无需把 TARGET_DIR 透传到所有 helper。
 let TARGET_DIR = process.cwd();
@@ -51,14 +52,17 @@ 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'),
   require('./opencode'),
+  require('./codebuddy'),
+  require('./trae'),
+  require('./qoder'),
+  require('./claude-code'),
 ];
 
-// superpowers 部署白名单：仅装 openspec 工作流硬依赖 + 方法论基底（源仓库仍保留全量 14 个，
-// 供 cbb update --upstream-superpowers 维护；砍掉的与 openspec 工作流重叠或属低频场景）
+// superpowers 部署白名单：仅装 openspec 工作流硬依赖 + 方法论基底（源仓库仍保留全量 15 个，
+// 供 cbbm update --upstream-superpowers 维护；砍掉的与 openspec 工作流重叠或属低频场景）
 const SUPERPOWERS_WHITELIST = [
   'writing-plans',                  // openspec apply：生成 plan.md（schema.yaml 引用）
   'subagent-driven-development',    // openspec apply：执行 plan.md（schema.yaml 引用）
@@ -68,20 +72,33 @@ const SUPERPOWERS_WHITELIST = [
   'test-driven-development',        // TDD 计划结构 + TDD Evidence 方法论基底
 ];
 
-// worktree 扩展 skills 部署到沙箱的白名单：init 只在 workspace 根执行
-// （由 installWorkspaceConfig 部署），沙箱内只需 push（推送）与 close（关闭）
-const SANDBOX_WORKTREE_SKILLS = ['cbb-worktree-push', 'cbb-worktree-close'];
+// worktree 管理 skill 清单：init / close / push 三件套（SKILL.md + scripts）。
+// 按 skill 形态部署到各工具的 skillsDir，使这三个能力可被 AI 在对话中自动触发
+// （description 驱动），同时工具也会把它们暴露为斜杠命令供用户手动指定。
+const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
+
+// 装到空间的 tools skills：当前不分发。
+// cbb-design-to-wiki（Wiki 发布）与 cbb-wiki-ops 保留在源仓库，需要时加入本清单即恢复分发；Java 工具不装。
+const TOOLS_SKILLS = [];
 
-// 装到沙箱的 tools skills：仅 cbb-design-to-wiki（openspec 设计阶段动作）。
-// cbb-wiki-ops 当前不分发（保留在源仓库，有用户需要时再加入 USER_LEVEL_SKILLS）；Java 工具不装。
-const SANDBOX_TOOLS_SKILLS = ['cbb-design-to-wiki'];
+// 不随安装分发的官方 OpenSpec 命令（源仓库保留，仍由 CLI 接管升级）：
+// onboard 为新手引导教程，团队入门已由文档覆盖；sync 是 archive 流程承重件，保留分发。
+const OPENSPEC_COMMANDS_EXCLUDE = ['onboard.md'];
 
 // settings.json hook 工具
 const settingsManager = require('../utils/settings');
 
+/** 适配器的 hook 方言参数（Trae 需顶层 version 字段等差异） */
+function hookOpts(adapter) {
+  return adapter.hookDialect ? { dialect: adapter.hookDialect } : {};
+}
+
 // 清单驱动的文件清理决策（保护用户文档 CLAUDE.md / AGENTS.md 等）
 const { pathsToDelete, protectedKeptPaths } = require('./cleanup');
 
+// 规则 frontmatter 改写（Trae/CodeBuddy 需 alwaysApply: true）
+const { applyRuleRewrites } = require('./rule-rewrite');
+
 // .gitignore 条目决策（纯函数：检测/写入/卸载移除）
 const gitignore = require('../utils/gitignore');
 
@@ -109,6 +126,18 @@ function detectExistingInstall() {
   return fs.existsSync(path.join(TARGET_DIR, MANIFEST_FILE));
 }
 
+/**
+ * 判定目标目录是否为业务空间根：workspace-config.json 存在且 .git 是目录。
+ * 需求工作树内也有 workspace-config.json（tracked 副本），但其 .git 是文件（gitdir 指针），
+ * 必须以 .git 形态排除——避免「在 worktree 里误跑 cbb update」被当作空间根
+ * （误装 worktree 管理入口、在错误位置报旧导航提示）。
+ */
+function detectWorkspaceRoot() {
+  if (!fs.existsSync(path.join(TARGET_DIR, 'workspace-config.json'))) return false;
+  const gitPath = path.join(TARGET_DIR, '.git');
+  return fs.existsSync(gitPath) && fs.statSync(gitPath).isDirectory();
+}
+
 // ── 清单管理 ──────────────────────────────────────────────
 
 /** 读取清单，返回 Set<path> */
@@ -193,6 +222,39 @@ function removePath(targetPath) {
   }
 }
 
+/**
+ * 清理因删除文件/目录而变空的祖先目录（从深到浅，止于 TARGET_DIR）。
+ *
+ * 删除清单路径只删到该路径本身，其父目录会留空（如改名后残留的空 `.cbb/skills/`）。
+ * 此处统一收尾，升级与卸载共用。仅删除「存在且为空」的目录，非空目录（含用户文件）
+ * 一律保留。
+ *
+ * @param {Iterable<string>} relativePaths 已删除的相对路径（正斜杠）
+ * @returns {string[]} 实际删除的空目录相对路径
+ */
+function cleanupEmptyParentDirs(relativePaths) {
+  const dirsToCheck = new Set();
+  for (const relativePath of relativePaths) {
+    let dir = path.dirname(relativePath);
+    while (dir && dir !== '.') {
+      dirsToCheck.add(dir);
+      dir = path.dirname(dir);
+    }
+  }
+
+  const removed = [];
+  [...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);
+        removed.push(dir);
+      }
+    });
+  return removed;
+}
+
 /**
  * 安全删除目标路径（文件或目录）
  * 在清单中 → 直接删除（本包旧版本）
@@ -290,7 +352,8 @@ function deployCoreRules(adapter, isUpgrade, managedPaths) {
       // 同名文件存在时直接覆盖
       removePath(destPath);
 
-      fs.writeFileSync(destPath, fs.readFileSync(srcPath, 'utf-8'));
+      const content = applyRuleRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'));
+      fs.writeFileSync(destPath, content);
     }
   });
 
@@ -299,56 +362,117 @@ function deployCoreRules(adapter, isUpgrade, managedPaths) {
 // ── opencode instructions 登记 ────────────────────────────────
 
 /**
- * opencode 无原生 rules 目录：把 .opencode/rules/*.md 的 glob 登记进项目根
- * opencode.json 的 instructions（官方支持的加载方式）。
+ * opencode 无原生 rules 目录：把 rules glob 登记进 .opencode/opencode.json 的
+ * instructions（opencode V2 支持的配置位置；随 .opencode gitignore，按机器生成）。
+ * instructions 相对路径的解析基准（配置文件目录 vs 项目根）文档未写死，
+ * 故登记双 glob 对冲：任一基准下恰有一个命中，另一个空匹配。
  * - 文件不存在：创建（记入清单，卸载时整体删除）
- * - 文件存在：仅追加 pattern（幂等）；若清单显示该文件本由本包创建，则续登
- *   newPaths 防止升级清理误删；JSONC（含注释）解析失败则只提示不改写
+ * - 文件存在：幂等补齐缺失的 glob（保留用户已有 instructions）
+ * - JSONC（含注释）解析失败则只提示不改写
+ * 旧版登记在项目根 opencode.json，由 migrateLegacyInstructions 负责迁移清理。
  */
 function injectInstructions(adapter, newPaths, managedPaths) {
-  const cfgPath = path.join(TARGET_DIR, 'opencode.json');
-  const pattern = adapter.instructionsPattern;
+  const cfgPath = path.join(TARGET_DIR, adapter.instructionsFile);
+  const patterns = adapter.instructionsPatterns;
+  let cfg = {};
+  if (fs.existsSync(cfgPath)) {
+    try {
+      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    } catch (_) {
+      log(`${adapter.instructionsFile} 解析失败（可能含注释），未自动登记。请手动在 instructions 中加入 "${patterns.join('", "')}"`, 'warn');
+      return;
+    }
+    if (!cfg || typeof cfg !== 'object') cfg = {};
+  }
+  const list = Array.isArray(cfg.instructions) ? cfg.instructions : [];
+  const merged = [...list];
+  let added = false;
+  patterns.forEach(p => {
+    if (!merged.includes(p)) {
+      merged.push(p);
+      added = true;
+    }
+  });
   if (!fs.existsSync(cfgPath)) {
-    const cfg = { $schema: 'https://opencode.ai/config.json', instructions: [pattern] };
+    cfg.instructions = merged;
+    if (!cfg.$schema) cfg.$schema = 'https://opencode.ai/config.json';
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
     fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-    newPaths.add('opencode.json');
-    log(`生成 opencode.json 并登记 rules 加载（instructions: ${pattern}）`, 'success');
-    return;
+    newPaths.add(adapter.instructionsFile);
+    log(`生成 ${adapter.instructionsFile} 并登记 rules 加载（instructions: ${patterns.join(' | ')}）`, 'success');
+  } else if (added) {
+    cfg.instructions = merged;
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    log(`已在 ${adapter.instructionsFile} instructions 中登记 rules glob`, 'success');
   }
+  // 本包此前创建的文件：续登清单，避免升级清理误删
+  if (managedPaths.has(adapter.instructionsFile)) newPaths.add(adapter.instructionsFile);
+}
+
+/**
+ * 旧版（≤0.0.3-beta.2）把 rules glob 登记在项目根 opencode.json；迁移为
+ * .opencode/opencode.json 后需把旧 pattern 从根文件摘除（用户其余配置保留）。
+ * 根文件若由本包创建（在清单中），升级时由清单差集自动整体删除，此处只摘 pattern。
+ */
+function migrateLegacyInstructions(adapter) {
+  const legacyPattern = adapter.legacyInstructionsPattern;
+  if (!legacyPattern) return;
+  const cfgPath = path.join(TARGET_DIR, 'opencode.json');
+  if (!fs.existsSync(cfgPath)) return;
   let cfg;
   try {
     cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
   } catch (_) {
-    log(`opencode.json 解析失败（可能含注释），未自动登记。请手动在 instructions 中加入 "${pattern}"`, 'warn');
+    log('根 opencode.json 解析失败（可能含注释），未自动迁移旧登记。可手动移除 instructions 中的 "' + legacyPattern + '"', 'warn');
     return;
   }
-  const list = Array.isArray(cfg.instructions) ? cfg.instructions : [];
-  if (!list.includes(pattern)) {
-    cfg.instructions = [...list, pattern];
+  if (Array.isArray(cfg.instructions) && cfg.instructions.includes(legacyPattern)) {
+    cfg.instructions = cfg.instructions.filter(p => p !== legacyPattern);
+    if (cfg.instructions.length === 0) delete cfg.instructions;
     fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-    log(`已在 opencode.json instructions 中登记 ${pattern}`, 'success');
+    log('已从根 opencode.json 移除旧版 rules 登记（迁移至 .opencode/opencode.json）', 'success');
   }
-  // 本包此前创建的文件：续登清单，避免升级清理误删
-  if (managedPaths.has('opencode.json')) newPaths.add('opencode.json');
 }
 
-/** 卸载时移除本包登记的 instructions pattern（用户创建的 opencode.json 只删 pattern 不删文件） */
+/** 卸载时移除本包登记的 instructions（用户自建配置只摘本包 glob，不删文件） */
 function removeInstructionsRegistrations() {
   adapters.forEach(adapter => {
-    if (!adapter.instructionsPattern) return;
-    const cfgPath = path.join(TARGET_DIR, 'opencode.json');
-    if (!fs.existsSync(cfgPath)) return;
-    let cfg;
-    try {
-      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
-    } catch (_) {
-      return; // 不可解析的文件不动
+    if (!adapter.instructionsFile) return;
+    const patterns = adapter.instructionsPatterns;
+    // 新位置：.opencode/opencode.json（cbb 创建的整体文件由清单删除兜底）
+    const cfgPath = path.join(TARGET_DIR, adapter.instructionsFile);
+    if (fs.existsSync(cfgPath)) {
+      let cfg;
+      try {
+        cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+      } catch (_) {
+        cfg = null; // 不可解析的文件不动
+      }
+      if (cfg && Array.isArray(cfg.instructions)) {
+        const filtered = cfg.instructions.filter(p => !patterns.includes(p));
+        if (filtered.length !== cfg.instructions.length) {
+          if (filtered.length === 0) delete cfg.instructions;
+          else cfg.instructions = filtered;
+          fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+          log(`${adapter.instructionsFile}: 移除本包登记的 instructions，保留用户配置`, 'success');
+        }
+      }
     }
-    if (Array.isArray(cfg.instructions) && cfg.instructions.includes(adapter.instructionsPattern)) {
-      cfg.instructions = cfg.instructions.filter(p => p !== adapter.instructionsPattern);
-      if (cfg.instructions.length === 0) delete cfg.instructions;
-      fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-      log('opencode.json: 移除本包登记的 instructions，保留用户配置', 'success');
+    // 旧位置：项目根 opencode.json（未升级就卸载的老空间，或迁移残留）
+    const legacyPath = path.join(TARGET_DIR, 'opencode.json');
+    if (adapter.legacyInstructionsPattern && fs.existsSync(legacyPath)) {
+      let legacyCfg;
+      try {
+        legacyCfg = JSON.parse(fs.readFileSync(legacyPath, 'utf-8'));
+      } catch (_) {
+        return; // 不可解析的文件不动
+      }
+      if (Array.isArray(legacyCfg.instructions) && legacyCfg.instructions.includes(adapter.legacyInstructionsPattern)) {
+        legacyCfg.instructions = legacyCfg.instructions.filter(p => p !== adapter.legacyInstructionsPattern);
+        if (legacyCfg.instructions.length === 0) delete legacyCfg.instructions;
+        fs.writeFileSync(legacyPath, JSON.stringify(legacyCfg, null, 2) + '\n');
+        log('opencode.json: 移除本包登记的旧版 instructions，保留用户配置', 'success');
+      }
     }
   });
 }
@@ -483,13 +607,59 @@ function deployCommandFiles(adapter, srcDir, destDir, prefix, filter) {
     const srcPath = path.join(srcDir, f);
     const destPath = path.join(destDir, prefix + f);
     removePath(destPath);
-    const content = applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'));
+    const content = rewriteCommandName(adapter, sanitizeCommandFrontmatter(applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'))));
     fs.writeFileSync(destPath, content);
   });
 
   return { count: commandFiles.length, names: commandFiles.map(f => prefix + f) };
 }
 
+/**
+ * 命令 frontmatter 消毒：opencode 新版校验命令配置（description 必须为 string | undefined），
+ * 上游个别命令（openspec/commands/update.md）的 description 为空值（YAML 解析为 null），
+ * 会导致 opencode 拒绝加载整个项目配置。此处对部署副本回填正文首句作为描述
+ * （超过 120 字截断），上游源文件不动（CLI 接管区）。
+ */
+function sanitizeCommandFrontmatter(content) {
+  const lines = content.split('\n');
+  if ((lines[0] || '').trim() !== '---') return content;
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if ((lines[i] || '').trim() === '---') { end = i; break; }
+  }
+  if (end === -1) return content;
+  let sentence = '';
+  for (let i = end + 1; i < lines.length; i++) {
+    const t = (lines[i] || '').trim();
+    if (t) { sentence = t; break; }
+  }
+  let changed = false;
+  for (let i = 1; i < end; i++) {
+    if (/^description:\s*(null|~)?\s*\r?$/.test(lines[i])) {
+      if (sentence) {
+        if (sentence.length > 120) sentence = sentence.slice(0, 117) + '...';
+        lines[i] = 'description: ' + JSON.stringify(sentence) + (lines[i].endsWith('\r') ? '\r' : '');
+      } else {
+        lines[i] = null; // 无正文可回填则移除（undefined 同样合法）
+      }
+      changed = true;
+    }
+  }
+  return changed ? lines.filter(l => l !== null).join('\n') : content;
+}
+
+/**
+ * opencode 命令显示名取自 frontmatter name，上游为大写空格风格（"OPSX: Propose"），
+ * 与文档写法（/opsx-propose）不一致；部署副本统一重写为 kebab-case。
+ */
+function rewriteCommandName(adapter, content) {
+  if (!adapter.commandNameKebab) return content;
+  return content.replace(/^name:\s*"?([A-Za-z]+):\s*([^"\r\n]+?)"?\s*\r?$/m, (m0, ns, rest) => {
+    const kebab = (ns + '-' + rest).toLowerCase().replace(/\s+/g, '-');
+    return `name: "${kebab}"`;
+  });
+}
+
 /** 官方 OpenSpec 命令（openspec/commands/ → adapter.commandsDir） */
 function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
   if (!adapter.commandsDir) return { count: 0, names: [] };
@@ -497,13 +667,6 @@ function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
     adapter, srcDir, path.join(TARGET_DIR, adapter.commandsDir), adapter.commandPrefix || '', filter);
 }
 
-/** worktree 管理命令（cbb/worktrees/commands/ → adapter.worktreeCommandsDir） */
-function deployWorktreeCommands(adapter, srcDir, filter) {
-  if (!adapter.worktreeCommandsDir) return { count: 0, names: [] };
-  return deployCommandFiles(
-    adapter, srcDir, path.join(TARGET_DIR, adapter.worktreeCommandsDir), adapter.worktreeCommandPrefix || '', filter);
-}
-
 // ── 设置 OpenSpec 工作流 ──────────────────────────────────
 
 /**
@@ -801,7 +964,7 @@ async function detectUserLevelSuperpowers(selectedAdapters, yes = false) {
 // ── 主流程 ────────────────────────────────────────────────
 
 async function init(targetDir, options = {}) {
-  const { yes = false } = options;
+  const { yes = false, selectedAdapters: presetAdapters = null } = options;
 
   // 允许调用方指定目标目录（cbb setup 在拉好仓库后切到仓库根调用）。
   // 不传则保持模块级 TARGET_DIR（即调用 init 时的 cwd）。
@@ -812,16 +975,33 @@ async function init(targetDir, options = {}) {
   const action = isUpgrade ? '升级' : '安装';
   const managedPaths = readManifest();
   const newPaths = new Set();
+  const isWorkspaceRoot = detectWorkspaceRoot();
 
   console.log(`\n  🚀 ${action} @jspg-ai/coding-bb...\n`);
 
   // 先选适配器：后续的前置依赖检测仅针对所选适配器，避免误导（如选了 Qoder 却提示安装 Claude Code 的 Superpowers）
   // 非交互模式判断：显式 -y/--yes 或 stdin 非 TTY（pipe/ignore）均视为非交互
+  // 选择优先级：调用方预设（cbb setup）> .last-tools（非交互沿用）> 交互选择；无记录才回退全选
   const isNonInteractive = yes || !process.stdin.isTTY;
-  if (yes && process.stdin.isTTY) {
-    log('--yes 非交互模式，已默认选中所有适配器', 'info');
+  let selectedAdapters;
+  if (presetAdapters && presetAdapters.length > 0) {
+    selectedAdapters = presetAdapters;
+  } else if (isNonInteractive) {
+    const lastTools = readLastTools();
+    const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
+    selectedAdapters = reused.length > 0 ? reused : adapters;
+    if (yes && process.stdin.isTTY) {
+      log(reused.length > 0
+        ? `--yes 非交互模式，沿用上次工具选择：${reused.map(a => a.displayName).join('、')}`
+        : '--yes 非交互模式，无上次选择记录，已默认选中所有适配器', 'info');
+    }
+  } else {
+    selectedAdapters = await selectTools(isUpgrade);
+  }
+  // 业务空间根记录本次选择，供 cbb update 等非交互场景沿用
+  if (isWorkspaceRoot && presetAdapters && presetAdapters.length > 0) {
+    saveLastTools(selectedAdapters);
   }
-  const selectedAdapters = isNonInteractive ? adapters : await selectTools(isUpgrade);
 
   // 前置依赖检测（放在选适配器之后，只检测与所选工具相关的依赖）
   const depProgress = progress('依赖');
@@ -838,9 +1018,10 @@ async function init(targetDir, options = {}) {
     newPaths.add(`${adapter.rulesDir}/cbb-coding-rule.md`);
     newPaths.add(`${adapter.rulesDir}/cbb-priority.md`);
     newPaths.add(`${adapter.rulesDir}/cbb-ai-behavior.md`);
-    // opencode：rules glob 登记进项目根 opencode.json instructions
-    if (adapter.instructionsPattern) {
+    // opencode：rules glob 登记进 .opencode/opencode.json instructions，并迁移根文件旧登记
+    if (adapter.instructionsFile) {
       injectInstructions(adapter, newPaths, managedPaths);
+      migrateLegacyInstructions(adapter);
     }
   });
   log(`核心规则 → ${selectedAdapters.map(a => a.rulesDir).join(', ')} (2 个文件)`, 'success');
@@ -850,11 +1031,10 @@ async function init(targetDir, options = {}) {
   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;
+    let stdCount = 0, extCount = 0;
     skillsAdapters.forEach(adapter => {
       // 通用编码规范 Skills（cbb/dev-standards/skills）
       const stdResult = deploySkills(adapter, isUpgrade, managedPaths, standardsSkillsSrc);
@@ -864,23 +1044,30 @@ async function init(targetDir, options = {}) {
       }
       // 官方 OpenSpec Skills（openspec/skills/）不部署——工作流入口统一为 /opsx:* 斜杠命令
       //（openspec/commands/ 在下方 Commands 段部署），避免双形态重复
-      // worktree 扩展 Skills：沙箱内只需 push / close（init 由 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);
+      // 工具 Skills：当前不分发（恢复方式见 TOOLS_SKILLS 注释）
+      const extResult = deploySkills(adapter, isUpgrade, managedPaths, extendsSkillsSrc, 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');
 
+    // 部署 worktree 管理 Skills（init / close / push；skill 形态，可被对话自动触发）
+    const worktreeSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
+    let wtCount = 0;
+    if (fs.existsSync(worktreeSkillsSrc)) {
+      skillsAdapters.forEach(adapter => {
+        const wtResult = deploySkills(adapter, isUpgrade, managedPaths, worktreeSkillsSrc, WORKTREE_SKILLS);
+        if (wtResult.count > 0) {
+          wtCount = wtResult.count;
+          wtResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+        }
+      });
+      if (wtCount > 0) log(`Worktree Skills → ${skillsDests.join(', ')} (${wtCount} 个)`, 'success');
+    }
+
     // 部署 Superpowers Skills（白名单：openspec 工作流依赖 + 方法论基底）
     const superpowersSkillsSrc = superpowers.SUPERPOWERS_SKILLS_DIR;
     let spCount = 0;
@@ -902,33 +1089,26 @@ async function init(targetDir, options = {}) {
     await detectUserLevelSuperpowers(selectedAdapters, yes);
   }
 
-  // 安装 Commands（官方 12 个 → /opsx:*；worktree 管理 → /cbb:worktree-*，
-  // 仅装 close/push，init 只在 workspace 根使用，由 installWorkspaceConfig 部署）
+  // 安装 Commands（官方 11 个 → /opsx:*，onboard 不分发）
   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 = ['worktree-close.md', 'worktree-push.md'];
+    const openspecCmdInclude = fs.readdirSync(commandsBaseSrc)
+      .filter(f => f.endsWith('.md') && !OPENSPEC_COMMANDS_EXCLUDE.includes(f));
 
     const cmdDests = [...new Set(commandsAdapters
-      .flatMap(a => [a.commandsDir, a.worktreeCommandsDir])
+      .map(a => a.commandsDir)
       .filter(Boolean))];
     let cmdCount = 0;
     commandsAdapters.forEach(adapter => {
       let adapterCmdCount = 0;
-      // 官方 Commands（openspec/commands/）— 始终部署
-      const baseResult = deployCommands(adapter, isUpgrade, managedPaths, commandsBaseSrc);
+      // 官方 Commands（openspec/commands/）— 部署除不分发清单外的全部
+      const baseResult = deployCommands(adapter, isUpgrade, managedPaths, commandsBaseSrc, openspecCmdInclude);
       if (baseResult.count > 0) {
         adapterCmdCount += baseResult.count;
         baseResult.names.forEach(name => newPaths.add(`${adapter.commandsDir}/${name}`));
       }
-      // worktree 管理 Commands（cbb/worktrees/commands/）
-      const extResult = deployWorktreeCommands(adapter, commandsExtendsSrc, cmdFilter);
-      if (extResult.count > 0) {
-        adapterCmdCount += extResult.count;
-        extResult.names.forEach(name => newPaths.add(`${adapter.worktreeCommandsDir}/${name}`));
-      }
       cmdCount = Math.max(cmdCount, adapterCmdCount);
     });
     if (cmdCount > 0) log(`Commands → ${cmdDests.join(', ')} (${cmdCount} 个)`, 'success');
@@ -948,6 +1128,15 @@ async function init(targetDir, options = {}) {
   setupOpenSpec(isUpgrade, managedPaths);
   newPaths.add('openspec/config.yaml');
 
+  // 业务空间根专属：空间导航 AGENTS.md（仅缺失时生成，永不覆盖）+ 旧版导航文案提示
+  let agentsMdState = null;
+  if (isWorkspaceRoot) {
+    agentsMdState = workspaces.ensureWorkspaceAgentsMd(TARGET_DIR);
+    if (workspaces.detectLegacyAgentsMd(TARGET_DIR)) {
+      log('空间根 AGENTS.md 仍是旧版导航文案（单层安装改造前模板）。建议删除该文件后重跑 cbb update 重新生成（仅缺失时生成，不会覆盖你的增补内容）', 'warn');
+    }
+  }
+
   // 写入自动版本检查 hook
   const hookAdapters = selectedAdapters.filter(a => a.settingsFile && a.hookEvents);
   if (hookAdapters.length > 0) {
@@ -958,9 +1147,9 @@ async function init(targetDir, options = {}) {
       const settingsPath = adapter.settingsFileIsUserLevel
         ? adapter.settingsFile
         : path.join(TARGET_DIR, adapter.settingsFile);
-      settingsManager.addHooks(settingsPath, command, adapter.hookEvents);
+      settingsManager.addHooks(settingsPath, command, adapter.hookEvents, hookOpts(adapter));
       // 清理旧版本遗留的 SessionStart hook（现已仅安装 UserPromptSubmit）
-      if (settingsManager.removeLegacyHooks(settingsPath)) {
+      if (settingsManager.removeLegacyHooks(settingsPath, hookOpts(adapter))) {
         log(`清理 ${adapter.displayName} 遗留的 SessionStart hook`, 'success');
       }
       if (!adapter.settingsFileIsUserLevel) newPaths.add(adapter.settingsFile);
@@ -985,6 +1174,8 @@ async function init(targetDir, options = {}) {
       if (oldPaths.length > MAX_DISPLAY) {
         log(`  ... 还有 ${oldPaths.length - MAX_DISPLAY} 个`, 'dim');
       }
+      // 收尾：清掉因此变空的祖先目录（如改名后残留的空 .cbb/skills/）
+      cleanupEmptyParentDirs(oldPaths).forEach(dir => log(`  清理空目录 ${dir}/`, 'dim'));
     }
 
     const kept = protectedKeptPaths(managedPaths, newPaths);
@@ -1015,7 +1206,7 @@ async function init(targetDir, options = {}) {
   console.log(`\n  ✅ ${action}完成！\n`);
 
   if (yes) {
-    console.log(c('dim', '  （使用 --yes 非交互模式，已默认选中所有适配器）'));
+    console.log(c('dim', `  （使用 --yes 非交互模式，工具：${selectedAdapters.map(a => a.displayName).join('、')}）`));
   }
 
   // 适配器映射（单行）
@@ -1045,161 +1236,13 @@ async function init(targetDir, options = {}) {
   if (hasSkills) extras.push('Skills');
   if (hasCommands) extras.push('Commands');
   if (hasHooks) extras.push('版本检查 hook');
+  if (agentsMdState === 'created') extras.push('AGENTS.md（空间导航）');
   if (extras.length > 0) {
     console.log(`  ${extras.join(' / ')} 已配置`);
   }
   console.log('');
 }
 
-/**
- * 为 workspace 根目录安装 AI 配置子集（由 cbb setup 调用）。
- *
- * 只装 worktree 生命周期管理（init/close/push）+ openspec 运行时配置 + 空间导航
- * AGENTS.md（仅缺失时生成，永不覆盖），不装 base 工作流、编码规范、superpowers、
- * 版本检查 hook--这些属于 sandbox worktree 内的开发配置，由 worktree 内
- * `cbbm init --yes` 完整模式安装。在 workspace 根目录
- * （主分支）装 base 工作流会诱导绕过 worktree 直接在主分支做需求开发。
- */
-async function installWorkspaceConfig(targetDir, options = {}) {
-  const { yes = false, selectedAdapters: presetAdapters = null } = options;
-  if (targetDir) TARGET_DIR = targetDir;
-
-  const isUpgrade = detectExistingInstall();
-  const managedPaths = readManifest();
-  const newPaths = new Set();
-
-  let selectedAdapters;
-  if (presetAdapters && presetAdapters.length > 0) {
-    // cbb setup 场景：上层已交互选定适配器，持久化供 cbb update 预选
-    selectedAdapters = presetAdapters;
-    saveLastTools(selectedAdapters);
-  } else {
-    const isNonInteractive = yes || !process.stdin.isTTY;
-    if (isNonInteractive) {
-      // 非交互（cbb update / 管道运行）：沿用上次工具选择，避免误装未使用的适配器
-      const lastTools = readLastTools();
-      const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
-      if (reused.length > 0) {
-        selectedAdapters = reused;
-      } else {
-        selectedAdapters = adapters;
-      }
-    } else {
-      selectedAdapters = await selectTools(isUpgrade);
-    }
-  }
-  // 只装 worktree 生命周期管理 Skills（init/close/push）
-  const skillsAdapters = selectedAdapters.filter(a => a.skillsDir);
-  const commandsAdapters = selectedAdapters.filter(a => a.worktreeCommandsDir);
-  let skillCount = 0;
-  let cmdCount = 0;
-  let adapterRoots = [];
-
-  // 「AI 配置」阶段心跳：检查依赖 → 部署 skills/commands → 写入 openspec 配置 → 生成导航。
-  // 其中 npm 查询/安装最长可达分钟级，必须让用户看到进程仍活着；任何异常先清掉进度行。
-  const cfgProgress = progress('AI 配置');
-  let agentsMdState = 'exists';
-  let openspecRes;
-  try {
-    await ensureOpenSpecCli(t => cfgProgress.update(t));
-
-    if (skillsAdapters.length > 0) {
-      cfgProgress.update('部署 skills');
-      const openspecExtendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
-      const osExtFilter = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
-      skillsAdapters.forEach(adapter => {
-        const r = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, osExtFilter);
-        if (r.count > 0) {
-          skillCount = Math.max(skillCount, r.count);
-          r.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
-        }
-      });
-      adapterRoots = skillsAdapters.map(a => a.skillsDir.split('/')[0]);
-    }
-
-    // 只装 worktree 管理 Commands（cbb:worktree-init/close/push）
-    if (commandsAdapters.length > 0) {
-      cfgProgress.update('部署 worktree 命令');
-      const commandsExtendsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'commands');
-      const cmdFilter = ['worktree-init.md', 'worktree-close.md', 'worktree-push.md'];
-      commandsAdapters.forEach(adapter => {
-        const r = deployWorktreeCommands(adapter, commandsExtendsSrc, cmdFilter);
-        if (r.count > 0) {
-          cmdCount = Math.max(cmdCount, r.count);
-          r.names.forEach(name => newPaths.add(`${adapter.worktreeCommandsDir}/${name}`));
-        }
-      });
-      if (adapterRoots.length === 0) adapterRoots = commandsAdapters.map(a => a.worktreeCommandsDir.split('/')[0]);
-    }
-
-    // 设置 OpenSpec 工作流（config.yaml + schemas）
-    cfgProgress.update('写入 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}`));
-      }
-    });
-    openspecRes = setupOpenSpec(isUpgrade, managedPaths);
-    newPaths.add('openspec/config.yaml');
-
-    // 空间导航文件 AGENTS.md：仅缺失时生成，永不覆盖（不登记清单，卸载不删）
-    cfgProgress.update('生成空间导航');
-    agentsMdState = workspaces.ensureWorkspaceAgentsMd(TARGET_DIR);
-  } finally {
-    cfgProgress.done();
-  }
-
-  // 升级时清理旧路径（workspace 曾装过的 base 工作流等不属于此子集，删除）
-  const cleaned = [];
-  const keptDocs = [];
-  if (isUpgrade) {
-    const oldPaths = pathsToDelete(managedPaths, newPaths);
-    oldPaths.forEach(oldPath => {
-      const targetPath = path.join(TARGET_DIR, oldPath);
-      if (fs.existsSync(targetPath)) {
-        removePath(targetPath);
-        cleaned.push(oldPath);
-      }
-    });
-    keptDocs.push(...protectedKeptPaths(managedPaths, newPaths));
-    (skillsAdapters || []).forEach(adapter => {
-      const legacyNodeModules = path.join(TARGET_DIR, adapter.skillsDir, 'node_modules');
-      if (fs.existsSync(legacyNodeModules)) {
-        removePath(legacyNodeModules);
-        cleaned.push(`${adapter.skillsDir}/node_modules`);
-      }
-    });
-  }
-
-  writeManifest(newPaths, selectedAdapters);
-  updateGitignore();
-
-  // 汇总输出（一行主结果 + 可选清理/保留明细）
-  const rootLabel = [...new Set(adapterRoots)].join('/');
-  const parts = [];
-  if (skillCount > 0) parts.push(`${rootLabel} skills×${skillCount}`);
-  if (cmdCount > 0) parts.push(`commands×${cmdCount}`);
-  if (openspecRes.installed.length > 0) {
-    parts.push(`openspec ${openspecRes.defaultSchema || openspecRes.installed.join('/')}`);
-  }
-  if (agentsMdState === 'created') parts.push('AGENTS.md（空间导航）');
-  const configLabel = 'AI 配置';
-  step('✓', configLabel, parts.join(' · '));
-  if (cleaned.length > 0) {
-    const MAX_DISPLAY = 3;
-    const preview = cleaned.slice(0, MAX_DISPLAY).join('、');
-    step('!', '清理残留', `${cleaned.length} 个（${preview}${cleaned.length > MAX_DISPLAY ? ' 等' : ''}）`,
-      { iconColor: 'yellow' });
-  }
-  if (keptDocs.length > 0) {
-    step('!', '保留文档', `${keptDocs.join('、')}（本包已不再管理）`, { iconColor: 'yellow' });
-  }
-}
-
 // ── cbb setup 命令 ──────────────────────────────────────
 
 /**
@@ -1521,9 +1564,9 @@ async function initSingleWorkspace(w, opts = {}) {
     return { ok: true, subdir: subdirName, upToDate: true };
   }
 
-  // 6. 安装 workspace AI 配置子集（worktree 管理技能/命令 + openspec 配置，不含 base 工作流）
+  // 6. 安装空间 AI 配置（单层全量：开发配置 + worktree 管理，统一安装器自动识别空间根）
   try {
-    await installWorkspaceConfig(targetDir, { yes: true, selectedAdapters: opts.selectedAdapters });
+    await init(targetDir, { yes: true, selectedAdapters: opts.selectedAdapters });
     return { ok: true, subdir: subdirName };
   } catch (e) {
     step('✗', 'AI 配置', e.message, { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
@@ -1717,8 +1760,8 @@ async function setupUserLevelComponents(targetAdapters = adapters) {
   if (hookAdapters.length > 0) {
     const command = settingsManager.getCheckUpdateCommand();
     hookAdapters.forEach(adapter => {
-      settingsManager.addHooks(adapter.settingsFile, command, adapter.hookEvents);
-      settingsManager.removeLegacyHooks(adapter.settingsFile);
+      settingsManager.addHooks(adapter.settingsFile, command, adapter.hookEvents, hookOpts(adapter));
+      settingsManager.removeLegacyHooks(adapter.settingsFile, hookOpts(adapter));
     });
     summaryParts.push(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join('、')}`);
   }
@@ -1733,13 +1776,16 @@ async function setupUserLevelComponents(targetAdapters = adapters) {
 }
 
 /**
- * cbb update：按现有安装模式升级当前目录内容 + 用户级组件。
+ * cbb update：就地升级当前目录内容 + 用户级组件。
  *
- * 安装模式判定：清单含 rules 路径 → 完整模式（worktree 沙箱/单项目），
- * 否则为 workspace 子集模式（空间根，只装 worktree 管理 + openspec 配置）。
+ * 单层安装：统一安装器按空间根判定（workspace-config.json + .git 目录）补齐
+ * worktree 管理入口与空间导航；旧子集清单升级时由清单差集机制自动补齐全量内容。
  */
 async function updateInstalled() {
-  await setupUserLevelComponents();
+  // 用户级组件沿用本目录的工具选择（.last-tools），无记录或为空才回退全量
+  const lastTools = readLastTools();
+  const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
+  await setupUserLevelComponents(reused.length > 0 ? reused : adapters);
 
   const manifest = readManifest();
   if (manifest.size === 0) {
@@ -1747,17 +1793,7 @@ async function updateInstalled() {
     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, {});
-  }
+  await init(undefined, {});
 }
 
 // ── 卸载 ──────────────────────────────────────────────────
@@ -1841,7 +1877,7 @@ async function uninstallUserLevelComponents() {
   // 移除版本检查 hook（保留用户其余配置）
   adapters.forEach(adapter => {
     if (!adapter.settingsFile || !adapter.hookEvents) return;
-    if (settingsManager.removeHooks(adapter.settingsFile, adapter.hookEvents)) {
+    if (settingsManager.removeHooks(adapter.settingsFile, adapter.hookEvents, hookOpts(adapter))) {
       log(`${adapter.settingsFile}: 移除版本检查 hook，保留用户配置`, 'success');
     }
   });
@@ -1872,7 +1908,7 @@ async function uninstall() {
   // 是否同时卸载用户级组件（工具 skills + 版本检查 hook，作用于 ~/.claude 等用户目录）
   let removeUserLevel = false;
   if (fs.existsSync(USER_MANIFEST_FILE)) {
-    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder 的版本检查 hook）？(y/N): ');
+    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder、~/.codebuddy、~/.trae-cn 的版本检查 hook）？(y/N): ');
     removeUserLevel = answerUser.toLowerCase() === 'y' || answerUser.toLowerCase() === 'yes';
   }
 
@@ -1891,11 +1927,11 @@ async function uninstall() {
       : path.join(TARGET_DIR, adapter.settingsFile);
     // 项目级：需在清单中才处理
     if (!adapter.settingsFileIsUserLevel && !managedPaths.has(adapter.settingsFile)) return;
-    if (removeUserLevel && settingsManager.removeHooks(settingsPath, adapter.hookEvents)) {
+    if (removeUserLevel && settingsManager.removeHooks(settingsPath, adapter.hookEvents, hookOpts(adapter))) {
       log(`${adapter.settingsFile}: 移除版本检查 hook，保留用户配置`, 'success');
     }
     // 清理旧版本遗留的 SessionStart hook（无版本差异，无条件清理）
-    if (settingsManager.removeLegacyHooks(settingsPath)) {
+    if (settingsManager.removeLegacyHooks(settingsPath, hookOpts(adapter))) {
       log(`${adapter.settingsFile}: 清理遗留 SessionStart hook`, 'success');
     }
     skippedPaths.add(adapter.settingsFile);
@@ -1920,22 +1956,7 @@ async function uninstall() {
   });
 
   // 清理可能变空的父目录（从深到浅）
-  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');
-    }
-  });
+  cleanupEmptyParentDirs(managedPaths).forEach(dir => log(`清理空目录 ${dir}/`, 'success'));
 
   // 删除清单文件和 .va 目录
   removePath(manifestDir);
@@ -1953,11 +1974,50 @@ async function uninstall() {
   console.log(`\n✅ 卸载完成！共移除 ${removed} 个文件/目录\n`);
 }
 
+// ── 上游版本检查 ──────────────────────────────────────────────
+
+/**
+ * 检查 openspec / superpowers 是否有上游新版本（只读，不改动任何文件）。
+ * 供 cbbm check-upstream 调用。
+ */
+async function checkUpstream() {
+  const results = await Promise.allSettled([
+    openspec.checkUpstream().then(r => ({ name: 'openspec', ...r })),
+    superpowers.checkUpstream().then(r => ({ name: 'superpowers', ...r })),
+  ]);
+
+  let outdated = false;
+  for (const r of results) {
+    if (r.status === 'rejected') {
+      log(`检查失败: ${r.reason.message}`, 'error');
+      continue;
+    }
+    const { name, current, latest, outdated: isOutdated } = r.value;
+    if (!latest) {
+      log(`${name}: 无法获取上游版本`, 'warn');
+      continue;
+    }
+    if (!current) {
+      log(`${name}: 本地无 pin（上游最新 ${latest}）`, 'warn');
+      outdated = true;
+    } else if (isOutdated) {
+      log(`${name}: ${current} → ${latest}（有新版本）`, 'warn');
+      outdated = true;
+    } else {
+      log(`${name}: ${current} 已是最新`, 'success');
+    }
+  }
+
+  if (outdated) {
+    log('升级方式：修改对应 .version 的 pin 后，执行 cbbm update --upstream-openspec / --upstream-superpowers', 'info');
+  }
+}
+
 // ── CLI 入口 ──────────────────────────────────────────────
 
 // 入口身份：cbb（用户命令） / cbbm（内部命令，由流程、hook、Agent 技能调用）
 const ENTRY = process.env.CBB_ENTRY === 'cbbm' ? 'cbbm' : 'cbb';
-const INTERNAL_COMMANDS = ['init', 'check-update', 'wiki', 'wp'];
+const INTERNAL_COMMANDS = ['check-update', 'check-upstream', 'wiki', 'wp'];
 const UPSTREAM_FLAGS = ['--upstream-superpowers', '--upstream-openspec'];
 
 const args = process.argv.slice(2);
@@ -1996,11 +2056,11 @@ switch (command) {
     const upstreamSuperpowers = restArgs.includes('--upstream-superpowers');
     const upstreamOpenspec = restArgs.includes('--upstream-openspec');
     if (upstreamSuperpowers || upstreamOpenspec) {
-      // 维护者选项：从 GitHub 拉取上游原生内容到本包源仓库（发布流程用）
+      // 维护者选项：按 .version 的 pin 重新拉取上游原生内容到本包源仓库（发布流程用）
       if (upstreamSuperpowers) {
         superpowers.fetchLatestSkills().then(result => {
           if (result.skipped) {
-            log(`superpowers skills 已是最新 (${result.sha.slice(0, 8)})`, 'success');
+            log(`superpowers skills 已是最新 (${result.tag})`, 'success');
           }
           const validation = superpowers.validateSkills();
           if (!validation.valid) {
@@ -2016,22 +2076,13 @@ switch (command) {
       }
       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');
+          const validation = openspec.validateDeployed();
+          if (!validation.valid) {
+            log(`部署不完整,缺失: ${validation.missing.join(', ')}`, '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);
@@ -2045,14 +2096,6 @@ switch (command) {
     }
     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');
@@ -2062,6 +2105,12 @@ switch (command) {
   case 'check-update':
     require('../utils/check-update.js');
     break;
+  case 'check-upstream':
+    checkUpstream().catch(err => {
+      log(err.message, 'error');
+      process.exit(1);
+    });
+    break;
   case 'wp':
     require('../wiki/index.js').publish(restArgs);
     break;
@@ -2092,13 +2141,13 @@ function showHelp() {
     console.log(`
 @jspg-ai/coding-bb v${pkg.version} — cbbm：内部命令（由流程 / hook / Agent 技能调用）
 
-  cbbm init --yes            worktree 沙箱内安装开发配置（/cbb:worktree-init Step 4 自动调用）
   cbbm check-update          版本检查（用户级 hook 每日自动触发）
+  cbbm check-upstream        检查 openspec / superpowers 是否有上游新版本
   cbbm wiki / cbbm wp        Wiki 查询与发布（AI 通过技能调用）
 
-维护者选项（拉取上游原生内容到本包源仓库）：
-  cbbm update --upstream-superpowers    从 GitHub 拉取最新 superpowers skills
-  cbbm update --upstream-openspec       从 GitHub 拉取最新 OpenSpec 工作流
+维护者选项（按 .version 的 pin 重新拉取上游原生内容到本包源仓库）：
+  cbbm update --upstream-superpowers    按 pin tag 拉取 superpowers skills（走镜像）
+  cbbm update --upstream-openspec       按 pin 版本从 npmmirror 渲染 OpenSpec 工作流
 `);
     return;
   }