coding-tool-x 3.8.3 → 3.8.5

package/src/server/services/config-templates-service.js

@@ -7,34 +7,70 @@
 
 const fs = require('fs');
 const path = require('path');
+const { randomUUID } = require('crypto');
 const yaml = require('js-yaml');
 const { PATHS } = require('../../config/paths');
-const { AgentsService } = require('./agents-service');
-const { CommandsService } = require('./commands-service');
+const { getPlatformContext } = require('../platform-context');
+const TEMPLATES_FILE = path.join(PATHS.config, 'config-templates.json');
+const { AgentsService } = require('../../platforms/agents-service');
+const { CommandsService } = require('../../platforms/commands-service');
 const { SkillService } = require('./skill-service');
 const { PluginsService } = require('./plugins-service');
 const { convertCommandToCodex, convertCommandToGemini } = require('./format-converter');
+const { assertNoSymlinkComponents, resolveProjectTarget } = require('../../shared/project-config');
 const mcpService = require('./mcp-service');
 const promptsService = require('./prompts-service');
-const pluginsService = new PluginsService();
 
-// 配置模板文件路径
-const TEMPLATES_FILE = path.join(PATHS.config, 'config-templates.json');
-const AI_CONFIG_MAP = {
-  claude: { fileName: 'CLAUDE.md', name: 'Claude' },
-  codex: { fileName: 'AGENTS.md', name: 'Codex' },
-  gemini: { fileName: 'GEMINI.md', name: 'Gemini' },
-  opencode: { fileName: '.opencode/AGENTS.md', name: 'OpenCode' },
-  omp: { fileName: null, name: 'OMP command templates' }
-};
+function getAiConfigMap(registry = getPlatformContext().registry) {
+  if (!registry || typeof registry.list !== 'function') return {};
+  return Object.fromEntries(
+    registry.list({ enabledOnly: true })
+      .filter(platform => platform && platform.key)
+      .map(platform => [platform.key, {
+        fileName: platform.promptFile || null,
+        name: platform.promptLabel
+          || (platform.promptFile
+            ? (platform.label || platform.title || platform.key)
+            : `${platform.label || platform.title || platform.key} command templates`)
+      }])
+  );
+}
 
-const CLI_DEFAULT_AI_TYPE = {
-  claude: 'claude',
-  codex: 'codex',
-  gemini: 'gemini',
-  opencode: 'opencode',
-  omp: 'omp'
-};
+function getTemplateRegistry(options = {}) {
+  return options.registry || getPlatformContext().registry;
+}
+
+function getTemplatePlatforms(registry = getPlatformContext().registry) {
+  if (!registry || typeof registry.list !== 'function') return [];
+  return registry.list({ enabledOnly: true })
+    .filter(platform => platform && platform.key);
+}
+
+function getProjectResourceDescriptor(platformKey, resourceType, registry = getPlatformContext().registry) {
+  if (!registry || typeof registry.resolve !== 'function') return null;
+  const platform = registry.resolve(platformKey);
+  if (!platform || platform.resourceTypes?.[resourceType] === false) return null;
+
+  const resource = platform.projectResources?.[resourceType];
+  if (!resource) return null;
+
+  const relativePath = resource.canonicalRoot || resource.path || null;
+  if (!relativePath) return null;
+
+  return {
+    platform: platform.key,
+    prefix: relativePath,
+    format: resource.format || resourceType,
+    sortOrder: platform.sortOrder || 0
+  };
+}
+
+function getProjectResourceTargets(platformKeys, resourceType, registry = getPlatformContext().registry) {
+  return (platformKeys || [])
+    .map(platformKey => getProjectResourceDescriptor(platformKey, resourceType, registry))
+    .filter(Boolean)
+    .sort((a, b) => a.sortOrder - b.sortOrder);
+}
 
 /**
  * 确保目录存在
@@ -49,17 +85,19 @@ function pushSkipped(list, type, item, reason) {
   list.push({ type, item, reason });
 }
 
-function getTemplateDefaultAiType(template) {
-  if (template?.cliType && CLI_DEFAULT_AI_TYPE[template.cliType]) {
-    return CLI_DEFAULT_AI_TYPE[template.cliType];
+function getTemplateDefaultAiType(template, registry = getPlatformContext().registry) {
+  const aiConfigMap = getAiConfigMap(registry);
+  if (template?.cliType && aiConfigMap[template.cliType]) {
+    return template.cliType;
   }
-  return 'claude';
+  return Object.keys(aiConfigMap)[0] || 'claude';
 }
 
-function normalizeRequestedAiConfigTypes(options = {}, template = null, skipped = []) {
+function normalizeRequestedAiConfigTypes(options = {}, template = null, skipped = [], registry = getPlatformContext().registry) {
+  const aiConfigMap = getAiConfigMap(registry);
   let aiConfigTypes = options.aiConfigTypes;
   if (!aiConfigTypes) {
-    aiConfigTypes = options.aiConfigType ? [options.aiConfigType] : [getTemplateDefaultAiType(template)];
+    aiConfigTypes = options.aiConfigType ? [options.aiConfigType] : [getTemplateDefaultAiType(template, registry)];
   }
   if (!Array.isArray(aiConfigTypes)) {
     aiConfigTypes = [aiConfigTypes];
@@ -74,7 +112,7 @@ function normalizeRequestedAiConfigTypes(options = {}, template = null, skipped
     }
     const aiType = rawType.trim().toLowerCase();
     if (!aiType) continue;
-    if (!AI_CONFIG_MAP[aiType]) {
+    if (!aiConfigMap[aiType]) {
       pushSkipped(skipped, 'aiConfigType', aiType, `不支持的 AI 配置类型: ${aiType}`);
       continue;
     }
@@ -85,7 +123,7 @@ function normalizeRequestedAiConfigTypes(options = {}, template = null, skipped
   }
 
   if (normalized.length === 0) {
-    const fallbackType = getTemplateDefaultAiType(template);
+    const fallbackType = getTemplateDefaultAiType(template, registry);
     normalized.push(fallbackType);
     pushSkipped(skipped, 'aiConfigType', fallbackType, `未提供有效 AI 配置类型，已回退到默认类型: ${fallbackType}`);
   }
@@ -109,14 +147,14 @@ function resolveItemName(primary, fallback, defaultPrefix) {
   return `${defaultPrefix}-${Date.now()}`;
 }
 
-function normalizeAiConfigs(aiConfigs = {}, claudeMd = null) {
-  const normalized = {
-    claude: { enabled: false, content: '' },
-    codex: { enabled: false, content: '' },
-    gemini: { enabled: false, content: '' },
-    opencode: { enabled: false, content: '' },
-    omp: { enabled: false, content: '' }
-  };
+function normalizeAiConfigs(aiConfigs = {}, claudeMd = null, registry = getPlatformContext().registry) {
+  const keys = new Set([
+    ...Object.keys(getAiConfigMap(registry)),
+    ...Object.keys(aiConfigs || {})
+  ]);
+  const normalized = Object.fromEntries(
+    [...keys].map(key => [key, { enabled: false, content: '' }])
+  );
 
   for (const key of Object.keys(normalized)) {
     const cfg = aiConfigs?.[key];
@@ -128,7 +166,7 @@ function normalizeAiConfigs(aiConfigs = {}, claudeMd = null) {
     }
   }
 
-  if (claudeMd?.enabled && claudeMd?.content && !normalized.claude.content) {
+  if (claudeMd?.enabled && claudeMd?.content && normalized.claude && !normalized.claude.content) {
     normalized.claude = {
       enabled: true,
       content: claudeMd.content
@@ -136,7 +174,7 @@ function normalizeAiConfigs(aiConfigs = {}, claudeMd = null) {
   }
 
   // OpenCode defaults to Codex profile if not explicitly configured.
-  if (!normalized.opencode.content) {
+  if (normalized.opencode && !normalized.opencode.content) {
     const fallback = normalized.codex.content ? normalized.codex : normalized.claude;
     normalized.opencode = {
       enabled: !!fallback.enabled,
@@ -293,56 +331,34 @@ function deleteCustomTemplate(id) {
   throw new Error('模板不存在或不可删除');
 }
 
+const projectConfigServiceCache = new Map();
+
+function getProjectConfigService() {
+  if (!projectConfigServiceCache.has('default')) {
+    const { ProjectConfigService } = require('./project-config-service');
+    projectConfigServiceCache.set('default', new ProjectConfigService());
+  }
+  return projectConfigServiceCache.get('default');
+}
+
 /**
  * 应用模板到指定目录
  * @param {string} targetDir - 目标目录
  * @param {string} templateId - 模板 ID
  */
