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

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

@@ -1,117 +1,136 @@
----
-trigger: always_on
----
-
-# AI 行为准则
-
-七条行为准则，减少 AI 编码常见错误。源自 [Andrej Karpathy 对 LLM 编码缺陷的观察](https://x.com/karpathy/status/2015883857489522876)。
-
-**权衡：** 这些准则倾向于谨慎而非速度。对于简单任务（如修 typo、改文案），按常识判断即可。
-
-## 1. 先想后写
-
-**不假设，不隐藏困惑，主动呈现权衡。**
-
-实现前：
-- 明确声明假设，不确定时主动询问
-- 若存在多种解释，呈现出来而非自己默默选一种
-- 若有更简单的方案，说出来，必要时 push back
-- 若有不明确的地方，停下来，说出困惑，请求澄清
-
-## 2. 简洁至上
-
-**用最少代码解决问题，不加推测性内容。**
-
-- 不实现用户未要求的功能
-- 不为单次使用的代码创建抽象
-- 不添加用户未要求的"灵活性"或"可配置性"
-- 不为不可能发生的场景写错误处理
-- 写了 200 行却发现 50 行就能搞定 → 重写
-
-自问："资深工程师会说过度设计吗？"如果会，简化。
-
-## 3. 外科手术式修改
-
-**只改必须改的，只清理自己造成的烂摊子。**
-
-编辑已有代码时：
-- 不顺手"改进"相邻代码、注释或格式
-- 不重构没坏的东西
-- 匹配现有风格，即使你更习惯另一种写法
-- 发现无关的死代码，口头提及即可，不要删除
-
-当你的改动产生孤儿代码时：
-- 删除因你的改动而不再使用的 import / 变量 / 函数
-- 不删除已有的死代码，除非用户要求
-
-**检验标准：** 每一行改动都应该能追溯到用户的需求。
-
-## 4. 目标驱动执行
-
-**定义成功标准，循环直到验证通过。**
-
-将命令式任务转换为可验证的目标：
-
-| 而非… | 转换为… |
-|--------|---------|
-| "加个校验" | "先写无效输入的测试，再让测试通过" |
-| "修这个 bug" | "先写能复现的测试，再修到测试通过" |
-| "重构 X" | "确保重构前后测试全部通过" |
-
-多步任务先给简短计划：
-```
-1. [步骤] → 验证: [检查项]
-2. [步骤] → 验证: [检查项]
-3. [步骤] → 验证: [检查项]
-```
-
-清晰的成功标准让 AI 可以独立循环验证，模糊的标准（"搞一下"）需要反复澄清。
-
-## 5. 失败要大声说出来
-
-**悄悄绕过失败比直接失败更糟糕。**
-
-- 有步骤被跳过，"完成"就是错的——说出来
-- 有测试被跳过，"测试通过"就是错的——说出来
-- 不确定就直接说不确定，不假装确认
-- 默认暴露不确定性，不掩盖
-
-**检验标准：** 任何跳过的步骤、不确定的结论、未验证的结果，都以标记形式呈现，不悄悄带过。
-
-## 6. 不认同也要说出来
-
-当项目现有约定明显有问题时：
-
-- 照样遵循，保持一致——不悄悄另起炉灶
-- 明确提出来——指出风险，给出替代方案
-- 让用户做决策，不要替用户做选择
-
-**检验标准：** 你的代码放进现有代码中，读不出"换了一个人写的"。发现的问题以建议形式呈现，而非悄悄用另一种方式实现。
-
-## 7. 先批准，后动工
-
-**任何实现动作前，先陈述方案并获得用户批准。**
-
-- 动手前说出打算怎么做（方案、涉及文件、验证方式），等用户确认
-- 仪式随任务缩放：小改动两三句话说清即可；大改动走 openspec 工作流（propose → specs → design）
-- "太简单不需要方案"是最危险的念头——简单意味着方案短，而不是没有方案
-- 中途发现复杂度超出预期：停下来重新说明，不要闷头扩大改动范围
-
-**检验标准：** 用户从未因"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 变更产物只出现在需求工作树内。
-
----
-
+---
+trigger: always_on
+---
+
+# AI 行为准则
+
+七条行为准则，减少 AI 编码常见错误。源自 [Andrej Karpathy 对 LLM 编码缺陷的观察](https://x.com/karpathy/status/2015883857489522876)。
+
+**权衡：** 这些准则倾向于谨慎而非速度。对于简单任务（如修 typo、改文案），按常识判断即可。
+
+## 1. 先想后写
+
+**不假设，不隐藏困惑，主动呈现权衡。**
+
+实现前：
+- 明确声明假设，不确定时主动询问
+- 若存在多种解释，呈现出来而非自己默默选一种
+- 若有更简单的方案，说出来，必要时 push back
+- 若有不明确的地方，停下来，说出困惑，请求澄清
+
+## 2. 简洁至上
+
+**用最少代码解决问题，不加推测性内容。**
+
+- 不实现用户未要求的功能
+- 不为单次使用的代码创建抽象
+- 不添加用户未要求的"灵活性"或"可配置性"
+- 不为不可能发生的场景写错误处理
+- 写了 200 行却发现 50 行就能搞定 → 重写
+
+自问："资深工程师会说过度设计吗？"如果会，简化。
+
+## 3. 外科手术式修改
+
+**只改必须改的，只清理自己造成的烂摊子。**
+
+编辑已有代码时：
+- 不顺手"改进"相邻代码、注释或格式
+- 不重构没坏的东西
+- 匹配现有风格，即使你更习惯另一种写法
+- 发现无关的死代码，口头提及即可，不要删除
+
+当你的改动产生孤儿代码时：
+- 删除因你的改动而不再使用的 import / 变量 / 函数
+- 不删除已有的死代码，除非用户要求
+
+**检验标准：** 每一行改动都应该能追溯到用户的需求。
+
+## 4. 目标驱动执行
+
+**定义成功标准，循环直到验证通过。**
+
+将命令式任务转换为可验证的目标：
+
+| 而非… | 转换为… |
+|--------|---------|
+| "加个校验" | "先写无效输入的测试，再让测试通过" |
+| "修这个 bug" | "先写能复现的测试，再修到测试通过" |
+| "重构 X" | "确保重构前后测试全部通过" |
+
+多步任务先给简短计划：
+```
+1. [步骤] → 验证: [检查项]
+2. [步骤] → 验证: [检查项]
+3. [步骤] → 验证: [检查项]
+```
+
+清晰的成功标准让 AI 可以独立循环验证，模糊的标准（"搞一下"）需要反复澄清。
+
+## 5. 失败要大声说出来
+
+**悄悄绕过失败比直接失败更糟糕。**
+
+- 有步骤被跳过，"完成"就是错的——说出来
+- 有测试被跳过，"测试通过"就是错的——说出来
+- 不确定就直接说不确定，不假装确认
+- 默认暴露不确定性，不掩盖
+
+**检验标准：** 任何跳过的步骤、不确定的结论、未验证的结果，都以标记形式呈现，不悄悄带过。
+
+## 6. 不认同也要说出来
+
+当项目现有约定明显有问题时：
+
+- 照样遵循，保持一致——不悄悄另起炉灶
+- 明确提出来——指出风险，给出替代方案
+- 让用户做决策，不要替用户做选择
+
+**检验标准：** 你的代码放进现有代码中，读不出"换了一个人写的"。发现的问题以建议形式呈现，而非悄悄用另一种方式实现。
+
+## 7. 先批准，后动工
+
+**任何实现动作前，先陈述方案并获得用户批准。**
+
+- 动手前说出打算怎么做（方案、涉及文件、验证方式），等用户确认
+- 仪式随任务缩放：小改动两三句话说清即可；大改动走 openspec 工作流（propose → specs → design）
+- "太简单不需要方案"是最危险的念头——简单意味着方案短，而不是没有方案
+- 中途发现复杂度超出预期：停下来重新说明，不要闷头扩大改动范围
+
+**检验标准：** 用户从未因"AI 直接改了代码没打招呼"而感到意外。
+
+## 8. 业务空间开发模式（双模式，用户选择制）
+
+**仅当工作目录是业务空间根（存在 `CBB-WORKSPACE.json` 且 `.git` 为目录）时生效。空间支持两种开发模式，能力对称（都能修改 workspace 内容与应用代码、都强制分支隔离、交付都走 MR），由用户显式选择，agent 只给推荐不代决。**
+
+**模式一 · 本地模式（单线程快改，当前会话就地干）：**
+
+- 就地切分支：根 + 各涉及应用 `.codespace/<app>/` 同名 `checkout -b`（基线 = `origin/<main>`，经 `cbb-local-mode` 技能执行）
+- 当前会话原地开发，相对路径原样生效；**一次只承载一个需求**（独占本地检出；期间并行新需求走 worktree 模式，互不干扰）
+- 收尾：MR 合并后各参与仓库 `checkout main && pull && 删分支`
+
+**模式二 · worktree 模式（并行 / 隔离）：**
+
+- `cbb-worktree-init` 建隔离 worktree（AI 配置内容子目录已 junction 就位），**开发会话开进 `.worktrees/worktree-<需求名>/`**，可多需求并行；app 检出收拢在 `<wt>/.codespace/<app>/`——**镜像空间根布局**（`.codespace/<app>/...` 相对路径两模式通用，ADR 0003）
+- 根会话保留作控制面（worktree 生灭、`cbb update` 等空间级操作）；**会话形态按工具定，能自动则 agent 亲自做**：OpenCode 桌面端 = agent 自动把会话切进/切出 worktree（`session_move`，上下文保留、不列入用户待办，空间根路径在案供回切）；无会话搬移能力的桌面端 = 用户手动切根；CLI/TUI = 新开会话进 worktree
+
+**基准与防线（两模式共同，ADR 0002）：**
+
+- **基准 = `origin/main`（唯一真相源）；`.codespace/<app>/` 的检出 = 视图**——本地模式可暂态被需求分支占用，收尾恢复
+- **严禁直接在任何 main 检出上提交载荷**：分支感知 pre-commit hook 机械拦截（workspace 仓库仅放行控制面白名单：`CBB-WORKSPACE.json` / `.gitignore` / `AGENTS.md` / `openspec/config.yaml` / `openspec/schemas/**`；应用仓库 main 全拦）——**被拦是防线生效，不是故障**；`--no-verify` 绕过仅限用户显式要求
+- 远端推送唯一出口 = `cbb-worktree-push`（init 创建流程零远端操作，lazy push；空分支尸体不存在）
+- **模式误判零代价**：本地模式中途要并行/隔离 → 重跑 `cbb-worktree-init`（分支已存在自动复用，提交随身带走）
+
+**三时刻对齐（agent 必须遵守）：**
+
+1. **开工前——状态自检**（`cbb-local-mode` 的 `check-local-state.js`）：干净态零交互直接开工；**遗留态（别的需求未收尾，任一仓库检出在非主干分支）必须让用户四选一**（继续 / 先收尾 / 升级 worktree / 丢弃），不得自行决定
+2. **开工时——布局确认**：向用户展示参与仓库与分支名，确认后执行
+3. **进行中——插单归属**：用户插入非本需求的改动，先确认归属（并入 / 收尾后处理 / 转 worktree），不得静默混入
+
+**读基准代码约定：** 本地模式进行中，工作区是开发态而非基准——要读"main 现状"先确认检出分支，或直接 `git show main:<path>` / `git diff main`；不要默认工作区即基准。
+
+**检验标准：** 任何 main 检出上无载荷提交（hook 兜底，git log 可机械审计）；本地模式收尾后全部仓库回主干且 clean；worktree 模式的变更产物只出现在需求工作树内；远端分支只经 push 技能产生。
+
+---
+
 **这些准则生效的标志：** diff 中不必要的改动减少、不会因过度设计而重写、澄清问题在实现前而非出错后提出。

package/cbb/lib/install/agents-nav.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * AGENTS.md 托管导航块（agentsNav）。
+ *
+ * MiniMax Code 不读取 .minimax/rules（源码无该逻辑），其项目级规则注入通道
+ * 只有工作区根 AGENTS.md（local-runtime/src/project/instructions.ts，32KB 预算）。
+ * 安装时在 AGENTS.md 注入一句托管导航，引导 AI 先读取规则；块形如：
+ *
+ *   <!-- cbb:agents-nav:minimax begin -->
+ *   ⚠️ 规则优先：……
+ *   <!-- cbb:agents-nav:minimax end -->
+ *
+ * 约束：
+ *  - 幂等：块内容随安装更新，块外用户内容永不改动；
+ *  - 标记带适配器名，多适配器共存不互撞；
+ *  - 卸载只摘除本包块；摘除后文件为空（本包创建的情形）则删除文件。
+ *
+ * AGENTS.md 本身不进清单（cleanup.js 的 PROTECTED_FROM_CLEANUP 同样保护它），
+ * 托管块的注入与摘除由 init() 安装流程 / uninstall() 按适配器显式处理。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** 转义正则元字符（适配器名入正则上下文） */
+function escapeRe(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function markersFor(adapterName) {
+  const safe = escapeRe(adapterName);
+  return {
+    begin: `<!-- cbb:agents-nav:${adapterName} begin -->`,
+    end: `<!-- cbb:agents-nav:${adapterName} end -->`,
+    // [\s\S]*? 非贪婪：块内可含任意内容（含 \r），遇最近的 end 标记即止
+    blockRe: new RegExp(`<!-- cbb:agents-nav:${safe} begin -->[\\s\\S]*?<!-- cbb:agents-nav:${safe} end -->`, 'm'),
+  };
+}
+
+/**
+ * 注入（或更新）导航块。
+ * @param {string} filePath 目标 AGENTS.md 绝对路径
+ * @param {string} adapterName 适配器名（标记命名空间）
+ * @param {string} text 导航句
+ * @returns {'created'|'updated'|'unchanged'} created = 文件原不存在或为空白
+ */
+function inject(filePath, adapterName, text) {
+  const { begin, end, blockRe } = markersFor(adapterName);
+  const existed = fs.existsSync(filePath);
+  const content = existed ? fs.readFileSync(filePath, 'utf-8') : '';
+  // 行尾与既有文件保持一致（Windows 生成的 AGENTS.md 多为 CRLF）
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const block = `${begin}${eol}${text}${eol}${end}`;
+
+  if (blockRe.test(content)) {
+    const next = content.replace(blockRe, block);
+    if (next === content) return 'unchanged';
+    fs.writeFileSync(filePath, next);
+    return 'updated';
+  }
+
+  const wasBlank = content.trim() === '';
+  const base = content.replace(/\n*$/, ''); // 收敛尾部空行，块另起段落
+  const next = wasBlank ? `${block}${eol}` : `${base}${eol}${eol}${block}${eol}`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next);
+  return wasBlank && !existed ? 'created' : wasBlank ? 'updated' : 'created';
+}
+
+/**
+ * 精确摘除导航块（块外内容不动）。
+ * @returns {boolean} 是否有改动（块不存在 → false）
+ */
+function remove(filePath, adapterName) {
+  if (!fs.existsSync(filePath)) return false;
+  const { blockRe } = markersFor(adapterName);
+  const content = fs.readFileSync(filePath, 'utf-8');
+  if (!blockRe.test(content)) return false;
+
+  // 只删块本身；随后收敛尾部空白（块移除后的残留空行）
+  const next = content.replace(blockRe, '').replace(/\s+$/, '');
+  if (next.trim() === '') {
+    // 文件只剩本包内容（由本包创建的情形）→ 连文件一起删除
+    fs.unlinkSync(filePath);
+    return true;
+  }
+  fs.writeFileSync(filePath, next + '\n');
+  return true;
+}
+
+module.exports = { inject, remove };

package/cbb/lib/install/claude-code.js

@@ -2,6 +2,11 @@
  * Claude Code 适配器
  *
  * 将编码规范分发到 .claude/rules/ 目录
+ *
+ * 退市（selectable: false）：团队当前不使用 Claude Code，不在安装面板提供。
+ * 适配器代码与全部能力保留（含用户级 settings hook）；先前已安装的空间按
+ * .last-tools 记录**粘性维护**（见 tool-selection.js），内容不被清理。
+ * 恢复入口：删掉 selectable 即可重新出现在面板（决策：不留参数开关）。
  */
 
 const path = require('path');
@@ -13,10 +18,10 @@ module.exports = {
   rulesDir: '.claude/rules',
   skillsDir: '.claude/skills',
   commandsDir: '.claude/commands/opsx',
-  // worktree 管理命令（非 openspec 上游）：独立命名空间 /cbb:worktree-*
-  worktreeCommandsDir: '.claude/commands/cbb',
   // 用户级 settings，写入全局生效，不污染项目目录
   settingsFile: path.join(os.homedir(), '.claude', 'settings.json'),
   settingsFileIsUserLevel: true,
   hookEvents: ['UserPromptSubmit'],
+  // 退市：不在安装面板提供（代码保留，存量空间粘性维护）
+  selectable: false,
 };

package/cbb/lib/install/command-skill.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * openspec 命令 → skill 形态转换（commandsAsSkills 适配器用，当前仅 MiniMax Code）。
+ *
+ * MiniMax Code 无项目级 commands 目录，skill 即其命令形态：每个 openspec 命令
+ * 落为 <skillsDir>/<prefix><name>/SKILL.md，目录名 = frontmatter name（Agent
+ * Skills 约定），/opsx-propose 斜杠照常可用。
+ *
+ * 同时承接命令 frontmatter 消毒（sanitizeCommandFrontmatter）：opencode 新版
+ * 校验命令配置（description 必须为 string | undefined），上游个别命令
+ * （openspec/commands/update.md）的 description 为空值（YAML 解析为 null），
+ * 会拒绝加载整个项目配置。此处对部署副本回填正文首句作为描述（超过 120 字
+ * 截断），上游源文件不动（CLI 接管区）。
+ */
+
+const path = require('path');
+
+/**
+ * 命令文件 → skill 目录名（文件名基准，保证目录名稳定）。
+ * @param {string} fileName 如 propose.md
+ * @param {string} prefix 如 opsx-
+ * @returns {string} 如 opsx-propose
+ */
+function skillNameFor(fileName, prefix) {
+  return (prefix || '') + path.basename(fileName, '.md');
+}
+
+/** 取 frontmatter（首个 --- 到闭合 --- 之间）；无 frontmatter 返回 -1 */
+function findFrontmatterEnd(lines) {
+  if ((lines[0] || '').trim() !== '---') return -1;
+  for (let i = 1; i < lines.length; i++) {
+    if ((lines[i] || '').trim() === '---') return i;
+  }
+  return -1;
+}
+
+/**
+ * 命令 frontmatter 消毒（见文件头注释）。无 frontmatter 或无需改动时原样返回。
+ */
+function sanitizeCommandFrontmatter(content) {
+  const lines = content.split('\n');
+  if ((lines[0] || '').trim() !== '---') return content;
+  const end = findFrontmatterEnd(lines);
+  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;
+}
+
+/**
+ * 把命令内容转换为 skill 的 SKILL.md 内容：
+ *  1. frontmatter description 消毒（null → 回填正文首句）；
+ *  2. frontmatter name 强制为 skillName —— 目录名 = name 是 Agent Skills 约定，
+ *     也规避上游标题与文件名不一致（如 ff.md 的 "OPSX: Fast Forward"）。
+ *
+ * 上游 frontmatter 的其余字段（category / tags 等）原样保留。
+ *
+ * @param {string} content 命令原文（调用方已应用 contentRewrites）
+ * @param {string} skillName 目标 skill 名（= 目录名）
+ * @returns {string} SKILL.md 内容
+ */
+function convertCommandToSkill(content, skillName) {
+  const sanitized = sanitizeCommandFrontmatter(content);
+  const lines = sanitized.split('\n');
+
+  // 无 frontmatter：补建（name 必填；description 回填正文首句）
+  if ((lines[0] || '').trim() !== '---') {
+    const sentence = (lines.find(l => l.trim()) || '').trim().slice(0, 120);
+    const fm = ['---', `name: "${skillName}"`];
+    if (sentence) fm.push(`description: ${JSON.stringify(sentence)}`);
+    fm.push('---', '');
+    return fm.concat(lines).join('\n');
+  }
+
+  const end = findFrontmatterEnd(lines);
+  if (end === -1) return sanitized; // 开了没闭合的异常 frontmatter：不动
+
+  let nameLine = -1;
+  for (let i = 1; i < end; i++) {
+    if (/^name:/.test(lines[i])) { nameLine = i; break; }
+  }
+  const nameValue = `name: "${skillName}"`;
+  if (nameLine === -1) lines.splice(1, 0, nameValue); // 缺 name：紧跟开标记插入
+  else lines[nameLine] = nameValue + (lines[nameLine].endsWith('\r') ? '\r' : '');
+
+  return lines.join('\n');
+}
+
+module.exports = { skillNameFor, sanitizeCommandFrontmatter, convertCommandToSkill };