Tokenectomy Razor

Tokenectomy Razor

修復 Claude Code 與 Cursor 速率限制：以 Rust 打造之零延遲本地 AI 閘道與上下文手術 MCP 伺服器

別再為了 node_modules 堆疊追蹤而燒掉 20,000 個 token。Tokenectomy Razor 是一個以安全 Rust 撰寫的次毫秒本地 AI 閘道反向代理（127.0.0.1:8080）及配套 MCP 伺服器。它能從終端錯誤日誌中切除 41.7%–99.7% 的框架雜訊、遮罩外洩的資料庫憑證/JWT，並免費快取提示詞。

快速開始（10 秒） • 架構 • 問題所在 • 前後對比 • 即時互動示範 • 效能基準

                                 ┌────────────────────────────────────────────────────────┐
                                 │                   Autonomous Agents                    │
                                 │  Claude Code • Cursor • Antigravity • Cline • Windsurf │
                                 └───────────────────────────┬────────────────────────────┘
                                                             │
                                                             ▼ (HTTP / SSE Outbound Prompts)
   ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
   │                                 ⚡ TOKENECTOMY AI GATEWAY (127.0.0.1:8080)                                       │
   │                                                                                                                  │
   │  ┌─────────────────────────┐   ┌───────────────────────────┐   ┌──────────────────────────────────────────────┐  │
   │  │   Zero-Cost Prompt      │   │   Zero-Leak Credential    │   │         Polyglot Trace Surgery               │  │
   │  │         Cache           │   │         Redaction         │   │            (9 Languages)                     │  │
   │  │  <1ms Hit • 100% Free   │   │  API Keys • JWTs • DB URIs│   │  node_modules • site-packages • .cargo       │  │
   │  └───────────┬─────────────┘   └─────────────┬─────────────┘   └──────────────────────┬───────────────────────┘  │
   │              │                               │                                        │                          │
   │              └───────────────────────────────┼────────────────────────────────────────┘                          │
   │                                              ▼                                                                   │
   │                                 Smart Upstream Auto-Router                                                       │
   │                         (Anthropic • OpenAI • Groq • Ollama Local)                                               │
   └──────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────┘
                                                  │
                 ┌────────────────────────────────┼────────────────────────────────┐
                 ▼                                ▼                                ▼
       api.anthropic.com                  api.openai.com                   localhost:11434
    (Claude 3.5 / 3.7 Sonnet)         (GPT-4o / o1 / o3-mini)              (DeepSeek / Llama)

⚡ 快速開始（10 秒）

0. 零設定單行包裝器（wrap）

在 Tokenectomy 的隱私與快取閘道後方直接執行任何程式碼代理或測試套件，無需手動設定任何環境變數：

# Wrap Claude Code CLI
razor wrap -- claude

# Wrap Aider with DeepSeek or Ollama (Auto-Transpiled on the fly!)
razor wrap -- aider --model deepseek/deepseek-chat

# Wrap test runs to scrub logs and prevent accidental credential leakage
razor wrap npm test

1. 啟動獨立 AI 閘道（手動模式）

npx -y tokenectomy-razor --proxy

💡 智慧多供應商自動路由與通用 LLM 轉譯器預設開啟！ Tokenectomy 會自動分析請求路徑與標頭。需要讓 Claude Code 對接 DeepSeek 或 Ollama 嗎？Tokenectomy 會即時將 Anthropic /v1/messages 格式轉譯為 OpenAI /v1/chat/completions 格式，反之亦然。

2. 連接您喜愛的代理

將您的程式碼代理或 CLI 指向位於 127.0.0.1:8080 的本地閘道：

3. 即時 FinOps 與安全儀表板

在瀏覽器中開啟 http://127.0.0.1:8080/dashboard，即時觀察 token 減量、提示詞快取命中率、節省金額以及被遮罩的憑證。

4. 配套 MCP 伺服器設定（子皮層）

供呼叫深度診斷工具（get_error_context、analyze_code、apply_code_patch）的代理使用：

Claude Code CLI

claude mcp add tokenectomy npx -y tokenectomy-razor --mcp

Google Antigravity / Gemini CLI

agy mcp add tokenectomy-razor -- npx -y tokenectomy-razor --mcp

Cursor Composer（.cursor/mcp.json）