-function applyTemplate(targetDir, templateId) {
-  const template = getTemplateById(templateId);
-
-  if (!template) {
-    throw new Error('模板不存在');
-  }
-
-  // 确保目标目录存在
-  ensureDir(targetDir);
-
-  const results = {
-    claudeMd: false,
-    skills: 0,
-    commands: 0,
-    agents: 0,
-    plugins: 0,
-    mcpServers: 0
-  };
-
-  // 1. 应用 CLAUDE.md
-  if (template.claudeMd && template.claudeMd.enabled && template.claudeMd.content) {
-    const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
-    fs.writeFileSync(claudeMdPath, template.claudeMd.content, 'utf8');
-    results.claudeMd = true;
-  }
-
-  // 2. 创建配置记录文件（记录应用了哪个模板）
-  const configRecord = {
-    templateId: template.id,
-    templateName: template.name,
-    appliedAt: new Date().toISOString(),
-    skills: template.skills,
-    commands: template.commands,
-    agents: template.agents,
-    plugins: template.plugins,
-    mcpServers: template.mcpServers
-  };
-
-  const recordPath = path.join(targetDir, '.ctx-config.json');
-  fs.writeFileSync(recordPath, JSON.stringify(configRecord, null, 2), 'utf8');
-
+async function applyTemplate(targetDir, templateId) {
+  const result = await applyTemplateToProject(targetDir, templateId);
   return {
-    success: true,
-    results,
-    template: template.name
+    success: result.success,
+    results: {
+      claudeMd: result.results.aiConfigs.some(config => config.key === 'claude'),
+      skills: result.results.skills.applied,
+      commands: result.results.commands.applied,
+      agents: result.results.agents.applied,
+      plugins: result.results.plugins.applied,
+      mcpServers: result.results.mcpServers.applied
+    },
+    template: result.template
   };
 }
 
@@ -372,76 +388,84 @@ function readCurrentConfig(targetDir) {
  * 获取所有可用配置（用于模板编辑器选择）
  * 返回用户级的 agents, commands, plugins + MCP 服务器列表
  */
-function getAvailableConfigs() {
-  const agentPlatforms = ['claude', 'codex', 'gemini', 'opencode'];
-  const commandPlatforms = ['claude', 'codex', 'gemini', 'opencode', 'omp'];
+function getAvailableConfigs(options = {}) {
+  const registry = getTemplateRegistry(options);
+  const platforms = getTemplatePlatforms(registry);
+  const agentPlatforms = platforms
+    .filter(platform => getProjectResourceDescriptor(platform.key, 'agents', registry))
+    .map(platform => platform.key);
+  const commandPlatforms = platforms
+    .filter(platform => getProjectResourceDescriptor(platform.key, 'commands', registry))
+    .map(platform => platform.key);
   const agentMap = new Map();
   const commandMap = new Map();
   const agentsByPlatform = {};
   const commandsByPlatform = {};
 
   for (const platform of agentPlatforms) {
-    const service = new AgentsService(platform);
-    const { agents } = service.listAgents();
-    for (const agent of agents || []) {
-      if (agent.scope !== 'user') continue;
-      const normalizedAgent = {
-        fileName: agent.fileName,
-        name: agent.name,
-        description: agent.description,
-        tools: agent.tools,
-        model: agent.model,
-        permissionMode: agent.permissionMode,
-        skills: agent.skills,
-        systemPrompt: agent.systemPrompt
-      };
-      agentsByPlatform[platform] = agentsByPlatform[platform] || [];
-      agentsByPlatform[platform].push(normalizedAgent);
-      const key = `${agent.fileName || agent.name}|${agent.model || ''}|${agent.description || ''}`;
-      if (!agentMap.has(key)) {
-        agentMap.set(key, normalizedAgent);
+    let service;
+    try {
+      service = new AgentsService(platform, { registry });
+      const { agents } = service.listAgents();
+      for (const agent of agents || []) {
+        if (agent.scope !== 'user') continue;
+        const detail = typeof service.getAgent === 'function' ? (service.getAgent(agent.fileName, 'user') || agent) : agent;
+        const normalizedAgent = { fileName: agent.fileName, name: agent.name, description: agent.description, tools: agent.tools, model: agent.model, permissionMode: agent.permissionMode, skills: agent.skills, systemPrompt: detail.systemPrompt };
+        agentsByPlatform[platform] = agentsByPlatform[platform] || [];
+        agentsByPlatform[platform].push(normalizedAgent);
+        const key = `${agent.fileName || agent.name}|${agent.model || ''}|${agent.description || ''}`;
+        if (!agentMap.has(key)) agentMap.set(key, normalizedAgent);
       }
+    } finally {
+      service?.dispose?.();
     }
   }
 
   for (const platform of commandPlatforms) {
-    const service = new CommandsService(platform);
-    const { commands } = service.listCommands();
-    for (const command of commands || []) {
-      if (command.scope !== 'user') continue;
-      const normalizedCommand = {
-        name: command.name,
-        namespace: command.namespace,
-        description: command.description,
-        allowedTools: command.allowedTools,
-        argumentHint: command.argumentHint,
-        body: command.body
-      };
-      commandsByPlatform[platform] = commandsByPlatform[platform] || [];
-      commandsByPlatform[platform].push(normalizedCommand);
-      const key = command.namespace ? `${command.namespace}/${command.name}` : command.name;
-      if (!commandMap.has(key)) {
-        commandMap.set(key, normalizedCommand);
+    let service;
+    try {
+      service = new CommandsService(platform, { registry });
+      const { commands } = service.listCommands();
+      for (const command of commands || []) {
+        if (command.scope !== 'user') continue;
+        const detail = typeof service.getCommand === 'function' ? (service.getCommand(command.name, 'user', null, command.namespace) || command) : command;
+        const normalizedCommand = { name: command.name, namespace: command.namespace, description: command.description, allowedTools: command.allowedTools, argumentHint: command.argumentHint, body: detail.body };
+        commandsByPlatform[platform] = commandsByPlatform[platform] || [];
+        commandsByPlatform[platform].push(normalizedCommand);
+        const key = command.namespace ? `${command.namespace}/${command.name}` : command.name;
+        if (!commandMap.has(key)) commandMap.set(key, normalizedCommand);
       }
+    } finally {
+      service?.dispose?.();
     }
   }
-
   // 按平台分别获取 skills（每个平台有独立的安装目录）
   const skillsByPlatform = {};
-  for (const platform of ['claude', 'codex', 'gemini', 'opencode', 'omp']) {
-    const service = new SkillService(platform);
-    skillsByPlatform[platform] = service.getInstalledSkills().map(skill => ({
-      directory: skill.directory,
-      name: skill.name || skill.directory,
-      description: skill.description || '',
-      repoOwner: skill.repoOwner || null,
-      repoName: skill.repoName || null,
-      repoBranch: skill.repoBranch || null
-    }));
+  for (const platform of platforms
+    .filter(item => getProjectResourceDescriptor(item.key, 'skills', registry))
+    .map(item => item.key)) {
+    const service = new SkillService(platform, { registry });
+    skillsByPlatform[platform] = service.getInstalledSkills().map(skill => {
+      const normalized = {
+        directory: skill.directory,
+        name: skill.name || skill.directory,
+        description: skill.description || '',
+        repoOwner: skill.repoOwner || null,
+        repoName: skill.repoName || null,
+        repoBranch: skill.repoBranch || null
+      };
+      for (const key of ['fullDirectory', 'repoProvider', 'repoHost', 'repoId', 'repoDirectory', 'repoProjectPath', 'repoLocalPath', 'repoUrl']) {
+        if (skill[key] !== undefined && skill[key] !== null && skill[key] !== '') {
+          normalized[key] = skill[key];
+        }
+      }
+      return normalized;
+    });
   }
 
   // 获取已安装的插件和市场插件
-  const { plugins: installedPlugins } = pluginsService.listPlugins();
+  const configuredPluginsService = new PluginsService({ registry });
+  const { plugins: installedPlugins } = configuredPluginsService.listPlugins();
 
   // 获取 MCP 服务器
   const mcpServers = mcpService.getAllServers();
@@ -469,6 +493,15 @@ function getAvailableConfigs() {
   }));
 
   return {
+    platforms: platforms.map(platform => ({
+      key: platform.key,
+      label: platform.label || platform.title || platform.key,
+      title: platform.title || platform.label || platform.key,
+      promptFile: platform.promptFile || null,
+      promptLabel: platform.promptLabel || null,
+      resourceTypes: platform.resourceTypes || {},
+      projectResources: platform.projectResources || {}
+    })),
     skillsByPlatform,
     agents: Array.from(agentMap.values()),
     agentsByPlatform,
@@ -519,110 +552,91 @@ function buildTemplateCommandFileName(commandName, format) {
   return `${commandName}.${format === 'gemini' ? 'toml' : 'md'}`;
 }
 
-function getCommandPreviewExtension(prefix) {
-  return prefix === '.gemini/commands' ? 'toml' : 'md';
+function getCommandPreviewExtension(format) {
+  return format === 'gemini' ? 'toml' : 'md';
 }
 
-function writeJsonFile(filePath, data) {
+function writeAtomicFile(filePath, content, rootDir = null) {
+  if (rootDir) {
+    assertNoSymlinkComponents(path.resolve(rootDir), path.dirname(filePath), fs);
+  }
   ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  if (rootDir) {
+    assertNoSymlinkComponents(path.resolve(rootDir), path.dirname(filePath), fs);
+  }
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
+  let fileDescriptor;
+  try {
+    const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0);
+    fileDescriptor = fs.openSync(tempPath, flags, 0o600);
+    if (rootDir) {
+      const tempRealPath = fs.realpathSync(tempPath);
+      const rootRealPath = fs.realpathSync(path.resolve(rootDir));
+      const relative = path.relative(rootRealPath, tempRealPath);
+      if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('Template atomic write escaped project root');
+      }
+    }
+    fs.writeFileSync(fileDescriptor, content, 'utf-8');
+    fs.closeSync(fileDescriptor);
+    fileDescriptor = undefined;
+    if (rootDir) {
+      assertNoSymlinkComponents(path.resolve(rootDir), path.dirname(filePath), fs);
+    }
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    if (fileDescriptor !== undefined) {
+      try {
+        fs.closeSync(fileDescriptor);
+      } catch (_) {}
+    }
+    try {
+      if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+    } catch (_) {}
+    throw error;
+  }
 }
 
-function writeYamlFile(filePath, data) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, yaml.dump(data || {}, {
+function writeJsonFile(filePath, data, rootDir = null) {
+  writeAtomicFile(filePath, JSON.stringify(data, null, 2), rootDir);
+}
+
+function writeYamlFile(filePath, data, rootDir = null) {
+  writeAtomicFile(filePath, yaml.dump(data || {}, {
     lineWidth: 120,
     noRefs: true,
     sortKeys: false
-  }), 'utf-8');
+  }), rootDir);
 }
 
-function mergeOmpProjectPackages(targetDir, plugins = []) {
+function mergeOmpProjectPackages(targetDir, plugins = [], relativePath) {
   const packages = plugins.map(plugin => plugin.name).filter(Boolean);
-  if (packages.length === 0) {
+  if (packages.length === 0 || !relativePath) {
     return false;
   }
 
-  const ompDir = path.join(targetDir, '.omp');
-  const settingsPath = path.join(ompDir, 'config.yml');
+  const settingsPath = resolveProjectTarget(targetDir, relativePath, 'template OMP config');
   let settings = {};
   if (fs.existsSync(settingsPath)) {
+    let parsed;
     try {
-      const parsed = yaml.load(fs.readFileSync(settingsPath, 'utf-8'));
-      settings = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-    } catch (err) {
-      settings = {};
+      parsed = yaml.load(fs.readFileSync(settingsPath, 'utf-8'));
+    } catch (error) {
+      throw new Error(`无法解析 OMP 项目配置: ${error.message}`);
+    }
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      settings = parsed;
+    } else {
+      throw new Error('无法解析 OMP 项目配置: 配置必须是对象');
     }
   }
 
   const existingPackages = Array.isArray(settings.packages) ? settings.packages : [];
   settings.packages = Array.from(new Set([...existingPackages, ...packages]));
-  writeYamlFile(settingsPath, settings);
+  writeYamlFile(settingsPath, settings, targetDir);
   return true;
 }
 
-/**
- * 转换为 OpenCode MCP 结构（local/remote）
- */
-function convertToOpenCodeMcpSpec(spec = {}) {
-  const type = spec.type || 'stdio';
-
-  if (type === 'local' || type === 'remote') {
-    return { ...spec };
-  }
-
-  if (type === 'stdio') {
-    const command = [];
-    if (spec.command) command.push(spec.command);
-    if (Array.isArray(spec.args)) command.push(...spec.args);
-
-    const result = {
-      type: 'local',
-      command
-    };
-
-    if (spec.env && typeof spec.env === 'object') {
-      result.environment = spec.env;
-    }
-    if (spec.cwd) {
-      result.cwd = spec.cwd;
-    }
-    return result;
-  }
-
-  const result = {
-    type: 'remote',
-    url: spec.url || ''
-  };
-  if (spec.headers && typeof spec.headers === 'object') {
-    result.headers = spec.headers;
-  }
-  return result;
-}
-
-function convertToOmpMcpSpec(spec = {}) {
-  const type = spec.type || 'stdio';
-  const copyCommonFields = (target) => {
-    for (const key of ['timeout', 'auth', 'oauth']) {
-      if (spec[key] !== undefined) {
-        target[key] = spec[key];
-      }
-    }
-    return target;
-  };
-
-  if (type === 'streamable_http') {
-    const result = {
-      type: 'http',
-      url: spec.url || ''
-    };
-    if (spec.headers && typeof spec.headers === 'object') {
-      result.headers = spec.headers;
-    }
-    return copyCommonFields(result);
-  }
-  return copyCommonFields({ ...spec });
-}
 
 /**
  * 应用模板到项目目录（完整应用，写入实际文件）
@@ -632,17 +646,16 @@ function convertToOmpMcpSpec(spec = {}) {
  * @param {string|string[]} options.aiConfigTypes - 选择的 AI 配置类型数组: ['claude', 'codex', 'gemini', 'opencode', 'omp']
  * @param {string} options.aiConfigType - (兼容旧版) 单个 AI 配置类型
  */
-function applyTemplateToProject(targetDir, templateId, options = {}) {
+async function applyTemplateToProject(targetDir, templateId, options = {}) {
   const template = getTemplateById(templateId);
   if (!template) {
     throw new Error('模板不存在');
   }
 
-  ensureDir(targetDir);
-
+  const projectConfigService = getProjectConfigService();
   const results = {
     aiConfigs: [],
-    skills: { applied: template.skills?.length || 0, items: template.skills?.map(s => s.directory || s.name) || [] },
+    skills: { applied: 0, items: [] },
     agents: { applied: 0, files: [] },
     commands: { applied: 0, files: [] },
     plugins: { applied: 0, items: [] },
@@ -650,48 +663,109 @@ function applyTemplateToProject(targetDir, templateId, options = {}) {
     skipped: []
   };
 
-  const aiConfigTypes = normalizeRequestedAiConfigTypes(options, template, results.skipped);
+  const registry = getTemplateRegistry(options);
+  const aiConfigMap = getAiConfigMap(registry);
+  const aiConfigTypes = normalizeRequestedAiConfigTypes(options, template, results.skipped, registry);
 
   for (const aiConfigType of aiConfigTypes) {
     const aiConfig = resolveAiConfig(template, aiConfigType);
-    const configInfo = AI_CONFIG_MAP[aiConfigType];
+    const configInfo = aiConfigMap[aiConfigType];
     if (!configInfo?.fileName) {
-      pushSkipped(results.skipped, 'aiConfig', configInfo?.name || aiConfigType, 'OMP 项目级命令模板通过 .omp/commands 写入，未生成单独 AI 配置文件');
+      const reason = aiConfigType === 'omp'
+        ? 'OMP 项目级命令模板通过 .omp/commands 写入，未生成单独 AI 配置文件'
+        : `平台 ${configInfo?.name || aiConfigType} 未声明项目级配置文件，已跳过`;
+      pushSkipped(results.skipped, 'aiConfig', configInfo?.name || aiConfigType, reason);
     } else if (aiConfig?.enabled && aiConfig?.content) {
-      const configPath = path.join(targetDir, configInfo.fileName);
-      ensureDir(path.dirname(configPath));
-      fs.writeFileSync(configPath, aiConfig.content, 'utf-8');
-      results.aiConfigs.push({ applied: true, path: configInfo.fileName, type: configInfo.name, key: aiConfigType });
+      try {
+        const written = await projectConfigService.writeInstruction(targetDir, aiConfigType, aiConfig.content);
+        if (written?.supported === false) {
+          pushSkipped(results.skipped, 'aiConfig', configInfo.fileName, `平台 ${configInfo.name} 不支持项目级指令文件，已跳过`);
+        } else {
+          results.aiConfigs.push({
+            applied: true,
+            path: written?.path || configInfo.fileName,
+            type: configInfo.name,
+            key: aiConfigType
+          });
+        }
+      } catch (error) {
+        pushSkipped(results.skipped, 'aiConfig', configInfo.fileName, `写入项目级指令失败: ${error.message}`);
+      }
     } else {
-      const fileName = AI_CONFIG_MAP[aiConfigType]?.fileName || aiConfigType;
+      const fileName = aiConfigMap[aiConfigType]?.fileName || aiConfigType;
       pushSkipped(results.skipped, 'aiConfig', fileName, `模板未启用 ${fileName}，已跳过`);
     }
   }
 
-  if (template.agents?.length > 0) {
-    const agentTargets = [];
-    if (aiConfigTypes.includes('claude')) {
-      agentTargets.push({ baseDir: path.join(targetDir, '.claude', 'agents'), prefix: '.claude/agents' });
-    }
-    if (aiConfigTypes.includes('opencode')) {
-      agentTargets.push({ baseDir: path.join(targetDir, '.opencode', 'agents'), prefix: '.opencode/agents' });
-    }
-    if (aiConfigTypes.includes('gemini')) {
-      agentTargets.push({ baseDir: path.join(targetDir, '.gemini', 'agents'), prefix: '.gemini/agents' });
+  for (const skill of template.skills || []) {
+    const skillPlatform = skill?.platform || template.cliType || aiConfigTypes[0];
+    const skillName = typeof skill === 'string' ? skill : (skill?.directory || skill?.name);
+    if (!skillName) continue;
+    if (!skillPlatform || !aiConfigTypes.includes(skillPlatform)) {
+      pushSkipped(results.skipped, 'skill', skillName, `未选择 ${skillPlatform || '目标平台'}，已跳过`);
+      continue;
     }
 
-    for (const target of agentTargets) {
-      ensureDir(target.baseDir);
+    const skillInput = typeof skill === 'string'
+      ? { directory: skill, name: skill }
+      : {
+        directory: skill.directory || skill.name,
+        name: skill.name || skill.directory,
+        ...(skill.fullDirectory ? { fullDirectory: skill.fullDirectory } : {}),
+        ...(Array.isArray(skill.files) ? { files: skill.files } : {}),
+        ...(skill.repo
+          ? { repo: skill.repo }
+          : ((skill.repoProvider || skill.repoId || skill.repoLocalPath || skill.repoProjectPath)
+            ? {
+              repo: {
+                provider: skill.repoProvider,
+                owner: skill.repoOwner || null,
+                name: skill.repoName || null,
+                branch: skill.repoBranch || null,
+                directory: skill.repoDirectory || '',
+                host: skill.repoHost || null,
+                projectPath: skill.repoProjectPath || null,
+                localPath: skill.repoLocalPath || null,
+                id: skill.repoId || null,
+                repoUrl: skill.repoUrl || null
+              }
+            }
+            : {}))
+      };
+
+    try {
+      const skillService = new SkillService(skillPlatform);
+      const registration = skillService.registerTemplateSkill({
+        ...skillInput,
+        scope: 'project',
+        cwd: targetDir
+      });
+      if (registration?.status === 'pending_refresh') {
+        results.skills.pending = (results.skills.pending || 0) + 1;
+        results.skills.pendingItems = [...(results.skills.pendingItems || []), skillName];
+      } else if (registration?.status === 'failed') {
+        pushSkipped(results.skipped, 'skill', skillName, '项目级 Skill 注册失败，已跳过');
+      } else {
+        results.skills.applied++;
+      }
+      results.skills.items.push(skillName);
+    } catch (error) {
+      pushSkipped(results.skipped, 'skill', skillName, `注册项目级 Skill 失败: ${error.message}`);
     }
+  }
+
+  if (template.agents?.length > 0) {
+    const agentTargets = getProjectResourceTargets(aiConfigTypes, 'agents', registry);
 
     for (const agent of template.agents) {
       const fileName = resolveItemName(agent.fileName, agent.name, 'agent').toLowerCase().replace(/\s+/g, '-');
       const content = generateAgentContent(agent);
       let written = false;
       for (const target of agentTargets) {
-        const filePath = path.join(target.baseDir, `${fileName}.md`);
-        fs.writeFileSync(filePath, content, 'utf-8');
-        results.agents.files.push(`${target.prefix}/${fileName}.md`);
+        const relativePath = `${target.prefix}/${fileName}.md`;
+        const filePath = resolveProjectTarget(targetDir, relativePath, 'template agent file');
+        writeAtomicFile(filePath, content, targetDir);
+        results.agents.files.push(relativePath);
         written = true;
       }
       if (aiConfigTypes.includes('codex')) {
@@ -707,26 +781,7 @@ function applyTemplateToProject(targetDir, templateId, options = {}) {
   }
 
   if (template.commands?.length > 0) {
-    const commandTargets = [];
-    if (aiConfigTypes.includes('claude')) {
-      commandTargets.push({ baseDir: path.join(targetDir, '.claude', 'commands'), prefix: '.claude/commands', format: 'claude' });
-    }
-    if (aiConfigTypes.includes('codex')) {
-      commandTargets.push({ baseDir: path.join(targetDir, '.codex', 'prompts'), prefix: '.codex/prompts', format: 'codex' });
-    }
-    if (aiConfigTypes.includes('opencode')) {
-      commandTargets.push({ baseDir: path.join(targetDir, '.opencode', 'commands'), prefix: '.opencode/commands', format: 'claude' });
-    }
-    if (aiConfigTypes.includes('gemini')) {
-      commandTargets.push({ baseDir: path.join(targetDir, '.gemini', 'commands'), prefix: '.gemini/commands', format: 'gemini' });
-    }
-    if (aiConfigTypes.includes('omp')) {
-      commandTargets.push({ baseDir: path.join(targetDir, '.omp', 'commands'), prefix: '.omp/commands', format: 'omp' });
-    }
-
-    for (const target of commandTargets) {
-      ensureDir(target.baseDir);
-    }
+    const commandTargets = getProjectResourceTargets(aiConfigTypes, 'commands', registry);
 
     for (const command of template.commands) {
       const commandName = resolveItemName(command.name, null, 'command');
@@ -738,15 +793,12 @@ function applyTemplateToProject(targetDir, templateId, options = {}) {
         } else if (target.format === 'gemini') {
           content = convertCommandToGemini(content).content;
         }
-        const targetCmdDir = command.namespace
-          ? path.join(target.baseDir, command.namespace)
-          : target.baseDir;
-        ensureDir(targetCmdDir);
-        const filePath = path.join(targetCmdDir, buildTemplateCommandFileName(commandName, target.format));
-        fs.writeFileSync(filePath, content, 'utf-8');
+        const commandFile = buildTemplateCommandFileName(commandName, target.format);
         const relativePath = command.namespace
-          ? `${target.prefix}/${command.namespace}/${buildTemplateCommandFileName(commandName, target.format)}`
-          : `${target.prefix}/${buildTemplateCommandFileName(commandName, target.format)}`;
+          ? `${target.prefix}/${command.namespace}/${commandFile}`
+          : `${target.prefix}/${commandFile}`;
+        const filePath = resolveProjectTarget(targetDir, relativePath, 'template command file');
+        writeAtomicFile(filePath, content, targetDir);
         results.commands.files.push(relativePath);
         written = true;
       }
@@ -768,66 +820,71 @@ function applyTemplateToProject(targetDir, templateId, options = {}) {
   }
 
   const hasMcp = template.mcpServers?.length > 0;
-  const writesGenericMcpConfig = hasMcp && aiConfigTypes.some(type => type !== 'omp');
-  const writesOmpMcpConfig = hasMcp && aiConfigTypes.includes('omp');
-  const hasPluginsForOpenCode = aiConfigTypes.includes('opencode') && template.plugins?.length > 0;
-  const hasPluginsForOmp = aiConfigTypes.includes('omp') && template.plugins?.length > 0;
-  if (hasMcp || hasPluginsForOpenCode || hasPluginsForOmp) {
-    const mcpConfig = { mcpServers: {} };
-    const ompMcpConfig = { mcpServers: {} };
-    const opencodeConfig = { mcp: {}, plugin: [] };
+  const openCodePluginTarget = getProjectResourceDescriptor('opencode', 'plugins', registry);
+  const ompPluginTarget = getProjectResourceDescriptor('omp', 'plugins', registry);
+  const hasPluginsForOpenCode = Boolean(openCodePluginTarget && aiConfigTypes.includes('opencode') && template.plugins?.length > 0);
+  const hasPluginsForOmp = Boolean(ompPluginTarget && aiConfigTypes.includes('omp') && template.plugins?.length > 0);
+  if (hasMcp) {
     const allServers = mcpService.getAllServers();
     const presets = mcpService.getPresets();
 
     for (const serverId of template.mcpServers || []) {
-      // 先从已配置的服务器中查找
       let serverSpec = allServers[serverId]?.server;
-      // 如果没有，从预设中查找
       if (!serverSpec) {
         const preset = presets.find(p => p.id === serverId);
-        if (preset) {
-          serverSpec = preset.server;
-        }
+        if (preset) serverSpec = preset.server;
       }
-      if (serverSpec) {
-        if (writesGenericMcpConfig) {
-          mcpConfig.mcpServers[serverId] = serverSpec;
-        }
-        if (writesOmpMcpConfig) {
-          ompMcpConfig.mcpServers[serverId] = convertToOmpMcpSpec(serverSpec);
-        }
-        opencodeConfig.mcp[serverId] = convertToOpenCodeMcpSpec(serverSpec);
-        if (writesGenericMcpConfig || writesOmpMcpConfig) {
-          results.mcpServers.applied++;
-        }
-      } else {
+
+      if (!serverSpec) {
         pushSkipped(results.skipped, 'mcpServer', serverId, '未找到对应 MCP 服务配置，已跳过');
+        continue;
       }
-    }
 
-    if (writesGenericMcpConfig && Object.keys(mcpConfig.mcpServers).length > 0) {
-      const mcpPath = path.join(targetDir, '.mcp.json');
-      writeJsonFile(mcpPath, mcpConfig);
-    }
-
-    if (writesOmpMcpConfig && Object.keys(ompMcpConfig.mcpServers).length > 0) {
-      const ompMcpPath = path.join(targetDir, '.omp', 'mcp.json');
-      writeJsonFile(ompMcpPath, ompMcpConfig);
+      let applied = false;
+      for (const aiConfigType of aiConfigTypes) {
+        try {
+          const written = await projectConfigService.upsertProjectMcp(
+            targetDir,
+            aiConfigType,
+            serverId,
+            serverSpec
+          );
+          if (written?.success !== false) applied = true;
+        } catch (error) {
+          pushSkipped(
+            results.skipped,
+            'mcpServer',
+            `${serverId} (${aiConfigType})`,
+            `写入项目级 MCP 失败: ${error.message}`
+          );
+        }
+      }
+      if (applied) results.mcpServers.applied++;
     }
+  }
 
-    if (hasPluginsForOpenCode) {
-      opencodeConfig.plugin = (template.plugins || []).map(p => p.name).filter(Boolean);
-    }
-    if (aiConfigTypes.includes('opencode') && (Object.keys(opencodeConfig.mcp).length > 0 || opencodeConfig.plugin.length > 0)) {
-      const opencodeDir = path.join(targetDir, '.opencode');
-      ensureDir(opencodeDir);
-      const opencodePath = path.join(opencodeDir, 'opencode.json');
-      writeJsonFile(opencodePath, opencodeConfig);
+  if (hasPluginsForOpenCode) {
+    const opencodePath = resolveProjectTarget(targetDir, openCodePluginTarget.prefix, 'template OpenCode config');
+    let opencodeConfig = {};
+    if (fs.existsSync(opencodePath)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(fs.readFileSync(opencodePath, 'utf-8'));
+      } catch (error) {
+        throw new Error(`无法解析 OpenCode 项目配置: ${error.message}`);
+      }
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        opencodeConfig = parsed;
+      } else {
+        throw new Error('无法解析 OpenCode 项目配置: 配置必须是对象');
+      }
     }
+    opencodeConfig.plugin = (template.plugins || []).map(p => p.name).filter(Boolean);
+    writeJsonFile(opencodePath, opencodeConfig, targetDir);
+  }
 
-    if (hasPluginsForOmp) {
-      mergeOmpProjectPackages(targetDir, template.plugins || []);
-    }
+  if (hasPluginsForOmp) {
+    mergeOmpProjectPackages(targetDir, template.plugins || [], ompPluginTarget.prefix);
   }
 
   const configRecord = {
@@ -843,8 +900,8 @@ function applyTemplateToProject(targetDir, templateId, options = {}) {
     mcpServers: template.mcpServers || [],
     skipped: results.skipped
   };
-  const recordPath = path.join(targetDir, '.ctx-config.json');
-  fs.writeFileSync(recordPath, JSON.stringify(configRecord, null, 2), 'utf-8');
+  const recordPath = resolveProjectTarget(targetDir, '.ctx-config.json', 'template provenance file');
+  writeAtomicFile(recordPath, JSON.stringify(configRecord, null, 2), targetDir);
 
   return {
     success: true,
@@ -882,15 +939,20 @@ function previewTemplateApplication(targetDir, templateId, options = {}) {
     }
   };
 
-  const aiConfigTypes = normalizeRequestedAiConfigTypes(options, template, preview.skipped);
+  const registry = getTemplateRegistry(options);
+  const aiConfigMap = getAiConfigMap(registry);
+  const aiConfigTypes = normalizeRequestedAiConfigTypes(options, template, preview.skipped, registry);
 
   for (const aiConfigType of aiConfigTypes) {
     const aiConfig = resolveAiConfig(template, aiConfigType);
-    const configInfo = AI_CONFIG_MAP[aiConfigType];
+    const configInfo = aiConfigMap[aiConfigType];
     if (!configInfo?.fileName) {
-      pushSkipped(preview.skipped, 'aiConfig', configInfo?.name || aiConfigType, 'OMP 项目级命令模板通过 .omp/commands 写入，预览不生成单独 AI 配置文件');
+      const reason = aiConfigType === 'omp'
+        ? 'OMP 项目级命令模板通过 .omp/commands 写入，预览不生成单独 AI 配置文件'
+        : `平台 ${configInfo?.name || aiConfigType} 未声明项目级配置文件，预览已跳过`;
+      pushSkipped(preview.skipped, 'aiConfig', configInfo?.name || aiConfigType, reason);
     } else if (aiConfig?.enabled && aiConfig?.content) {
-      const configPath = path.join(targetDir, configInfo.fileName);
+      const configPath = resolveProjectTarget(targetDir, configInfo.fileName, 'template instruction file');
       if (fs.existsSync(configPath)) {
         preview.willOverwrite.push(configInfo.fileName);
       } else {
@@ -898,7 +960,7 @@ function previewTemplateApplication(targetDir, templateId, options = {}) {
       }
       preview.summary.aiConfigs.push({ type: aiConfigType, fileName: configInfo.fileName, name: configInfo.name });
     } else {
-      const fileName = AI_CONFIG_MAP[aiConfigType]?.fileName || aiConfigType;
+      const fileName = aiConfigMap[aiConfigType]?.fileName || aiConfigType;
       pushSkipped(preview.skipped, 'aiConfig', fileName, `模板未启用 ${fileName}，已跳过`);
     }
   }
@@ -909,17 +971,14 @@ function previewTemplateApplication(targetDir, templateId, options = {}) {
   }
 
   if (template.agents?.length > 0) {
-    const agentPrefixes = [];
-    if (aiConfigTypes.includes('claude')) agentPrefixes.push('.claude/agents');
-    if (aiConfigTypes.includes('opencode')) agentPrefixes.push('.opencode/agents');
-    if (aiConfigTypes.includes('gemini')) agentPrefixes.push('.gemini/agents');
+    const agentTargets = getProjectResourceTargets(aiConfigTypes, 'agents', registry);
 
     for (const agent of template.agents) {
       const fileName = resolveItemName(agent.fileName, agent.name, 'agent').toLowerCase().replace(/\s+/g, '-');
       let applicable = false;
-      for (const prefix of agentPrefixes) {
-        const relativePath = `${prefix}/${fileName}.md`;
-        const fullPath = path.join(targetDir, relativePath);
+      for (const target of agentTargets) {
+        const relativePath = `${target.prefix}/${fileName}.md`;
+        const fullPath = resolveProjectTarget(targetDir, relativePath, 'template agent file');
         if (fs.existsSync(fullPath)) {
           preview.willOverwrite.push(relativePath);
         } else {
@@ -940,22 +999,17 @@ function previewTemplateApplication(targetDir, templateId, options = {}) {
   }
 
   if (template.commands?.length > 0) {
-    const commandPrefixes = [];
-    if (aiConfigTypes.includes('claude')) commandPrefixes.push('.claude/commands');
-    if (aiConfigTypes.includes('codex')) commandPrefixes.push('.codex/prompts');
-    if (aiConfigTypes.includes('opencode')) commandPrefixes.push('.opencode/commands');
-    if (aiConfigTypes.includes('gemini')) commandPrefixes.push('.gemini/commands');
-    if (aiConfigTypes.includes('omp')) commandPrefixes.push('.omp/commands');
+    const commandTargets = getProjectResourceTargets(aiConfigTypes, 'commands', registry);
 
     for (const command of template.commands) {
       const commandName = resolveItemName(command.name, null, 'command');
       let applicable = false;
-      for (const prefix of commandPrefixes) {
-        const extension = getCommandPreviewExtension(prefix);
+      for (const target of commandTargets) {
+        const extension = getCommandPreviewExtension(target.format);
         const relativePath = command.namespace
-          ? `${prefix}/${command.namespace}/${commandName}.${extension}`
-          : `${prefix}/${commandName}.${extension}`;
-        const fullPath = path.join(targetDir, relativePath);
+          ? `${target.prefix}/${command.namespace}/${commandName}.${extension}`
+          : `${target.prefix}/${commandName}.${extension}`;
+        const fullPath = resolveProjectTarget(targetDir, relativePath, 'template command file');
         if (fs.existsSync(fullPath)) {
           preview.willOverwrite.push(relativePath);
         } else {
@@ -969,8 +1023,16 @@ function previewTemplateApplication(targetDir, templateId, options = {}) {
     }
   }
 
-  const writesGenericMcpConfig = template.mcpServers?.length > 0 && aiConfigTypes.some(type => type !== 'omp');
-  const writesOmpMcpConfig = template.mcpServers?.length > 0 && aiConfigTypes.includes('omp');
+  const genericMcpTarget = getProjectResourceTargets(
+    aiConfigTypes.filter(type => type !== 'omp'),
+    'mcp',
+    registry
+  )[0];
+  const writesGenericMcpConfig = Boolean(
+    template.mcpServers?.length > 0 && aiConfigTypes.some(type => type !== 'omp') && genericMcpTarget
+  );
+  const ompMcpTarget = getProjectResourceDescriptor('omp', 'mcp', registry);
+  const writesOmpMcpConfig = Boolean(template.mcpServers?.length > 0 && aiConfigTypes.includes('omp') && ompMcpTarget);
   const allServers = mcpService.getAllServers();
   const presets = mcpService.getPresets();
   let resolvableMcpCount = 0;
@@ -992,43 +1054,46 @@ function previewTemplateApplication(targetDir, templateId, options = {}) {
   }
 
   if (writesGenericMcpConfig && resolvableMcpCount > 0) {
-    const mcpPath = path.join(targetDir, '.mcp.json');
+    const mcpRelativePath = genericMcpTarget.prefix;
+    const mcpPath = resolveProjectTarget(targetDir, mcpRelativePath, 'template MCP file');
     if (fs.existsSync(mcpPath)) {
-      preview.willOverwrite.push('.mcp.json');
+      preview.willOverwrite.push(mcpRelativePath);
     } else {
-      preview.willCreate.push('.mcp.json');
+      preview.willCreate.push(mcpRelativePath);
     }
     preview.summary.mcpServers = resolvableMcpCount;
   }
 
   if (writesOmpMcpConfig && resolvableMcpCount > 0) {
-    const ompMcpPath = path.join(targetDir, '.omp/mcp.json');
+    const ompMcpPath = resolveProjectTarget(targetDir, ompMcpTarget.prefix, 'template OMP MCP file');
     if (fs.existsSync(ompMcpPath)) {
-      preview.willOverwrite.push('.omp/mcp.json');
+      preview.willOverwrite.push(ompMcpTarget.prefix);
     } else {
-      preview.willCreate.push('.omp/mcp.json');
+      preview.willCreate.push(ompMcpTarget.prefix);
     }
     preview.summary.mcpServers = resolvableMcpCount;
   }
 
-  if (aiConfigTypes.includes('opencode') && (resolvableMcpCount > 0 || template.plugins?.length > 0)) {
-    const opencodeConfigPath = path.join(targetDir, '.opencode/opencode.json');
+  const openCodePluginTarget = getProjectResourceDescriptor('opencode', 'plugins', registry);
+  if (aiConfigTypes.includes('opencode') && openCodePluginTarget && (resolvableMcpCount > 0 || template.plugins?.length > 0)) {
+    const opencodeConfigPath = resolveProjectTarget(targetDir, openCodePluginTarget.prefix, 'template OpenCode config');
     if (fs.existsSync(opencodeConfigPath)) {
-      preview.willOverwrite.push('.opencode/opencode.json');
+      preview.willOverwrite.push(openCodePluginTarget.prefix);
     } else {
-      preview.willCreate.push('.opencode/opencode.json');
+      preview.willCreate.push(openCodePluginTarget.prefix);
     }
   }
 
   if (template.plugins?.length > 0) {
     if (aiConfigTypes.includes('opencode') || aiConfigTypes.includes('omp')) {
       preview.summary.plugins = template.plugins.length;
-      if (aiConfigTypes.includes('omp')) {
-        const ompSettingsPath = path.join(targetDir, '.omp/config.yml');
+      const ompPluginTarget = getProjectResourceDescriptor('omp', 'plugins', registry);
+      if (aiConfigTypes.includes('omp') && ompPluginTarget) {
+        const ompSettingsPath = resolveProjectTarget(targetDir, ompPluginTarget.prefix, 'template OMP config');
         if (fs.existsSync(ompSettingsPath)) {
-          preview.willOverwrite.push('.omp/config.yml');
+          preview.willOverwrite.push(ompPluginTarget.prefix);
         } else {
-          preview.willCreate.push('.omp/config.yml');
+          preview.willCreate.push(ompPluginTarget.prefix);
         }
       }
     } else {
@@ -1055,5 +1120,6 @@ module.exports = {
   readCurrentConfig,
   getAvailableConfigs,
   applyTemplateToProject,
-  previewTemplateApplication
+  previewTemplateApplication,
+  getAiConfigMap
 };