@jspg-ai/coding-bb 0.0.1 → 0.0.2-beta.22

package/cbb/lib/install/init.js

@@ -4,21 +4,25 @@
  * OpenSpec Shared Standards 安装脚本
  *
  * 将AI 编码规范与工作流套件安装到目标项目中。
- * 支持工具：Claude Code (.claude/rules/)、Qoder (.qoder/rules/)
+ * 支持工具：Claude Code (.claude/rules/)、Qoder (.qoder/rules/)、opencode (.opencode/rules/)
  *
  * 使用方式：
  *   npm install -g @jspg-ai/coding-bb  # 首次使用
  *   npm install -g @jspg-ai/coding-bb
- *   cd your-project && cbb init
+ *   cd your-project && cbbm init
  */
 
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const readline = require('readline');
-const { execSync } = require('child_process');
+const { execSync, execFile } = require('child_process');
+const { promisify } = require('util');
 const yaml = require('js-yaml');
 
+// 异步执行外部命令：长耗时 git 操作不阻塞事件循环，进度行才能持续刷新
+const execFileAsync = promisify(execFile);
+
 const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
 
 // 目标项目根目录：默认取当前 cwd，init() / initWorkspace() 可在调用前覆盖。
@@ -35,6 +39,7 @@ const LAST_TOOLS_FILE = path.join(MANIFEST_DIR, '.last-tools');
 const adapters = [
   require('./claude-code'),
   require('./qoder'),
+  require('./opencode'),
 ];
 
 // superpowers 部署白名单：仅装 openspec 工作流硬依赖 + 方法论基底（源仓库仍保留全量 14 个，
@@ -48,11 +53,12 @@ const SUPERPOWERS_WHITELIST = [
   'test-driven-development',        // TDD 计划结构 + TDD Evidence 方法论基底
 ];
 
-// worktree 扩展 skills 部署到沙箱的白名单：init/extend 只在 workspace 根执行
+// worktree 扩展 skills 部署到沙箱的白名单：init 只在 workspace 根执行
 // （由 installWorkspaceConfig 部署），沙箱内只需 push（推送）与 close（关闭）
-const SANDBOX_WORKTREE_SKILLS = ['openspec-push-worktrees', 'openspec-close-worktree'];
+const SANDBOX_WORKTREE_SKILLS = ['cbb-worktree-push', 'cbb-worktree-close'];
 
-// 装到沙箱的 tools skills：cbb-wiki-ops 装用户级（与项目无关），Java 工具不装
+// 装到沙箱的 tools skills：仅 cbb-design-to-wiki（openspec 设计阶段动作）。
+// cbb-wiki-ops 当前不分发（保留在源仓库，有用户需要时再加入 USER_LEVEL_SKILLS）；Java 工具不装。
 const SANDBOX_TOOLS_SKILLS = ['cbb-design-to-wiki'];
 
 // settings.json hook 工具
@@ -81,7 +87,7 @@ const openspec = require('../openspec');
 
 // ── 颜色与输出辅助 ──────────────────────────────────────
 
-const { COLOR, COLOR_ENABLED, c, log, section, field, LOG_STYLES } = require('../utils/output');
+const { COLOR, COLOR_ENABLED, c, log, section, step, padVisual, progress, LOG_STYLES } = require('../utils/output');
 
 // 检测是否已安装（清单文件存在即视为已安装）
 function detectExistingInstall() {
@@ -275,6 +281,63 @@ function deployCoreRules(adapter, isUpgrade, managedPaths) {
 
 }
 
+// ── opencode instructions 登记 ────────────────────────────────
+
+/**
+ * opencode 无原生 rules 目录：把 .opencode/rules/*.md 的 glob 登记进项目根
+ * opencode.json 的 instructions（官方支持的加载方式）。
+ * - 文件不存在：创建（记入清单，卸载时整体删除）
+ * - 文件存在：仅追加 pattern（幂等）；若清单显示该文件本由本包创建，则续登
+ *   newPaths 防止升级清理误删；JSONC（含注释）解析失败则只提示不改写
+ */
+function injectInstructions(adapter, newPaths, managedPaths) {
+  const cfgPath = path.join(TARGET_DIR, 'opencode.json');
+  const pattern = adapter.instructionsPattern;
+  if (!fs.existsSync(cfgPath)) {
+    const cfg = { $schema: 'https://opencode.ai/config.json', instructions: [pattern] };
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    newPaths.add('opencode.json');
+    log(`生成 opencode.json 并登记 rules 加载（instructions: ${pattern}）`, 'success');
+    return;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+  } catch (_) {
+    log(`opencode.json 解析失败（可能含注释），未自动登记。请手动在 instructions 中加入 "${pattern}"`, 'warn');
+    return;
+  }
+  const list = Array.isArray(cfg.instructions) ? cfg.instructions : [];
+  if (!list.includes(pattern)) {
+    cfg.instructions = [...list, pattern];
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    log(`已在 opencode.json instructions 中登记 ${pattern}`, 'success');
+  }
+  // 本包此前创建的文件：续登清单，避免升级清理误删
+  if (managedPaths.has('opencode.json')) newPaths.add('opencode.json');
+}
+
+/** 卸载时移除本包登记的 instructions pattern（用户创建的 opencode.json 只删 pattern 不删文件） */
+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 (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');
+    }
+  });
+}
+
 // ── YAML 配置合并 ─────────────────────────────────────────
 
 function mergeConfig(ourYaml, userYaml) {
@@ -337,6 +400,29 @@ function generateBackupPath(filePath) {
 
 // ── 部署 Skills ──────────────────────────────────────────────
 
+/**
+ * 按适配器的 contentRewrites 改写文本（opencode 侧把 /opsx:xxx 引用
+ * 改写为其扁平命令名 /opsx-xxx）。无改写规则的适配器原样返回。
+ */
+function applyContentRewrites(adapter, text) {
+  if (!adapter.contentRewrites) return text;
+  return adapter.contentRewrites.reduce((t, [from, to]) => t.split(from).join(to), text);
+}
+
+/** 递归改写目录内所有 .md 文件的适配器引用（opencode skills 部署后调用） */
+function rewriteSkillRefs(adapter, dir) {
+  if (!adapter.contentRewrites) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) rewriteSkillRefs(adapter, p);
+    else if (e.name.endsWith('.md')) {
+      const content = fs.readFileSync(p, 'utf-8');
+      const rewritten = applyContentRewrites(adapter, content);
+      if (rewritten !== content) fs.writeFileSync(p, rewritten);
+    }
+  }
+}
+
 function deploySkills(adapter, isUpgrade, managedPaths, srcDir, filter) {
   const skillsDir = adapter.skillsDir;
   if (!skillsDir || !fs.existsSync(srcDir)) return { count: 0, names: [] };
@@ -355,6 +441,7 @@ function deploySkills(adapter, isUpgrade, managedPaths, srcDir, filter) {
     const destDir = path.join(skillsDest, skillName);
     removePath(destDir);
     fs.cpSync(path.join(srcDir, skillName), destDir, { recursive: true });
+    rewriteSkillRefs(adapter, destDir);
   });
 
   return { count: skillDirs.length, names: skillDirs };
