@becrafter/prompt-manager 0.0.19 → 0.1.1

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

@@ -0,0 +1,223 @@
+/**
+ * 工具日志记录服务
+ * 
+ * 职责：
+ * 1. 为每个工具提供独立的日志记录器
+ * 2. 日志自动写入到工具的 run.log 文件
+ * 3. 自动清理过期日志
+ * 4. 限制日志文件大小
+ */
+
+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';
+
+// 日志队列，用于批量写入
+const logQueues = new Map();
+
+// 日志清理间隔（1小时）
+const CLEANUP_INTERVAL = 60 * 60 * 1000;
+
+// 日志保留时间（3小时）
+const LOG_RETENTION_HOURS = 3;
+
+// 最大日志文件大小（10MB）
+const MAX_LOG_SIZE = 10 * 1024 * 1024;
+
+// 当日志文件过大时保留的行数
+const MAX_LOG_LINES = 1000;
+
+/**
+ * 获取工具日志记录器
+ * @param {string} toolName - 工具名称
+ * @returns {object} 日志记录器对象
+ */
+export function getLogger(toolName) {
+  if (!logQueues.has(toolName)) {
+    logQueues.set(toolName, []);
+  }
+  
+  const logQueue = logQueues.get(toolName);
+  
+  return {
+    info: (message, meta) => log(toolName, 'INFO', message, meta),
+    warn: (message, meta) => log(toolName, 'WARN', message, meta),
+    error: (message, meta) => log(toolName, 'ERROR', message, meta),
+    debug: (message, meta) => log(toolName, 'DEBUG', message, meta)
+  };
+  
+  function log(toolName, level, message, meta = {}) {
+    const timestamp = new Date().toISOString();
+    const metaStr = meta && Object.keys(meta).length > 0 
+      ? ' ' + JSON.stringify(meta)
+      : '';
+    
+    const logEntry = `[${timestamp}] [${level}] ${message}${metaStr}\n`;
+    
+    // 添加到队列
+    logQueue.push(logEntry);
+    
+    // 如果队列达到一定大小，立即刷新
+    if (logQueue.length >= 10) {
+      flushLogQueue(toolName).catch(error => {
+        logger.error(`刷新工具日志队列失败: ${toolName}`, { error: error.message });
+      });
+    } else {
+      // 延迟刷新，批量写入
+      setTimeout(() => {
+        flushLogQueue(toolName).catch(error => {
+          logger.error(`刷新工具日志队列失败: ${toolName}`, { error: error.message });
+        });
+      }, 100);
+    }
+  }
+}
+
+/**
+ * 刷新日志队列
+ * @param {string} toolName - 工具名称
+ */
+async function flushLogQueue(toolName) {
+  const logQueue = logQueues.get(toolName);
+  if (!logQueue || logQueue.length === 0) {
+    return;
+  }
+  
+  const toolDir = path.join(os.homedir(), '.prompt-manager', 'toolbox', toolName);
+  const logFilePath = path.join(toolDir, 'run.log');
+  
+  try {
+    // 确保目录存在
+    await fs.ensureDir(toolDir);
+    
+    // 读取现有日志（如果存在）
+    let existingLogs = '';
+    if (await pathExists(logFilePath)) {
+      existingLogs = await fs.readFile(logFilePath, 'utf-8');
+    }
+    
+    // 清理过期日志
+    const cleanedLogs = cleanOldLogs(existingLogs);
+    
+    // 合并新日志
+    const newLogs = logQueue.join('');
+    const allLogs = cleanedLogs + newLogs;
+    
+    // 检查日志文件大小
+    const logsToWrite = allLogs.length > MAX_LOG_SIZE
+      ? keepRecentLogs(allLogs)
+      : allLogs;
+    
+    // 写入日志文件
+    await fs.writeFile(logFilePath, logsToWrite, 'utf-8');
+    
+    // 清空队列
+    logQueue.length = 0;
+    
+  } catch (error) {
+    logger.error(`写入工具日志失败: ${toolName}`, { error: error.message });
+  }
+}
+
+/**
+ * 清理过期日志
+ * @param {string} logs - 日志内容
+ * @returns {string} 清理后的日志
+ */
+function cleanOldLogs(logs) {
+  const lines = logs.split('\n');
+  const now = Date.now();
+  const retentionMs = LOG_RETENTION_HOURS * 60 * 60 * 1000;
+  
+  const validLines = [];
+  
+  for (const line of lines) {
+    if (!line.trim()) {
+      validLines.push(line);
+      continue;
+    }
+    
+    // 提取时间戳
+    const timestampMatch = line.match(/^\[([^\]]+)\]/);
+    if (timestampMatch) {
+      try {
+        const timestamp = new Date(timestampMatch[1]).getTime();
+        if (now - timestamp < retentionMs) {
+          validLines.push(line);
+        }
+      } catch (error) {
+        // 无法解析时间戳，保留该行
+        validLines.push(line);
+      }
+    } else {
+      // 没有时间戳，保留该行
+      validLines.push(line);
+    }
+  }
+  
+  return validLines.join('\n');
+}
+
+/**
+ * 保留最近的日志行
+ * @param {string} logs - 日志内容
+ * @returns {string} 保留的日志
+ */
+function keepRecentLogs(logs) {
+  const lines = logs.split('\n');
+  const recentLines = lines.slice(-MAX_LOG_LINES);
+  return recentLines.join('\n') + '\n';
+}
+
+/**
+ * 启动定期清理任务
+ */
+export function startLogCleanupTask() {
+  setInterval(async () => {
+    const toolboxDir = path.join(os.homedir(), '.prompt-manager', 'toolbox');
+    
+    if (!await pathExists(toolboxDir)) {
+      return;
+    }
+    
+    try {
+      const entries = await fs.readdir(toolboxDir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+        
+        const toolName = entry.name;
+        const logFilePath = path.join(toolboxDir, toolName, 'run.log');
+        
+        if (await pathExists(logFilePath)) {
+          const logs = await fs.readFile(logFilePath, 'utf-8');
+          const cleanedLogs = cleanOldLogs(logs);
+          
+          if (cleanedLogs.length < logs.length) {
+            await fs.writeFile(logFilePath, cleanedLogs, 'utf-8');
+            logger.debug(`清理工具日志: ${toolName}`);
+          }
+        }
+      }
+    } catch (error) {
+      logger.error('定期清理日志失败', { error: error.message });
+    }
+  }, CLEANUP_INTERVAL);
+  
+  logger.info('工具日志清理任务已启动');
+}
+
+/**
+ * 强制刷新所有日志队列
+ */
+export async function flushAllLogQueues() {
+  const toolNames = Array.from(logQueues.keys());
+  for (const toolName of toolNames) {
+    await flushLogQueue(toolName);
+  }
+}
+

