@jspg-ai/coding-bb 0.0.3-beta.8 → 0.0.4

package/cbb/lib/install/init.js

@@ -5,7 +5,8 @@
  *
  * 将AI 编码规范与工作流套件安装到目标项目中。
  * 支持工具：Claude Code (.claude/rules/)、Qoder (.qoder/rules/)、opencode (.opencode/rules/)、
- *          WorkBuddy/CodeBuddy (.codebuddy/rules/)、TraeWork/TraeCode (.trae/rules/)
+ *          WorkBuddy (.workbuddy/rules/)、TraeWork/TraeCode 中国版 (.trae/rules/，用户级 hook 在 ~/.trae-cn)、
+ *          MiniMax Code (.minimax/rules/，规则经 AGENTS.md 托管导航加载，命令转 skill，hook 走用户级本地插件)
  *
  * 使用方式：
  *   npm install -g @jspg-ai/coding-bb  # 首次使用
@@ -40,6 +41,7 @@ function execCmd(file, args, opts = {}) {
 }
 
 const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+const setupDecision = require('./setup-decision');
 
 // 目标项目根目录：默认取当前 cwd，init() 可在调用前覆盖。
 // 注意：使用 let 而非 const 是为了让 cbb setup 能在拉好仓库后把目标目录
@@ -55,10 +57,11 @@ const LAST_TOOLS_FILE = path.join(MANIFEST_DIR, '.last-tools');
 // 适配器（数组顺序 = 工具选择面板的显示顺序）
 const adapters = [
   require('./opencode'),
-  require('./codebuddy'),
+  require('./workbuddy'),
   require('./trae'),
   require('./qoder'),
   require('./claude-code'),
+  require('./minimax'),
 ];
 
 // superpowers 部署白名单：仅装 openspec 工作流硬依赖 + 方法论基底（源仓库仍保留全量 15 个，
@@ -75,12 +78,17 @@ const SUPERPOWERS_WHITELIST = [
 // worktree 管理 skill 清单：init / close / push 三件套（SKILL.md + scripts）。
 // 按 skill 形态部署到各工具的 skillsDir，使这三个能力可被 AI 在对话中自动触发
 // （description 驱动），同时工具也会把它们暴露为斜杠命令供用户手动指定。
-const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
+const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push', 'cbb-local-mode'];
 
 // 装到空间的 tools skills：当前不分发。
 // cbb-design-to-wiki（Wiki 发布）与 cbb-wiki-ops 保留在源仓库，需要时加入本清单即恢复分发；Java 工具不装。
 const TOOLS_SKILLS = [];
 
+// external 外部依赖 skills 白名单：第三方上游 pin vendor 的 skill（源在 external/<name>/，
+// 各子目录自带 .version pin，供 cbbm update --upstream-external 维护）。
+// 非 skill 类外部依赖不走部署通道，不会进本清单。
+const EXTERNAL_SKILLS = ['frontend-design'];
+
 // 不随安装分发的官方 OpenSpec 命令（源仓库保留，仍由 CLI 接管升级）：
 // onboard 为新手引导教程，团队入门已由文档覆盖；sync 是 archive 流程承重件，保留分发。
 const OPENSPEC_COMMANDS_EXCLUDE = ['onboard.md'];
@@ -88,20 +96,48 @@ const OPENSPEC_COMMANDS_EXCLUDE = ['onboard.md'];
 // settings.json hook 工具
 const settingsManager = require('../utils/settings');
 
+// MiniMax 本地插件 hook（无 settings.json hooks 的适配器走插件形态）
+const pluginHookManager = require('../utils/plugin-hook');
+
+// AGENTS.md 托管导航块（agentsNav 适配器的项目级规则注入通道）
+const agentsNav = require('./agents-nav');
+
+// 命令 → skill 形态转换（commandsAsSkills 适配器，当前仅 MiniMax Code）
+const commandSkill = require('./command-skill');
+
+// 工具选择策略（退市工具不在面板提供；勾选范围即权威，ADR 0006）
+const toolSelection = require('./tool-selection');
+
 /** 适配器的 hook 方言参数（Trae 需顶层 version 字段等差异） */
 function hookOpts(adapter) {
   return adapter.hookDialect ? { dialect: adapter.hookDialect } : {};
 }
 
+// 工具历史名迁移（codebuddy → workbuddy）与集合归一见 setup-decision.js
+// （normalizeToolSet / LEGACY_TOOL_NAMES 单一来源）
+
+/**
+ * 迁移清理：移除本包写在旧用户级 settings 里的 hook（如 WorkBuddy 适配修正：
+ * ~/.codebuddy/settings.json → ~/.workbuddy/settings.json）。
+ * removeHooks 只删 _managedBy: cbb 标记的条目，文件清空则删除。返回 true 表示有改动。
+ */
+function cleanLegacySettings(adapter) {
+  if (!adapter.legacySettingsFile || !adapter.hookEvents) return false;
+  return settingsManager.removeHooks(adapter.legacySettingsFile, adapter.hookEvents, hookOpts(adapter));
+}
+
 // 清单驱动的文件清理决策（保护用户文档 CLAUDE.md / AGENTS.md 等）
 const { pathsToDelete, protectedKeptPaths } = require('./cleanup');
 
-// 规则 frontmatter 改写（Trae/CodeBuddy 需 alwaysApply: true）
+// 规则 frontmatter 改写（Trae/WorkBuddy 需 alwaysApply: true）
 const { applyRuleRewrites } = require('./rule-rewrite');
 
 // .gitignore 条目决策（纯函数：检测/写入/卸载移除）
 const gitignore = require('../utils/gitignore');
 
+// git pre-commit hook：分支感知提交防线（ADR 0002，install/uninstall 调用）
+const githook = require('../utils/githook');
+
 // 业务空间配置（cbb setup 命令专用）
 const workspaces = require('./workspaces');
 
@@ -117,6 +153,9 @@ const superpowers = require('../superpowers');
 // OpenSpec 工作流管理（内置集成 + cbb update --upstream-openspec）
 const openspec = require('../openspec');
 
+// External 外部依赖管理（内置集成 + cbbm update --upstream-external）
+const external = require('../external');
+
 // ── 颜色与输出辅助 ──────────────────────────────────────
 
 const { COLOR, COLOR_ENABLED, c, log, section, step, padVisual, progress, LOG_STYLES } = require('../utils/output');
@@ -127,13 +166,15 @@ function detectExistingInstall() {
 }
 
 /**
- * 判定目标目录是否为业务空间根：workspace-config.json 存在且 .git 是目录。
- * 需求工作树内也有 workspace-config.json（tracked 副本），但其 .git 是文件（gitdir 指针），
+ * 判定目标目录是否为业务空间根：CBB-WORKSPACE.json（或旧名 workspace-config.json）存在且 .git 是目录。
+ * 需求工作树内也有该文件（tracked 副本），但其 .git 是文件（gitdir 指针），
  * 必须以 .git 形态排除——避免「在 worktree 里误跑 cbb update」被当作空间根
  * （误装 worktree 管理入口、在错误位置报旧导航提示）。
+ * 双名识别用于改名过渡期：存量空间（旧名）跑 update 时仍能识别并装上新版 hook。
  */
 function detectWorkspaceRoot() {
-  if (!fs.existsSync(path.join(TARGET_DIR, 'workspace-config.json'))) return false;
+  if (!fs.existsSync(path.join(TARGET_DIR, 'CBB-WORKSPACE.json'))
+    && !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();
 }
@@ -177,8 +218,13 @@ function writeManifest(paths, selectedAdapters) {
     });
   }
 