@@ -362,13 +449,15 @@ function deploySkills(adapter, isUpgrade, managedPaths, srcDir, filter) {
 
 // ── 部署 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);
+/**
+ * 部署命令文件（扁平 .md）到指定目录并加文件名前缀。
+ * opencode 侧：命令名 = 文件名，加适配器前缀扁平化（opsx-propose.md → /opsx-propose）。
+ * @returns {{count:number, names:string[]}} names 为落盘文件名（含前缀）
+ */
+function deployCommandFiles(adapter, srcDir, destDir, prefix, filter) {
+  if (!destDir || !fs.existsSync(srcDir)) return { count: 0, names: [] };
 
-  fs.mkdirSync(commandsDest, { recursive: true });
+  fs.mkdirSync(destDir, { recursive: true });
 
   // 读取所有 .md 文件（command 是扁平文件，不像 skill 是子目录）
   const commandFiles = fs.readdirSync(srcDir)
@@ -377,17 +466,37 @@ function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
 
   commandFiles.forEach(f => {
     const srcPath = path.join(srcDir, f);
-    const destPath = path.join(commandsDest, f);
+    const destPath = path.join(destDir, prefix + f);
     removePath(destPath);
-    fs.copyFileSync(srcPath, destPath);
+    const content = applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'));
+    fs.writeFileSync(destPath, content);
   });
 
-  return { count: commandFiles.length, names: commandFiles };
+  return { count: commandFiles.length, names: commandFiles.map(f => prefix + f) };
+}
+
+/** 官方 OpenSpec 命令（openspec/commands/ → adapter.commandsDir） */
+function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
+  if (!adapter.commandsDir) return { count: 0, names: [] };
+  return deployCommandFiles(
+    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 工作流 ──────────────────────────────────
 
+/**
+ * 安装 openspec/schemas/* 与 openspec/config.yaml。
+ * 不打印结果（由调用方汇总输出），返回 { schemas, config, installed, defaultSchema, removed }。
+ */
 function setupOpenSpec(isUpgrade, managedPaths) {
+  const result = { schemas: [], config: null, installed: [], defaultSchema: null, removed: [] };
   const schemasSrcs = [
     path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
   ];
@@ -421,7 +530,7 @@ function setupOpenSpec(isUpgrade, managedPaths) {
         } else if (managedPaths.has(relativePath)) {
           // 清单中有但本包不再提供 → 清理旧版本
           removePath(dest);
-          log(`移除已废弃的 openspec/schemas/${name}/`, 'success');
+          result.removed.push(`openspec/schemas/${name}`);
         }
         // 非本包且不在清单中 → 不动（用户自建）
       });
@@ -435,7 +544,7 @@ function setupOpenSpec(isUpgrade, managedPaths) {
           const srcPath = path.join(src, name);
           const dest = path.join(schemasDest, name);
           fs.cpSync(srcPath, dest, { recursive: true });
-          log(`安装 openspec/schemas/${name}/`, 'success');
+          result.schemas.push(name);
         });
     });
   }
@@ -444,7 +553,7 @@ function setupOpenSpec(isUpgrade, managedPaths) {
   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;
+  if (!fs.existsSync(configSrc)) return result;
 
   fs.mkdirSync(path.dirname(configDest), { recursive: true });
   const ourContent = fs.readFileSync(configSrc, 'utf-8');
@@ -454,21 +563,19 @@ function setupOpenSpec(isUpgrade, managedPaths) {
     const userContent = fs.readFileSync(configDest, 'utf-8');
     const merged = mergeConfig(ourContent, userContent);
     fs.writeFileSync(configDest, merged);
-    log('合并 openspec/config.yaml', 'success');
+    result.config = 'merged';
   } else {
     fs.writeFileSync(configDest, ourContent);
-    log('创建 openspec/config.yaml', 'success');
+    result.config = 'created';
   }
 
-  // 输出已安装的 schema 和可用命令
+  // 汇总已安装的 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}）`);
+    result.defaultSchema = yaml.load(fs.readFileSync(configDest, 'utf-8')).schema;
+    result.installed = fs.readdirSync(schemasDest)
+      .filter(name => fs.statSync(path.join(schemasDest, name)).isDirectory());
   }
+  return result;
 }
 
 // ── .gitignore 管理 ───────────────────────────────────────
@@ -540,26 +647,26 @@ async function ensureOpenSpecCli() {
     && version.compareVersions(latestVersion, currentVersion) > 0;
 
   if (!needInstall && !needUpgrade) {
-    log(`OpenSpec CLI: v${currentVersion} (最新)`, 'success');
-    return;
+    return { state: 'ok', version: currentVersion };
   }
 
-  // 4. 执行安装/升级
+  // 4. 执行安装/升级（耗时操作，打印进行中提示）
   const action = needInstall ? '安装' : '升级';
   const detail = needInstall
     ? `→ v${latestVersion || 'latest'}`
     : `v${currentVersion} → v${latestVersion}`;
-  log(`${action} OpenSpec CLI (${detail})...`, 'info');
+  console.log(`  ${c('gray', '⏳')} ${c('gray', `${action} OpenSpec CLI（${detail}）...`)}`);
 
   try {
     execSync(
       `npm install -g ${OPENSPEC_PKG}@latest --registry ${OPENSPEC_REGISTRY}`,
       { stdio: 'pipe', timeout: 120000 }
     );
-    log(`OpenSpec CLI ${action}完成`, 'success');
+    return { state: needInstall ? 'installed' : 'upgraded', version: latestVersion || currentVersion };
   } catch (err) {
     log(`OpenSpec CLI ${action}失败: ${err.message}`, 'error');
     log(`请手动执行: npm install -g ${OPENSPEC_PKG}@latest --registry ${OPENSPEC_REGISTRY}`, 'warn');
+    return { state: 'failed', version: currentVersion };
   }
 }
 
