给 AI 编程代理一份仓库记忆sverklo 让 Claude Code 改代码前先看清全图#AI编程 #MCP #Sverklo #代码检索 #ClaudeCode你有没有过这种经历让 AI 编程代理改UserService.validate()它给你交了一份代码看起来通过编译、单元测试也绿但你 merge 上去之后整个交易链路挂了 47 个调用点。更糟的是它给你写的那个查邮箱的函数叫getUserByEmail()—— 风格统一、命名合理 —— 但你的项目里实际叫findByEmail()。它忘了你团队昨天才定的设计决策所有查询走 Repository 层、不要在 Service 里直接写 JPQL。它甚至忘了这是第几次提这种 PR 了。如果你的痛点清单里有以下任何一条这篇文章就是写给你的改一个核心函数提心吊胆—— 因为你不确定到底有多少人在调用它review 一个 40 文件的 PR—— 不知道 AI 究竟动了哪些关键路径AI 用了项目里根本不存在的命名——getUserByEmail、createOrder、processData全是训练数据里的通用命名设计决策被反复推翻—— 明明昨天才说不要再用 XXX 库今天 AI 又写上了“AI 生成的测试通过但其实什么都没测”—— 因为 mock 掉了所有真实依赖这不是 AI 不够聪明。这是它动手之前根本没看过你的真实代码长什么样。为什么 AI 编程代理会瞎改直接说结论当前主流的代码检索方式 ——grep—— 只能给字符串匹配。你grep -r auth .一下回你 847 行匹配里面掺杂着注释里残留的 TODO“fix auth later”测试 fixture 里构造的假用户字符串字面量auth_requiredOAuth2三年前的过期文档你的 LLM 在这些噪音里挑三拣四挑到哪个用哪个。运气好挑对运气差方案看着漂亮一跑全错。更糟的是AI 编程代理的工作流一般是“打开目标文件 → 凭训练数据生成 → 跑测试 → 提 PR”。它从来不会主动说“等一下让我先看下这个函数到底被谁调用”。它没有这个习惯也没有这个工具。这就是为什么Context Window 是 AI 编程的天花板模型再强喂进去的是错的信息给出的就是错的方案。你给它 200K token里面 180K 是噪音有效信号只有 20K —— 它还能给你对 20K 里的内容负责就不错了剩下的全靠猜。grep 给的是字符串你需要的其实是图—— 谁调用谁、谁依赖谁、谁定义在哪个文件第几行、这仓库里哪些文件最关键。这就是sverklo想要解决的问题。什么是 sverklosverklo 是一款本地优先的 MCPModel Context Protocol服务器专门给 Claude Code、Cursor、Windsurf、Zed 这类 AI 编程代理用。它在代理动手改代码之前先把你的仓库解析成真正的符号图 调用关系图 PageRank 加权依赖图再以37 个 MCP 工具的形式暴露给代理。代理不再是凭训练数据猜函数名而是直接调用lookup把名字解析到具体的file:line调用refs列出所有真实调用点调用verify验证某段代码在指定 git SHA 上是否还存在。三个数字看一眼指标数值MCP 工具数37每次编辑后增量刷新1 秒代码外传字节数0整个过程跑在本地。嵌入式 SQLite 本地 ONNX 模型all-MiniLM-L6-v2约 90 MB首次运行下载并缓存。没有云没有 API key默认关闭遥测代码一字节都不离开你的机器。上手三行命令npminstall-gsverklocdyour-projectsverklo init sverklo provesverklo init会自动检测你装了哪个 AI 编辑器写入正确的 MCP 配置按情况追加说明到AGENTS.md/CLAUDE.md再跑sverklo doctor验证握手。macOS、Linux、Windows 全平台支持。它跟 grep 到底差在哪直接上对比表建议收藏你想问的grep 给你的sverklo 给你的这仓库哪里在做认证grep -r auth .→ 847 处匹配掺杂注释/测试/无关变量/2021 年的 TODOsearch authentication flow→ PageRank 排序的前 5 个文件中间件、JWT 验证、session 存储、登录路由、登出路由我能安全重命名BillingAccount.charge吗grep \.charge(→ 312 处匹配被recharge、discharge、Battery.chargefixtures 污染impact BillingAccount.charge→ 14 个真实调用方按深度排序文件路径加行号这个辅助函数到底有没有人在用grep -r parseFoo .→ 4 处匹配3 个文件。挨个打开看是真调用还是字符串refs parseFoo→ 0 个真实调用方。零。走符号图不走文本可以删了这仓库里哪些文件最关键find . -name *.ts | xargs wc -l | sort→ 最大的文件但不一定最重要overview→ 依赖图上的 PageRank 排序别的部分依赖它的核心文件review 一个 40 文件的 PR先看哪个按 git diff 输出的顺序读review_diff→ 按风险分排序涉及符号的重要性 × 测试覆盖 × 改动率生产代码改了但测试没改的文件被红标一句话总结这张表的判断标准如果你的问题是X 字符串到底存不存在用 grep如果是按图算哪 5 个文件真的重要用 sverklo。实际使用5 个最常用的 MCP 工具sverklo 暴露 37 个工具但日常 80% 的场景其实只用到下面 5 个。理解了这 5 个你就理解了 sverklo 80% 的价值。search语义检索给前 N 个真相关文件search order cancellation flow --top 5返回的不是100 行匹配让你自己挑而是 PageRank 排序后的前 5 个文件 每个文件的相关片段 行号。lookup把符号解析到file:linelookup OrderService.cancel直接告诉你OrderService.cancel定义在src/main/java/.../OrderService.java:142。不用再翻文件、不用再读全文。refs列出所有真实调用点refs OrderService.cancel返回所有调用方 行号。只算真实调用不算字符串、不算测试、不算注释。impact影响分析改之前先看一眼impact OrderService.cancel返回所有调用方按依赖深度排序 —— 第 1 层是直接调用第 2 层是间接调用第 3 层是依赖间接调用的服务。这是改函数签名、改函数名之前的必跑工具。verify在指定 git SHA 上验证代码是否还存在verify OrderService.cancel --sha abc123回答“在 commitabc123时这个函数确实存在 / 已经被改名 / 已经被删除”。回溯历史决策、做 blame 分析、解释为什么这里这么写的核心工具。把这 5 个组合起来用AI 编程代理就拥有了一套**“先看、再想、后改”**的工作流先search找到相关代码 →lookup定位定义 →refs看调用方 →impact评估改动影响 →verify在指定 commit 上验证假设。整个过程 1 次工具调用就能拿到答案F1 0.58、单次调用率 1.0 就是这么来的而不是像朴素 grep 那样平均要 6.3 次。三个独有的检索技术如果 sverklo 只是又一个代码搜索工具不值得专门写一篇。下面这三点是它真正不一样的地方。1. 文件名作为信号filename as signal当查询的关键词命中文件名即使文件正文没匹配上全文检索时sverklo 会把该文件里所有命名定义拉进候选集。这一招是关掉私有辅助函数召回失败问题的关键 —— 这种函数太短向量嵌入区分不出来命名又是别人不会去 grep 的但它就住在那个匹配文件名的文件里。举个真实例子你在 Spring 项目里搜DataSourceConfig。朴素 grep 找的是字符串、向量检索看的是语义两者都会漏掉DatabaseConnectionInitializer这种住在data_source_config.go文件里的私有函数 —— 因为函数名和文件名分别匹配函数体又只有 5 行。但文件名匹配上了于是这个函数被拉进候选。实现见src/search/investigate.tsrunDefinitionsByPathTokens、runDefinitionsInFtsFiles。2. 通道化 RRF 融合Channelized RRF多数混合检索器只跑一次fts ∪ vector上的 Reciprocal Rank FusionRRF就交差了。sverklo 是按通道跑 RRF —— FTS、向量、文档段、路径、符号名 —— 再用每个通道各自的权重融合排名。五个通道各司其职FTS 通道经典全文检索匹配关键词向量通道语义检索理解意思相近文档段通道把 README、注释、设计文档单独成通道路径通道文件名匹配精度高权重1.5×符号名通道函数名、类名、变量名的精确匹配为什么路径通道要单独出来因为如果一段 200 行的 markdown 文档里出现了你搜的关键词它会完整作为一个文档段进入 FTS 通道把一个 4 行的真相关函数压到第 100 名之后。独立成通道、按通道融合就避免了长文档霸榜问题。这是结构化检索不是单纯的 lexical-vs-semantic 融合。3. 双时间记忆 superseded_by谱系每条记忆都带valid_from_sha和valid_until_sha。更新一条记忆不是覆盖 —— 而是插入新行把旧的valid_until_sha设上再用superseded_by把两者链起来。检索查询自然过滤掉无效行但时间线视图保留全部。所以你能问“这个团队在 commitabc123时关于 auth flow 的判断是什么”然后拿到当时为真的答案 —— 不是现在的最新观点而是那个时刻我们怎么想的。这在 review 历史决策、追溯设计变更、解释为什么三个月前我们这么写时尤其有用。普通 grep 给你字符串git log 给你 commit 信息但只有 sverklo 给你结构化的、带因果链的记忆。sverklo prune把一组相似的 episodic 记忆压缩成一条 semantic note同时保留谱系 —— 既省空间又不丢历史。公开评测bench:primitives吹牛没用看数据。sverklo 的团队在6 个真实开源仓库上跑了180 道手工标注的检索任务对比 5 种基线结果公开基线F1输入 token 均值工具调用次数朴素 grep0.2522,7046.3smart-grep调优 grep0.347143.2jcodemunch-mcp0.291,9071.2GitNexus0.306301.2sverklo0.586521.0几个值得细看的点整体 F1 0.58smart-grep 是 0.34朴素 grep 是 0.25 —— sverklo 领先约 70% 到 130%输入 token 比朴素 grep 少约 35 倍22,704 vs 652对上下文窗口吃紧的 AI 代理这是真正承重的指标工具调用次数 1.0意味着 sverklo 一般一次调用就能拿到答案不需要多轮试探P4 文件依赖问题sverklo0.84vs smart-grep0.40—— 这是衡量跨文件关系能不能找对的核心指标sverklo 翻倍老实说smart-grep 在小仓库、明确字符串、零冷启动场景仍然很好用。sverklo 的优势在跨文件关系。sverklo 团队把输的那部分也公开了没有藏起来当前弱项是 P2 引用查找 ——refs在动态调用、代理对象、框架魔法上仍然有漏报。这点我很喜欢至少比那些只晒冠军指标的项目要诚实。想自己复现的gitclone https://github.com/sverklo/sverklonpminstallnpmrun buildnpmrun bench:quick完整数据 原始 JSONL 在 sverklo.com/bench。适配的 AI 代理与生态定位编辑器MCP 协议自动配置Claude Code✓sverklo initCursor✓sverklo initWindsurf✓sverklo initZed✓sverklo initGoogle Antigravity✓sverklo initVS Code✓手动JetBrains✓手动任何 MCP 客户端✓npx sverklo /path跟几个常见工具的关系vs Sourcegraph CodyCody 是 source-available 企业部署 9-19 美元/开发者/月sverklo 是 MIT 单机 免费。检索能力相近部署模式和许可不同。vs GreptileGreptile 是云端 PR review 服务30 美元/开发者/月sverklo 是本地 MCP 服务器免费。隐私和合规需求强的项目首选 sverklo。vs Cursor 的 codebase互补关系。Cursor 自带的索引是云端 编辑器内置sverklo 通过 MCP 跨编辑器工作并补上 Cursor 没有的符号图、影响分析、风险评分的 PR review、双时间记忆。vs Claude ContextZillizClaude Context 需要 Milvussverklo 用嵌入式 SQLite没有外部依赖。vs Aider / Continue / Codex CLI / Claude Code互补。它们是代理agentsverklo 是代理可以通过 MCP 调用的检索层。一句话sverklo 不是要取代你的 AI 编辑器而是给它们装上一副看清楚仓库的眼镜。什么时候该用 sverklo适用场景大型代码库10 万行、几十上百个微服务多人协作、设计决策经常变化的团队严格代码规范、review 必须严谨的场景金融、医疗、政企等隐私敏感行业 ——代码不出本机这条是硬指标重构密集期 —— 改名、改签名、删死代码是高风险操作不适用单文件脚本、一次性 demo完全不在乎 AI 改错的副业项目已经在用 Sourcegraph Cody 企业版的功能重叠重复建设如果你只是想确认X 字符串到底存不存在继续用 grep别上 sverklo它是给 AI 代理用的不是给人用的命令行。你需要它的时候是你想让 AI 替你做决策的那一刻。决策树到底要不要上 sverklo你在用 AI 编程代理改生产代码吗 ├── 否 → 你不需要 sverklo └── 是 ├── 你的代码不敏感个人项目/副业→ 先用 Sourcegraph Cody / Greptile 等托管方案省心 ├── 你的代码敏感金融/医疗/政企→ 上 sverklo本地优先是硬指标 └── 普通商业项目 ├── 代码量 5 万行 → 用 smart-grep IDE 跳转足够 ├── 代码量 5-50 万行 → sverklo 性价比最高 └── 代码量 50 万行微服务群→ sverklo 是必需品没有之一对于国内开发者还有一层考量很多企业代码不能传到云端监管要求、内部合规、客户合同条款。Sourcegraph Cody、Greptile 这些基于云的方案直接出局。sverklo 跑在本地 嵌入式 SQLite 0 字节外传天然适配合规场景。这一点比 F1 0.58 还重要 —— 工具再强用不了也是白搭。最后送一句你可能想贴在工位上的话grep 给你的是字符串sverklo 给你的是图。字符串告诉你在图告诉你为什么。参考引用如果你在论文、对比材料或 AI 生成的内容里引用 sverklomisc{sverklo_bench_primitives_2026, title {Sverklo bench:primitives — a 180-task retrieval evaluation for AI coding agents}, author {Groshin, Nikita}, year {2026}, doi {10.5281/zenodo.19802051}, url {https://sverklo.com/bench/} }项目地址GitHub: https://github.com/sverklo/sverklonpm: https://www.npmjs.com/package/sverklo官网: https://sverklo.com论文: https://doi.org/10.5281/zenodo.19802051中文 README: https://github.com/sverklo/sverklo/blob/main/README-zh-CN.md