@becrafter/prompt-manager 0.0.19 → 0.1.2

package/packages/server/toolm/tool-environment.service.js

@@ -0,0 +1,200 @@
+/**
+ * 工具环境变量管理服务
+ * 
+ * 职责：
+ * 1. 管理工具的环境变量配置（.env 文件）
+ * 2. 加载环境变量到工具执行环境
+ * 3. 支持 configure 模式更新配置
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { logger } from '../utils/logger.js';
+import { pathExists } from './tool-utils.js';
+
+/**
+ * 加载工具环境变量
+ * @param {string} toolName - 工具名称
+ * @returns {object} 环境变量对象
+ */
+export async function loadToolEnvironment(toolName) {
+  const toolDir = path.join(os.homedir(), '.prompt-manager', 'toolbox', toolName);
+  const envFilePath = path.join(toolDir, '.env');
+  
+  // 检查 .env 文件是否存在
+  if (!await pathExists(envFilePath)) {
+    logger.debug(`工具 ${toolName} 的 .env 文件不存在`);
+    return {};
+  }
+  
+  try {
+    // 读取 .env 文件内容
+    const envContent = await fs.readFile(envFilePath, 'utf-8');
+    
+    // 解析 .env 文件内容
+    const envVars = {};
+    const lines = envContent.split('\n');
+    
+    for (const line of lines) {
+      // 跳过注释和空行
+      const trimmedLine = line.trim();
+      if (!trimmedLine || trimmedLine.startsWith('#')) {
+        continue;
+      }
+      
+      // 解析键值对
+      const equalIndex = trimmedLine.indexOf('=');
+      if (equalIndex === -1) {
+        continue;
+      }
+      
+      const key = trimmedLine.substring(0, equalIndex).trim();
+      let value = trimmedLine.substring(equalIndex + 1).trim();
+      
+      // 处理带引号的值
+      if ((value.startsWith('"') && value.endsWith('"')) || 
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.substring(1, value.length - 1);
+      }
+      
+      // 处理转义字符
+      value = value.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+      
+      // 尝试解析JSON（如果是JSON数组或对象）
+      try {
+        if ((value.startsWith('[') && value.endsWith(']')) || 
+            (value.startsWith('{') && value.endsWith('}'))) {
+          const parsed = JSON.parse(value);
+          envVars[key] = parsed;
+        } else {
+          envVars[key] = value;
+        }
+      } catch {
+        // 不是有效的JSON，直接使用字符串值
+        envVars[key] = value;
+      }
+    }
+    
+    logger.debug(`工具 ${toolName} 环境变量加载成功`, { 
+      count: Object.keys(envVars).length 
+    });
+    
+    return envVars;
+    
+  } catch (error) {
+    logger.error(`加载工具 ${toolName} 的环境变量失败`, { error: error.message });
+    return {};
+  }
+}
+
+/**
+ * 保存工具环境变量配置
+ * @param {string} toolName - 工具名称
+ * @param {object} envVars - 环境变量对象
+ */
+export async function saveToolEnvironment(toolName, envVars) {
+  const toolDir = path.join(os.homedir(), '.prompt-manager', 'toolbox', toolName);
+  await fs.ensureDir(toolDir);
+  
+  const envFilePath = path.join(toolDir, '.env');
+  
+  // 读取现有配置（如果存在）
+  const existingVars = await loadToolEnvironment(toolName);
+  
+  // 合并配置
+  const mergedVars = {
+    ...existingVars,
+    ...envVars
+  };
+  
+  // 生成 .env 文件内容
+  let envContent = `# Tool Environment Variables
+# Tool: ${toolName}
+# Generated by PromptManager ToolEnvironment
+# Last modified: ${new Date().toISOString()}
+
+`;
+  
+  // 写入环境变量
+  for (const [key, value] of Object.entries(mergedVars)) {
+    let escapedValue;
+    
+    // 如果值是对象或数组，转换为JSON字符串
+    if (typeof value === 'object' && value !== null) {
+      escapedValue = JSON.stringify(value);
+    } else {
+      // 转义特殊字符
+      escapedValue = String(value)
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t');
+    }
+    
+    // 如果值包含空格、等号或特殊字符，用引号包裹
+    if (escapedValue.includes(' ') || escapedValue.includes('=') || escapedValue.includes('[') || escapedValue.includes('{')) {
+      escapedValue = `"${escapedValue}"`;
+    }
+    
+    envContent += `${key}=${escapedValue}\n`;
+  }
+  
+  // 写入文件
+  await fs.writeFile(envFilePath, envContent, 'utf-8');
+  
+  logger.info(`工具 ${toolName} 环境变量配置已保存`, { 
+    count: Object.keys(mergedVars).length 
+  });
+}
+
+/**
+ * 获取工具环境变量配置信息
+ * @param {string} toolName - 工具名称
+ * @param {object} schema - 工具的环境变量Schema
+ * @returns {object} 配置信息对象
+ */
+export async function getToolEnvironmentInfo(toolName, schema) {
+  const toolDir = path.join(os.homedir(), '.prompt-manager', 'toolbox', toolName);
+  const envFilePath = path.join(toolDir, '.env');
+  
+  // 加载当前配置
+  const currentVars = await loadToolEnvironment(toolName);
+  
+  // 获取环境变量定义
+  const envProps = schema?.environment?.properties || {};
+  
+  // 构建配置信息
+  const configured = [];
+  const unconfigured = [];
+  
+  for (const [key, def] of Object.entries(envProps)) {
+    const value = currentVars[key];
+    const defaultValue = def.default;
+    
+    if (value !== undefined) {
+      configured.push({
+        key,
+        value,
+        description: def.description || '',
+        status: '✅ 已配置'
+      });
+    } else {
+      unconfigured.push({
+        key,
+        defaultValue,
+        description: def.description || '',
+        status: '⚠️ 使用默认值'
+      });
+    }
+  }
+  
+  return {
+    toolName,
+    envFilePath,
+    configured,
+    unconfigured,
+    hasConfig: await pathExists(envFilePath)
+  };
+}
+

