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

package/cbb/bin/cbbm.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 'use strict';
 
-// 内部命令入口：cbbm init / check-update / wiki / wp（由流程、hook、Agent 技能调用）
+// 内部命令入口：cbbm check-update / wiki / wp（由流程、hook、Agent 技能调用）
 process.env.CBB_ENTRY = 'cbbm';
 require('../lib/install/init.js');

package/cbb/dev-standards/rules/cbb-ai-behavior.md

@@ -99,6 +99,19 @@ trigger: always_on
 
 **检验标准：** 用户从未因"AI 直接改了代码没打招呼"而感到意外。
 
+## 8. 业务空间目录纪律
+
+**仅当工作目录是业务空间根（存在 `workspace-config.json`）时生效：写操作命令必须落在需求工作树内。**
+
+业务空间根（主分支）只负责组织与调度，不做需求开发。接到需求先建工作树（`/cbb:worktree-init` 或 `/cbb-worktree-init`），之后：
+
+- 一切产生写操作的命令（git commit / openspec / 构建 / 测试 / 文件修改）必须以 `.worktrees/worktree-<需求名>/`（或其应用子目录）为工作目录：显式 `cd` 或绝对路径
+- 禁止在空间根执行写操作：不在主分支提交代码、不在空间根创建 openspec 变更产物、不改 `.codespace/` 基准代码
+- 只读命令（git status / log、查看文件）在空间根执行无妨
+- 会话开始时确认本次需求对应的工作树路径；存在多个未完成工作树时，先与用户确认目标，不要猜
+
+**检验标准：** 空间根主分支的 `git status` 永远干净（除工具维护的配置文件外），openspec 变更产物只出现在需求工作树内。
+
 ---
 
 **这些准则生效的标志：** diff 中不必要的改动减少、不会因过度设计而重写、澄清问题在实现前而非出错后提出。

package/cbb/lib/install/init.js

@@ -8,8 +8,8 @@
  *
  * 使用方式：
  *   npm install -g @jspg-ai/coding-bb  # 首次使用
- *   npm install -g @jspg-ai/coding-bb
- *   cd your-project && cbbm init
+ *   cbb setup                          # 初始化业务空间（空间根全量安装）
+ *   cbb update                         # 就地升级已安装目录
  */
 
 const fs = require('fs');
