@becrafter/prompt-manager 0.0.19 → 0.1.2

package/packages/resources/tools/filesystem/filesystem.tool.js

@@ -1,184 +1,538 @@
-import fs from 'fs-extra';
-import path from 'path';
-
 /**
- * 文件系统工具
- * @param {Object} params - 工具参数
- * @param {string} mode - 操作模式
- * @returns {Promise<Object>} 执行结果
+ * Filesystem Tool - Prompt Manager 体系的文件系统基础设施
+ * 
+ * 战略意义：
+ * 
+ * 1. 架构隔离性
+ * 专为 Prompt Manager 体系设计，通过沙箱隔离确保文件操作不会影响
+ * Prompt Manager 核心功能。即使 AI Agent 出错，也不会破坏系统稳定性。
+ * 
+ * 2. 平台独立性  
+ * 虽然很多 AI 平台自带文件工具，但 Prompt Manager 需要自己的实现来保证：
+ * - 在无本地工具的 Web Agent 平台上也能工作
+ * - 统一的操作语义，不依赖特定 AI 平台
+ * - 可移植到任何支持 MCP 协议的环境
+ * 
+ * 3. 生态自主性
+ * 作为 Prompt Manager 工具生态的基础组件，filesystem 确保了：
+ * - 其他工具可以依赖稳定的文件操作接口
+ * - 用户数据始终在 Prompt Manager 控制范围内
+ * - 未来可扩展更多存储后端（云存储、分布式等）
+ * 
+ * 这不仅是一个文件操作工具，更是 Prompt Manager 实现平台独立、
+ * 生态自主的关键基础设施。
  */
