@jspg-ai/coding-bb 0.0.3-beta.23 → 0.0.3-beta.24

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

@@ -111,7 +111,7 @@ trigger: always_on
 
 **模式二 · worktree 模式（并行 / 隔离）：**
 
-- `cbb-worktree-init` 建隔离 worktree（AI 配置内容子目录已 junction 就位），**开发会话开进 `.worktrees/worktree-<需求名>/`**，可多需求并行
+- `cbb-worktree-init` 建隔离 worktree（AI 配置内容子目录已 junction 就位），**开发会话开进 `.worktrees/worktree-<需求名>/`**，可多需求并行；app 检出收拢在 `<wt>/.codespace/<app>/`——**镜像空间根布局**（`.codespace/<app>/...` 相对路径两模式通用，ADR 0003）
 - 根会话保留作控制面（worktree 生灭、`cbb update` 等空间级操作）
 
 **基准与防线（两模式共同，ADR 0002）：**

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

@@ -66,7 +66,7 @@ node "<skill_dir>/scripts/start-local.js" "<ws_root>" "<branch>" --apps "<app1>,
 
 ## Step 3：开发（会话 cwd == 开发目录）
 
-- 当前会话**原地**开发：workspace 内容用根相对路径，应用代码用 `.codespace/<app>/...` 相对路径——上游 `/opsx:propose → apply → verify` 的相对路径指令**原样生效**，零翻译
+- 当前会话**原地**开发：workspace 内容用根相对路径，应用代码用 `.codespace/<app>/...` 相对路径——上游 `/opsx:propose → apply → verify` 的相对路径指令**原样生效**，零翻译（worktree 模式自 ADR 0003 起同布局，两模式路径通用）
 - 需求产物落 `openspec/changes/<需求名>/`（在分支上，hook 已保证不会误进 main）
 - **读基准代码约定**：本地模式进行中工作区是开发态——要读"main 上是什么"先看 `git -C .codespace/<app> branch --show-current`，或直接 `git show main:<path>`，不要默认工作区即基准
 - **中途插单**：用户插入非本需求的改动 → 先确认归属（并入当前需求 / 收尾后处理 / 转 worktree），不得静默混入

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

@@ -13,9 +13,9 @@ description: "关闭/清理/删除需求工作空间的 worktree 和分支。触
 
 - 本技能的所有原子操作封装为 `scripts/*.js` Node.js 脚本，**跨平台执行**
 - 本技能是 `cbb-worktree-init` 的逆操作：共用 `workspace-config.json`、共用 `.worktrees/worktree-<需求名>/` 物理直聚命名、共用统一的分支名（不加前缀）
-- App worktree **物理嵌套**在 workspace worktree 内（`.worktrees/worktree-<需求名>/<应用名>/`），但 git 上属于各自仓库的独立 worktree
+- App worktree **物理嵌套**在 workspace worktree 的 `.codespace/` 容器内（`.worktrees/worktree-<需求名>/.codespace/<应用名>/`，镜像空间根布局，ADR 0003），但 git 上属于各自仓库的独立 worktree
 - 只操作 `.worktrees/worktree-<需求名>` 这一类精确路径，**绝不碰其它 worktree**（如 IDE/工具自动创建的 `~/.qoder/worktree/...` 会话 worktree）
-- 通过检查 `.worktrees/worktree-<需求名>/<应用名>/` **是否实际存在**来确定关联应用——创建时用户可能只关联了 `workspace-config.json` 中的部分应用，不能假设全部应用都关联
+- 通过检查 `.worktrees/worktree-<需求名>/.codespace/<应用名>/` **是否实际存在**来确定关联应用——创建时用户可能只关联了 `workspace-config.json` 中的部分应用，不能假设全部应用都关联
 - **顺序硬约束：先移除所有 worktree，再删除分支。** 目标分支当前正检出于 worktree 中，先删分支会报 `error: Cannot delete branch '<分支>' checked out at '<worktree 路径>'`
 - **破坏性操作必须先报告、经用户确认才执行**：未提交修改、未合并/未推送的提交，绝不静默 `--force` 或 `-D` 丢弃
 - 软性检查失败时报告详情，询问用户是否继续
