@jspg-ai/coding-bb 0.0.3-beta.30 → 0.0.3-beta.32

package/cbb/lib/external/index.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * External 小型外部依赖管理模块
+ *
+ * 管理顶层 external/ 目录下的零散第三方依赖（当前为 frontend-design skill，
+ * 来源 anthropics/skills）。与 superpowers / openspec 的整仓 pin 不同，
+ * 这里是「一依赖一目录、pin 文件放依赖自己的子目录内」的轻量形态：
+ *
+ *   external/<dep-name>/
+ *   ├── .version        # pin：{ repo, ref(commit sha), path(tarball 内子路径), updatedAt }
+ *   └── ...             # 上游 path 子目录的内容（如 SKILL.md + LICENSE.txt）
+ *
+ * 新增外部依赖 = 在 external/ 下新建子目录并写入 .version，无需改本模块。
+ *
+ * 网络：GitHub 直连可能被墙 / 被本机 DNS 劫持，走 config/upstream-mirrors.json
+ * 的 'external' 镜像前缀列表（按顺序尝试，首个成功即用；空字符串 = 直连）。
+ *
+ * 升级方式：cbbm update --upstream-external [name]（按 .version 的 ref 幂等重拉，省略 name = 全部）
+ * 版本检查：cbbm check-upstream（对比 pinned sha 与上游 main 该 path 的最新提交）
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+
+// External 依赖根目录
+const EXTERNAL_DIR = path.join(SHARED_STANDARDS_DIR, 'external');
+const VERSION_FILE_NAME = '.version';
+// skill 型依赖的完整性标记（上游 path 内容含 SKILL.md 时以其校验完整性）
+const SKILL_MARKER = 'SKILL.md';
+
+const { log } = require('../utils/output');
+const { extractTarGz } = require('../utils/tar');
+const { loadMirrors, fetchWithMirrors } = require('../utils/upstream');
+
+// ── 依赖发现与 pin 读取 ──────────────────────────────────────
+
+/**
+ * 读取依赖目录内的 .version pin。字段不全 / JSON 损坏 / 文件缺失返回 null。
+ * @param {string} dir
+ * @returns {{repo: string, ref: string, path: string, updatedAt?: string}|null}
+ */
+function readPin(dir) {
+  const file = path.join(dir, VERSION_FILE_NAME);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!data || typeof data.repo !== 'string' || !data.repo.includes('/') ||
+        typeof data.ref !== 'string' || !data.ref ||
+        typeof data.path !== 'string' || !data.path) {
+      return null;
+    }
+    return data;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 扫描 external/ 下各依赖子目录，返回全部依赖（pin 无效的目录跳过并告警）。
+ * @returns {Array<{name: string, dir: string, pin: object}>}
+ */
+function listDeps() {
+  if (!fs.existsSync(EXTERNAL_DIR)) return [];
+  const deps = [];
+  for (const entry of fs.readdirSync(EXTERNAL_DIR)) {
+    const dir = path.join(EXTERNAL_DIR, entry);
+    if (!fs.statSync(dir).isDirectory()) continue;
+    const pin = readPin(dir);
+    if (!pin) {
+      log(`external/${entry}: 缺少有效 .version pin（{ repo, ref, path }），跳过`, 'warn');
+      continue;
+    }
+    deps.push({ name: entry, dir, pin });
+  }
+  return deps;
+}
+
+/**
+ * 依赖内容完整性：skill 型（上游含 SKILL.md）要求本地 SKILL.md 存在；
+ * 其余类型要求除 .version 外至少有一个条目。
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function validateDepDir(dir) {
+  if (!fs.existsSync(dir)) return false;
+  if (fs.existsSync(path.join(dir, SKILL_MARKER))) return true;
+  return fs.readdirSync(dir).some(f => f !== VERSION_FILE_NAME);
+}
+
+// ── 上游拉取 ──────────────────────────────────────────────────
+
+/** tarball 下载地址（按镜像前缀拼接；ref = commit sha，上游无 skill 粒度 tag） */
+function tarballUrl(mirror, pin) {
+  return `${mirror}https://api.github.com/repos/${pin.repo}/tarball/${pin.ref}`;
+}
+
+/**
+ * 按 .version 的 ref 下载 tarball，解压出 pin.path 子目录，内容覆盖到 external/<name>/。
+ * 幂等：pin 一致且内容完整 → 跳过重拉。.version 由本模块改写，不被上游内容覆盖。
+ * @param {string[]} [names] - 指定依赖名；省略 = 全部
+ * @returns {Promise<Array<{name: string, ref: string, skipped: boolean, error?: string}>>}
+ */
+async function fetchDeps(names) {
+  const all = listDeps();
+  let deps = all;
+  if (names && names.length > 0) {
+    const known = new Set(all.map(d => d.name));
+    const unknown = names.filter(n => !known.has(n));
+    if (unknown.length > 0) {
+      throw new Error(`未知的 external 依赖: ${unknown.join(', ')}（现有: ${[...known].join(', ') || '无'}）`);
+    }
+    deps = all.filter(d => names.includes(d.name));
+  }
+
+  const results = [];
+  for (const dep of deps) {
+    try {
+      results.push(await fetchDep(dep));
+    } catch (err) {
+      results.push({ name: dep.name, ref: dep.pin.ref, skipped: false, error: err.message });
+    }
+  }
+  return results;
+}
+
+/**
+ * 拉取单个依赖。
+ * @param {{name: string, dir: string, pin: object}} dep
+ * @returns {Promise<{name: string, ref: string, skipped: boolean}>}
+ */
+async function fetchDep(dep) {
+  const { name, dir, pin } = dep;
+
+  // pin 一致且内容完整 → 幂等跳过
+  if (validateDepDir(dir)) {
+    log(`external/${name} 已按 pin ${pin.ref.slice(0, 12)} 就位，跳过重拉`, 'success');
+    return { name, ref: pin.ref, skipped: true };
+  }
+  log(`external/${name} 内容不完整，按 pin ${pin.ref.slice(0, 12)} 拉取...`, 'info');
+
+  const mirrors = loadMirrors('external');
+  log(`正在获取 ${pin.repo}@${pin.ref.slice(0, 12)}（${mirrors.map(m => m || '直连').join(' → ')}）...`, 'info');
+  const { buffer, mirror } = await fetchWithMirrors(mirrors, m => tarballUrl(m, pin));
+  log(`已从 ${mirror || '(直连)'} 下载 ${(buffer.length / 1024).toFixed(0)} KB`, 'info');
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cbb-ext-'));
+  try {
+    extractTarGz(buffer, tmpDir);
+
+    // GitHub tarball 顶层目录名格式：<owner>-<repo>-<short-sha>
+    const topPrefix = `${pin.repo.replace('/', '-')}-`;
+    const tops = fs.readdirSync(tmpDir).filter(f => {
+      const p = path.join(tmpDir, f);
+      return fs.statSync(p).isDirectory() && f.startsWith(topPrefix);
+    });
+    if (tops.length === 0) throw new Error(`解压后未找到 ${topPrefix}* 目录`);
+
+    // pin.path 是 tarball 内相对仓库根的子路径（如 skills/frontend-design）
+    const source = path.join(tmpDir, tops[0], pin.path);
+    if (!fs.existsSync(source)) {
+      throw new Error(`上游 ${pin.repo}@${pin.ref.slice(0, 12)} 中不存在路径 ${pin.path}（ref 或 path 配置有误）`);
+    }
+
+    // 覆盖内容到 external/<name>/（cpSync 合并，.version 保留）
+    fs.cpSync(source, dir, { recursive: true });
+    if (!validateDepDir(dir)) throw new Error('拉取后完整性校验未通过');
+
+    // 刷新 pin 时间戳（ref 不变）
+    fs.writeFileSync(
+      path.join(dir, VERSION_FILE_NAME),
+      JSON.stringify({ ...pin, updatedAt: new Date().toISOString() }, null, 2) + '\n'
+    );
+
+    log(`external/${name} 已更新: ${pin.repo}@${pin.ref.slice(0, 12)}`, 'success');
+    return { name, ref: pin.ref, skipped: false };
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+}
+
+/**
+ * 检查全部依赖上游是否有新提交（只读，不改动任何文件）。
+ * 对比 pinned sha 与上游 main 分支 pin.path 的最新提交 sha
+ * （commits?path= 只统计该子路径的变更，仓库其他目录的提交不告警）。
+ * 单依赖失败不阻塞其他依赖（返回 {name, error} 条目）。
+ * @returns {Promise<Array<{name: string, current: string, latest: string, outdated: boolean}|{name: string, error: string}>>}
+ */
+async function checkUpstream() {
+  const deps = listDeps();
+  const results = await Promise.allSettled(deps.map(async dep => {
+    const mirrors = loadMirrors('external');
+    const { buffer } = await fetchWithMirrors(mirrors, m =>
+      `${m}https://api.github.com/repos/${dep.pin.repo}/commits?path=${encodeURIComponent(dep.pin.path)}&sha=main&per_page=1`
+    );
+    const data = JSON.parse(buffer.toString('utf-8'));
+    const latest = Array.isArray(data) && data[0] ? data[0].sha : null;
+    return {
+      name: dep.name,
+      current: dep.pin.ref,
+      latest,
+      outdated: Boolean(latest && latest !== dep.pin.ref),
+    };
+  }));
+  return results.map((r, i) => r.status === 'fulfilled'
+    ? r.value
+    : { name: deps[i].name, error: r.reason.message });
+}
+
+// ── 导出 ──────────────────────────────────────────────────────
+
+module.exports = {
+  // 常量
+  EXTERNAL_DIR,
+  VERSION_FILE_NAME,
+  SKILL_MARKER,
+
+  // 核心函数
+  listDeps,
+  readPin,
+  validateDepDir,
+  fetchDeps,
+  checkUpstream,
+  tarballUrl,
+};

package/cbb/lib/install/claude-code.js

@@ -4,8 +4,8 @@
  * 将编码规范分发到 .claude/rules/ 目录
  *
  * 退市（selectable: false）：团队当前不使用 Claude Code，不在安装面板提供。
- * 适配器代码与全部能力保留（含用户级 settings hook）；先前已安装的空间按
- * .last-tools 记录**粘性维护**（见 tool-selection.js），内容不被清理。
+ * 适配器代码与全部能力保留（含用户级 settings hook）；旧记录中的遗留内容
+ * 不在勾选范围时随清单差集与用户级差集清理移除（ADR 0006）。
  * 恢复入口：删掉 selectable 即可重新出现在面板（决策：不留参数开关）。
  */
 
@@ -22,6 +22,6 @@ module.exports = {
   settingsFile: path.join(os.homedir(), '.claude', 'settings.json'),
   settingsFileIsUserLevel: true,
   hookEvents: ['UserPromptSubmit'],
-  // 退市：不在安装面板提供（代码保留，存量空间粘性维护）
+  // 退市：不在安装面板提供（代码保留；旧记录遗留随清单/用户级差集清理，ADR 0006）
   selectable: false,
 };

package/cbb/lib/install/init.js

@@ -84,6 +84,11 @@ const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktre
 // 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'];
@@ -100,7 +105,7 @@ const agentsNav = require('./agents-nav');
 // 命令 → skill 形态转换（commandsAsSkills 适配器，当前仅 MiniMax Code）
 const commandSkill = require('./command-skill');
 
-// 工具选择策略（退市工具不在面板提供 + 存量粘性保留）
+// 工具选择策略（退市工具不在面板提供；勾选范围即权威，ADR 0006）
 const toolSelection = require('./tool-selection');
 
 /** 适配器的 hook 方言参数（Trae 需顶层 version 字段等差异） */
@@ -156,6 +161,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');
@@ -376,10 +384,7 @@ async function selectTools(isUpgrade) {
       .map(i => selectable[i]);
   }
 
-  // 退市但该空间旧记录里有的工具：粘性保留（继续维护，不因退市清删其内容）
-  result = toolSelection.carryOverRetired(adapters, result, lastTools);
-
-  // 保存本次选择（含粘性保留项，避免记录丢失导致下次被清理），供下次运行时预选
+  // 保存本次选择（勾选范围即权威，供下次运行时预选）
   saveLastTools(result);
   return result;
 }
