kld-sdd 2.4.19 → 2.5.1

package/lib/init.js

@@ -17,83 +17,25 @@ const os = require('os');
 const {
   SKILLS_BUNDLE_NAME,
   OPSX_SKILL_DIRS,
-  renderTemplate
+  OPSX_SKILL_METADATA,
+  renderTemplate,
+  validateRenderedContent,
 } = require('./skills-bundle');
+const { getToolProfile, buildToolConfigs } = require('./tool-profiles');
+const {
+  deployKunlunCommandBridges,
+  cleanupManagedKunlunBridges,
+  BRIDGE_MARKER,
+} = require('./command-bridge');
+const { deployCodebuddyHookPack } = require('./deploy-codebuddy-hooks');
 
 const rl = readline.createInterface({
   input: process.stdin,
   output: process.stdout
 });
 
-// 工具类型配置
-const TOOL_CONFIGS = {
-  cursor: {
-    name: 'Cursor',
-    configDir: '.cursor',
-    commandsDir: '.cursor/commands',
-    opsxDir: '.cursor/commands/opsx',
-    skillsDir: '.cursor/skills',
-    agentType: 'cursor'
-  },
-  claude: {
-    name: 'Claude Code',
-    configDir: '.claude',
-    commandsDir: '.claude/commands',
-    opsxDir: '.claude/commands/opsx',
-    skillsDir: '.claude/skills',
-    agentType: 'claude-code'
-  },
-  codebuddy: {
-    name: 'CodeBuddy',
-    configDir: '.codebuddy',
-    commandsDir: '.codebuddy/commands',
-    opsxDir: '.codebuddy/commands/opsx',
-    skillsDir: '.codebuddy/skills',
-    agentType: 'codebuddy'
-  },
-  qoder: {
-    name: 'Qoder',
-    configDir: '.qoder',
-    commandsDir: '.qoder/commands',
-    opsxDir: '.qoder/commands/opsx',
-    skillsDir: '.qoder/skills',
-    agentType: 'qoder'
-  },
-  opencode: {
-    name: 'OpenCode',
-    configDir: '.opencode',
-    commandsDir: '.opencode/commands',
-    opsxDir: '.opencode/commands/opsx',
-    skillsDir: '.opencode/skills',
-    agentType: 'opencode',
-    // opencode 原生命令使用 command/（单数），需要额外清理
-    nativeCommandDir: '.opencode/command'
-  },
-  kunlunzhima: {
-    name: 'KunlunZhima',
-    configDir: '.kunlunzhima',
-    commandsDir: '.kunlunzhima/commands',
-    opsxDir: '.kunlunzhima/commands/opsx',
-    skillsDir: '.kunlunzhima/skills',
-    agentType: 'kunlunzhima'
-  },
-  workbuddy: {
-    name: 'WorkBuddy',
-    configDir: '.workbuddy',
-    commandsDir: '.workbuddy/commands',
-    opsxDir: '.workbuddy/commands/opsx',
-    skillsDir: '.workbuddy/skills',
-    agentType: 'workbuddy'
-  },
-  codex: {
-    name: 'Codex',
-    configDir: '.agents',
-    commandsDir: '.agents/commands',
-    opsxDir: '.agents/commands/opsx',
-    skillsDir: '.agents/skills',
-    agentType: 'codex'
-  }
-};
+// 工具类型配置（路径字段从 TOOL_PROFILES 派生，避免双份漂移）
+const TOOL_CONFIGS = buildToolConfigs();
 
 /**
  * 询问用户选择
@@ -331,6 +273,8 @@ function copyDir(source, target) {
 }
 
 function copyDirRendered(source, target, config, toolKey) {
+  const profile = getToolProfile(toolKey);
+
   if (!fs.existsSync(target)) {
     fs.mkdirSync(target, { recursive: true });
   }
@@ -344,7 +288,8 @@ function copyDirRendered(source, target, config, toolKey) {
     if (stat.isDirectory()) {
       copyDirRendered(srcPath, tgtPath, config, toolKey);
     } else {
-      const rendered = renderTemplate(fs.readFileSync(srcPath, 'utf8'), config, toolKey);
+      const rendered = renderTemplate(fs.readFileSync(srcPath, 'utf8'), config, toolKey, profile);
+      validateRenderedContent(rendered, profile, tgtPath);
       fs.writeFileSync(tgtPath, rendered, 'utf8');
     }
   }
@@ -363,7 +308,9 @@ const NATIVE_OPSX_CMDS_SLASH = ['propose.md', 'apply.md', 'archive.md', 'explore
  * SDD 自定义 command 标记（init 不部署；用户手动维护时保留）
  */
 function isSddCustomCommand(content) {
-  return content.includes('# SDD') || content.includes('skywalk-sdd/log.cjs');
+  return content.includes(BRIDGE_MARKER)
+    || content.includes('skywalk-sdd/log.cjs')
+    || /# SDD\b/.test(content);
 }
 
 /**
@@ -376,7 +323,8 @@ function isSddCustomCommand(content) {
  * openspec 对不同工具生成的目录结构：
  * - Cursor: commands/opsx-*.md（根目录，连字符）
  * - Claude/CodeBuddy/Qoder 等: commands/opsx/*.md（opsx 子目录）
- * - OpenCode: command/opsx-*.md（command 单数目录，整目录删除）
+ * - OpenSpec OpenCode: commands/opsx-*.md（复数扁平，通用 commands/ 循环清理）
+ * - Legacy OpenCode: command/（单数目录，nativeCommandDir 整目录删除）
  *
  * @param {string[]} selectedTools - 用户选择的编辑器列表
  */
