@adversity/coding-tool-x 2.2.0 → 2.3.0

package/src/server/services/format-converter.js

@@ -0,0 +1,506 @@
+/**
+ * 格式转换服务
+ *
+ * 支持 Claude Code ↔ Codex CLI 格式互转
+ * - Skills: SKILL.md 格式转换
+ * - Commands/Prompts: 命令/提示格式转换
+ */
+
+// Codex CLI 限制
+const CODEX_LIMITS = {
+  skillName: 100,
+  skillDescription: 500
+};
+
+/**
+ * 解析 YAML frontmatter
+ * 支持基本的 YAML 解析和嵌套 metadata 对象
+ */
+function parseFrontmatter(content) {
+  const result = {
+    frontmatter: {},
+    body: content
+  };
+
+  // 移除 BOM
+  content = content.trim().replace(/^\uFEFF/, '');
+
+  // 解析 YAML frontmatter
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!match) {
+    return result;
+  }
+
+  const frontmatterText = match[1];
+  result.body = match[2].trim();
+
+  // 解析 YAML（支持嵌套 metadata）
+  const lines = frontmatterText.split('\n');
+  let currentParent = null;
+
+  for (const line of lines) {
+    // 检测缩进（嵌套对象）
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+
+    // 跳过空行
+    if (!line.trim()) continue;
+
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.slice(0, colonIndex).trim();
+    let value = line.slice(colonIndex + 1).trim();
+
+    // 检测是否是嵌套对象开始（值为空）
+    if (!value && indent === 0) {
+      currentParent = key;
+      result.frontmatter[key] = {};
+      continue;
+    }
+
+    // 处理嵌套属性
+    if (indent > 0 && currentParent && typeof result.frontmatter[currentParent] === 'object') {
+      // 去除引号
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      result.frontmatter[currentParent][key] = value;
+      continue;
+    }
+
+    // 重置当前父级
+    currentParent = null;
+
+    // 去除引号
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    result.frontmatter[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * 生成 YAML frontmatter 字符串
+ */
+function generateFrontmatter(data, format = 'claude') {
+  const lines = ['---'];
+
+  if (format === 'codex') {
+    // Codex 格式: name, description 必须，metadata 可选
+    if (data.name) {
+      lines.push(`name: "${escapeYamlString(data.name)}"`);
+    }
+    if (data.description) {
+      lines.push(`description: "${escapeYamlString(data.description)}"`);
+    }
+    if (data.metadata && Object.keys(data.metadata).length > 0) {
+      lines.push('metadata:');
+      for (const [key, value] of Object.entries(data.metadata)) {
+        lines.push(`  ${key}: "${escapeYamlString(value)}"`);
+      }
+    }
+    // Codex commands/prompts 特有字段
+    if (data['argument-hint']) {
+      lines.push(`argument-hint: ${data['argument-hint']}`);
+    }
+  } else {
+    // Claude Code 格式
+    if (data.name) {
+      lines.push(`name: "${escapeYamlString(data.name)}"`);
+    }
+    if (data.description) {
+      lines.push(`description: "${escapeYamlString(data.description)}"`);
+    }
+    if (data.license) {
+      lines.push(`license: "${escapeYamlString(data.license)}"`);
+    }
+    // Claude Code commands 特有字段
+    if (data['allowed-tools']) {
+      lines.push(`allowed-tools: ${data['allowed-tools']}`);
+    }
+    if (data['argument-hint']) {
+      lines.push(`argument-hint: ${data['argument-hint']}`);
+    }
+    if (data.model) {
+      lines.push(`model: ${data.model}`);
+    }
+    if (data.context) {
+      lines.push(`context: ${data.context}`);
+    }
+    if (data.agent) {
+      lines.push(`agent: ${data.agent}`);
+    }
+  }
+
+  lines.push('---');
+  return lines.join('\n');
+}
+
+/**
+ * 转义 YAML 字符串中的特殊字符
+ */
+function escapeYamlString(str) {
+  if (!str) return '';
+  return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * 检测 Skill 格式
+ * @returns {'claude' | 'codex' | 'unknown'}
+ */
+function detectSkillFormat(content) {
+  const { frontmatter } = parseFrontmatter(content);
+
+  // Codex 特征: 有 metadata 对象
+  if (frontmatter.metadata && typeof frontmatter.metadata === 'object') {
+    return 'codex';
+  }
+
+  // Claude Code 特征: 有 allowed-tools 或 license
+  if (frontmatter['allowed-tools'] || frontmatter.license) {
+    return 'claude';
+  }
+
+  // 两者都有 name 和 description，无法区分时默认 claude
+  if (frontmatter.name && frontmatter.description) {
+    return 'claude';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * 检测 Command/Prompt 格式
+ * @returns {'claude' | 'codex' | 'unknown'}
+ */
+function detectCommandFormat(content) {
+  const { frontmatter } = parseFrontmatter(content);
+
+  // Claude Code 特征: allowed-tools, model, context, agent, hooks
+  if (frontmatter['allowed-tools'] || frontmatter.model ||
+      frontmatter.context || frontmatter.agent || frontmatter.hooks) {
+    return 'claude';
+  }
+
+  // Codex 特征: 只有 description 和 argument-hint
+  if (frontmatter.description && !frontmatter['allowed-tools']) {
+    return 'codex';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * 转换 Skill: Claude Code → Codex CLI
+ */
+function convertSkillToCodex(claudeContent, options = {}) {
+  const { frontmatter, body } = parseFrontmatter(claudeContent);
+  const warnings = [];
+
+  // 处理字段
+  const codexData = {
+    name: frontmatter.name || '',
+    description: frontmatter.description || '',
+    metadata: {}
+  };
+
+  // 检查并截断 name
+  if (codexData.name.length > CODEX_LIMITS.skillName) {
+    warnings.push(`name 超过 ${CODEX_LIMITS.skillName} 字符，已截断`);
+    codexData.name = codexData.name.slice(0, CODEX_LIMITS.skillName);
+  }
+
+  // 检查并截断 description
+  if (codexData.description.length > CODEX_LIMITS.skillDescription) {
+    warnings.push(`description 超过 ${CODEX_LIMITS.skillDescription} 字符，已截断`);
+    codexData.description = codexData.description.slice(0, CODEX_LIMITS.skillDescription);
+  }
+
+  // 不支持的字段警告
+  if (frontmatter['allowed-tools']) {
+    warnings.push('allowed-tools 字段在 Codex 中不支持，已忽略');
+  }
+
+  // 生成 Codex 格式内容
+  const codexFrontmatter = generateFrontmatter(codexData, 'codex');
+  const codexContent = codexFrontmatter + '\n\n' + body;
+
+  return {
+    content: codexContent,
+    warnings,
+    format: 'codex'
+  };
+}
+
+/**
+ * 转换 Skill: Codex CLI → Claude Code
+ */
+function convertSkillToClaude(codexContent, options = {}) {
+  const { frontmatter, body } = parseFrontmatter(codexContent);
+  const warnings = [];
+
+  // 处理字段
+  const claudeData = {
+    name: frontmatter.name || '',
+    description: frontmatter.description || ''
+  };
+
+  // 保留 metadata.short-description（如果有）作为注释
+  if (frontmatter.metadata && frontmatter.metadata['short-description']) {
+    // 可以选择将其添加到 description 或作为单独字段
+    warnings.push(`metadata.short-description 已保留: "${frontmatter.metadata['short-description']}"`);
+  }
+
+  // 生成 Claude Code 格式内容
+  const claudeFrontmatter = generateFrontmatter(claudeData, 'claude');
+  const claudeContent = claudeFrontmatter + '\n\n' + body;
+
+  return {
+    content: claudeContent,
+    warnings,
+    format: 'claude'
+  };
+}
+
+/**
+ * 转换 Command: Claude Code → Codex CLI (Custom Prompt)
+ */
+function convertCommandToCodex(claudeContent, options = {}) {
+  const { frontmatter, body } = parseFrontmatter(claudeContent);
+  const warnings = [];
+
+  // 处理字段
+  const codexData = {
+    description: frontmatter.description || ''
+  };
+
+  // argument-hint 两者都支持
+  if (frontmatter['argument-hint']) {
+    codexData['argument-hint'] = frontmatter['argument-hint'];
+  }
+
+  // 不支持的字段警告
+  const unsupportedFields = ['allowed-tools', 'model', 'context', 'agent', 'hooks'];
+  for (const field of unsupportedFields) {
+    if (frontmatter[field]) {
+      warnings.push(`${field} 字段在 Codex 中不支持，已忽略`);
+    }
+  }
+
+  // 检查 body 中的 Claude Code 特有语法
+  let processedBody = body;
+
+  // 检测 Bash 执行语法 !`command`
+  if (/!\`[^`]+\`/.test(body)) {
+    warnings.push('Bash 执行语法 !`command` 在 Codex 中不支持，请手动替换');
+  }
+
+  // 检测文件引用语法 @filepath
+  if (/@[^\s]+/.test(body)) {
+    warnings.push('文件引用语法 @filepath 在 Codex 中不支持，请手动替换');
+  }
+
+  // 生成 Codex 格式内容
+  let codexContent = '';
+  if (codexData.description || codexData['argument-hint']) {
+    codexContent = generateFrontmatter(codexData, 'codex') + '\n\n';
+  }
+  codexContent += processedBody;
+
+  return {
+    content: codexContent,
+    warnings,
+    format: 'codex'
+  };
+}
+
+/**
+ * 转换 Command: Codex CLI (Custom Prompt) → Claude Code
+ */
+function convertCommandToClaude(codexContent, options = {}) {
+  const { frontmatter, body } = parseFrontmatter(codexContent);
+  const warnings = [];
+
+  // 处理字段
+  const claudeData = {
+    description: frontmatter.description || ''
+  };
+
+  // argument-hint 两者都支持
+  if (frontmatter['argument-hint']) {
+    claudeData['argument-hint'] = frontmatter['argument-hint'];
+  }
+
+  // Codex 命名参数 $KEY 在 Claude Code 中也支持，无需转换
+
+  // 生成 Claude Code 格式内容
+  let claudeContent = '';
+  if (claudeData.description || claudeData['argument-hint']) {
+    claudeContent = generateFrontmatter(claudeData, 'claude') + '\n\n';
+  }
+  claudeContent += body;
+
+  return {
+    content: claudeContent,
+    warnings,
+    format: 'claude'
+  };
+}
+
+/**
+ * 批量转换 Skills
+ */
+function convertSkillsBatch(skills, targetFormat) {
+  const results = [];
+
+  for (const skill of skills) {
+    try {
+      const converted = targetFormat === 'codex'
+        ? convertSkillToCodex(skill.content)
+        : convertSkillToClaude(skill.content);
+
+      results.push({
+        name: skill.name,
+        success: true,
+        ...converted
+      });
+    } catch (err) {
+      results.push({
+        name: skill.name,
+        success: false,
+        error: err.message
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 批量转换 Commands
+ */
+function convertCommandsBatch(commands, targetFormat) {
+  const results = [];
+
+  for (const command of commands) {
+    try {
+      const converted = targetFormat === 'codex'
+        ? convertCommandToCodex(command.content)
+        : convertCommandToClaude(command.content);
+
+      results.push({
+        name: command.name,
+        success: true,
+        ...converted
+      });
+    } catch (err) {
+      results.push({
+        name: command.name,
+        success: false,
+        error: err.message
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 解析 Skill 内容（支持双格式）
+ */
+function parseSkillContent(content) {
+  const { frontmatter, body } = parseFrontmatter(content);
+  const format = detectSkillFormat(content);
+
+  const result = {
+    name: frontmatter.name || '',
+    description: frontmatter.description || '',
+    body,
+    fullContent: content,
+    format
+  };
+
+  // 处理 Codex 特有字段
+  if (frontmatter.metadata) {
+    result.metadata = frontmatter.metadata;
+    if (frontmatter.metadata['short-description']) {
+      result.shortDescription = frontmatter.metadata['short-description'];
+    }
+  }
+
+  // 处理 Claude Code 特有字段
+  if (frontmatter['allowed-tools']) {
+    result.allowedTools = frontmatter['allowed-tools'];
+  }
+  if (frontmatter.license) {
+    result.license = frontmatter.license;
+  }
+
+  return result;
+}
+
+/**
+ * 解析 Command 内容（支持双格式）
+ */
+function parseCommandContent(content) {
+  const { frontmatter, body } = parseFrontmatter(content);
+  const format = detectCommandFormat(content);
+
+  const result = {
+    description: frontmatter.description || '',
+    argumentHint: frontmatter['argument-hint'] || '',
+    body,
+    fullContent: content,
+    format
+  };
+
+  // 处理 Claude Code 特有字段
+  if (frontmatter['allowed-tools']) {
+    result.allowedTools = frontmatter['allowed-tools'];
+  }
+  if (frontmatter.model) {
+    result.model = frontmatter.model;
+  }
+  if (frontmatter.context) {
+    result.context = frontmatter.context;
+  }
+  if (frontmatter.agent) {
+    result.agent = frontmatter.agent;
+  }
+  if (frontmatter.hooks) {
+    result.hooks = frontmatter.hooks;
+  }
+
+  return result;
+}
+
+module.exports = {
+  // 格式检测
+  detectSkillFormat,
+  detectCommandFormat,
+
+  // Skills 转换
+  convertSkillToCodex,
+  convertSkillToClaude,
+  convertSkillsBatch,
+
+  // Commands 转换
+  convertCommandToCodex,
+  convertCommandToClaude,
+  convertCommandsBatch,
+
+  // 通用解析（支持双格式）
+  parseSkillContent,
+  parseCommandContent,
+  parseFrontmatter,
+  generateFrontmatter,
+
+  // 常量
+  CODEX_LIMITS
+};