@@ -1046,7 +1051,8 @@ async function init(targetDir, options = {}) {
     fromRecord = true;
   } else if (isNonInteractive) {
     const lastTools = readLastTools();
-    const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
+    // 旧记录只用于预选可选项——历史遗留的退市工具不并回（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) {
@@ -1058,19 +1064,10 @@ async function init(targetDir, options = {}) {
     selectedAdapters = await selectTools(isUpgrade);
   }
 
-  // 退市工具粘性保留（面板不出现，但本空间旧记录里有 → 继续维护，内容不被清理）。
-  // 覆盖面板外入口：setup 预设（presetAdapters）与非交互记录沿用；交互面板已在 selectTools 内并过。
-  const lastToolsForDir = readLastTools();
-  const withRetired = toolSelection.carryOverRetired(adapters, selectedAdapters, lastToolsForDir);
-  const retiredKept = toolSelection.retiredNames(withRetired);
-  if (retiredKept.length > 0) {
-    log(`保留上次选择的退市工具：${retiredKept.join('、')}（当前不在安装面板提供，内容继续维护）`, 'dim');
-  }
-  selectedAdapters = withRetired;
+  // 退市工具不粘性保留（ADR 0006）：选择集即权威，旧记录里的退市工具随清单差集清理
 
-  // 业务空间根记录本次选择，供 cbb update 等非交互场景沿用；
-  // 沿用旧记录时同样落盘，使历史工具名（codebuddy → workbuddy）归一化自愈
-  if (isWorkspaceRoot && fromRecord) {
+  // 本次选择落盘（沿用旧记录时同样落盘：归一化历史工具名 + 剔除退市遗留记录）
+  if (fromRecord) {
     saveLastTools(selectedAdapters);
   }
 
@@ -1156,6 +1153,22 @@ 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);
   }
