Cranot/roam-code

Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evidence, zero API keys.

📚 什麼是 roam‑code

roam‑code 是一個基於 Python 的本地執行靜態分析工具包，專為 程式碼代理（LLM 驅動的程式碼生成工具）設計。它建立程式碼庫中符號（函數、類別、匯入及其相互關係）的可搜尋地圖，讓代理能詢問「誰呼叫了這個函數？」或「這個變更會影響哪些測試？」等問題，而無需逐一讀取所有檔案。

此工具 不進行任何遠端模型呼叫；所有繁重工作皆在您的機器上完成。它以 CLI（roam）形式提供，並可選地作為 MCP（Model-Control-Protocol）伺服器運行，讓代理可透過標準工具呼叫介面與之通訊。

🔧 核心功能（如 README 所述）

功能	作用	使用方式
索引 / `roam init`	解析整個程式庫，建立涵蓋 28 種語言、287 個指令與 246 個 MCP 工具的符號圖。	在程式庫根目錄執行 `roam init`（或使用 `roam index` 進行輕量建構）。
預飛行檢查 (`roam preflight <symbol>`)	評估變更的爆炸半徑（可能受影響的符號/檔案數量），並報告相關測試、複雜度、耦合度等。	`roam preflight open_db` – 回傳包含具體數字的風險評估結果。
健康摘要 (`roam health`)	提供程式碼結構、發現項目與整體「健康分數」的快速概覽。	索引完成後執行 `roam health`。
搜尋 (`roam search <name>`)	在索引圖中按名稱搜尋符號。	`roam search handleSave`。
驗證 (`roam verify …`)	對變更檔案執行一系列靜態檢查：命名規範、匯入有效性、複雜度、密鑰外洩、慣用模式警告等。	`roam verify --auto`（自動為變更檔案選擇檢查項目）或使用更細緻的旗標。
MCP 伺服器 (`roam-code[mcp]`)	透過網路套接字公開相同查詢，讓基於 LLM 的代理可作為工具呼叫。	使用 `pip install "roam-code[mcp]"` 安裝並啟動伺服器；代理可透過 MCP 呼叫 `roam` 命令。
Claude Code 鈎子 (`roam hooks claude`)	自動將執行前上下文（呼叫者、最近變更）注入 Claude Code 提示詞，並在模型完成後驗證結果。	`roam hooks claude --write` 啟用，`--uninstall` 移除。
Roam Guard	一個 PR 門禁，記錄執行的檢查、其結果，並在出現關鍵發現時阻止合併。	在 CI 中使用 `roam verify --auto`；可設定為在特定嚴重性下失敗。
效能	索引為一次性成本；後續更新非常快速。基準測試（2026 年 5 月–7 月）顯示，導航類查詢的 LLM 輪次減少高達 80%，令牌數與成本大幅降低。	請參閱 README 中的詳細基準表格以獲取具體數字。

🚀 通常採用方式

新增至程式庫 – 在專案的虛擬環境中執行 pip install "roam-code[mcp]"。
建立索引 – 在程式庫根目錄執行 roam init（大型程式碼庫首次執行可能需一分鐘）。
連接你的代理 – 啟用 MCP 伺服器或 Claude 特定鈎子，讓 LLM 能在推理過程中請求 roam 資料。
在 CI 中執行檢查 – 使用 roam verify --auto（或自訂檢查集）在合併前強制執行「門禁」。
迭代 – 變更後，執行 roam preflight <symbol> 查看潛在影響，再提交。

📊 為何對 AI 輔助開發至關重要

本地化、隱私保護 – 無需 API 金鑰，無遙測資料；分析完全在本地完成。
代理為中心 – 提供結構化、符號級別的上下文，LLM 可直接使用，減少通常所需的「搜尋-開啟檔案」步驟。
語言無關 – 支援 28 種程式語言，適用於多語言單體程式庫。
門禁機制 – 可作為 CI 流水線的一部分，防止高風險變更被合併，補足人工程式碼審查。

📦 快速入門（四個指令）

pip install "roam-code[mcp]"   # CLI + 可選 MCP 伺服器
cd /path/to/your/repo
roam init                       # 建構索引與設定
roam health                     # 查看健康快照
roam preflight <symbol>         # 編輯前評估風險

TL;DR

roam‑code 是一個免費、開源的靜態分析引擎，將程式碼庫轉化為符號及其關係的可搜尋圖。它讓基於 LLM 的程式碼代理能提出精確、低令牌的問題，並可在 CI 中強制執行安全門禁——所有操作均無需將原始碼傳出機器外部。