@jspg-ai/coding-bb 0.0.3-beta.3 → 0.0.3-beta.31

package/cbb/lib/utils/githook.js

@@ -0,0 +1,226 @@
+'use strict';
+
+/**
+ * git pre-commit hook：分支感知提交防线（ADR 0002）。
+ *
+ * 策略（对当前仓库生效，worktree 与主仓库共享 .git/hooks 故一并覆盖）：
+ *   - 当前分支非主干（含 detached HEAD）→ 一律放行（两模式开发态都在需求分支上）
+ *   - workspace 仓库（检出含 CBB-WORKSPACE.json）在主干上 → 只放行控制面白名单路径：
+ *     CBB-WORKSPACE.json / .gitignore / AGENTS.md / openspec/config.yaml /
+ *     openspec/schemas/** / .cbb/**（配置变更与 cbb update 部署物，直改即推）；
+ *     另放行旧名 workspace-config.json 的删除条目（仅用于一次性更名迁移）
+ *   - 应用仓库在主干上 → 全拦（交付只走 MR）
+ *   - 逃生口：用户显式 git commit --no-verify（AI 侧纪律禁止自动绕过）
+ *
+ * 本模块是 hook 源码的唯一真源；cbb/worktrees/_shared/scripts/install-git-hook.js
+ * 部署到业务空间后独立运行，内嵌同一份源码副本（改动须两处同步）。
+ *
+ * 提供纯函数（isCbbHookContent / buildPreCommitSource）与 I/O 包装
+ * （installGitHook / uninstallGitHook），供 init.js 的 setup / update / uninstall 调用。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const HOOK_MARKER = 'managed-by-cbb';
+const HOOK_FILE = 'pre-commit';
+const BACKUP_SUFFIX = '.cbb-backup';
+
+// 部署到仓库后的 hook 源码（独立 Node 脚本，无外部依赖）。
+// 注意：源码内不使用反引号，便于本模块以模板字符串承载。
+const PRE_COMMIT_SOURCE = [
+  '#!/usr/bin/env node',
+  '// managed-by-cbb v1 —— 分支感知提交防线（ADR 0002）',
+  '// main 上：workspace 仓库只放行控制面白名单，应用仓库全拦；非 main 一律放行。',
+  '// 绕过逃生口仅限用户显式 git commit --no-verify。',
+  "const { execSync } = require('child_process');",
+  "const fs = require('fs');",
+  'function run(cmd) {',
+  "  try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }",
+  '  catch (e) { return null; }',
+  '}',
+  "const branch = run('git branch --show-current') || '';",
+  '// 主干名：优先远端 HEAD 指向；探测失败按本地 main/master 存在性回退',
+  'let main = null;',
+  "const remotes = run('git remote');",
+  'if (remotes) {',
+  "  const r = remotes.split(/\\r?\\n/)[0];",
+  "  const sym = run('git symbolic-ref \"refs/remotes/' + r + '/HEAD\"');",
+  "  if (sym) main = sym.replace('refs/remotes/' + r + '/', '');",
+  '}',
+  "if (!main) {",
+  "  if (run('git rev-parse --verify --quiet refs/heads/main')) main = 'main';",
+  "  else if (run('git rev-parse --verify --quiet refs/heads/master')) main = 'master';",
+  '}',
+  '// 非主干（含 detached / 探测失败）→ 放行',
+  'if (!main || branch !== main) process.exit(0);',
+  '',
+  "// 主干上的提交：收集 staged 变更（空提交放行）",
+  "const staged = run('git diff --cached --name-only') || '';",
+  "const files = staged.split(/\\r?\\n/).filter(Boolean);",
+  'if (files.length === 0) process.exit(0);',
+  '',
+  '// 仓库类型：workspace 仓库 = 检出含 CBB-WORKSPACE.json（或旧名，改名过渡期识别）',
+  "const isWorkspace = fs.existsSync('CBB-WORKSPACE.json') || fs.existsSync('workspace-config.json');",
+  '',
+  'function deny(bad) {',
+  "  console.error('[cbb-guard] 主干上拦截载荷提交（ADR 0002）：');",
+  "  bad.forEach(f => console.error('  ' + f));",
+  "  console.error('需求载荷须在需求分支上提交：本地模式先 git checkout -b <需求名>；worktree 模式在 .worktrees/ 工作树内提交。');",
+  "  console.error('控制面白名单：CBB-WORKSPACE.json / .gitignore / AGENTS.md / openspec/config.yaml / openspec/schemas/** / .cbb/**');",
+  "  console.error('如确需在主干提交，须由用户显式 git commit --no-verify。');",
+  '  process.exit(1);',
+  '}',
+  '',
+  'if (isWorkspace) {',
+  '  // 旧名仅放行删除条目：更名迁移提交（git mv）会产生旧名删除 + 新名新增两条',
+  "  const EXACT = new Set(['CBB-WORKSPACE.json', 'workspace-config.json', '.gitignore', 'AGENTS.md', 'openspec/config.yaml']);",
+  "  const PREFIXES = ['openspec/schemas/', '.cbb/'];",
+  '  const bad = files.filter(f => !EXACT.has(f) && !PREFIXES.some(p => f.indexOf(p) === 0));',
+  '  if (bad.length) deny(bad);',
+  '} else {',
+  '  deny(files);',
+  '}',
+  'process.exit(0);',
+].join('\n');
+
+/**
+ * 内容是否为本包管理的 hook（含标记行）。
+ */
+function isCbbHookContent(content) {
+  return typeof content === 'string' && content.includes(HOOK_MARKER);
+}
+
+/**
+ * hook 源码（纯函数，便于单测与未来按仓库定制）。
+ */
+function buildPreCommitSource() {
+  return PRE_COMMIT_SOURCE + '\n';
+}
+
+/**
+ * 解析仓库的 hooks 目录。
+ * 优先 core.hooksPath 配置（相对路径基于仓库根）；未配置或读取失败回退 .git/hooks。
+ * @returns {string|null} 绝对路径；目录不可用时返回 null（调用方跳过安装）
+ */
+function resolveHooksDir(repoPath) {
+  let configured = null;
+  try {
+    configured = execSync('git config core.hooksPath', {
+      cwd: repoPath,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+  } catch (_) { /* 未配置 */ }
+
+  let dir;
+  if (configured) {
+    dir = path.isAbsolute(configured) ? configured : path.join(repoPath, configured);
+  } else {
+    const gitDir = path.join(repoPath, '.git');
+    if (!fs.existsSync(gitDir)) return null; // 非 git 仓库（或 .git 为 worktree 文件，见下）
+    // worktree 检出的 .git 是文件（内容 "gitdir: ..."）；hook 安装统一走主仓库，
+    // 调用方应传主仓库路径。此处对文件形态直接放弃，避免误建目录。
+    const st = fs.statSync(gitDir);
+    if (!st.isDirectory()) return null;
+    dir = path.join(gitDir, 'hooks');
+  }
+  return dir;
+}
+
+/**
+ * 安装（幂等，可用于升级覆盖）：
+ *   - 无既有 hook → 写入
+ *   - 既有本包 hook → 覆盖（升级）
+ *   - 既有用户 hook → 备份为 pre-commit.cbb-backup 后写入；卸载时恢复
+ * @param {string} repoPath 仓库根（主仓库；worktree 共享 hooks 无需重复安装）
+ * @returns {'installed' | 'updated' | 'skipped-not-git' | 'skipped-no-dir'}
+ */
+function installGitHook(repoPath) {
+  const dir = resolveHooksDir(repoPath);
+  if (!dir) return 'skipped-not-git';
+
+  const hookPath = path.join(dir, HOOK_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+
+  let prev = null;
+  if (fs.existsSync(hookPath)) {
+    prev = fs.readFileSync(hookPath, 'utf-8');
+    if (isCbbHookContent(prev)) {
+      if (prev === buildPreCommitSource()) return 'updated'; // 幂等：同版本
+      fs.writeFileSync(hookPath, buildPreCommitSource());
+      return 'updated';
+    }
+    // 用户自有 hook：备份后接管
+    fs.writeFileSync(hookPath + BACKUP_SUFFIX, prev);
+  }
+  fs.writeFileSync(hookPath, buildPreCommitSource());
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) { /* Windows 无压力 */ }
+  return 'installed';
+}
+
+/**
+ * 卸载：
+ *   - 当前 hook 是本包的 → 删除；有备份则恢复
+ *   - 当前 hook 非本包（用户已接管）→ 不动，仅清掉残留备份
+ * @returns {'removed' | 'restored-backup' | 'noop'}
+ */
+function uninstallGitHook(repoPath) {
+  const dir = resolveHooksDir(repoPath);
+  if (!dir) return 'noop';
+
+  const hookPath = path.join(dir, HOOK_FILE);
+  const backupPath = hookPath + BACKUP_SUFFIX;
+  let result = 'noop';
+
+  if (fs.existsSync(hookPath)) {
+    const content = fs.readFileSync(hookPath, 'utf-8');
+    if (isCbbHookContent(content)) {
+      fs.unlinkSync(hookPath);
+      result = 'removed';
+      if (fs.existsSync(backupPath)) {
+        fs.renameSync(backupPath, hookPath);
+        result = 'restored-backup';
+      }
+    }
+  } else if (fs.existsSync(backupPath)) {
+    // hook 已被用户删除但备份残留：不擅自恢复，只清备份
+    fs.unlinkSync(backupPath);
+  }
+  return result;
+}
+
+/**
+ * 对业务空间批量安装：空间根仓库 + .codespace/ 下每个应用仓库。
+ * @param {string} wsRoot 业务空间根
+ * @returns {{ root: string, apps: {name: string, status: string}[] }}
+ */
+function installGitHooksForWorkspace(wsRoot) {
+  const root = installGitHook(wsRoot);
+  const apps = [];
+  const codeDir = path.join(wsRoot, '.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'))) {
+        apps.push({ name, status: installGitHook(appDir) });
+      }
+    }
+  }
+  return { root, apps };
+}
+
+module.exports = {
+  HOOK_MARKER,
+  HOOK_FILE,
+  BACKUP_SUFFIX,
+  PRE_COMMIT_SOURCE,
+  isCbbHookContent,
+  buildPreCommitSource,
+  resolveHooksDir,
+  installGitHook,
+  uninstallGitHook,
+  installGitHooksForWorkspace,
+};

