BeaconBay/ck

Local first semantic and hybrid BM25 grep / search tool for use by AI and humans!

📦 ck – 語意代碼搜尋

ck（發音：「seek」）是一款基於 Rust 的命令列工具，讓您能透過語意而非僅文字匹配來搜尋原始碼。它會建立程式碼的本地嵌入（embeddings），增量快取，並能回應如「錯誤處理」或「驗證邏輯」等查詢，即使這些字詞未明確出現，也能回傳相關的函數、類別或程式碼區塊。

🎯 功能

功能	說明
語意搜尋	透過向量嵌入（BGE‑Small、Mixedbread、Nomic、Jina‑Code 等）尋找程式碼概念。
混合搜尋	使用 Reciprocal Rank Fusion 將語意相關性與傳統正規表示式/關鍵字比對結合。
grep 相容 CLI	支援您熟悉的 `grep`/`ripgrep` 參數（`-n`、`-R`、`-l` 等）。
互動式 TUI	全螢幕終端介面，支援即時結果、預覽模式、多選與編輯器整合。
AI 代理（MCP）伺服器	透過 Model Context Protocol（MCP）公開工具（`semantic_search`、`regex_search` 等），讓 Claude Desktop、Cursor 或其他代理可程式化呼叫 ck。
增量、分塊級索引	僅重新嵌入變更的區塊；在典型編輯中快取命中率可達 80–90%。
智慧檔案過濾	尊重 `.gitignore`、專用的 `.ckignore` 及命令列排除參數。
結構化輸出	支援 `--json`（單一陣列）或 `--jsonl`（行分隔）格式，適用於腳本與 LLM 流水線。
多語言支援	Python、JavaScript/TypeScript、Rust、Go、C/C++、C#、Ruby、Haskell、Dart、Markdown，以及通用文字格式。
純離線運作	所有嵌入模型皆在本機執行；初始模型下載後不再產生網路流量。

⚙️ 工作原理（概覽）

索引建立 – ck --index <root> 遍歷原始碼樹，使用 Tree‑sitter 將檔案分割為語言感知的區塊（函數、類別等），並透過 FastEmbed 計算嵌入。索引資料儲存在 .ck/ 目錄中（或透過 CK_INDEX_DIR 指定自訂路徑）。
搜尋 – 查詢使用相同模型進行嵌入，與儲存的向量計算相似度分數。在混合模式下，傳統正規表示式搜尋並行執行，兩結果列表合併。
服務 – ck --serve 啟動 MCP 伺服器，將搜尋工具作為 JSON-RPC 端點公開，讓 AI 助手可直接呼叫。

🚀 快速入門（CLI）

# 從 crates.io 安裝二進位檔
cargo install ck-search

# 語意搜尋（首次執行時自動建立索引）
ck --sem "error handling" src/

# 混合搜尋（語意 + 關鍵字）
ck --hybrid "connection timeout" src/

# 傳統 grep 風格搜尋
ck -R "TODO|FIXME" .

# 互動式終端 UI
ck --tui "authentication logic"

🤖 AI 代理整合（MCP）

# 啟動伺服器
ck --serve

伺服器註冊如 semantic_search 等工具，代理可呼叫：

{
  "tool": "semantic_search",
  "args": {"query": "authentication logic", "path": "/my/project", "top_k": 25}
}

回應以 JSONL 格式串流輸出，便於在 LLM 驅動的工作流程中使用。

📚 常見使用情境

開發者生產力 – 無需記住確切識別碼，即可快速跳轉至某概念的實作。
程式碼審查準備 – 列出所有實作安全關鍵模式的函數。
CI/CD 自動化 – 掃描倉儲中不安全的模式（ck --json --sem "password|secret" . | my_scanner）。
團隊入職 – 快速定位相關測試檔案或重複邏輯。
LLM 增強工具 – 將結構化搜尋結果輸入 Claude、Cursor 或自訂代理。

📦 安裝

方法	命令
Crates.io（推薦）	`cargo install ck-search`
從原始碼安裝	`git clone https://github.com/BeaconBay/ck && cd ck && cargo install --path ck-cli`
未來套件管理器	Brew / apt 套件正在規劃中，尚未發佈。

📄 授權

採用 MIT 與 Apache‑2.0 雙重授權（詳見 LICENSE-MIT / LICENSE-APACHE）。

🙏 更多資訊

完整文件： https://beaconbay.github.io/ck/
TUI 指南：倉儲中的 TUI.md
模型選擇與索引細節見 README 表格。

ck 是一個真實、持續維護的開源專案，將現代 AI 驅動的語意搜尋帶入熟悉的命令列程式碼 grep 世界。它完全離線運作，尊重您的 .gitignore，並能無縫整合至人類工作流程與 AI 代理中。