@@ -701,6 +808,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) {
+      injectInstructions(adapter, newPaths, managedPaths);
+    }
   });
   log(`核心规则 → ${selectedAdapters.map(a => a.rulesDir).join(', ')} (2 个文件)`, 'success');
 
@@ -723,7 +834,7 @@ async function init(targetDir, options = {}) {
       }
       // 官方 OpenSpec Skills（openspec/skills/）不部署——工作流入口统一为 /opsx:* 斜杠命令
       //（openspec/commands/ 在下方 Commands 段部署），避免双形态重复
-      // worktree 扩展 Skills：沙箱内只需 push / close（init/extend 由 workspace 根的子集安装）
+      // worktree 扩展 Skills：沙箱内只需 push / close（init 由 workspace 根的子集安装）
       const osExtResult = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, SANDBOX_WORKTREE_SKILLS);
       if (osExtResult.count > 0) {
         osCount = osExtResult.count;
@@ -761,16 +872,18 @@ async function init(targetDir, options = {}) {
     await detectUserLevelSuperpowers(selectedAdapters, yes);
   }
 
-  // 安装 Commands（官方 12 个 + worktree 扩展；worktree 命令仅装 close/push，
-  // init/extend 只在 workspace 根使用，由 installWorkspaceConfig 部署）
+  // 安装 Commands（官方 12 个 → /opsx:*；worktree 管理 → /cbb:worktree-*，
+  // 仅装 close/push，init 只在 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 cmdFilter = ['worktree-close.md', 'worktree-push.md'];
 
-    const cmdDests = commandsAdapters.map(a => a.commandsDir);
+    const cmdDests = [...new Set(commandsAdapters
+      .flatMap(a => [a.commandsDir, a.worktreeCommandsDir])
+      .filter(Boolean))];
     let cmdCount = 0;
     commandsAdapters.forEach(adapter => {
       let adapterCmdCount = 0;
@@ -780,11 +893,11 @@ async function init(targetDir, options = {}) {
         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);
+      // 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.commandsDir}/${name}`));
+        extResult.names.forEach(name => newPaths.add(`${adapter.worktreeCommandsDir}/${name}`));
       }
       cmdCount = Math.max(cmdCount, adapterCmdCount);
     });
@@ -911,67 +1024,76 @@ async function init(targetDir, options = {}) {
 /**
  * 为 workspace 根目录安装 AI 配置子集（由 cbb setup 调用）。
  *
- * 只装 worktree 生命周期管理（init/extend/close/push）+ openspec 运行时配置，
+ * 只装 worktree 生命周期管理（init/close/push）+ openspec 运行时配置，
  * 不装 base 工作流、编码规范、superpowers、版本检查 hook--这些属于 sandbox worktree
- * 内的开发配置，由 worktree 内 `cbb init --yes` 完整模式安装。在 workspace 根目录
+ * 内的开发配置，由 worktree 内 `cbbm init --yes` 完整模式安装。在 workspace 根目录
  * （主分支）装 base 工作流会诱导绕过 worktree 直接在主分支做需求开发。
  */
 async function installWorkspaceConfig(targetDir, options = {}) {
-  const { yes = false } = options;
+  const { yes = false, selectedAdapters: presetAdapters = null } = 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');
+  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);
+    }
   }
-  const selectedAdapters = isNonInteractive ? adapters : await selectTools(isUpgrade);
-  await ensureOpenSpecCli();
+  const openspecCli = await ensureOpenSpecCli();
 
-  // 只装 worktree 生命周期管理 Skills（init/extend/close/push）
+  // 只装 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 = [];
+
   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;
+    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) {
-        count += r.count;
+        skillCount = Math.max(skillCount, r.count);
         r.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
       }
     });
-    if (count > 0) log(`worktree 管理 Skills → ${skillsDests.join(', ')} (${count} 个)`, 'success');
+    adapterRoots = skillsAdapters.map(a => a.skillsDir.split('/')[0]);
   }
 
-  // 只装 worktree 管理 Commands（init/extend/close/push）
-  const commandsAdapters = selectedAdapters.filter(a => a.commandsDir);
+  // 只装 worktree 管理 Commands（cbb:worktree-init/close/push）
   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;
+    const cmdFilter = ['worktree-init.md', 'worktree-close.md', 'worktree-push.md'];
     commandsAdapters.forEach(adapter => {
-      const r = deployCommands(adapter, isUpgrade, managedPaths, commandsExtendsSrc, cmdFilter);
+      const r = deployWorktreeCommands(adapter, commandsExtendsSrc, cmdFilter);
       if (r.count > 0) {
-        count += r.count;
-        r.names.forEach(name => newPaths.add(`${adapter.commandsDir}/${name}`));
+        cmdCount = Math.max(cmdCount, r.count);
+        r.names.forEach(name => newPaths.add(`${adapter.worktreeCommandsDir}/${name}`));
       }
     });
-    if (count > 0) log(`worktree 管理 Commands → ${cmdDests.join(', ')} (${count} 个)`, 'success');
+    if (adapterRoots.length === 0) adapterRoots = commandsAdapters.map(a => a.worktreeCommandsDir.split('/')[0]);
   }
 
   // 设置 OpenSpec 工作流（config.yaml + schemas）
-  console.log(`\n  📋 设置 OpenSpec 工作流...`);
   const schemasSrcs = [
     path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
   ];
@@ -981,32 +1103,27 @@ async function installWorkspaceConfig(targetDir, options = {}) {
         .forEach(name => newPaths.add(`openspec/schemas/${name}`));
     }
   });