package/cbb/lib/utils/gitignore.js

@@ -4,7 +4,8 @@
  * .gitignore 管理的纯函数工具（无副作用，便于单测；由 init.js 的 I/O 层调用）。
  *
  * 安装时：若 .gitignore 已含某目录（认可带/不带尾斜杠两种形式），则不重复添加；
- *         否则新增无尾斜杠形式（.claude / .qoder，更通用）。.cbb/ 维持带斜杠。
+ *         否则新增无尾斜杠形式（.claude / .qoder，更通用）。.cbb/ / .codespace/ /
+ *         .worktrees/ 这类纯目录路径维持带斜杠。
  * 卸载时：移除本包曾写入的所有形式（新旧版本均覆盖）。
  *
  * 注意：.gitignore 条目无 _managedBy 之类的标记，卸载按"形式匹配"移除，
@@ -13,12 +14,24 @@
 
 // 各目录：add = 写入形式；accept = 视为"已存在 / 需卸载移除"的可接受形式（含尾斜杠变体）。
 // .claude / .qoder 写无尾斜杠形式，但检测/卸载时同时认可带斜杠变体，避免重复添加、覆盖旧版本。
+// .worktrees/ 自 0.0.3-beta.22 起随 setup 写入（ADR 0002：本地模式下 main 工作区恒净，
+// 不再依赖 worktree-init 把该条目提交到 feature 分支——那会导致首个分支合并前 main 恒脏）。
 const GITIGNORE_RULES = [
   { add: '.claude', accept: ['.claude', '.claude/'] },
   { add: '.qoder', accept: ['.qoder', '.qoder/'] },
   { add: '.cbb/', accept: ['.cbb/'] },
   { add: '.codespace/', accept: ['.codespace/', '.codespace'] },
+  { add: '.worktrees/', accept: ['.worktrees/', '.worktrees'] },
   { add: '.opencode', accept: ['.opencode', '.opencode/'] },
+  // .codebuddy：beta.15 及以前写入的旧目录，不再新增（add: null），但卸载/清理时仍移除其行
+  { add: null, accept: ['.codebuddy', '.codebuddy/'] },
+  { add: '.workbuddy', accept: ['.workbuddy', '.workbuddy/'] },
+  // .trae-cn：beta.19 误把中国版项目级目录当成 .trae-cn（实为用户级目录），beta.20 起不再新增，
+  // 但卸载/清理时仍移除其 gitignore 行
+  { add: null, accept: ['.trae-cn', '.trae-cn/'] },
+  { add: '.trae', accept: ['.trae', '.trae/'] },
+  // .minimax：MiniMax Code 项目级配置根（rules / skills）
+  { add: '.minimax', accept: ['.minimax', '.minimax/'] },
 ];
 
 /** 将 .gitignore 文本拆为行数组。 */
