@jspg-ai/coding-bb 0.0.3-beta.2 → 0.0.3-beta.4

package/cbb/lib/install/init.js

@@ -68,8 +68,8 @@ const SUPERPOWERS_WHITELIST = [
   'test-driven-development',        // TDD 计划结构 + TDD Evidence 方法论基底
 ];
 
-// worktree 扩展 skills 部署白名单：init / close / push 三件套
-// （单层安装：业务空间根是唯一安装点，worktree 管理入口 init 同样部署在根）
+// worktree 运行时部署清单：init / close / push 三件套（SKILL.md + scripts），
+// 部署到 .cbb/skills/<name>/（每空间一份，不分工具；命令文件统一指向此处）
 const WORKTREE_SKILLS = ['cbb-worktree-init', 'cbb-worktree-close', 'cbb-worktree-push'];
 
 // 装到空间的 tools skills：当前不分发。
@@ -315,56 +315,117 @@ function deployCoreRules(adapter, isUpgrade, managedPaths) {
 // ── opencode instructions 登记 ────────────────────────────────
 
 /**
- * opencode 无原生 rules 目录：把 .opencode/rules/*.md 的 glob 登记进项目根
- * opencode.json 的 instructions（官方支持的加载方式）。
+ * opencode 无原生 rules 目录：把 rules glob 登记进 .opencode/opencode.json 的
+ * instructions（opencode V2 支持的配置位置；随 .opencode gitignore，按机器生成）。
+ * instructions 相对路径的解析基准（配置文件目录 vs 项目根）文档未写死，
+ * 故登记双 glob 对冲：任一基准下恰有一个命中，另一个空匹配。
  * - 文件不存在：创建（记入清单，卸载时整体删除）
- * - 文件存在：仅追加 pattern（幂等）；若清单显示该文件本由本包创建，则续登
- *   newPaths 防止升级清理误删；JSONC（含注释）解析失败则只提示不改写
+ * - 文件存在：幂等补齐缺失的 glob（保留用户已有 instructions）
+ * - JSONC（含注释）解析失败则只提示不改写
+ * 旧版登记在项目根 opencode.json，由 migrateLegacyInstructions 负责迁移清理。
  */
 function injectInstructions(adapter, newPaths, managedPaths) {
-  const cfgPath = path.join(TARGET_DIR, 'opencode.json');
-  const pattern = adapter.instructionsPattern;
+  const cfgPath = path.join(TARGET_DIR, adapter.instructionsFile);
+  const patterns = adapter.instructionsPatterns;
+  let cfg = {};
+  if (fs.existsSync(cfgPath)) {
+    try {
+      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    } catch (_) {
+      log(`${adapter.instructionsFile} 解析失败（可能含注释），未自动登记。请手动在 instructions 中加入 "${patterns.join('", "')}"`, 'warn');
+      return;
+    }
+    if (!cfg || typeof cfg !== 'object') cfg = {};
+  }
+  const list = Array.isArray(cfg.instructions) ? cfg.instructions : [];
+  const merged = [...list];
+  let added = false;
+  patterns.forEach(p => {
+    if (!merged.includes(p)) {
+      merged.push(p);
+      added = true;
+    }
+  });
   if (!fs.existsSync(cfgPath)) {
-    const cfg = { $schema: 'https://opencode.ai/config.json', instructions: [pattern] };
+    cfg.instructions = merged;
+    if (!cfg.$schema) cfg.$schema = 'https://opencode.ai/config.json';
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
     fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-    newPaths.add('opencode.json');
-    log(`生成 opencode.json 并登记 rules 加载（instructions: ${pattern}）`, 'success');
-    return;
+    newPaths.add(adapter.instructionsFile);
+    log(`生成 ${adapter.instructionsFile} 并登记 rules 加载（instructions: ${patterns.join(' | ')}）`, 'success');
+  } else if (added) {
+    cfg.instructions = merged;
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    log(`已在 ${adapter.instructionsFile} instructions 中登记 rules glob`, 'success');
   }
+  // 本包此前创建的文件：续登清单，避免升级清理误删
+  if (managedPaths.has(adapter.instructionsFile)) newPaths.add(adapter.instructionsFile);
+}
+
+/**
+ * 旧版（≤0.0.3-beta.2）把 rules glob 登记在项目根 opencode.json；迁移为
+ * .opencode/opencode.json 后需把旧 pattern 从根文件摘除（用户其余配置保留）。
+ * 根文件若由本包创建（在清单中），升级时由清单差集自动整体删除，此处只摘 pattern。
+ */
+function migrateLegacyInstructions(adapter) {
+  const legacyPattern = adapter.legacyInstructionsPattern;
+  if (!legacyPattern) return;
+  const cfgPath = path.join(TARGET_DIR, 'opencode.json');
+  if (!fs.existsSync(cfgPath)) return;
   let cfg;
   try {
     cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
   } catch (_) {
-    log(`opencode.json 解析失败（可能含注释），未自动登记。请手动在 instructions 中加入 "${pattern}"`, 'warn');
+    log('根 opencode.json 解析失败（可能含注释），未自动迁移旧登记。可手动移除 instructions 中的 "' + legacyPattern + '"', 'warn');
     return;
   }
-  const list = Array.isArray(cfg.instructions) ? cfg.instructions : [];
-  if (!list.includes(pattern)) {
-    cfg.instructions = [...list, pattern];
+  if (Array.isArray(cfg.instructions) && cfg.instructions.includes(legacyPattern)) {
+    cfg.instructions = cfg.instructions.filter(p => p !== legacyPattern);
+    if (cfg.instructions.length === 0) delete cfg.instructions;
     fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-    log(`已在 opencode.json instructions 中登记 ${pattern}`, 'success');
+    log('已从根 opencode.json 移除旧版 rules 登记（迁移至 .opencode/opencode.json）', 'success');
   }
-  // 本包此前创建的文件：续登清单，避免升级清理误删
-  if (managedPaths.has('opencode.json')) newPaths.add('opencode.json');
 }
 
-/** 卸载时移除本包登记的 instructions pattern（用户创建的 opencode.json 只删 pattern 不删文件） */
+/** 卸载时移除本包登记的 instructions（用户自建配置只摘本包 glob，不删文件） */
 function removeInstructionsRegistrations() {
   adapters.forEach(adapter => {
-    if (!adapter.instructionsPattern) return;
-    const cfgPath = path.join(TARGET_DIR, 'opencode.json');
-    if (!fs.existsSync(cfgPath)) return;
-    let cfg;
-    try {
-      cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
-    } catch (_) {
-      return; // 不可解析的文件不动
+    if (!adapter.instructionsFile) return;
+    const patterns = adapter.instructionsPatterns;
+    // 新位置：.opencode/opencode.json（cbb 创建的整体文件由清单删除兜底）
+    const cfgPath = path.join(TARGET_DIR, adapter.instructionsFile);
+    if (fs.existsSync(cfgPath)) {
+      let cfg;
+      try {
+        cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+      } catch (_) {
+        cfg = null; // 不可解析的文件不动
+      }
+      if (cfg && Array.isArray(cfg.instructions)) {
+        const filtered = cfg.instructions.filter(p => !patterns.includes(p));
+        if (filtered.length !== cfg.instructions.length) {
+          if (filtered.length === 0) delete cfg.instructions;
+          else cfg.instructions = filtered;
+          fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+          log(`${adapter.instructionsFile}: 移除本包登记的 instructions，保留用户配置`, 'success');
+        }
+      }
     }
-    if (Array.isArray(cfg.instructions) && cfg.instructions.includes(adapter.instructionsPattern)) {
-      cfg.instructions = cfg.instructions.filter(p => p !== adapter.instructionsPattern);
-      if (cfg.instructions.length === 0) delete cfg.instructions;
-      fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-      log('opencode.json: 移除本包登记的 instructions，保留用户配置', 'success');
+    // 旧位置：项目根 opencode.json（未升级就卸载的老空间，或迁移残留）
+    const legacyPath = path.join(TARGET_DIR, 'opencode.json');
+    if (adapter.legacyInstructionsPattern && fs.existsSync(legacyPath)) {
+      let legacyCfg;
+      try {
+        legacyCfg = JSON.parse(fs.readFileSync(legacyPath, 'utf-8'));
+      } catch (_) {
+        return; // 不可解析的文件不动
+      }
+      if (Array.isArray(legacyCfg.instructions) && legacyCfg.instructions.includes(adapter.legacyInstructionsPattern)) {
+        legacyCfg.instructions = legacyCfg.instructions.filter(p => p !== adapter.legacyInstructionsPattern);
+        if (legacyCfg.instructions.length === 0) delete legacyCfg.instructions;
+        fs.writeFileSync(legacyPath, JSON.stringify(legacyCfg, null, 2) + '\n');
+        log('opencode.json: 移除本包登记的旧版 instructions，保留用户配置', 'success');
+      }
     }
   });
 }
@@ -499,13 +560,82 @@ function deployCommandFiles(adapter, srcDir, destDir, prefix, filter) {
     const srcPath = path.join(srcDir, f);
     const destPath = path.join(destDir, prefix + f);
     removePath(destPath);
-    const content = applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'));
+    const content = rewriteCommandName(adapter, sanitizeCommandFrontmatter(applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8'))));
     fs.writeFileSync(destPath, content);
   });
 
   return { count: commandFiles.length, names: commandFiles.map(f => prefix + f) };
 }
 
+/**
+ * worktree 运行时部署：SKILL.md + scripts 复制到 .cbb/skills/<name>/（每空间一份，不分工具）。
+ * 单形态 command 收敛后，worktree 不进各工具的 skills 目录——新版工具会把 skills 暴露成
+ * 斜杠命令，与命令文件在面板里重复；脚本与流程文档统一放 .cbb/skills/，命令文件指向此处。
+ */
+function deployWorktreeRuntime(newPaths) {
+  const srcDir = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
+  if (!fs.existsSync(srcDir)) return 0;
+  const runtimeDir = path.join(TARGET_DIR, '.cbb', 'skills');
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  let count = 0;
+  WORKTREE_SKILLS.forEach(name => {
+    const src = path.join(srcDir, name);
+    if (!fs.existsSync(src)) return;
+    const destDir = path.join(runtimeDir, name);
+    removePath(destDir);
+    fs.cpSync(src, destDir, { recursive: true });
+    newPaths.add(`.cbb/skills/${name}`);
+    count++;
+  });
+  return count;
+}
+
+/**
+ * 命令 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。
+ */
+function rewriteCommandName(adapter, content) {
+  if (!adapter.commandNameKebab) return content;
+  return content.replace(/^name:\s*"?([A-Za-z]+):\s*([^"\r\n]+?)"?\s*\r?$/m, (m0, ns, rest) => {
+    const kebab = (ns + '-' + rest).toLowerCase().replace(/\s+/g, '-');
+    return `name: "${kebab}"`;
+  });
+}
+
 /** 官方 OpenSpec 命令（openspec/commands/ → adapter.commandsDir） */
 function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
   if (!adapter.commandsDir) return { count: 0, names: [] };
@@ -871,9 +1001,10 @@ 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`);
-    // opencode：rules glob 登记进项目根 opencode.json instructions
-    if (adapter.instructionsPattern) {
+    // 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');
@@ -883,11 +1014,10 @@ async function init(targetDir, options = {}) {
   if (skillsAdapters.length > 0) {
     console.log(`\n  🔧 ${action}按需加载 Skills...`);
     const standardsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'dev-standards', 'skills');
-    const openspecExtendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees', 'skills');
     const extendsSkillsSrc = path.join(SHARED_STANDARDS_DIR, 'cbb', 'tools');
 
     const skillsDests = skillsAdapters.map(a => a.skillsDir);
-    let stdCount = 0, osCount = 0, extCount = 0;
+    let stdCount = 0, extCount = 0;
     skillsAdapters.forEach(adapter => {
       // 通用编码规范 Skills（cbb/dev-standards/skills）
       const stdResult = deploySkills(adapter, isUpgrade, managedPaths, standardsSkillsSrc);
@@ -897,12 +1027,6 @@ async function init(targetDir, options = {}) {
       }
       // 官方 OpenSpec Skills（openspec/skills/）不部署——工作流入口统一为 /opsx:* 斜杠命令
       //（openspec/commands/ 在下方 Commands 段部署），避免双形态重复
-      // 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：当前不分发（恢复方式见 TOOLS_SKILLS 注释）
       const extResult = deploySkills(adapter, isUpgrade, managedPaths, extendsSkillsSrc, TOOLS_SKILLS);
       if (extResult.count > 0) {
@@ -911,7 +1035,6 @@ async function init(targetDir, options = {}) {
       }
     });
     if (stdCount > 0) log(`规范 Skills → ${skillsDests.join(', ')} (${stdCount} 个)`, 'success');
-    if (osCount > 0) log(`worktree Skills → ${skillsDests.join(', ')} (${osCount} 个)`, 'success');
     if (extCount > 0) log(`扩展 Skills → ${skillsDests.join(', ')} (${extCount} 个)`, 'success');
 
     // 部署 Superpowers Skills（白名单：openspec 工作流依赖 + 方法论基底）
@@ -935,6 +1058,10 @@ async function init(targetDir, options = {}) {
     await detectUserLevelSuperpowers(selectedAdapters, yes);
   }
 
+  // worktree 运行时（SKILL.md + scripts）→ .cbb/skills/（每空间一份，不分工具）
+  const runtimeCount = deployWorktreeRuntime(newPaths);
+  if (runtimeCount > 0) log(`worktree 运行时 → .cbb/skills (${runtimeCount} 个)`, 'success');
+
   // 安装 Commands（官方 11 个 → /opsx:*，onboard 不分发；worktree 管理 → /cbb:worktree-*，init/close/push 三件套）
   const commandsAdapters = selectedAdapters.filter(a => a.commandsDir);
   if (commandsAdapters.length > 0) {

package/cbb/lib/install/opencode.js

@@ -1,31 +1,39 @@
-/**
- * opencode 适配器
- *
- * 将编码规范分发到 .opencode/ 目录（opencode 项目级配置域）。
- *
- * 与 Claude Code / Qoder 的映射差异：
- * - rules：opencode 无原生 rules 目录，部署到 .opencode/rules/ 并由安装流程
- *   将 glob 注册进项目根 opencode.json 的 instructions 字段（官方支持的加载方式）
- * - skills：.opencode/skills/<name>/SKILL.md，结构与 Claude 同构
- * - commands：命令名 = 文件名（嵌套目录无命名空间，且 init.md 等会撞内置 /init），
- *   因此扁平化为 opsx-<name>.md（/opsx-propose）；worktree 管理命令同理扁平化为
- *   cbb-<name>.md（/cbb-worktree-init），部署副本中的 /opsx: 与 /cbb: 引用同步改写
- * - hooks：opencode 无 UserPromptSubmit 等价事件，版本检查 hook 不安装（settingsFile 留空即跳过）
- */
-
-module.exports = {
-  name: 'opencode',
-  displayName: 'opencode',
-  rulesDir: '.opencode/rules',
-  skillsDir: '.opencode/skills',
-  commandsDir: '.opencode/commands',
-  // 部署时给命令文件名加此前缀（规避内置命令名冲突）
-  commandPrefix: 'opsx-',
-  // worktree 管理命令（非 openspec 上游）落在同一扁平目录，用 cbb- 前缀区分
-  worktreeCommandsDir: '.opencode/commands',
-  worktreeCommandPrefix: 'cbb-',
-  // 部署副本中将该引用串改写为 opencode 的命令风格（配合 commandPrefix）
-  contentRewrites: [['/opsx:', '/opsx-'], ['/cbb:', '/cbb-']],
-  // rules 加载登记：注入项目根 opencode.json 的 instructions（glob，相对项目根）
-  instructionsPattern: '.opencode/rules/*.md',
-};
+/**
+ * opencode 适配器
+ *
+ * 将编码规范分发到 .opencode/ 目录（opencode 项目级配置域）。
+ *
+ * 与 Claude Code / Qoder 的映射差异：
+ * - rules：opencode 无原生 rules 目录，部署到 .opencode/rules/ 并由安装流程
+ *   将 glob 登记进 .opencode/opencode.json 的 instructions 字段（opencode V2
+ *   官方支持的配置位置：全局目录 / 项目根 / .opencode 目录内均会被发现）
+ * - skills：.opencode/skills/<name>/SKILL.md，结构与 Claude 同构
+ * - commands：命令名 = 文件名（嵌套目录无命名空间，且 init.md 等会撞内置 /init），
+ *   因此扁平化为 opsx-<name>.md（/opsx-propose）；worktree 管理命令同理扁平化为
+ *   cbb-<name>.md（/cbb-worktree-init），部署副本中的 /opsx: 与 /cbb: 引用同步改写
+ * - hooks：opencode 无 UserPromptSubmit 等价事件，版本检查 hook 不安装（settingsFile 留空即跳过）
+ */
+
+module.exports = {
+  name: 'opencode',
+  displayName: 'opencode',
+  rulesDir: '.opencode/rules',
+  skillsDir: '.opencode/skills',
+  commandsDir: '.opencode/commands',
+  // 部署时给命令文件名加此前缀（规避内置命令名冲突）
+  commandPrefix: 'opsx-',
+  // worktree 管理命令（非 openspec 上游）落在同一扁平目录，用 cbb- 前缀区分
+  worktreeCommandsDir: '.opencode/commands',
+  worktreeCommandPrefix: 'cbb-',
+  // 部署副本中将该引用串改写为 opencode 的命令风格（配合 commandPrefix）
+  contentRewrites: [['/opsx:', '/opsx-'], ['/cbb:', '/cbb-']],
+  // 命令显示名取自 frontmatter name，部署副本重写为 kebab-case（/opsx-propose，与文档一致）
+  commandNameKebab: true,
+  // rules 加载登记：写入 .opencode/opencode.json 的 instructions。
+  // instructions 相对路径的解析基准（配置文件目录 vs 项目根）文档未写死，
+  // 登记双 glob 对冲：任一基准下恰有一个命中，另一个空匹配。
+  instructionsFile: '.opencode/opencode.json',
+  instructionsPatterns: ['rules/*.md', '.opencode/rules/*.md'],
+  // 旧版（≤0.0.3-beta.2）曾登记在项目根 opencode.json 的 pattern，迁移/卸载时识别清理用
+  legacyInstructionsPattern: '.opencode/rules/*.md',
+};

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

@@ -11,12 +11,11 @@ tags: [worktree, cleanup, worktree, git-worktree]
 
 **禁止**用 `ls` / `find` / `cat` / `head` / `grep` 等 bash 命令搜索 SKILL.md。这些命令在 Agent 运行环境（Qoder Windows PowerShell 等）中经常失败。
 
-**直接路径**：
-- Qoder 适配器：`.qoder/skills/cbb-worktree-close/SKILL.md`
-- Claude Code 适配器：`.claude/skills/cbb-worktree-close/SKILL.md`
+**直接路径**（各工具统一，worktree 运行时部署在空间根 `.cbb/skills/`）：
+- `.cbb/skills/cbb-worktree-close/SKILL.md`
 
 **第一步**：
-1. 用 Read 工具直接打开 SKILL.md
+1. 用 Read 工具直接打开 `.cbb/skills/cbb-worktree-close/SKILL.md`
 2. 按 SKILL.md 的 Step 0 → 1 → 2 → 3 → 4 → 5 → 6 顺序执行
 3. 每次调用 Node.js 脚本时使用**绝对路径**
 

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

@@ -11,16 +11,15 @@ tags: [worktree, isolation, worktree, git-worktree]
 
 **禁止**用 `ls` / `find` / `cat` / `head` / `grep` 等 bash 命令搜索 SKILL.md 是否存在。**这些命令在 Agent 运行环境（Qoder Windows PowerShell 等）中经常失败**（如 `head` 不存在、stderr 重定向无效等）。
 
-**直接路径**：
-- Qoder 适配器：`.qoder/skills/cbb-worktree-init/SKILL.md`
-- Claude Code 适配器：`.claude/skills/cbb-worktree-init/SKILL.md`
+**直接路径**（各工具统一，worktree 运行时部署在空间根 `.cbb/skills/`）：
+- `.cbb/skills/cbb-worktree-init/SKILL.md`
 
 **第一步**：
-1. 用 Read 工具直接打开 `.qoder/skills/cbb-worktree-init/SKILL.md`（或 `.claude/skills/...`）
+1. 用 Read 工具直接打开 `.cbb/skills/cbb-worktree-init/SKILL.md`
 2. 按 SKILL.md 的 Step 0 → 1 → 2 → 3 → 4 顺序执行
 3. 每次调用 Node.js 脚本时，使用**绝对路径**（避免依赖相对路径）：
    ```
-   node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\<name>.js" <参数>
+   node "D:\workspace\<用户工作空间>\.cbb\skills\cbb-worktree-init\scripts\<name>.js" <参数>
    ```
    - 参数形式：
      - `check-env.js`：无参数

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

@@ -16,7 +16,7 @@ tags: [workflow, push, commit, worktree, experimental]
 - 开发过程中想保存中间进度
 - 用户口语化说"提交并push" / "推一下"
 
-**Steps 摘要**（详细见 [cbb-worktree-push SKILL.md](../../skills/cbb-worktree-push/SKILL.md)）：
+**Steps 摘要**（详细流程见空间根 `.cbb/skills/cbb-worktree-push/SKILL.md`）：
 
 1. **Step 0**：定位工作空间根（find-workspace-root.js）
 2. **Step 1**：识别目标 worktree（find-target-worktree.js）

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

@@ -34,7 +34,7 @@ metadata:
 ### 0.1 环境健康探活
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-env.js"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/check-env.js"
 ```
 
 **解读输出**：
@@ -45,7 +45,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-env.
 ### 0.2 定位工作空间根目录
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-workspace-root.js"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/find-workspace-root.js"
 ```
 
 **解读输出**：
@@ -69,7 +69,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-works
 3. AI agent 列出 `.worktrees/` 下的所有 worktree：
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-target-worktree.js "<ws_root>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/find-target-worktree.js "<ws_root>"
 ```
 
 > 注：本技能支持工作空间根目录或 worktree 内执行，find-target-worktree 自动从 cwd 反推或列出。
@@ -84,7 +84,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/find-targe
 ### 1.2 发现关联应用 worktree
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/discover-apps.js "<ws_root>" "<branch>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/discover-apps.js "<ws_root>" "<branch>"
 ```
 
 脚本自动从 `workspace-config.json` 读取应用列表，扫描 `.worktrees/worktree-<branch>/<应用名>/` 实际存在的子目录。
@@ -98,7 +98,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/discover-a
 ### 1.3 检查未归档 change
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-unarchived.js "<ws_root>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/check-unarchived.js "<ws_root>"
 ```
 
 脚本扫描 `openspec/changes/` 目录，筛选出非 `archive/` 子目录的 change 名称列表。
@@ -117,7 +117,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/check-unar
 对 workspace worktree 和每个关联应用 worktree，依次执行三项检查并汇总成安全状态表。**这是破坏性操作前的必经环节，结果将驱动 Step 3 的用户决策。**
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/safety-check.js "<ws_root>" "<branch>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/safety-check.js "<ws_root>" "<branch>"
 ```
 
 脚本内部对每个仓库自动执行：
@@ -289,7 +289,7 @@ node "<skill>/scripts/delete-branches.js" "<ws_root>" "<branch>" local_remote
 **顺序：先移除各应用 worktree，再移除 workspace worktree**（逆序于创建；也为后续删分支扫清"分支仍被检出"的障碍）。
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-close/scripts/remove-worktrees.js "<ws_root>" "<branch>" "<force>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-close/scripts/remove-worktrees.js "<ws_root>" "<branch>" "<force>"
 ```
 
 **三层降级策略**：`git worktree remove` 实际包含两个动作——①清理 git 元数据（`.git/worktrees/`）②删除物理目录。当 IDE 占用目录时 ② 会被 Windows 文件锁阻塞，但 ① 永远不受影响。脚本将这两个动作解耦：

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

@@ -28,11 +28,11 @@ metadata:
 
 ## 调用脚本的统一方式
 
-**重要**：所有脚本必须用**绝对路径**调用。`./scripts/...` 相对路径在 Agent 运行环境中不适用（AI agent 的 cwd 不一定是技能目录）。
+**重要**：所有脚本必须用**绝对路径**调用。`./scripts/...` 相对路径在 Agent 运行环境中不适用（AI agent 的 cwd 不一定是技能目录）。worktree 运行时统一部署在空间根 `.cbb/skills/` 下，各工具一致。
 
 调用方式（推荐用绝对路径）：
 ```
-node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\<name>.js" <参数>
+node "D:\workspace\<用户工作空间>\.cbb\skills\cbb-worktree-init\scripts\<name>.js" <参数>
 ```
 
 脚本输出：
@@ -54,7 +54,7 @@ node "D:\workspace\<用户工作空间>\.qoder\skills\cbb-worktree-init\scripts\
 ### 0.1 环境健康探活
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env.js"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/check-env.js"
 ```
 
 **解读输出**：
@@ -67,7 +67,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env.j
 提前检测权限/版本问题，把可能在后续步骤暴露的失败前移到流程最开始：
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env-deep.js"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/check-env-deep.js"
 ```
 
 **解读输出**：
@@ -81,7 +81,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-env-d
 ### 0.2 读取并校验 workspace-config.json
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/parse-config.js"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/parse-config.js"
 ```
 
 **解读输出**：
@@ -148,7 +148,7 @@ worktree 需要知道要关联哪些应用仓库。
 
 ```bash
 # ws_root 来自 AI agent 维护的状态
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/sync-repos.js" "<ws_root>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/sync-repos.js" "<ws_root>"
 ```
 
 **用法**：
@@ -192,7 +192,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/sync-repos.
 | 当前在主分支上 | ✅ | ❌ |
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-repos.js" "<ws_root>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/check-repos.js" "<ws_root>"
 ```
 
 **解读输出**：
@@ -220,7 +220,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/check-repos
 ### 3.2 安全更新 .gitignore（前置）
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/update-gitignore.js "<ws_root>" "<branch>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/update-gitignore.js "<ws_root>" "<branch>"
 ```
 
 脚本内部自动完成：stash 保护 → 切分支 → 添加 `.worktrees/` 和 `.codespace/` → 提交 → 切回 → pop stash
@@ -234,7 +234,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/update-giti
 ### 3.3 创建分支
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/create-branches.js" "<ws_root>" "<branch>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/create-branches.js" "<ws_root>" "<branch>"
 ```
 
 **解读输出**：
@@ -259,7 +259,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/create-bran
 ### 3.4 推送并建立 upstream
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/push-branches.js" "<ws_root>" "<branch>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/push-branches.js" "<ws_root>" "<branch>"
 ```
 
 脚本内部自动完成：
@@ -287,7 +287,7 @@ node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/push-branch
 ### 3.5 创建 Worktree（含自愈清理）
 
 ```bash
-node "D:/workspace/<ws_root>/.qoder/skills/cbb-worktree-init/scripts/create-worktrees.js" "<ws_root>" "<branch>"
+node "D:/workspace/<ws_root>/.cbb/skills/cbb-worktree-init/scripts/create-worktrees.js" "<ws_root>" "<branch>"
 ```
 
 脚本内部自动完成：
@@ -467,7 +467,7 @@ WT_PATH d:\workspace\xxx\.worktrees\worktree-feature-login
 - workspace 仓库标准检查（当前在主分支等），app 仓库轻量检查（fetch + `origin/main` 可用即可）
 - app 仓库分支从 `origin/main` 创建（`git branch <需求名> ${REMOTE}/${MAIN}`），不依赖本地主分支状态
 - 严格 Step 3.3 → Step 3.4 顺序（先统一创建分支，再统一创建 worktree；workspace 工作树先建，各应用按序补建）
-- 所有脚本调用以 `node "<WS_ROOT>\.qoder\skills\cbb-worktree-init\scripts\<name>.js" "<绝对路径>" "<branch>"` 形式发起（apps 由脚本内部从 workspace-config.json 读取），**不依赖跨调用的 cwd**
+- 所有脚本调用以 `node "<WS_ROOT>\.cbb\skills\cbb-worktree-init\scripts\<name>.js" "<绝对路径>" "<branch>"` 形式发起（apps 由脚本内部从 workspace-config.json 读取），**不依赖跨调用的 cwd**
 - **Step 3.4 push 步骤必须执行且插入在 create-branches.js (3.3) 之后、create-worktrees.js (3.5) 之前** — 失败时阻塞整个 init-worktree 流程
 - **Step 3.4 仅覆盖创建 worktree 时的空 commit** — 开发过程中产生的本地 commit（如 apply 任务实现）必须由用户在 worktree 中手动提交并调 `cbb-worktree-push` 推送；不允许依赖 Step 3.4 之后的自动推送（不存在）
 

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

@@ -33,7 +33,7 @@ metadata:
 **所有脚本必须用绝对路径调用**（Agent 运行环境中 AI agent 的 cwd 不一定是技能目录）。
 
 ```
-node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/<name>.js" <参数>
+node "<ws_root>/.cbb/skills/cbb-worktree-push/scripts/<name>.js" <参数>
 ```
 
 脚本输出：
@@ -46,7 +46,7 @@ node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/<name>.js" <参数>
 ## Step 0：定位工作空间
 
 ```bash
-node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/find-workspace-root.js"
+node "<ws_root>/.cbb/skills/cbb-worktree-push/scripts/find-workspace-root.js"
 ```
 
 **解读末行**：
@@ -58,7 +58,7 @@ node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/find-workspace-root.js"
 ## Step 1：识别目标 worktree
 
 ```bash
-node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/find-target-worktree.js" "<ws_root>"
+node "<ws_root>/.cbb/skills/cbb-worktree-push/scripts/find-target-worktree.js" "<ws_root>"
 ```
 
 **解读末行**：
@@ -72,7 +72,7 @@ node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/find-target-worktree.js"
 
 ```bash
 # 仅 commit 阶段先做 dry-run 预览
-node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/commit-worktrees.js" "<ws_root>" "<branch>" --message "preview" --dry-run
+node "<ws_root>/.cbb/skills/cbb-worktree-push/scripts/commit-worktrees.js" "<ws_root>" "<branch>" --message "preview" --dry-run
 ```
 
 **解读末行 `COMMIT_RESULT`**：每项仓库的状态
@@ -119,7 +119,7 @@ AI agent 在执行真实 commit 前**必须**在对话中向用户确认 commit
 
 ```bash
 # 统一信息
-node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/commit-worktrees.js" "<ws_root>" "<branch>" --message "feat(<branch>): 实现客户运费逻辑"
+node "<ws_root>/.cbb/skills/cbb-worktree-push/scripts/commit-worktrees.js" "<ws_root>" "<branch>" --message "feat(<branch>): 实现客户运费逻辑"
 
 # 多仓库分别
 node "..." "<ws_root>" "<branch>" --per-repo "ep-foo-app:feat(<branch>): 实现 saveClientExpectFreight;ep-bar-app:refactor(<branch>): 拆分 PlanService"
@@ -155,7 +155,7 @@ node "..." "<ws_root>/.worktrees/worktree-<branch>" --message "..."
 ## Step 5：批量 push
 
 ```bash
-node "<ws_root>/.qoder/skills/cbb-worktree-push/scripts/push-worktrees.js" "<ws_root>" "<branch>"
+node "<ws_root>/.cbb/skills/cbb-worktree-push/scripts/push-worktrees.js" "<ws_root>" "<branch>"
 
 # 或 wt_path 形式
 node "..." "<ws_root>/.worktrees/worktree-<branch>"

package/config/workspace-agents.sample.md

@@ -20,8 +20,8 @@
 | `.codespace/` | 各关联应用的基准代码（每个应用一个子目录） | `cbb setup` 与 worktree 流程自动 clone / fetch；**勿手动编辑**；已 gitignore，不提交 |
 | `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/` 目录） | worktree 命令自动创建 / 清理；不提交（首次执行 worktree 流程时自动加入 .gitignore） |
 | `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | 由 cbb 安装；需求变更产物（`openspec/changes/` 等）在**需求工作树内**生成，随需求分支提交 |
-| `.claude/` `.qoder/` `.opencode/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、worktree 管理技能与命令 | 由 cbb 按 setup 时选择的工具安装；已 gitignore，不提交，勿手动改 |
-| `.cbb/` | cbb 安装清单，记录本包管理的全部路径 | 由 cbb 管理；**勿手动编辑** |
+| `.claude/` `.qoder/` `.opencode/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、worktree 管理命令 | 由 cbb 按 setup 时选择的工具安装；已 gitignore，不提交，勿手动改 |
+| `.cbb/` | cbb 安装清单 + worktree 运行时（`.cbb/skills/`：流程文档与脚本，各工具命令共用） | 由 cbb 管理；**勿手动编辑** |
 
 ## 典型流程
 

package/package.json

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