-  setupOpenSpec(isUpgrade, managedPaths);
+  const openspecRes = setupOpenSpec(isUpgrade, managedPaths);
   newPaths.add('openspec/config.yaml');
 
   // 升级时清理旧路径（workspace 曾装过的 base 工作流等不属于此子集，删除）
+  const cleaned = [];
+  const keptDocs = [];
   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'));
-    }
+    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);
-        log(`清理遗留 ${adapter.skillsDir}/node_modules/`, 'success');
+        cleaned.push(`${adapter.skillsDir}/node_modules`);
       }
     });
   }
@@ -1014,156 +1131,158 @@ async function installWorkspaceConfig(targetDir, options = {}) {
   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('');
+  // 汇总输出（一行主结果 + 可选清理/保留明细）
+  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('/')}`);
+  }
+  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 命令 ──────────────────────────────────────
 
 /**
- * 若 targetDir 已安装（.cbb/.managed-by-cbb 存在），输出当前版本号
- * 并尝试从 registry 查询最新版本，让用户确认是否继续。
- *  - 用户输入 n / no → 返回 false（调用方决定是跳过还是退出）
- *  - 未安装 / 查询失败 / 用户确认 → 返回 true
+ * 若 targetDir 已安装（.cbb/.managed-by-cbb 存在），比较已装版本与当前包版本决定是否继续。
+ *  - 版本一致 → 返回 'skip'（不询问、不重复安装）
+ *  - 版本不同 → 询问是否升级到当前包版本，用户拒绝返回 'cancel'
+ *  - 未安装 → 返回 'install'（不提示，直接继续）
+ *
+ * 注：只比较「已装版本 vs 当前包版本」——安装动作只能落盘当前包的产物，
+ * registry 是否有更新由用户级版本检查 hook 提醒，不在此处联网查询。
+ * @returns {Promise<'install'|'skip'|'cancel'>}
  */
 async function confirmUpgradeIfInstalled(targetDir) {
   const installed = version.readInstalledVersion(targetDir);
-  if (!installed) return true; // 未安装：不提示，直接继续
+  if (!installed) return 'install'; // 未安装：不提示，直接继续
 
-  // 根据当前包版本（而非已安装版本）决定查询哪个 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
+  // 版本未变化 → 不处理（不询问、不重复安装）
+  if (version.compareVersions(installed, pkg.version) === 0) {
+    step('✓', '版本', `v${installed}（已是最新，跳过）`);
+    return 'skip';
   }
 
-  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);
+  step('⏳', '版本', `v${installed} → v${pkg.version}`, { iconColor: 'cyan' });
+  const answer = await ask(`? 升级到 v${pkg.version}？(Y/n) `);
   if (answer && answer.toLowerCase() === 'n') {
-    log('已取消安装/升级', 'warn');
-    return false;
+    step('!', '版本', '已跳过安装/升级', { iconColor: 'yellow' });
+    return 'cancel';
   }
-  return true;
+  return 'install';
 }
 
 /**
- * 检查业务空间根目录下是否有 CONFIG.json（init-worktree 技能依赖）。
- * 不存在时，将包内样例文件复制为 CONFIG.json，提示用户编辑为实际配置。
+ * 检查业务空间根目录下是否有 workspace-config.json（init-worktree 技能依赖）。
+ * 不存在时，将包内样例文件复制为 workspace-config.json。
+ * 返回 'exists' | 'created'（不打印，由调用方汇总输出）。
  */
-function ensureWorkspaceConfig(targetDir, workspaceName) {
-  const configPath = path.join(targetDir, 'CONFIG.json');
-  if (fs.existsSync(configPath)) {
-    log(`工作空间「${workspaceName}」的 CONFIG.json 已存在，跳过初始化`, 'success');
-    return;
-  }
+function ensureWorkspaceConfig(targetDir) {
+  const configPath = path.join(targetDir, 'workspace-config.json');
+  if (fs.existsSync(configPath)) return 'exists';
 
-  // 复制样例文件作为 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');
+  return 'created';
 }
 
 /**
- * 读取 CONFIG.json 中的应用列表，将关联应用代码 clone/fetch 到 .code/ 目录。
+ * 读取 workspace-config.json 中的应用列表，将关联应用代码 clone/fetch 到 .codespace/ 目录。
  * 首次 clone（耗时较长），后续 fetch --all（秒级更新）。
  * 这是基准代码，init-worktree 技能后续只做轻量 fetch 检查。
  */
-function syncAppRepos(targetDir) {
-  const configPath = path.join(targetDir, 'CONFIG.json');
-  if (!fs.existsSync(configPath)) return;
+/**
+ * 读取 workspace-config.json，将关联应用代码 clone/fetch 到 .codespace/ 目录。
+ * 不打印逐条日志，返回汇总对象由调用方渲染：
+ *   { ok, fail, updated[], cloned[], fetchFailed[], sampleApps[], invalid[] }
+ * 长耗时（首次 clone），通过 onProgress 回调实时提示当前正在处理哪个应用。
+ * @param {string} targetDir
+ * @param {(text:string)=>void} [onProgress]
+ */
+async function syncAppRepos(targetDir, onProgress = () => {}) {
+  const summary = { ok: 0, fail: 0, updated: [], cloned: [], fetchFailed: [], sampleApps: [], invalid: [] };
+  const configPath = path.join(targetDir, 'workspace-config.json');
+  if (!fs.existsSync(configPath)) return summary;
 
   let config;
   try {
     config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   } catch (e) {
-    log('CONFIG.json 解析失败，跳过应用代码拉取', 'warn');
-    return;
+    summary.parseFailed = true;
+    return summary;
   }
 
   const apps = config.apps;
   if (!Array.isArray(apps) || apps.length === 0) {
-    log('CONFIG.json 中 apps 为空，跳过 .code/ 拉取', 'dim');
-    return;
+    summary.empty = true;
+    return summary;
   }
 
-  const codeDir = path.join(targetDir, '.code');
+  const codeDir = path.join(targetDir, '.codespace');
   fs.mkdirSync(codeDir, { recursive: true });
 
-  let ok = 0, fail = 0;
-  apps.forEach(app => {
+  const syncable = apps.filter(app => app.name && app.repo && !workspaces.isSampleRepo(app.repo));
+  let index = 0;
+
+  for (const app of apps) {
     if (!app.name || !app.repo) {
-      log(`应用 "${app.name || '(未知)'}" 缺少 name 或 repo，跳过`, 'warn');
-      fail++;
-      return;
+      summary.invalid.push(app.name || '(未知)');
+      summary.fail++;
+      continue;
+    }
+
+    // 样例占位地址（example 等保留域名）：clone 必然失败，逐条跳过并汇总提示
+    if (workspaces.isSampleRepo(app.repo)) {
+      summary.sampleApps.push(app);
+      continue;
     }
 
+    index++;
     const appDir = path.join(codeDir, app.name);
     if (fs.existsSync(path.join(appDir, '.git'))) {
       // 已存在：fetch 更新
+      onProgress(`更新 ${app.name}（${index}/${syncable.length}）`);
       try {
-        execSync('git fetch --all -q', { cwd: appDir, stdio: 'pipe', timeout: 60000 });
-        log(`${app.name}: 代码已更新（fetch --all）`, 'success');
-        ok++;
+        await execFileAsync('git', ['fetch', '--all', '-q'], { cwd: appDir, timeout: 60000 });
+        summary.updated.push(app.name);
+        summary.ok++;
       } catch (e) {
-        log(`${app.name}: fetch 失败（离线或无权限，使用本地已有代码）`, 'warn');
-        ok++; // 不算失败，用本地代码
+        summary.fetchFailed.push(app.name);
+        summary.ok++; // 不算失败，用本地代码
       }
     } else {
-      // 不存在：clone
+      // 不存在：clone（首次较慢）
+      onProgress(`克隆 ${app.name}（${index}/${syncable.length}，首次较慢）`);
       try {
-        execSync(`git clone -q "${app.repo}" "${appDir}"`, { stdio: 'pipe', timeout: 180000 });
-        log(`${app.name}: 代码已拉取（clone）`, 'success');
-        ok++;
+        await execFileAsync('git', ['clone', '-q', app.repo, appDir], { timeout: 180000 });
+        summary.cloned.push(app.name);
+        summary.ok++;
       } catch (e) {
-        log(`${app.name}: clone 失败 — ${app.repo}`, 'error');
-        fail++;
+        summary.fail++;
       }
     }
-  });
-
-  if (fail > 0) {
-    log(`应用代码拉取完成（成功 ${ok}，失败 ${fail}）`, 'warn');
-  } else {
-    log(`应用代码已就绪（${ok} 个应用 → .code/）`, 'success');
   }
+
+  return summary;
 }
 
 /**
  * 读取远程默认分支名（如 "main" / "master" / "develop"）。
  * 用 symbolic-ref refs/remotes/origin/HEAD 探测；取不到返回 null。
- * 参照 cbb/worktrees/skills/openspec-init-worktree/scripts/create-branches.js:47。
+ * 参照 cbb/worktrees/skills/cbb-worktree-init/scripts/create-branches.js:47。
  */
 function getRemoteDefaultBranch(cwd) {
   try {
@@ -1185,13 +1304,17 @@ function getRemoteDefaultBranch(cwd) {
  * 在「子目录已存在且匹配」分支同步工作空间仓库到远程默认分支的最新。
  * 流程：fetch → 检测默认分支 → 必要时切换分支 → fast-forward merge。
  * 任一步失败都抛出，由调用方走错误路径中止整个 cbb setup。
+ * fetch 可能耗时，通过 onProgress 回调实时提示。
+ * @param {string} targetDir
+ * @param {(text:string)=>void} [onProgress]
+ * @returns {Promise<string>} 同步到的默认分支名
  */
-function syncWorkspaceRepo(targetDir) {
-  // 1. fetch
+async function syncWorkspaceRepo(targetDir, onProgress = () => {}) {
+  // 1. fetch（耗时步：大型仓库首次 fetch 可能数十秒）
+  onProgress(`同步 ${path.basename(targetDir)}/（git fetch）`);
   try {
-    execSync('git fetch --all -q', {
+    await execFileAsync('git', ['fetch', '--all', '-q'], {
       cwd: targetDir,
-      stdio: 'pipe',
       timeout: 60000,
     });
   } catch (e) {
@@ -1237,112 +1360,135 @@ function syncWorkspaceRepo(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;
   }
+
+  return defaultBranch;
 }
 
 /**
- * 处理单个业务空间：展示详情 → 计算子目录 → 检测/克隆 → CONFIG.json → 拉取应用代码 → 升级询问 → init()。
- * 失败时不抛出也不退出，返回结果对象供调用方汇总。
+ * 处理单个业务空间：计算子目录 → 检测/克隆 → workspace-config.json → 拉取应用代码 → 升级询问 → 安装 AI 配置。
+ * 输出为紧凑步进行（✓ 标签 值），失败时不抛出也不退出，返回结果对象供调用方汇总。
+ * @param {object} [opts] - { selectedAdapters } cbb setup 上层选定的适配器（透传给空间级安装）
  * @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 的最后一段）
+async function initSingleWorkspace(w, opts = {}) {
+  // 1. 计算仓库子目录名（来自 repo URL 的最后一段）
   const subdirName = workspaces.extractRepoBasename(w.repo);
   if (!subdirName) {
-    log(`无法从仓库地址 "${w.repo}" 提取目录名`, 'error');
+    step('✗', '仓库', `无法从仓库地址提取目录名：${w.repo}`, { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
     return { ok: false, error: 'EXTRACT_FAILED' };
   }
 
   const parentDir = process.cwd();
   const targetDir = path.join(parentDir, subdirName);
 
-  // 3. 检查子目录：复用 / 报错 / 克隆
+  // 2. 检查子目录：复用（同步）/ 报错 / 克隆
   let wasCloned = false;
   if (fs.existsSync(targetDir)) {
     const detection = workspaces.detectRepo(targetDir, w.repo);
     if (detection.state === 'matched') {
-      log(`子目录 ${c('cyan', subdirName + '/')} 已存在且匹配，正在同步远程最新...`, 'info');
+      let branch;
+      const repoProgress = progress('仓库');
       try {
-        syncWorkspaceRepo(targetDir);
+        branch = await syncWorkspaceRepo(targetDir, t => repoProgress.update(t));
       } catch (e) {
+        repoProgress.done();
         return { ok: false, error: 'PULL_FAILED', message: e.message };
       }
+      repoProgress.done();
+      step('✓', '仓库', `${subdirName} → origin/${branch}（fast-forward）`);
     } else {
+      step('✗', '仓库', `${subdirName}/ 已存在，但不是业务空间「${w.name}」的仓库`,
+        { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
       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',
-      );
+        ? detection.remotes.map(r => `      ${c('gray', r.name + ':')} ${r.url}`).join('\n')
+        : `      ${c('gray', '（该目录尚未配置 remote）')}`;
       console.log(remoteList);
-      console.log(`        ${c('gray', '期望 remote:')} ${w.repo}`);
-      console.log('');
+      console.log(`      ${c('gray', '期望 remote:')} ${w.repo}`);
       log('请删除该子目录后重试，或在另一个父目录中运行本命令。', 'warn');
       return { ok: false, error: 'DIR_MISMATCH' };
     }
   } else {
-    console.log(`⏳ 正在克隆仓库到 ${c('cyan', subdirName + '/')} ...`);
+    const cloneProgress = progress('仓库');
+    cloneProgress.update(`克隆 ${subdirName}/（首次较慢）`);
     try {
       // 在 parentDir 下克隆，git 会自动创建 subdirName 子目录
-      execSync(`git clone "${w.repo}"`, {
+      await execFileAsync('git', ['clone', '-q', w.repo], {
         cwd: parentDir,
-        stdio: 'pipe',
         timeout: 180000,
       });
     } catch (e) {
+      cloneProgress.done();
       log(`git clone 失败：${e.message}`, 'error');
       log('请检查：1) 仓库地址是否正确  2) 是否已配置 SSH key 或 GitLab 访问凭证', 'warn');
       return { ok: false, error: 'CLONE_FAILED', message: e.message };
     }
+    cloneProgress.done();
     wasCloned = true;
-    log(`已克隆到 ${c('cyan', subdirName + '/')}`, 'success');
+    step('✓', '仓库', `已克隆 ${subdirName}/`);
   }
 
-  // 4. 检查 CONFIG.json（init-worktree 技能依赖），不存在则复制样例文件
-  ensureWorkspaceConfig(targetDir, w.name);
-
-  // 5. 校验 CONFIG.json 格式，不合法则中断并撤销本空间初始化
-  const configPath = path.join(targetDir, 'CONFIG.json');
+  // 3. workspace-config.json：缺失则从样例生成，随后校验格式
+  const cfgState = ensureWorkspaceConfig(targetDir);
+  const configPath = path.join(targetDir, 'workspace-config.json');
   const configValidation = workspaces.validateWorkspaceConfig(configPath);
   if (!configValidation.valid) {
-    log(`CONFIG.json 校验失败：${configValidation.message}`, 'error');
-    // 撤销本次克隆，使工作空间回到初始状态，用户配好 CONFIG.json 后可重新执行
+    step('✗', '配置', `workspace-config.json 校验失败：${configValidation.message}`,
+      { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
+    // 撤销本次克隆，使工作空间回到初始状态，用户配好 workspace-config.json 后可重新执行
     if (wasCloned && fs.existsSync(targetDir)) {
       removePath(targetDir);
-      log(`已撤销本次克隆（${subdirName}/），请配好 CONFIG.json 后重新执行 cbb setup`, 'warn');
+      log(`已撤销本次克隆（${subdirName}/），请配好 workspace-config.json 后重新执行 cbb setup`, 'warn');
     } else {
-      log('请修正 CONFIG.json 后重新执行 cbb setup', 'warn');
+      log('请修正 workspace-config.json 后重新执行 cbb setup', 'warn');
     }
-    const samplePath = path.join(SHARED_STANDARDS_DIR, workspaces.SAMPLE_CONFIG);
-    log(`参考格式：${samplePath}`, 'info');
+    log(`参考格式：${path.join(SHARED_STANDARDS_DIR, workspaces.SAMPLE_CONFIG)}`, 'info');
     return { ok: false, error: 'CONFIG_INVALID', message: configValidation.message };
   }
-  log('CONFIG.json 校验通过', 'success');
-
-  // 6. 拉取关联应用代码到 .code/（基准代码，首次 clone，后续 fetch 更新）
-  syncAppRepos(targetDir);
+  if (cfgState === 'created') {
+    step('!', '配置', 'workspace-config.json 已从样例生成，请编辑 apps 后重跑 cbb setup',
+      { iconColor: 'yellow', valueColor: 'yellow' });
+  } else {
+    step('✓', '配置', `workspace-config.json（${configValidation.config.apps.length} 个应用）`);
+  }
 
-  // 7. 若已安装，提示当前版本并询问是否继续；用户拒绝则跳过本 workspace
-  const shouldInstall = await confirmUpgradeIfInstalled(targetDir);
-  if (!shouldInstall) {
+  // 4. 拉取关联应用代码到 .codespace/（基准代码，首次 clone 较慢，实时提示当前应用）
+  const appProgress = progress('应用');
+  let apps;
+  try {
+    apps = await syncAppRepos(targetDir, t => appProgress.update(t));
+  } finally {
+    appProgress.done();
+  }
+  const appParts = [`${apps.ok}/${apps.ok + apps.fail} 个就绪`];
+  if (apps.fetchFailed.length > 0) appParts.push(`${apps.fetchFailed.length} 个 fetch 失败（用本地代码）`);
+  if (apps.sampleApps.length > 0) appParts.push(`${apps.sampleApps.length} 个样例占位已跳过`);
+  const appWarn = apps.fail > 0 || apps.sampleApps.length > 0 || apps.fetchFailed.length > 0;
+  step(appWarn ? '!' : '✓', '应用', appParts.join(' · '), { iconColor: appWarn ? 'yellow' : 'green' });
+  if (apps.sampleApps.length > 0) {
+    const names = apps.sampleApps.map(a => a.name).join('、');
+    console.log(`      ${c('gray', `${names} → 编辑 workspace-config.json 填入真实仓库地址`)}`);
+  }
+
+  // 5. 若已安装：版本未变化直接跳过；有新版本需用户确认；用户拒绝则跳过本 workspace
+  const decision = await confirmUpgradeIfInstalled(targetDir);
+  if (decision === 'cancel') {
     return { ok: false, error: 'USER_CANCELLED', skipped: true };
   }
+  if (decision === 'skip') {
+    return { ok: true, subdir: subdirName, upToDate: true };
+  }
 
-  // 7. 安装 workspace AI 配置子集（worktree 管理技能/命令 + openspec 配置，不含 base 工作流）
+  // 6. 安装 workspace AI 配置子集（worktree 管理技能/命令 + openspec 配置，不含 base 工作流）
   try {
-    await installWorkspaceConfig(targetDir, { yes: true });
+    await installWorkspaceConfig(targetDir, { yes: true, selectedAdapters: opts.selectedAdapters });
     return { ok: true, subdir: subdirName };
   } catch (e) {
-    log(`初始化 ${subdirName} 失败：${e.message}`, 'error');
+    step('✗', 'AI 配置', e.message, { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
     return { ok: false, error: 'INIT_FAILED', message: e.message };
   }
 }
@@ -1354,42 +1500,37 @@ function describeBatchError(r) {
     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 'CONFIG_INVALID':  return `workspace-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');
