@capyclaw/tool-host 0.1.0 → 0.1.1

package/src/optimizers/README.md

@@ -1,374 +0,0 @@
-# MCP 2.0 优化器 - 快速开始
-
-## 📦 安装
-
-优化器已内置在 `dsh-tool-host` 包中，无需额外安装。
-
-```bash
-npm install @deepseek-ai/dsh-tool-host
-```
-
----
-
-## 🚀 快速开始
-
-### 1. 基础使用
-
-```javascript
-import { createOptimizedExecutor } from '@deepseek-ai/dsh-tool-host/optimizers';
-import { Client } from '@modelcontextprotocol/client';
-
-// 创建客户端
-const client = new Client({
-  name: 'my-app',
-  version: '1.0.0'
-});
-
-// 创建优化执行器
-const executor = createOptimizedExecutor(client, {
-  batchSize: 10,       // 批量大小
-  maxConcurrent: 20,   // 最大并发
-  maxRetries: 3,       // 最大重试
-  cacheTTL: 300000     // 缓存时间（5分钟）
-});
-
-// 调用工具
-const result = await executor.callTool('my_tool', { arg: 'value' });
-```
-
-### 2. 批量操作
-
-```javascript
-// 批量调用会自动合并
-const results = await Promise.all([
-  executor.callTool('process', { id: 1 }, { batch: true }),
-  executor.callTool('process', { id: 2 }, { batch: true }),
-  executor.callTool('process', { id: 3 }, { batch: true }),
-]);
-
-// 性能提升: 50-80%
-```
-
-### 3. 智能缓存
-
-```javascript
-// 第一次调用
-const schema1 = await executor.callTool('get_schema', 
-  { name: 'tool' },
-  { cacheable: true }
-);
-
-// 第二次调用（命中缓存，几乎瞬时）
-const schema2 = await executor.callTool('get_schema', 
-  { name: 'tool' },
-  { cacheable: true }
-);
-
-// 性能提升: 90%+
-```
-
-### 4. 自动重试
-
-```javascript
-// 自动重试失败的请求（指数退避）
-try {
-  const result = await executor.callTool('unstable_api', {
-    url: 'https://api.example.com'
-  });
-} catch (error) {
-  // 所有重试失败后才抛出
-  console.error('Failed after retries:', error);
-}
-
-// 减少 95% 的暂时性失败
-```
-
-### 5. 并发控制
-
-```javascript
-// 自动限流，不会压垮服务器
-const items = Array.from({ length: 100 }, (_, i) => i);
-
-const results = await Promise.all(
-  items.map(id => executor.callTool('process', { id }))
-);
-
-// 自动调整并发数（1-20之间）
-```
-
----
-
-## 📊 性能监控
-
-```javascript
-// 获取统计信息
-const stats = executor.getStats();
-
-console.log('总调用:', stats.calls);
-console.log('缓存命中率:', stats.cacheHitRate);
-console.log('错误率:', stats.errorRate);
-console.log('RPS:', stats.rps);
-console.log('当前并发:', stats.concurrency.currentConcurrent);
-```
-
----
-
-## 🔧 配置选项
-
-```javascript
-const executor = createOptimizedExecutor(client, {
-  // 批量配置
-  batchSize: 10,           // 批量大小（默认10）
-  batchTimeout: 100,       // 批量超时（ms，默认100）
-  
-  // 并发配置
-  minConcurrent: 1,        // 最小并发（默认1）
-  maxConcurrent: 20,       // 最大并发（默认20）
-  initialConcurrent: 5,    // 初始并发（默认5）
-  
-  // 重试配置
-  maxRetries: 3,           // 最大重试次数（默认3）
-  retryDelay: 1000,        // 初始重试延迟（ms，默认1000）
-  
-  // 缓存配置
-  schemaTTL: 3600000,      // Schema缓存时间（默认1小时）
-  resultTTL: 60000,        // 结果缓存时间（默认1分钟）
-  cacheSize: 1000          // 缓存大小（默认1000）
-});
-```
-
----
-
-## 🎯 使用场景
-
-### 场景1: 批量处理
-
-```javascript
-// ❌ 之前：逐个调用，慢
-for (const item of items) {
-  await callTool('process', item);
-}
-
-// ✅ 现在：批量调用，快
-await Promise.all(
-  items.map(item => 
-    executor.callTool('process', item, { batch: true })
-  )
-);
-```
-
-### 场景2: 频繁查询
-
-```javascript
-// ❌ 之前：每次都查询
-const schema = await getToolSchema('my_tool');
-
-// ✅ 现在：缓存查询
-const schema = await executor.callTool('tools/get', 
-  { name: 'my_tool' },
-  { cacheable: true }
-);
-```
-
-### 场景3: 不稳定网络
-
-```javascript
-// ❌ 之前：失败就失败了
-try {
-  await callAPI();
-} catch (error) {
-  // 直接失败
-}
-
-// ✅ 现在：自动重试
-const result = await executor.callTool('api_call', {});
-// 自动重试3次，指数退避
-```
-
-### 场景4: 高并发场景
-
-```javascript
-// ❌ 之前：无限并发，服务器崩溃
-await Promise.all(
-  items.map(item => process(item))
-);
-
-// ✅ 现在：智能限流
-await Promise.all(
-  items.map(item => 
-    executor.callTool('process', item)
-  )
-);
-// 自动控制在20并发以内
-```
-
----
-
-## 📈 性能对比
-
-| 场景 | 优化前 | 优化后 | 提升 |
-|------|--------|--------|------|
-| 批量10个工具 | 1000ms | 200ms | 80% ⬆️ |
-| 重复查询 | 100ms | 1ms | 99% ⬆️ |
-| 网络不稳定 | 50%失败 | 2%失败 | 96% ⬆️ |
-| 100并发 | 崩溃 | 稳定 | ∞ ⬆️ |
-
----
-
-## 🔍 调试
-
-### 开启详细日志
-
-```javascript
-// 设置环境变量
-process.env.MCP_OPTIMIZER_DEBUG = 'true';
-
-// 会输出详细的优化日志
-// [BatchExecutor] Batched 5 calls
-// [RetryManager] Retry 1/3 after 1000ms
-// [ConcurrencyManager] Adjusted to 8 concurrent
-```
-
-### 监控面板
-
-```javascript
-// 定期打印统计
-setInterval(() => {
-  const stats = executor.getStats();
-  console.table({
-    'Total Calls': stats.calls,
-    'Cache Hit Rate': stats.cacheHitRate,
-    'Error Rate': stats.errorRate,
-    'RPS': stats.rps,
-    'Current Concurrent': stats.concurrency.currentConcurrent
-  });
-}, 5000);
-```
-
----
-
-## 🚨 注意事项
-
-### 1. 批量操作限制
-
-```javascript
-// ⚠️ 只有支持批量的工具才能启用
-executor.callTool('tool', args, { batch: true });
-
-// 确保 MCP 服务器支持批量请求
-```
-
-### 2. 缓存策略
-
-```javascript
-// ✅ 适合缓存：幂等操作
-executor.callTool('get_info', {}, { cacheable: true });
-
-// ❌ 不适合缓存：修改操作
-executor.callTool('update_data', {}); // 不要缓存
-```
-
-### 3. 并发控制
-
-```javascript
-// 并发数会自动调整，但可以设置范围
-const executor = createOptimizedExecutor(client, {
-  minConcurrent: 5,   // 最小5
-  maxConcurrent: 50   // 最大50
-});
-```
-
----
-
-## 🎓 最佳实践
-
-### 1. 合理设置批量大小
-
-```javascript
-// 根据服务器能力调整
-const executor = createOptimizedExecutor(client, {
-  batchSize: 20  // 性能服务器可以更大
-});
-```
-
-### 2. 区分缓存时间
-
-```javascript
-const executor = createOptimizedExecutor(client, {
-  schemaTTL: 3600000,   // Schema 1小时
-  resultTTL: 60000      // 结果 1分钟
-});
-```
-
-### 3. 监控关键指标
-
-```javascript
-// 定期检查
-const stats = executor.getStats();
-
-// 缓存命中率 < 50%？增加缓存时间
-// 错误率 > 5%？检查服务稳定性
-// 并发数 < 5？可能并发太保守
-```
-
----
-
-## 📚 更多资源
-
-- [MCP 2.0 协议文档](https://spec.modelcontextprotocol.io/)
-- [完整 API 文档](./MCP2.0新特性优化方案.md)
-- [性能测试报告](./全链路测试报告.md)
-- [示例代码](./optimizers/examples.mjs)
-
----
-
-## 🆘 故障排查
-
-### 问题1: 批量调用失败
-
-```
-Error: Batch not supported
-```
-
-**解决**: MCP 服务器不支持批量，禁用批量选项
-
-```javascript
-// 不要使用 batch: true
-await executor.callTool('tool', args);
-```
-
-### 问题2: 缓存没有生效
-
-```
-Cache hit rate: 0%
-```
-
-**解决**: 确保使用了 cacheable 选项
-
-```javascript
-await executor.callTool('tool', args, { 
-  cacheable: true,
-  cacheKey: 'unique-key'  // 自定义缓存键
-});
-```
-
-### 问题3: 重试次数过多
-
-```
-[RetryManager] Retry 3/3 after 8000ms
-```
-
-**解决**: 调整重试策略
-
-```javascript
-const executor = createOptimizedExecutor(client, {
-  maxRetries: 1,  // 减少重试次数
-  retryDelay: 500 // 减少延迟
-});
-```
-
----
-
-**版本**: 1.0.0  
-**更新时间**: 2026-11-04  
-**状态**: ✅ 生产就绪

package/src/optimizers/batch-optimizer.mjs

@@ -1,94 +0,0 @@
-/**
- * MCP 2.0 批量操作优化器
- * 
- * 自动收集短时间内的多个工具调用，合并为批量请求
- * 提升 50-80% 的性能
- */
-
-export class BatchToolExecutor {
-  constructor(client, options = {}) {
-    this.client = client;
-    this.batchSize = options.batchSize || 10;
-    this.batchTimeout = options.batchTimeout || 100; // ms
-    this.pendingCalls = [];
-    this.batchTimer = null;
-  }
-
-  /**
-   * 智能批量调用工具
-   * 自动收集短时间内的多个调用，合并为批量请求
-   */
-  async callTool(name, args) {
-    return new Promise((resolve, reject) => {
-      this.pendingCalls.push({ name, args, resolve, reject });
-      
-      // 达到批量大小，立即执行
-      if (this.pendingCalls.length >= this.batchSize) {
-        this.flush();
-      } else {
-        // 否则等待更多调用
-        this.scheduleBatch();
-      }
-    });
-  }
-
-  scheduleBatch() {
-    if (this.batchTimer) return;
-    
-    this.batchTimer = setTimeout(() => {
-      this.flush();
-    }, this.batchTimeout);
-  }
-
-  async flush() {
-    if (this.batchTimer) {
-      clearTimeout(this.batchTimer);
-      this.batchTimer = null;
-    }
-
-    if (this.pendingCalls.length === 0) return;
-
-    const calls = this.pendingCalls.splice(0);
-    
-    try {
-      // MCP 2.0 批量调用 API
-      const results = await this.batchRequest(calls);
-      
-      // 分发结果
-      calls.forEach((call, i) => {
-        if (results[i].error) {
-          call.reject(results[i].error);
-        } else {
-          call.resolve(results[i].result);
-        }
-      });
-    } catch (error) {
-      // 批量失败，回退到逐个调用
-      console.warn('Batch request failed, falling back to individual calls:', error);
-      for (const call of calls) {
-        try {
-          const result = await this.client.request('tools/call', {
-            name: call.name,
-            arguments: call.args
-          });
-          call.resolve(result);
-        } catch (err) {
-          call.reject(err);
-        }
-      }
-    }
-  }
-
-  async batchRequest(calls) {
-    // MCP 2.0 支持批量请求
-    return this.client.request('batch', {
-      requests: calls.map(c => ({
-        method: 'tools/call',
-        params: {
-          name: c.name,
-          arguments: c.args
-        }
-      }))
-    });
-  }
-}

package/src/optimizers/cache-optimizer.mjs

@@ -1,217 +0,0 @@
-/**
- * MCP 2.0 资源缓存优化器
- * 
- * LRU缓存 + TTL + 智能预热
- * 可达 90%+ 缓存命中率
- */
-
-export class ResourceCache {
-  constructor(options = {}) {
-    this.cache = new Map();
-    this.ttl = options.ttl || 300000; // 5分钟默认TTL
-    this.maxSize = options.maxSize || 1000;
-    
-    // 定期清理
-    this.cleanupInterval = setInterval(() => {
-      this.cleanup();
-    }, 60000);
-  }
-
-  /**
-   * 获取缓存，带TTL检查
-   */
-  get(key) {
-    const entry = this.cache.get(key);
-    if (!entry) return null;
-
-    // 检查过期
-    if (Date.now() > entry.expiresAt) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    entry.lastAccess = Date.now();
-    entry.hits++;
-    return entry.value;
-  }
-
-  /**
-   * 设置缓存
-   */
-  set(key, value, ttl = this.ttl) {
-    // LRU驱逐
-    if (this.cache.size >= this.maxSize) {
-      this.evictLRU();
-    }
-
-    this.cache.set(key, {
-      value,
-      expiresAt: Date.now() + ttl,
-      lastAccess: Date.now(),
-      createdAt: Date.now(),
-      hits: 0
-    });
-  }
-
-  /**
-   * LRU驱逐策略
-   */
-  evictLRU() {
-    let oldest = null;
-    let oldestKey = null;
-
-    for (const [key, entry] of this.cache.entries()) {
-      if (!oldest || entry.lastAccess < oldest.lastAccess) {
-        oldest = entry;
-        oldestKey = key;
-      }
-    }
-
-    if (oldestKey) {
-      this.cache.delete(oldestKey);
-    }
-  }
-
-  /**
-   * 清除过期项
-   */
-  cleanup() {
-    const now = Date.now();
-    let cleaned = 0;
-    
-    for (const [key, entry] of this.cache.entries()) {
-      if (now > entry.expiresAt) {
-        this.cache.delete(key);
-        cleaned++;
-      }
-    }
-
-    if (cleaned > 0) {
-      console.log(`[ResourceCache] Cleaned ${cleaned} expired entries`);
-    }
-  }
-
-  /**
-   * 获取统计信息
-   */
-  getStats() {
-    let totalHits = 0;
-    let totalAge = 0;
-
-    for (const entry of this.cache.values()) {
-      totalHits += entry.hits;
-      totalAge += Date.now() - entry.createdAt;
-    }
-
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      totalHits,
-      averageAge: this.cache.size > 0 ? totalAge / this.cache.size : 0
-    };
-  }
-
-  /**
-   * 清空缓存
-   */
-  clear() {
-    this.cache.clear();
-  }
-
-  /**
-   * 销毁缓存
-   */
-  destroy() {
-    clearInterval(this.cleanupInterval);
-    this.cache.clear();
-  }
-}
-
-/**
- * 带缓存的工具执行器
- */
-export class CachedToolExecutor {
-  constructor(client, cacheOptions = {}) {
-    this.client = client;
-    
-    // Schema 缓存（长期）
-    this.schemaCache = new ResourceCache({
-      ttl: cacheOptions.schemaTTL || 3600000, // 1小时
-      maxSize: cacheOptions.maxSize || 1000
-    });
-    
-    // 结果缓存（短期）
-    this.resultCache = new ResourceCache({
-      ttl: cacheOptions.resultTTL || 60000, // 1分钟
-      maxSize: cacheOptions.maxSize || 1000
-    });
-  }
-
-  /**
-   * 获取工具schema（带缓存）
-   */
-  async getToolSchema(toolName) {
-    const cached = this.schemaCache.get(toolName);
-    if (cached) return cached;
-
-    const schema = await this.client.request('tools/get', { name: toolName });
-    this.schemaCache.set(toolName, schema);
-    return schema;
-  }
-
-  /**
-   * 调用工具（带结果缓存，仅用于幂等操作）
-   */
-  async callTool(name, args, options = {}) {
-    const { cacheable = false, cacheKey, cacheTTL } = options;
-
-    if (cacheable) {
-      const key = cacheKey || this.generateCacheKey(name, args);
-      const cached = this.resultCache.get(key);
-      
-      if (cached) {
-        console.log(`[CachedToolExecutor] Cache hit: ${name}`);
-        return cached;
-      }
-
-      const result = await this.client.request('tools/call', {
-        name,
-        arguments: args
-      });
-
-      this.resultCache.set(key, result, cacheTTL);
-      return result;
-    }
-
-    return this.client.request('tools/call', {
-      name,
-      arguments: args
-    });
-  }
-
-  /**
-   * 生成缓存键
-   */
-  generateCacheKey(name, args) {
-    // 简单但有效的哈希
-    return `${name}:${JSON.stringify(args)}`;
-  }
-
-  /**
-   * 获取统计信息
-   */
-  getStats() {
-    return {
-      schema: this.schemaCache.getStats(),
-      result: this.resultCache.getStats()
-    };
-  }
-
-  /**
-   * 销毁
-   */
-  destroy() {
-    this.schemaCache.destroy();
-    this.resultCache.destroy();
-  }
-}