PromptX/resource/role/luban/knowledge/tool-best-practices.knowledge.md

工具设计最佳实践

🎯 工具设计哲学

极简主义原则

• 单一职责：每个工具只解决一个核心问题
• 接口优雅：参数设计直观易懂，返回值结构清晰
• 依赖最小：只引入必要的依赖，避免过度膨胀
• 错误友好：提供清晰的错误信息和处理建议

用户体验至上

• 即装即用：工具无需复杂配置即可使用
• 文档自描述：通过Schema和Metadata实现自我说明
• 性能优先：执行效率和响应速度优化
• 跨平台兼容：确保在不同环境下稳定运行

🏗️ 架构设计原则

ToolInterface标准化实现

// 完美的工具接口示例
module.exports = {
  // 🔧 依赖管理：明确、最小、版本锁定
  getDependencies() {
    return [
      'lodash@^4.17.21',    // 工具函数库
      'validator@^13.11.0'  // 数据验证
    ];
  },
  
  // 📊 元信息：完整、准确、描述性
  getMetadata() {
    return {
      name: 'text-processor',
      description: '智能文本处理工具，支持清理、格式化、验证等功能',
      version: '1.2.0',
      category: 'text-processing',
      author: '鲁班',
      tags: ['text', 'processing', 'utility']
    };
  },
  
  // 📝 Schema定义：结构化、类型安全、示例丰富
  getSchema() {
    return {
      type: 'object',
      properties: {
        text: {
          type: 'string',
          description: '需要处理的文本内容',
          example: 'Hello World!'
        },
        operations: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['clean', 'format', 'validate']
          },
          description: '要执行的操作列表',
          default: ['clean']
        },
        options: {
          type: 'object',
          properties: {
            encoding: { type: 'string', default: 'utf-8' },
            strict: { type: 'boolean', default: false }
          }
        }
      },
      required: ['text']
    };
  },
  
  // ✅ 参数验证：严格、友好、早期失败
  validate(params) {
    const errors = [];
    
    if (!params.text || typeof params.text !== 'string') {
      errors.push('text参数必须是非空字符串');
    }
    
    if (params.text && params.text.length > 50000) {
      errors.push('text长度不能超过50000字符');
    }
    
    return {
      valid: errors.length === 0,
      errors
    };
  },
  
  // 🚀 核心执行：健壮、高效、可观测
  async execute(params) {
    const startTime = Date.now();
    
    try {
      // 核心处理逻辑
      const result = await this.processText(params);
      
      return {
        success: true,
        data: result,
        metadata: {
          executionTime: Date.now() - startTime,
          timestamp: new Date().toISOString()
        }
      };
    } catch (error) {
      return {
        success: false,
        error: {
          message: error.message,
          code: error.code || 'UNKNOWN_ERROR'
        },
        metadata: {
          executionTime: Date.now() - startTime,
          timestamp: new Date().toISOString()
        }
      };
    }
  }
};

🛡️ 安全与性能最佳实践

输入安全防护

// 输入验证模式
class InputValidator {
  static validateText(text, maxLength = 10000) {
    if (typeof text !== 'string') {
      throw new Error('输入必须是字符串类型');
    }
    
    if (text.length > maxLength) {
      throw new Error(`文本长度超过限制: ${maxLength}`);
    }
    
    // XSS防护
    if (/<script|javascript:|on\w+=/i.test(text)) {
      throw new Error('检测到潜在的恶意脚本');
    }
    
    return true;
  }
  
  static sanitizeFilename(filename) {
    return filename.replace(/[^a-zA-Z0-9._-]/g, '');
  }
}

性能优化模式

// 缓存机制
const cache = new Map();
const CACHE_TTL = 300000; // 5分钟

function withCache(fn, cacheKey) {
  const cached = cache.get(cacheKey);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const result = fn();
  cache.set(cacheKey, {
    data: result,
    timestamp: Date.now()
  });
  
  return result;
}

// 资源控制
function withResourceLimit(fn, timeout = 30000) {
  return Promise.race([
    fn(),
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('执行超时')), timeout)
    )
  ]);
}