@@ -97,13 +97,13 @@ node "<skill_dir>/scripts/find-target-worktree.js "<ws_root>"
 node "<skill_dir>/scripts/discover-apps.js "<ws_root>" "<branch>"
 ```
 
-脚本自动从 `workspace-config.json` 读取应用列表，扫描 `.worktrees/worktree-<branch>/<应用名>/` 实际存在的子目录。
+脚本自动从 `workspace-config.json` 读取应用列表，扫描 `.worktrees/worktree-<branch>/.codespace/<应用名>/`（兼容 ≤beta.23 旧平铺 `<应用名>/`）实际存在的子目录。
 
 **解读末行 `DISCOVER_RESULT`**：
 - `workspace` 字段：workspace worktree 绝对路径（AI agent 记录供后续命令使用）
 - `apps` 数组：实际存在的应用 worktree 列表（每项含 `name`, `repo`, `side`, `wt_path`, `app_path`）
 
-> 说明：app worktree 物理嵌套在 workspace worktree 内，移除 workspace worktree 时嵌套的子目录会一并消失，但各 app 仓库的 git worktree 元数据（`.git/worktrees/`）仍需通过 `git worktree remove` 逐个清理。AI 配置只装在业务空间根（单层安装），worktree 内没有 AI 配置目录，无需特殊处理。
+> 说明：app worktree 物理嵌套在 workspace worktree 的 `.codespace/` 容器内，移除 workspace worktree 时嵌套的子目录会一并消失，但各 app 仓库的 git worktree 元数据（`.git/worktrees/`）仍需通过 `git worktree remove` 逐个清理。AI 配置经 junction 链入 worktree（只读内容子目录指向空间根唯一物理副本），随 worktree 目录一并消失，无需特殊处理。
 
 ### 1.3 检查未归档 change
 
@@ -393,8 +393,8 @@ git -C "<ws_root>" worktree list
   当前目录：<工作空间根目录绝对路径>
   已移除 worktree：
     - .worktrees/worktree-feature-xxx（workspace）
-    - .worktrees/worktree-feature-xxx/ep-user-info-server（嵌套，ep-user-info-server 仓库）
-    - .worktrees/worktree-feature-xxx/ep-user-management-app（嵌套，ep-user-management-app 仓库）
+    - .worktrees/worktree-feature-xxx/.codespace/ep-user-info-server（嵌套，ep-user-info-server 仓库）
+    - .worktrees/worktree-feature-xxx/.codespace/ep-user-management-app（嵌套，ep-user-management-app 仓库）
   未提交修改：已丢弃（--force）/ 无
   未归档 change 处理：
     ✅ ai-call-send-im-msg → 已归档到 archive/2026-07-08-ai-call-send-im-msg
@@ -430,7 +430,7 @@ git -C "<ws_root>" worktree list
 
 ### 必须执行
 
-- 读 `workspace-config.json` 取应用名列表；以 `.worktrees/worktree-<需求名>/<应用名>/` 实际存在性确定关联清单
+- 读 `workspace-config.json` 取应用名列表；以 `.worktrees/worktree-<需求名>/.codespace/<应用名>/` 实际存在性确定关联清单
 - 移除/删除前执行安全评估（未提交修改 / 是否合并 / 是否推远程）并报告
 - 严格按 Step 4.2（移除 worktree）→ Step 4.4（删分支）顺序
 - 移除 workspace worktree 前先把会话移出（`cd "<WS_ROOT>" &&` 或 `git -C` 绝对路径）

package/cbb/worktrees/skills/cbb-worktree-close/scripts/discover-apps.js

@@ -50,9 +50,18 @@ if (!fs.existsSync(wtDir)) {
   process.exit(2);
 }
 
+/** 解析 app worktree 物理路径：新布局 .codespace/<app> 优先，兼容 ≤beta.23 旧平铺 <app> */
+function resolveAppWt(appName) {
+  const nested = path.join(wtDir, '.codespace', appName);
+  if (fs.existsSync(path.join(nested, '.git'))) return nested;
+  const legacy = path.join(wtDir, appName);
+  if (fs.existsSync(path.join(legacy, '.git'))) return legacy;
+  return nested;
+}
+
 const found = [];
 for (const app of apps) {
-  const appWt = path.join(wtDir, app.name);
+  const appWt = resolveAppWt(app.name);
   if (fs.existsSync(appWt) && fs.existsSync(path.join(appWt, '.git'))) {
     console.log('✅ ' + app.name + '：存在嵌套 worktree（' + appWt + '）');
     found.push({

package/cbb/worktrees/skills/cbb-worktree-close/scripts/remove-worktrees.js

@@ -88,9 +88,18 @@ let config = {};
 try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (e) {}
 
 const apps = config.apps || [];
+/** 解析 app worktree 物理路径：新布局 .codespace/<app> 优先，兼容 ≤beta.23 旧平铺 <app> */
+function resolveAppWt(appName) {
+  const nested = path.join(wtDir, '.codespace', appName);
+  if (fs.existsSync(path.join(nested, '.git'))) return nested;
+  const legacy = path.join(wtDir, appName);
+  if (fs.existsSync(path.join(legacy, '.git'))) return legacy;
+  return nested;
+}
+
 console.log('=== 移除应用 Worktrees ===');
 for (const app of apps) {
-  const appWt = path.join(wtDir, app.name);
+  const appWt = resolveAppWt(app.name);
   const appPath = path.join(wsRoot, '.codespace', app.name);
   removeWt(appPath, appWt, app.name);
 }

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

@@ -159,12 +159,21 @@ try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (e) {}
 const apps = config.apps || [];
 const wtDir = path.join(wsRoot, '.worktrees', 'worktree-' + branch);
 
+/** 解析 app worktree 物理路径：新布局 .codespace/<app> 优先，兼容 ≤beta.23 旧平铺 <app> */
+function resolveAppWt(appName) {
+  const nested = path.join(wtDir, '.codespace', appName);
+  if (fs.existsSync(path.join(nested, '.git'))) return nested;
+  const legacy = path.join(wtDir, appName);
+  if (fs.existsSync(path.join(legacy, '.git'))) return legacy;
+  return nested;
+}
+
 const results = [];
 
 results.push(checkRepo('workspace', wsRoot, wtDir));
 
 for (const app of apps) {
-  const appWt = path.join(wtDir, app.name);
+  const appWt = resolveAppWt(app.name);
   const appPath = path.join(wsRoot, '.codespace', app.name);
   results.push(checkRepo(app.name, appPath, appWt));
 }

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

@@ -12,7 +12,7 @@ description: "为一个需求在 workspace 与各关联应用仓库同步创建
 ## 核心原则
 
 - 本技能的所有原子操作封装为 `scripts/*.js` Node.js 脚本，**跨平台执行**（Windows PowerShell / macOS bash / Linux bash / Git Bash 均无需适配）
-- 物理位置与 `init-worktree` 兼容：`.worktrees/worktree-<需求名>/<应用名>/`
+- 物理位置（ADR 0003）：workspace worktree 在 `.worktrees/worktree-<需求名>/`，各 app worktree 收拢在其 `.codespace/<应用名>/` 容器内——**镜像空间根布局**（应用检出恒在 `.codespace/<app>/`，相对路径两模式通用）
 - 所有仓库使用统一的分支名（不加前缀）；worktree 目录名自动加 `worktree-` 前缀；**分支基线统一取 `origin/<main>`（ADR 0002，不取 HEAD）**
 - **lazy push（ADR 0002）**：本技能**不向远端推送任何分支**——远端副作用收敛到 `cbb-worktree-push` 唯一出口；推送失败早暴露的职责由 push 技能的 dry-run 承担
 - **AI 配置 junction（ADR 0002 防线 B）**：创建 worktree 后把根的 AI 配置**内容子目录**（rules / skills / commands）junction 进工作树——开发会话开在 `<wt_path>`（上游 `/opsx:*` 相对路径原样生效，零翻译）；工具状态落在工作树自建空壳目录，不互相污染；`cbb update` 在根跑一次全 worktree 生效
@@ -280,7 +280,7 @@ node "<skill_dir>/scripts/create-worktrees.js" "<ws_root>" "<branch>" [--apps "a
 脚本内部自动完成：
 1. **元数据自愈**：仅 `git worktree prune`（清理"目录已缺失/失效"的注册项）；**绝不删除任何物理目录**（0.0.3-beta.11 起——旧版"清理无元数据残留目录"因 Windows 路径分隔符不匹配会误删活跃 worktree，已整体移除）
 2. **workspace worktree 创建**：`git worktree add .worktrees/worktree-<branch> <branch>`
-3. **app worktree 创建**（物理嵌套在 workspace worktree 内）
+3. **app worktree 创建**（收拢在 workspace worktree 的 `.codespace/` 容器内，镜像空间根布局）；≤beta.23 旧平铺布局自动 `git worktree move` 迁移
 
 **解读输出**：
 - 退出码 0 + 末行 `WT_PATH <绝对路径>` → 全部成功，AI 解析出 worktree 绝对路径供后续 Step 4 使用
@@ -333,7 +333,7 @@ node "<skill_dir>/scripts/junction-ai-config.js" "<ws_root>" "<wt_path>"
 
 ```
 ✅ worktree 已创建：<wt_path>
-   关联应用：<应用名 → 嵌套路径> 列表（应用子集或全量）
+   关联应用：<应用名 → .codespace/<应用名> 路径> 列表（应用子集或全量）
 🔗 AI 配置已 junction 就位：rules / skills / commands（cbb update 一处生效）
 📌 开发会话请开在 <wt_path>（新开 IDE 窗口 / agent 会话）；本根会话保留作控制面
 👉 下一步建议：
@@ -354,7 +354,7 @@ node "<skill_dir>/scripts/junction-ai-config.js" "<ws_root>" "<wt_path>"
 
 | 场景 | 重跑行为 |
 |------|----------|
-| 空间新增了应用（编辑 `workspace-config.json` 后） | Step 1 拉取新应用代码 → Step 3.3 为新应用建分支 → Step 3.5 创建缺失的嵌套 worktree → Step 3.6 补 junction |
+| 空间新增了应用（编辑 `workspace-config.json` 后） | Step 1 拉取新应用代码 → Step 3.3 为新应用建分支 → Step 3.5 在 `.codespace/` 容器内创建缺失的 app worktree → Step 3.6 补 junction |
 | 上次 init 中途失败 | 已存在的分支 / worktree 自动复用，`.gitignore` 处理自动跳过，仅补齐缺失部分 |
 | 应用从 config 移除 | 已创建的分支 / worktree **不会**自动删除；如需清理用 `cbb-worktree-close` skill 关闭后重建 |
 | **本地模式升级 worktree**（ADR 0002） | Step 3.3 分支已存在 → reused（本地阶段提交随身带走）；先 `git checkout main` 腾出各仓库本地检出，再重跑本技能 |

package/cbb/worktrees/skills/cbb-worktree-init/scripts/create-worktrees.js

@@ -109,12 +109,13 @@ if (fs.existsSync(wtDir)) {
   console.log('✅ workspace worktree 已创建：' + wtDir);
 }
 
-// 3. apps worktree 创建（物理嵌套）
+// 3. apps worktree 创建（物理嵌套于 workspace worktree 的 .codespace/ 容器内，镜像主布局，ADR 0003）
 console.log('=== 创建 App Worktrees ===');
 const results = [];
 for (const app of apps) {
   const appPath = path.join(wsRoot, '.codespace', app.name);
-  const nestedWt = path.join(wtDir, app.name);
+  const nestedWt = path.join(wtDir, '.codespace', app.name);
+  const legacyWt = path.join(wtDir, app.name);
 
   if (fs.existsSync(nestedWt) && fs.existsSync(path.join(nestedWt, '.git'))) {
     console.log('⏭️  ' + app.name + ': 嵌套 worktree 已存在，复用');
@@ -122,8 +123,23 @@ for (const app of apps) {
     continue;
   }
 
-  // 防御性兜底：父目录不存在则创建
+  // 防御性兜底：容器目录不存在则创建
   fs.mkdirSync(path.dirname(nestedWt), { recursive: true });
+
+  // 存量迁移：≤beta.23 旧平铺布局 → .codespace/ 容器（worktree 平移，分支与提交随身带走）
+  if (fs.existsSync(legacyWt) && fs.existsSync(path.join(legacyWt, '.git'))) {
+    const moved = run('git worktree move "' + legacyWt + '" "' + nestedWt + '"', appPath);
+    if (moved.ok) {
+      console.log('🔁 ' + app.name + ': 旧平铺 worktree 已迁移到 .codespace/ 容器');
+      results.push({ name: app.name, status: 'migrated' });
+      continue;
+    }
+    console.error('❌ ' + app.name + ': 旧平铺 worktree 迁移失败（常见原因：目录被 IDE 等进程占用）：' + moved.err);
+    console.error('   请关闭占用 ' + legacyWt + ' 的程序后重跑本技能；或先执行 cbb-worktree-close 再重建');
+    results.push({ name: app.name, status: 'failed', error: moved.err });
+    continue;
+  }
+
   const created = run('git worktree add "' + nestedWt + '" "' + branch + '"', appPath);
   if (created.ok) {
     console.log('✅ ' + app.name + ': 嵌套 worktree 创建成功');

package/cbb/worktrees/skills/cbb-worktree-push/scripts/commit-worktrees.js

@@ -8,7 +8,7 @@ require('./silence-popup');
  *
  * 行为：
  *   1. 按需求名发现参与仓库（ADR 0002 双布局）：
- *      - worktree 布局：.worktrees/worktree-<branch>/ 下所有 git 仓库
+ *      - worktree 布局：.worktrees/worktree-<branch>/ 的 workspace + 其 .codespace/<app>/ 容器内各 app worktree（镜像主布局，ADR 0003）
  *      - 本地布局：根 / .codespace/<app>/ 检出恰在 <branch> 分支上
  *   2. 对每个仓库：
  *      a. git status --porcelain 检测 dirty
@@ -97,6 +97,16 @@ function isGitRepo(p) {
   return fs.existsSync(path.join(p, '.git'));
 }
 
+/** 读取 workspace-config.json 的 app 名列表（旧布局兼容判定用；缺失返回 []） */
+function loadAppNames(wsRoot) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(wsRoot, 'workspace-config.json'), 'utf-8'));
+    return Array.isArray(cfg.apps) ? cfg.apps.map(a => a.name).filter(Boolean) : [];
+  } catch (e) {
+    return [];
+  }
+}
+
 function currentBranch(p) {
   try {
     return execSync('git branch --show-current', { cwd: p, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
@@ -105,7 +115,7 @@ function currentBranch(p) {
 
 /**
  * 按需求名发现参与仓库（ADR 0002 双布局）：
- *   布局一 worktree：.worktrees/worktree-<branch>/ 下 workspace + 嵌套 app worktree
+ *   布局一 worktree：.worktrees/worktree-<branch>/ 的 workspace + 其 .codespace/<app>/ 容器内 app worktree（ADR 0003 镜像主布局；≤beta.23 旧平铺顶层布局按配置 app 名兼容）
  *   布局二 本地模式：根 / .codespace/<app>/ 的检出恰在 <branch> 分支上（同名仓库以 worktree 布局优先）
  * 两者皆空 → error。
  */
@@ -118,12 +128,24 @@ function scanWorktreeRepos(wsRoot, branch) {
     if (isGitRepo(wtRoot)) {
       repos.push({ name: 'workspace', wt: wtRoot, repo: wsRoot, layout: 'worktree' });
     }
-    const entries = fs.readdirSync(wtRoot, { withFileTypes: true });
-    for (const e of entries) {
-      if (!e.isDirectory() || e.name.startsWith('.')) continue;
-      const appWt = path.join(wtRoot, e.name);
-      if (!isGitRepo(appWt)) continue;
-      repos.push({ name: e.name, wt: appWt, repo: path.join(wsRoot, '.codespace', e.name), layout: 'worktree' });
+    // app worktree 收拢在 .codespace/ 容器内（镜像主布局，ADR 0003）
+    const appContainer = path.join(wtRoot, '.codespace');
+    if (fs.existsSync(appContainer)) {
+      for (const e of fs.readdirSync(appContainer, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        const appWt = path.join(appContainer, e.name);
+        if (!isGitRepo(appWt)) continue;
+        repos.push({ name: e.name, wt: appWt, repo: path.join(wsRoot, '.codespace', e.name), layout: 'worktree' });
+      }
+    }
+    // 兼容 ≤beta.23 旧平铺布局：按配置 app 名精确匹配（避免把根仓库自带的嵌套 git 目录误判为 app）
+    for (const name of loadAppNames(wsRoot)) {
+      if (repos.some(r => r.name === name)) continue;
+      const legacyWt = path.join(wtRoot, name);
+      if (fs.existsSync(path.join(legacyWt, '.git'))) {
+        console.error('⚠️  ' + name + ' 仍是旧平铺布局（' + legacyWt + '），建议重跑 cbb-worktree-init 迁移到 .codespace/ 容器');
+        repos.push({ name, wt: legacyWt, repo: path.join(wsRoot, '.codespace', name), layout: 'worktree' });
+      }
     }
   }
 

package/cbb/worktrees/skills/cbb-worktree-push/scripts/push-worktrees.js

@@ -8,7 +8,7 @@ require('./silence-popup');
  *
  * 行为：
  *   1. 按需求名发现参与仓库（ADR 0002 双布局）：
- *      - worktree 布局：.worktrees/worktree-<branch>/ 下所有 git 仓库（workspace + 各 app 子 worktree）
+ *      - worktree 布局：.worktrees/worktree-<branch>/ 的 workspace + 其 .codespace/<app>/ 容器内各 app worktree（镜像主布局，ADR 0003）
  *      - 本地布局：根 / .codespace/<app>/ 检出恰在 <branch> 分支上
  *   2. 对每个仓库调 push-core.pushSingle（已建立 upstream 时直接 push -u；否则建立 upstream）
  *   3. 逐个报告状态，输出末行 PUSH_RESULT
@@ -59,6 +59,16 @@ function isGitRepo(p) {
   }
 }
 
+/** 读取 workspace-config.json 的 app 名列表（旧布局兼容判定用；缺失返回 []） */
+function loadAppNames(wsRoot) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(wsRoot, 'workspace-config.json'), 'utf-8'));
+    return Array.isArray(cfg.apps) ? cfg.apps.map(a => a.name).filter(Boolean) : [];
+  } catch (e) {
+    return [];
+  }
+}
+
 function currentBranch(p) {
   try {
     return execSync('git branch --show-current', { cwd: p, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
@@ -67,7 +77,7 @@ function currentBranch(p) {
 
 /**
  * 按需求名发现参与仓库（ADR 0002 双布局）：
- *   布局一 worktree：.worktrees/worktree-<branch>/ 下 workspace + 嵌套 app worktree
+ *   布局一 worktree：.worktrees/worktree-<branch>/ 的 workspace + 其 .codespace/<app>/ 容器内 app worktree（ADR 0003 镜像主布局；≤beta.23 旧平铺顶层布局按配置 app 名兼容）
  *   布局二 本地模式：根 / .codespace/<app>/ 的检出恰在 <branch> 分支上（同名仓库以 worktree 布局优先）
  * 两者皆空 → error。
  */
@@ -80,12 +90,24 @@ function scanWorktreeRepos(wsRoot, branch) {
     if (isGitRepo(wtRoot)) {
       repos.push({ name: 'workspace', wt: wtRoot, repo: wsRoot, layout: 'worktree' });
     }
-    const entries = fs.readdirSync(wtRoot, { withFileTypes: true });
-    for (const e of entries) {
-      if (!e.isDirectory() || e.name.startsWith('.')) continue;
-      const appWt = path.join(wtRoot, e.name);
-      if (!isGitRepo(appWt)) continue;
-      repos.push({ name: e.name, wt: appWt, repo: path.join(wsRoot, '.codespace', e.name), layout: 'worktree' });
+    // app worktree 收拢在 .codespace/ 容器内（镜像主布局，ADR 0003）
+    const appContainer = path.join(wtRoot, '.codespace');
+    if (fs.existsSync(appContainer)) {
+      for (const e of fs.readdirSync(appContainer, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        const appWt = path.join(appContainer, e.name);
+        if (!isGitRepo(appWt)) continue;
+        repos.push({ name: e.name, wt: appWt, repo: path.join(wsRoot, '.codespace', e.name), layout: 'worktree' });
+      }
+    }
+    // 兼容 ≤beta.23 旧平铺布局：按配置 app 名精确匹配（避免把根仓库自带的嵌套 git 目录误判为 app）
+    for (const name of loadAppNames(wsRoot)) {
+      if (repos.some(r => r.name === name)) continue;
+      const legacyWt = path.join(wtRoot, name);
+      if (fs.existsSync(path.join(legacyWt, '.git'))) {
+        console.error('⚠️  ' + name + ' 仍是旧平铺布局（' + legacyWt + '），建议重跑 cbb-worktree-init 迁移到 .codespace/ 容器');
+        repos.push({ name, wt: legacyWt, repo: path.join(wsRoot, '.codespace', name), layout: 'worktree' });
+      }
     }
   }
 

package/config/workspace-agents.sample.md

@@ -19,7 +19,7 @@
 |------|----------|----------|
 | `workspace-config.json` | 关联应用清单，所有应用联动的唯一数据源 | 人工编辑（控制面白名单，可直接提交 main） |
 | `.codespace/` | 各应用的**标准本地检出**（基准 = `origin/main`） | `cbb setup` 与技能自动 clone / fetch；本地模式可在其中**切需求分支开发**（main 检出禁改）；已 gitignore，不提交 |
-| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/`，内含 AI 配置 junction） | worktree 技能自动创建 / 清理；已 gitignore，不提交 |
+| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/`，内含 AI 配置 junction 与 `.codespace/<app>/` 应用检出，**镜像本空间布局**） | worktree 技能自动创建 / 清理；已 gitignore，不提交 |
 | `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | `config.yaml`/`schemas/` 为控制面白名单（`cbb update` 部署，可直改）；变更产物（`openspec/changes/`）落需求分支随 MR 合入 |
 | `.claude/` `.qoder/` `.opencode/` `.workbuddy/` `.trae/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、技能 | 由 cbb 按 setup 时选择的工具安装（**唯一物理副本在此**）；worktree 内经 junction 引用同一份；已 gitignore，不提交，勿手动改 |
 | `.cbb/` | cbb 安装清单与状态（`.managed-by-cbb`、`.last-tools`） | 由 cbb 管理；**勿手动编辑** |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jspg-ai/coding-bb",
-  "version": "0.0.3-beta.23",
+  "version": "0.0.3-beta.24",
   "description": "整合业界热门且高价值的工具、框架与技能，为 AI CODING AGENT 提供统一的行为准则与工作流，辅助开发者将需求高效落地为符合规范的代码",
   "main": "cbb/lib/install/init.js",
   "bin": {