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 代理中。