判断:传统 grep / ripgrep 按「字」找代码——你记得变量名才找得到。ck 把搜索从「匹配关键字」升级成「理解含义」:搜 error handling 能捞出 try/catch、错误返回、异常处理,即使那些词一个都没出现。而且它完全本地运行,代码和查询都不出机器。
痛点:在大仓库里找一个功能,往往只记得「它是干 X 的」却想不起函数名;grep 对此无能为力,靠 IDE 全局搜索也常被同名词汇淹没。语义搜索能解决这个,但很多方案要把代码传上云、或笨重地跑大模型。ck 的赌注是:用本地嵌入模型做语义检索,既懂含义,又不把代码送出去。
它到底是什么
ck(seek)是一个本地优先的语义代码搜索工具,用 Rust 写,把 grep 的「按关键字」和嵌入向量的「按含义」合在一起。核心能力:语义搜索(搜 retry logic 能找到退避、断路器)、与 AI 编码工具集成的 MCP 服务器(对接 Claude Desktop / Cursor,提供 semantic_search / regex_search / hybrid_search 等工具)、交互式 TUI,以及把语义相关性和关键字过滤融合的混合搜索(Reciprocal Rank Fusion)。它完全兼容 grep 的 -i / -n / -A / -B / -l / -R 等标志,你已有的肌肉记忆照常工作。
一句话:grep 听得懂「这个词」,ck 听得懂「这件事」。
怎么用
装好就能搜,首次语义搜索会自动建索引。命令逐字取自 README:
cargo install ck-search

# 语义搜索:按含义找代码
ck --sem "error handling" src/

# 传统 grep 照常可用
ck -n "TODO" *.rs

# 语义 + 关键字融合
ck --hybrid "connection timeout" src/

# 启动 MCP 服务器,接 AI 编码客户端
ck --serve

# 交互式界面
ck --tui
在 Claude Code 里用 claude mcp add ck-search -s user -- ck --serve 即可接入;嵌入模型默认 bge-small,本地运行、只下载一次并缓存,可换 mxbai-xsmall / nomic-v1.5 / jina-code(代码专用)。索引存在项目内 .ck/(可随时删,或设 CK_INDEX_DIR 外置);npm 也有 @beaconbay/ck-search 全局包。
优点
· 本地优先、完全离线:嵌入模型在本地跑,无网络调用,代码和查询都不出机器——对隐私与 air-gapped 环境友好。
· Apache-2.0 / MIT 双许可,可商用、可改。
· grep 平替:同样的标志、同样的输出格式,团队零学习成本;还能 --jsonl 给脚本和 AI 代理流式消费。
· 增量索引聪明:块级缓存(blake3 哈希),典型改动只重嵌 80–90%,首次建索引约 2 分钟 / 100 万行,之后子 500ms 查询。
· AI 友好:MCP 直连主流编码客户端,让 Agent 按含义搜你的代码库。
缺点
· 语言覆盖有缺口:Python / JS·TS / Rust / Go / C / C++ / Ruby / Haskell / C# / Dart / Markdown 已支持,但 Java / PHP / Swift 仍在路线图,尚不能 AST 感知分块;未知扩展名按纯文本处理。
· 索引有体积成本:通常是源码的 1–3 倍(压缩约 2x),.ck/ 虽可删但占盘。
· ANN 索引已退役:ck-ann 于 2026-06 移除(零生产使用),现用暴力扫描,适合约 5 万块以内;真正的近邻索引待重新设计——超大仓库的语义查询会随块数线性变慢。
· 分发渠道受限:目前只有 cargo 与 npm,brew / apt 仍「开发中」。
· 语义质量受嵌入模型约束:默认 bge-small 用 400-token 块,跨块语义可能丢失;想更准要换更大模型、更吃算力。GPU 加速暂无(有用户问过,当前走 ONNX CPU)。
· 已知小坑:MCP 的 reindex 工具会跳过 .ckignore 创建(issue #191);裸名操作数会从 cwd 触发 **/ 递归遍历(issue #186),行为未必符合直觉。
最终能达到什么效果
把它当「会读心」的 grep:在陌生大仓库里搜 the code that handles auth 直接定位登录、凭证、鉴权逻辑;接进 Claude Code / Cursor 后,Agent 不再只靠文件名和符号,而是按「这段代码在干嘛」去检索你的代码库。它是 AI 辅助开发时代里一个轻量、本地、可审计的代码检索层。
适合谁 / 不适合谁 / 坑
适合谁:长期在别人或大型代码库里翻找功能、用 Claude Code / Cursor 等 Agent 编码、又在意代码不外传的人;做私有 / 离线环境检索的人。

不适合谁:主要写 Java / PHP / Swift 且依赖 AST 分块的人(暂未支持);想要开箱即用的 GUI 全家桶、或 brew/apt 一键装的人(渠道未齐);追求超大仓库亚秒语义查询、愿上向量数据库的人(当前暴力扫描有上限)。

几个坑:先 cargo install ck-search;首次语义搜索会建索引,给它一两分钟;用 CK_INDEX_DIR 把索引移出源码树;换 jina-code 这类代码专用模型质量更好;MCP 接入后记得 claude mcp list 验证。
下期预告:承接「本地优先」主线,下期做「代码检索三件套」横向对比——ck(语义 grep)/ 自托管向量库 + 代码分块 / 传统 ripgrep 管线,讲清各自适用边界与选型。
本文安装与命令示例均取自项目 README;限制项综合 README 与 issues(#191 / #186 / #77 等)。项目采用 Apache-2.0 / MIT 双许可。地址 github.com/BeaconBay/ck。