@@ -1847,8 +1860,10 @@ 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（与具体项目无关，任何会话都可能用到）。
@@ -1860,15 +1875,18 @@ async function setupUserLevelComponents(targetAdapters = toolSelection.selectabl
   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 = [];
 
@@ -1915,6 +1933,43 @@ async function setupUserLevelComponents(targetAdapters = toolSelection.selectabl
     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'));
@@ -1931,9 +1986,10 @@ async function setupUserLevelComponents(targetAdapters = toolSelection.selectabl
  * worktree 管理入口与空间导航；旧子集清单升级时由清单差集机制自动补齐全量内容。
  */
 async function updateInstalled() {
-  // 用户级组件沿用本目录的工具选择（.last-tools），无记录或为空才回退全量
+  // 用户级组件沿用本目录的工具选择（.last-tools），无记录或为空才回退全量。
+  // 旧记录只预选可选项——历史遗留的退市工具不并回（ADR 0006）
   const lastTools = readLastTools();
-  const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
+  const reused = lastTools ? toolSelection.selectableAdapters(adapters).filter(a => lastTools.has(a.name)) : [];
   await setupUserLevelComponents(reused.length > 0 ? reused : toolSelection.selectableAdapters(adapters));
 
   const manifest = readManifest();
@@ -2164,13 +2220,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;
@@ -2179,6 +2236,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');
@@ -2196,7 +2269,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');
   }
 }
 
@@ -2205,7 +2278,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];
@@ -2213,11 +2286,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);
 }
