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

package/cbb/lib/install/init.js

@@ -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,37 @@ 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 = sanitizeCommandFrontmatter(applyContentRewrites(adapter, fs.readFileSync(srcPath, 'utf-8')));
     fs.writeFileSync(destPath, content);
   });
 
   return { count: commandFiles.length, names: commandFiles.map(f => prefix + f) };
 }
 
+/**
+ * 命令 frontmatter 消毒：opencode 新版校验命令配置（description 必须为 string | undefined），
+ * 上游个别命令（openspec/commands/update.md）的 description 为空值（YAML 解析为 null），
+ * 会导致 opencode 拒绝加载整个项目配置。此处仅在部署副本的 frontmatter 块内
+ * 移除空的 description 行（undefined 合法），上游源文件不动（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 changed = false;
+  for (let i = 1; i < end; i++) {
+    if (/^description:\s*(null|~)?\s*\r?$/.test(lines[i])) {
+      lines[i] = null;
+      changed = true;
+    }
+  }
+  return changed ? lines.filter(l => l !== null).join('\n') : content;
+}
+
 /** 官方 OpenSpec 命令（openspec/commands/ → adapter.commandsDir） */
 function deployCommands(adapter, isUpgrade, managedPaths, srcDir, filter) {
   if (!adapter.commandsDir) return { count: 0, names: [] };
@@ -871,9 +956,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');

package/cbb/lib/install/opencode.js

@@ -1,31 +1,37 @@
-/**
- * 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-']],
+  // 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/package.json

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