package/packages/server/toolm/tool-execution.service.js

@@ -0,0 +1,277 @@
+/**
+ * 工具执行服务
+ * 
+ * 职责：
+ * 1. 处理工具执行模式
+ * 2. 创建执行上下文
+ * 3. 执行工具并处理错误
+ */
+
+import { logger } from '../utils/logger.js';
+import { toolLoaderService } from './tool-loader.service.js';
+import { ensureToolDependencies } from './tool-dependency.service.js';
+import { createToolContext } from './tool-context.service.js';
+import { generateHelpInfo } from './tool-manual-generator.service.js';
+
+/**
+ * 执行工具
+ * @param {string} toolName - 工具名称
+ * @param {object} parameters - 工具参数
+ * @returns {object} MCP 格式的返回结果
+ */
+export async function executeTool(toolName, parameters) {
+  logger.info(`执行工具: ${toolName}`, { parameters });
+  
+  try {
+    const tool = toolLoaderService.getTool(toolName);
+    const toolModule = tool.module;
+
+    // 1. 确保工具运行环境已初始化（创建 package.json 并安装依赖）
+    await ensureToolDependencies(toolName, toolModule);
+
+    // 2. 创建工具执行上下文
+    const toolContext = await createToolContext(toolName, toolModule);
+    
+    // 3. 记录执行开始
+    toolContext.api.logger.info('执行开始', { 
+      tool: toolName,
+      parameters: Object.keys(parameters)
+    });
+
+    // 4. 执行工具（使用绑定后的execute方法）
+    let result;
+    try {
+      result = await toolContext.execute(parameters);
+      
+      // 5. 记录执行完成
+      toolContext.api.logger.info('执行完成', { 
+        tool: toolName,
+        success: true
+      });
+      
+    } catch (error) {
+      // 记录执行错误
+      toolContext.api.logger.error('执行失败', { 
+        tool: toolName,
+        error: error.message,
+        stack: error.stack
+      });
+      throw error;
+    }
+    
+    logger.info(`工具执行成功: ${toolName}`);
+    
+    // 6. 格式化并返回结果
+    const content = formatToolResult(result, toolName);
+    return { content };
+    
+  } catch (error) {
+    logger.error(`工具执行失败: ${toolName}`, { error: error.message });
+    
+    const tool = toolLoaderService.getTool(toolName);
+    const helpInfo = generateErrorHelpInfo(toolName, error, tool, parameters);
+    
+    return createTextResponse(helpInfo);
+  }
+}
+
+// ============================================================================
+// 辅助函数
+// ============================================================================
+
+/**
+ * 格式化工具执行结果
+ * 根据结果类型自动识别并转换为 MCP 格式的内容
+ * 
+ * @param {any} result - 工具执行结果
+ * @param {string} toolName - 工具名称
+ * @returns {Array} MCP 格式的内容数组
+ */
+function formatToolResult(result, toolName) {
+  const content = [];
+  
+  // 尝试提取图片数据
+  const imageContent = extractImageContent(result);
+  if (imageContent.length > 0) {
+    content.push(...imageContent);
+    
+    // 对于截图操作，只返回图片
+    if (result?.method === 'takeScreenshot') {
+      logger.info('截图成功，返回图片数据');
+      return content;
+    }
+    
+    // 其他操作有图片时，添加文本信息
+    if (result?.text) {
+      content.push(createTextContent(result.text));
+    } else if (result?.method) {
+      content.push(createTextContent(`操作成功：${result.method}`));
+    }
+    
+    return content;
+  }
+  
+  // 处理 file-reader 工具的其他格式（二进制、媒体元信息等）
+  if (result?.format && result?.content) {
+    return [createJsonTextContent(result, toolName)];
+  }
+  
+  // 默认情况：返回 JSON 格式
+  return [createJsonTextContent(result, toolName)];
+}
+
+/**
+ * 从工具结果中提取图片内容
+ * 支持多种工具返回格式：
+ * 1. chrome-devtools: result.images 数组
+ * 2. filesystem: result.base64 + result.mimeType (图片类型)
+ * 3. file-reader: result.format === 'image' + result.content.base64
+ * 
+ * @param {any} result - 工具执行结果
+ * @returns {Array} 图片内容数组
+ */
+function extractImageContent(result) {
+  const images = [];
+  
+  if (!result) {
+    return images;
+  }
+  
+  // 情况1: chrome-devtools 工具返回的图片数组
+  if (Array.isArray(result.images) && result.images.length > 0) {
+    for (const image of result.images) {
+      if (image?.data && image?.mimeType) {
+        images.push(createImageContent(image.data, image.mimeType));
+      }
+    }
+    return images;
+  }
+  
+  // 情况2: filesystem 工具的 read_media_file 返回的 base64 + mimeType
+  if (result.base64 && result.mimeType && result.mimeType.startsWith('image/')) {
+    images.push(createImageContent(result.base64, result.mimeType));
+    logger.info('读取图片文件成功，返回图片数据');
+    return images;
+  }
+  
+  // 情况3: file-reader 工具返回的图片格式
+  if (result.format === 'image' && result.content?.base64 && result.content?.mimeType) {
+    images.push(createImageContent(result.content.base64, result.content.mimeType));
+    
+    // 如果有描述信息，也一并返回
+    if (result.content.description) {
+      images.push(createTextContent(result.content.description));
+    }
+    logger.info('读取图片文件成功，返回图片数据');
+    return images;
+  }
+  
+  return images;
+}
+
+/**
+ * 创建图片类型的内容
+ * 
+ * @param {string} data - base64 编码的图片数据
+ * @param {string} mimeType - 图片 MIME 类型
+ * @returns {object} MCP 图片内容对象
+ */
+function createImageContent(data, mimeType) {
+  return {
+    type: "image",
+    data: data,
+    mimeType: mimeType
+  };
+}
+
+/**
+ * 创建文本类型的内容
+ * 
+ * @param {string} text - 文本内容
+ * @returns {object} MCP 文本内容对象
+ */
+function createTextContent(text) {
+  return {
+    type: "text",
+    text: text
+  };
+}
+
+/**
+ * 创建 JSON 格式的文本内容
+ * 
+ * @param {any} result - 工具执行结果
+ * @param {string} toolName - 工具名称
+ * @returns {object} MCP 文本内容对象
+ */
+function createJsonTextContent(result, toolName) {
+  return createTextContent(
+    JSON.stringify({
+      success: true,
+      tool: toolName,
+      mode: 'execute',
+      result: result
+    }, null, 2)
+  );
+}
+
+/**
+ * 创建文本类型的响应
+ * 
+ * @param {string} text - 文本内容
+ * @returns {object} MCP 格式的响应对象
+ */
+function createTextResponse(text) {
+  return {
+    content: [createTextContent(text)]
+  };
+}
+
+/**
+ * 生成错误帮助信息
+ * 
+ * @param {string} toolName - 工具名称
+ * @param {Error} error - 错误对象
+ * @param {object} tool - 工具对象
+ * @param {object} parameters - 工具参数
+ * @returns {string} 帮助信息文本
+ */
+function generateErrorHelpInfo(toolName, error, tool, parameters) {
+  // 检查是否是参数验证错误
+  if (isValidationErrorType(error.message)) {
+    return generateHelpInfo(toolName, error, tool, parameters);
+  }
+  
+  // 检查是否是业务错误
+  const businessErrors = tool?.businessErrors || [];
+  for (const businessError of businessErrors) {
+    if (businessError.match?.test(error.message)) {
+      return generateHelpInfo(toolName, error, tool, parameters, businessError);
+    }
+  }
+  
+  // 其他错误也返回帮助信息
+  return generateHelpInfo(toolName, error, tool, parameters);
+}
+
+/**
+ * 判断是否是参数验证错误
+ * 
+ * @param {string} errorMessage - 错误消息
+ * @returns {boolean} 是否是参数验证错误
+ */
+function isValidationErrorType(errorMessage) {
+  const validationPatterns = [
+    /不支持的方法/i,
+    /缺少必需参数/i,
+    /缺少参数/i,
+    /参数.*必须是/i,
+    /参数.*的值必须是/i,
+    /无效的参数/i,
+    /参数.*类型错误/i,
+    /参数.*格式错误/i
+  ];
+  
+  return validationPatterns.some(pattern => pattern.test(errorMessage));
+}
+

