botrun-horse 2.30.0 → 2.34.0

package/botrun-c/dev/mcp-token-calculator/calculate-mcp-tokens.ts

@@ -1,464 +0,0 @@
-/**
- * 計算所有 MCP Server 的 Tool Definitions 會佔用多少 tokens
- *
- * 這個腳本會：
- * 1. 收集所有 8 個 MCP Server 的 tool definitions
- * 2. 計算每個 tool definition 的 token 數量
- * 3. 輸出詳細的統計資訊
- */
-
-import { encoding_for_model } from 'tiktoken';
-
-// 使用 Claude 3.5 Sonnet 的 tokenizer (cl100k_base)
-const encoder = encoding_for_model('gpt-4');
-
-/**
- * 計算文字的 token 數量
- */
-function countTokens(text: string): number {
-  const tokens = encoder.encode(text);
-  return tokens.length;
-}
-
-/**
- * 所有 MCP Server Tool Definitions
- * 直接從源碼中提取的實際 tool definitions
- */
-const MCP_TOOLS = [
-  // 1. botrun-pdf-split
-  {
-    name: 'split_pdf',
-    server: 'botrun-pdf-split',
-    description: '拆解多頁 PDF 為單頁檔案。使用 qpdf 確保最佳檔案大小(無膨脹)。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        filePath: {
-          type: 'string',
-          description: 'PDF 檔案的完整路徑或相對路徑',
-        },
-        outputDir: {
-          type: 'string',
-          description: '輸出目錄路徑(可選，預設為 {檔名}_pages)',
-        },
-      },
-      required: ['filePath'],
-    },
-  },
-
-  // 2. botrun-pdf-to-text
-  {
-    name: 'pdf_to_text',
-    server: 'botrun-pdf-to-text',
-    description: '將分頁 PDF 目錄轉換為純文字檔案。使用 pdftotext 確保最佳文字擷取品質。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        inputDir: {
-          type: 'string',
-          description: 'PDF 檔案目錄的完整路徑(例如：分頁後的 PDF 目錄)',
-        },
-        outputDir: {
-          type: 'string',
-          description: '輸出目錄路徑(可選，預設為 {輸入目錄}_text)',
-        },
-      },
-      required: ['inputDir'],
-    },
-  },
-
-  // 3. botrun-secure-rg
-  {
-    name: 'secure_rg_search',
-    server: 'botrun-secure-rg',
-    description: '安全的 ripgrep 搜尋工具。支援完整 rg 參數，但嚴格限制在工作目錄內，防止路徑遍歷攻擊。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        pattern: {
-          type: 'string',
-          description: '搜尋的正則表達式模式',
-        },
-        path: {
-          type: 'string',
-          description: '搜尋路徑(相對於工作目錄，可選，預設為 .)',
-        },
-        args: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'ripgrep 額外參數(如 -i, -C 3, --type js 等)',
-        },
-      },
-      required: ['pattern'],
-    },
-  },
-
-  // 4. botrun-secure-read
-  {
-    name: 'read_files',
-    server: 'botrun-secure-read',
-    description:
-      '安全地讀取多個純文字檔案。支援 glob patterns(如 *.txt, src/**/*.js)。只能讀取工作目錄及其子目錄的檔案，防止路徑遍歷攻擊。輸出使用 XML tags 區隔不同檔案，方便 AI 解析。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        patterns: {
-          type: 'array',
-          items: {
-            type: 'string',
-          },
-          description: '檔案路徑或 glob patterns 陣列。範例：["file.txt", "*.md", "src/**/*.ts"]',
-        },
-      },
-      required: ['patterns'],
-    },
-  },
-
-  // 5. botrun-tree-view
-  {
-    name: 'list_files',
-    server: 'botrun-tree-view',
-    description:
-      '列出當前工作目錄的所有檔案(樹狀結構)。當使用者說「列出檔案」、「我想看檔案列表」、「list files」、「檔案列表」、「看檔案」、「看有哪些檔案」、「顯示檔案」、「檔案結構」、「目錄結構」、「tree」、「ls」時使用。無參數，自動列出 process.cwd() 下的所有檔案。',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      required: [],
-    },
-  },
-
-  // 6. botrun-multimodal-reader
-  {
-    name: 'read_multimodal',
-    server: 'botrun-multimodal-reader',
-    description:
-      '使用 Vertex AI Claude Haiku 4.5(台灣端點)多模態閱讀本地檔案。支援多種格式：\n\n' +
-      '📄 **文件**：PDF, TXT\n' +
-      '🖼️ **圖片**：PNG, JPEG, WebP\n' +
-      '🎬 **影片**：MP4, MOV, WebM, MPEG, FLV, WMV, 3GP\n' +
-      '🎵 **音訊**：MP3, WAV, AAC, FLAC, M4A, Opus, PCM\n\n' +
-      '支援單一檔案、多檔案、或使用萬用字元(如 *.pdf, *.mp4)。可平行處理最多 30 個檔案，理解文字、圖片、圖表、影片、音訊等所有多模態內容。所有路徑嚴格限制在工作目錄內，防止路徑遍歷攻擊。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        filePaths: {
-          type: ['string', 'array'],
-          description:
-            '檔案路徑(字串或字串陣列)。支援萬用字元(如 "*.pdf", "*.mp4", "audio-*.mp3")。所有路徑必須在工作目錄內。\n\n' +
-            '支援的格式：\n' +
-            '- 文件：.pdf, .txt\n' +
-            '- 圖片：.png, .jpg, .jpeg, .webp\n' +
-            '- 影片：.mp4, .mov, .webm, .mpeg, .mpg, .flv, .wmv, .3gp\n' +
-            '- 音訊：.mp3, .wav, .aac, .flac, .m4a, .opus, .pcm\n\n' +
-            '範例：\n' +
-            '- 單一檔案："document.pdf" 或 "video.mp4" 或 "audio.mp3"\n' +
-            '- 多檔案：["page-1.pdf", "video.mp4", "audio.mp3"]\n' +
-            '- 萬用字元："*.pdf" 或 "video-*.mp4" 或 "*.mp3"',
-          items: {
-            type: 'string',
-          },
-        },
-        prompt: {
-          type: 'string',
-          description: '要問的問題或分析指示(可選，預設為完整描述)',
-        },
-      },
-      required: ['filePaths'],
-    },
-  },
-
-  // 7. botrun-web-search
-  {
-    name: 'web_search',
-    server: 'botrun-web-search',
-    description:
-      `使用 Claude Haiku 4.5(台灣端點 asia-east1) + Brave Search 進行網路搜尋。
-
-**核心功能**：
-- 搜尋引擎：Brave Search(Anthropic 提供)
-- 自動取得最新網路資訊
-- 用繁體中文總結結果
-- 回傳來源網址和引證內容
-
-**支援功能**：
-1. 單一查詢或平行多個查詢
-2. 限制搜尋網域(只搜尋特定網站)
-3. 排除特定網域
-4. 本地化搜尋結果
-5. 限制搜尋次數
-
-**回傳內容**：
-- result: 繁體中文總結
-- citations[]: 引用來源(含 url, title, cited_text)
-- sources[]: 搜尋結果來源(含 url, title, page_age)
-- usage: Token 使用統計
-
-**何時使用**：
-- 使用者詢問最新資訊、新聞、天氣、股市等即時資訊
-- 需要引證來源網址時
-- 需要搜尋特定網域的資訊(如政府網站、教育機構)
-- 需要排除不可信來源時`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        queries: {
-          type: ['string', 'array'],
-          description: `**搜尋查詢**(必填)
-
-支援格式：
-- 單一查詢：字串
-- 多個平行查詢：字串陣列
-
-範例：
-- 基本搜尋："台灣今天新聞"
-- 平行搜尋：["台灣今天新聞", "台北天氣", "台股行情"]
-
-使用建議：
-- 查詢要具體明確
-- 多個查詢會平行執行，速度更快
-- 每個查詢獨立回傳結果`,
-          items: {
-            type: 'string',
-          },
-        },
-        max_uses: {
-          type: 'number',
-          description: `**限制搜尋次數**(選填)
-
-限制 Claude 在單次對話中最多執行幾次搜尋。
-
-範例：
-- max_uses: 3(最多搜尋 3 次)
-- max_uses: 1(只搜尋 1 次)
-
-何時使用：
-- 需要控制成本時
-- 快速回應不需要多次搜尋時
-- 避免過度搜尋時`,
-        },
-        allowed_domains: {
-          type: 'array',
-          items: {
-            type: 'string',
-          },
-          description: `**允許的網域白名單**(選填)
-
-只搜尋來自這些網域的結果，其他來源會被過濾。
-
-範例：
-- ["gov.tw", "edu.tw"] → 只搜尋台灣政府和教育機構
-- ["law.moj.gov.tw"] → 只搜尋全國法規資料庫
-- ["wikipedia.org"] → 只搜尋維基百科
-- ["github.com", "stackoverflow.com"] → 只搜尋技術網站
-
-何時使用：
-- 需要權威來源時(政府、教育機構)
-- 需要特定領域資訊時
-- 需要可信度高的內容時
-- 使用者明確要求引證特定網站時
-
-注意：
-- 網域不需要加 https://
-- 可以使用子網域(如 law.moj.gov.tw)
-- 越具體越精確`,
-        },
-        blocked_domains: {
-          type: 'array',
-          items: {
-            type: 'string',
-          },
-          description: `**封鎖的網域黑名單**(選填)
-
-永不包含來自這些網域的搜尋結果。
-
-範例：
-- ["example.com"] → 排除範例網站
-- ["ads-site.com", "spam-site.com"] → 排除廣告和垃圾網站
-
-何時使用：
-- 排除不可信來源
-- 排除廣告網站
-- 使用者明確要求排除特定網站時
-
-注意：
-- 與 allowed_domains 互斥
-- 如果同時設定，allowed_domains 優先`,
-        },
-        user_location: {
-          type: 'object',
-          properties: {
-            type: {
-              type: 'string',
-              enum: ['approximate'],
-            },
-            city: {
-              type: 'string',
-            },
-            region: {
-              type: 'string',
-            },
-            country: {
-              type: 'string',
-            },
-            timezone: {
-              type: 'string',
-            },
-          },
-          description: `**使用者位置(本地化)**(選填)
-
-根據位置本地化搜尋結果，提供更相關的地區性內容。
-
-格式：
-{
-  "type": "approximate",
-  "city": "城市名稱",
-  "region": "地區/州/省",
-  "country": "國家代碼",
-  "timezone": "時區"
-}
-
-範例：
-- 台北：{"type": "approximate", "city": "Taipei", "region": "Taiwan", "country": "TW", "timezone": "Asia/Taipei"}
-- 東京：{"type": "approximate", "city": "Tokyo", "region": "Kanto", "country": "JP", "timezone": "Asia/Tokyo"}
-- 紐約：{"type": "approximate", "city": "New York", "region": "New York", "country": "US", "timezone": "America/New_York"}
-
-何時使用：
-- 搜尋「天氣」、「新聞」等地區性資訊時
-- 搜尋「餐廳」、「景點」等本地服務時
-- 需要特定地區的搜尋結果時
-
-注意：
-- 所有欄位都是選填，但建議至少填 city 和 country
-- country 使用 ISO 3166-1 alpha-2 代碼(如 TW, US, JP)
-- timezone 使用 IANA 時區資料庫格式`,
-        },
-      },
-      required: ['queries'],
-    },
-  },
-
-  // 8. botrun-audio-transcribe
-  {
-    name: 'transcribe_audio_file',
-    server: 'botrun-audio-transcribe',
-    description: `使用 NCHC Whisper 轉錄音訊檔案。支援大檔案自動切割(每 3 分鐘)和平行處理(最多 50 個並發)。`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        filePath: {
-          type: 'string',
-          description: '音訊檔案的路徑(相對於工作目錄或絕對路徑)',
-        },
-        model: {
-          type: 'string',
-          description: 'Whisper 模型名稱(預設: whisper-Breeze-ASR-25)',
-          enum: ['whisper-Breeze-ASR-25', 'Whisper-Large-V3'],
-        },
-      },
-      required: ['filePath'],
-    },
-  },
-];
-
-/**
- * 主函數：計算並輸出統計資訊
- */
-function main() {
-  console.log('='.repeat(80));
-  console.log('📊 MCP Server Tool Definitions Token 使用量分析');
-  console.log('='.repeat(80));
-  console.log();
-
-  let totalTokens = 0;
-  const results: Array<{ name: string; server: string; tokens: number; jsonLength: number }> = [];
-
-  // 計算每個 tool 的 token 數量
-  for (const tool of MCP_TOOLS) {
-    const toolJson = JSON.stringify(tool, null, 2);
-    const tokens = countTokens(toolJson);
-    totalTokens += tokens;
-
-    results.push({
-      name: tool.name,
-      server: tool.server,
-      tokens,
-      jsonLength: toolJson.length,
-    });
-  }
-
-  // 排序：按 token 數量降序
-  results.sort((a, b) => b.tokens - a.tokens);
-
-  // 輸出詳細統計
-  console.log('📋 各個 MCP Tool 的 Token 使用量 (按 Token 數量降序)：');
-  console.log();
-  console.log('| # | Tool Name                | Server                      | Tokens | JSON 字元數 |');
-  console.log('|---|--------------------------|-----------------------------| ------:| -----------:|');
-
-  results.forEach((result, index) => {
-    console.log(
-      `| ${String(index + 1).padStart(2, ' ')} | ${result.name.padEnd(24, ' ')} | ${result.server.padEnd(27, ' ')} | ${String(
-        result.tokens
-      ).padStart(6, ' ')} | ${String(result.jsonLength).padStart(11, ' ')} |`
-    );
-  });
-
-  console.log();
-  console.log('='.repeat(80));
-  console.log('📊 總結：');
-  console.log('='.repeat(80));
-  console.log(`總計 MCP Tools 數量: ${MCP_TOOLS.length} 個`);
-  console.log(`總 Token 使用量: ${totalTokens.toLocaleString()} tokens`);
-  console.log(`平均每個 Tool: ${Math.round(totalTokens / MCP_TOOLS.length).toLocaleString()} tokens`);
-  console.log();
-
-  // 計算各種情境下的負擔
-  console.log('='.repeat(80));
-  console.log('💡 不同情境下的 Token 負擔：');
-  console.log('='.repeat(80));
-  console.log();
-
-  // 情境 1: 初始載入所有 tools (ListTools)
-  console.log('1️⃣  初始載入 (ListTools)：');
-  console.log(`   - 一次性載入所有 ${MCP_TOOLS.length} 個 MCP Tools`);
-  console.log(`   - 初始負擔：${totalTokens.toLocaleString()} tokens`);
-  console.log();
-
-  // 情境 2: 每次對話都要傳遞 tools (假設使用 Claude Agent SDK)
-  console.log('2️⃣  每次對話傳遞 Tools (如果使用 allowedTools)：');
-  console.log(`   - 每次 API 呼叫都會傳遞所有 tools 定義`);
-  console.log(`   - 每次對話負擔：${totalTokens.toLocaleString()} tokens`);
-  console.log(`   - 10 次對話：${(totalTokens * 10).toLocaleString()} tokens`);
-  console.log(`   - 100 次對話：${(totalTokens * 100).toLocaleString()} tokens`);
-  console.log();
-
-  // 情境 3: Top 3 最大的 tools
-  const top3 = results.slice(0, 3);
-  const top3Tokens = top3.reduce((sum, r) => sum + r.tokens, 0);
-  console.log('3️⃣  最消耗 Token 的前 3 個 Tools：');
-  top3.forEach((result, index) => {
-    console.log(`   ${index + 1}. ${result.name}: ${result.tokens.toLocaleString()} tokens`);
-  });
-  console.log(`   合計：${top3Tokens.toLocaleString()} tokens (佔總量 ${((top3Tokens / totalTokens) * 100).toFixed(1)}%)`);
-  console.log();
-
-  // 情境 4: 最小的 tools
-  const bottom3 = results.slice(-3).reverse();
-  const bottom3Tokens = bottom3.reduce((sum, r) => sum + r.tokens, 0);
-  console.log('4️⃣  最輕量的 3 個 Tools：');
-  bottom3.forEach((result, index) => {
-    console.log(`   ${index + 1}. ${result.name}: ${result.tokens.toLocaleString()} tokens`);
-  });
-  console.log(`   合計：${bottom3Tokens.toLocaleString()} tokens (佔總量 ${((bottom3Tokens / totalTokens) * 100).toFixed(1)}%)`);
-  console.log();
-
-  console.log('='.repeat(80));
-  console.log('✅ 分析完成！');
-  console.log('='.repeat(80));
-
-  // 清理 encoder
-  encoder.free();
-}
-
-// 執行主函數
-main();