@jspg-ai/coding-bb 0.0.3-beta.8 → 0.0.4

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

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

package/cbb/dev-standards/rules/cbb-workspace-discipline.md

@@ -0,0 +1,38 @@
+---
+trigger: always_on
+---
+
+# 业务空间开发纪律（双模式，用户选择制）
+
+**仅当处于业务空间体系（空间根、`.worktrees/` 工作树、及其中各应用检出）时生效。空间支持两种开发模式，能力对称（都能修改 workspace 内容与应用代码、都强制分支隔离、交付均有 MR 与直合并两条通道，ADR 0007/0008），由用户显式选择，agent 只给推荐不代决。**
+
+**模式一 · 本地模式（单线程快改，当前会话就地干）：**
+
+- 就地切分支：根 + 各涉及应用 `.codespace/<app>/` 同名 `checkout -b`（基线 = `origin/<main>`，经 `cbb-local-mode` 技能执行）
+- 当前会话原地开发，相对路径原样生效；**一次只承载一个需求**（独占本地检出；期间并行新需求走 worktree 模式，互不干扰）
+- 收尾（收尾合并门禁，ADR 0007）：`merge-branches.js --check` 判定已合并；未合并须三选一（提 MR / 直合并 `--allow-checkout` / 确认废弃）后方可收尾；各参与仓库 `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 全拦；**merge 提交（`MERGE_HEAD` 存在）放行**，见 ADR 0007）——**被拦是防线生效，不是故障**；`--no-verify` 绕过仅限用户显式要求
+- 需求分支推送唯一出口 = `cbb-worktree-push`（init 创建流程零远端操作，lazy push）；推送后可选提 MR 或**直接合并**（`merge-branches.js`，主干 / 测试分支，ADR 0008）；收尾合并门禁同源（ADR 0007）
+- **收尾合并门禁（ADR 0007）**：两模式收尾均须每仓库"已合并"（`safety-check` / `merge-branches.js --check` 判定）；未合并三选一——提 MR / 直合并 / 确认废弃（远程重命名 `<分支>-deprecated`）；交付完成自动删本地+远程分支
+- **模式误判零代价**：本地模式中途要并行/隔离 → 重跑 `cbb-worktree-init`（分支已存在自动复用，提交随身带走）
+
+**五时刻对齐（agent 必须遵守）：**
+
+1. **开工前——状态自检**（`cbb-local-mode` 的 `check-local-state.js`）：干净态零交互直接开工；**遗留态（别的需求未收尾，任一仓库检出在非主干分支）必须让用户四选一**（继续 / 先收尾 / 升级 worktree / 丢弃），不得自行决定
+2. **开工时——布局确认**：向用户展示参与仓库与分支名，确认后执行
+3. **进行中——插单归属**：用户插入非本需求的改动，先确认归属（并入 / 收尾后处理 / 转 worktree），不得静默混入
+4. **打包前——主干对齐**（任何构建打包动作前）：对产物所涉及的仓库（按代码来源判定：哪个仓库的代码被编进产物就同步哪个，与产物存放位置无关；多仓聚合产物则全部同步）先对齐再打包——① `git fetch <远端>`；② 在当前需求分支执行 `git merge <远端>/<主干>`（远端通常为 `origin`，主干名以远端 HEAD 为准，常见 main / master；在 main 检出上打包时改为 `git pull`；工作区未提交修改阻碍合并时，先提交或暂存再对齐）；③ 冲突未解决时**禁止打包**，停下报告用户；fetch/merge 失败 → 报告并等待用户指示；④ 对齐完成后（由此产生的 merge 提交属正常）再执行打包命令（`mvn package` / `npm run build` / 前端 bundle / 生成部署包等凡产出构建产物者）；产物目录须已被 `.gitignore` 忽略（未忽略先补 ignore——该修改属普通变更，随需求分支提交）。产物基线 = 主干最新，避免基于过时分支打包导致的集成返工；**不 rebase、不 force push**，merge 提交随下次 push 一并推送
+5. **打包后——产物收集与留存**：打包完成后把各仓库产物**复制**到 `<空间根>/.build/<需求名>/<应用名>/`（原件保持原位；需求名 = 分支名；workspace 仓库产物用 `workspace` 子目录；目标目录已存在时先向用户确认清理或覆盖；`.build/` 由 cbb 写入空间根 `.gitignore`）——产物按需求聚合留存，worktree 关闭后不丢失；打包时顺带报告 `.build/` 积压现状（需求目录数与总体积），建议清理已交付或已废弃需求的产物目录，经用户逐项确认后执行、**永不自动删除**
+
+**读基准代码约定：** 本地模式进行中，工作区是开发态而非基准——要读"main 现状"先确认检出分支，或直接 `git show main:<path>` / `git diff main`；不要默认工作区即基准。
+
+**检验标准：** 任何 main 检出上无载荷提交（hook 兜底，git log 可机械审计；merge 提交除外）；本地模式收尾后全部仓库回主干且 clean；worktree 模式的**变更（代码改动）**只出现在需求工作树内（打包产物按第 5 条收集到空间根 `.build/`，不在此限）；需求分支只经 push 技能产生；**未合并且非废弃的分支无法通过收尾（门禁兜底）**。

package/cbb/lib/external/index.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * External 小型外部依赖管理模块
+ *
+ * 管理顶层 external/ 目录下的零散第三方依赖（当前为 frontend-design skill，
+ * 来源 anthropics/skills）。与 superpowers / openspec 的整仓 pin 不同，
+ * 这里是「一依赖一目录、pin 文件放依赖自己的子目录内」的轻量形态：
+ *
+ *   external/<dep-name>/
+ *   ├── .version        # pin：{ repo, ref(commit sha), path(tarball 内子路径), updatedAt }
+ *   └── ...             # 上游 path 子目录的内容（如 SKILL.md + LICENSE.txt）
+ *
+ * 新增外部依赖 = 在 external/ 下新建子目录并写入 .version，无需改本模块。
+ *
+ * 网络：GitHub 直连可能被墙 / 被本机 DNS 劫持，走 config/upstream-mirrors.json
+ * 的 'external' 镜像前缀列表（按顺序尝试，首个成功即用；空字符串 = 直连）。
+ *
+ * 升级方式：cbbm update --upstream-external [name]（按 .version 的 ref 幂等重拉，省略 name = 全部）
+ * 版本检查：cbbm check-upstream（对比 pinned sha 与上游 main 该 path 的最新提交）
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+
+// External 依赖根目录
+const EXTERNAL_DIR = path.join(SHARED_STANDARDS_DIR, 'external');
+const VERSION_FILE_NAME = '.version';
+// skill 型依赖的完整性标记（上游 path 内容含 SKILL.md 时以其校验完整性）
+const SKILL_MARKER = 'SKILL.md';
+
+const { log } = require('../utils/output');
+const { extractTarGz } = require('../utils/tar');
+const { loadMirrors, fetchWithMirrors } = require('../utils/upstream');
+
+// ── 依赖发现与 pin 读取 ──────────────────────────────────────
+
+/**
+ * 读取依赖目录内的 .version pin。字段不全 / JSON 损坏 / 文件缺失返回 null。
+ * @param {string} dir
+ * @returns {{repo: string, ref: string, path: string, updatedAt?: string}|null}
+ */
+function readPin(dir) {
+  const file = path.join(dir, VERSION_FILE_NAME);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!data || typeof data.repo !== 'string' || !data.repo.includes('/') ||
+        typeof data.ref !== 'string' || !data.ref ||
+        typeof data.path !== 'string' || !data.path) {
+      return null;
+    }
+    return data;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 扫描 external/ 下各依赖子目录，返回全部依赖（pin 无效的目录跳过并告警）。
+ * @returns {Array<{name: string, dir: string, pin: object}>}
+ */
+function listDeps() {
+  if (!fs.existsSync(EXTERNAL_DIR)) return [];
+  const deps = [];
+  for (const entry of fs.readdirSync(EXTERNAL_DIR)) {
+    const dir = path.join(EXTERNAL_DIR, entry);
+    if (!fs.statSync(dir).isDirectory()) continue;
+    const pin = readPin(dir);
+    if (!pin) {
+      log(`external/${entry}: 缺少有效 .version pin（{ repo, ref, path }），跳过`, 'warn');
+      continue;
+    }
+    deps.push({ name: entry, dir, pin });
+  }
+  return deps;
+}
+
+/**
+ * 依赖内容完整性：skill 型（上游含 SKILL.md）要求本地 SKILL.md 存在；
+ * 其余类型要求除 .version 外至少有一个条目。
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function validateDepDir(dir) {
+  if (!fs.existsSync(dir)) return false;
+  if (fs.existsSync(path.join(dir, SKILL_MARKER))) return true;
+  return fs.readdirSync(dir).some(f => f !== VERSION_FILE_NAME);
+}
+
+// ── 上游拉取 ──────────────────────────────────────────────────
+
+/** tarball 下载地址（按镜像前缀拼接；ref = commit sha，上游无 skill 粒度 tag） */
+function tarballUrl(mirror, pin) {
+  return `${mirror}https://api.github.com/repos/${pin.repo}/tarball/${pin.ref}`;
+}
+
+/**
+ * 按 .version 的 ref 下载 tarball，解压出 pin.path 子目录，内容覆盖到 external/<name>/。
+ * 幂等：pin 一致且内容完整 → 跳过重拉。.version 由本模块改写，不被上游内容覆盖。
+ * @param {string[]} [names] - 指定依赖名；省略 = 全部
+ * @returns {Promise<Array<{name: string, ref: string, skipped: boolean, error?: string}>>}
+ */
+async function fetchDeps(names) {
+  const all = listDeps();
+  let deps = all;
+  if (names && names.length > 0) {
+    const known = new Set(all.map(d => d.name));
+    const unknown = names.filter(n => !known.has(n));
+    if (unknown.length > 0) {
+      throw new Error(`未知的 external 依赖: ${unknown.join(', ')}（现有: ${[...known].join(', ') || '无'}）`);
+    }
+    deps = all.filter(d => names.includes(d.name));
+  }
+
+  const results = [];
+  for (const dep of deps) {
+    try {
+      results.push(await fetchDep(dep));
+    } catch (err) {
+      results.push({ name: dep.name, ref: dep.pin.ref, skipped: false, error: err.message });
+    }
+  }
+  return results;
+}
+
+/**
+ * 拉取单个依赖。
+ * @param {{name: string, dir: string, pin: object}} dep
+ * @returns {Promise<{name: string, ref: string, skipped: boolean}>}
+ */
+async function fetchDep(dep) {
+  const { name, dir, pin } = dep;
+
+  // pin 一致且内容完整 → 幂等跳过
+  if (validateDepDir(dir)) {
+    log(`external/${name} 已按 pin ${pin.ref.slice(0, 12)} 就位，跳过重拉`, 'success');
+    return { name, ref: pin.ref, skipped: true };
+  }
+  log(`external/${name} 内容不完整，按 pin ${pin.ref.slice(0, 12)} 拉取...`, 'info');
+
+  const mirrors = loadMirrors('external');
+  log(`正在获取 ${pin.repo}@${pin.ref.slice(0, 12)}（${mirrors.map(m => m || '直连').join(' → ')}）...`, 'info');
+  const { buffer, mirror } = await fetchWithMirrors(mirrors, m => tarballUrl(m, pin));
+  log(`已从 ${mirror || '(直连)'} 下载 ${(buffer.length / 1024).toFixed(0)} KB`, 'info');
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cbb-ext-'));
+  try {
+    extractTarGz(buffer, tmpDir);
+
+    // GitHub tarball 顶层目录名格式：<owner>-<repo>-<short-sha>
+    const topPrefix = `${pin.repo.replace('/', '-')}-`;
+    const tops = fs.readdirSync(tmpDir).filter(f => {
+      const p = path.join(tmpDir, f);
+      return fs.statSync(p).isDirectory() && f.startsWith(topPrefix);
+    });
+    if (tops.length === 0) throw new Error(`解压后未找到 ${topPrefix}* 目录`);
+
+    // pin.path 是 tarball 内相对仓库根的子路径（如 skills/frontend-design）
+    const source = path.join(tmpDir, tops[0], pin.path);
+    if (!fs.existsSync(source)) {
+      throw new Error(`上游 ${pin.repo}@${pin.ref.slice(0, 12)} 中不存在路径 ${pin.path}（ref 或 path 配置有误）`);
+    }
+
+    // 覆盖内容到 external/<name>/（cpSync 合并，.version 保留）
+    fs.cpSync(source, dir, { recursive: true });
+    if (!validateDepDir(dir)) throw new Error('拉取后完整性校验未通过');
+
+    // 刷新 pin 时间戳（ref 不变）
+    fs.writeFileSync(
+      path.join(dir, VERSION_FILE_NAME),
+      JSON.stringify({ ...pin, updatedAt: new Date().toISOString() }, null, 2) + '\n'
+    );
+
+    log(`external/${name} 已更新: ${pin.repo}@${pin.ref.slice(0, 12)}`, 'success');
+    return { name, ref: pin.ref, skipped: false };
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+}
+
+/**
+ * 检查全部依赖上游是否有新提交（只读，不改动任何文件）。
+ * 对比 pinned sha 与上游 main 分支 pin.path 的最新提交 sha
+ * （commits?path= 只统计该子路径的变更，仓库其他目录的提交不告警）。
+ * 单依赖失败不阻塞其他依赖（返回 {name, error} 条目）。
+ * @returns {Promise<Array<{name: string, current: string, latest: string, outdated: boolean}|{name: string, error: string}>>}
+ */
+async function checkUpstream() {
+  const deps = listDeps();
+  const results = await Promise.allSettled(deps.map(async dep => {
+    const mirrors = loadMirrors('external');
+    const { buffer } = await fetchWithMirrors(mirrors, m =>
+      `${m}https://api.github.com/repos/${dep.pin.repo}/commits?path=${encodeURIComponent(dep.pin.path)}&sha=main&per_page=1`
+    );
+    const data = JSON.parse(buffer.toString('utf-8'));
+    const latest = Array.isArray(data) && data[0] ? data[0].sha : null;
+    return {
+      name: dep.name,
+      current: dep.pin.ref,
+      latest,
+      outdated: Boolean(latest && latest !== dep.pin.ref),
+    };
+  }));
+  return results.map((r, i) => r.status === 'fulfilled'
+    ? r.value
+    : { name: deps[i].name, error: r.reason.message });
+}
+
+// ── 导出 ──────────────────────────────────────────────────────
+
+module.exports = {
+  // 常量
+  EXTERNAL_DIR,
+  VERSION_FILE_NAME,
+  SKILL_MARKER,
+
+  // 核心函数
+  listDeps,
+  readPin,
+  validateDepDir,
+  fetchDeps,
+  checkUpstream,
+  tarballUrl,
+};

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）；旧记录中的遗留内容
+ * 不在勾选范围时随清单差集与用户级差集清理移除（ADR 0006）。
+ * 恢复入口：删掉 selectable 即可重新出现在面板（决策：不留参数开关）。
  */
 
 const path = require('path');
@@ -13,8 +18,10 @@ module.exports = {
   rulesDir: '.claude/rules',
   skillsDir: '.claude/skills',
   commandsDir: '.claude/commands/opsx',
-  // 用户级 settings，写入全局生效，不污染项目目录
+  // 用户级 settings，写入全局生效，不污染项目目录
   settingsFile: path.join(os.homedir(), '.claude', 'settings.json'),
   settingsFileIsUserLevel: true,
   hookEvents: ['UserPromptSubmit'],
+  // 退市：不在安装面板提供（代码保留；旧记录遗留随清单/用户级差集清理，ADR 0006）
+  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 };