-  // 合并：选中的适配器写入新版本，未选中的保持不变
-  const adapterVersions = { ...existingAdapterVersions };
+  // 合并：选中的适配器写入新版本；未选中的（工具仍在包内）保持不变；
+  // 已从包中移除的工具（如 codebuddy）记录清理，避免清单里留下永久无效项
+  const knownNames = new Set(adapters.map(a => a.name));
+  const adapterVersions = {};
+  for (const [name, ver] of Object.entries(existingAdapterVersions)) {
+    if (knownNames.has(name)) adapterVersions[name] = ver;
+  }
   selectedAdapters.forEach(adapter => {
     adapterVersions[adapter.name] = pkg.version;
   });
@@ -197,7 +243,7 @@ function readLastTools() {
   if (!fs.existsSync(filePath)) return null;
   try {
     const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-    return new Set(data.tools || []);
+    return setupDecision.normalizeToolSet(new Set(data.tools || []));
   } catch (_) {
     return null;
   }
@@ -298,19 +344,22 @@ function ask(question) {
 async function selectTools(isUpgrade) {
   const action = isUpgrade ? '升级' : '安装';
 
+  // 面板可选项 = 未退市适配器（Claude Code / MiniMax Code 已退市，见 tool-selection.js）
+  const selectable = toolSelection.selectableAdapters(adapters);
+
   // 读取上次选择的工具：有记录则预选上次选择，首次安装则全部不选
   const lastTools = readLastTools();
   const preSelected = lastTools
-    ? adapters.map((a, i) => lastTools.has(a.name) ? i : -1).filter(i => i >= 0)
+    ? selectable.map((a, i) => lastTools.has(a.name) ? i : -1).filter(i => i >= 0)
     : [];
 
   // checkbox 多选：
   //   - 不切换 → 确认当前选择
   //   - 取消某项 → 只装剩下的
-  //   - 全部不选 → 提示后回退全部
+  //   - 全部不选 → 提示后回退全部可选项
   const selectedIdx = await checkbox.promptCheckbox({
     header: `🔧  选择要${action}的 AI 工具（空格切换，回车确认）`,
-    items: adapters.map(a => ({
+    items: selectable.map(a => ({
       label: c('cyan', a.displayName),
     })),
     preSelected,
@@ -319,15 +368,15 @@ async function selectTools(isUpgrade) {
   let result;
   if (selectedIdx.size === 0) {
     log(`未选择任何工具，默认全部${action}`, 'warn');
-    result = adapters;
+    result = selectable;
   } else {
     // 转成有序适配器数组（按原始顺序）
     result = [...selectedIdx]
       .sort((a, b) => a - b)
-      .map(i => adapters[i]);
+      .map(i => selectable[i]);
   }
 
-  // 保存本次选择，供下次运行时预选
+  // 保存本次选择（勾选范围即权威，供下次运行时预选）
   saveLastTools(result);
   return result;
 }
@@ -339,7 +388,7 @@ function deployCoreRules(adapter, isUpgrade, managedPaths) {
   const rulesDest = path.join(TARGET_DIR, adapter.rulesDir);
   const action = isUpgrade ? '更新' : '安装';
 
-  const coreRules = ['cbb-coding-rule.md', 'cbb-priority.md', 'cbb-ai-behavior.md'];
+  const coreRules = ['cbb-coding-rule.md', 'cbb-priority.md', 'cbb-ai-behavior.md', 'cbb-workspace-discipline.md'];
 
   // 确保目标目录存在
   fs.mkdirSync(rulesDest, { recursive: true });
@@ -607,47 +656,13 @@ function deployCommandFiles(adapter, srcDir, destDir, prefix, filter) {
     const srcPath = path.join(srcDir, f);
     const destPath = path.join(destDir, prefix + f);
     removePath(destPath);
-    const content = rewriteCommandName(adapter, sanitizeCommandFrontmatter(applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'))));
+    const content = rewriteCommandName(adapter, commandSkill.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。
@@ -660,11 +675,49 @@ function rewriteCommandName(adapter, content) {
   });
 }
 
-/** 官方 OpenSpec 命令（openspec/commands/ → adapter.commandsDir） */
+/**
+ * MiniMax：无项目级 commands 目录，命令转 skill 形态（skill 即其斜杠命令），
+ * 每个命令落为 <skillsDir>/<prefix><name>/SKILL.md，目录名 = frontmatter name。
+ * @returns {{count:number, names:string[], destDir:string|null}} destDir 为清单登记用相对目录
+ */
+function deployCommandSkills(adapter, srcDir, filter) {
+  if (!fs.existsSync(srcDir)) return { count: 0, names: [], destDir: null };
+  const destDir = adapter.skillsDir;
+  const skillsRoot = path.join(TARGET_DIR, destDir);
+  fs.mkdirSync(skillsRoot, { recursive: true });
+
+  // 与 skill 同构的扁平 .md 源文件（命令不是子目录）
+  const commandFiles = fs.readdirSync(srcDir)
+    .filter(f => f.endsWith('.md') && fs.statSync(path.join(srcDir, f)).isFile())
+    .filter(f => !filter || filter.includes(f));
+
+  const names = [];
+  commandFiles.forEach(f => {
+    const skillName = commandSkill.skillNameFor(f, adapter.commandPrefix || '');
+    const skillDir = path.join(skillsRoot, skillName);
+    removePath(skillDir);
+    fs.mkdirSync(skillDir, { recursive: true });
+    const content = commandSkill.convertCommandToSkill(
+      applyContentRewrites(adapter, fs.readFileSync(path.join(srcDir, f), 'utf-8')),
+      skillName);
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+    names.push(skillName);
+  });
+
+  return { count: commandFiles.length, names, destDir };
+}
+
+/**
+ * 官方 OpenSpec 命令（openspec/commands/ → adapter.commandsDir；
+ * commandsAsSkills 适配器转 skill 形态 → adapter.skillsDir）
+ * @returns {{count:number, names:string[], destDir:string|null}}
+ */
 function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
-  if (!adapter.commandsDir) return { count: 0, names: [] };
-  return deployCommandFiles(
+  if (adapter.commandsAsSkills) return deployCommandSkills(adapter, srcDir, filter);
+  if (!adapter.commandsDir) return { count: 0, names: [], destDir: null };
+  const result = deployCommandFiles(
     adapter, srcDir, path.join(TARGET_DIR, adapter.commandsDir), adapter.commandPrefix || '', filter);
+  return { ...result, destDir: adapter.commandsDir };
 }
 
 // ── 设置 OpenSpec 工作流 ──────────────────────────────────
@@ -984,22 +1037,29 @@ async function init(targetDir, options = {}) {
   // 选择优先级：调用方预设（cbb setup）> .last-tools（非交互沿用）> 交互选择；无记录才回退全选
   const isNonInteractive = yes || !process.stdin.isTTY;
   let selectedAdapters;
+  let fromRecord = false; // 选择来自预设或 .last-tools 记录（需落盘归一化后的新工具名）
   if (presetAdapters && presetAdapters.length > 0) {
     selectedAdapters = presetAdapters;
+    fromRecord = true;
   } else if (isNonInteractive) {
     const lastTools = readLastTools();
-    const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
-    selectedAdapters = reused.length > 0 ? reused : adapters;
+    // 旧记录只用于预选可选项——历史遗留的退市工具不并回（ADR 0006：勾选范围即权威）
+    const reused = lastTools ? toolSelection.selectableAdapters(adapters).filter(a => lastTools.has(a.name)) : [];
+    selectedAdapters = reused.length > 0 ? reused : toolSelection.selectableAdapters(adapters);
+    fromRecord = reused.length > 0;
     if (yes && process.stdin.isTTY) {
       log(reused.length > 0
         ? `--yes 非交互模式，沿用上次工具选择：${reused.map(a => a.displayName).join('、')}`
-        : '--yes 非交互模式，无上次选择记录，已默认选中所有适配器', 'info');
+        : '--yes 非交互模式，无上次选择记录，已默认选中全部可选工具', 'info');
     }
   } else {
     selectedAdapters = await selectTools(isUpgrade);
   }
-  // 业务空间根记录本次选择，供 cbb update 等非交互场景沿用
-  if (isWorkspaceRoot && presetAdapters && presetAdapters.length > 0) {
+
+  // 退市工具不粘性保留（ADR 0006）：选择集即权威，旧记录里的退市工具随清单差集清理
+
+  // 本次选择落盘（沿用旧记录时同样落盘：归一化历史工具名 + 剔除退市遗留记录）
+  if (fromRecord) {
     saveLastTools(selectedAdapters);
   }
 
@@ -1018,13 +1078,14 @@ 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`);
+    newPaths.add(`${adapter.rulesDir}/cbb-workspace-discipline.md`);
     // 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');
+  log(`核心规则 → ${selectedAdapters.map(a => a.rulesDir).join(', ')} (4 个文件)`, 'success');
 
   // 安装 Skills（支持 skills 的适配器）
   const skillsAdapters = selectedAdapters.filter(a => a.skillsDir);
@@ -1085,12 +1146,28 @@ async function init(targetDir, options = {}) {
       log('可运行 cbb update --upstream-superpowers 下载最新 skills', 'warn');
     }
 
+    // 部署 external 外部依赖 Skills（第三方上游 pin vendor，白名单控制）
+    const externalSkillsSrc = external.EXTERNAL_DIR;
+    let exCount = 0;
+    if (fs.existsSync(externalSkillsSrc)) {
+      skillsAdapters.forEach(adapter => {
+        const exResult = deploySkills(adapter, isUpgrade, managedPaths, externalSkillsSrc, EXTERNAL_SKILLS);
+        if (exResult.count > 0) {
+          exCount = exResult.count;
+          exResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
+        }
+      });
+      if (exCount > 0) log(`External Skills → ${skillsDests.join(', ')} (${exCount}/${EXTERNAL_SKILLS.length} 个，白名单)`, 'success');
+    } else {
+      log('external/ 目录不存在，跳过 External Skills 部署', 'warn');
+    }
+
     // 检测用户级 superpowers 安装，避免与项目级重复导致 skill 冲突
     await detectUserLevelSuperpowers(selectedAdapters, yes);
   }
 
-  // 安装 Commands（官方 11 个 → /opsx:*，onboard 不分发）
-  const commandsAdapters = selectedAdapters.filter(a => a.commandsDir);
+  // 安装 Commands（官方 11 个 → /opsx:*，onboard 不分发；commandsAsSkills 适配器转 skill 形态）
+  const commandsAdapters = selectedAdapters.filter(a => a.commandsDir || a.commandsAsSkills);
   if (commandsAdapters.length > 0) {
     console.log(`\n  ⚡ ${action} Commands...`);
     const commandsBaseSrc = path.join(SHARED_STANDARDS_DIR, 'openspec', 'commands');
@@ -1098,7 +1175,7 @@ async function init(targetDir, options = {}) {
       .filter(f => f.endsWith('.md') && !OPENSPEC_COMMANDS_EXCLUDE.includes(f));
 
     const cmdDests = [...new Set(commandsAdapters
-      .map(a => a.commandsDir)
+      .map(a => a.commandsDir || (a.commandsAsSkills ? `${a.skillsDir}（转 skill）` : null))
       .filter(Boolean))];
     let cmdCount = 0;
     commandsAdapters.forEach(adapter => {
@@ -1107,7 +1184,7 @@ async function init(targetDir, options = {}) {
       const baseResult = deployCommands(adapter, isUpgrade, managedPaths, commandsBaseSrc, openspecCmdInclude);
       if (baseResult.count > 0) {
         adapterCmdCount += baseResult.count;
-        baseResult.names.forEach(name => newPaths.add(`${adapter.commandsDir}/${name}`));
+        baseResult.names.forEach(name => newPaths.add(`${baseResult.destDir}/${name}`));
       }
       cmdCount = Math.max(cmdCount, adapterCmdCount);
     });
@@ -1128,18 +1205,27 @@ 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');
+  // AGENTS.md 规则导航块（声明 agentsNav 的适配器；MiniMax 唯一项目级规则注入通道）。
+  // 选中 → 注入/更新托管块（块外用户内容不动）；未选中（本次 update 取消勾选）→ 精确摘除。
+  let agentsNavState = null;
+  let agentsNavFile = null;
+  adapters.filter(a => a.agentsNav).forEach(adapter => {
+    const target = path.join(TARGET_DIR, adapter.agentsNav.file);
+    if (selectedAdapters.some(sa => sa.name === adapter.name)) {
+      const state = agentsNav.inject(target, adapter.name, adapter.agentsNav.text);
+      if (state !== 'unchanged') { agentsNavState = state; agentsNavFile = adapter.agentsNav.file; }
+    } else if (agentsNav.remove(target, adapter.name)) {
+      agentsNavState = 'removed';
     }
+  });
+  if (agentsNavState === 'created' || agentsNavState === 'updated') {
+    log(`AGENTS.md 规则导航 → ${agentsNavFile}`, 'success');
   }
 
-  // 写入自动版本检查 hook
+  // 写入自动版本检查 hook（settings.json 方言 + 本地插件方言）
   const hookAdapters = selectedAdapters.filter(a => a.settingsFile && a.hookEvents);
-  if (hookAdapters.length > 0) {
+  const pluginHookAdapters = selectedAdapters.filter(a => a.pluginHook);
+  if (hookAdapters.length > 0 || pluginHookAdapters.length > 0) {
     console.log(`\n  🔔 配置自动版本检查...`);
     const command = settingsManager.getCheckUpdateCommand();
     hookAdapters.forEach(adapter => {
@@ -1152,9 +1238,28 @@ async function init(targetDir, options = {}) {
       if (settingsManager.removeLegacyHooks(settingsPath, hookOpts(adapter))) {
         log(`清理 ${adapter.displayName} 遗留的 SessionStart hook`, 'success');
       }
+      // 迁移：清理旧用户级 settings（如 ~/.codebuddy → ~/.workbuddy）
+      if (cleanLegacySettings(adapter)) {
+        log(`迁移清理旧用户级配置 ${adapter.legacySettingsFile}`, 'success');
+      }
       if (!adapter.settingsFileIsUserLevel) newPaths.add(adapter.settingsFile);
     });
-    log(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join(', ')} (${hookAdapters[0].hookEvents.join(', ')})`, 'success');
+    if (hookAdapters.length > 0) {
+      log(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join(', ')} (${hookAdapters[0].hookEvents.join(', ')})`, 'success');
+    }
+    // 本地插件方言（MiniMax：无 settings.json hooks）——用户级，不写入项目清单
+    if (pluginHookAdapters.length > 0) {
+      const pkgVersion = require(path.join(SHARED_STANDARDS_DIR, 'package.json')).version;
+      pluginHookAdapters.forEach(adapter => {
+        const info = pluginHookManager.install({
+          dataDir: adapter.resolveDataDir(),
+          ...adapter.pluginHook,
+          command,
+          version: pkgVersion,
+        });
+        log(`${adapter.displayName} 版本检查插件 → ${info.dir}`, 'success');
+      });
+    }
   }
 
   // 升级时清理旧路径（在旧清单中但不在新路径集中）。
@@ -1202,6 +1307,14 @@ async function init(targetDir, options = {}) {
   // 更新 .gitignore
   updateGitignore();
 
+  // 安装分支感知提交防线（ADR 0002，仅业务空间根：空间根仓库 + .codespace/ 各应用）
+  let hookSummary = null;
+  if (isWorkspaceRoot) {
+    hookSummary = githook.installGitHooksForWorkspace(TARGET_DIR);
+    const appDone = hookSummary.apps.length;
+    log(`提交防线 pre-commit hook → 空间根 + ${appDone} 个应用仓库（${hookSummary.root}）`, 'success');
+  }
+
   // 完成摘要
   console.log(`\n  ✅ ${action}完成！\n`);
 
@@ -1230,13 +1343,14 @@ async function init(targetDir, options = {}) {
 
   // 附加组件（单行）
   const hasSkills = selectedAdapters.some(a => a.skillsDir);
-  const hasCommands = selectedAdapters.some(a => a.commandsDir);
-  const hasHooks = selectedAdapters.some(a => a.settingsFile && a.hookEvents);
+  const hasCommands = selectedAdapters.some(a => a.commandsDir || a.commandsAsSkills);
+  const hasHooks = selectedAdapters.some(a => (a.settingsFile && a.hookEvents) || a.pluginHook);
   const extras = [];
   if (hasSkills) extras.push('Skills');
   if (hasCommands) extras.push('Commands');
   if (hasHooks) extras.push('版本检查 hook');
-  if (agentsMdState === 'created') extras.push('AGENTS.md（空间导航）');
+  if (hookSummary) extras.push('提交防线 pre-commit hook');
+  if (agentsNavState === 'created' || agentsNavState === 'updated') extras.push('AGENTS.md（规则导航）');
   if (extras.length > 0) {
     console.log(`  ${extras.join(' / ')} 已配置`);
   }
@@ -1246,38 +1360,51 @@ async function init(targetDir, options = {}) {
 // ── cbb setup 命令 ──────────────────────────────────────
 
 /**
- * 若 targetDir 已安装，比较已装版本与当前包版本决定是否继续安装。
- *  - 版本一致 → 返回 'skip'（不询问、不重复安装）
- *  - 版本不同 → 返回 'install'（setup 已整体确认过，直接升级到当前包版本，不再二次询问）
- *  - 未安装 → 返回 'install'（不提示，直接继续）
+ * 若 targetDir 已安装，比较「已装版本 vs 当前包版本」与「本次工具选择 vs .last-tools」
+ * 决定是否继续安装（判定纯逻辑见 setup-decision.js）。
+ *  - 版本不同 → 'install'（setup 已整体确认过，直接升级到当前包版本，不再二次询问）
+ *  - 版本一致但本次选择含 .last-tools 之外的新工具（或无记录）→ 'install'
+ *    （beta.14 及以前的 bug：版本一致即整体跳过，新工具的空间级目录永不安装）
+ *  - 版本一致且所选 ⊆ .last-tools → 'skip'（不询问、不重复安装）
  *
  * 注：只比较「已装版本 vs 当前包版本」——安装动作只能落盘当前包的产物，
  * registry 是否有更新由用户级版本检查 hook 提醒，不在此处联网查询。
+ * @param {string} targetDir
+ * @param {Array<{name:string}>} [selectedAdapters] 本次 setup 选中的工具
  * @returns {'install'|'skip'}
  */
-function decideUpgradeIfInstalled(targetDir) {
+function decideUpgradeIfInstalled(targetDir, selectedAdapters) {
   const installed = version.readInstalledVersion(targetDir);
   if (!installed) return 'install'; // 未安装：不提示，直接继续
 
   const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
+  const decision = setupDecision.decideSetupAction({
+    sameVersion: version.compareVersions(installed, pkg.version) === 0,
+    lastTools: setupDecision.normalizeToolSet(setupDecision.readLastToolsFrom(targetDir)),
+    selectedNames: (selectedAdapters || []).map(a => a.name),
+  });
 
-  // 版本未变化 → 不处理（不询问、不重复安装）
-  if (version.compareVersions(installed, pkg.version) === 0) {
+  if (decision.action === 'skip') {
     step('✓', '版本', `v${installed}（已是最新，跳过）`);
     return 'skip';
   }
-
-  step('✓', '版本', `v${installed} → v${pkg.version}`);
+  if (decision.reason === 'new-tools') {
+    step('✓', '版本', `v${installed}（版本一致，新增工具 ${decision.newTools.join('、')} → 继续安装）`);
+  } else if (decision.reason === 'no-tools-record') {
+    step('✓', '版本', `v${installed}（无工具选择记录 → 继续安装）`);
+  } else {
+    step('✓', '版本', `v${installed} → v${pkg.version}`);
+  }
   return 'install';
 }
 
 /**
- * 检查业务空间根目录下是否有 workspace-config.json（init-worktree 技能依赖）。
- * 不存在时，将包内样例文件复制为 workspace-config.json。
+ * 检查业务空间根目录下是否有 CBB-WORKSPACE.json（init-worktree 技能依赖）。
+ * 不存在时，将包内样例文件复制为 CBB-WORKSPACE.json。
  * 返回 'exists' | 'created'（不打印，由调用方汇总输出）。
  */
 function ensureWorkspaceConfig(targetDir) {
-  const configPath = path.join(targetDir, 'workspace-config.json');
+  const configPath = path.join(targetDir, 'CBB-WORKSPACE.json');
   if (fs.existsSync(configPath)) return 'exists';
 
   const samplePath = path.join(SHARED_STANDARDS_DIR, workspaces.SAMPLE_CONFIG);
@@ -1286,12 +1413,12 @@ function ensureWorkspaceConfig(targetDir) {
 }
 
 /**
- * 读取 workspace-config.json 中的应用列表，将关联应用代码 clone/fetch 到 .codespace/ 目录。
+ * 读取 CBB-WORKSPACE.json 中的应用列表，将关联应用代码 clone/fetch 到 .codespace/ 目录。
  * 首次 clone（耗时较长），后续 fetch --all（秒级更新）。
  * 这是基准代码，init-worktree 技能后续只做轻量 fetch 检查。
  */
 /**
- * 读取 workspace-config.json，将关联应用代码 clone/fetch 到 .codespace/ 目录。
+ * 读取 CBB-WORKSPACE.json，将关联应用代码 clone/fetch 到 .codespace/ 目录。
  * 不打印逐条日志，返回汇总对象由调用方渲染：
  *   { ok, fail, updated[], cloned[], fetchFailed[], sampleApps[], invalid[] }
  * 长耗时（首次 clone），通过 onProgress 回调实时提示当前正在处理哪个应用。
@@ -1300,7 +1427,7 @@ function ensureWorkspaceConfig(targetDir) {
  */
 async function syncAppRepos(targetDir, onProgress = () => {}) {
   const summary = { ok: 0, fail: 0, updated: [], cloned: [], fetchFailed: [], sampleApps: [], invalid: [] };
-  const configPath = path.join(targetDir, 'workspace-config.json');
+  const configPath = path.join(targetDir, 'CBB-WORKSPACE.json');
   if (!fs.existsSync(configPath)) return summary;
 
   let config;
@@ -1454,7 +1581,7 @@ async function syncWorkspaceRepo(targetDir, onProgress = () => {}) {
 }
 
 /**
- * 处理单个业务空间：计算子目录 → 检测/克隆 → workspace-config.json → 拉取应用代码 → 升级询问 → 安装 AI 配置。
+ * 处理单个业务空间：计算子目录 → 检测/克隆 → CBB-WORKSPACE.json → 拉取应用代码 → 升级询问 → 安装 AI 配置。
  * 输出为紧凑步进行（✓ 标签 值），失败时不抛出也不退出，返回结果对象供调用方汇总。
  * @param {object} [opts] - { selectedAdapters } cbb setup 上层选定的适配器（透传给空间级安装）
  * @returns {Promise<{ok: boolean, error?: string, message?: string, subdir?: string, skipped?: boolean}>}
@@ -1516,28 +1643,28 @@ async function initSingleWorkspace(w, opts = {}) {
     step('✓', '仓库', `已克隆 ${subdirName}/`);
   }
 
-  // 3. workspace-config.json：缺失则从样例生成，随后校验格式
+  // 3. CBB-WORKSPACE.json：缺失则从样例生成，随后校验格式
   const cfgState = ensureWorkspaceConfig(targetDir);
-  const configPath = path.join(targetDir, 'workspace-config.json');
+  const configPath = path.join(targetDir, 'CBB-WORKSPACE.json');
   const configValidation = workspaces.validateWorkspaceConfig(configPath);
   if (!configValidation.valid) {
-    step('✗', '配置', `workspace-config.json 校验失败：${configValidation.message}`,
+    step('✗', '配置', `CBB-WORKSPACE.json 校验失败：${configValidation.message}`,
       { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
-    // 撤销本次克隆，使工作空间回到初始状态，用户配好 workspace-config.json 后可重新执行
+    // 撤销本次克隆，使工作空间回到初始状态，用户配好 CBB-WORKSPACE.json 后可重新执行
     if (wasCloned && fs.existsSync(targetDir)) {
       removePath(targetDir);
-      log(`已撤销本次克隆（${subdirName}/），请配好 workspace-config.json 后重新执行 cbb setup`, 'warn');
+      log(`已撤销本次克隆（${subdirName}/），请配好 CBB-WORKSPACE.json 后重新执行 cbb setup`, 'warn');
     } else {
-      log('请修正 workspace-config.json 后重新执行 cbb setup', 'warn');
+      log('请修正 CBB-WORKSPACE.json 后重新执行 cbb setup', 'warn');
     }
     log(`参考格式：${path.join(SHARED_STANDARDS_DIR, workspaces.SAMPLE_CONFIG)}`, 'info');
     return { ok: false, error: 'CONFIG_INVALID', message: configValidation.message };
   }
   if (cfgState === 'created') {
-    step('!', '配置', 'workspace-config.json 已从样例生成，请编辑 apps 后重跑 cbb setup',
+    step('!', '配置', 'CBB-WORKSPACE.json 已从样例生成，请编辑 apps 后重跑 cbb setup',
       { iconColor: 'yellow', valueColor: 'yellow' });
   } else {
-    step('✓', '配置', `workspace-config.json（${configValidation.config.apps.length} 个应用）`);
+    step('✓', '配置', `CBB-WORKSPACE.json（${configValidation.config.apps.length} 个应用）`);
   }
 
   // 4. 拉取关联应用代码到 .codespace/（基准代码，首次 clone 较慢，实时提示当前应用）
@@ -1555,11 +1682,11 @@ async function initSingleWorkspace(w, opts = {}) {
   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 填入真实仓库地址`)}`);
+    console.log(`      ${c('gray', `${names} → 编辑 CBB-WORKSPACE.json 填入真实仓库地址`)}`);
   }
 
-  // 5. 若已安装：版本未变化直接跳过；有新版本直接升级（setup 已整体确认过，不再二次询问）
-  const decision = decideUpgradeIfInstalled(targetDir);
+  // 5. 若已安装：版本一致且无新增工具才跳过；否则继续安装/升级（setup 已整体确认过，不再二次询问）
+  const decision = decideUpgradeIfInstalled(targetDir, opts.selectedAdapters);
   if (decision === 'skip') {
     return { ok: true, subdir: subdirName, upToDate: true };
   }
@@ -1581,7 +1708,7 @@ 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 `workspace-config.json 不合法：${r.message || ''}`.trim();
+    case 'CONFIG_INVALID':  return `CBB-WORKSPACE.json 不合法：${r.message || ''}`.trim();
     case 'INIT_FAILED':     return `初始化失败：${r.message || ''}`.trim();
     default:                return r.error || '未知错误';
   }
@@ -1654,20 +1781,26 @@ async function setupWorkspace() {
     .sort((a, b) => a - b)
     .map(i => list[i]);
 
-  // 2.5 选择 AI 工具适配器（一次选择，作用于用户级组件与全部空间；非交互默认全选）
+  // 2.5 选择 AI 工具适配器（一次选择，作用于用户级组件与全部空间；非交互默认全选可选工具）
+  const selectable = toolSelection.selectableAdapters(adapters);
   let selectedAdapters;
   if (!process.stdin.isTTY) {
-    selectedAdapters = adapters;
+    selectedAdapters = selectable;
   } else {
+    // 预选 = 所选空间 .cbb/.last-tools 记录的并集（目录规则与 initSingleWorkspace 一致：
+    // repo 末段子目录；退市工具不并回；旧名归一；并集为空回退预选 opencode——首次引导行为）
+    const records = selected.map(w => {
+      const subdirName = workspaces.extractRepoBasename(w.repo);
+      return subdirName ? setupDecision.readLastToolsFrom(path.join(parentDir, subdirName)) : null;
+    });
     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), []),
+      items: selectable.map(a => ({ label: c('cyan', a.displayName) })),
+      preSelected: setupDecision.preselectIndexes(records, selectable),
     });
     selectedAdapters = toolIdx.size === 0
-      ? adapters
-      : [...toolIdx].sort((a, b) => a - b).map(i => adapters[i]);
+      ? selectable
+      : [...toolIdx].sort((a, b) => a - b).map(i => selectable[i]);
   }
 
   // 3. 配置摘要（业务空间 / 目标目录 / AI 工具）
@@ -1715,28 +1848,33 @@ function printSetupSummary(selected, selectedAdapters, parentDir) {
 /**
  * 安装用户级组件（与项目无关的内容，一次安装全局可用，幂等）。
  *
- * - 清单：~/.cbb/.user-components 记录本包管理的用户级路径
+ * - 清单：~/.cbb/.user-components 只记录**本次实装**的用户级路径
  * - 内容：check-update hook（settings 由 settingsManager 幂等管理）
+ * - 差集清理（ADR 0006）：不在本次目标集合内的适配器，其清单遗留路径、
+ *   本包版本检查 hook、本地插件一并移除（仅删本包标记项，不动用户自装内容）
  */
 const USER_MANIFEST_FILE = path.join(os.homedir(), '.cbb', '.user-components');
 // 装到用户级的工具 skills（与具体项目无关，任何会话都可能用到）。
 // 当前为空：cbb-wiki-ops 保留在源仓库（cbb/tools/）但不分发，有用户需要时再加入此清单。
 const USER_LEVEL_SKILLS = [];
 
-async function setupUserLevelComponents(targetAdapters = adapters) {
+async function setupUserLevelComponents(targetAdapters = toolSelection.selectableAdapters(adapters)) {
   const home = os.homedir();
   const srcDir = path.join(SHARED_STANDARDS_DIR, 'cbb', 'tools');
   if (!fs.existsSync(srcDir)) return;
 
-  const managed = new Set();
+  // 旧清单仅作差集清理基准，不再并入 managed（ADR 0006：勾选范围即权威，
+  // 本次未实装的路径由下方差集移除，而非累积保留）
+  let oldPaths = [];
   const manifestDir = path.dirname(USER_MANIFEST_FILE);
   fs.mkdirSync(manifestDir, { recursive: true });
   if (fs.existsSync(USER_MANIFEST_FILE)) {
     try {
       const data = JSON.parse(fs.readFileSync(USER_MANIFEST_FILE, 'utf-8'));
-      (data.paths || []).forEach(p => managed.add(p));
+      oldPaths = data.paths || [];
     } catch (_) { /* ignore parse errors */ }
   }
+  const managed = new Set();
 
   const summaryParts = [];
 
@@ -1762,10 +1900,64 @@ async function setupUserLevelComponents(targetAdapters = adapters) {
     hookAdapters.forEach(adapter => {
       settingsManager.addHooks(adapter.settingsFile, command, adapter.hookEvents, hookOpts(adapter));
       settingsManager.removeLegacyHooks(adapter.settingsFile, hookOpts(adapter));
+      cleanLegacySettings(adapter);
     });
     summaryParts.push(`版本检查 hook → ${hookAdapters.map(a => a.displayName).join('、')}`);
   }
 
+  // 本地插件 hook（MiniMax：无 settings.json hooks，走 <dataDir>/plugins 本地插件，幂等覆盖）
+  const pluginHookAdapters = targetAdapters.filter(a => a.pluginHook);
+  if (pluginHookAdapters.length > 0) {
+    const command = settingsManager.getCheckUpdateCommand();
+    const pkgVersion = require(path.join(SHARED_STANDARDS_DIR, 'package.json')).version;
+    pluginHookAdapters.forEach(adapter => {
+      pluginHookManager.install({
+        dataDir: adapter.resolveDataDir(),
+        ...adapter.pluginHook,
+        command,
+        version: pkgVersion,
+      });
+    });
+    summaryParts.push(`版本检查插件 → ${pluginHookAdapters.map(a => a.displayName).join('、')}`);
+  }
+
+  // ── 用户级差集清理（ADR 0006：不在本次勾选范围内的工具，用户级组件一并移除）──
+  const targetNames = new Set(targetAdapters.map(a => a.name));
+
+  // 1) 清单路径差集：旧有新无 → 删除（仅本包管理路径，不碰用户自装内容）
+  const removedPaths = [];
+  oldPaths.forEach(relPath => {
+    if (!managed.has(relPath)) {
+      const target = path.join(home, relPath);
+      if (fs.existsSync(target)) {
+        removePath(target);
+        removedPaths.push(relPath);
+      }
+    }
+  });
+  if (removedPaths.length > 0) {
+    summaryParts.push(`移除清单遗留 ×${removedPaths.length}`);
+  }
+
+  // 2) 非目标适配器：摘除本包版本检查 hook（仅删 _managedBy: cbb 标记项，保留用户配置）
+  //    + 本地插件目录
+  const removedNames = [];
+  adapters.filter(a => !targetNames.has(a.name)).forEach(adapter => {
+    let touched = false;
+    if (adapter.settingsFile && adapter.hookEvents) {
+      if (settingsManager.removeHooks(adapter.settingsFile, adapter.hookEvents, hookOpts(adapter))) touched = true;
+      if (cleanLegacySettings(adapter)) touched = true;
+    }
+    if (adapter.pluginHook &&
+        pluginHookManager.remove({ dataDir: adapter.resolveDataDir(), ...adapter.pluginHook })) {
+      touched = true;
+    }
+    if (touched) removedNames.push(adapter.displayName);
+  });
+  if (removedNames.length > 0) {
+    summaryParts.push(`清理 ${removedNames.join('、')} 的用户级组件`);
+  }
+
   if (summaryParts.length > 0) step('✓', '用户级组件', summaryParts.join(' · '));
 
   const pkg = require(path.join(SHARED_STANDARDS_DIR, 'package.json'));
@@ -1778,14 +1970,15 @@ async function setupUserLevelComponents(targetAdapters = adapters) {
 /**
  * cbb update：就地升级当前目录内容 + 用户级组件。
  *
- * 单层安装：统一安装器按空间根判定（workspace-config.json + .git 目录）补齐
- * worktree 管理入口与空间导航；旧子集清单升级时由清单差集机制自动补齐全量内容。
+ * 单层安装：统一安装器按空间根判定（CBB-WORKSPACE.json + .git 目录）补齐
+ * worktree 管理入口；旧子集清单升级时由清单差集机制自动补齐全量内容。
  */
 async function updateInstalled() {
-  // 用户级组件沿用本目录的工具选择（.last-tools），无记录或为空才回退全量
+  // 用户级组件沿用本目录的工具选择（.last-tools），无记录或为空才回退全量。
+  // 旧记录只预选可选项——历史遗留的退市工具不并回（ADR 0006）
   const lastTools = readLastTools();
-  const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
-  await setupUserLevelComponents(reused.length > 0 ? reused : adapters);
+  const reused = lastTools ? toolSelection.selectableAdapters(adapters).filter(a => lastTools.has(a.name)) : [];
+  await setupUserLevelComponents(reused.length > 0 ? reused : toolSelection.selectableAdapters(adapters));
 
   const manifest = readManifest();
   if (manifest.size === 0) {
@@ -1880,6 +2073,9 @@ async function uninstallUserLevelComponents() {
     if (settingsManager.removeHooks(adapter.settingsFile, adapter.hookEvents, hookOpts(adapter))) {
       log(`${adapter.settingsFile}: 移除版本检查 hook，保留用户配置`, 'success');
     }
+    if (cleanLegacySettings(adapter)) {
+      log(`${adapter.legacySettingsFile}: 移除版本检查 hook（旧路径），保留用户配置`, 'success');
+    }
   });
 
   removePath(USER_MANIFEST_FILE);
@@ -1908,7 +2104,7 @@ async function uninstall() {
   // 是否同时卸载用户级组件（工具 skills + 版本检查 hook，作用于 ~/.claude 等用户目录）
   let removeUserLevel = false;
   if (fs.existsSync(USER_MANIFEST_FILE)) {
-    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder、~/.codebuddy、~/.trae-cn 的版本检查 hook）？(y/N): ');
+    const answerUser = await ask('是否同时卸载用户级组件（~/.claude、~/.qoder、~/.workbuddy、~/.trae-cn 的版本检查 hook、MiniMax Code 本地插件）？(y/N): ');
     removeUserLevel = answerUser.toLowerCase() === 'y' || answerUser.toLowerCase() === 'yes';
   }
 
@@ -1937,6 +2133,25 @@ async function uninstall() {
     skippedPaths.add(adapter.settingsFile);
   });
 
+  // 本地插件 hook（MiniMax，用户级组件）：仅确认卸载用户级时删除插件目录
+  if (removeUserLevel) {
+    adapters.forEach(adapter => {
+      if (!adapter.pluginHook) return;
+      if (pluginHookManager.remove({ dataDir: adapter.resolveDataDir(), ...adapter.pluginHook })) {
+        log(`移除 ${adapter.displayName} 版本检查插件（${adapter.resolveDataDir()}）`, 'success');
+      }
+    });
+  }
+
+  // AGENTS.md 规则导航块：本包托管块精确摘除（块外用户内容不动；文件归用户所有不进清单）
+  adapters.forEach(adapter => {
+    if (!adapter.agentsNav) return;
+    const target = path.join(TARGET_DIR, adapter.agentsNav.file);
+    if (agentsNav.remove(target, adapter.name)) {
+      log(`移除 ${adapter.agentsNav.file} 规则导航块`, 'success');
+    }
+  });
+
   // opencode.json：移除本包登记的 instructions pattern（cbb 创建的整体文件由清单删除兜底）
   removeInstructionsRegistrations();
 
@@ -1965,6 +2180,22 @@ async function uninstall() {
   // 清理 .gitignore
   cleanupGitignore();
 
+  // 移除分支感知提交防线（ADR 0002）：空间根 + .codespace/ 各应用（业务空间根专属）
+  if (detectWorkspaceRoot()) {
+    const results = [githook.uninstallGitHook(TARGET_DIR)];
+    const codeDir = path.join(TARGET_DIR, '.codespace');
+    if (fs.existsSync(codeDir)) {
+      for (const name of fs.readdirSync(codeDir)) {
+        const appDir = path.join(codeDir, name);
+        if (fs.existsSync(path.join(appDir, '.git'))) {
+          results.push(githook.uninstallGitHook(appDir));
+        }
+      }
+    }
+    const removedHooks = results.filter(r => r !== 'noop').length;
+    if (removedHooks > 0) log(`移除提交防线 pre-commit hook（${removedHooks} 个仓库）`, 'success');
+  }
+
   // 卸载用户级组件（如已确认）
   if (removeUserLevel) {
     console.log('');
@@ -1977,13 +2208,14 @@ async function uninstall() {
 // ── 上游版本检查 ──────────────────────────────────────────────
 
 /**
- * 检查 openspec / superpowers 是否有上游新版本（只读，不改动任何文件）。
+ * 检查 openspec / superpowers / external 是否有上游新版本（只读，不改动任何文件）。
  * 供 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 })),
+    external.checkUpstream().then(list => ({ name: 'external', list })),
   ]);
 
   let outdated = false;
@@ -1992,6 +2224,22 @@ async function checkUpstream() {
       log(`检查失败: ${r.reason.message}`, 'error');
       continue;
     }
+    // external 是多依赖聚合结果，逐依赖渲染
+    if (r.value.name === 'external') {
+      for (const item of r.value.list) {
+        if (item.error) {
+          log(`external/${item.name}: 检查失败: ${item.error}`, 'error');
+        } else if (!item.latest) {
+          log(`external/${item.name}: 无法获取上游版本`, 'warn');
+        } else if (item.outdated) {
+          log(`external/${item.name}: ${item.current.slice(0, 12)} → ${item.latest.slice(0, 12)}（上游有新提交）`, 'warn');
+          outdated = true;
+        } else {
+          log(`external/${item.name}: ${item.current.slice(0, 12)} 已是最新`, 'success');
+        }
+      }
+      continue;
+    }
     const { name, current, latest, outdated: isOutdated } = r.value;
     if (!latest) {
       log(`${name}: 无法获取上游版本`, 'warn');
@@ -2009,7 +2257,7 @@ async function checkUpstream() {
   }
 
   if (outdated) {
-    log('升级方式：修改对应 .version 的 pin 后，执行 cbbm update --upstream-openspec / --upstream-superpowers', 'info');
+    log('升级方式：修改对应 .version 的 pin 后，执行 cbbm update --upstream-openspec / --upstream-superpowers / --upstream-external', 'info');
   }
 }
 
@@ -2018,7 +2266,7 @@ async function checkUpstream() {
 // 入口身份：cbb（用户命令） / cbbm（内部命令，由流程、hook、Agent 技能调用）
 const ENTRY = process.env.CBB_ENTRY === 'cbbm' ? 'cbbm' : 'cbb';
 const INTERNAL_COMMANDS = ['check-update', 'check-upstream', 'wiki', 'wp'];
-const UPSTREAM_FLAGS = ['--upstream-superpowers', '--upstream-openspec'];
+const UPSTREAM_FLAGS = ['--upstream-superpowers', '--upstream-openspec', '--upstream-external'];
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -2026,11 +2274,11 @@ 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');
+  log('维护者拉源选项已迁移到 cbbm：cbbm update --upstream-superpowers / --upstream-openspec / --upstream-external', 'error');
   process.exit(1);
 }
 if (ENTRY === 'cbbm' && command === 'update' && !hasUpstreamFlag) {
-  log('cbbm update 仅用于维护者拉源（--upstream-superpowers / --upstream-openspec）', 'error');
+  log('cbbm update 仅用于维护者拉源（--upstream-superpowers / --upstream-openspec / --upstream-external）', 'error');
   log('升级已安装内容请使用 cbb update', 'warn');
   process.exit(1);
 }
@@ -2055,7 +2303,8 @@ switch (command) {
   case 'update': {
     const upstreamSuperpowers = restArgs.includes('--upstream-superpowers');
     const upstreamOpenspec = restArgs.includes('--upstream-openspec');
-    if (upstreamSuperpowers || upstreamOpenspec) {
+    const upstreamExternal = restArgs.includes('--upstream-external');
+    if (upstreamSuperpowers || upstreamOpenspec || upstreamExternal) {
       // 维护者选项：按 .version 的 pin 重新拉取上游原生内容到本包源仓库（发布流程用）
       if (upstreamSuperpowers) {
         superpowers.fetchLatestSkills().then(result => {
@@ -2088,6 +2337,26 @@ switch (command) {
           process.exit(1);
         });
       }
+      if (upstreamExternal) {
+        // 可选依赖名参数：cbbm update --upstream-external [name]（省略 = 全部）
+        const extNames = [];
+        for (let i = 0; i < restArgs.length; i++) {
+          if (restArgs[i] === '--upstream-external' && restArgs[i + 1] && !restArgs[i + 1].startsWith('-')) {
+            extNames.push(restArgs[i + 1]);
+          }
+        }
+        external.fetchDeps(extNames).then(results => {
+          const failed = results.filter(r => r.error);
+          if (failed.length > 0) {
+            failed.forEach(r => log(`external/${r.name}: 更新失败: ${r.error}`, 'error'));
+            process.exit(1);
+          }
+          log('external 外部依赖完整性校验通过', 'success');
+        }).catch(err => {
+          log(`更新失败: ${err.message}`, 'error');
+          process.exit(1);
+        });
+      }
     } else {
       updateInstalled().catch(err => {
         log(err.message, 'error');
@@ -2142,12 +2411,13 @@ function showHelp() {
 @jspg-ai/coding-bb v${pkg.version} — cbbm：内部命令（由流程 / hook / Agent 技能调用）
 
   cbbm check-update          版本检查（用户级 hook 每日自动触发）
-  cbbm check-upstream        检查 openspec / superpowers 是否有上游新版本
+  cbbm check-upstream        检查 openspec / superpowers / external 是否有上游新版本
   cbbm wiki / cbbm wp        Wiki 查询与发布（AI 通过技能调用）
 
 维护者选项（按 .version 的 pin 重新拉取上游原生内容到本包源仓库）：
   cbbm update --upstream-superpowers    按 pin tag 拉取 superpowers skills（走镜像）
   cbbm update --upstream-openspec       按 pin 版本从 npmmirror 渲染 OpenSpec 工作流
+  cbbm update --upstream-external [名]  按 pin sha 拉取 external 外部依赖（省略名 = 全部，走镜像）
 `);
     return;
   }