@@ -2242,7 +2315,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 => {
@@ -2275,6 +2349,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');
@@ -2329,12 +2423,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;
   }

package/cbb/lib/install/minimax.js

@@ -19,7 +19,7 @@
  * 退市（selectable: false）：实测 MiniMax Code 不支持目录级 skill 与 command
  * （无项目级 commands 目录，skill 亦需插件形态承载），当前分发形态不可用。
  * 适配器代码与全部能力保留（备将来改走插件形态），但不在安装面板提供；
- * 已安装过（beta.29）的空间按 .last-tools 记录**粘性维护**，内容不被清理。
+ * 旧记录中的遗留内容不在勾选范围时随清单差集与用户级差集清理移除（ADR 0006）。
  */
 
 const path = require('path');
@@ -55,6 +55,6 @@ module.exports = {
     timeout: 10,
   },
   resolveDataDir,
-  // 退市：不在安装面板提供（代码保留，存量空间粘性维护）
+  // 退市：不在安装面板提供（代码保留；旧记录遗留随清单/用户级差集清理，ADR 0006）
   selectable: false,
 };

package/cbb/lib/install/tool-selection.js

@@ -1,20 +1,18 @@
 'use strict';
 
 /**
- * 工具选择策略：安装面板的可见集合 + 退市工具的粘性保留。
+ * 工具选择策略：安装面板的可见集合（未退市适配器）。
  *
  * 背景（2026-09-28 决策）：MiniMax Code 实测不支持目录级 skill 与 command、
  * Claude Code 团队当前未用，两者**退市**——适配器与全部能力保留（见各适配器
  * 文件头），仅不在 `cbb setup` / `cbb update` 的安装面板提供。
  *
- * 两条规则：
- *  1. **可选项**（selectableAdapters）：面板项、非交互全选兜底、setup 默认预选、
- *     用户级组件新装，一律只用未退市适配器（`selectable !== false`）；
- *  2. **粘性保留**（carryOverRetired）：某空间的 `.last-tools` 记录过退市工具
- *     （即确曾安装），则继续纳入本次安装/升级集合——面板不出现，内容不因退市
- *     被清单差集清删；`.last-tools` 一并保持该记录，避免记录丢失导致下次清理。
- *
- * 恢复入口：删掉适配器的 `selectable: false` 即回到面板（决策：不留参数开关）。
+ * 退市工具的取舍（ADR 0006，反转 beta.30 的粘性保留决策）：
+ *  - 退市工具**不进**选择集：面板、非交互沿用、setup 预设、用户级组件，
+ *     一律只用未退市适配器（`selectable !== false`）；
+ *  - 勾选范围即权威：`.last-tools` 只如实记录本次实际选择，不在范围内的
+ *     工具内容（含用户级 hook / 插件）由清单差集与用户级差集清理移除；
+ *  - 恢复入口：删掉适配器的 `selectable: false` 即回到面板。
  */
 
 /** 面板/默认可选适配器（未标 selectable: false 的全部） */
