sloth-d2c-mcp 1.0.4-beta100

package/dist/build/utils/file-manager.js

@@ -0,0 +1,868 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import envPaths from 'env-paths';
+import { Logger } from '../utils/logger.js';
+import { httpServer, socketServer } from '../server.js';
+/**
+ * 通用文件管理器
+ * 可以保存任何类型的文件，使用fileKey和nodeId组织目录结构
+ */
+export class FileManager {
+    paths; // 应用路径配置
+    baseDir; // 基础存储目录
+    _workspaceRoot = null; // MCP 工作目录根路径
+    _uuid = '';
+    constructor(appName) {
+        this.paths = envPaths(appName);
+        this.baseDir = path.join(this.paths.data, 'files');
+    }
+    get workspaceRoot() {
+        const isMainProcess = httpServer !== null;
+        if (isMainProcess && this._uuid) {
+            const workspaceRoot = socketServer?.getTokenExtraField(this._uuid, 'workspaceRoot');
+            return workspaceRoot || this._workspaceRoot;
+        }
+        return this._workspaceRoot;
+    }
+    set workspaceRoot(rootPath) {
+        this._workspaceRoot = rootPath;
+    }
+    /**
+     * 设置工作目录根路径（用于 MCP 工作项目）
+     * @param rootPath - 工作目录根路径
+     */
+    setWorkspaceRoot(rootPath) {
+        this.workspaceRoot = rootPath;
+        Logger.log(`已设置工作目录根路径: ${rootPath}`);
+    }
+    getWorkspaceRoot() {
+        return this.workspaceRoot || './';
+    }
+    /**
+     * 生成文件路径
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     * @returns 完整的文件路径
+     */
+    getFilePath(fileKey, nodeId, filename) {
+        // 清理文件名中的特殊字符
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf-_]/g, '_');
+        const cleanNodeId = nodeId ? nodeId.replace(/[^a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf-_]/g, '_') : 'root';
+        const cleanFilename = filename.replace(/[^a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf-_.]/g, '_');
+        return path.join(this.baseDir, cleanFileKey, cleanNodeId, cleanFilename);
+    }
+    /**
+     * 生成工作目录中的文件路径（保存到 .sloth 文件夹）
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     * @returns 完整的文件路径
+     */
+    getWorkspaceFilePath(fileKey, nodeId, filename, opts = { skipParsePath: false }) {
+        const { skipParsePath = false } = opts;
+        if (!this.workspaceRoot) {
+            console.error('工作目录根路径未设置,使用默认目录:', this.baseDir);
+            return this.getFilePath(fileKey, nodeId, filename);
+        }
+        // 清理文件名中的特殊字符
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf-_]/g, '_');
+        const cleanNodeId = nodeId ? nodeId.replace(/[^a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf-_]/g, '_') : 'root';
+        const cleanFilename = filename.replace(/[^a-zA-Z0-9\u4e00-\u9fff\u3400-\u4dbf-_.]/g, '_');
+        if (skipParsePath) {
+            return path.join(this.workspaceRoot, '.sloth', fileKey, nodeId || 'root', cleanFilename);
+        }
+        return path.join(this.workspaceRoot, '.sloth', cleanFileKey, cleanNodeId, cleanFilename);
+    }
+    /**
+     * 获取工作目录下特定 fileKey 的目录路径
+     * @param fileKey - Figma 文件的 key
+     * @returns string | null
+     */
+    getWorkspaceFileKeyDirPath(fileKey) {
+        if (!this.workspaceRoot)
+            return null;
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+        return path.join(this.workspaceRoot, '.sloth', cleanFileKey);
+    }
+    /**
+     * 保存文件内容
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     * @param content - 文件内容
+     * @param useWorkspaceDir - 是否使用工作目录
+     */
+    async saveFile(fileKey, nodeId, filename, content, opts = { useWorkspaceDir: false, skipParsePath: false }) {
+        const { useWorkspaceDir = false, ...restOpts } = opts;
+        try {
+            const filePath = useWorkspaceDir ? this.getWorkspaceFilePath(fileKey, nodeId, filename, restOpts) : this.getFilePath(fileKey, nodeId, filename);
+            // 确保目录存在
+            await fs.mkdir(path.dirname(filePath), { recursive: true });
+            // 保存文件内容
+            await fs.writeFile(filePath, content, 'utf-8');
+            Logger.log(`文件已保存: ${filePath}`);
+        }
+        catch (error) {
+            Logger.error(`保存文件失败: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * 读取文件内容
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     * @param useWorkspaceDir - 是否使用工作目录
+     * @returns Promise<string> - 文件内容，如果文件不存在则返回空字符串
+     */
+    async loadFile(fileKey, nodeId, filename, opts = { useWorkspaceDir: false, skipParsePath: false }) {
+        const { useWorkspaceDir = false, ...restOpts } = opts;
+        try {
+            const filePath = useWorkspaceDir ? this.getWorkspaceFilePath(fileKey, nodeId, filename, restOpts) : this.getFilePath(fileKey, nodeId, filename);
+            Logger.log(`加载文件: ${filePath}, workspaceRoot: ${this.workspaceRoot}`);
+            const content = await fs.readFile(filePath, 'utf-8');
+            return content;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                Logger.log(`文件不存在: ${filename}`);
+                return '';
+            }
+            Logger.error(`读取文件失败: ${err.toString()}`);
+            throw err;
+        }
+    }
+    /**
+     * 检查文件是否存在
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     * @returns Promise<boolean> - 如果文件存在则返回true
+     */
+    async exists(fileKey, nodeId, filename) {
+        try {
+            const filePath = this.getFilePath(fileKey, nodeId, filename);
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 删除文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     */
+    async deleteFile(fileKey, nodeId, filename) {
+        try {
+            const filePath = this.getFilePath(fileKey, nodeId, filename);
+            await fs.unlink(filePath);
+            Logger.log(`文件已删除: ${filePath}`);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                Logger.error(`删除文件失败: ${err.toString()}`);
+                throw err; // 如果不是文件不存在错误，则抛出异常
+            }
+        }
+    }
+    /**
+     * 清理特定fileKey的所有文件
+     * @param fileKey - Figma文件的key
+     */
+    async cleanupFileKey(fileKey) {
+        try {
+            const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+            const fileKeyDir = path.join(this.baseDir, cleanFileKey);
+            await fs.rm(fileKeyDir, { recursive: true, force: true });
+            Logger.log(`文件Key目录已清理: ${fileKeyDir}`);
+        }
+        catch (error) {
+            Logger.error(`清理文件Key目录失败: ${error}`);
+        }
+    }
+    /**
+     * 清理特定fileKey和nodeId的所有文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     */
+    async cleanupNode(fileKey, nodeId) {
+        try {
+            const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+            const cleanNodeId = nodeId ? nodeId.replace(/[^a-zA-Z0-9-_]/g, '_') : 'root';
+            const nodeDir = path.join(this.baseDir, cleanFileKey, cleanNodeId);
+            await fs.rm(nodeDir, { recursive: true, force: true });
+            Logger.log(`节点目录已清理: ${nodeDir}`);
+        }
+        catch (error) {
+            Logger.error(`清理节点目录失败: ${error}`);
+        }
+    }
+    /**
+     * 清理整个存储目录
+     */
+    async cleanup() {
+        try {
+            await fs.rm(this.baseDir, { recursive: true, force: true });
+            Logger.log(`存储目录已清理: ${this.baseDir}`);
+        }
+        catch (error) {
+            Logger.error(`清理存储目录失败: ${error}`);
+        }
+    }
+    /**
+     * 获取文件的完整路径（公共方法）
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param filename - 文件名
+     * @returns string - 文件的完整路径
+     */
+    getFilePathPublic(fileKey, nodeId, filename) {
+        return this.getFilePath(fileKey, nodeId, filename);
+    }
+    /**
+     * 获取基础存储目录路径
+     * @returns string - 基础存储目录的完整路径
+     */
+    getBaseDir() {
+        return this.baseDir;
+    }
+    /**
+     * 获取特定fileKey的目录路径
+     * @param fileKey - Figma文件的key
+     * @returns string - fileKey目录的完整路径
+     */
+    getFileKeyDir(fileKey) {
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+        return path.join(this.baseDir, cleanFileKey);
+    }
+    /**
+     * 获取特定fileKey和nodeId的目录路径
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns string - 节点目录的完整路径
+     */
+    getNodeDir(fileKey, nodeId) {
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+        const cleanNodeId = nodeId ? nodeId.replace(/[^a-zA-Z0-9-_]/g, '_') : 'root';
+        return path.join(this.baseDir, cleanFileKey, cleanNodeId);
+    }
+    /**
+     * 保存 groupsData 到特定的 nodeId 文件（保存到工作目录的 .sloth 文件夹）
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param groupsData - 分组数据
+     */
+    async saveGroupsData(fileKey, nodeId, groupsData) {
+        await this.saveFile(fileKey, nodeId, 'groupsData.json', JSON.stringify(groupsData, null, 2), { useWorkspaceDir: true, skipParsePath: false });
+    }
+    /**
+     * 加载 groupsData 从特定的 nodeId 文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns Promise<any[]> - 分组数据，如果文件不存在则返回空数组
+     */
+    async loadGroupsData(fileKey, nodeId) {
+        try {
+            const content = await this.loadFile(fileKey, nodeId, 'groupsData.json', { useWorkspaceDir: true, skipParsePath: false });
+            return content ? JSON.parse(content) : [];
+        }
+        catch (error) {
+            Logger.log(`加载 groupsData 失败，返回空数组: ${error}`);
+            return [];
+        }
+    }
+    /**
+     * 保存 promptSetting 到特定的 nodeId 文件（保存到工作目录的 .sloth 文件夹）
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param promptSetting - 提示词设置对象，格式为 { [key: string]: string }
+     */
+    /**
+     * 将 camelCase 转换为 kebab-case
+     */
+    camelToKebab(str) {
+        return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+    }
+    /**
+     * 将 kebab-case 转换为 camelCase
+     */
+    kebabToCamel(str) {
+        return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    }
+    async savePromptSetting(fileKey, nodeId, promptSetting) {
+        fileKey = '.';
+        nodeId = '.';
+        // 按 key 存储为独立的 md 文件
+        if (promptSetting && typeof promptSetting === 'object') {
+            for (const [key, value] of Object.entries(promptSetting)) {
+                if (typeof value === 'string' && value) {
+                    // 将 camelCase key 转换为 kebab-case 文件名
+                    const fileName = this.camelToKebab(key);
+                    Logger.log(`fileName: ${fileName}`, 'this.workspaceRoot: ', this.workspaceRoot);
+                    // 直接构建完整路径到 .sloth/prompt/xx.md
+                    const filePath = path.join(this.workspaceRoot, '.sloth', 'd2c-prompt', `${fileName}.md`);
+                    await fs.mkdir(path.dirname(filePath), { recursive: true });
+                    await fs.writeFile(filePath, value, 'utf-8');
+                    Logger.log(`Prompt 文件已保存: ${filePath}`);
+                }
+            }
+        }
+    }
+    /**
+     * 加载 promptSetting 从特定的 nodeId 文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns Promise<any> - 提示词设置对象，如果文件不存在则返回 null
+     */
+    async loadPromptSetting(fileKey, nodeId) {
+        fileKey = '.';
+        nodeId = '.';
+        try {
+            // 兼容老格式：尝试读取 promptSetting.json
+            const oldContent = await this.loadFile(fileKey, nodeId, 'promptSetting.json', { useWorkspaceDir: true, skipParsePath: true });
+            if (oldContent) {
+                Logger.log('检测到老格式 promptSetting.json，准备删除');
+                // 删除老文件
+                const filePath = this.getWorkspaceFilePath(fileKey, nodeId, 'promptSetting.json', { skipParsePath: true });
+                await fs.unlink(filePath).catch((err) => Logger.log(`删除老文件失败: ${err}`));
+                return JSON.parse(oldContent);
+            }
+            // 读取新格式：所有 .md 文件，直接从 .sloth/d2c-prompt/ 目录读取
+            const dirPath = path.join(this.workspaceRoot, '.sloth', 'd2c-prompt');
+            const files = await fs.readdir(dirPath).catch(() => []);
+            const result = {};
+            for (const file of files) {
+                if (file.endsWith('.md')) {
+                    // 将 kebab-case 文件名转换回 camelCase key
+                    const kebabKey = file.replace(/\.md$/, '');
+                    const key = this.kebabToCamel(kebabKey);
+                    const filePath = path.join(dirPath, file);
+                    const content = await fs.readFile(filePath, 'utf-8').catch(() => '');
+                    if (content) {
+                        result[key] = content;
+                    }
+                }
+            }
+            return Object.keys(result).length > 0 ? result : null;
+        }
+        catch (error) {
+            Logger.log(`加载 promptSetting 失败，返回 null: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * 保存 configSetting 到特定的 nodeId 文件（保存到工作目录的 .sloth 文件夹）
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param configSetting - 配置设置
+     */
+    async saveConfigSetting(fileKey, nodeId, configSetting) {
+        fileKey = '.';
+        nodeId = '.';
+        await this.saveFile(fileKey, nodeId, 'configSetting.json', JSON.stringify(configSetting, null, 2), { useWorkspaceDir: true, skipParsePath: true });
+    }
+    /**
+     * 加载 configSetting 从特定的 nodeId 文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns Promise<any> - 配置设置，如果文件不存在则返回 null
+     */
+    async loadConfigSetting(fileKey, nodeId) {
+        fileKey = '.';
+        nodeId = '.';
+        try {
+            const content = await this.loadFile(fileKey, nodeId, 'configSetting.json', { useWorkspaceDir: true, skipParsePath: true });
+            return content ? JSON.parse(content) : null;
+        }
+        catch (error) {
+            Logger.log(`加载 configSetting 失败，返回 null: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * 列出指定 fileKey 下的所有 nodeId（目录名）
+     * @param fileKey - Figma 文件的 key
+     */
+    async listNodeIds(fileKey) {
+        const workspaceDir = this.getWorkspaceFileKeyDirPath(fileKey);
+        const targetDir = workspaceDir || this.getFileKeyDir(fileKey);
+        try {
+            const dirents = await fs.readdir(targetDir, { withFileTypes: true });
+            return dirents.filter((d) => d.isDirectory()).map((d) => d.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 列出所有 fileKey
+     * @returns Promise<string[]> - 所有 fileKey 的列表
+     */
+    async listAllFileKeys() {
+        try {
+            if (!this.workspaceRoot) {
+                Logger.log('workspaceRoot 未设置，无法列出所有 fileKey');
+                return [];
+            }
+            const slothDir = path.join(this.workspaceRoot, '.sloth');
+            const entries = await fs.readdir(slothDir, { withFileTypes: true });
+            const fileKeys = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+            Logger.log(`找到 ${fileKeys.length} 个 fileKey:`, fileKeys);
+            return fileKeys;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 加载指定 fileKey 下所有 nodeId 的 groupsData
+     * @param fileKey - Figma 文件的 key
+     */
+    async loadAllGroupsData(fileKey) {
+        const nodeIds = await this.listNodeIds(fileKey);
+        const results = [];
+        Logger.log(`加载指定 fileKey 下所有 nodeId 的 groupsData: ${fileKey}, nodeIds: ${nodeIds}`);
+        if (nodeIds.length === 0) {
+            const groups = await this.loadGroupsData(fileKey, undefined);
+            if (groups.length > 0) {
+                results.push({ nodeId: 'root', groups });
+            }
+            return results;
+        }
+        for (const nodeId of nodeIds) {
+            const normalizedNodeId = nodeId === 'root' ? undefined : nodeId;
+            Logger.log(`加载指定 fileKey 下 nodeId 的 groupsData: ${fileKey}, nodeId: ${nodeId}`);
+            const groups = await this.loadGroupsData(fileKey, normalizedNodeId);
+            if (groups && groups.length > 0) {
+                results.push({ nodeId, groups });
+            }
+        }
+        return results;
+    }
+    /**
+     * 加载整个项目所有 fileKey 的所有 groupsData（用于跨文件组件匹配）
+     * @returns Promise<Array<{ fileKey: string; nodeId: string; groups: any[] }>>
+     */
+    async loadAllProjectGroupsData() {
+        const fileKeys = await this.listAllFileKeys();
+        const results = [];
+        Logger.log(`开始加载整个项目的 groupsData，共 ${fileKeys.length} 个 fileKey`);
+        for (const fileKey of fileKeys) {
+            const groupsDataByNode = await this.loadAllGroupsData(fileKey);
+            for (const { nodeId, groups } of groupsDataByNode) {
+                if (groups && groups.length > 0) {
+                    results.push({ fileKey, nodeId, groups });
+                }
+            }
+        }
+        Logger.log(`项目 groupsData 加载完成，共 ${results.length} 个节点有分组数据`);
+        return results;
+    }
+    /**
+     * 获取 screenshots 目录路径
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns string - screenshots 目录的完整路径
+     */
+    getScreenshotsDir(fileKey, nodeId) {
+        const nodeDir = this.getWorkspaceFilePath(fileKey, nodeId, '');
+        return path.join(nodeDir, 'screenshots');
+    }
+    /**
+     * 保存截图文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param hash - 截图文件的哈希值（作为文件名）
+     * @param buffer - 截图文件的二进制数据
+     */
+    async saveScreenshot(fileKey, nodeId, hash, buffer) {
+        try {
+            const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+            // 确保目录存在
+            await fs.mkdir(screenshotsDir, { recursive: true });
+            const filePath = path.join(screenshotsDir, `${hash}.png`);
+            await fs.writeFile(filePath, buffer);
+            Logger.log(`截图已保存: ${filePath}`);
+        }
+        catch (error) {
+            Logger.error(`保存截图失败: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * 加载截图文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param hash - 截图文件的哈希值
+     * @returns Promise<Buffer> - 截图文件的二进制数据
+     */
+    async loadScreenshot(fileKey, nodeId, hash) {
+        try {
+            const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+            const filePath = path.join(screenshotsDir, `${hash}.png`);
+            const buffer = await fs.readFile(filePath);
+            return buffer;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                Logger.log(`截图文件不存在: ${hash}.png`);
+                return null;
+            }
+            Logger.error(`加载截图失败: ${err.toString()}`);
+            throw err;
+        }
+    }
+    /**
+     * 检查截图文件是否存在
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param hash - 截图文件的哈希值
+     * @returns Promise<boolean> - 如果文件存在则返回 true
+     */
+    async screenshotExists(fileKey, nodeId, hash) {
+        try {
+            const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+            const filePath = path.join(screenshotsDir, `${hash}.png`);
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 获取截图文件的完整路径
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param hash - 截图文件的哈希值
+     * @returns string - 截图文件的完整路径
+     */
+    getScreenshotPath(fileKey, nodeId, hash) {
+        const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+        return path.join(screenshotsDir, `${hash}.png`);
+    }
+    /**
+     * 删除截图文件
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param hash - 截图文件的哈希值
+     */
+    async deleteScreenshot(fileKey, nodeId, hash) {
+        try {
+            const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+            const filePath = path.join(screenshotsDir, `${hash}.png`);
+            await fs.unlink(filePath);
+            Logger.log(`截图已删除: ${filePath}`);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                Logger.error(`删除截图失败: ${err.toString()}`);
+                throw err;
+            }
+        }
+    }
+    /**
+     * 清理旧的截图文件（根据时间戳）
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param maxAgeDays - 最大保留天数
+     */
+    async cleanupOldScreenshots(fileKey, nodeId, maxAgeDays = 30) {
+        try {
+            const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+            // 检查目录是否存在
+            try {
+                await fs.access(screenshotsDir);
+            }
+            catch {
+                // 目录不存在，直接返回
+                return;
+            }
+            const files = await fs.readdir(screenshotsDir);
+            const now = Date.now();
+            const maxAge = maxAgeDays * 24 * 60 * 60 * 1000;
+            let deletedCount = 0;
+            for (const file of files) {
+                const filePath = path.join(screenshotsDir, file);
+                const stats = await fs.stat(filePath);
+                const age = now - stats.mtimeMs;
+                if (age > maxAge) {
+                    await fs.unlink(filePath);
+                    deletedCount++;
+                }
+            }
+            if (deletedCount > 0) {
+                Logger.log(`清理了 ${deletedCount} 个旧截图文件（超过 ${maxAgeDays} 天）`);
+            }
+        }
+        catch (error) {
+            Logger.error(`清理旧截图失败: ${error}`);
+        }
+    }
+    /**
+     * 读取组件数据库
+     * @returns Promise<StoredComponent[]> - 组件列表
+     */
+    async loadComponentsDatabase() {
+        const workspaceRoot = this.getWorkspaceRoot();
+        if (!workspaceRoot) {
+            Logger.warn('工作目录根路径未设置，无法加载组件数据库');
+            return [];
+        }
+        const componentsPath = path.join(workspaceRoot, '.sloth', 'components.json');
+        try {
+            const content = await fs.readFile(componentsPath, 'utf-8');
+            // 验证文件内容不为空
+            if (!content || !content.trim()) {
+                Logger.warn('components.json 文件为空，返回空数组');
+                return [];
+            }
+            const components = JSON.parse(content);
+            // 验证数据格式
+            if (!Array.isArray(components)) {
+                Logger.warn('components.json 格式错误（不是数组），返回空数组');
+                return [];
+            }
+            Logger.log(`成功加载 ${components.length} 个组件`);
+            return components;
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                // 文件不存在，返回空数组
+                Logger.log('components.json 不存在，将创建新文件');
+                return [];
+            }
+            if (err instanceof SyntaxError) {
+                Logger.error('components.json JSON 解析失败:', err.message);
+                return [];
+            }
+            Logger.error('读取组件数据库失败:', err);
+            throw error;
+        }
+    }
+    /**
+     * 保存组件数据库
+     * @param components - 要保存的组件列表
+     */
+    async saveComponentsDatabase(components) {
+        const workspaceRoot = this.getWorkspaceRoot();
+        const slothDir = path.join(workspaceRoot, '.sloth');
+        const componentsPath = path.join(slothDir, 'components.json');
+        // 确保目录存在
+        try {
+            await fs.mkdir(slothDir, { recursive: true });
+        }
+        catch (error) {
+            Logger.error('创建 .sloth 目录失败:', error);
+            throw new Error(`无法创建目录: ${slothDir}`);
+        }
+        // 写入数据
+        try {
+            const jsonContent = JSON.stringify(components, null, 2);
+            await fs.writeFile(componentsPath, jsonContent, 'utf-8');
+            Logger.log(`✅ 已保存 ${components.length} 个组件到 components.json`);
+        }
+        catch (error) {
+            Logger.error('写入组件数据库失败:', error);
+            throw new Error(`无法写入文件: ${componentsPath}`);
+        }
+    }
+    /**
+     * 根据截图 hash 在整个 .sloth 目录下搜索截图文件
+     * @param hash - 截图文件的哈希值
+     * @returns Promise<string | null> - 截图文件的完整路径，如果未找到则返回 null
+     */
+    async findScreenshotByHash(hash) {
+        const workspaceRoot = this.getWorkspaceRoot();
+        if (!workspaceRoot) {
+            Logger.warn('工作目录根路径未设置，无法搜索截图');
+            return null;
+        }
+        const slothDir = path.join(workspaceRoot, '.sloth');
+        try {
+            await fs.access(slothDir);
+        }
+        catch {
+            Logger.warn('.sloth 目录不存在');
+            return null;
+        }
+        const targetFilename = `${hash}.png`;
+        // 递归搜索 .sloth 目录下所有 screenshots 文件夹
+        const searchDir = async (dir) => {
+            try {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        // 如果是 screenshots 目录，检查是否有目标文件
+                        if (entry.name === 'screenshots') {
+                            const screenshotPath = path.join(fullPath, targetFilename);
+                            try {
+                                await fs.access(screenshotPath);
+                                return screenshotPath;
+                            }
+                            catch {
+                                // 文件不存在，继续搜索
+                            }
+                        }
+                        else {
+                            // 递归搜索子目录
+                            const result = await searchDir(fullPath);
+                            if (result)
+                                return result;
+                        }
+                    }
+                }
+                return null;
+            }
+            catch (error) {
+                Logger.error(`搜索目录失败 ${dir}:`, error);
+                return null;
+            }
+        };
+        return searchDir(slothDir);
+    }
+    /**
+     * 保存 absolute.html 到 .sloth 目录，支持版本管理
+     * 如果内容不一致，将当前版本移动到带时间戳的文件夹中
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param content - 文件内容
+     */
+    async saveAbsoluteHtml(fileKey, nodeId, content, useWorkspaceDir = false) {
+        const filename = 'absolute.html';
+        // 先尝试加载现有文件
+        const existingContent = await this.loadFile(fileKey, nodeId, filename, { useWorkspaceDir });
+        // 如果存在且内容不一致，先归档旧版本
+        if (existingContent && existingContent.trim() !== content.trim()) {
+            await this.archiveAbsoluteHtml(fileKey, nodeId, existingContent);
+            Logger.log(`检测到 absolute.html 内容变化，已归档旧版本`);
+        }
+        // 保存新内容
+        await this.saveFile(fileKey, nodeId, filename, content, { useWorkspaceDir });
+    }
+    /**
+     * 归档 absolute.html 到带时间戳的文件夹
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @param content - 要归档的内容
+     */
+    async archiveAbsoluteHtml(fileKey, nodeId, content) {
+        if (!this.workspaceRoot) {
+            Logger.warn('工作目录根路径未设置，无法归档');
+            return;
+        }
+        // 生成时间戳文件夹名：YYYYMMDD_HHmmss
+        const now = new Date();
+        const timestamp = now.getFullYear().toString() +
+            (now.getMonth() + 1).toString().padStart(2, '0') +
+            now.getDate().toString().padStart(2, '0') +
+            '_' +
+            now.getHours().toString().padStart(2, '0') +
+            now.getMinutes().toString().padStart(2, '0') +
+            now.getSeconds().toString().padStart(2, '0');
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+        const cleanNodeId = nodeId ? nodeId.replace(/[^a-zA-Z0-9-_]/g, '_') : 'root';
+        // 归档路径：.sloth/{fileKey}/{nodeId}/history/{timestamp}/absolute.html
+        const archiveDir = path.join(this.workspaceRoot, '.sloth', cleanFileKey, cleanNodeId, 'history', timestamp);
+        try {
+            await fs.mkdir(archiveDir, { recursive: true });
+            const archivePath = path.join(archiveDir, 'absolute.html');
+            await fs.writeFile(archivePath, content, 'utf-8');
+            // 同时复制 index.png 截图（如果存在）
+            const screenshotsDir = this.getScreenshotsDir(fileKey, nodeId);
+            const indexScreenshotPath = path.join(screenshotsDir, 'index.png');
+            try {
+                await fs.access(indexScreenshotPath);
+                const archiveScreenshotPath = path.join(archiveDir, 'index.png');
+                await fs.copyFile(indexScreenshotPath, archiveScreenshotPath);
+                Logger.log(`截图已归档: ${archiveScreenshotPath}`);
+            }
+            catch {
+                // 截图不存在，跳过
+            }
+            Logger.log(`absolute.html 已归档到: ${archivePath}`);
+        }
+        catch (error) {
+            Logger.error(`归档 absolute.html 失败: ${error}`);
+        }
+    }
+    /**
+     * 加载 absolute.html
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns Promise<string> - 文件内容
+     */
+    async loadAbsoluteHtml(fileKey, nodeId, useWorkspaceDir = false) {
+        return this.loadFile(fileKey, nodeId, 'absolute.html', { useWorkspaceDir });
+    }
+    /**
+     * 列出 absolute.html 的所有历史版本
+     * @param fileKey - Figma文件的key
+     * @param nodeId - 节点ID（可选）
+     * @returns Promise<Array<{ timestamp: string; path: string }>> - 历史版本列表
+     */
+    async listAbsoluteHtmlHistory(fileKey, nodeId) {
+        if (!this.workspaceRoot) {
+            return [];
+        }
+        const cleanFileKey = fileKey.replace(/[^a-zA-Z0-9-_]/g, '_');
+        const cleanNodeId = nodeId ? nodeId.replace(/[^a-zA-Z0-9-_]/g, '_') : 'root';
+        const historyDir = path.join(this.workspaceRoot, '.sloth', cleanFileKey, cleanNodeId, 'history');
+        try {
+            const entries = await fs.readdir(historyDir, { withFileTypes: true });
+            const versions = [];
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const htmlPath = path.join(historyDir, entry.name, 'absolute.html');
+                    const screenshotPath = path.join(historyDir, entry.name, 'index.png');
+                    try {
+                        await fs.access(htmlPath);
+                        let screenshot;
+                        try {
+                            await fs.access(screenshotPath);
+                            screenshot = screenshotPath;
+                        }
+                        catch {
+                            // 截图不存在
+                        }
+                        versions.push({
+                            timestamp: entry.name,
+                            path: htmlPath,
+                            screenshotPath: screenshot,
+                        });
+                    }
+                    catch {
+                        // html 文件不存在，跳过
+                    }
+                }
+            }
+            // 按时间戳倒序排列（最新的在前）
+            versions.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+            return versions;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 创建一个临时的 FileManager 代理，仅在本次链式调用中使用指定的 uuid
+     * 不会影响原始实例的 _uuid 值
+     * @param uuid - 临时使用的 uuid
+     * @returns 带有临时 uuid 的 FileManager 代理对象
+     */
+    withUUID(uuid) {
+        if (!uuid) {
+            return this;
+        }
+        const proxy = Object.create(this);
+        proxy._uuid = uuid;
+        return proxy;
+    }
+}
+export default FileManager;