📦 依赖管理策略

精选依赖原则

// 工具库选择矩阵
const DEPENDENCY_MATRIX = {
  // 基础工具函数
  utilities: {
    recommended: 'lodash@^4.17.21',
    alternatives: ['ramda@^0.29.0', 'underscore@^1.13.0'],
    criteria: '成熟度、包大小、功能覆盖'
  },
  
  // HTTP请求
  http: {
    recommended: 'axios@^1.6.0',
    alternatives: ['node-fetch@^3.3.0', 'got@^13.0.0'],
    criteria: '易用性、功能丰富度、兼容性'
  },
  
  // 数据验证
  validation: {
    recommended: 'validator@^13.11.0',
    alternatives: ['joi@^17.11.0', 'yup@^1.3.0'],
    criteria: '验证规则丰富度、性能、学习成本'
  },
  
  // 文件操作
  filesystem: {
    recommended: 'fs-extra@^11.1.0',
    alternatives: ['graceful-fs@^4.2.11'],
    criteria: '功能完整性、错误处理、跨平台'
  }
};

// 依赖版本策略
getDependencies() {
  return [
    'lodash@^4.17.21',      // 主版本锁定，次版本兼容
    'axios@~1.6.0',        // 补丁版本兼容
    'validator@13.11.0'     // 精确版本锁定（关键依赖）
  ];
}

🧪 测试驱动开发

工具测试模式

// 标准测试模板
describe('TextProcessor Tool', () => {
  let tool;
  
  beforeEach(() => {
    tool = require('./text-processor.tool.js');
  });
  
  describe('接口合规性测试', () => {
    test('必须实现所有接口方法', () => {
      expect(typeof tool.getDependencies).toBe('function');
      expect(typeof tool.getMetadata).toBe('function');
      expect(typeof tool.getSchema).toBe('function');
      expect(typeof tool.validate).toBe('function');
      expect(typeof tool.execute).toBe('function');
    });
    
    test('getDependencies返回格式正确', () => {
      const deps = tool.getDependencies();
      expect(Array.isArray(deps)).toBe(true);
      deps.forEach(dep => {
        expect(typeof dep).toBe('string');
        expect(dep).toMatch(/^[a-zA-Z0-9-]+@[\^~]?\d+\.\d+\.\d+$/);
      });
    });
  });
  
  describe('功能测试', () => {
    test('正常输入处理', async () => {
      const result = await tool.execute({
        text: 'Hello World',
        operations: ['clean']
      });
      
      expect(result.success).toBe(true);
      expect(result.data).toBeDefined();
    });
    
    test('异常输入处理', async () => {
      const result = await tool.execute({
        text: null
      });
      
      expect(result.success).toBe(false);
      expect(result.error).toBeDefined();
    });
  });
});

📊 质量保证体系

代码质量检查

// ESLint配置示例
module.exports = {
  env: { node: true, es2021: true },
  extends: ['eslint:recommended'],
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error',
    'prefer-const': 'error',
    'no-var': 'error',
    'complexity': ['warn', 10],
    'max-lines-per-function': ['warn', 50]
  }
};

性能基准测试

// 性能测试模板
function benchmarkTool(tool, testData) {
  const iterations = 1000;
  const start = process.hrtime.bigint();
  
  for (let i = 0; i < iterations; i++) {
    tool.execute(testData);
  }
  
  const end = process.hrtime.bigint();
  const avgTime = Number(end - start) / iterations / 1000000; // ms
  
  return {
    iterations,
    averageTime: avgTime,
    totalTime: Number(end - start) / 1000000
  };
}

🌟 卓越工具特征

用户体验指标

• 启动时间 < 100ms
• 执行效率 < 1s（常规任务）
• 内存占用 < 50MB
• 错误恢复 100%优雅处理

代码质量指标

• 圈复杂度 < 10
• 测试覆盖率 > 90%
• 依赖漏洞 0个
• 文档完整度 100%

生态贡献指标

• 复用性 高（可被其他工具引用）
• 扩展性 强（支持插件机制）
• 社区认可 正面反馈 > 95%
• 维护活跃度 定期更新