@@ -22,24 +20,4 @@ function selectableAdapters(adapters) {
   return adapters.filter(a => a.selectable !== false);
 }
 
-/**
- * 把「本空间旧记录中的退市工具」并入选择结果（按注册表顺序追加，去重）。
- * @param {Array} adapters 注册表全量
- * @param {Array} selected 本次选择（面板 / 预设 / 记录沿用）
- * @param {Set<string>|null} lastTools 该空间的旧工具记录（.last-tools）
- * @returns {Array} 并入后的有序数组（无退市工具需保留时原样返回）
- */
-function carryOverRetired(adapters, selected, lastTools) {
-  if (!lastTools || lastTools.size === 0) return selected;
-  const selectedNames = new Set(selected.map(a => a.name));
-  const carried = adapters.filter(a =>
-    a.selectable === false && lastTools.has(a.name) && !selectedNames.has(a.name));
-  return carried.length > 0 ? selected.concat(carried) : selected;
-}
-
-/** 结果集中退市工具的显示名（供安装输出提示，如「保留上次选择的 Claude Code」） */
-function retiredNames(selected) {
-  return selected.filter(a => a.selectable === false).map(a => a.displayName);
-}
-
-module.exports = { selectableAdapters, carryOverRetired, retiredNames };
+module.exports = { selectableAdapters };

package/cbb/worktrees/skills/cbb-local-mode/SKILL.md

@@ -73,7 +73,7 @@ node "<skill_dir>/scripts/start-local.js" "<ws_root>" "<branch>" --apps "<app1>,
 
 ## Step 4：提交推送（转 cbb-worktree-push）
 
-对话中说"提交并推送"即触发 `cbb-worktree-push`——其仓库发现已支持**本地布局**（根 + 持有同名分支的 `.codespace/<app>/`），dry-run 预览 → 用户确认 commit 信息 → 批量 commit → push → MR 预填链接，全流程与 worktree 模式一致。
+对话中说"提交并推送"即触发 `cbb-worktree-push`——其仓库发现已支持**本地布局**（根 + 持有同名分支的 `.codespace/<app>/`），dry-run 预览（含 agent 生成的 commit 信息）→ 批量 commit → push → MR 预填链接，全流程与 worktree 模式一致。
 
 ## Step 5：收尾（MR 合并后）
 

package/cbb/worktrees/skills/cbb-worktree-init/SKILL.md

@@ -265,7 +265,7 @@ node "<skill_dir>/scripts/create-branches.js" "<ws_root>" "<branch>" [--apps "ap
 
 ### 3.4 分支就位（lazy push，不推远端）
 
-**本技能不执行任何远端推送（ADR 0002 lazy push）**：分支创建止步于本地。远端副作用收敛到 `cbb-worktree-push` 唯一出口（dry-run 预览 → 用户确认 commit 信息 → push → MR 链接）——推送类失败（认证/网络/保护分支）在 push 技能内暴露并处理，不在创建流程中阻塞。
+**本技能不执行任何远端推送（ADR 0002 lazy push）**：分支创建止步于本地。远端副作用收敛到 `cbb-worktree-push` 唯一出口（dry-run 预览 → agent 生成 commit 信息并提交 → push → MR 链接）——推送类失败（认证/网络/保护分支）在 push 技能内暴露并处理，不在创建流程中阻塞。
 
 > 旧版在本步骤推送空分支建立 upstream（`push-branches.js`），自 0.0.3-beta.22 起移除：避免每个需求在远端留下空分支尸体；`push-worktrees.js` 首次推送时自动建立 upstream，行为等价。