-export default async function filesystem(params, mode = 'execute') {
-  // 根据模式执行不同的操作
-  switch (mode) {
-    case 'manual':
-      // 生成 Markdown 格式的手册
-      return generateManual();
 
-    case 'execute':
-      // 执行模式 - 实际执行操作
-      const { action, path: filePath, content } = params;
+import path from 'path';
+import os from 'os';
+
+export default {
+  /**
+   * 获取工具依赖
+   * 使用 Node.js 内置模块，无需额外依赖
+   */
+  getDependencies() {
+    return {
+      // 使用 Node.js 内置 fs、path 等模块，无需额外依赖
+    };
+  },
+
+  /**
+   * 获取工具元信息
+   */
+  getMetadata() {
+    return {
+      id: 'filesystem',
+      name: 'filesystem',
+      description: '基于MCP标准的文件系统操作工具，提供读写、搜索、编辑等功能',
+      version: '2.0.0',
+      category: 'system',
+      author: 'Prompt Manager',
+      tags: ['file', 'system', 'io', 'mcp'],
+      scenarios: [
+        '文件读写操作',
+        '目录管理和遍历',
+        '文件搜索和批量处理',
+        'Prompt Manager资源文件管理',
+        '项目文件结构分析'
+      ],
+      limitations: [
+        '默认只能访问 ~/.prompt-manager 目录',
+        '可通过环境变量配置额外允许的目录',
+        '不支持符号链接操作',
+        '单文件大小建议不超过10MB'
+      ]
+    };
+  },
+
+  /**
+   * 获取参数Schema
+   */
+  getSchema() {
+    return {
+      parameters: {
+        type: 'object',
+        properties: {
+          method: {
+            type: 'string',
+            description: 'MCP方法名',
+            enum: [
+              'read_text_file',
+              'read_media_file', 
+              'read_multiple_files',
+              'write_file',
+              'edit_file',
+              'create_directory',
+              'list_directory',
+              'list_directory_with_sizes',
+              'directory_tree',
+              'move_file',
+              'search_files',
+              'get_file_info',
+              'list_allowed_directories'
+            ]
+          },
+          // 通用参数，根据method动态使用
+          path: { type: 'string', description: '文件或目录路径' },
+          paths: { type: 'array', items: { type: 'string' }, description: '多个文件路径' },
+          content: { type: 'string', description: '文件内容' },
+          head: { type: 'number', description: '读取前N行' },
+          tail: { type: 'number', description: '读取后N行' },
+          edits: {
+            type: 'array',
+            description: '编辑操作列表，每个元素为对象: {oldText: "要替换的文本", newText: "新文本"}',
+            items: {
+              type: 'object',
+              properties: {
+                oldText: {
+                  type: 'string',
+                  description: '要替换的原始文本（必须完全匹配）'
+                },
+                newText: {
+                  type: 'string',
+                  description: '替换后的新文本'
+                }
+              },
+              required: ['oldText', 'newText']
+            }
+          },
+          dryRun: { type: 'boolean', description: '仅预览不执行' },
+          source: { type: 'string', description: '源路径' },
+          destination: { type: 'string', description: '目标路径' },
+          pattern: { type: 'string', description: '搜索模式' },
+          excludePatterns: { type: 'array', items: { type: 'string' }, description: '排除模式' },
+          sortBy: { type: 'string', enum: ['name', 'size'], description: '排序方式' }
+        },
+        required: ['method']
+      },
+      environment: {
+        type: 'object',
+        properties: {
+          ALLOWED_DIRECTORIES: {
+            type: 'string',
+            description: '允许访问的目录列表（JSON数组格式），默认为 ["~/.prompt-manager"]',
+            default: '["~/.prompt-manager"]'
+          }
+        },
+        required: []
+      }
+    };
+  },
+
+  /**
+   * 获取业务错误定义
+   */
+  getBusinessErrors() {
+    return [
+      {
+        code: 'PATH_OUTSIDE_SCOPE',
+        description: '路径越权访问',
+        match: /路径越权/,
+        solution: '确保路径在允许的目录范围内',
+        retryable: false
+      },
+      {
+        code: 'FILE_NOT_FOUND',
+        description: '文件或目录不存在',
+        match: /ENOENT|no such file|cannot find/i,
+        solution: '检查文件路径是否正确',
+        retryable: false
+      },
+      {
+        code: 'PERMISSION_DENIED',
+        description: '权限不足',
+        match: /EACCES|permission denied/i,
+        solution: '检查文件或目录的访问权限',
+        retryable: false
+      },
+      {
+        code: 'FILE_TOO_LARGE',
+        description: '文件过大',
+        match: /File too large|ENOBUFS|too big/i,
+        solution: '文件大小不应超过10MB',
+        retryable: false
+      },
+      {
+        code: 'DIRECTORY_NOT_EMPTY',
+        description: '目录非空',
+        match: /ENOTEMPTY|directory not empty/i,
+        solution: '清空目录后再试',
+        retryable: false
+      },
+      {
+        code: 'INVALID_PATH',
+        description: '无效路径',
+        match: /invalid path|illegal characters/i,
+        solution: '检查路径格式是否正确',
+        retryable: false
+      }
+    ];
+  },
+
+  /**
+   * 执行工具 - 包装MCP实现
+   * 
+   * 注意：文件系统基础能力（getAllowedDirectories、initializeFilesystem、resolvePromptManagerPath）
+   * 已由框架层提供，工具可直接通过 this 调用这些方法
+   */
+  async execute(params) {
+    const { api } = this;
+    
+    // 记录执行开始
+    api?.logger?.info('Executing filesystem operation', { 
+      method: params.method,
+      path: params.path || params.paths || params.source
+    });
+    
+    // 参数验证由 ToolValidator 根据 getSchema() 自动处理
+    // 这里进行 method 相关的业务验证
+    const methodRequirements = {
+      'read_text_file': ['path'],
+      'read_media_file': ['path'],
+      'read_multiple_files': ['paths'],
+      'write_file': ['path', 'content'],
+      'edit_file': ['path', 'edits'],
+      'create_directory': ['path'],
+      'list_directory': ['path'],
+      'list_directory_with_sizes': ['path'],
+      'directory_tree': ['path'],
+      'move_file': ['source', 'destination'],
+      'search_files': ['path', 'pattern'],
+      'get_file_info': ['path'],
+      'list_allowed_directories': []
+    };
+
+    const required = methodRequirements[params.method];
+    if (!required) {
+      throw new Error(`不支持的方法: ${params.method}`);
+    }
+
+    const missing = required.filter(field => !params[field]);
+    if (missing.length > 0) {
+      throw new Error(`方法 ${params.method} 缺少必需参数: ${missing.join(', ')}`);
+    }
+
+    try {
+      // 初始化文件系统
+      await this.initializeFilesystem();
+      
+      // 导入 fs 模块
+      const fs = await import('fs');
+      const fsPromises = fs.promises;
       
-      if (!action) {
-        throw new Error('缺少必需参数: action');
+      // 特殊处理list_allowed_directories
+      if (params.method === 'list_allowed_directories') {
+        // 使用已初始化的目录列表，如果未初始化则获取
+        const dirs = this._allowedDirectories ?? this.getAllowedDirectories();
+        api?.logger?.info('Returning allowed directories', { directories: dirs });
+        return dirs;
       }
+
+      // 准备MCP调用参数
+      let mcpParams = { ...params };
       
-      if (!filePath) {
-        throw new Error('缺少必需参数: path');
+      // 路径参数转换
+      if (params.path) {
+        mcpParams.path = this.resolvePromptManagerPath(params.path);
       }
       
-      switch (action) {
-        case 'read':
-          try {
-            const fileContent = await fs.readFile(filePath, 'utf8');
-            return {
-              success: true,
-              action: 'read',
-              path: filePath,
-              content: fileContent
-            };
-          } catch (error) {
-            throw new Error(`读取文件失败: ${error.message}`);
-          }
+      if (params.paths) {
+        mcpParams.paths = params.paths.map(p => this.resolvePromptManagerPath(p));
+      }
+      
+      if (params.source) {
+        mcpParams.source = this.resolvePromptManagerPath(params.source);
+      }
+      
+      if (params.destination) {
+        mcpParams.destination = this.resolvePromptManagerPath(params.destination);
+      }
+
+      // 执行对应的文件系统操作
+      let result;
+      switch (params.method) {
+        case 'read_text_file': {
+          const content = await fsPromises.readFile(mcpParams.path, 'utf-8');
           
-        case 'write':
-          if (content === undefined) {
-            throw new Error('写入文件需要提供 content 参数');
+          if (params.head) {
+            // 返回前 N 行
+            const lines = content.split('\n');
+            result = lines.slice(0, params.head).join('\n');
+          } else if (params.tail) {
+            // 返回后 N 行
+            const lines = content.split('\n');
+            result = lines.slice(-params.tail).join('\n');
+          } else {
+            result = content;
           }
+          break;
+        }
+          
+        case 'read_media_file': {
+          // 读取二进制文件并转base64
+          const buffer = await fsPromises.readFile(mcpParams.path);
+          const base64 = buffer.toString('base64');
+          const ext = path.extname(mcpParams.path).toLowerCase();
+          const mimeTypes = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp',
+            '.svg': 'image/svg+xml',
+            '.mp3': 'audio/mpeg',
+            '.wav': 'audio/wav'
+          };
+          result = {
+            base64: base64,
+            mimeType: mimeTypes[ext] || 'application/octet-stream'
+          };
+          break;
+        }
+          
+        case 'read_multiple_files':
+          result = await Promise.all(
+            mcpParams.paths.map(async (filePath, index) => {
+              try {
+                const content = await fsPromises.readFile(filePath, 'utf-8');
+                return {
+                  path: params.paths[index], // 返回原始相对路径
+                  content: content,
+                  success: true
+                };
+              } catch (error) {
+                return {
+                  path: params.paths[index],
+                  error: error.message,
+                  success: false
+                };
+              }
+            })
+          );
+          break;
+          
+        case 'write_file': {
+          // 自动创建父目录
+          const dirPath = path.dirname(mcpParams.path);
+          
           try {
-            await fs.writeFile(filePath, content, 'utf8');
-            return {
-              success: true,
-              action: 'write',
-              path: filePath,
-              message: '文件写入成功'
-            };
-          } catch (error) {
-            throw new Error(`写入文件失败: ${error.message}`);
+            // 检查目录是否存在，不存在则创建
+            await fsPromises.access(dirPath);
+          } catch {
+            // 目录不存在，创建它
+            await fsPromises.mkdir(dirPath, { recursive: true });
+            api?.logger?.info('Auto-created directory for write_file', { directory: dirPath });
           }
           
-        case 'list':
-          try {
-            const items = await fs.readdir(filePath);
-            return {
-              success: true,
-              action: 'list',
-              path: filePath,
-              items: items
+          await fsPromises.writeFile(mcpParams.path, params.content, 'utf-8');
+          result = {
+            bytesWritten: Buffer.byteLength(params.content, 'utf-8'),
+            path: params.path
+          };
+          break;
+        }
+          
+        case 'edit_file': {
+          // 读取文件内容
+          let content = await fsPromises.readFile(mcpParams.path, 'utf-8');
+          
+          // 应用编辑
+          for (const edit of params.edits) {
+            content = content.replace(edit.oldText, edit.newText);
+          }
+          
+          if (params.dryRun) {
+            // 预览模式，返回修改后的内容
+            result = content;
+          } else {
+            // 写回文件
+            await fsPromises.writeFile(mcpParams.path, content, 'utf-8');
+            result = {
+              editsApplied: params.edits.length,
+              path: params.path
             };
-          } catch (error) {
-            throw new Error(`列出目录内容失败: ${error.message}`);
           }
+          break;
+        }
           
-        case 'delete':
-          try {
-            const stats = await fs.stat(filePath);
-            if (stats.isDirectory()) {
-              await fs.rm(filePath, { recursive: true });
-              return {
-                success: true,
-                action: 'delete',
-                path: filePath,
-                type: 'directory',
-                message: '目录删除成功'
-              };
+        case 'create_directory': {
+          await fsPromises.mkdir(mcpParams.path, { recursive: true });
+          result = { created: mcpParams.path };
+          break;
+        }
+          
+        case 'list_directory':
+        case 'list_directory_with_sizes': {
+          const entries = await fsPromises.readdir(mcpParams.path, { withFileTypes: true });
+          
+          if (params.method === 'list_directory') {
+            result = entries.map(entry => ({
+              name: entry.name,
+              type: entry.isDirectory() ? 'directory' : 'file'
+            }));
+          } else {
+            result = await Promise.all(
+              entries.map(async (entry) => {
+                const entryPath = path.join(mcpParams.path, entry.name);
+                const stats = await fsPromises.stat(entryPath);
+                return {
+                  name: entry.name,
+                  type: entry.isDirectory() ? 'directory' : 'file',
+                  size: stats.size,
+                  modified: stats.mtime
+                };
+              })
+            );
+            
+            if (params.sortBy === 'size') {
+              result.sort((a, b) => b.size - a.size);
             } else {
-              await fs.unlink(filePath);
-              return {
-                success: true,
-                action: 'delete',
-                path: filePath,
-                type: 'file',
-                message: '文件删除成功'
-              };
+              result.sort((a, b) => a.name.localeCompare(b.name));
             }
-          } catch (error) {
-            throw new Error(`删除文件或目录失败: ${error.message}`);
           }
+          break;
+        }
+          
+        case 'directory_tree': {
+          // 构建目录树
+          const buildTree = async (currentPath) => {
+            const entries = await fsPromises.readdir(currentPath, { withFileTypes: true });
+            const tree = [];
+            
+            for (const entry of entries) {
+              const entryPath = path.join(currentPath, entry.name);
+              const node = {
+                name: entry.name,
+                type: entry.isDirectory() ? 'directory' : 'file'
+              };
+              
+              if (entry.isDirectory()) {
+                try {
+                  node.children = await buildTree(entryPath);
+                } catch (error) {
+                  node.children = [];
+                  node.error = error.message;
+                }
+              }
+              
+              tree.push(node);
+            }
+            
+            return tree;
+          };
+          
+          result = await buildTree(mcpParams.path);
+          break;
+        }
+          
+        case 'move_file': {
+          await fsPromises.rename(mcpParams.source, mcpParams.destination);
+          result = {
+            from: params.source,
+            to: params.destination
+          };
+          break;
+        }
+          
+        case 'search_files': {
+          // 递归搜索文件（使用内置fs，不依赖glob）
+          const searchFiles = async (dir, pattern) => {
+            const results = [];
+            const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+            
+            for (const entry of entries) {
+              const fullPath = path.join(dir, entry.name);
+              
+              // 检查排除模式
+              if (params.excludePatterns) {
+                const shouldExclude = params.excludePatterns.some(excludePattern => {
+                  return entry.name.match(new RegExp(excludePattern.replace(/\*/g, '.*')));
+                });
+                if (shouldExclude) continue;
+              }
+              
+              if (entry.isDirectory()) {
+                // 递归搜索子目录
+                try {
+                  const subResults = await searchFiles(fullPath, pattern);
+                  results.push(...subResults);
+                } catch (error) {
+                  // 忽略无权访问的目录
+                }
+              } else {
+                // 检查文件名是否匹配模式
+                const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
+                if (regex.test(entry.name)) {
+                  results.push(fullPath);
+                }
+              }
+            }
+            
+            return results;
+          };
+          
+          const foundFiles = await searchFiles(mcpParams.path, params.pattern);
+          
+          // 转换为相对路径（相对于第一个允许的目录）
+          const allowedDirs = this._allowedDirectories ?? this.getAllowedDirectories();
+          const baseDir = allowedDirs[0];
+          result = foundFiles.map(file => path.relative(baseDir, file));
+          break;
+        }
+          
+        case 'get_file_info': {
+          const stats = await fsPromises.stat(mcpParams.path);
+          result = {
+            size: stats.size,
+            created: stats.birthtime,
+            modified: stats.mtime,
+            accessed: stats.atime,
+            isDirectory: stats.isDirectory(),
+            isFile: stats.isFile(),
+            permissions: stats.mode
+          };
+          break;
+        }
           
         default:
-          throw new Error(`不支持的操作类型: ${action}`);
+          throw new Error(`不支持的方法: ${params.method}`);
       }
       
-    default:
-      throw new Error(`不支持的模式: ${mode}`);
+      // 记录执行成功
+      api?.logger?.info('Filesystem operation completed', { 
+        method: params.method,
+        success: true 
+      });
+      
+      return result;
+      
+    } catch (error) {
+      // 记录错误
+      api?.logger?.error('Filesystem operation failed', { 
+        method: params.method,
+        error: error.message 
+      });
+      throw error;
+    }
   }
-}
-
-/**
- * 生成 Markdown 格式的手册
- * @returns {string} Markdown 格式的手册
- */
-function generateManual() {
-  return `# 🔧 filesystem
-
-> 文件系统工具 - 用于文件操作
-
-## 📋 基础信息
-
-- **标识**: \`tool://filesystem\`
-- **分类**: 系统工具
-
-## ✅ 适用场景
-
-- 读取文件内容进行分析
-- 写入文件内容保存数据
-- 列出目录内容查看文件结构
-- 删除文件或目录进行清理
-
-## 📝 参数定义
-
-### execute 模式参数
-
-| 参数 | 类型 | 必需 | 描述 | 默认值 |
-|------|------|------|------|--------|
-| action | string (read|write|list|delete) | ✅ | 操作类型 | - |
-| path | string | ✅ | 文件或目录路径 | - |
-| content | string | ❌ | 写入的文件内容 (仅在action为write时需要) | - |
-
-## 💻 使用示例
-
-通过 toolx 调用，使用 YAML 格式：
-
-\`\`\`yaml
-# 读取文件内容
-tool: tool://filesystem
-mode: execute
-parameters:
-  action: read
-  path: /path/to/file.txt
-
-# 写入文件内容
-tool: tool://filesystem
-mode: execute
-parameters:
-  action: write
-  path: /path/to/file.txt
-  content: "Hello, World!"
-
-# 列出目录内容
-tool: tool://filesystem
-mode: execute
-parameters:
-  action: list
-  path: /path/to/directory
-
-# 删除文件或目录
-tool: tool://filesystem
-mode: execute
-parameters:
-  action: delete
-  path: /path/to/file-or-directory
-\`\`\`
-
-## 🚨 业务错误
-
-| 错误码 | 描述 | 解决方案 | 可重试 |
-|--------|------|----------|--------|
-| MISSING_ACTION | 缺少必需参数: action | 提供 action 参数 | ❌ |
-| MISSING_PATH | 缺少必需参数: path | 提供 path 参数 | ❌ |
-| READ_FAILED | 读取文件失败 | 检查文件路径是否存在且可读 | ✅ |
-| WRITE_FAILED | 写入文件失败 | 检查文件路径是否可写 | ✅ |
-| LIST_FAILED | 列出目录内容失败 | 检查目录路径是否存在且可读 | ✅ |
-| DELETE_FAILED | 删除文件或目录失败 | 检查文件或目录是否存在且可删除 | ✅ |
-`;
-}
+};