-  });
+  if (failed.length === 0) {
+    const dirs = ok.map(r => (r.subdir || r.w.name) + '/').join('、');
+    step('✓', '完成', `${ok.length} 个业务空间已就绪（${dirs}）`);
+    return;
+  }
+  step('!', '完成', `成功 ${ok.length}/${results.length}，失败项见下`, { iconColor: 'yellow', valueColor: 'yellow' });
   failed.forEach(r => {
-    log(`${r.w.name}（${r.w.businessLine}）：${describeBatchError(r)}`, 'error');
+    step('✗', r.w.name, describeBatchError(r), { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
   });
-  if (failed.length > 0) {
-    console.log('');
-    log(`${failed.length} 个业务空间处理失败，请按上述提示排查`, 'warn');
-  }
 }
 
 /**
  * 初始化业务空间工作目录（cbb setup 命令）。
  *
- * 流程：安装用户级组件（幂等）→ 检测当前目录 → 加载配置 → checkbox 多选
- *       → 确认目标目录 → 依次处理每个选中的 workspace。
+ * 流程：检测当前目录 → 加载配置 → checkbox 多选业务空间 → 选择 AI 工具适配器
+ *       → 安装用户级组件 → 确认目标目录 → 依次处理每个选中的 workspace。
  * 单个 workspace 失败不影响后续。
  */
 async function setupWorkspace() {
-  // 首次运行：安装用户级组件（hook / cbb-wiki-ops，幂等，已装则跳过）
-  await setupUserLevelComponents();
-
   // 0. 检测当前目录是否为 git 仓库
   const parentDir = process.cwd();
   try {
@@ -1433,37 +1574,61 @@ async function setupWorkspace() {
     .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('');
+  // 2.5 选择 AI 工具适配器（一次选择，作用于用户级组件与全部空间；非交互默认全选）
+  let selectedAdapters;
+  if (!process.stdin.isTTY) {
+    selectedAdapters = adapters;
+  } else {
+    const toolIdx = await checkbox.promptCheckbox({
+      header: '🔧  选择要安装的 AI 工具（空格切换，回车确认）',
+      items: adapters.map(a => ({ label: c('cyan', a.displayName) })),
+      // 默认只预选 opencode（团队当前主用），可空格加选其他工具
+      preSelected: adapters.reduce((acc, a, i) => (a.name === 'opencode' ? acc.concat(i) : acc), []),
+    });
+    selectedAdapters = toolIdx.size === 0
+      ? adapters
+      : [...toolIdx].sort((a, b) => a - b).map(i => adapters[i]);
+  }
+
+  // 3. 配置摘要（业务空间 / 目标目录 / AI 工具）
+  printSetupSummary(selected, selectedAdapters, parentDir);
+
+  // 4. 用户级组件（版本检查 hook，幂等）→ 一行结果
+  await setupUserLevelComponents(selectedAdapters);
 
-  // 4. 展示目标目录并让用户确认
-  section('📁', '业务空间将创建在以下目录');
-  console.log(`  ${c('cyan', parentDir)}`);
+  // 5. 目录确认
   console.log('');
-  const answer = await ask(`${c('yellow', '?')} 是否将上述业务空间创建在此目录？(Y/n) `);
+  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);
+    console.log('  ' + c('cyan', '▸') + ' ' + c('gray', `[${i + 1}/${selected.length}]`) + ' ' + c('bold', w.name));
+    const result = await initSingleWorkspace(w, { selectedAdapters });
     results.push({ w, ...result });
-    console.log('');
   }
+  console.log('');
+  printBatchSummary(results);
+}
 
-  // 5. 汇总报告（已移除）
+/** 展示本次 setup 的配置摘要：业务空间清单 + 目标目录 + AI 工具 */
+function printSetupSummary(selected, selectedAdapters, parentDir) {
+  const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+  console.log('');
+  console.log('  ' + c('bold', 'cbb setup') + '  ' + c('gray', `v${pkg.version}`));
+  console.log('');
+  selected.forEach(w => {
+    console.log(`    ${c('yellow', '[' + w.businessLine + ']')} ${w.name}`);
+    console.log(`      ${c('gray', w.repo)}`);
+  });
+  console.log('    ' + c('gray', padVisual('目标目录', 10)) + ' ' + c('cyan', parentDir));
+  console.log('    ' + c('gray', padVisual('AI 工具', 10)) + ' ' + selectedAdapters.map(a => a.displayName).join('、'));
 }
 
 // ── 用户级组件 ────────────────────────────────────────────
@@ -1472,13 +1637,14 @@ async function setupWorkspace() {
  * 安装用户级组件（与项目无关的内容，一次安装全局可用，幂等）。
  *
  * - 清单：~/.cbb/.user-components 记录本包管理的用户级路径
- * - 内容：check-update hook（settings 由 settingsManager 幂等管理）+ 工具 skills（cbb-wiki-ops）
+ * - 内容：check-update hook（settings 由 settingsManager 幂等管理）
  */
 const USER_MANIFEST_FILE = path.join(os.homedir(), '.cbb', '.user-components');
-// 装到用户级的工具 skills（与具体项目无关，任何会话都可能用到）
-const USER_LEVEL_SKILLS = ['cbb-wiki-ops'];
+// 装到用户级的工具 skills（与具体项目无关，任何会话都可能用到）。
+// 当前为空：cbb-wiki-ops 保留在源仓库（cbb/tools/）但不分发，有用户需要时再加入此清单。
+const USER_LEVEL_SKILLS = [];
 
-async function setupUserLevelComponents() {
+async function setupUserLevelComponents(targetAdapters = adapters) {
   const home = os.homedir();
   const srcDir = path.join(SHARED_STANDARDS_DIR, 'cbb', 'tools');
   if (!fs.existsSync(srcDir)) return;
@@ -1493,32 +1659,36 @@ async function setupUserLevelComponents() {
     } catch (_) { /* ignore parse errors */ }
   }
 
-  section('🏠', '检查用户级组件（~/.claude/、~/.qoder/）');
+  const summaryParts = [];
 
-  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}`);
+  if (USER_LEVEL_SKILLS.length > 0) {
+    const skillAdapters = targetAdapters.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');
+    summaryParts.push(`工具 skills×${USER_LEVEL_SKILLS.length}`);
+  }
 
   // check-update hook（settingsManager 幂等：已有 _managedBy: cbb 标记则不重复写入）
-  const hookAdapters = adapters.filter(a => a.settingsFile && a.hookEvents);
+  const hookAdapters = targetAdapters.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');
+    summaryParts.push(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join('、')}`);
   }
 