package/packages/server/toolm/tool-loader.service.js

@@ -0,0 +1,219 @@
+/**
+ * 工具加载服务
+ * 
+ * 职责：
+ * 1. 扫描并加载 ~/.prompt-manager/tools 和 packages/resources/tools 目录下的所有工具
+ * 2. 验证工具是否符合标准接口规范
+ * 3. 提供工具元数据注册表
+ * 4. 管理工具体验生命周期
+ * 5. 实现工具的四种运行模式 (manual, execute, configure, log)
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { logger } from '../utils/logger.js';
+import { pathExists } from './tool-utils.js';
+import { generateManual as generateManualFromService } from './tool-manual-generator.service.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+class ToolLoaderService {
+  constructor() {
+    // 工具缓存：toolName -> toolModule
+    this.toolCache = new Map();
+    
+    // 工具目录列表（所有工具都在沙箱环境中）
+    this.toolDirectories = [
+      // 沙箱工具目录（系统工具和用户工具都在这里）
+      path.join(os.homedir(), '.prompt-manager', 'toolbox')
+    ];
+    
+    // 已初始化标志
+    this.initialized = false;
+  }
+
+  /**
+   * 初始化工具加载器
+   * 扫描所有工具目录并加载工具
+   */
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+
+    logger.info('初始化工具加载器...');
+    
+    // 确保工具箱目录存在
+    const toolboxDir = path.join(os.homedir(), '.prompt-manager', 'toolbox');
+    await fs.ensureDir(toolboxDir);
+    
+    // 扫描并加载所有工具
+    await this.scanAndLoadTools();
+    
+    this.initialized = true;
+    logger.info(`工具加载器初始化完成，共加载 ${this.toolCache.size} 个工具`);
+  }
+
+  /**
+   * 扫描并加载所有工具目录中的工具
+   */
+  async scanAndLoadTools() {
+    for (const toolsDir of this.toolDirectories) {
+      if (!await pathExists(toolsDir)) {
+        logger.debug(`工具目录不存在，跳过: ${toolsDir}`);
+        continue;
+      }
+
+      try {
+        const entries = await fs.readdir(toolsDir, { withFileTypes: true });
+        
+        for (const entry of entries) {
+          if (!entry.isDirectory()) {
+            continue;
+          }
+
+          const toolName = entry.name;
+          const toolDir = path.join(toolsDir, toolName);
+          const toolFile = path.join(toolDir, `${toolName}.tool.js`);
+          
+          if (await pathExists(toolFile)) {
+            try {
+              await this.loadTool(toolName, toolFile);
+            } catch (error) {
+              logger.error(`加载工具失败: ${toolName}`, { error: error.message });
+            }
+          }
+        }
+      } catch (error) {
+        logger.error(`扫描工具目录失败: ${toolsDir}`, { error: error.message });
+      }
+    }
+  }
+
+  /**
+   * 加载单个工具
+   * @param {string} toolName - 工具名称
+   * @param {string} toolFile - 工具文件路径
+   */
+  async loadTool(toolName, toolFile) {
+    logger.debug(`加载工具: ${toolName}`, { file: toolFile });
+
+    // 动态导入工具模块
+    const toolModule = await import(toolFile);
+    const tool = toolModule.default || toolModule;
+
+    // 验证工具接口
+    this.validateToolInterface(toolName, tool);
+
+    // 缓存工具实例
+    this.toolCache.set(toolName, {
+      name: toolName,
+      file: toolFile,
+      module: tool,
+      metadata: tool.getMetadata ? tool.getMetadata() : { name: toolName },
+      schema: tool.getSchema ? tool.getSchema() : {},
+      businessErrors: tool.getBusinessErrors ? tool.getBusinessErrors() : []
+    });
+
+    logger.info(`工具加载成功: ${toolName}`);
+  }
+
+  /**
+   * 验证工具接口是否符合规范
+   * @param {string} toolName - 工具名称
+   * @param {object} tool - 工具模块
+   */
+  validateToolInterface(toolName, tool) {
+    // 必需的方法
+    const requiredMethods = ['execute'];
+    
+    // 推荐的方法
+    const recommendedMethods = ['getMetadata', 'getSchema', 'getDependencies', 'getBusinessErrors'];
+
+    // 检查必需方法
+    for (const method of requiredMethods) {
+      if (typeof tool[method] !== 'function') {
+        throw new Error(`工具 ${toolName} 缺少必需方法: ${method}`);
+      }
+    }
+
+    // 检查推荐方法
+    for (const method of recommendedMethods) {
+      if (typeof tool[method] !== 'function') {
+        logger.warn(`工具 ${toolName} 缺少推荐方法: ${method}`);
+      }
+    }
+  }
+
+  /**
+   * 获取工具实例
+   * @param {string} toolName - 工具名称
+   * @returns {object} 工具实例
+   */
+  getTool(toolName) {
+    if (!this.initialized) {
+      throw new Error('工具加载器尚未初始化，请先调用 initialize()');
+    }
+
+    const tool = this.toolCache.get(toolName);
+    if (!tool) {
+      const availableTools = Array.from(this.toolCache.keys()).join(', ');
+      throw new Error(`工具 '${toolName}' 不存在。可用工具: ${availableTools}`);
+    }
+
+    return tool;
+  }
+
+  /**
+   * 获取所有已加载的工具列表
+   * @returns {Array} 工具列表
+   */
+  getAllTools() {
+    if (!this.initialized) {
+      throw new Error('工具加载器尚未初始化，请先调用 initialize()');
+    }
+
+    return Array.from(this.toolCache.values()).map(tool => ({
+      name: tool.name,
+      metadata: tool.metadata,
+      schema: tool.schema
+    }));
+  }
+
+  /**
+   * 检查工具是否存在
+   * @param {string} toolName - 工具名称
+   * @returns {boolean}
+   */
+  hasTool(toolName) {
+    return this.toolCache.has(toolName);
+  }
+
+  /**
+   * 重新加载所有工具
+   */
+  async reload() {
+    logger.info('重新加载所有工具...');
+    this.toolCache.clear();
+    this.initialized = false;
+    await this.initialize();
+  }
+
+  /**
+   * 生成工具手册（manual模式）
+   * @param {string} toolName - 工具名称
+   * @returns {string} Markdown格式的手册
+   */
+  generateManual(toolName) {
+    // 使用统一的工具手册生成服务
+    const tool = this.getTool(toolName);
+    return generateManualFromService(toolName, tool);
+  }
+}
+
+// 导出单例实例
+export const toolLoaderService = new ToolLoaderService();
+