package/packages/server/toolm/tool-manager.handler.js

@@ -0,0 +1,65 @@
+/**
+ * 统一工具管理处理器
+ * 
+ * 职责：
+ * 1. 实现 mcp__promptmanager__toolm 工具的处理逻辑
+ * 2. 路由到不同的模式处理器
+ * 3. 统一错误处理
+ */
+
+import { logger } from '../utils/logger.js';
+import { toolLoaderService } from './tool-loader.service.js';
+import { parseToolYaml } from './tool-yaml-parser.service.js';
+import { 
+  handleManualMode, 
+  handleExecuteMode, 
+  handleConfigureMode, 
+  handleLogMode 
+} from './tool-mode-handlers.service.js';
+
+/**
+ * 处理 toolm 工具调用
+ * @param {object} args - 参数对象，包含 yaml 字段
+ * @returns {object} MCP 格式的返回结果
+ */
+export async function handleToolM(args) {
+  const { yaml: yamlInput } = args;
+  
+  try {
+    // 初始化工具加载器（如果尚未初始化）
+    if (!toolLoaderService.initialized) {
+      await toolLoaderService.initialize();
+    }
+
+    // 解析 YAML 配置
+    const { toolName, mode, parameters } = parseToolYaml(yamlInput);
+    
+    // 检查工具是否存在
+    if (!toolLoaderService.hasTool(toolName)) {
+      const availableTools = toolLoaderService.getAllTools().map(t => t.name).join(', ');
+      throw new Error(`工具 '${toolName}' 不存在\n可用工具: ${availableTools}`);
+    }
+
+    // 根据模式路由到对应的处理器
+    switch (mode) {
+      case 'manual':
+        return handleManualMode(toolName);
+      
+      case 'execute':
+        return await handleExecuteMode(toolName, parameters);
+      
+      case 'configure':
+        return await handleConfigureMode(toolName, parameters);
+      
+      case 'log':
+        return await handleLogMode(toolName, parameters);
+      
+      default:
+        throw new Error(`不支持的模式: ${mode}\n支持的模式: manual, execute, configure, log`);
+    }
+
+  } catch (error) {
+    // 错误已经在 parseToolYaml 中处理，直接抛出
+    throw error;
+  }
+}