@@ -29,12 +42,12 @@ function toLines(content) {
 /**
  * 给定 .gitignore 内容，返回需要新增的条目。
  * 已含任一可接受形式（带/不带尾斜杠）的目录会被跳过；全部已存在时返回空数组。
- * 返回的是写入形式（.claude / .qoder 无尾斜杠，.cbb/ 带尾斜杠）。
+ * 返回的是写入形式（.claude / .qoder 无尾斜杠，.cbb/ 带尾斜杠；add 为 null 的纯遗留规则不新增）。
  */
 function entriesToAdd(content) {
   const lines = toLines(content).map(l => l.trim());
   return GITIGNORE_RULES
-    .filter(r => !r.accept.some(a => lines.includes(a)))
+    .filter(r => r.add && !r.accept.some(a => lines.includes(a)))
     .map(r => r.add);
 }
 

package/cbb/lib/utils/plugin-hook.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * MiniMax Code 本地插件 hook 的安装 / 卸载工具。
+ *
+ * MiniMax 无 Claude 式 settings.json hooks（hooks 仅插件作用域），版本检查改由
+ * 用户级本地插件承担：
+ *   <dataDir>/plugins/cbb-check-update/
+ *     .claude-plugin/plugin.json    兼容 manifest（仅 name 必填，走 CLAUDE 兼容读取器）
+ *     hooks/hooks.json              manifest 未声明 hooks 时的默认路径
+ *
+ * 机制（源码考证）：
+ *  - 本地插件根为 path.join(dataDir, 'plugins')，由扫描自动发现并热加载
+ *    （package-storage.ts + watcher），无需重启 mcode；
+ *  - 本地插件默认启用（不在 pluginDisabledLocalRoots 表即启用）；
+ *  - hook 事件 UserPromptSubmit，stdin 收 session_id JSON（与 Claude 同构），
+ *    输出 hookSpecificOutput.additionalContext 注入对话；
+ *  - timeout 单位为秒（1–10，超限视为非法回落 5s）；非 0 退出码（exit 2）会拒绝
+ *    prompt —— check-update.js 恒 exit 0，绝不阻塞；
+ *  - Windows 下 CLAUDE 格式命令经 Git Bash / PowerShell 执行（不走 cmd.exe）。
+ *
+ * 本插件目录整目录归本包管理：安装幂等覆盖本包两个文件，卸载直接删除目录。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** 插件目录：dataDir + plugins + dirName */
+function pluginDir({ dataDir, dirName }) {
+  return path.join(dataDir, 'plugins', dirName);
+}
+
+/** 幂等写入（内容一致不重写，避免触发插件 digest 重算） */
+function writeIfChanged(file, content) {
+  if (fs.existsSync(file) && fs.readFileSync(file, 'utf-8') === content) return false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+  return true;
+}
+
+/**
+ * 安装（幂等）版本检查插件。
+ *
+ * @param {object} opts
+ * @param {string} opts.dataDir mcode 数据目录（由适配器 resolveDataDir 解析）
+ * @param {string} opts.dirName 插件目录名（cbb-check-update）
+ * @param {string[]} opts.events hook 事件（['UserPromptSubmit']）
+ * @param {number} opts.timeout 秒（1–10）
+ * @param {string} opts.command hook 命令（node "<check-update.js>"）
+ * @param {string} opts.version 插件 manifest 版本（= 本包版本）
+ * @returns {{dir: string, changed: boolean}}
+ */
+function install({ dataDir, dirName, events, timeout, command, version }) {
+  const root = pluginDir({ dataDir, dirName });
+
+  const manifest = {
+    name: dirName,
+    description: '@jspg-ai/coding-bb 版本检查 hook（UserPromptSubmit 触发，每日最多请求一次 registry）',
+    version: version || '0.0.0',
+    author: 'jspg-ai',
+    // 刻意不声明 hooks 字段：CLAUDE 兼容读取器对未声明的 hooks 走默认路径
+    // hooks/hooks.json（readPluginCapabilities 的 defaultPath），结构最稳。
+  };
+
+  const hooksDoc = {
+    hooks: Object.fromEntries(events.map(event => [event, [{
+      hooks: [{ type: 'command', command, timeout }],
+    }]])),
+  };
+
+  const changedManifest = writeIfChanged(
+    path.join(root, '.claude-plugin', 'plugin.json'),
+    JSON.stringify(manifest, null, 2) + '\n');
+  const changedHooks = writeIfChanged(
+    path.join(root, 'hooks', 'hooks.json'),
+    JSON.stringify(hooksDoc, null, 2) + '\n');
+
+  return { dir: root, changed: changedManifest || changedHooks };
+}
+
+/**
+ * 卸载版本检查插件（整目录删除）。
+ * @returns {boolean} 是否有删除动作
+ */
+function remove({ dataDir, dirName }) {
+  const root = pluginDir({ dataDir, dirName });
+  if (!fs.existsSync(root)) return false;
+  fs.rmSync(root, { recursive: true, force: true });
+  return true;
+}
+
+module.exports = { pluginDir, install, remove };

package/cbb/lib/utils/settings.js

@@ -11,6 +11,9 @@
  * removeLegacyHooks 负责清理旧版本曾写入、现已弃用的 SessionStart hook：
  * 当前仅安装 UserPromptSubmit，但升级自旧版本的用户 settings.json 中可能仍残留
  * SessionStart 条目，升级 / 卸载时需主动移除，否则会永久残留。
+ *
+ * 方言：Trae 的 hooks.json 需顶层 `version: 1` 且非 Claude 的 settings.json，
+ * 由 opts.dialect === 'trae' 处理（写入时补 version，清理干净后移除）。
  */
 
 const fs = require('fs');
@@ -53,12 +56,16 @@ function stripManaged(arr) {
  * @param {string} settingsPath settings.json 路径
  * @param {string} command 要执行的命令
  * @param {string[]} events 要写入的事件名数组，如 ['UserPromptSubmit']
+ * @param {{dialect?: string}} [opts] 方言：'trae' 时补顶层 version: 1（Trae hooks.json 要求）
  * 已存在本包标记的条目会先移除再添加（保证命令为最新路径），不重复。
  */
-function addHooks(settingsPath, command, events) {
+function addHooks(settingsPath, command, events, opts = {}) {
   const settings = readSettings(settingsPath);
   if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
 
+  // Trae hooks.json 需要顶层 version 字段（当前仅支持 1）
+  if (opts.dialect === 'trae' && settings.version === undefined) settings.version = 1;
+
   events.forEach(event => {
     settings.hooks[event] = stripManaged(settings.hooks[event]);
     const entry = { _managedBy: MANAGED_BY, hooks: [{ type: 'command', command }] };
@@ -74,9 +81,10 @@ function addHooks(settingsPath, command, events) {
  * 清理变空的事件数组 / hooks。
  * @param {string} settingsPath settings.json 路径
  * @param {string[]} events 要清理的事件名数组
+ * @param {{dialect?: string}} [opts] 方言：'trae' 时把 version 一并视为可清理字段
  * 返回 true 表示有改动。
  */
-function removeHooks(settingsPath, events) {
+function removeHooks(settingsPath, events, opts = {}) {
   if (!fs.existsSync(settingsPath)) return false;
   const settings = readSettings(settingsPath);
   if (!settings.hooks || typeof settings.hooks !== 'object') return false;
@@ -94,6 +102,11 @@ function removeHooks(settingsPath, events) {
 
   if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
 
+  // Trae：hooks 清空后 version 只是本包写入的脚手架，一并移除
+  if (opts.dialect === 'trae' && settings.version !== undefined && !settings.hooks) {
+    delete settings.version;
+  }
+
   // 文件变成空对象则删除，否则写回
   if (Object.keys(settings).length === 0) {
     fs.unlinkSync(settingsPath);
@@ -107,8 +120,8 @@ function removeHooks(settingsPath, events) {
  * 清理遗留事件下本包标记的 hook 条目（旧版本写入的 SessionStart 等）。
  * 复用 removeHooks 的清理逻辑；返回 true 表示有改动。
  */
-function removeLegacyHooks(settingsPath) {
-  return removeHooks(settingsPath, LEGACY_HOOK_EVENTS);
+function removeLegacyHooks(settingsPath, opts = {}) {
+  return removeHooks(settingsPath, LEGACY_HOOK_EVENTS, opts);
 }
 
 module.exports = {

package/cbb/lib/utils/tar.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * 跨平台 .tar.gz 解压工具。
+ *
+ * 用 zlib + 手写 tar parser，避开 OS shell tar（Windows 上是 bsdtar、行为不完全一致），
+ * 与仓库「脚本语言统一 Node.js、禁止平台绑定脚本」的约定一致。
+ *
+ * 支持：
+ *   - gzip 压缩的 tar（GitHub tarball / npm registry tgz 都是这种）
+ *   - 目录项（type '5' 或名字以 '/' 结尾）
+ *   - 跳过 pax 扩展头（'g'/'x'）等元数据伪条目
+ *   - 路径穿越防护（拒绝 ../ 逃逸 destDir）
+ *
+ * 不支持（上游 tarball 均不使用，遇到时跳过而非静默损坏）：
+ *   - GNU longname/longlink（'L'/'K'）—— 超过 100 字符的路径
+ */
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+// 非文件、非目录的 tar 条目类型（pax 扩展头、GNU 长名等）
+const META_TYPE_FLAGS = new Set(['g', 'x', 'L', 'K', 'V', 'N']);
+
+/**
+ * 解析 tar buffer，返回条目列表（不落盘）。
+ * @param {Buffer} data - 已解压的 tar 数据
+ * @returns {Array<{name: string, size: number, typeFlag: string, dataStart: number}>}
+ */
+function listTar(data) {
+  const entries = [];
+  let off = 0;
+  while (off + 512 <= data.length) {
+    const header = data.subarray(off, off + 512);
+    off += 512;
+
+    // 连续两个 512 字节零块 = tar 终止
+    if (header.every(b => b === 0)) break;
+
+    // 文件名 header[0..100]（NUL 终止）
+    let nameEnd = 0;
+    while (nameEnd < 100 && header[nameEnd] !== 0) nameEnd++;
+    const name = header.subarray(0, nameEnd).toString('utf-8');
+
+    // 文件大小 header[124..136]（八进制 ASCII）
+    const size = parseInt(header.subarray(124, 136).toString('utf-8').trim(), 8) || 0;
+
+    // 类型标志 header[156]（'0'/NUL = 普通文件，'5' = 目录）
+    const typeFlag = String.fromCharCode(header[156]);
+
+    entries.push({ name, size, typeFlag, dataStart: off });
+    off += Math.ceil(size / 512) * 512;
+  }
+  return entries;
+}
+
+/**
+ * 解压 .tar.gz buffer 到目标目录。
+ * @param {Buffer} compressed - .tar.gz 文件内容
+ * @param {string} destDir - 解压目标根目录（不存在则创建）
+ * @returns {{files: number, dirs: number}} 落盘计数
+ */
+function extractTarGz(compressed, destDir) {
+  const data = zlib.gunzipSync(compressed);
+  const root = path.resolve(destDir);
+  let files = 0;
+  let dirs = 0;
+
+  for (const entry of listTar(data)) {
+    if (!entry.name) continue;
+    // 跳过 pax 扩展头等元数据伪条目
+    if (META_TYPE_FLAGS.has(entry.typeFlag)) continue;
+
+    const target = path.resolve(root, entry.name);
+    // 路径穿越防护：解压目标必须落在 destDir 内
+    if (target !== root && !target.startsWith(root + path.sep)) continue;
+
+    if (entry.typeFlag === '5' || entry.name.endsWith('/')) {
+      fs.mkdirSync(target, { recursive: true });
+      dirs += 1;
+    } else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, data.subarray(entry.dataStart, entry.dataStart + entry.size));
+      files += 1;
+    }
+  }
+
+  return { files, dirs };
+}
+
+module.exports = { extractTarGz, listTar };

package/cbb/lib/utils/upstream.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * 上游内容拉取的共享工具。
+ *
+ * 维护者侧（cbbm update --upstream-*）需要访问 GitHub / npm registry。
+ * 本模块提供：
+ *   - 镜像前缀列表加载（config/upstream-mirrors.json，仓库内维护）
+ *   - 带重定向跟随的 HTTPS GET
+ *   - 「按镜像列表依次尝试」的拉取策略（首个成功即用）
+ *
+ * 镜像前缀为空字符串表示直连；列表末位通常放 "" 作为兜底。
+ */
+
+const fs = require('fs');
+const https = require('https');
+const path = require('path');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+const MIRRORS_FILE = path.join(SHARED_STANDARDS_DIR, 'config', 'upstream-mirrors.json');
+
+/**
+ * 读取指定上游的镜像前缀列表。
+ * 文件缺失 / 解析失败 / 未配置该上游时返回 ['']（仅直连）。
+ * @param {string} name - 上游名（如 'superpowers'）
+ * @returns {string[]}
+ */
+function loadMirrors(name) {
+  try {
+    const data = JSON.parse(fs.readFileSync(MIRRORS_FILE, 'utf-8'));
+    const list = data[name];
+    if (Array.isArray(list) && list.length > 0) {
+      return list.map(m => String(m));
+    }
+  } catch (_) { /* 回退到直连 */ }
+  return [''];
+}
+
+/**
+ * 发起 HTTPS GET，跟随重定向（最多 8 次），返回响应体 Buffer。
+ * @param {string} url
+ * @param {number} [redirectCount]
+ * @returns {Promise<Buffer>}
+ */
+function httpsGetBuffer(url, redirectCount = 0) {
+  if (redirectCount > 8) return Promise.reject(new Error('Too many redirects'));
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'cbb-cli' } }, res => {
+      if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
+        res.resume();
+        return httpsGetBuffer(res.headers.location, redirectCount + 1).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+      }
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+/**
+ * 按镜像列表依次尝试拉取，首个成功即返回。
+ * @param {string[]} mirrors - 镜像前缀列表（'' = 直连）
+ * @param {(prefix: string) => string} buildUrl - 由前缀构造完整 URL
+ * @returns {Promise<{buffer: Buffer, mirror: string, url: string}>}
+ */
+async function fetchWithMirrors(mirrors, buildUrl) {
+  const errors = [];
+  for (const mirror of mirrors) {
+    const url = buildUrl(mirror);
+    try {
+      const buffer = await httpsGetBuffer(url);
+      return { buffer, mirror, url };
+    } catch (err) {
+      errors.push(`${mirror || '(直连)'}: ${err.message}`);
+    }
+  }
+  throw new Error(`所有镜像均失败:\n  ${errors.join('\n  ')}`);
+}
+
+module.exports = {
+  MIRRORS_FILE,
+  loadMirrors,
+  httpsGetBuffer,
+  fetchWithMirrors,
+};