Muvon/octocode

Octocode – 面向 AI 代理的結構化程式碼智慧

是什麼 – Octocode 是一個開源的 Rust 工具，可將程式碼庫轉換為即時可查詢的知識圖譜。它內建 MCP 伺服器（Claude Desktop、Cursor、Windsurf 等使用的 Model-Center-Protocol），讓 AI 助手能像人類一樣搜尋、導航並推理專案結構。

為何重要 – 傳統的檢索增強生成（RAG）將原始碼檔案視為平面文字片段，遺失了匯入、函數呼叫、繼承與模組邊界之間的關係。Octocode 提取一個基於 AST 的符號圖，具有確定性的邊（imports、calls、extends、implements 等），並將此圖譜與語意搜尋功能提供給任何 MCP 相容的代理。結果是 AI 可以給出程式碼感知的回答，例如「認證邏輯在哪裡處理？」或「哪些檔案依賴支付模組？」，而無需靠關鍵字匹配猜測。

---

核心功能

功能	你將獲得
語意搜尋	自然語言查詢使用 BM25 關鍵字匹配與向量嵌入（Voyage、OpenAI、Jina 等）的混合方式，返回最相關的檔案。
即時 AST 圖	Tree-sitter 將目前的原始碼樹解析為節點（檔案、符號）與邊（imports、calls 等），始終保持最新狀態——無需額外索引。
GraphRAG（可選）	可選的持久化圖在確定性圖之上新增 LLM 生成的描述與更廣泛的架構關係。
LSP 集成	使用 --with-lsp 啟動時，伺服器會透過你的語言伺服器（如 rust-analyzer）轉發 goto-definition、find-references、hover、completion 等請求。
結構化搜尋	AST 模式比對可定位特定程式碼模式（例如所有 .unwrap() 呼叫）。
多語言支援	16 種語言原生支援（Rust、Python、TypeScript/JS、Go、PHP、C++、Ruby、Elixir、Java、Swift、Svelte、Lua、CSS、JSON、Bash、Markdown）。
本地優先 & 隱私優先	可透過 fastembed 本地生成嵌入；雲端服務為可選，僅能看見你明確傳送的片段。

---

工作原理（高階流程）

1. Tree-sitter 解析 每個原始碼檔案 → 產生檔案、函數、類別等節點。
2. 即時符號圖 從這些節點建構，具有確定性邊（contains、imports、calls 等）。
3. 可選索引：為每個檔案（或符號）計算嵌入並儲存；可選 LLM 可新增文字描述。
4. MCP 伺服器 暴露 RPC 工具（semantic_search、view_signatures、graphrag、structural_search、LSP 輔助工具），AI 代理呼叫。
5. 混合檢索 結合 BM25 關鍵字得分與向量相似度（RRF 融合）對結果排序。

---

快速開始（安裝 → 索引 → 查詢）

# 安裝（curl 安裝器、Homebrew 或 cargo）
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# 或：brew install muvon/tap/octocode
# 或：cargo install octocode

# 設定嵌入提供者（Voyage AI 金鑰範例）
export VOYAGE_API_KEY="your-key"

# 索引專案
cd /path/to/your/project
octocode index   # 處理每個檔案並建構即時圖譜

# 自然語言搜尋
octocode search "authentication middleware"

---

連接 AI 助手（MCP 客戶端）

在客戶端的 mcpServers 設定中新增伺服器條目，例如 Claude Desktop：

{
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/path/to/your/project"]
    }
  }
}

現在助手可以呼叫 semantic_search 或 graphrag 等工具，並以具體位置與呼叫圖回答程式碼庫問題。

檢索品質（基準測試）

Octocode 附帶一個可重現的基準測試（127 個程式碼搜尋查詢），在自身原始碼樹上執行。使用簡單的混合策略（BM25 0.3 + 向量 0.7）達到：

• Hit@5 = 0.732
• Hit@10 = 0.835
• MRR = 0.572
• Recall@10 = 0.807 關鍵字加權可使 Hit@5 比僅使用密集檢索提升 +22%。基準測試也顯示，通用程式碼重排序器（bge-reranker-base）會降低性能，顯示需要專用程式碼重排序器。

---

誰可能使用它

• 開發者：希望其 LLM 驅動的助手（Claude、Cursor 等）理解倉儲實際架構的人。
• 團隊：建構需要可靠、隱私保護程式碼導航的內部 AI 代理的人。
• 工具製作者：尋找即用型 MCP 伺服器，提供 LSP 級精度而無需重新實作 AST 解析的人。

---

許可與社群

• 許可證：Apache 2.0（寬鬆，適合商業使用）。
• 倉儲活躍度：CI 指示器、覆蓋率指示器、crates.io 發布、持續增長的星標數。
• 支援：GitHub Issues、討論區、聯絡信箱（opensource@muvon.io）。

---

總結：Octocode 是一個真實、生產級的 Rust 專案，為 AI 代理提供程式碼的結構化、圖形化視圖，實現精確、上下文感知的輔助，同時將所有內容保留在本地並完全受控。