package/packages/server/toolm/tool-manual-generator.service.js

@@ -0,0 +1,389 @@
+/**
+ * 工具手册生成服务
+ * 
+ * 职责：
+ * 1. 生成格式化的工具手册（manual模式）
+ * 2. 生成错误帮助信息（execute模式出错时）
+ * 3. 统一工具文档的格式和样式
+ */
+
+/**
+ * 生成工具手册（完整版）
+ * @param {string} toolName - 工具名称
+ * @param {object} tool - 工具对象（包含 metadata, schema, businessErrors）
+ * @returns {string} Markdown格式的手册
+ */
+export function generateManual(toolName, tool) {
+  const { metadata, schema, businessErrors } = tool;
+
+  let manual = '';
+  
+  // 标题和基本信息
+  manual += `# 📚 ${metadata.name || toolName}\n\n`;
+  
+  if (metadata.description) {
+    manual += `## 📋 工具描述\n\n${metadata.description}\n\n`;
+  }
+
+  // 基本信息卡片
+  manual += `## ℹ️ 基本信息\n\n`;
+  if (metadata.version) {
+    manual += `- **版本**: ${metadata.version}\n`;
+  }
+  if (metadata.author) {
+    manual += `- **作者**: ${metadata.author}\n`;
+  }
+  if (metadata.tags && metadata.tags.length > 0) {
+    manual += `- **标签**: ${metadata.tags.map(t => `\`${t}\``).join(', ')}\n`;
+  }
+  manual += `\n`;
+
+  // 使用场景
+  if (metadata.scenarios && metadata.scenarios.length > 0) {
+    manual += `## 🎯 使用场景\n\n`;
+    metadata.scenarios.forEach(scenario => {
+      manual += `- ✅ ${scenario}\n`;
+    });
+    manual += '\n';
+  }
+
+  // 参数说明
+  if (schema.parameters) {
+    manual += `## 📝 参数说明\n\n`;
+    
+    const props = schema.parameters.properties || {};
+    const required = schema.parameters.required || [];
+    
+    // 必需参数
+    if (required.length > 0) {
+      manual += `### ✅ 必需参数\n\n`;
+      for (const key of required) {
+        const prop = props[key];
+        if (prop) {
+          manual += `- **\`${key}\`** (${prop.type || '未指定类型'})`;
+          if (prop.enum) {
+            manual += ` - 可选值: ${prop.enum.map(v => `\`${v}\``).join(', ')}`;
+          }
+          manual += `\n`;
+          if (prop.description) {
+            manual += `  > ${prop.description}\n`;
+          }
+          if (prop.default !== undefined) {
+            manual += `  > 💡 默认值: \`${prop.default}\`\n`;
+          }
+          manual += `\n`;
+        }
+      }
+    }
+    
+    // 可选参数
+    const optional = Object.keys(props).filter(k => !required.includes(k));
+    if (optional.length > 0) {
+      manual += `### 📌 可选参数\n\n`;
+      for (const key of optional) {
+        const prop = props[key];
+        if (prop) {
+          manual += `- **\`${key}\`** (${prop.type || '未指定类型'})`;
+          if (prop.default !== undefined) {
+            manual += ` - 默认值: \`${prop.default}\``;
+          }
+          if (prop.enum) {
+            manual += ` - 可选值: ${prop.enum.map(v => `\`${v}\``).join(', ')}`;
+          }
+          manual += `\n`;
+          if (prop.description) {
+            manual += `  > ${prop.description}\n`;
+          }
+          manual += `\n`;
+        }
+      }
+    }
+  }
+
+  // 环境变量
+  if (schema.environment && schema.environment.properties) {
+    manual += `## ⚙️ 环境变量配置\n\n`;
+    const envProps = schema.environment.properties;
+    for (const [key, value] of Object.entries(envProps)) {
+      manual += `### \`${key}\`\n\n`;
+      if (value.description) {
+        manual += `**说明**: ${value.description}\n\n`;
+      }
+      if (value.default) {
+        manual += `**默认值**: \`${value.default}\`\n\n`;
+      }
+    }
+    
+    manual += `> 💡 使用 \`mode: configure\` 可以配置这些环境变量\n\n`;
+  }
+
+  // 错误处理
+  if (businessErrors && businessErrors.length > 0) {
+    manual += `## ⚠️ 常见错误处理\n\n`;
+    businessErrors.forEach(error => {
+      manual += `### ${error.code}\n\n`;
+      manual += `- **描述**: ${error.description}\n`;
+      manual += `- **解决方案**: ${error.solution}\n`;
+      manual += `- **可重试**: ${error.retryable ? '✅ 是' : '❌ 否'}\n\n`;
+    });
+  }
+
+  // 限制说明
+  if (metadata.limitations && metadata.limitations.length > 0) {
+    manual += `## ⚠️ 限制说明\n\n`;
+    metadata.limitations.forEach(limitation => {
+      manual += `- ⚠️ ${limitation}\n`;
+    });
+    manual += '\n';
+  }
+
+  // 使用示例
+  manual += `## 💡 使用示例\n\n`;
+  manual += `### 基础使用\n\n`;
+  manual += `\`\`\`yaml\n`;
+  manual += `tool: tool://${toolName}\n`;
+  manual += `mode: execute\n`;
+  manual += `parameters:\n`;
+  
+  // 生成示例参数
+  if (schema.parameters && schema.parameters.properties) {
+    const props = schema.parameters.properties;
+    const required = schema.parameters.required || [];
+    
+    // 添加必需参数示例
+    for (const key of required.slice(0, 3)) { // 最多显示3个必需参数
+      const prop = props[key];
+      if (prop) {
+        const exampleValue = generateExampleValue(key, prop);
+        manual += `  ${key}: ${exampleValue}  # ${prop.description || ''}\n`;
+      }
+    }
+    
+    // 添加可选参数示例（最多2个）
+    const optional = Object.keys(props).filter(k => !required.includes(k));
+    for (const key of optional.slice(0, 2)) {
+      const prop = props[key];
+      if (prop && prop.default !== undefined) {
+        const defaultValue = typeof prop.default === 'string' ? `"${prop.default}"` : prop.default;
+        manual += `  # ${key}: ${defaultValue}  # ${prop.description || ''} (可选)\n`;
+      }
+    }
+  }
+  
+  manual += `\`\`\`\n\n`;
+
+  return manual;
+}
+
+/**
+ * 生成错误帮助信息
+ * @param {string} toolName - 工具名称
+ * @param {Error} error - 错误对象
+ * @param {object} tool - 工具对象（包含 metadata, schema）
+ * @param {object} parameters - 当前参数
+ * @param {object} businessError - 业务错误信息（可选）
+ * @returns {string} Markdown格式的帮助信息
+ */
+export function generateHelpInfo(toolName, error, tool, parameters = {}, businessError = null) {
+  const { metadata, schema } = tool;
+  
+  let helpText = '';
+  
+  // 错误提示
+  helpText += `# ⚠️ 工具执行错误\n\n`;
+  helpText += `**工具**: ${metadata.name || toolName}\n\n`;
+  helpText += `**错误信息**: \`${error.message}\`\n\n`;
+  
+  if (businessError) {
+    helpText += `**错误类型**: ${businessError.description}\n\n`;
+    helpText += `**解决方案**: ${businessError.solution}\n\n`;
+  }
+  
+  helpText += `---\n\n`;
+  
+  // 工具基本信息
+  helpText += `## 📋 工具信息\n\n`;
+  if (metadata.description) {
+    helpText += `**描述**: ${metadata.description}\n\n`;
+  }
+  
+  // 当前参数
+  if (parameters && Object.keys(parameters).length > 0) {
+    helpText += `## 📥 当前参数\n\n`;
+    helpText += `\`\`\`json\n${JSON.stringify(parameters, null, 2)}\n\`\`\`\n\n`;
+  }
+  
+  // 参数说明
+  if (schema.parameters) {
+    helpText += `## 📝 参数说明\n\n`;
+    
+    const props = schema.parameters.properties || {};
+    const required = schema.parameters.required || [];
+    
+    // 必需参数
+    if (required.length > 0) {
+      helpText += `### ✅ 必需参数\n\n`;
+      for (const key of required) {
+        const prop = props[key];
+        if (prop) {
+          helpText += `- **\`${key}\`** (${prop.type || '未指定类型'})`;
+          if (prop.enum) {
+            helpText += ` - 可选值: ${prop.enum.map(v => `\`${v}\``).join(', ')}`;
+          }
+          helpText += `\n`;
+          if (prop.description) {
+            helpText += `  > ${prop.description}\n`;
+          }
+        }
+      }
+      helpText += `\n`;
+    }
+    
+    // 可选参数
+    const optional = Object.keys(props).filter(k => !required.includes(k));
+    if (optional.length > 0) {
+      helpText += `### 📌 可选参数\n\n`;
+      for (const key of optional) {
+        const prop = props[key];
+        if (prop) {
+          helpText += `- **\`${key}\`** (${prop.type || '未指定类型'})`;
+          if (prop.default !== undefined) {
+            helpText += ` - 默认值: \`${prop.default}\``;
+          }
+          if (prop.enum) {
+            helpText += ` - 可选值: ${prop.enum.map(v => `\`${v}\``).join(', ')}`;
+          }
+          helpText += `\n`;
+          if (prop.description) {
+            helpText += `  > ${prop.description}\n`;
+          }
+        }
+      }
+      helpText += `\n`;
+    }
+  }
+  
+  // 使用示例
+  helpText += `## 💡 使用示例\n\n`;
+  
+  // 根据错误类型生成不同的示例
+  if (error.message.includes('不支持的方法')) {
+    // 方法错误，显示所有支持的方法
+    if (schema.parameters && schema.parameters.properties && schema.parameters.properties.method) {
+      const methodEnum = schema.parameters.properties.method.enum || [];
+      if (methodEnum.length > 0) {
+        helpText += `### ❌ 错误：不支持的方法\n\n`;
+        helpText += `**支持的方法列表**：\n\n`;
+        methodEnum.forEach(method => {
+          helpText += `- \`${method}\`\n`;
+        });
+        helpText += `\n`;
+      }
+    }
+  }
+  
+  if (error.message.includes('缺少必需参数') || error.message.includes('缺少参数')) {
+    // 提取缺失的参数名
+    const missingMatch = error.message.match(/缺少.*参数[：:]\s*([^\n]+)/i);
+    if (missingMatch) {
+      const missingParams = missingMatch[1].split(',').map(p => p.trim());
+      helpText += `### ❌ 错误：缺少必需参数\n\n`;
+      helpText += `**缺失的参数**：${missingParams.map(p => `\`${p}\``).join(', ')}\n\n`;
+      helpText += `**这些参数是必需的，必须提供**\n\n`;
+    }
+  }
+  
+  // 生成正确的使用示例
+  helpText += `### ✅ 正确使用方式\n\n`;
+  helpText += `\`\`\`yaml\n`;
+  helpText += `tool: tool://${toolName}\n`;
+  helpText += `mode: execute\n`;
+  helpText += `parameters:\n`;
+  
+  // 根据schema生成示例参数
+  if (schema.parameters && schema.parameters.properties) {
+    const props = schema.parameters.properties;
+    const required = schema.parameters.required || [];
+    
+    // 先添加必需参数
+    for (const key of required) {
+      const prop = props[key];
+      if (prop) {
+        const exampleValue = generateExampleValue(key, prop);
+        helpText += `  ${key}: ${exampleValue}  # ${prop.description || ''}\n`;
+      }
+    }
+    
+    // 添加一些常用的可选参数（最多3个）
+    const optional = Object.keys(props).filter(k => !required.includes(k));
+    let shownOptional = 0;
+    for (const key of optional) {
+      if (shownOptional >= 3) break;
+      const prop = props[key];
+      if (prop) {
+        if (prop.default !== undefined) {
+          const defaultValue = typeof prop.default === 'string' ? `"${prop.default}"` : prop.default;
+          helpText += `  # ${key}: ${defaultValue}  # ${prop.description || ''} (可选，默认值: ${prop.default})\n`;
+          shownOptional++;
+        } else if (prop.enum && prop.enum.length > 0) {
+          helpText += `  # ${key}: ${prop.enum[0]}  # ${prop.description || ''} (可选)\n`;
+          shownOptional++;
+        }
+      }
+    }
+  }
+  
+  helpText += `\`\`\`\n\n`;
+  
+  // 查看完整手册的提示
+  helpText += `---\n\n`;
+  helpText += `## 🔍 需要更多帮助？\n\n`;
+  helpText += `使用以下命令查看完整的工具手册：\n\n`;
+  helpText += `\`\`\`yaml\n`;
+  helpText += `tool: tool://${toolName}\n`;
+  helpText += `mode: manual\n`;
+  helpText += `\`\`\`\n\n`;
+  
+  return helpText;
+}
+
+/**
+ * 生成参数示例值
+ * @param {string} key - 参数名
+ * @param {object} prop - 参数属性
+ * @returns {string} 示例值字符串
+ */
+function generateExampleValue(key, prop) {
+  if (prop.enum && prop.enum.length > 0) {
+    return prop.enum[0];
+  }
+  
+  if (prop.type === 'string') {
+    // 根据参数名提供更合适的示例值
+    if (key.includes('path') || key.includes('url') || key.includes('file')) {
+      return key.includes('url') ? '"https://example.com/file.txt"' : '"~/.prompt-manager/file.txt"';
+    } else if (key.includes('method')) {
+      return prop.enum ? prop.enum[0] : '"method_name"';
+    }
+    return '"示例值"';
+  }
+  
+  if (prop.type === 'number') {
+    return '0';
+  }
+  
+  if (prop.type === 'boolean') {
+    return 'true';
+  }
+  
+  if (prop.type === 'array') {
+    return '[]';
+  }
+  
+  if (prop.type === 'object') {
+    return '{}';
+  }
+  
+  return '# 请填写';
+}
+