+  if (summaryParts.length > 0) step('✓', '用户级组件', summaryParts.join(' · '));
+
   const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
   fs.writeFileSync(USER_MANIFEST_FILE, JSON.stringify({
     version: pkg.version,
@@ -1608,7 +1778,7 @@ function uninstallConfigYaml(managedPaths) {
 }
 
 /**
- * 卸载用户级组件（cbb-wiki-ops 等工具 skills + 版本检查 hook）。
+ * 卸载用户级组件（工具 skills + 版本检查 hook，按清单精确删除）。
  * 按 ~/.cbb/.user-components 清单精确删除，不影响用户自装内容；
  * ~/.cbb 目录不动（可能含用户自己的 wiki-config.json）。
  */
@@ -1666,7 +1836,7 @@ async function uninstall() {
   // 是否同时卸载用户级组件（工具 skills + 版本检查 hook，作用于 ~/.claude 等用户目录）
   let removeUserLevel = false;
   if (fs.existsSync(USER_MANIFEST_FILE)) {
-    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder 下的工具 skills + 版本检查 hook）？(y/N): ');
+    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder 的版本检查 hook）？(y/N): ');
     removeUserLevel = answerUser.toLowerCase() === 'y' || answerUser.toLowerCase() === 'yes';
   }
 
@@ -1695,6 +1865,9 @@ async function uninstall() {
     skippedPaths.add(adapter.settingsFile);
   });
 
+  // opencode.json：移除本包登记的 instructions pattern（cbb 创建的整体文件由清单删除兜底）
+  removeInstructionsRegistrations();
+
   // 删除清单中记录的所有路径。
   // 注意：CLAUDE.md / AGENTS.md 等用户文档受保护，即使旧清单里有也不删除。
   let removed = 0;
@@ -1746,9 +1919,34 @@ async function uninstall() {
 
 // ── CLI 入口 ──────────────────────────────────────────────
 
+// 入口身份：cbb（用户命令） / cbbm（内部命令，由流程、hook、Agent 技能调用）
+const ENTRY = process.env.CBB_ENTRY === 'cbbm' ? 'cbbm' : 'cbb';
+const INTERNAL_COMMANDS = ['init', 'check-update', 'wiki', 'wp'];
+const UPSTREAM_FLAGS = ['--upstream-superpowers', '--upstream-openspec'];
+
 const args = process.argv.slice(2);
 const command = args[0];
 const restArgs = args.slice(1);
+const hasUpstreamFlag = restArgs.some(a => UPSTREAM_FLAGS.includes(a));
+
+if (ENTRY === 'cbb' && command === 'update' && hasUpstreamFlag) {
+  log('维护者拉源选项已迁移到 cbbm：cbbm update --upstream-superpowers / --upstream-openspec', 'error');
+  process.exit(1);
+}
+if (ENTRY === 'cbbm' && command === 'update' && !hasUpstreamFlag) {
+  log('cbbm update 仅用于维护者拉源（--upstream-superpowers / --upstream-openspec）', 'error');
+  log('升级已安装内容请使用 cbb update', 'warn');
+  process.exit(1);
+}
+if (ENTRY === 'cbbm' && (command === 'setup' || command === 'uninstall')) {
+  log(`cbbm 仅承载内部命令；请使用 cbb ${command}`, 'error');
+  process.exit(1);
+}
+if (ENTRY === 'cbb' && INTERNAL_COMMANDS.includes(command)) {
+  log(`内部命令已迁移为 cbbm ${command}`, 'error');
+  log('若调用方是未升级的流程文件，请先在项目根执行 cbb update', 'warn');
+  process.exit(1);
+}
 
 switch (command) {
   case 'setup': {
@@ -1840,6 +2038,11 @@ switch (command) {
   case undefined:
     showHelp();
     break;
+  case 'version':
+  case '-v':
+  case '--version':
+    console.log(require(path.join(SHARED_STANDARDS_DIR, 'package.json')).version);
+    break;
   default:
     log(`未知命令: ${command}`, 'error');
     showHelp();
@@ -1848,6 +2051,22 @@ switch (command) {
 
 function showHelp() {
   const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+
+  if (ENTRY === 'cbbm') {
+    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 wiki / cbbm wp        Wiki 查询与发布（AI 通过技能调用）
+
+维护者选项（拉取上游原生内容到本包源仓库）：
+  cbbm update --upstream-superpowers    从 GitHub 拉取最新 superpowers skills
+  cbbm update --upstream-openspec       从 GitHub 拉取最新 OpenSpec 工作流
+`);
+    return;
+  }
+
   console.log(`
 @jspg-ai/coding-bb v${pkg.version} — AI Coding Agent 统一行为准则与工作流
 
@@ -1856,19 +2075,6 @@ function showHelp() {
   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
 `);