{
  "mcpServers": {
    "tokenectomy": {
      "command": "npx",
      "args": ["-y", "tokenectomy-razor", "--mcp"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "tokenectomy": {
      "command": "npx",
      "args": ["-y", "tokenectomy-razor", "--mcp"]
    }
  }
}

5. 終端管線與 CLI 清理

npm test 2>&1 | npx tokenectomy-razor

🛑 問題所在：為何您的 AI 會觸發速率限制並產生幻覺

當您的應用程式在開發期間崩潰（Next.js、Express、FastAPI、Tokio）時，執行環境會傾倒數百行來自 node_modules 或 site-packages 的第三方管道程式碼。

當您將原始崩潰傾倒內容貼入 Cursor 或 Claude 時：

1. 耗盡您的 5 小時速率限制：單一 Express/Prisma 錯誤可能傾倒 5,000 至 45,000 個 token 的第三方函式庫程式碼，而這些程式碼並非您所撰寫。幾次崩潰迴圈就足以燒光您的會話額度。
2. 觸發 AI 幻覺：Claude 會迷失在框架內部（node_modules/express/lib/router/layer.js 或 starlette/routing.py）中，並嘗試編輯函式庫檔案，而非您的實際應用程式碼。
3. 洩漏機密與憑證：包含原始資料庫密碼的連線字串、JWT bearer token 以及內嵌於錯誤追蹤中的雲端金鑰，都會被轉發至外部模型伺服器。

Raw Terminal Crash (45,820 tokens + Leaked Secrets)
     │
     ▼  <0.2ms Local Rust DFA Engine
[Redact Passwords & Keys] ──► [Strip Third-Party Framework Frames] ──► [Isolate Root Cause]
     │
     ▼
Clean Context (118 tokens • Zero Secrets • Sub-millisecond)

🔍 前後對比

❌ 沒有 Tokenectomy：AI 產生幻覺並燒盡上下文

TypeError: Cannot read properties of undefined (reading 'token')
    at loadComponents (/app/node_modules/next/dist/server/load-components.js:14:2)
    at renderToHTML (/app/node_modules/next/dist/server/render.js:50:5)
    at nextServer (/app/node_modules/next/dist/server/next-server.js:80:12)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at runMicrotasks (node:internal/process/task_queues:120:3)
    at checkoutHandler (/app/pages/api/checkout.ts:42:15)
Database connection failed: postgresql://admin:super_secret_password@db.prod.internal:5432/primary
API key leaked: sk-ant-api03-abcdef1234567890abcdef1234567890

Claude 會做什麼： 分析 load-components.js 與 next-server.js，推測 Webpack / Next.js 內部機制，並將連線憑證洩漏至遠端推論日誌。

✅ 使用 Tokenectomy：乾淨上下文與即時修復

// [Tokenectomy Surgery: 5 internal framework frames pruned (83.3%)]
// Source: /app/pages/api/checkout.ts:42:15
42 |   const sessionToken = req.headers.authorization.token;
   |                                                  ^ TypeError: Cannot read properties of undefined (reading 'token')
🛡️ [CONNECTION_STRING_REDACTED]
🛡️ [ANTHROPIC_KEY_REDACTED]

Claude 會做什麼： 立即識別出 checkout.ts 第 42 行嘗試存取未定義 headers 上的 .token。立即建議使用可選鏈（req.headers.authorization?.token）。憑證在傳輸前即已遮罩。

🔬 可驗證的效能基準

所有效能宣稱皆以實體硬體為基礎，且可獨立重現（於執行 Arch Linux、Kernel 6.13 的 10 核心 Intel Core i5-1235U @ 15W 上量測）：

硬體依賴聲明： 效能取決於硬體；所報告的吞吐量代表在指定測試硬體（10 核心 Intel Core i5-1235U @ 15W TDP）上量測的結果。吞吐量會隨更高 TDP 的桌上型/伺服器 CPU 與更快的記憶體匯流排而提升。鼓勵開發者使用下方重現指令獨立稽核效能。

$ cargo test --release --test stress_benchmark -- --nocapture

=====================================================================================
🧪 TOKENECTOMY OSS VERIFIABLE HEAVY STRESS BENCHMARK (100% REPRODUCIBLE IN OSS)
   Hardware: 10-Core / 12-Thread Intel Core i5-1235U | OS: Arch Linux | Kernel Telemetry Active
   Initial Baseline Process Memory (VmRSS): 3.45 MB
=====================================================================================

🔥 [TEST 1/3] QUARTER-MILLION LINES LOG REDACTION TORTURE (250,000 LINES / 25MB+ BUFFER)
  ├── Buffer Size: 24.44 MB (250000 lines)
  ├── Redaction Latency: 471.05ms (51.9 MB/sec)
  ├── Line Throughput: 530,735 lines/sec
  ├── Peak Memory (VmRSS): 76.05 MB (Delta: +72.60 MB)
  └── Status: ✅ PASSED (100% of 250,000 lines sanitized, zero memory balloon)

🔥 [TEST 2/3] REDOS CATASTROPHIC BACKTRACKING TORTURE (50,000 CHARS PAYLOAD)
  ├── Attack Payload Size: 50,082 characters
  ├── Execution Latency: 1.165 ms
  └── Status: ✅ PASSED (Linear O(N) evaluation, ReDoS-resistant on tested payloads)

🔥 [TEST 3/3] HIGH-CONCURRENCY TORTURE (100 PARALLEL OS THREADS)
  ├── Thread Concurrency: 100 concurrent OS threads
  ├── Successful Operations: 100/100 (100.0%)
  ├── Total Elapsed: 11.31ms
  ├── Concurrency Throughput: 17,688 ops/sec
  ├── Final VmRSS: 78.99 MB
  └── Status: ✅ PASSED (Zero race condition, zero deadlock)

=====================================================================================
🏆 TOKENECTOMY OSS STRESS BENCHMARK: 3/3 PASSED (100% GREEN)
   Total Suite Duration: 580.83ms
   Bounded Final VmRSS: 78.99 MB
=====================================================================================
test test_oss_heavy_stress_benchmark ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.58s

🛡️ 自動遮罩與機密淨化基準

於內部基準測試夾具（tests/fixtures/）上評估，包含 12 份多語言崩潰追蹤（Rust、Python、TypeScript、Go、YAML），內含 22 個真實憑證與乾淨的負面對照組。並與 Gitleaks v8.30.1（預設規則集）進行正面對決。

架構說明： Gitleaks 主要設計為儲存庫提交/差異掃描器，而非記憶體內的執行時期追蹤遮罩器。Tokenectomy Razor 則專門針對執行時期串流淨化與堆疊追蹤手術而設計。

1. 各類別精確率、召回率與 F1 分數

2. 正面對決效能與架構摘要

3. Token 減量與 LLM 上下文節省（tiktoken cl100k_base）

🔌 進階代理與閘道組態

1. 多供應商 AI 閘道選項（--proxy）

Tokenectomy 的閘道在 127.0.0.1:8080 上以零手動組態於本地執行。在複雜的開發環境或容器化代理拓撲中，您可以自訂綁定與路由：

# Default Smart Auto-Routing (routes Anthropic, OpenAI, and Ollama requests dynamically):
razor --proxy

# Safety Circuit Breaker: Prevent runaway agent loops from burning your hourly budget or 5-hour window:
razor --proxy --max-hourly-tokens 200000

# Resilient 429 Auto-Retry: Automatically pause and retry when hitting upstream rate limits (default: on):
razor --proxy --max-retries 5

# Explicit upstream override (e.g. Groq, vLLM, or OpenRouter):
razor --proxy --upstream-url https://api.groq.com/openai/v1

# Secure remote container binding with mandatory bearer token:
razor --proxy --proxy-bind 0.0.0.0:8080 --allow-remote --proxy-token "$MY_GATEWAY_TOKEN"

即時指標與 Prometheus 匯出

Tokenectomy 透過 JSON 公開即時的 FinOps 與代幣經濟數據：

curl http://127.0.0.1:8080/v1/metrics

回傳 rate_limits_mitigated、circuit_breaker_trips、last_latency_ms、current_hourly_tokens、cache_hits、cache_tokens_saved 與 estimated_cost_saved_usd 的即時遙測資料。

2. 獨立 CLI 與終端機清理

當直接除錯或將終端機測試輸出進行管道處理時：

# Pipe terminal test failures through the surgical redactor:
npm test 2>&1 | razor --scrub

# Sanitize a specific raw log file:
razor --scrub --file /var/log/app/error.log > sanitized.log

# Offline local air-gapped mode (zero external network calls):
cat failure.log | razor --scrub --local-only

🛠️ 公開的 MCP 工具

Tokenectomy Razor 符合 Glama Grade A 工具定義品質評分（TDQS），並具備明確的參數邊界：

🌐 支援的多語言生態系

📦 安裝選項

方法 1：透過 npx 即時安裝（零工具鏈設定）

npx -y tokenectomy-razor --mcp

方法 2：Cargo（crates.io）

cargo install tokenectomy

方法 3：預編譯獨立二進位檔

零依賴的獨立發行二進位檔可於 GitHub Releases 取得：

• Linux： x86_64-unknown-linux-gnu、x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu
• macOS： aarch64-apple-darwin（Apple Silicon M1/M2/M3/M4）、x86_64-apple-darwin（Intel）
• Windows： x86_64-pc-windows-msvc.exe

方法 4：多架構 Docker 容器（GHCR）

docker pull ghcr.io/tokenectomy-labs/razor:latest
docker run -i ghcr.io/tokenectomy-labs/razor:latest --mcp

⚖️ 版本比較

需要企業級 AST 自我修復？ 探索 Sentinel 版本

🗺️ 路線圖與里程碑

🔒 安全性與不變量

• 預設本地執行： 所有堆疊追蹤解析、幀修剪與機密遮罩均在實體硬體上本地執行。
• 已記錄的網路出口： 在 MCP 伺服器模式下，search_stack_overflow 是唯一具備對外網路出口的工具（HTTPS 至 api.stackexchange.com）。負載嚴格限制為已消毒、遮罩的錯誤特徵文字（不含程式碼行、不含本地路徑、零憑證）。在氣隙環境中，使用 --local-only 可完全停用網路搜尋。
• 確定性線性時間模式比對： 所有模式比對器均使用非回溯 DFA 正規表達式引擎（$O(N)$ 線性時間）與 Aho-Corasick 自動機評估。
• 路徑遍歷邊界隔離： 檔案操作嚴格鎖定在作用中工作區根目錄（CWD）內。路徑遍歷（../）與未授權的符號連結均被封鎖。
• 安全 Rust 實作： 核心執行路徑強制執行安全 Rust 記憶體保證，並使用有界串流讀取器（.take()）防止資源耗盡。

如需漏洞揭露，請參閱我們的安全性政策。

⚖️ 法律與下游分支免責聲明

Tokenectomy Razor 僅供合法的開發者生產力、可觀測性、日誌手術與防禦性憑證遮罩使用。任何下游分支、複製、重新散布或私人部署均完全獨立於原始作者。Tokenectomy Labs 及其維護者對第三方使用此程式碼庫或其衍生品所進行的非法、惡意或未授權行為不承擔任何責任。所有下游營運者須 100% 個別承擔遵守當地與國際網路安全法律的責任。完整法律條款請參閱 DISCLAIMER.md。

❓ 常見問題（FAQ）

Tokenectomy Razor 如何防止 Claude Code 與 Cursor 觸發速率限制？

當測試或終端機建置崩潰時，Next.js、Express、Jest 與 Django 等框架會傾印數千個內部堆疊幀（node_modules、site-packages）。傳送原始 5,000 行崩潰日誌每次提示詞會消耗 15,000 至 45,000 個代幣，在數分鐘內耗盡您的 5 小時工作階段限制。Tokenectomy Razor 攔截日誌並移除 95% 不具可操作性的框架管線，在 <0.2ms 內將 40,000 字元的崩潰日誌縮減至 200 個以下的基本代幣。

如何阻止 Cursor 將 node_modules 錯誤日誌傳送給 LLM？

將 Tokenectomy Razor 作為本地 AI 閘道反向代理執行（npx -y tokenectomy-razor --proxy）。在 Cursor 設定中，將您的 OpenAI Base URL 指向 http://127.0.0.1:8080/v1。任何由 Composer 貼上或引用的終端機錯誤輸出，都會在送達模型伺服器前自動進行消毒、清理與快取。

Tokenectomy 如何防止錯誤日誌中的憑證洩漏？

所有日誌手術與機密遮罩均在您的機器上 100% 本地記憶體中執行，然後才進行對外傳輸。Razor 使用確定性線性時間正規表達式與 Aho-Corasick 自動機，以 [REDACTED] 代幣偵測並遮罩 PostgreSQL/MongoDB 連線 URI、JWT bearer 代幣與雲端 API 金鑰。清理過程零雲端出口需求。

🤝 社群與資源

• 🌐 官方網站
• 📖 文件
• 🏗️ 系統架構
• 📋 變更日誌
• 🤝 貢獻指南
• 🔒 安全性政策
• ⚖️ 免責聲明與責任