ck

本地语义+关键词混合搜索，让 AI 和人都能秒找代码

开源 free 搜索知识

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1741

维护状态较活跃

是否开源是

定价模式 free

项目预览

项目数据

分类搜索知识

开发团队BeaconBay

所属国家

官网地址https://beaconbay.github.io/ck

GitHubhttps://github.com/BeaconBay/ck

定价模式free

价格说明开源免费工具，需自行部署使用

访问状态

是否开源是

开源协议Apache-2.0

主要语言Rust

技术栈/模型grep,grep-like,rust,semantic

GitHub 星标★ 1741

30天Star增速

HF 下载量

上线时间2025-08-30 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-11

浏览次数0

项目介绍

ck 是一个用 Rust 编写的本地优先语义与混合 BM25 搜索工具，定位是给 AI 和人类共用的 grep 替代品。它解决传统 grep 只能做字面匹配、无法理解语义的问题：当你想找“登录失败的处理逻辑”，grep 只能搜关键词，而 ck 能同时做 BM25 关键词检索和向量语义检索，并按混合排序返回最相关结果。核心能力包括：本地索引代码与文本文件，无需上传数据；支持语义搜索和关键词搜索两种模式；面向 AI Agent 设计，可作为工具调用接口让模型快速定位代码上下文，减少 token 消耗；Rust 实现带来较快的索引和查询速度。它适合在大型代码库、文档库中做模糊查找，也适合给本地 LLM 或编码助手提供检索能力。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

已安装 Rust 工具链与 Cargo（cargo install 必需）
一个待搜索的本地代码库或文本目录
可选：Claude Desktop / Cursor 等 MCP 兼容 AI 客户端
可选：Claude Code CLI（用于一键注册 MCP）

安装与启动步骤

1安装 ck 命令行

从 crates.io 安装 ck-search，装好后可直接用 ck 命令；安装完可先在任意目录试跑语义搜索。
```
cargo install ck-search
```
2语义搜索体验

用 --sem 按含义查找代码，无需预先建索引，ck 会自动建立并更新；路径传目录即可。
```
ck --sem "error handling" src/
```
3关键词与混合检索

传统 grep 用法仍可用，--hybrid 会把语义相关度和关键词过滤结合起来，结果更聚焦。
```
ck -n "TODO" *.rs
ck -R "TODO|FIXME" .
ck --hybrid "connection timeout" src/
```
4启动 MCP 服务

--serve 以 MCP Server 方式运行，供 AI 客户端调用；生产环境建议在代码库目录下启动。
```
ck --serve
```
5接入 AI 客户端

推荐用 Claude Code CLI 注册，scope 为 user；也可改为在客户端里手写 mcpServers 配置。
```
claude mcp add ck-search -s user -- ck --serve
```
6验证接入状态

注册后需重启 Claude Code，再用 list 命令或会话内 /mcp 查看 ck-search 是否已连接。
```
claude mcp list
```
7排查分块效果

--inspect 可查看文件被如何切分、token 占用情况，并支持换模型对比效果。
```
ck --inspect src/main.rs
ck --inspect --model bge-small src/main.rs
```

8可选源码构建

需要改代码或跑测试时，克隆仓库后用 cargo 构建工作区，再用 debug 二进制验证搜索。

git clone https://github.com/BeaconBay/ck
cd ck
cargo build --workspace
cargo test --workspace
./target/debug/ck --index test_files/
./target/debug/ck --sem "test query" test_files/

关键配置

配置项	必填	说明	示例
`mcpServers.ck.command`	是	MCP 手动配置里要启动的可执行程序名	`ck`
`mcpServers.ck.args`	是	传给 ck 的参数，以 MCP 服务模式启动	`["--serve"]`
`mcpServers.ck.cwd`	是	工作目录，指向你要检索的代码库根路径	`/path/to/your/codebase`
`claude mcp add -s`	否	注册 MCP 的作用域，user 表示对当前用户全局生效	`user`
`top_k`	否	MCP 工具调用参数，限制返回结果总数，默认 100	`50`
`snippet_length`	否	MCP 工具调用参数，控制返回代码片段长度	`200`

如何确认成功

执行 ck --sem "test query" test_files/ 或任意 --sem 搜索能返回结果即成功；接入 AI 客户端时用 claude mcp list（或 /mcp）看到 ck-search 已注册连接。

常见问题

Q：首次搜索需要手动建索引吗？

A：不需要。ck 会自动建立并更新索引，直接执行 ck --sem 即可，索引和查询都发生在本地。

Q：索引跑到一半能中断吗？

A：可以，用 Ctrl+C 安全中断。已生成的部分索引会被保存，下次操作从断点继续，只处理新增或变更的文件。

Q：MCP 注册后 AI 客户端里没反应？

A：先重启 Claude Code，再用 claude mcp list 或会话内 /mcp 检查；提示权限时需批准 ck-search 的工具权限。

Q：返回结果太多怎么办？

A：MCP 工具支持内置分页：用 page_size 控制单页数量，配合游标翻页，并用 top_k 限制总条数、snippet_length 控制片段长度。

Q：怎么确认切分和模型效果？

A：用 ck --inspect src/main.rs 查看分块与 token 使用，再加 --model bge-small 切换模型做对比测试。

注意事项

项目本地优先，索引与检索都在本机完成，无需上传代码。
MCP 提供 semantic_search、regex_search、hybrid_search、index_status、reindex、health_check 等工具。
接入 Claude Code 后需按提示批准 ck-search 工具权限，否则工具调用会失败。
开发调试时需通过 cargo clippy --workspace --all-features --all-targets -- -D warnings 且不得有告警。

核心亮点

同时支持 BM25 关键词和向量语义检索，混合排序比单一 grep 更准
完全本地运行，代码和文档不上传，隐私友好
Rust 实现，索引和查询速度快，适合大仓库

不足之处

需要先建索引，首次使用比直接 grep 多一步
语义检索依赖嵌入模型，配置和效果调优有一定门槛

适用场景

在大型代码库中按意图查找实现，而非精确关键词
给本地编码助手提供代码检索工具，降低上下文成本
在文档或笔记库中做语义模糊搜索

替代项目

ripgrep、ast-grep、sourcegraph

上一篇：brave-search-skills

下一篇：Foxel

ck