mcp-osp-prompt 1.0.0

package/prompt-manager.js

@@ -0,0 +1,1027 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { detectPlatformFromPath, parseRemotePath, createAuthHeaders } from './platform-utils.js';
+
+/**
+ * Prompt管理器
+ * 职责：
+ * 1. 同步初始化：首次加载确保工具列表完整可用
+ * 2. 统一缓存：管理文件列表和内容的TTL缓存
+ * 3. 异步更新：使用时异步检查TTL并更新
+ * 4. 提供prompt获取接口：对接fetcher.js
+ */
+class PromptManager {
+  constructor() {
+    this.cacheDir = process.env.CACHE_DIR || path.join(process.env.HOME || '.', '.cache', 'prompts');
+    this.ttl = parseInt(process.env.CACHE_TTL_SEC || '10800', 10) * 1000; // 转为毫秒，默认3小时
+    this.force = (process.env.FORCE_UPDATE || 'false').toLowerCase() === 'true';
+    this.token = process.env.GIT_TOKEN || process.env.GITLAB_TOKEN || process.env.GITHUB_TOKEN; // 支持多种token环境变量
+    this.platform = null;
+    this.resourcePath = null;
+    this.toolsConfig = [];
+    this.isInitialized = false;
+  }
+
+  /**
+   * 同步初始化 - 必须在MCP服务器启动时完成
+   * 确保工具列表完整可用
+   */
+  async initializeSync() {
+    if (this.isInitialized) {
+      return this.toolsConfig;
+    }
+
+    console.error('[PromptManager] Starting synchronous initialization...');
+    
+    // 🟢 GREEN: Task 1.1 - 确保resourcePath正确初始化
+    this.resourcePath = process.env.RESOURCE_PATH;
+    if (!this.resourcePath) {
+      throw new Error('RESOURCE_PATH environment variable is required');
+    }
+
+    this.platform = detectPlatformFromPath(this.resourcePath);
+    console.error(`[PromptManager] Platform: ${this.platform}, Path: ${this.resourcePath}`);
+
+    // 确保缓存目录存在（包括子目录）
+    await fs.mkdir(this.cacheDir, { recursive: true });
+    await fs.mkdir(path.join(this.cacheDir, 'projects'), { recursive: true });
+    await fs.mkdir(path.join(this.cacheDir, 'rules'), { recursive: true });
+
+    // 🟢 GREEN: Task 3.1 - 多目录资源同步（如果是远程平台）
+    if (this.platform !== 'local') {
+      console.error('[PromptManager] Checking multi-directory resources...');
+      
+      // 先尝试读取缓存
+      const cachedResources = await this.readCachedMultiDirectoryResources();
+      const TTL_12_HOURS = 12 * 60 * 60 * 1000; // 12小时
+      
+      if (cachedResources && cachedResources.lastSync) {
+        const cacheAge = Date.now() - new Date(cachedResources.lastSync).getTime();
+        
+        if (cacheAge < TTL_12_HOURS && !this.force) {
+          // 缓存未过期，直接使用
+          console.error(`[PromptManager] ✅ Using cached resources (age: ${Math.round(cacheAge / 1000 / 60 / 60)}h)`);
+          this.toolsConfig = this.generateToolsConfig(cachedResources.prompts);
+        } else {
+          // 缓存过期，先使用缓存，然后异步更新
+          console.error(`[PromptManager] ⏳ Using cached resources (age: ${Math.round(cacheAge / 1000 / 60 / 60)}h), triggering async update...`);
+          this.toolsConfig = this.generateToolsConfig(cachedResources.prompts);
+          
+          // 异步更新（不阻塞）
+          this.fetchMultiDirectoryResources().then(() => {
+            console.error('[PromptManager] ✅ Async resource update complete');
+          }).catch(error => {
+            console.warn(`[PromptManager] ⚠️  Async resource update failed: ${error.message}`);
+          });
+        }
+      } else {
+        // 无缓存或缓存损坏，必须同步拉取
+        console.error('[PromptManager] 🔄 No cache found, fetching resources...');
+        try {
+          const resources = await this.fetchMultiDirectoryResources();
+          console.error(`[PromptManager] ✅ Resource fetch complete: ${resources.prompts.length} prompts, ${resources.projects.length} projects, ${resources.rules.length} rules`);
+          this.toolsConfig = this.generateToolsConfig(resources.prompts);
+        } catch (error) {
+          console.error(`[PromptManager] ❌ Resource fetch failed: ${error.message}`);
+          // 最后的fallback：使用旧的单目录逻辑
+          const promptFiles = await this.getPromptFilesList();
+          this.toolsConfig = this.generateToolsConfig(promptFiles);
+        }
+      }
+    } else {
+      // 本地模式：支持多目录资源
+      try {
+        console.error('[PromptManager] Local mode: Scanning multi-directory resources...');
+        const resources = await this.fetchLocalMultiDirectoryResources();
+        console.error(`[PromptManager] ✅ Local scan complete: ${resources.prompts.length} prompts, ${resources.projects.length} projects, ${resources.rules.length} rules`);
+        this.toolsConfig = this.generateToolsConfig(resources.prompts);
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Local multi-directory scan failed: ${error.message}, using single directory mode`);
+        const promptFiles = await this.getPromptFilesList();
+        this.toolsConfig = this.generateToolsConfig(promptFiles);
+      }
+    }
+
+    // 不再验证核心工具内容可用性，仅确保工具配置存在
+    this.validateToolsConfigExists();
+
+    this.isInitialized = true;
+    console.error(`[PromptManager] ✅ Initialization complete: ${this.toolsConfig.length} tools ready`);
+    
+    return this.toolsConfig;
+  }
+
+  /**
+   * 获取prompt文件列表（带缓存）
+   */
+  async getPromptFilesList() {
+    if (this.platform === 'local') {
+      return await this.scanLocalPromptFiles();
+    } else {
+      return await this.getRemotePromptFilesList();
+    }
+  }
+
+  /**
+   * 扫描本地prompt文件
+   */
+  async scanLocalPromptFiles() {
+    try {
+      const files = await fs.readdir(this.resourcePath);
+      const promptFiles = files
+        .filter(file => file.endsWith('.prompt.md'))
+        .map(filename => {
+          const baseName = filename.replace('.prompt.md', '');
+          return {
+            filename,
+            toolName: `dev-${baseName}`,
+            source: filename,
+            platform: 'local'
+          };
+        });
+
+      console.error(`[PromptManager] Local scan: ${promptFiles.length} files found`);
+      return promptFiles;
+  } catch (error) {
+      throw new Error(`Failed to scan local prompt directory: ${error.message}`);
+  }
+}
+
+  /**
+   * 获取远程prompt文件列表（启动阶段逻辑）
+   * 🟢 GREEN: Task 1.1 - 修正启动逻辑：只要有缓存就立即启动+异步更新
+   */
+  async getRemotePromptFilesList() {
+    const fileListCache = path.join(this.cacheDir, 'file-list.json');
+    
+    // 检查缓存是否存在
+    if (!this.force) {
+      try {
+        const stat = await fs.stat(fileListCache);
+        const cacheAge = Date.now() - stat.mtimeMs;
+        const cacheAgeMinutes = Math.round(cacheAge / 1000 / 60);
+        
+        // 读取缓存内容
+        const cachedList = JSON.parse(await fs.readFile(fileListCache, 'utf8'));
+        
+        // 🔧 关键修正：启动时不区分缓存新鲜度，只要有缓存就立即启动+异步更新
+        console.error(`[PromptManager] Using cached file list for startup (age: ${cacheAgeMinutes}min), scheduling async update`);
+        
+        // 启动阶段总是异步更新，确保缓存最新
+        this.asyncUpdateFileListCache().catch(error => {
+          console.warn(`[PromptManager] Async file list update failed: ${error.message}`);
+        });
+        
+        return cachedList;
+      } catch (_) {
+        // 缓存不存在，必须同步获取
+        console.error('[PromptManager] No cache found, fetching synchronously for startup');
+      }
+    }
+
+    // 无缓存时必须同步获取
+    return await this.fetchRemoteFileListSync();
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.1 - 同步获取远程文件列表
+   */
+  async fetchRemoteFileListSync() {
+    const fileListCache = path.join(this.cacheDir, 'file-list.json');
+    
+    console.error('[PromptManager] Fetching remote file list synchronously...');
+    const pathInfo = parseRemotePath(this.resourcePath);
+    if (!pathInfo) {
+      throw new Error(`Unable to parse RESOURCE_PATH: ${this.resourcePath}`);
+    }
+
+    try {
+      let promptFiles;
+      if (pathInfo.platform === 'gitlab') {
+        promptFiles = await this.fetchGitLabFileList(pathInfo);
+      } else if (pathInfo.platform === 'github') {
+        promptFiles = await this.fetchGitHubFileList(pathInfo);
+      } else {
+        throw new Error(`Unsupported platform: ${pathInfo.platform}`);
+      }
+
+      // 缓存文件列表
+      await fs.writeFile(fileListCache, JSON.stringify(promptFiles, null, 2), 'utf8');
+      console.error(`[PromptManager] Remote scan: ${promptFiles.length} files cached`);
+      
+      return promptFiles;
+    } catch (error) {
+      // API失败时尝试使用旧缓存作为最后手段
+      try {
+        const cachedList = await fs.readFile(fileListCache, 'utf8');
+        console.warn(`[PromptManager] API failed, using stale cache: ${error.message}`);
+        return JSON.parse(cachedList);
+      } catch (_) {
+        throw new Error(`Remote file list fetch failed and no cache available: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.1 - 异步更新文件列表缓存
+   */
+  async asyncUpdateFileListCache() {
+    try {
+      console.error('[PromptManager] Starting async file list update...');
+      const promptFiles = await this.fetchRemoteFileListSync();
+      console.error(`[PromptManager] ✅ Async file list update completed: ${promptFiles.length} files`);
+      return promptFiles;
+    } catch (error) {
+      console.warn(`[PromptManager] ⚠️ Async file list update failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.2 - 通用目录文件扫描函数
+   * @param {Object} pathInfo - 路径信息
+   * @param {String} filePattern - 文件模式 (*.prompt.md, *.md, *-code-rules.md)
+   * @param {String} dirType - 目录类型 (prompts, projects, rules)
+   * @returns {Array} 文件列表
+   */
+  async fetchDirectoryFiles(pathInfo, filePattern, dirType = 'prompts') {
+    if (!pathInfo || !filePattern) {
+      throw new Error('pathInfo and filePattern are required');
+    }
+    
+    const platform = pathInfo.platform;
+    console.error(`[PromptManager] Fetching ${dirType} files (pattern: ${filePattern}) from ${platform}...`);
+    
+    // 根据平台调用不同的API
+    let files = [];
+    if (platform === 'gitlab') {
+      files = await this.fetchGitLabDirectory(pathInfo);
+    } else if (platform === 'github') {
+      files = await this.fetchGitHubDirectory(pathInfo);
+    } else {
+      throw new Error(`Unsupported platform: ${platform}`);
+    }
+    
+    // 根据文件模式过滤和映射
+    return this.filterAndMapFiles(files, filePattern, dirType, pathInfo);
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.2 - 从GitLab获取目录文件（原始数据）
+   */
+  async fetchGitLabDirectory(pathInfo) {
+    const headers = createAuthHeaders('gitlab', process.env.GIT_TOKEN);
+    console.error(`[PromptManager] GitLab API call: ${pathInfo.apiUrl}`);
+    const requestOptions = { headers, timeout: 10000 };
+    const response = await fetch(pathInfo.apiUrl, requestOptions);
+    
+    if (!response.ok) {
+      const debugHeaders = { ...headers };
+      const requestInfo = `
+        REQUEST INFO: \n
+        - URL: ${pathInfo.apiUrl} \n
+        - Method: GET \n
+        - Headers: ${JSON.stringify(debugHeaders, null, 2)} \n
+        - Timeout: ${requestOptions.timeout}ms \n
+        - Response Status: ${response.status} \n
+        - Response StatusText: ${response.statusText} \n`;
+      throw new Error(`GitLab API error: ${requestInfo}`);
+    }
+    
+    return await response.json();
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.2 - 从GitHub获取目录文件（原始数据）
+   */
+  async fetchGitHubDirectory(pathInfo) {
+    const url = `${pathInfo.apiUrl}?ref=${pathInfo.branch}`;
+    const headers = createAuthHeaders('github', process.env.GIT_TOKEN);
+    console.error(`[PromptManager] GitHub API call: ${url}`);
+    const requestOptions = { headers, timeout: 10000 };
+    const response = await fetch(url, requestOptions);
+    
+    if (!response.ok) {
+      const debugHeaders = { ...headers };
+      const requestInfo = `
+        REQUEST INFO: \n
+        - URL: ${url} \n
+        - Method: GET \n
+        - Headers: ${JSON.stringify(debugHeaders, null, 2)} \n
+        - Timeout: ${requestOptions.timeout}ms \n
+        - Response Status: ${response.status} \n
+        - Response StatusText: ${response.statusText} \n`;
+      throw new Error(`GitHub API error: ${requestInfo}`);
+    }
+    
+    return await response.json();
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.2 - 根据文件模式过滤和映射文件
+   */
+  filterAndMapFiles(files, filePattern, dirType, pathInfo) {
+    // 转换filePattern为正则表达式 - 先转义点，再替换星号
+    const pattern = filePattern.replace(/\./g, '\\.').replace(/\*/g, '.*');
+    const regex = new RegExp(`^${pattern}$`);
+    
+    const platform = pathInfo.platform;
+    const fileTypeKey = platform === 'gitlab' ? 'blob' : 'file';
+    
+    return files
+      .filter(file => {
+        const isFile = platform === 'gitlab' ? file.type === 'blob' : file.type === 'file';
+        return isFile && regex.test(file.name);
+      })
+      .map(file => {
+        const mapped = {
+          filename: file.name,
+          path: `${pathInfo.path ? pathInfo.path + '/' : ''}${file.name}`,
+          platform: platform
+        };
+        
+        // 根据目录类型添加额外信息
+        if (dirType === 'prompts') {
+          const baseName = file.name.replace('.prompt.md', '');
+          mapped.toolName = `dev-${baseName}`;
+          mapped.source = mapped.path;
+        } else if (dirType === 'rules') {
+          // 提取语言名称 (java-code-rules.md -> java)
+          const langMatch = file.name.match(/^(.+)-code-rules\.md$/);
+          if (langMatch) {
+            mapped.language = langMatch[1];
+          }
+        } else if (dirType === 'projects') {
+          // projects目录，保留原始文件名
+          mapped.type = 'project-doc';
+        }
+        
+        return mapped;
+      });
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.2 - 从GitLab获取文件列表（重构为使用通用函数）
+   */
+  async fetchGitLabFileList(pathInfo) {
+    return await this.fetchDirectoryFiles(pathInfo, '*.prompt.md', 'prompts');
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.2 - 从GitHub获取文件列表（重构为使用通用函数）
+   */
+  async fetchGitHubFileList(pathInfo) {
+    return await this.fetchDirectoryFiles(pathInfo, '*.prompt.md', 'prompts');
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.4 - 缓存多目录资源
+   * @param {Object} resources - 资源对象 { prompts, projects, rules, lastSync }
+   */
+  async cacheMultiDirectoryResources(resources) {
+    const cacheFile = path.join(this.cacheDir, 'resource-cache.json');
+    
+    try {
+      await fs.writeFile(cacheFile, JSON.stringify(resources, null, 2), 'utf8');
+      console.error(`[PromptManager] ✅ Resources cached to ${cacheFile}`);
+      
+      // 同时保留旧格式的file-list.json用于向后兼容
+      const legacyCache = path.join(this.cacheDir, 'file-list.json');
+      await fs.writeFile(legacyCache, JSON.stringify(resources.prompts, null, 2), 'utf8');
+      
+    } catch (error) {
+      console.warn(`[PromptManager] ⚠️  Failed to cache resources: ${error.message}`);
+    }
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.4 - 读取缓存的多目录资源
+   * @returns {Object|null} 资源对象或null
+   */
+  async readCachedMultiDirectoryResources() {
+    const cacheFile = path.join(this.cacheDir, 'resource-cache.json');
+    
+    try {
+      const data = await fs.readFile(cacheFile, 'utf8');
+      const resources = JSON.parse(data);
+      
+      // 验证缓存结构
+      if (resources && resources.prompts && resources.projects && resources.rules) {
+        console.error(`[PromptManager] ✅ Loaded cached resources (${resources.prompts.length + resources.projects.length + resources.rules.length} total files)`);
+        return resources;
+      }
+      
+      return null;
+    } catch (error) {
+      console.warn(`[PromptManager] No valid resource cache found: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.4 - 检查缓存是否过期
+   * @param {Object} resources - 资源对象
+   * @returns {boolean} true表示过期
+   */
+  isCacheExpired(resources) {
+    if (!resources || !resources.lastSync) {
+      return true;
+    }
+    
+    const lastSyncTime = new Date(resources.lastSync).getTime();
+    const now = Date.now();
+    const ttlMs = this.ttl * 1000;
+    const age = now - lastSyncTime;
+    
+    const expired = age >= ttlMs;
+    console.error(`[PromptManager] Cache age: ${Math.round(age / 1000)}s, TTL: ${this.ttl}s, Expired: ${expired}`);
+    
+    return expired;
+  }
+
+  /**
+   * 🟢 GREEN: Task 1.3 - 多目录资源拉取主函数
+   * @returns {Object} { prompts: [], projects: [], rules: [], lastSync: ISO时间 }
+   */
+  async fetchMultiDirectoryResources() {
+    const directories = [
+      { name: 'prompts', pattern: '*.prompt.md', type: 'prompts' },
+      { name: 'projects', pattern: '*.md', type: 'projects' },
+      { name: 'rules', pattern: '*-rules.md', type: 'rules' }
+    ];
+    
+    const results = {
+      prompts: [],
+      projects: [],
+      rules: [],
+      lastSync: new Date().toISOString()
+    };
+    
+    console.error('[PromptManager] Fetching multi-directory resources...');
+    
+    // 依次拉取各个目录（错误容错，单个失败不影响其他）
+    for (const dir of directories) {
+      try {
+        console.error(`[PromptManager] Fetching ${dir.name} directory...`);
+        
+        // 使用parseRemotePath的子目录功能
+        const pathInfo = parseRemotePath(this.resourcePath, dir.name);
+        
+        // 使用通用扫描函数
+        const files = await this.fetchDirectoryFiles(pathInfo, dir.pattern, dir.type);
+        
+        results[dir.type] = files;
+        console.error(`[PromptManager] ✅ ${dir.name}: ${files.length} files`);
+        
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Failed to fetch ${dir.name}: ${error.message}`);
+        results[dir.type] = []; // 失败时使用空数组
+      }
+    }
+    
+    console.error(`[PromptManager] Multi-directory fetch complete. Total: ${results.prompts.length + results.projects.length + results.rules.length} files`);
+    
+    // 🟢 GREEN: Task 3.1 - 保存文件内容到子目录
+    await this.saveResourceContents(results);
+    
+    // 🟢 GREEN: Task 1.4 - 自动缓存结果
+    await this.cacheMultiDirectoryResources(results);
+    
+    return results;
+  }
+
+  /**
+   * 🟢 GREEN: 本地多目录资源扫描
+   * @returns {Object} { prompts: [], projects: [], rules: [], lastSync: ISO时间 }
+   */
+  async fetchLocalMultiDirectoryResources() {
+    // 假设 RESOURCE_PATH 指向包含 prompts/projects/rules 子目录的基础目录
+    // 或者直接指向 prompts 目录，此时需要找到父目录
+    
+    let baseDir = this.resourcePath;
+    
+    // 如果 RESOURCE_PATH 直接指向 prompts 目录，找到父目录
+    if (baseDir.endsWith('/prompts') || baseDir.endsWith('\\prompts')) {
+      baseDir = path.dirname(baseDir);
+    }
+    
+    const directories = [
+      { name: 'prompts', pattern: /\.prompt\.md$/, type: 'prompts' },
+      { name: 'projects', pattern: /\.md$/, type: 'projects' },
+      { name: 'rules', pattern: /-rules\.md$/, type: 'rules' }
+    ];
+    
+    const results = {
+      prompts: [],
+      projects: [],
+      rules: [],
+      lastSync: new Date().toISOString()
+    };
+    
+    console.error(`[PromptManager] Scanning local directories from base: ${baseDir}`);
+    
+    for (const dir of directories) {
+      try {
+        const dirPath = path.join(baseDir, dir.name);
+        console.error(`[PromptManager] Scanning ${dir.name} directory: ${dirPath}`);
+        
+        // 检查目录是否存在
+        try {
+          await fs.access(dirPath);
+        } catch {
+          console.warn(`[PromptManager] ⚠️  Directory not found: ${dirPath}`);
+          results[dir.type] = [];
+          continue;
+        }
+        
+        const files = await fs.readdir(dirPath);
+        const matchedFiles = files
+          .filter(file => dir.pattern.test(file))
+          .map(filename => {
+            const fileInfo = {
+              filename,
+              type: dir.type,
+              path: path.join(dirPath, filename)
+            };
+            
+            // 为 prompts 类型添加额外的工具信息
+            if (dir.type === 'prompts') {
+              const baseName = filename.replace('.prompt.md', '');
+              fileInfo.toolName = `dev-${baseName}`;
+              fileInfo.source = filename;
+              fileInfo.platform = 'local';
+            }
+            
+            return fileInfo;
+          });
+        
+        results[dir.type] = matchedFiles;
+        console.error(`[PromptManager] ✅ ${dir.name}: ${matchedFiles.length} files`);
+        
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Failed to scan ${dir.name}: ${error.message}`);
+        results[dir.type] = [];
+      }
+    }
+    
+    console.error(`[PromptManager] Local scan complete. Total: ${results.prompts.length + results.projects.length + results.rules.length} files`);
+    
+    // 本地模式：复制文件到缓存目录
+    await this.saveLocalResourceContents(results, baseDir);
+    
+    // 缓存结果
+    await this.cacheMultiDirectoryResources(results);
+    
+    return results;
+  }
+
+  /**
+   * 🟢 GREEN: 保存本地资源文件内容到缓存目录
+   * @param {Object} resources - 资源对象
+   * @param {string} baseDir - 基础目录
+   */
+  async saveLocalResourceContents(resources, baseDir) {
+    console.error('[PromptManager] Copying local resource contents to cache...');
+    
+    // 复制 projects 内容
+    for (const project of resources.projects) {
+      try {
+        const sourcePath = path.join(baseDir, 'projects', project.filename);
+        const destPath = path.join(this.cacheDir, 'projects', project.filename);
+        const content = await fs.readFile(sourcePath, 'utf8');
+        await fs.writeFile(destPath, content, 'utf8');
+        console.error(`[PromptManager] ✅ Copied ${project.filename} (${content.length} bytes)`);
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Failed to copy ${project.filename}: ${error.message}`);
+      }
+    }
+    
+    // 复制 rules 内容
+    for (const rule of resources.rules) {
+      try {
+        const sourcePath = path.join(baseDir, 'rules', rule.filename);
+        const destPath = path.join(this.cacheDir, 'rules', rule.filename);
+        const content = await fs.readFile(sourcePath, 'utf8');
+        await fs.writeFile(destPath, content, 'utf8');
+        console.error(`[PromptManager] ✅ Copied ${rule.filename} (${content.length} bytes)`);
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Failed to copy ${rule.filename}: ${error.message}`);
+      }
+    }
+    
+    console.error('[PromptManager] ✅ Local resource copy complete');
+  }
+
+  /**
+   * 🟢 GREEN: Task 3.1 - 保存资源文件内容到本地子目录
+   * @param {Object} resources - 资源对象
+   */
+  async saveResourceContents(resources) {
+    console.error('[PromptManager] Saving resource contents to cache...');
+    
+    // 解析远程路径信息
+    const pathInfo = parseRemotePath(this.resourcePath);
+    
+    // 保存projects内容
+    for (const project of resources.projects) {
+      try {
+        const content = await this.fetchFileContent(pathInfo, 'projects', project.filename);
+        const filePath = path.join(this.cacheDir, 'projects', project.filename);
+        await fs.writeFile(filePath, content, 'utf8');
+        console.error(`[PromptManager] ✅ Saved ${project.filename} (${content.length} bytes)`);
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Failed to save ${project.filename}: ${error.message}`);
+      }
+    }
+    
+    // 保存rules内容
+    for (const rule of resources.rules) {
+      try {
+        const content = await this.fetchFileContent(pathInfo, 'rules', rule.filename);
+        const filePath = path.join(this.cacheDir, 'rules', rule.filename);
+        await fs.writeFile(filePath, content, 'utf8');
+        console.error(`[PromptManager] ✅ Saved ${rule.filename} (${content.length} bytes)`);
+      } catch (error) {
+        console.warn(`[PromptManager] ⚠️  Failed to save ${rule.filename}: ${error.message}`);
+      }
+    }
+    
+    console.error('[PromptManager] ✅ Resource content save complete');
+  }
+
+  /**
+   * 🟢 GREEN: 从远程获取单个文件内容
+   * @param {Object} pathInfo - 路径信息
+   * @param {string} subDir - 子目录（projects或rules）
+   * @param {string} filename - 文件名
+   * @returns {Promise<string>} 文件内容
+   */
+  async fetchFileContent(pathInfo, subDir, filename) {
+    const { platform, project, branch, path: basePath } = pathInfo;
+    const filePath = `${basePath}/${subDir}/${filename}`;
+    
+    if (platform === 'gitlab') {
+      const encodedPath = encodeURIComponent(filePath);
+      const url = `https://gitlab.com/api/v4/projects/${encodeURIComponent(project)}/repository/files/${encodedPath}/raw?ref=${branch}`;
+      
+      const headers = createAuthHeaders(platform, this.token);
+      console.error(`[PromptManager] 🔐 Token available: ${this.token ? 'YES' : 'NO'}, Headers: ${JSON.stringify(Object.keys(headers))}`);
+      
+      const response = await fetch(url, {
+        headers: headers
+      });
+      
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => '');
+        console.error(`[PromptManager] ⚠️  GitLab API error for ${filename}: ${response.status}`);
+        console.error(`[PromptManager] URL: ${url}`);
+        throw new Error(`GitLab API error: ${response.status} for ${filePath}`);
+      }
+      
+      return await response.text();
+    } else if (platform === 'github') {
+      // GitHub uses owner/repo format (project contains it)
+      const url = `https://raw.githubusercontent.com/${project}/${branch}/${filePath}`;
+      
+      const response = await fetch(url, {
+        headers: createAuthHeaders(platform, this.token)
+      });
+      
+      if (!response.ok) {
+        throw new Error(`GitHub raw API error: ${response.status} for ${filePath}`);
+      }
+      
+      return await response.text();
+    } else {
+      throw new Error(`Unsupported platform for file content fetch: ${platform}`);
+    }
+  }
+
+  /**
+   * 生成工具配置
+   */
+  generateToolsConfig(promptFiles) {
+    // Prompt工具
+    const promptTools = promptFiles.map(({ toolName, source }) => ({
+      name: toolName,
+      type: 'prompt',
+      source: source,
+      description: `${toolName} prompt direct`,
+      schema: {
+        type: 'object',
+        properties: { 
+          source: { type: 'string' } 
+        },
+        required: ['source']
+      }
+    }));
+
+    // Handler工具（固定配置）
+    const handlerTools = [
+      {
+        name: 'dev-feedback',
+        type: 'handler',
+        handler: 'handleDevFeedback',
+        description: '反馈确认工具',
+        schema: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            message: { type: 'string' },
+            options: { type: 'array', items: { type: 'string' } }
+          },
+          required: ['title', 'message']
+        }
+      },
+      {
+        name: 'dev-manual',
+        type: 'handler',
+        handler: 'handleDevManual',
+        description: '手动选择开发类型',
+        schema: {
+          type: 'object',
+          properties: {
+            random_string: { description: 'Dummy parameter for no-parameter tools', type: 'string' }
+          },
+          required: ['random_string']
+        }
+      },
+      {
+        name: 'load-resource',
+        type: 'handler',
+        handler: 'handleLoadResource',
+        description: 'Load full content of a resource (project documentation or rules)',
+        schema: {
+          type: 'object',
+          properties: {
+            resourceName: { 
+              type: 'string',
+              description: 'Resource filename (e.g. "java-rules.md", "kiki-framework-wiki.md")'
+            }
+          },
+          required: ['resourceName']
+        }
+      }
+    ];
+
+    return [...promptTools, ...handlerTools];
+  }
+
+  /**
+   * 验证工具配置存在（不验证内容）
+   */
+  validateToolsConfigExists() {
+    const promptTools = this.toolsConfig.filter(tool => tool.type === 'prompt');
+    if (promptTools.length === 0) {
+      throw new Error('No prompt tools configured after initialization');
+    }
+
+    console.error(`[PromptManager] Tools configured: ${promptTools.length} prompt tools available`);
+    console.error(`[PromptManager] Available tools: ${promptTools.map(t => t.name).join(', ')}`);
+  }
+
+  /**
+   * 获取prompt内容（运行时逻辑）
+   * 🟢 GREEN: Task 1.1 - 运行时区分缓存新鲜度
+   */
+  async getPromptContent(fileName) {
+    const cacheFile = path.join(this.cacheDir, fileName);
+    const versionFile = path.join(this.cacheDir, `${fileName}.version`);
+    
+    try {
+      const stat = await fs.stat(cacheFile);
+      const cacheAge = Date.now() - stat.mtimeMs;
+      
+      // 读取缓存内容
+      const content = await fs.readFile(cacheFile, 'utf8');
+      
+      if (cacheAge < this.ttl && !this.force) {
+        // 🟢 缓存新鲜：直接返回，不进行异步更新
+        console.error(`[PromptManager] Using fresh cached ${fileName} (age: ${Math.round(cacheAge / 1000 / 60)}min)`);
+        return content;
+      } else {
+        // 🟡 缓存过期：立即返回缓存内容，同时异步更新
+        console.error(`[PromptManager] Using stale cached ${fileName} (age: ${Math.round(cacheAge / 1000 / 60)}min), scheduling async update`);
+        
+        // 异步更新缓存（不阻塞本次返回）
+        this.asyncUpdatePromptCache(fileName).catch(error => {
+          console.warn(`[PromptManager] Async cache update failed for ${fileName}: ${error.message}`);
+        });
+        
+        return content;
+      }
+    } catch (error) {
+      // 🔴 缓存不存在：必须立即获取
+      console.error(`[PromptManager] Cache miss for ${fileName}, fetching immediately`);
+      return await this.fetchPromptContent(fileName);
+    }
+  }
+
+  /**
+   * 从远程获取prompt内容
+   */
+  async fetchPromptContent(fileName) {
+    if (this.platform === 'local') {
+      const filePath = path.join(this.resourcePath, fileName);
+      return await fs.readFile(filePath, 'utf8');
+    } else {
+      console.error(`[PromptManager] Fetching prompt content: ${fileName}`);
+      
+      // 🟢 GREEN: Task 1.1 - 添加更详细的错误处理
+      let pathInfo;
+      try {
+        pathInfo = parseRemotePath(this.promptPath);
+      } catch (error) {
+        throw new Error(`Failed to parse remote path configuration: ${error.message}`);
+      }
+      let url, headers;
+      
+      if (pathInfo.platform === 'github') {
+        // fileName 已经包含完整相对路径，不需要再拼接 pathInfo.path
+        url = `https://api.github.com/repos/${pathInfo.project}/contents/${fileName}?ref=${pathInfo.branch}`;
+        headers = createAuthHeaders('github', process.env.GIT_TOKEN);
+        console.error(`[PromptManager] GitHub API call: ${url}`);
+      } else if (pathInfo.platform === 'gitlab') {
+        const projectEnc = encodeURIComponent(pathInfo.project);
+        // fileName 已经包含完整相对路径，不需要再拼接 pathInfo.path
+        const filePathEnc = encodeURIComponent(fileName);
+        url = `https://gitlab.com/api/v4/projects/${projectEnc}/repository/files/${filePathEnc}?ref=${pathInfo.branch}`;
+        headers = createAuthHeaders('gitlab', process.env.GIT_TOKEN);
+        console.error(`[PromptManager] GitLab API call: ${url}`);
+      }
+      
+      const requestOptions = { headers, timeout: 10000 };
+      const response = await fetch(url, requestOptions);
+      if (!response.ok) {
+        // 🟢 GREEN: Task 1.2 - 增强错误信息的详细性，包含完整请求信息
+        
+        // 构建详细的调试信息，隐藏敏感token信息
+        const debugHeaders = { ...headers };
+        
+        const requestInfo = `
+          REQUEST INFO: \n
+          - URL: ${url} \n
+          - Method: GET \n
+          - Headers: ${JSON.stringify(debugHeaders, null, 2)} \n
+          - Timeout: ${requestOptions.timeout}ms \n
+          - Response Status: ${response.status} \n
+          - Response StatusText: ${response.statusText} \n`;
+                  
+        throw new Error(`fetchPromptContent Error: ${fileName}, request info: ${requestInfo}`);
+      }
+      
+      const data = await response.json();
+      const content = Buffer.from(data.content, 'base64').toString('utf8');
+      
+      // 获取版本信息 - 优先使用last_commit_id（GitLab）或sha（GitHub）
+      let version = 'unknown';
+      if (pathInfo.platform === 'gitlab' && data.last_commit_id) {
+        version = data.last_commit_id.substring(0, 8); // 前8位作为版本号
+      } else if (pathInfo.platform === 'github' && data.sha) {
+        version = data.sha.substring(0, 8);
+      }
+      
+      // 保存到缓存
+      await this.saveToCacheWithVersion(fileName, content, version);
+      
+      console.error(`[PromptManager] Successfully fetched ${fileName} with version ${version}`);
+      return content;
+    }
+  }
+
+  /**
+   * 异步更新prompt缓存
+   */
+  async asyncUpdatePromptCache(fileName) {
+    try {
+      console.error(`[PromptManager] Async updating cache for ${fileName}...`);
+      await this.fetchPromptContent(fileName);
+      console.error(`[PromptManager] ✅ Async cache update completed for ${fileName}`);
+    } catch (error) {
+      console.warn(`[PromptManager] ⚠️  Async cache update failed for ${fileName}: ${error.message}`);
+  }
+}
+
+/**
+ * 保存prompt到缓存，同时保存版本信息
+ */
+  async saveToCacheWithVersion(fileName, content, version) {
+    const cacheFile = path.join(this.cacheDir, fileName);
+    const versionFile = path.join(this.cacheDir, `${fileName}.version`);
+    
+    try {
+      await fs.writeFile(cacheFile, content, 'utf8');
+      
+      // 获取缓存文件的修改时间并格式化为yyyyMMddHH
+      const stat = await fs.stat(cacheFile);
+      const modTime = new Date(stat.mtimeMs);
+      const timeFormat = modTime.getFullYear().toString() +
+                        (modTime.getMonth() + 1).toString().padStart(2, '0') +
+                        modTime.getDate().toString().padStart(2, '0') +
+                        modTime.getHours().toString().padStart(2, '0');
+      
+      // 组合版本号：sha前8位-时间yyyyMMddHH
+      const finalVersion = version !== 'unknown' ? `${version}-${timeFormat}` : `unknown-${timeFormat}`;
+      
+      const versionInfo = {
+        version: finalVersion,
+        platform: this.platform,
+        source: this.resourcePath
+      };
+      await fs.writeFile(versionFile, JSON.stringify(versionInfo, null, 2), 'utf8');
+    
+      console.error(`[PromptManager] Cached ${fileName} with version ${finalVersion}`);
+  } catch (error) {
+      console.warn(`[PromptManager] Failed to cache ${fileName}: ${error.message}`);
+  }
+}
+
+/**
+   * 获取工具配置列表
+   */
+  getToolsConfig() {
+    if (!this.isInitialized) {
+      throw new Error('PromptManager not initialized. Call initializeSync() first.');
+    }
+    return this.toolsConfig;
+  }
+}
+
+// 导出单例实例
+const promptManagerInstance = new PromptManager();
+
+// 主要功能函数导出
+export async function initializePrompts() {
+  return await promptManagerInstance.initializeSync();
+}
+
+export function getToolsConfiguration() {
+  return promptManagerInstance.getToolsConfig();
+}
+
+export async function getPrompt(fileName) {
+  return await promptManagerInstance.getPromptContent(fileName);
+}
+
+// 获取prompt版本信息
+export async function getCurrentPromptVersion(fileName) {
+  try {
+    // 从缓存版本文件中获取版本信息
+    const versionFile = path.join(promptManagerInstance.cacheDir, `${fileName}.version`);
+    const versionData = await fs.readFile(versionFile, 'utf8');
+    const info = JSON.parse(versionData);
+    return `${info.version}`;
+  } catch {
+    return 'Unknown';
+  }
+}
+
+// 获取详细prompt信息
+export async function getLocalPromptInfo(fileName) {
+  const platform = promptManagerInstance.platform;
+  
+  if (platform === 'local') {
+    try {
+      const filePath = path.join(promptManagerInstance.promptPath, fileName);
+      const stat = await fs.stat(filePath);
+      
+      // 本地模式也使用相同的版本格式：local-yyyyMMddHH
+      const modTime = new Date(stat.mtimeMs);
+      const timeFormat = modTime.getFullYear().toString() +
+                        (modTime.getMonth() + 1).toString().padStart(2, '0') +
+                        modTime.getDate().toString().padStart(2, '0') +
+                        modTime.getHours().toString().padStart(2, '0');
+      const localVersion = `local-${timeFormat}`;
+      
+      return {
+        version: localVersion,
+        platform: 'local',
+        source: promptManagerInstance.promptPath
+      };
+    } catch (error) {
+      return {
+        version: `unknown`,
+        platform: 'local',
+        source: promptManagerInstance.promptPath
+      };
+    }
+  } else {
+    const versionFile = path.join(promptManagerInstance.cacheDir, `${fileName}.version`);
+    try {
+      const versionData = await fs.readFile(versionFile, 'utf8');
+      const info = JSON.parse(versionData);
+      return {
+        version: info.version,
+        platform: info.platform,
+        source: info.source
+      };
+    } catch (error) {
+      return {
+        version: 'unknown',
+        platform: 'remote',
+        source: promptManagerInstance.promptPath
+      };
+    }
+  }
+}
+