@@ -40,7 +40,7 @@ function execCmd(file, args, opts = {}) {
 
 const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
 
-// 目标项目根目录：默认取当前 cwd，init() / initWorkspace() 可在调用前覆盖。
+// 目标项目根目录：默认取当前 cwd，init() 可在调用前覆盖。
 // 注意：使用 let 而非 const 是为了让 cbb setup 能在拉好仓库后把目标目录
 // 切到仓库根，再复用 init() 的完整安装流程，而无需把 TARGET_DIR 透传到所有 helper。
 let TARGET_DIR = process.cwd();
@@ -68,13 +68,13 @@ const SUPERPOWERS_WHITELIST = [
   'test-driven-development',        // TDD 计划结构 + TDD Evidence 方法论基底
 ];
 
-// worktree 扩展 skills 部署到沙箱的白名单：init 只在 workspace 根执行
-// （由 installWorkspaceConfig 部署），沙箱内只需 push（推送）与 close（关闭）
-const SANDBOX_WORKTREE_SKILLS = ['cbb-worktree-push', 'cbb-worktree-close'];
+// worktree 扩展 skills 部署白名单：init / close / push 三件套
+// （单层安装：业务空间根是唯一安装点，worktree 管理入口 init 同样部署在根）
+const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
 
-// 装到沙箱的 tools skills：仅 cbb-design-to-wiki（openspec 设计阶段动作）。
+// 装到空间的 tools skills：仅 cbb-design-to-wiki（openspec 设计阶段动作）。
 // cbb-wiki-ops 当前不分发（保留在源仓库，有用户需要时再加入 USER_LEVEL_SKILLS）；Java 工具不装。
-const SANDBOX_TOOLS_SKILLS = ['cbb-design-to-wiki'];
+const TOOLS_SKILLS = ['cbb-design-to-wiki'];
 
 // settings.json hook 工具
 const settingsManager = require('../utils/settings');
@@ -109,6 +109,18 @@ function detectExistingInstall() {
   return fs.existsSync(path.join(TARGET_DIR, MANIFEST_FILE));
 }
 
+/**
+ * 判定目标目录是否为业务空间根：workspace-config.json 存在且 .git 是目录。
+ * 需求工作树内也有 workspace-config.json（tracked 副本），但其 .git 是文件（gitdir 指针），
+ * 必须以 .git 形态排除——避免「在 worktree 里误跑 cbb update」被当作空间根
+ * （误装 worktree 管理入口、在错误位置报旧导航提示）。
+ */
+function detectWorkspaceRoot() {
+  if (!fs.existsSync(path.join(TARGET_DIR, 'workspace-config.json'))) return false;
+  const gitPath = path.join(TARGET_DIR, '.git');
+  return fs.existsSync(gitPath) && fs.statSync(gitPath).isDirectory();
+}
+
 // ── 清单管理 ──────────────────────────────────────────────
 
 /** 读取清单，返回 Set<path> */
@@ -801,7 +813,7 @@ async function detectUserLevelSuperpowers(selectedAdapters, yes = false) {
 // ── 主流程 ────────────────────────────────────────────────
 
 async function init(targetDir, options = {}) {
-  const { yes = false } = options;
+  const { yes = false, selectedAdapters: presetAdapters = null } = options;
 
   // 允许调用方指定目标目录（cbb setup 在拉好仓库后切到仓库根调用）。
   // 不传则保持模块级 TARGET_DIR（即调用 init 时的 cwd）。
@@ -812,16 +824,33 @@ async function init(targetDir, options = {}) {
   const action = isUpgrade ? '升级' : '安装';
   const managedPaths = readManifest();
   const newPaths = new Set();
+  const isWorkspaceRoot = detectWorkspaceRoot();
 
   console.log(`\n  🚀 ${action} @jspg-ai/coding-bb...\n`);
 
   // 先选适配器：后续的前置依赖检测仅针对所选适配器，避免误导（如选了 Qoder 却提示安装 Claude Code 的 Superpowers）
   // 非交互模式判断：显式 -y/--yes 或 stdin 非 TTY（pipe/ignore）均视为非交互
+  // 选择优先级：调用方预设（cbb setup）> .last-tools（非交互沿用）> 交互选择；无记录才回退全选
   const isNonInteractive = yes || !process.stdin.isTTY;
-  if (yes && process.stdin.isTTY) {
-    log('--yes 非交互模式，已默认选中所有适配器', 'info');
+  let selectedAdapters;
+  if (presetAdapters && presetAdapters.length > 0) {
+    selectedAdapters = presetAdapters;
+  } else if (isNonInteractive) {
+    const lastTools = readLastTools();
+    const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
+    selectedAdapters = reused.length > 0 ? reused : adapters;
+    if (yes && process.stdin.isTTY) {
+      log(reused.length > 0
+        ? `--yes 非交互模式，沿用上次工具选择：${reused.map(a => a.displayName).join('、')}`
+        : '--yes 非交互模式，无上次选择记录，已默认选中所有适配器', 'info');
+    }
+  } else {
+    selectedAdapters = await selectTools(isUpgrade);
+  }
+  // 业务空间根记录本次选择，供 cbb update 等非交互场景沿用
+  if (isWorkspaceRoot && presetAdapters && presetAdapters.length > 0) {
+    saveLastTools(selectedAdapters);
   }
-  const selectedAdapters = isNonInteractive ? adapters : await selectTools(isUpgrade);
 
   // 前置依赖检测（放在选适配器之后，只检测与所选工具相关的依赖）
   const depProgress = progress('依赖');
@@ -864,14 +893,14 @@ async function init(targetDir, options = {}) {
       }
       // 官方 OpenSpec Skills（openspec/skills/）不部署——工作流入口统一为 /opsx:* 斜杠命令
       //（openspec/commands/ 在下方 Commands 段部署），避免双形态重复
-      // worktree 扩展 Skills：沙箱内只需 push / close（init 由 workspace 根的子集安装）
-      const osExtResult = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, SANDBOX_WORKTREE_SKILLS);
+      // worktree 扩展 Skills：init / close / push 三件套（单层安装，空间根是唯一安装点）
+      const osExtResult = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, WORKTREE_SKILLS);
       if (osExtResult.count > 0) {
         osCount = osExtResult.count;
         osExtResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
       }
       // 工具 Skills：仅 cbb-design-to-wiki（设计文档发布属 openspec 设计阶段动作）
-      const extResult = deploySkills(adapter, isUpgrade, managedPaths, extendsSkillsSrc, SANDBOX_TOOLS_SKILLS);
+      const extResult = deploySkills(adapter, isUpgrade, managedPaths, extendsSkillsSrc, TOOLS_SKILLS);
       if (extResult.count > 0) {
         extCount = extResult.count;
         extResult.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
@@ -902,14 +931,13 @@ async function init(targetDir, options = {}) {
     await detectUserLevelSuperpowers(selectedAdapters, yes);
   }
 
-  // 安装 Commands（官方 12 个 → /opsx:*；worktree 管理 → /cbb:worktree-*，
-  // 仅装 close/push，init 只在 workspace 根使用，由 installWorkspaceConfig 部署）
+  // 安装 Commands（官方 12 个 → /opsx:*；worktree 管理 → /cbb:worktree-*，init/close/push 三件套）
   const commandsAdapters = selectedAdapters.filter(a => a.commandsDir);
   if (commandsAdapters.length > 0) {
     console.log(`\n  ⚡ ${action} Commands...`);
     const commandsBaseSrc = path.join(SHARED_STANDARDS_DIR, 'openspec', 'commands');
     const commandsExtendsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'commands');
-    const cmdFilter = ['worktree-close.md', 'worktree-push.md'];
+    const cmdFilter = ['worktree-init.md', 'worktree-close.md', 'worktree-push.md'];
 
     const cmdDests = [...new Set(commandsAdapters
       .flatMap(a => [a.commandsDir, a.worktreeCommandsDir])
@@ -948,6 +976,15 @@ async function init(targetDir, options = {}) {
   setupOpenSpec(isUpgrade, managedPaths);
   newPaths.add('openspec/config.yaml');
 
+  // 业务空间根专属：空间导航 AGENTS.md（仅缺失时生成，永不覆盖）+ 旧版导航文案提示
+  let agentsMdState = null;
+  if (isWorkspaceRoot) {
+    agentsMdState = workspaces.ensureWorkspaceAgentsMd(TARGET_DIR);
+    if (workspaces.detectLegacyAgentsMd(TARGET_DIR)) {
+      log('空间根 AGENTS.md 仍是旧版导航文案（单层安装改造前模板）。建议删除该文件后重跑 cbb update 重新生成（仅缺失时生成，不会覆盖你的增补内容）', 'warn');
+    }
+  }
+
   // 写入自动版本检查 hook
   const hookAdapters = selectedAdapters.filter(a => a.settingsFile && a.hookEvents);
   if (hookAdapters.length > 0) {
@@ -1015,7 +1052,7 @@ async function init(targetDir, options = {}) {
   console.log(`\n  ✅ ${action}完成！\n`);
 
   if (yes) {
-    console.log(c('dim', '  （使用 --yes 非交互模式，已默认选中所有适配器）'));
+    console.log(c('dim', `  （使用 --yes 非交互模式，工具：${selectedAdapters.map(a => a.displayName).join('、')}）`));
   }
 
   // 适配器映射（单行）
@@ -1045,161 +1082,13 @@ async function init(targetDir, options = {}) {
   if (hasSkills) extras.push('Skills');
   if (hasCommands) extras.push('Commands');
   if (hasHooks) extras.push('版本检查 hook');
+  if (agentsMdState === 'created') extras.push('AGENTS.md（空间导航）');
   if (extras.length > 0) {
     console.log(`  ${extras.join(' / ')} 已配置`);
   }
   console.log('');
 }
 
-/**
- * 为 workspace 根目录安装 AI 配置子集（由 cbb setup 调用）。
- *
- * 只装 worktree 生命周期管理（init/close/push）+ openspec 运行时配置 + 空间导航
- * AGENTS.md（仅缺失时生成，永不覆盖），不装 base 工作流、编码规范、superpowers、
- * 版本检查 hook--这些属于 sandbox worktree 内的开发配置，由 worktree 内
- * `cbbm init --yes` 完整模式安装。在 workspace 根目录
- * （主分支）装 base 工作流会诱导绕过 worktree 直接在主分支做需求开发。
- */
-async function installWorkspaceConfig(targetDir, options = {}) {
-  const { yes = false, selectedAdapters: presetAdapters = null } = options;
-  if (targetDir) TARGET_DIR = targetDir;
-
-  const isUpgrade = detectExistingInstall();
-  const managedPaths = readManifest();
-  const newPaths = new Set();
-
-  let selectedAdapters;
-  if (presetAdapters && presetAdapters.length > 0) {
-    // cbb setup 场景：上层已交互选定适配器，持久化供 cbb update 预选
-    selectedAdapters = presetAdapters;
-    saveLastTools(selectedAdapters);
-  } else {
-    const isNonInteractive = yes || !process.stdin.isTTY;
-    if (isNonInteractive) {
-      // 非交互（cbb update / 管道运行）：沿用上次工具选择，避免误装未使用的适配器
-      const lastTools = readLastTools();
-      const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
-      if (reused.length > 0) {
-        selectedAdapters = reused;
-      } else {
-        selectedAdapters = adapters;
-      }
-    } else {
-      selectedAdapters = await selectTools(isUpgrade);
-    }
-  }
-  // 只装 worktree 生命周期管理 Skills（init/close/push）
-  const skillsAdapters = selectedAdapters.filter(a => a.skillsDir);
-  const commandsAdapters = selectedAdapters.filter(a => a.worktreeCommandsDir);
-  let skillCount = 0;
-  let cmdCount = 0;
-  let adapterRoots = [];
-
-  // 「AI 配置」阶段心跳：检查依赖 → 部署 skills/commands → 写入 openspec 配置 → 生成导航。
-  // 其中 npm 查询/安装最长可达分钟级，必须让用户看到进程仍活着；任何异常先清掉进度行。
-  const cfgProgress = progress('AI 配置');
-  let agentsMdState = 'exists';
-  let openspecRes;
-  try {
-    await ensureOpenSpecCli(t => cfgProgress.update(t));
-
-    if (skillsAdapters.length > 0) {
-      cfgProgress.update('部署 skills');
-      const openspecExtendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
-      const osExtFilter = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
-      skillsAdapters.forEach(adapter => {
-        const r = deploySkills(adapter, isUpgrade, managedPaths, openspecExtendsSkillsSrc, osExtFilter);
-        if (r.count > 0) {
-          skillCount = Math.max(skillCount, r.count);
-          r.names.forEach(name => newPaths.add(`${adapter.skillsDir}/${name}`));
-        }
-      });
-      adapterRoots = skillsAdapters.map(a => a.skillsDir.split('/')[0]);
-    }
-
-    // 只装 worktree 管理 Commands（cbb:worktree-init/close/push）
-    if (commandsAdapters.length > 0) {
-      cfgProgress.update('部署 worktree 命令');
-      const commandsExtendsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'commands');
-      const cmdFilter = ['worktree-init.md', 'worktree-close.md', 'worktree-push.md'];
-      commandsAdapters.forEach(adapter => {
-        const r = deployWorktreeCommands(adapter, commandsExtendsSrc, cmdFilter);
-        if (r.count > 0) {
-          cmdCount = Math.max(cmdCount, r.count);
-          r.names.forEach(name => newPaths.add(`${adapter.worktreeCommandsDir}/${name}`));
-        }
-      });
-      if (adapterRoots.length === 0) adapterRoots = commandsAdapters.map(a => a.worktreeCommandsDir.split('/')[0]);
-    }
-
-    // 设置 OpenSpec 工作流（config.yaml + schemas）
-    cfgProgress.update('写入 openspec 配置');
-    const schemasSrcs = [
-      path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
-    ];
-    schemasSrcs.forEach(src => {
-      if (fs.existsSync(src)) {
-        fs.readdirSync(src).filter(f2 => fs.statSync(path.join(src, f2)).isDirectory())
-          .forEach(name => newPaths.add(`openspec/schemas/${name}`));
-      }
-    });
-    openspecRes = setupOpenSpec(isUpgrade, managedPaths);
-    newPaths.add('openspec/config.yaml');
-
-    // 空间导航文件 AGENTS.md：仅缺失时生成，永不覆盖（不登记清单，卸载不删）
-    cfgProgress.update('生成空间导航');
-    agentsMdState = workspaces.ensureWorkspaceAgentsMd(TARGET_DIR);
-  } finally {
-    cfgProgress.done();
-  }
-
-  // 升级时清理旧路径（workspace 曾装过的 base 工作流等不属于此子集，删除）
-  const cleaned = [];
-  const keptDocs = [];
-  if (isUpgrade) {
-    const oldPaths = pathsToDelete(managedPaths, newPaths);
-    oldPaths.forEach(oldPath => {
-      const targetPath = path.join(TARGET_DIR, oldPath);
-      if (fs.existsSync(targetPath)) {
-        removePath(targetPath);
-        cleaned.push(oldPath);
-      }
-    });
-    keptDocs.push(...protectedKeptPaths(managedPaths, newPaths));
-    (skillsAdapters || []).forEach(adapter => {
-      const legacyNodeModules = path.join(TARGET_DIR, adapter.skillsDir, 'node_modules');
-      if (fs.existsSync(legacyNodeModules)) {
-        removePath(legacyNodeModules);
-        cleaned.push(`${adapter.skillsDir}/node_modules`);
-      }
-    });
-  }
-
-  writeManifest(newPaths, selectedAdapters);
-  updateGitignore();
-
-  // 汇总输出（一行主结果 + 可选清理/保留明细）
-  const rootLabel = [...new Set(adapterRoots)].join('/');
-  const parts = [];
-  if (skillCount > 0) parts.push(`${rootLabel} skills×${skillCount}`);
-  if (cmdCount > 0) parts.push(`commands×${cmdCount}`);
-  if (openspecRes.installed.length > 0) {
-    parts.push(`openspec ${openspecRes.defaultSchema || openspecRes.installed.join('/')}`);
-  }
-  if (agentsMdState === 'created') parts.push('AGENTS.md（空间导航）');
-  const configLabel = 'AI 配置';
-  step('✓', configLabel, parts.join(' · '));
-  if (cleaned.length > 0) {
-    const MAX_DISPLAY = 3;
-    const preview = cleaned.slice(0, MAX_DISPLAY).join('、');
-    step('!', '清理残留', `${cleaned.length} 个（${preview}${cleaned.length > MAX_DISPLAY ? ' 等' : ''}）`,
-      { iconColor: 'yellow' });
-  }
-  if (keptDocs.length > 0) {
-    step('!', '保留文档', `${keptDocs.join('、')}（本包已不再管理）`, { iconColor: 'yellow' });
-  }
-}
-
 // ── cbb setup 命令 ──────────────────────────────────────
 
 /**
@@ -1521,9 +1410,9 @@ async function initSingleWorkspace(w, opts = {}) {
     return { ok: true, subdir: subdirName, upToDate: true };
   }
 
-  // 6. 安装 workspace AI 配置子集（worktree 管理技能/命令 + openspec 配置，不含 base 工作流）
+  // 6. 安装空间 AI 配置（单层全量：开发配置 + worktree 管理，统一安装器自动识别空间根）
   try {
-    await installWorkspaceConfig(targetDir, { yes: true, selectedAdapters: opts.selectedAdapters });
+    await init(targetDir, { yes: true, selectedAdapters: opts.selectedAdapters });
     return { ok: true, subdir: subdirName };
   } catch (e) {
     step('✗', 'AI 配置', e.message, { iconColor: 'red', labelColor: 'red', valueColor: 'red' });
@@ -1733,13 +1622,16 @@ async function setupUserLevelComponents(targetAdapters = adapters) {
 }
 
 /**
- * cbb update：按现有安装模式升级当前目录内容 + 用户级组件。
+ * cbb update：就地升级当前目录内容 + 用户级组件。
  *
- * 安装模式判定：清单含 rules 路径 → 完整模式（worktree 沙箱/单项目），
- * 否则为 workspace 子集模式（空间根，只装 worktree 管理 + openspec 配置）。
+ * 单层安装：统一安装器按空间根判定（workspace-config.json + .git 目录）补齐
+ * worktree 管理入口与空间导航；旧子集清单升级时由清单差集机制自动补齐全量内容。
  */
 async function updateInstalled() {
-  await setupUserLevelComponents();
+  // 用户级组件沿用本目录的工具选择（.last-tools），无记录或为空才回退全量
+  const lastTools = readLastTools();
+  const reused = lastTools ? adapters.filter(a => lastTools.has(a.name)) : [];
+  await setupUserLevelComponents(reused.length > 0 ? reused : adapters);
 
   const manifest = readManifest();
   if (manifest.size === 0) {
@@ -1747,17 +1639,7 @@ async function updateInstalled() {
     process.exit(1);
   }
 
-  const isFullInstall = [...manifest].some(p =>
-    adapters.some(a => p.startsWith(`${a.rulesDir}/`))
-  );
-
-  if (isFullInstall) {
-    log('检测到完整模式安装，升级开发配置（rules + skills + commands + 工作流）...', 'info');
-    await init(undefined, {});
-  } else {
-    log('检测到 workspace 子集模式，升级 worktree 管理 + openspec 配置...', 'info');
-    await installWorkspaceConfig(undefined, {});
-  }
+  await init(undefined, {});
 }
 
 // ── 卸载 ──────────────────────────────────────────────────
@@ -1957,7 +1839,7 @@ async function uninstall() {
 
 // 入口身份：cbb（用户命令） / cbbm（内部命令，由流程、hook、Agent 技能调用）
 const ENTRY = process.env.CBB_ENTRY === 'cbbm' ? 'cbbm' : 'cbb';
-const INTERNAL_COMMANDS = ['init', 'check-update', 'wiki', 'wp'];
+const INTERNAL_COMMANDS = ['check-update', 'wiki', 'wp'];
 const UPSTREAM_FLAGS = ['--upstream-superpowers', '--upstream-openspec'];
 
 const args = process.argv.slice(2);
@@ -2045,14 +1927,6 @@ switch (command) {
     }
     break;
   }
-  case 'init': {
-    const yes = restArgs.includes('-y') || restArgs.includes('--yes');
-    init(undefined, { yes }).catch(err => {
-      log(err.message, 'error');
-      process.exit(1);
-    });
-    break;
-  }
   case 'uninstall':
     uninstall().catch(err => {
       log(err.message, 'error');
@@ -2092,7 +1966,6 @@ function showHelp() {
     console.log(`
 @jspg-ai/coding-bb v${pkg.version} — cbbm：内部命令（由流程 / hook / Agent 技能调用）
 
-  cbbm init --yes            worktree 沙箱内安装开发配置（/cbb:worktree-init Step 4 自动调用）
   cbbm check-update          版本检查（用户级 hook 每日自动触发）
   cbbm wiki / cbbm wp        Wiki 查询与发布（AI 通过技能调用）
 

package/cbb/lib/install/workspaces.js

@@ -186,6 +186,29 @@ function ensureWorkspaceAgentsMd(targetDir) {
   return 'created';
 }
 
+// 旧版空间导航模板（0.0.3 单层安装改造前）的特征语句。
+// 该文件归用户所有、永不覆盖，故只能提示用户删除后重跑 cbb update 重新生成。
+const LEGACY_AGENTS_MD_MARKERS = [
+  '故意不含编码规范',
+  '自动安装沙箱内的编码规范',
+];
+
+/**
+ * 检测空间根 AGENTS.md 是否仍为旧版导航文案（命中任一特征语句即为旧版）。
+ * 仅用于安装时打印提示，不修改文件。
+ * @returns {boolean}
+ */
+function detectLegacyAgentsMd(targetDir) {
+  const agentsPath = path.join(targetDir, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) return false;
+  try {
+    const content = fs.readFileSync(agentsPath, 'utf-8');
+    return LEGACY_AGENTS_MD_MARKERS.some(m => content.includes(m));
+  } catch (_) {
+    return false;
+  }
+}
+
 /**
  * 在指定目录执行 `git remote -v`，解析出 [{ name, url }] 列表。
  * 任何异常静默返回空数组，便于上层用 state 机判定。
@@ -285,6 +308,7 @@ module.exports = {
   loadWorkspaces,
   validateWorkspaceConfig,
   ensureWorkspaceAgentsMd,
+  detectLegacyAgentsMd,
   readGitRemotes,
   detectRepo,
   extractRepoBasename,

package/cbb/lib/utils/check-update.js

@@ -17,7 +17,7 @@ const path = require('path');
 const versionUtil = require('./version');
 
 // 缓存提升到用户级：registry 最新版本号是全局属性（npm 全局包只有一个版本），
-// 团队多 workspace / 多 worktree 沙箱共享一份，每日真实请求一次；
+// 团队多 workspace / 多 worktree 共享一份，每日真实请求一次；
 // 「本项目是否落后」仍按项目清单版本在本地判定。
 const CACHE_FILE = path.join(os.homedir(), '.cbb', '.update-check-cache.json');
 const CACHE_TTL = 24 * 60 * 60 * 1000;

package/cbb/worktrees/commands/worktree-close.md

@@ -9,7 +9,7 @@ tags: [worktree, cleanup, worktree, git-worktree]
 
 ## 重要：第一步必须用 Read 工具直接打开 SKILL.md
 
-**禁止**用 `ls` / `find` / `cat` / `head` / `grep` 等 bash 命令搜索 SKILL.md。这些命令在 Qoder Windows PowerShell 沙箱中经常失败。
+**禁止**用 `ls` / `find` / `cat` / `head` / `grep` 等 bash 命令搜索 SKILL.md。这些命令在 Agent 运行环境（Qoder Windows PowerShell 等）中经常失败。
 
 **直接路径**：
 - Qoder 适配器：`.qoder/skills/cbb-worktree-close/SKILL.md`

package/cbb/worktrees/commands/worktree-init.md

@@ -9,7 +9,7 @@ tags: [worktree, isolation, worktree, git-worktree]
 
 ## 重要：第一步必须用 Read 工具直接打开 SKILL.md
 
-**禁止**用 `ls` / `find` / `cat` / `head` / `grep` 等 bash 命令搜索 SKILL.md 是否存在。**这些命令在 Qoder Windows PowerShell 沙箱中经常失败**（如 `head` 不存在、stderr 重定向无效等）。
+**禁止**用 `ls` / `find` / `cat` / `head` / `grep` 等 bash 命令搜索 SKILL.md 是否存在。**这些命令在 Agent 运行环境（Qoder Windows PowerShell 等）中经常失败**（如 `head` 不存在、stderr 重定向无效等）。
 
 **直接路径**：
 - Qoder 适配器：`.qoder/skills/cbb-worktree-init/SKILL.md`
@@ -17,7 +17,7 @@ tags: [worktree, isolation, worktree, git-worktree]
 
 **第一步**：
 1. 用 Read 工具直接打开 `.qoder/skills/cbb-worktree-init/SKILL.md`（或 `.claude/skills/...`）
-2. 按 SKILL.md 的 Step 0 → 1 → 2 → 3 → 4 → 5 → 6 顺序执行
+2. 按 SKILL.md 的 Step 0 → 1 → 2 → 3 → 4 顺序执行
 3. 每次调用 Node.js 脚本时，使用**绝对路径**（避免依赖相对路径）：
    ```
    node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\<name>.js" <参数>
@@ -29,9 +29,7 @@ tags: [worktree, isolation, worktree, git-worktree]
      - `check-repos.js`：`<ws_root>`
      - `create-branches.js`：`<ws_root> <branch>`
      - `update-gitignore.js`：`<ws_root> <branch>`
-     - `create-worktrees.js`：`<ws_root> <branch>`
-     - `install-ai.js`：`<wt_path>`
-     - `auto-open.js`：`<wt_path>`
+      - `create-worktrees.js`：`<ws_root> <branch>`
 
 ## Input
 
@@ -42,14 +40,12 @@ tags: [worktree, isolation, worktree, git-worktree]
 1. Step 0：环境探活 + 解析 workspace-config.json
 2. Step 1：同步 .codespace/ 仓库（fetch --all）
 3. Step 2：状态检查（5 项 / 3 项分级）
-4. Step 3：创建分支（workspace 从 HEAD，app 从 origin/master）
-5. Step 4：创建 worktree（workspace + 嵌套 app）
-6. Step 5：在 worktree 中安装 AI 配置（cbbm init -y）
-7. Step 6：环境感知 + 进入工作目录
+4. Step 3：创建分支 → 推送 upstream → 创建 worktree（workspace + 嵌套 app）
+5. Step 4：收尾与交接（继续当前会话，声明目录纪律）
 
 ## 关键 Guardrails
 
 - workspace 主分支 tracked 的所有内容（openspec/、cbb/ 等）由 git worktree 自动 checkout——**禁止 cp / clone / symlink “带过来”**
 - 必须用 `git branch` 而非 `git checkout -b`（分支不能同时在主目录与 worktree 检出）
-- 沙箱内 node 不可用时 fail-fast：终止流程并提示用户到系统终端重试
+- 运行环境 node 不可用时 fail-fast：终止流程并提示用户到系统终端重试
 - **不要试图搜索 SKILL.md**——直接用 Read 工具打开

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

@@ -414,7 +414,7 @@ git -C "<ws_root>" worktree list
 - 删除工作空间根目录的 AI 配置目录（`.claude/`、`.qoder/`、`.cbb/` 等源目录）
 - 用 `AskUserQuestion` 收集自由文本（分支名等直接对话提问）
 - 手动改任何仓库的 `.gitignore`（关闭流程不碰它）
-- 沙箱内 node 不可用时强行继续 → 改为 fail-fast 提示用户
+- 运行环境 node 不可用时强行继续 → 改为 fail-fast 提示用户
 
 ### 必须执行
 

package/cbb/worktrees/skills/cbb-worktree-close/scripts/check-env.js

@@ -34,7 +34,7 @@ const checks = {};
 // ── 必检：git ─────────────────────────────────────────
 checks.git = tryExec('git --version');
 if (!checks.git.ok) {
-  console.error('❌ git 启动失败（可能是 Qoder 沙箱 DLL 问题 0xc0000142）');
+  console.error('❌ git 启动失败（可能是 Agent 运行环境 DLL 问题 0xc0000142）');
   console.error('   解决方案：到系统终端重新执行本技能');
   process.exit(1);
 }
@@ -57,12 +57,12 @@ if (!checks.node.ok) {
   console.log('✅ node OK:', checks.node.out);
 }
 
-// ── 沙箱检测 ─────────────────────────────────────────
+// ── 运行环境检测 ─────────────────────────────────────────
 const inWorktree = !!(process.env.QODER_AGENT || process.env.QODER_WORKTREE);
 if (inWorktree) {
-  console.log('🛡️  Qoder 沙箱环境：移除 worktree 时如遇 IDE 锁，将降级处理');
+  console.log('🛡️  Qoder Agent 运行环境：移除 worktree 时如遇 IDE 锁，将降级处理');
 } else {
-  console.log('✅ 非沙箱环境');
+  console.log('✅ 系统终端环境');
 }
 
 const summary = {