@@ -524,16 +472,17 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
   
   for (const toolKey of selectedTools) {
     const config = TOOL_CONFIGS[toolKey];
-    if (!config || !config.skillsDir) continue;
+    const profile = getToolProfile(toolKey);
+    if (!config || !profile.skillsDir) continue;
     
-    const targetSkillsDir = path.join(cwd, config.skillsDir);
+    const targetSkillsDir = path.join(cwd, profile.skillsDir);
     
     // 确保 skills 目录存在
     if (!fs.existsSync(targetSkillsDir)) {
       fs.mkdirSync(targetSkillsDir, { recursive: true });
     }
     
-    console.log(`   部署 ${config.name} 的 opsx skills（${skillDirs.length} 个，扁平到 ${config.skillsDir}/）...`);
+    console.log(`   部署 ${config.name} 的 opsx skills（${skillDirs.length} 个，扁平到 ${profile.skillsDir}/）...`);
     
     for (const skillDir of skillDirs) {
       const sourceDir = path.join(skillsTemplatePath, skillDir);
@@ -554,6 +503,46 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
   return true;
 }
 
+/**
+ * 按 profile 部署 Agent 专属产物（Kunlun bridge / CodeBuddy hooks / Claude hooks）
+ * 仅处理 selectedTools 中的 profile，不触碰未选 Agent 目录。
+ */
+function deployProfileArtifacts(selectedTools = Object.keys(TOOL_CONFIGS), cwd = process.cwd(), pkgPath = getPackagePath()) {
+  console.log('🧩 正在部署 Agent 专属产物...');
+
+  for (const toolKey of selectedTools) {
+    const profile = getToolProfile(toolKey);
+    const config = TOOL_CONFIGS[toolKey];
+    if (!config) continue;
+
+    if (profile.requiresCommandBridge) {
+      cleanupManagedKunlunBridges(profile, cwd);
+      const bridgeResult = deployKunlunCommandBridges({
+        profile,
+        projectRoot: cwd,
+        pkgPath,
+        skillMetadata: OPSX_SKILL_METADATA,
+      });
+      console.log(`   ✓ ${config.name}: 部署 ${bridgeResult.deployed.length} 个 Kunlun command bridge`);
+    }
+
+    if (profile.hookProvider === 'codebuddy') {
+      const hookResult = deployCodebuddyHookPack(profile, cwd, pkgPath);
+      if (!hookResult.ok) {
+        throw new Error(hookResult.error || `CodeBuddy Hook 部署失败: ${profile.configDir}/settings.json`);
+      }
+      console.log(`   ✓ ${config.name}: 部署 Hook Pack（运行 /hooks 审核后生效）`);
+    }
+
+    if (profile.hookProvider === 'claude') {
+      deployClaudeHookPack([toolKey]);
+    }
+  }
+
+  console.log('✅ Agent 专属产物部署完成');
+  return true;
+}
+
 /**
  * 部署 Claude Code Hook Pack（可选增强）
  * Hook 只调用 skywalk-sdd/log.cjs，不写私有日志，不替代 OPSX 模板采集。
@@ -780,9 +769,33 @@ function initGlobalOverview() {
   return true;
 }
 
+/**
+ * 部署 SDD 操作手册（HTML）到 openspec 目录
+ */
+function deploySddGuideManual(cwd = process.cwd(), pkgPath = getPackagePath()) {
+  console.log('📖 正在部署 SDD 操作手册...');
+
+  const source = path.join(pkgPath, 'kld-sdd-guide.html');
+  const targetDir = path.join(cwd, 'openspec');
+  const targetFile = path.join(targetDir, 'kld-sdd操作手册.html');
+
+  if (!fs.existsSync(source)) {
+    console.log('⚠️  操作手册源文件不存在，跳过: kld-sdd-guide.html');
+    return false;
+  }
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  fs.copyFileSync(source, targetFile);
+  console.log(`✅ SDD 操作手册已部署: openspec/kld-sdd操作手册.html`);
+  return true;
+}
+
 /**
  * 部署 SDD Telemetry 数据目录
- * 创建本地数据目录用于存储事件和报告
+ * 创建本地数据目录用于存储事件和活跃状态（最终报告落 openspec/changes/<change>/reports/，不再写 skywalk-sdd/reports/）
  */
 function deployTelemetryDataDir() {
   console.log('📊 正在初始化 SDD Telemetry 数据目录...');
@@ -795,18 +808,13 @@ function deployTelemetryDataDir() {
     fs.mkdirSync(dataDir, { recursive: true });
   }
 
-  // 创建本地数据目录（事件和报告存储）
+  // 创建本地数据目录（事件和活跃状态存储；报告落 change 子目录，不在此创建）
   const eventsDir = path.join(dataDir, 'events');
-  const reportsDir = path.join(dataDir, 'reports');
   const stateDir = path.join(dataDir, 'state');
   if (!fs.existsSync(eventsDir)) {
     fs.mkdirSync(eventsDir, { recursive: true });
     console.log('   ✓ 创建 skywalk-sdd/events/ 数据目录');
   }
-  if (!fs.existsSync(reportsDir)) {
-    fs.mkdirSync(reportsDir, { recursive: true });
-    console.log('   ✓ 创建 skywalk-sdd/reports/ 报告目录');
-  }
   if (!fs.existsSync(stateDir)) {
     fs.mkdirSync(stateDir, { recursive: true });
     console.log('   ✓ 创建 skywalk-sdd/state/ 活跃阶段状态目录');
@@ -876,10 +884,14 @@ function installGitHookShim(cwd, hookName, scriptPath) {
  * 这些脚本只做质量门禁和 CI 补充记录，不替代 OPSX 主采集链路。
  */
 function deployQualityGateTemplates() {
-  console.log('🧰 正在部署 SDD Git hooks / CI 兜底模板...');
-
   const pkgPath = getPackagePath();
   const cwd = process.cwd();
+  // U4: 非 Git 项目跳过 Git hooks / CI 兜底模板（按需部署，不污染非 Git 项目根）
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    console.log('🧰 非 Git 项目，跳过 Git hooks / CI 兜底模板部署');
+    return false;
+  }
+  console.log('🧰 正在部署 SDD Git hooks / CI 兜底模板...');
   const dataDir = path.join(cwd, 'skywalk-sdd');
   const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
   const ciTemplateDir = path.join(pkgPath, 'templates', 'ci');
@@ -936,7 +948,6 @@ function updateGitignore() {
     '.workbuddy/commands/personal-*',
     '.agents/commands/personal-*',
     'skywalk-sdd/events/',
-    'skywalk-sdd/reports/',
     'skywalk-sdd/state/',
     '.worktrees/'
   ];
@@ -951,9 +962,8 @@ function updateGitignore() {
 .workbuddy/commands/personal-*
 .agents/commands/personal-*
 
-# SDD Telemetry 数据（本地度量，可选提交）
+# SDD Telemetry 数据（本地度量，可选提交；最终报告落 openspec/changes/<change>/reports/ 随 change 提交）
 skywalk-sdd/events/
-skywalk-sdd/reports/
 skywalk-sdd/state/
 
 # SDD Apply 隔离 worktree（本地临时目录）
@@ -1039,7 +1049,7 @@ async function main() {
   } catch (error) {
     console.error(`❌ ${error.message}`);
     rl.close();
-    return;
+    process.exit(1);
   }
 
   // 1. 运行 openspec init（传入用户选择的工具）
@@ -1060,8 +1070,8 @@ async function main() {
     // 3.2 清理原生 openspec-* skills（防止残留）
     cleanupNativeOpenspecSkills(selectedTools);
 
-    // 3.3 部署 Claude Code Hook Pack（可选增强）
-    deployClaudeHookPack(selectedTools);
+    // 3.3 部署 Agent 专属产物（Kunlun bridge / CodeBuddy hooks / Claude hooks）
+    deployProfileArtifacts(selectedTools, process.cwd(), getPackagePath());
 
     // 5. 部署 SDD Telemetry 数据目录
     deployTelemetryDataDir();
@@ -1074,6 +1084,9 @@ async function main() {
     
     // 7. 初始化全局架构约束 (overview.md)
     initGlobalOverview();
+
+    // 7.1 部署 SDD 操作手册（HTML）
+    deploySddGuideManual();
   }
 
   // 7. 更新 .gitignore
@@ -1090,8 +1103,16 @@ async function main() {
   console.log();
   console.log('已生成/覆盖:');
   console.log('  🌐 openspec/specs/overview.md     # 全局架构约束（数据字典、接口规范）');
+  console.log('  📖 openspec/kld-sdd操作手册.html   # SDD 操作手册（HTML）');
   console.log('  📄 openspec-templates/           # 标准文档模版（参考用）');
   console.log('  🎯 .*/skills/opsx-*/              # SDD skills（扁平一层）');
+  if (selectedTools.includes('kunlunzhima')) {
+    console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
+    console.log('  ℹ️  KunlunZhima 通过 commands/skills 入口使用 SDD，未启用自动 Hook');
+  }
+  if (selectedTools.includes('codebuddy')) {
+    console.log('  🪝 .codebuddy/hooks/              # CodeBuddy SDD Hook Pack（运行 /hooks 审核后生效）');
+  }
   if (selectedTools.includes('claude')) {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
   }
@@ -1101,7 +1122,7 @@ async function main() {
   console.log();
   
   // 统一的 skill 格式说明
-  console.log('可用 skills（opsx-* 系列，10 个 SDD skills）:');
+  console.log('可用 skills（opsx-* 系列，11 个 SDD skills）:');
   console.log('  opsx-propose   - 创建业务意图文档（Why）');
   console.log('  opsx-spec      - 创建技术契约文档（What）');
   console.log('  opsx-design    - 创建技术实现方案（How）');
@@ -1112,6 +1133,7 @@ async function main() {
   console.log('  opsx-archive   - 归档变更（Archive）');
   console.log('  opsx-explore   - 浏览变更状态（Explore）');
   console.log('  opsx-knowledge - 业务知识库检索（辅助）');
+  console.log('  opsx-rules     - 生成/更新 Agent 规则（辅助）');
     
   console.log();
   console.log('后续步骤:');
@@ -1119,6 +1141,15 @@ async function main() {
   console.log('  2. 按顺序执行 propose → spec → design → task');
   console.log('  3. 激活 opsx-check 验证文档质量');
   console.log('  4. 激活 opsx-apply 申请实施，opsx-archive 归档完成');
+  if (selectedTools.includes('codebuddy')) {
+    console.log('  5. CodeBuddy 用户：重启会话后运行 /hooks 审核 SDD Hook，审批后门禁生效');
+  }
+  if (selectedTools.includes('kunlunzhima')) {
+    console.log('  5. KunlunZhima 用户：在 Craft 模式使用 /opsx:propose 等 OPSX 命令（.kunlunzhima/commands/opsx/）');
+  }
+  if (selectedTools.includes('opencode')) {
+    console.log('  5. OpenCode 用户：用 /opsx-propose 或 /skills 启动 SDD（.opencode/skills/opsx-*/，skill 即斜杠命令）');
+  }
   console.log();
   console.log('📊 SDD Telemetry（嵌入在 skill 流程中，自动执行，无需配置）：');
   console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
@@ -1128,4 +1159,16 @@ async function main() {
   rl.close();
 }
 
-module.exports = { main, detectTools, getTemplatePath, selectEditor };
+module.exports = {
+  main,
+  detectTools,
+  getTemplatePath,
+  getPackagePath,
+  selectEditor,
+  deployOpsxSkills,
+  deployProfileArtifacts,
+  deploySddGuideManual,
+  copyDirRendered,
+  parseSelectedTools,
+  TOOL_CONFIGS,
+};

package/lib/settings-merge.js

@@ -0,0 +1,85 @@
+/**
+ * Conservative merge for CodeBuddy .codebuddy/settings.json hooks.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SDD_HOOK_COMMAND_RE = /(?:^|\s|["'])\$?CODEBUDDY_PROJECT_DIR[\\/]+\.codebuddy[\\/]+hooks[\\/]+sdd-[\w-]+\.cjs(?=$|\s|["'])/i;
+
+function hookCommandText(hook) {
+  const args = Array.isArray(hook.args) ? hook.args : [];
+  return [hook.command, ...args].filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function isSddCodebuddyHook(hook) {
+  return SDD_HOOK_COMMAND_RE.test(hookCommandText(hook));
+}
+
+function sameHookCommand(left, right) {
+  return hookCommandText(left) === hookCommandText(right) &&
+    String(left.type || '') === String(right.type || '');
+}
+
+function removeManagedSddHooks(entries) {
+  return entries
+    .map(entry => {
+      if (!Array.isArray(entry.hooks)) {
+        return entry;
+      }
+      return {
+        ...entry,
+        hooks: entry.hooks.filter(hook => !isSddCodebuddyHook(hook)),
+      };
+    })
+    .filter(entry => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
+}
+
+function mergeCodebuddySettings(settingsPath, templateSettings) {
+  const displayPath = path.basename(settingsPath);
+  let originalBytes = '';
+  if (fs.existsSync(settingsPath)) {
+    originalBytes = fs.readFileSync(settingsPath, 'utf8');
+  }
+
+  let existingSettings = {};
+  if (originalBytes) {
+    try {
+      existingSettings = JSON.parse(originalBytes);
+    } catch {
+      return {
+        ok: false,
+        error: `${displayPath} 不是合法 JSON，请修复后重试（路径: ${settingsPath}）`,
+      };
+    }
+  }
+
+  const merged = { ...existingSettings };
+  merged.hooks = merged.hooks || {};
+
+  for (const [eventName, entries] of Object.entries(templateSettings.hooks || {})) {
+    merged.hooks[eventName] = removeManagedSddHooks(merged.hooks[eventName] || []);
+    for (const entry of entries) {
+      const templateHooks = entry.hooks || [];
+      const exists = merged.hooks[eventName].some(existingEntry => {
+        const existingHooks = existingEntry.hooks || [];
+        return templateHooks.every(templateHook =>
+          existingHooks.some(existingHook => sameHookCommand(existingHook, templateHook))
+        );
+      });
+      if (!exists) {
+        merged.hooks[eventName].push(entry);
+      }
+    }
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  return { ok: true };
+}
+
+module.exports = {
+  mergeCodebuddySettings,
+  isSddCodebuddyHook,
+  hookCommandText,
+  removeManagedSddHooks,
+};

package/lib/skills-bundle.js

@@ -2,6 +2,9 @@
  * SDD skills bundle 共享配置与模板渲染
  */
 
+const fs = require('fs');
+const path = require('path');
+
 const SKILLS_BUNDLE_NAME = 'kld-sdd';
 
 const OPSX_SKILL_DIRS = [
@@ -14,17 +17,151 @@ const OPSX_SKILL_DIRS = [
   'opsx-test',
   'opsx-archive',
   'opsx-explore',
-  'opsx-knowledge'
+  'opsx-knowledge',
+  'opsx-rules',
 ];
 
-function renderTemplate(content, config, toolKey) {
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function commandNameFromSkillDir(skillDir) {
+  return skillDir.replace(/^opsx-/, '');
+}
+
+function displayNameFromCommandName(commandName) {
+  return `OPSX: ${commandName.charAt(0).toUpperCase() + commandName.slice(1)}`;
+}
+
+function parseSkillFrontmatter(content) {
+  const stripped = content.replace(/^\uFEFF/, '');
+  if (!stripped.startsWith('---')) {
+    return {};
+  }
+
+  const end = stripped.indexOf('---', 3);
+  if (end < 0) {
+    return {};
+  }
+
+  const block = stripped.slice(3, end).trim();
+  const result = {};
+
+  for (const rawLine of block.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+
+  return result;
+}
+
+function buildOpsxSkillMetadata(pkgPath = PKG_ROOT) {
+  const skillsTemplateDir = path.join(pkgPath, 'templates', 'skills', SKILLS_BUNDLE_NAME);
+
+  return OPSX_SKILL_DIRS.map((skillDir) => {
+    const commandName = commandNameFromSkillDir(skillDir);
+    const skillMdPath = path.join(skillsTemplateDir, skillDir, 'SKILL.md');
+    let description = '';
+    let argumentHint = '';
+
+    if (fs.existsSync(skillMdPath)) {
+      const frontmatter = parseSkillFrontmatter(fs.readFileSync(skillMdPath, 'utf8'));
+      description = frontmatter.description || '';
+      argumentHint = frontmatter['argument-hint'] || '';
+    }
+
+    return {
+      skillDir,
+      commandName,
+      displayName: displayNameFromCommandName(commandName),
+      description,
+      argumentHint,
+    };
+  });
+}
+
+const OPSX_SKILL_METADATA = buildOpsxSkillMetadata(PKG_ROOT);
+
+const KUNLUN_SLASH_COMMANDS = [
+  'propose',
+  'spec',
+  'design',
+  'task',
+  'check',
+  'apply',
+  'test',
+  'archive',
+  'explore',
+];
+
+function transformKunlunSlashCommands(content) {
+  if (typeof content !== 'string') {
+    return content;
+  }
+
+  let result = content;
+  for (const cmd of KUNLUN_SLASH_COMMANDS) {
+    result = result.replace(new RegExp(`/opsx-${cmd}(?![a-z-])`, 'g'), `/opsx:${cmd}`);
+  }
+  return result;
+}
+
+function replaceProfileTokens(content, profile) {
+  if (!profile) {
+    return content;
+  }
+
+  const vars = profile.templateVariables || {};
   return content
-    .replace(/^\uFEFF/, '')
-    .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey);
+    .replace(/\$\{SKILL_RUNTIME_DIR\}/g, vars.SKILL_RUNTIME_DIR || profile.skillsDir || '')
+    .replace(/\$\{HOOK_GATE_DESCRIPTION\}/g, vars.HOOK_GATE_DESCRIPTION || '')
+    .replace(/\$\{SHELL_GUIDANCE\}/g, vars.SHELL_GUIDANCE || '')
+    .replace(/\$\{AGENT_SKILL_DIR\}/g, profile.skillsDir || '');
+}
+
+function renderTemplate(content, config, toolKey, profile) {
+  let rendered = replaceProfileTokens(
+    content
+      .replace(/^\uFEFF/, '')
+      .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey),
+    profile
+  );
+
+  if (toolKey === 'kunlunzhima') {
+    rendered = transformKunlunSlashCommands(rendered);
+  }
+
+  return rendered;
+}
+
+function validateRenderedContent(content, profile, context = '') {
+  const unresolved = (content.match(/\$\{[A-Z_]+\}/g) || [])
+    // Claude Code 运行时注入，部署时保留字面量
+    .filter((token) => token !== '${CLAUDE_SKILL_DIR}');
+  if (unresolved.length > 0) {
+    const unique = [...new Set(unresolved)];
+    const prefix = context ? `${context}: ` : '';
+    throw new Error(`${prefix}未解析的模板 token: ${unique.join(', ')}`);
+  }
+
+  return true;
 }
 
 module.exports = {
   SKILLS_BUNDLE_NAME,
   OPSX_SKILL_DIRS,
-  renderTemplate
+  OPSX_SKILL_METADATA,
+  buildOpsxSkillMetadata,
+  commandNameFromSkillDir,
+  displayNameFromCommandName,
+  parseSkillFrontmatter,
+  renderTemplate,
+  replaceProfileTokens,
+  transformKunlunSlashCommands,
+  validateRenderedContent,
 };