@jspg-ai/coding-bb 0.0.3-beta.1 → 0.0.3-beta.13

package/cbb/lib/openspec/index.js

@@ -1,554 +1,337 @@
-#!/usr/bin/env node
-
-/**
- * OpenSpec 工作流管理模块
- *
- * 负责从 GitHub (Fission-AI/OpenSpec) 拉取官方 workflow 模板,
- * 渲染并部署到本项目的 openspec/{commands,skills} 目录。
- * 提供 `cbbm update --upstream-openspec` 选项。
- *
- * 升级范围严格限定:只有 WORKFLOWS 白名单中的 commands/*.md 和
- * skills/<workflow>/SKILL.md 会被覆盖写入。config/openspec/（schemas + config.yaml）、
- * cbb/worktrees/ 等项目自有扩展位不会被触碰 —— 由 assertSafeDestination
- * 兜底拦截,任何写入命中受保护前缀都会抛错退出。
- */
-
-const fs = require('fs');
-const path = require('path');
-const https = require('https');
-const os = require('os');
-const zlib = require('zlib');
-
-const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
-
-// 部署目标根目录
-const OPENSPEC_DIR = path.join(SHARED_STANDARDS_DIR, 'openspec');
-const OPENSPEC_COMMANDS_DIR = path.join(OPENSPEC_DIR, 'commands');
-const OPENSPEC_SKILLS_DIR = path.join(OPENSPEC_DIR, 'skills');
-
-// 版本文件(commit SHA)
-const VERSION_FILE = path.join(OPENSPEC_DIR, '.version');
-
-// GitHub 配置
-const GITHUB_REPO = 'Fission-AI/OpenSpec';
-const GITHUB_BRANCH = 'main';
-// 使用 codeload (不走 API,无速率限制) 与 git ls-remote (拉 SHA,无速率限制)
-const GITHUB_TARBALL_URL = `https://codeload.github.com/${GITHUB_REPO}/tar.gz/refs/heads/${GITHUB_BRANCH}`;
-const GITHUB_GIT_URL = `https://github.com/${GITHUB_REPO}.git`;
-
-// 升级白名单:每个工作流的源文件名 → 命令文件名 + skill 目录名
-// 部署 strategy:
-//   - cmd 不为空 → 写入 commands/<cmd>.md
-//   - skill 不为空 → 写入 skills/<skill>/SKILL.md
-const WORKFLOWS = [
-  { name: 'propose',            cmd: 'propose',       skill: 'openspec-propose' },
-  { name: 'apply-change',       cmd: 'apply',         skill: 'openspec-apply-change' },
-  { name: 'archive-change',     cmd: 'archive',       skill: 'openspec-archive-change' },
-  { name: 'verify-change',      cmd: 'verify',        skill: 'openspec-verify-change' },
-  { name: 'ff-change',          cmd: 'ff',            skill: 'openspec-ff-change' },
-  { name: 'continue-change',    cmd: 'continue',      skill: 'openspec-continue-change' },
-  { name: 'new-change',         cmd: 'new',           skill: 'openspec-new-change' },
-  { name: 'explore',            cmd: 'explore',       skill: 'openspec-explore' },
-  { name: 'update-change',      cmd: 'update',        skill: 'openspec-update-change' },
-  { name: 'sync-specs',         cmd: 'sync',          skill: 'openspec-sync-specs' },
-  { name: 'bulk-archive-change',cmd: 'bulk-archive',  skill: 'openspec-bulk-archive-change' },
-  { name: 'onboard',            cmd: 'onboard',       skill: 'openspec-onboard' },
-];
-
-// ── 受保护路径（项目自有扩展位,绝对禁止覆盖写入）─────────────
-//
-// 与 AGENTS.md「原生内容保护与扩展位」一致:
-// - config/openspec/schemas/     项目自托管 schema 与模板（spec-driven）
-// - cbb/worktrees/              项目自有扩展(worktree 命令/技能/_shared)
-// - config/openspec/config.yaml 项目自托管
-//
-// 任何写入命中下列任一前缀,assertSafeDestination 立即抛错,
-// 避免后续重构意外把 schema.yaml / config.yaml / worktrees/ 冲掉。
-const PROTECTED_PATH_PREFIXES = [
-  path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
-  path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees'),
-  path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'config.yaml'),
-];
-
-function assertSafeDestination(destPath, op) {
-  const abs = path.resolve(destPath);
-  for (const prefix of PROTECTED_PATH_PREFIXES) {
-    if (abs === prefix || abs.startsWith(prefix + path.sep)) {
-      throw new Error(
-        `[cbbm update --upstream-openspec] ${op} 试图写入受保护路径: ${abs}\n` +
-        `命中前缀: ${prefix}\n` +
-        `该路径属于项目自有扩展位,绝对禁止被 cbbm update --upstream-openspec 覆盖。\n` +
-        `详见 AGENTS.md「原生内容保护与扩展位」一节。`
-      );
-    }
-  }
-}
-
-// 与 lib/install/init.js 共用输出辅助
-const { log } = require('../utils/output');
-
-// 嵌入的 STORE_SELECTION_GUIDANCE (来自 Fission-AI/OpenSpec store-selection.ts)
-// 用于替换官方 TS 模板中的 ${STORE_SELECTION_GUIDANCE} 占位符
-const STORE_SELECTION_GUIDANCE_TEXT =
-  '**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.';
-
-// ── HTTP 工具 ──────────────────────────────────────────────────
-
-function httpsGet(url, headers = {}, redirectCount = 0) {
-  if (redirectCount > 5) throw new Error('Too many redirects');
-
-  return new Promise((resolve, reject) => {
-    const defaultHeaders = { 'User-Agent': 'cbb-cli' };
-    https.get(url, { headers: { ...defaultHeaders, ...headers } }, (res) => {
-      if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
-        res.resume();
-        return httpsGet(res.headers.location, headers, redirectCount + 1)
-          .then(resolve, reject);
-      }
-
-      const chunks = [];
-      res.on('data', chunk => chunks.push(chunk));
-      res.on('end', () => {
-        resolve({
-          statusCode: res.statusCode,
-          headers: res.headers,
-          body: Buffer.concat(chunks),
-        });
-      });
-      res.on('error', reject);
-    }).on('error', reject);
-  });
-}
-
-async function downloadToFile(url, destPath) {
-  const res = await httpsGet(url);
-  if (res.statusCode !== 200) {
-    throw new Error(`HTTP ${res.statusCode}: ${url}`);
-  }
-  fs.mkdirSync(path.dirname(destPath), { recursive: true });
-  fs.writeFileSync(destPath, res.body);
-  return res;
-}
-
-/**
- * HEAD 请求拿 ETag,用于无 API 限速的版本比对。
- * codeload 对同一 ref 的 tarball 返回稳定 ETag;上游变更即变化。
- */
-async function fetchEtag(url) {
-  return new Promise((resolve, reject) => {
-    const req = https.request(url, { method: 'HEAD', headers: { 'User-Agent': 'cbb-cli' } }, (res) => {
-      const etag = (res.headers.etag || '').replace(/^W\//, '').replace(/^"|"$/g, '');
-      res.resume();
-      res.on('end', () => resolve({ statusCode: res.statusCode, etag }));
-    });
-    req.on('error', reject);
-    req.end();
-  });
-}
-
-// ── tar.gz 解压 ──────────────────────────────────────────────────
-
-/**
- * 跨平台 .tar.gz 解压,用 zlib + 手写 tar parser,避开 OS shell tar。
- * 支持路径嵌套目录创建,跳过权限/所有者字段。
- */
-function extractTarGz(tarGzPath, destDir) {
-  const compressed = fs.readFileSync(tarGzPath);
-  const data = zlib.gunzipSync(compressed);
-
-  let off = 0;
-  while (off + 512 <= data.length) {
-    const header = data.subarray(off, off + 512);
-    off += 512;
-
-    // 空块 = 连续两个 512-byte 零 = tar 终止
-    if (header.every(b => b === 0)) break;
-
-    // 文件名在 header[0..100] (NUL 终止)
-    let nameEnd = 0;
-    while (nameEnd < 100 && header[nameEnd] !== 0) nameEnd++;
-    const name = header.subarray(0, nameEnd).toString('utf-8');
-
-    // 文件大小在 header[124..136] (octal ASCII)
-    const sizeStr = header.subarray(124, 136).toString('utf-8').trim();
-    const size = parseInt(sizeStr, 8) || 0;
-
-    const target = path.join(destDir, name);
-    if (name.endsWith('/')) {
-      fs.mkdirSync(target, { recursive: true });
-    } else {
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, data.subarray(off, off + size));
-    }
-
-    // 数据按 512 字节对齐
-    off += Math.ceil(size / 512) * 512;
-  }
-}
-
-// ── 版本管理 ──────────────────────────────────────────────────
-
-function getLocalVersion() {
-  if (!fs.existsSync(VERSION_FILE)) return null;
-  try {
-    const content = fs.readFileSync(VERSION_FILE, 'utf-8').trim();
-    if (content.startsWith('{')) {
-      const data = JSON.parse(content);
-      return data.sha || null;
-    }
-    return content || null;
-  } catch (_) {
-    return null;
-  }
-}
-
-function writeVersion(sha) {
-  const data = {
-    sha,
-    branch: GITHUB_BRANCH,
-    repo: GITHUB_REPO,
-    updatedAt: new Date().toISOString(),
-  };
-  fs.writeFileSync(VERSION_FILE, JSON.stringify(data, null, 2) + '\n');
-}
-
-// ── 渲染:从 *.ts 文件中提取 template literal 并替换占位符 ──
-
-/**
- * 反转义 TS 模板字符串中典型的转义:
- *   \`  → `   (反引号)
- *   \$  → $   (美元符,常用于 \${\w} 形式防止被当作插值)
- *   \\  → \   (反斜杠本身)
- */
-function unescapeTsTemplate(s) {
-  return s
-    .replace(/\\`/g, '`')
-    .replace(/\\\$/g, '$')
-    .replace(/\\\\/g, '\\');
-}
-
-/**
- * 将模板字符串中的 ${STORE_SELECTION_GUIDANCE} 替换为实际内容。
- * 上游 store-selection.ts 是常量,我们直接内嵌字符串,避免运行时求值。
- */
-function substituteStoreGuidance(s) {
-  return s.split('${STORE_SELECTION_GUIDANCE}').join(STORE_SELECTION_GUIDANCE_TEXT);
-}
-
-/**
- * 从 TS 源码中提取 SkillTemplate 函数体内的字段,并渲染成 SKILL.md。
- * @param {string} tsContent - 整个 .ts 文件内容
- * @param {string} functionName - 例如 'getProposeSkillTemplate' / 'getApplyChangeSkillTemplate'
- * @returns {string|null} 渲染出的 SKILL.md 完整内容,若提取失败返回 null
- */
-function renderSkillFromTs(tsContent, functionName) {
-  // 匹配 functionName(...): SkillTemplate { return { ... }; }
-  const fnRegex = new RegExp(
-    `function\\s+${functionName}\\s*\\(\\)\\s*:\\s*SkillTemplate\\s*\\{[\\s\\S]*?return\\s*\\{([\\s\\S]*?)\\}\\s*;\\s*\\}`,
-    'm'
-  );
-  const fnMatch = tsContent.match(fnRegex);
-  if (!fnMatch) return null;
-  const fields = fnMatch[1];
-
-  // 提取 name (单引号字符串)
-  const nameMatch = fields.match(/name:\s*'([^']+)'/);
-  const name = nameMatch ? nameMatch[1] : '';
-
-  // 提取 description (单引号字符串)
-  const descMatch = fields.match(/description:\s*'([\s\S]*?)',\s*\n\s*instructions/);
-  const description = descMatch ? descMatch[1].trim() : '';
-
-  // 提取 instructions (backtick 模板字符串,以 `\n    license:` 为锚点)
-  let instMatch = fields.match(/instructions:\s*`([\s\S]*?)`,\s*\n\s*license/);
-  if (!instMatch) {
-    // 兜底: instructions 可能是函数调用,如 instructions: getOnboardInstructions(),
-    const fnCallMatch = fields.match(/instructions:\s*(\w+)\(\)/);
-    if (fnCallMatch) {
-      const helperFnName = fnCallMatch[1];
-      const helperFnRegex = new RegExp(
-        `function\\s+${helperFnName}\\s*\\([^)]*\\)\\s*:\\s*string\\s*\\{[\\s\\S]*?return\\s*\`([\\s\\S]*?)\`\\s*;\\s*\\}`,
-        'm'
-      );
-      const helperMatch = tsContent.match(helperFnRegex);
-      if (helperMatch) {
-        instMatch = [null, helperMatch[1]];
-      }
-    }
-  }
-  if (!instMatch) return null;
-  let instructions = unescapeTsTemplate(substituteStoreGuidance(instMatch[1]));
-  // 去掉开头/结尾的多余换行
-  instructions = instructions.replace(/^\n+/, '').replace(/\n+$/, '') + '\n';
-
-  // 提取 license / compatibility / metadata
-  const licenseMatch = fields.match(/license:\s*'([^']+)'/);
-  const license = licenseMatch ? licenseMatch[1] : 'MIT';
-  const compatMatch = fields.match(/compatibility:\s*'([^']+)'/);
-  const compatibility = compatMatch ? compatMatch[1] : 'Requires openspec CLI.';
-  const metaMatch = fields.match(/metadata:\s*\{\s*author:\s*'([^']+)',\s*version:\s*'([^']+)'/);
-  const metaAuthor = metaMatch ? metaMatch[1] : 'openspec';
-  const metaVersion = metaMatch ? metaMatch[2] : '1.0';
-
-  // 构造 frontmatter (YAML)
-  const fm = [
-    '---',
-    `name: ${name}`,
-    `description: ${description}`,
-    `license: ${license}`,
-    `compatibility: ${compatibility}`,
-    'metadata:',
-    `  author: ${metaAuthor}`,
-    `  version: "${metaVersion}"`,
-    `  generatedBy: "1.6.0"`,
-    '---',
-    '',
-  ].join('\n');
-
-  return fm + instructions;
-}
-
-/**
- * 从 TS 源码中提取 CommandTemplate 函数体内的 content,并渲染成 .md。
- * @param {string} tsContent
- * @param {string} functionName - 例如 'getOpsxProposeCommandTemplate'
- * @returns {string|null}
- */
-function renderCommandFromTs(tsContent, functionName) {
-  const fnRegex = new RegExp(
-    `function\\s+${functionName}\\s*\\(\\)\\s*:\\s*CommandTemplate\\s*\\{[\\s\\S]*?return\\s*\\{([\\s\\S]*?)\\}\\s*;\\s*\\}`,
-    'm'
-  );
-  const fnMatch = tsContent.match(fnRegex);
-  if (!fnMatch) return null;
-  const fields = fnMatch[1];
-
-  // 提取 description (单引号字符串)
-  const descMatch = fields.match(/description:\s*'([\s\S]*?)',\s*\n\s*category/);
-  const description = descMatch ? descMatch[1].trim() : '';
-
-  // 提取 category / tags
-  const catMatch = fields.match(/category:\s*'([^']+)'/);
-  const category = catMatch ? catMatch[1] : 'Workflow';
-  const tagsMatch = fields.match(/tags:\s*\[([^\]]+)\]/);
-  let tags = '[]';
-  if (tagsMatch) {
-    const tagList = tagsMatch[1]
-      .split(',')
-      .map(t => t.trim().replace(/^['"]|['"]$/g, ''))
-      .filter(Boolean);
-    tags = '[' + tagList.join(', ') + ']';
-  }
-
-  // 提取 content (backtick 模板字符串;content 是 CommandTemplate 的最末字段,
-  // 所以以字符串结尾 `$` 作为锚点即可,不带 /m 标志)
-  let contentMatch = fields.match(/content:\s*`([\s\S]*?)`\s*$/);
-  if (!contentMatch) {
-    // 兜底: content 可能是函数调用,如 content: getOnboardInstructions(),
-    const fnCallMatch = fields.match(/content:\s*(\w+)\(\)/);
-    if (fnCallMatch) {
-      const helperFnName = fnCallMatch[1];
-      const helperFnRegex = new RegExp(
-        `function\\s+${helperFnName}\\s*\\([^)]*\\)\\s*:\\s*string\\s*\\{[\\s\\S]*?return\\s*\`([\\s\\S]*?)\`\\s*;\\s*\\}`,
-        'm'
-      );
-      const helperMatch = tsContent.match(helperFnRegex);
-      if (helperMatch) {
-        contentMatch = [null, helperMatch[1]];
-      }
-    }
-  }
-  if (!contentMatch) return null;
-  let content = unescapeTsTemplate(substituteStoreGuidance(contentMatch[1]));
-  content = content.replace(/^\n+/, '').replace(/\n+$/, '') + '\n';
-
-  // 派生 name: 'OPSX: <Title>' 来自 description 的若干词
-  // 实际从 CommandTemplate.name 字段读取
-  const nameMatch = fields.match(/name:\s*'([^']+)'/);
-  const name = nameMatch ? nameMatch[1] : `OPSX: ${description.split(/[.,:!?]/)[0].slice(0, 24)}`;
-
-  const fm = [
-    '---',
-    `name: "${name}"`,
-    `description: ${description}`,
-    `category: ${category}`,
-    `tags: ${tags}`,
-    '---',
-    '',
-  ].join('\n');
-
-  return fm + content;
-}
-
-/**
- * 把 workflow 名映射到它对应的 TS 函数名。
- * 例如 'propose' → getOpsxProposeCommandTemplate / getOpsxProposeSkillTemplate
- */
-function functionNamesForWorkflow(name, kind /* 'cmd' | 'skill' */) {
-  // 所有官方 cmd 函数都以 getOpsx 开头,skill 以 get 开头,Workflow 名驼峰式接续
-  // 我们手动列出(因为没法从文件名可靠推导)
-  const map = {
-    'propose':            { cmd: 'getOpsxProposeCommandTemplate',            skill: 'getOpsxProposeSkillTemplate' },
-    'apply-change':       { cmd: 'getOpsxApplyCommandTemplate',             skill: 'getApplyChangeSkillTemplate' },
-    'archive-change':     { cmd: 'getOpsxArchiveCommandTemplate',           skill: 'getArchiveChangeSkillTemplate' },
-    'verify-change':      { cmd: 'getOpsxVerifyCommandTemplate',            skill: 'getVerifyChangeSkillTemplate' },
-    'ff-change':          { cmd: 'getOpsxFfCommandTemplate',                skill: 'getFfChangeSkillTemplate' },
-    'continue-change':    { cmd: 'getOpsxContinueCommandTemplate',          skill: 'getContinueChangeSkillTemplate' },
-    'new-change':         { cmd: 'getOpsxNewCommandTemplate',               skill: 'getNewChangeSkillTemplate' },
-    'explore':            { cmd: 'getOpsxExploreCommandTemplate',           skill: 'getExploreSkillTemplate' },
-    'update-change':      { cmd: 'getOpsxUpdateCommandTemplate',            skill: 'getUpdateChangeSkillTemplate' },
-    'sync-specs':         { cmd: 'getOpsxSyncCommandTemplate',              skill: 'getSyncSpecsSkillTemplate' },
-    'bulk-archive-change':{ cmd: 'getOpsxBulkArchiveCommandTemplate',       skill: 'getBulkArchiveChangeSkillTemplate' },
-    'onboard':            { cmd: 'getOpsxOnboardCommandTemplate',           skill: 'getOnboardSkillTemplate' },
-  };
-  return map[name] ? map[name][kind] : null;
-}
-
-// ── 下载与部署 ──────────────────────────────────────────────────
-
-async function fetchLatestOpenSpec() {
-  log(`正在获取 OpenSpec 版本元数据...`, 'info');
-  // 1) 先 HEAD 拿 ETag,避免每次都下载完整 tarball
-  const head = await fetchEtag(GITHUB_TARBALL_URL);
-  if (head.statusCode !== 200 || !head.etag) {
-    throw new Error(`无法获取版本信息: HTTP ${head.statusCode}`);
-  }
-  const versionToken = head.etag;
-  const localToken = getLocalVersion();
-
-  if (versionToken === localToken) {
-    // 即使版本号一致,也要校验全部文件是否已部署(白名单可能新增了条目)
-    const { valid } = validateDeployed();
-    if (valid) {
-      log(`已是最新版本 (${versionToken.slice(0, 12)})`, 'success');
-      return { version: versionToken, cmdCount: 0, skillCount: 0, skipped: true };
-    }
-    log(`版本一致但文件不完整,强制重新部署...`, 'info');
-  }
-
-  log(`检测到上游更新,正在下载 OpenSpec tarball...`, 'info');
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cbb-os-'));
-  const tarballPath = path.join(tmpDir, 'openspec.tar.gz');
-
-  try {
-    await downloadToFile(GITHUB_TARBALL_URL, tarballPath);
-    log('正在解压...', 'info');
-    // 跨平台解压:用 zlib + 自写 tar parser。无需 shell tar,Windows 也能跑。
-    extractTarGz(tarballPath, tmpDir);
-
-    // 通过「含 src/core/templates/workflows」特征定位真仓库根。
-    // codeload 的 tarball 顶层可能是 pax_global_header / 杂项,但
-    // 真正的源码根目录固定有一个 src/ 子树。这种探测比依赖目录名约定稳。
-    let extractedDir = null;
-    for (const entry of fs.readdirSync(tmpDir)) {
-      const cand = path.join(tmpDir, entry);
-      let isDir = false;
-      try { isDir = fs.statSync(cand).isDirectory(); } catch (_) { continue; }
-      if (!isDir) continue;
-      const probe = path.join(cand, 'src', 'core', 'templates', 'workflows');
-      if (fs.existsSync(probe)) {
-        extractedDir = cand;
-        break;
-      }
-    }
-    if (!extractedDir) {
-      throw new Error('解压后未在 tarball 中定位到含 src/core/templates/workflows 的 OpenSpec 根目录');
-    }
-
-    const workflowsDir = path.join(extractedDir, 'src', 'core', 'templates', 'workflows');
-    if (!fs.existsSync(workflowsDir)) throw new Error('未找到 workflows 目录');
-
-    let cmdCount = 0;
-    let skillCount = 0;
-
-    for (const wf of WORKFLOWS) {
-      const tsFile = path.join(workflowsDir, `${wf.name}.ts`);
-      if (!fs.existsSync(tsFile)) {
-        log(`跳过 ${wf.name}: 官方源无对应文件`, 'warn');
-        continue;
-      }
-      const tsContent = fs.readFileSync(tsFile, 'utf-8');
-
-      // 命令
-      if (wf.cmd) {
-        const fnName = functionNamesForWorkflow(wf.name, 'cmd');
-        const rendered = fnName ? renderCommandFromTs(tsContent, fnName) : null;
-        if (!rendered) {
-          log(`${wf.name}.ts: 未提取到 CommandTemplate,跳过`, 'warn');
-        } else {
-          const dest = path.join(OPENSPEC_COMMANDS_DIR, `${wf.cmd}.md`);
-          assertSafeDestination(dest, `写入命令 ${wf.name}`);
-          fs.mkdirSync(path.dirname(dest), { recursive: true });
-          fs.writeFileSync(dest, rendered);
-          cmdCount++;
-        }
-      }
-
-      // 技能
-      if (wf.skill) {
-        const fnName = functionNamesForWorkflow(wf.name, 'skill');
-        const rendered = fnName ? renderSkillFromTs(tsContent, fnName) : null;
-        if (!rendered) {
-          log(`${wf.name}.ts: 未提取到 SkillTemplate,跳过`, 'warn');
-        } else {
-          const dest = path.join(OPENSPEC_SKILLS_DIR, wf.skill, 'SKILL.md');
-          assertSafeDestination(dest, `写入技能 ${wf.name}`);
-          fs.mkdirSync(path.dirname(dest), { recursive: true });
-          fs.writeFileSync(dest, rendered);
-          skillCount++;
-        }
-      }
-    }
-
-    writeVersion(versionToken);
-    log(
-      `已更新 OpenSpec 工作流: ${localToken ? localToken.slice(0, 12) : '(无)'} → ${versionToken.slice(0, 12)} ` +
-      `(${cmdCount} 个命令 + ${skillCount} 个技能)`,
-      'success'
-    );
-
-    return { version: versionToken, cmdCount, skillCount, skipped: false };
-  } catch (err) {
-    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
-    throw err;
-  }
-}
-
-// ── 完整性校验 ──────────────────────────────────────────────────
-
-/**
- * 校验 Safe-Overwrite 区的所有文件均已部署。
- * @returns {{valid: boolean, missing: string[]}}
- */
-function validateDeployed() {
-  const missing = [];
-  for (const wf of WORKFLOWS) {
-    if (wf.cmd) {
-      const p = path.join(OPENSPEC_COMMANDS_DIR, `${wf.cmd}.md`);
-      if (!fs.existsSync(p)) missing.push(`commands/${wf.cmd}.md`);
-    }
-    if (wf.skill) {
-      const p = path.join(OPENSPEC_SKILLS_DIR, wf.skill, 'SKILL.md');
-      if (!fs.existsSync(p)) missing.push(`skills/${wf.skill}/SKILL.md`);
-    }
-  }
-  return { valid: missing.length === 0, missing };
-}
-
-// ── 导出 ────────────────────────────────────────────────────────
-
-module.exports = {
-  OPENSPEC_DIR,
-  OPENSPEC_COMMANDS_DIR,
-  OPENSPEC_SKILLS_DIR,
-  VERSION_FILE,
-  WORKFLOWS,
-  GITHUB_REPO,
-  GITHUB_BRANCH,
-
-  PROTECTED_PATH_PREFIXES,
-  assertSafeDestination,
-  fetchLatestOpenSpec,
-  getLocalVersion,
-  validateDeployed,
-};
+#!/usr/bin/env node
+
+/**
+ * OpenSpec 工作流管理模块
+ *
+ * 内容来源 = 指定版本的 OpenSpec CLI npm 包（默认 npmmirror，可配置镜像），
+ * 调用该包自带的渲染器产出 canonical 形态的 commands + skills，再由本模块
+ * 套上本仓库的 frontmatter 格式写入 openspec/{commands,skills}/。
+ *
+ * 为什么不再自研 TS 模板解析：上游 1.13.1 起模板引入 PROJECT_ROOT_GUARD、
+ * optionalWorkflow 条件块等新语法，正则解析会持续落后。改用 CLI 自带渲染器后，
+ * 内容与 CLI 版本严格一致，且完全不依赖 GitHub（用户/维护者本机可达 npmmirror）。
+ *
+ * 接缝：用 getSkillTemplates()/getCommandContents()（canonical `/opsx:<id>` 形态），
+ * 不用 CLI 的 generateCommand()（那会按 CLI 自己的适配器格式化）——
+ * 分发格式的唯一决定者仍是本仓库的适配器改写层。
+ *
+ * 升级范围严格限定：只有 WORKFLOWS 白名单中的 commands/*.md 和
+ * skills/<name>/SKILL.md 会被覆盖写入。config/openspec/（schemas + config.yaml）、
+ * cbb/worktrees/ 等项目自有扩展位不会被触碰 —— 由 assertSafeDestination
+ * 兜底拦截，任何写入命中受保护前缀都会抛错退出。
+ *
+ * 升级方式：cbbm update --upstream-openspec（按 .version 的 pin 幂等重渲染）
+ * 版本检查：cbbm check-upstream
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const url = require('url');
+
+const { log } = require('../utils/output');
+const { extractTarGz } = require('../utils/tar');
+const { loadMirrors, fetchWithMirrors } = require('../utils/upstream');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+
+// 部署目标根目录
+const OPENSPEC_DIR = path.join(SHARED_STANDARDS_DIR, 'openspec');
+const OPENSPEC_COMMANDS_DIR = path.join(OPENSPEC_DIR, 'commands');
+const OPENSPEC_SKILLS_DIR = path.join(OPENSPEC_DIR, 'skills');
+
+// 版本锁定文件（pin）
+const VERSION_FILE = path.join(OPENSPEC_DIR, '.version');
+
+// 上游包信息
+const NPM_PKG = '@fission-ai/openspec';
+const NPM_PKG_BASENAME = 'openspec';
+const GITHUB_REPO = 'Fission-AI/OpenSpec';
+
+// 升级白名单：每个工作流的命令文件名 + skill 目录名
+// 用于 validateDeployed（不下载即可校验完整性）与写入目标定位。
+const WORKFLOWS = [
+  { id: 'propose',             cmd: 'propose',       skill: 'openspec-propose' },
+  { id: 'apply',               cmd: 'apply',         skill: 'openspec-apply-change' },
+  { id: 'archive',             cmd: 'archive',       skill: 'openspec-archive-change' },
+  { id: 'verify',              cmd: 'verify',        skill: 'openspec-verify-change' },
+  { id: 'ff',                  cmd: 'ff',            skill: 'openspec-ff-change' },
+  { id: 'continue',            cmd: 'continue',      skill: 'openspec-continue-change' },
+  { id: 'new',                 cmd: 'new',           skill: 'openspec-new-change' },
+  { id: 'explore',             cmd: 'explore',       skill: 'openspec-explore' },
+  { id: 'update',              cmd: 'update',        skill: 'openspec-update-change' },
+  { id: 'sync',                cmd: 'sync',          skill: 'openspec-sync-specs' },
+  { id: 'bulk-archive',        cmd: 'bulk-archive',  skill: 'openspec-bulk-archive-change' },
+  { id: 'onboard',             cmd: 'onboard',       skill: 'openspec-onboard' },
+];
+
+// ── 受保护路径（项目自有扩展位，绝对禁止覆盖写入）─────────────
+//
+// 与 AGENTS.md「原生内容保护与扩展位」一致：
+// - config/openspec/schemas/     项目自托管 schema 与模板（spec-driven）
+// - cbb/worktrees/              项目自有扩展（worktree 命令/技能/_shared）
+// - config/openspec/config.yaml 项目自有
+//
+// 任何写入命中下列任一前缀，assertSafeDestination 立即抛错，
+// 避免后续重构意外把 schema.yaml / config.yaml / worktrees/ 冲掉。
+const PROTECTED_PATH_PREFIXES = [
+  path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
+  path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees'),
+  path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'config.yaml'),
+];
+
+function assertSafeDestination(destPath, op) {
+  const abs = path.resolve(destPath);
+  for (const prefix of PROTECTED_PATH_PREFIXES) {
+    if (abs === prefix || abs.startsWith(prefix + path.sep)) {
+      throw new Error(
+        `[cbbm update --upstream-openspec] ${op} 试图写入受保护路径: ${abs}\n` +
+        `命中前缀: ${prefix}\n` +
+        `该路径属于项目自有扩展位，绝对禁止被 cbbm update --upstream-openspec 覆盖。\n` +
+        `详见 AGENTS.md「原生内容保护与扩展位」一节。`
+      );
+    }
+  }
+}
+
+// ── 版本管理（pin）────────────────────────────────────────────
+
+/**
+ * 读取本地 pin（.version 的 version 字段）。
+ * 兼容旧格式：无 version 时回退 sha（历史 ETag/commit）。
+ * @returns {string|null}
+ */
+function getLocalVersion() {
+  if (!fs.existsSync(VERSION_FILE)) return null;
+  try {
+    const content = fs.readFileSync(VERSION_FILE, 'utf-8').trim();
+    if (content.startsWith('{')) {
+      const data = JSON.parse(content);
+      return data.version || data.sha || null;
+    }
+    return content || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeVersion(version) {
+  const data = {
+    version,
+    repo: GITHUB_REPO,
+    renderedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(VERSION_FILE, JSON.stringify(data, null, 2) + '\n');
+}
+
+// ── 上游拉取 ──────────────────────────────────────────────────
+
+/** npm tarball 下载地址（按镜像前缀拼接） */
+function tarballUrl(mirror, version) {
+  return `${mirror}/${NPM_PKG}/-/${NPM_PKG_BASENAME}-${version}.tgz`;
+}
+
+/** npm registry 元数据地址（用于 check-upstream） */
+function registryUrl(mirror) {
+  return `${mirror}/${NPM_PKG}`;
+}
+
+/**
+ * 下载指定版本的 OpenSpec CLI npm tarball 并解压，返回包根目录。
+ * @param {string} version
+ * @param {string} tmpDir
+ * @returns {Promise<string>} 解压出的 package/ 绝对路径
+ */
+async function downloadCliPackage(version, tmpDir) {
+  const mirrors = loadMirrors('openspec');
+  log(`正在获取 OpenSpec CLI ${version} 包（${mirrors.map(m => m || '直连').join(' → ')}）...`, 'info');
+  const { buffer, mirror } = await fetchWithMirrors(mirrors, m => tarballUrl(m, version));
+  log(`已从 ${mirror || '(直连)'} 下载 ${(buffer.length / 1024).toFixed(0)} KB`, 'info');
+
+  const pkgDir = path.join(tmpDir, 'pkg');
+  fs.mkdirSync(pkgDir, { recursive: true });
+  const { files } = extractTarGz(buffer, pkgDir);
+
+  const extracted = path.join(pkgDir, 'package');
+  if (!fs.existsSync(extracted)) {
+    throw new Error('解压后未找到 package/ 目录');
+  }
+  log(`已解压 ${files} 个文件`, 'info');
+  return extracted;
+}
+
+/**
+ * 加载 CLI 自带渲染器。
+ * @param {string} pkgDir - 解压出的 package/ 目录
+ * @returns {Promise<{getSkillTemplates: Function, getCommandContents: Function, generateSkillContent: Function, version: string}>}
+ */
+async function loadCliRenderer(pkgDir) {
+  const entry = path.join(pkgDir, 'dist', 'core', 'shared', 'skill-generation.js');
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `未找到 CLI 渲染器: ${path.relative(pkgDir, entry)}\n` +
+      `该路径属于 @fission-ai/openspec 的内部结构，上游重构可能导致失效。`
+    );
+  }
+  const mod = await import(url.pathToFileURL(entry).href);
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+
+  for (const fn of ['getSkillTemplates', 'getCommandContents', 'generateSkillContent']) {
+    if (typeof mod[fn] !== 'function') {
+      throw new Error(`CLI 渲染器缺少导出函数 ${fn}（@fission-ai/openspec@${pkgJson.version}）`);
+    }
+  }
+  return { ...mod, version: pkgJson.version };
+}
+
+// ── 渲染：套本仓库的 frontmatter 格式 ─────────────────────────
+
+/**
+ * 生成 YAML 标量：需要引号时用双引号包裹，否则原样输出（与仓库既有风格一致）。
+ */
+function yamlScalar(value) {
+  const s = String(value == null ? '' : value);
+  if (s === '' || /^[\s>|&*!%@`{}[\],#?:-]/.test(s) || /[:#]\s/.test(s) || /["'\\\n\r\t]/.test(s)) {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+
+/** 渲染命令 .md（本仓库格式：name / description / category / tags） */
+function renderCommand(commandContent) {
+  const tags = Array.isArray(commandContent.tags) ? commandContent.tags : [];
+  return [
+    '---',
+    `name: ${yamlScalar(commandContent.name)}`,
+    `description: ${yamlScalar(commandContent.description)}`,
+    `category: ${yamlScalar(commandContent.category)}`,
+    `tags: [${tags.join(', ')}]`,
+    '---',
+    commandContent.body.replace(/\n+$/, '') + '\n',
+  ].join('\n');
+}
+
+// ── 主流程 ────────────────────────────────────────────────────
+
+/**
+ * 按 pin 拉取并重新渲染 OpenSpec 工作流到本仓库。
+ * 幂等：重复执行结果一致。
+ * @returns {Promise<{version: string, cmdCount: number, skillCount: number, skipped: boolean}>}
+ */
+async function fetchLatestOpenSpec() {
+  const pin = getLocalVersion();
+  if (!pin) {
+    throw new Error(
+      `未找到 OpenSpec 版本 pin（${path.relative(SHARED_STANDARDS_DIR, VERSION_FILE)} 缺失或损坏）。\n` +
+      `请先写入 { "version": "<x.y.z>" } 再执行。`
+    );
+  }
+
+  // pin 一致且文件齐全 → 幂等跳过
+  if (validateDeployed().valid) {
+    log(`OpenSpec 内容已按 pin ${pin} 就位，跳过重渲染`, 'success');
+    return { version: pin, cmdCount: 0, skillCount: 0, skipped: true };
+  }
+  log(`检测到内容不完整，按 pin ${pin} 重新渲染...`, 'info');
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cbb-os-'));
+  try {
+    const pkgDir = await downloadCliPackage(pin, tmpDir);
+    const cli = await loadCliRenderer(pkgDir);
+    if (cli.version !== pin) {
+      log(`警告：pin 为 ${pin}，但包内版本为 ${cli.version}`, 'warn');
+    }
+
+    const skills = cli.getSkillTemplates();
+    const commands = cli.getCommandContents();
+    const cmdById = new Map(commands.map(c => [c.id, c]));
+    const skillByName = new Map(skills.map(s => [s.dirName, s]));
+
+    let cmdCount = 0;
+    let skillCount = 0;
+
+    for (const wf of WORKFLOWS) {
+      const cmd = cmdById.get(wf.cmd);
+      if (!cmd) {
+        log(`跳过命令 ${wf.cmd}: 官方渲染器无此 workflow`, 'warn');
+      } else {
+        const dest = path.join(OPENSPEC_COMMANDS_DIR, `${wf.cmd}.md`);
+        assertSafeDestination(dest, `写入命令 ${wf.cmd}`);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, renderCommand(cmd));
+        cmdCount += 1;
+      }
+
+      const skill = skillByName.get(wf.skill);
+      if (!skill) {
+        log(`跳过技能 ${wf.skill}: 官方渲染器无此 workflow`, 'warn');
+      } else {
+        const dest = path.join(OPENSPEC_SKILLS_DIR, wf.skill, 'SKILL.md');
+        assertSafeDestination(dest, `写入技能 ${wf.skill}`);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, cli.generateSkillContent(skill.template, cli.version));
+        skillCount += 1;
+      }
+    }
+
+    writeVersion(pin);
+    log(`OpenSpec 工作流已渲染: ${pin}（${cmdCount} 个命令 + ${skillCount} 个技能）`, 'success');
+    return { version: pin, cmdCount, skillCount, skipped: false };
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+}
+
+/**
+ * 检查上游是否有新版本（不改动任何文件）。
+ * @returns {Promise<{current: string|null, latest: string|null, outdated: boolean}>}
+ */
+async function checkUpstream() {
+  const current = getLocalVersion();
+  const mirrors = loadMirrors('openspec');
+  const { buffer } = await fetchWithMirrors(mirrors, m => registryUrl(m));
+  const data = JSON.parse(buffer.toString('utf-8'));
+  const latest = (data['dist-tags'] || {}).latest || null;
+  const outdated = Boolean(current && latest && current !== latest);
+  return { current, latest, outdated };
+}
+
+// ── 完整性校验 ────────────────────────────────────────────────
+
+/**
+ * 校验 Safe-Overwrite 区的所有文件均已部署（无需下载）。
+ * @returns {{valid: boolean, missing: string[]}}
+ */
+function validateDeployed() {
+  const missing = [];
+  for (const wf of WORKFLOWS) {
+    if (wf.cmd) {
+      const p = path.join(OPENSPEC_COMMANDS_DIR, `${wf.cmd}.md`);
+      if (!fs.existsSync(p)) missing.push(`commands/${wf.cmd}.md`);
+    }
+    if (wf.skill) {
+      const p = path.join(OPENSPEC_SKILLS_DIR, wf.skill, 'SKILL.md');
+      if (!fs.existsSync(p)) missing.push(`skills/${wf.skill}/SKILL.md`);
+    }
+  }
+  return { valid: missing.length === 0, missing };
+}
+
+// ── 导出 ──────────────────────────────────────────────────────
+
+module.exports = {
+  OPENSPEC_DIR,
+  OPENSPEC_COMMANDS_DIR,
+  OPENSPEC_SKILLS_DIR,
+  VERSION_FILE,
+  WORKFLOWS,
+  GITHUB_REPO,
+  NPM_PKG,
+
+  PROTECTED_PATH_PREFIXES,
+  assertSafeDestination,
+  fetchLatestOpenSpec,
+  checkUpstream,
+  getLocalVersion,
+  validateDeployed,
+};