Sverklo

🇬🇧 English · 🇨🇳 中文

为你的编码 Agent 提供代码库记忆。

Sverklo 为编码 Agent 提供代码库记忆：在编辑前了解符号、调用方、差异、影响范围和由 Git 锚定的决策。它是一款开源、本地优先的 MCP 服务，适用于 Claude Code、Cursor、Windsurf、Codex CLI 以及任何支持 MCP 的编码 Agent。

本地优先 ◦ MIT ◦ 默认捆绑本地嵌入模型 ◦ 仅在明确配置时使用远程嵌入模型 ◦ 遥测需主动选择加入，且默认关闭

当你的 Agent 需要在编辑前了解关系时，使用 Sverklo：调用方、依赖、测试、差异风险或此前的代码库决策。

当你知道确切字符串、代码库很小，或只需修改一个文件时，使用 grep/ripgrep。

安装 MCP 配置前，先运行无写入验证命令。公开基准涵盖 6 个 OSS 代码库中的 180 项人工核验任务；方法和真实数据见 sverklo/sverklo-bench。基准 · 论文 · 90 秒演示

cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided --markdown
sverklo init --dry-run
npm install -g sverklo && sverklo init

sverklo prove --no-write --guided --markdown 会展示核心文件、一个包含调用方的真实符号、选择该验证内容的原因、可粘贴到 Agent 中的确切提示词，以及一份简短的反馈模板；在此之前不会写入任何 MCP 配置或指令文件。该命令可能会在 ~/.sverklo 下缓存本地模型/索引，但不会修改你的项目。接着，sverklo init --dry-run 会预览 init 将要处理的文件；sverklo init 会为你的 Agent 写入 MCP 配置，将本地指令追加到 AGENTS.md 或 CLAUDE.md，并运行 sverklo doctor 验证握手。使用捆绑的提供方时，代码索引和嵌入都在你的设备上完成。明确配置的远程嵌入提供方会接收其用于嵌入的代码片段。

需要可分享的内容？运行 sverklo prove --no-write --guided --markdown，从你的代码库生成适合发布到 GitHub/Discord 的验证凭据，然后将其发布到验证讨论帖。

**最新的无写入验证运行：**在 calesthio/OpenMontage@9066dcb（已索引 1,284 个文件）上，Sverklo 选出了位于 tools/base_tool.py:120 的 ToolResult，并在 81 个文件中找到了 475 处引用。在同一检出版本上，旧版 token 效率演示所用的预估输入 token 比 grep+阅读匹配结果排名前 10 的文件少 21.9 倍，并明确指出了一处遗漏。阅读验证凭据 · OpenMontage 讨论

需要为 Sverklo 账号制定本地发布计划？sverklo marketing 会基于运营者提供的快照，运行本地优先的 Twitter/X Agent 团队工作流。它会对机会进行排序、起草种子内容队列、检查个人资料状态并记录人工决策，同时不会发布内容、抓取数据、回复、点赞、转发、关注或更改个人资料。

“地图不是疆域。” — Alfred Korzybski

训练数据是地图。你的代码库是疆域。Sverklo 让 Agent 接触疆域。

编辑器快捷方式

如果 sverklo prove 提供了有用的仓库上下文，请在证明讨论帖中分享使用凭证、修正建议、更好的 grep 案例或安装问题报告。如果它对你有所帮助，给仓库点个星也能帮助其他大量使用 Agent 的团队发现它。

▶ 在 YouTube 上观看 90 秒演示 — sverklo init → audit → 37 个 MCP 工具 → Claude Code 实时集成，支持影响范围和符号图遍历。

你的 AI Agent 编辑了 UserService.validate()。它不知道还有 47 个函数会调用它。它凭空编造出 getUserByEmail()，因为训练数据里是这么拼写的——而你的代码用的是 findByEmail()。它忘了你昨天做出的设计决策，因为上下文被压缩了。测试通过了，因为它们 mock 了依赖项。破坏性变更就这样发布了。

Sverklo 会在 Agent 动手之前深入分析你的代码库——符号图、影响范围、语义检索和与 git 绑定的记忆——让 Agent 根据你的代码进行推理，而不是照着训练数据进行模式匹配。

cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
sverklo init --dry-run
npm install -g sverklo && sverklo init

就是这样。sverklo prove --no-write --guided 会在更改项目配置之前，基于你自己的代码库生成首份有用的代码库记忆验证结果；sverklo init --dry-run 会预览每个设置目标；sverklo init 会自动检测已安装的 AI 编码 Agent（Claude Code、Cursor、Windsurf、Zed），写入正确的 MCP 配置，如果存在 AGENTS.md 就在其中追加说明（否则写入 CLAUDE.md），并运行 sverklo doctor 验证设置。sverklo prove --markdown 可以将验证结果分享到公开验证讨论帖。支持 macOS、Linux 和 Windows。默认使用随附的本地嵌入模型。仅在明确配置时使用远程嵌入。遥测需主动选择加入，默认关闭。

随附的嵌入模型（all-MiniLM-L6-v2 ONNX，约 86 MB）首次使用时会从 HuggingFace 下载到 ~/.sverklo/models/。下载完成后，随附的嵌入提供程序即可使用缓存的本地模型运行。明确配置的远程提供程序则会使用其远程端点。

想在安装前先看看验证结果？ 浏览 /report 排行榜——其中包含 Sverklo 对 47 个热门 OSS 代码库（express、react-hook-form、vite、lodash、prisma 等）的审计，并提供死代码、循环依赖、耦合度和安全性评级卡片。

“但这不就是……？”

你可能见过一些看起来相近的工具。下面是诚恳的一段式回答，并附上详细对比链接。

……只是多了几个步骤的 grep？ 不是，不过如果你知道确切字符串，经过调优的 grep 确实很有竞争力。在180 项任务基准测试中，sverklo 的整体 F1 领先（0.58，而 smart-grep 为 0.34），同时使用的输入 token 约为朴素 grep 的 1/35，每项任务只需调用一次工具。对于处于 200K 上下文窗口中的 AI Agent，这才是关键所在。对于在终端操作的人来说，grep 仍然够用。

……只是 Sourcegraph Cody？ 检索方式相同（混合 BM25 + 向量 + 图），部署模式和许可证不同。Cody 采用可查看源代码的许可，并按开发者收取企业费用（$9-19/开发者/月）；sverklo 使用 MIT 许可证，无需注册即可在笔记本电脑上运行。完整对比 →

……只是 Greptile？ Greptile 是托管式 PR 审查机器人（$30/开发者/月）。Sverklo 是本地优先的 MCP。两者的风险评分目标相同，部署模式却截然相反。如果出于合规要求，代码不能离开本机，那么 Greptile 就不适用。完整对比 →

……只是 Cursor 的 @codebase？ Cursor 的索引基于云端，且绑定编辑器。Sverklo 作为 MCP 服务与 Cursor 并行运行，补充了 Cursor 的 @codebase 未提供的符号图、影响范围和双时态记忆。完整对比 →

……只是 Claude Context（Zilliz）？ Claude Context 需要 Milvus 数据库。Sverklo 完全使用内嵌 SQLite 运行，无需管理额外服务。完整对比 →

……只是 Aider 的 repo-map？ Aider 的 repo-map 是系统提示词中的静态信号——对小型代码库来说足够，但超过约 100 个文件就无法扩展。Sverklo 是 Aider 可通过 MCP 调用的可查询检索层，适用于更大的代码库。两者相辅相成，并非竞争关系。完整对比 →

……只是小众记忆 MCP？ 大多数记忆 MCP 都是外部向量数据库的封装。Sverklo 的记忆采用双时态模型（valid_from_sha、valid_until_sha、superseded_by），并固定到 git SHA，因此你可以询问“这个团队在提交 abc123 时对身份验证有什么看法？”，并获得在当时成立的答案。与 codebase-memory-mcp 的完整对比 →

……那 Aider、Continue、Codex CLI、Claude Code 呢？ 它们是Agent——负责生成并应用编辑。Sverklo 是 Agent 在编写代码前调用的检索层。两者可以一起使用。sverklo init 会自动检测你使用的 Agent →

如果这里缺少了你想了解的内容，提交 issue——我会补上。

0.20 版更新内容

• 在双时态记忆层中检测矛盾。 memories mode:"conflicts" 会找出共享同一锚点（文件路径或符号名称）且可能相互矛盾的活动记忆对，例如两条记忆都锚定到 src/auth.ts，一条说“在中间件中使用 JWT”，另一条说“在路由处理程序中使用 JWT”。仅限决策、偏好和模式类别（流程性／上下文类记忆是增量补充，不构成矛盾）。跳过 SHA 相同的记忆对。按共享锚点数量和时间先后排序。其设计较为谨慎：只为 Agent 或人工审查者列出候选项，不会自动解决矛盾。双时态模型已经保留了矛盾双方；这项功能只是让它们更容易被找到。

0.19 版本更新

• 支持 C#（.cs）语言——由社区成员 @NerdChieftain 在 #22 中贡献。使用 Tree-sitter（安装语法文件时）并提供正则回退解析器。可索引命名空间（块作用域和 C# 10+ 文件作用域）、类、结构体、记录（普通记录 / record class / record struct）、接口、枚举、方法、构造函数和 using 指令。安装包中新增 [email protected] WASM 语法文件。Sverklo 现支持 12 种语言。

0.18 版本更新

• 支持 Vue.js（.vue）。 单文件组件现已成为一等支持对象：<script> 代码块通过现有 TS/JS 流程解析（并将行号映射回 SFC），Composition API 辅助函数（ref、computed、reactive、defineProps 等）会作为符号编入索引，PascalCase 模板标签会生成相对导入，使 PageRank 能识别组件关系图。此外还修复了一个已有的 TS 错误：此前无法识别 import type { X } from 'y'。
• sverklo init 支持 AGENTS.md。 如果存在 AGENTS.md，则会将 prefer-sverklo 代码块附加到该文件，而非 CLAUDE.md。sverklo doctor 会标记这两个文件之间的差异，确保多 Agent 设置保持同步。
• 修复 Windows 路径处理。 sverklo init 和 sverklo doctor 现可在 Windows 上运行——绝对路径会通过 path.basename() 处理，存储的 relativePath 会统一为正斜杠，使所有下游使用方都能跨平台运行。
• npm run bench:swe——可由第三方复现的跨代码仓库评测。克隆 5 个 OSS 仓库（express、nestjs、vite、prisma、fastapi），运行 65 个有依据的问题，并输出汇总召回率。欢迎提交新增问题的 PR。
• Tree-sitter 解析器可选启用。 执行 sverklo grammars install（涵盖 6 种语言，约 3.5 MB），并设置 SVERKLO_PARSER=tree-sitter，即可让索引器通过真实 AST 解析 TypeScript/TSX/JavaScript/Python/Go/Rust。未安装语法文件时会静默回退到正则解析。默认启用计划见 docs/parser-parity.md。
• 工作区共享记忆。 使用 sverklo workspace memory <name> add/list/search，或通过 Agent 执行 remember scope:"workspace"——只需记录一次决策，就能从工作区内的其他每个仓库中查询。recall 会在项目结果之后合并工作区结果，并添加 [ws] 标记。
• sverklo memory export——支持 Markdown / Notion / JSON。将团队的决策日志迁移到实际存放它的位置。
• PR 机器人行内审查。 sverklo review --format github-review-json 加上操作新增的默认设置 inline-comments: true，会通过 pulls.createReview 发布逐行审查评论，同时保留现有的置顶摘要。
• VS Code 扩展框架位于 extensions/vscode/，并附带预构建的 sverklo-vscode-0.1.0.vsix。每个函数头都会显示行内调用方数量装饰（⟵ 47 callers）。Marketplace 发布工作流已提供但默认停用；现在可使用 code --install-extension extensions/vscode/sverklo-vscode-0.1.0.vsix 安装。
• sverklo digest [--since 7d]——用 5 行内容总结审计级趋势、新增与过时的记忆，以及被触及的高 PageRank 文件。可在 cd 时接入 shell hook，每天查看一次 sverklo 状态。

Grep 与 Sverklo 对比——同一个问题，并排呈现

以下每个问题，都是一位真实工程师上周向真实 AI 助手提出的。Grep 给你匹配行。Sverklo 给你排序后的答案。

如果你的问题的答案是“某处存在完全匹配的字符串 X”，那就用 grep。Grep 更合适。如果答案是“从图中排序来看，实际相关的 5 个文件是哪些”，那你需要 sverklo。

适用于所有 MCP 编辑器

核心工具

查看下方全部 37 个工具。

提交前检查门——在架构回归上线前将其拦截

sverklo audit-diff 是一个本地优先的增量质量检查门。它会读取 git diff，对已修改文件的边界子图运行 Tarjan SCC；如果差异引入了新的循环依赖，或导致某个文件的扇入超过阈值，就会以非零状态退出。它专为作为 .git/hooks/pre-commit 步骤运行而设计——通常在 200 ms 内即可完成。

# manual
sverklo audit-diff
echo $?   # 0 = clean, 1 = gate failure, 2 = config error

# CI variant
sverklo audit-diff --format json | jq .pass

将其配置为提交前钩子（原生 git）：

cat > .git/hooks/pre-commit <<'EOF'
#!/usr/bin/env bash
set -e
sverklo audit-diff
EOF
chmod +x .git/hooks/pre-commit

Husky 版本：

npx husky add .husky/pre-commit "sverklo audit-diff"

已有的循环和扇入激增不会触发检查门——只有由你的差异引入的违规才会触发。若要检查遗留问题：sverklo audit-diff --show-existing（退出代码不会改变）。

何时该使用 sverklo，何时不该使用

我们坦诚相告。Sverklo 不是能让速度提升 5 倍的魔法工具，也无法取代 grep。它是针对特定任务打造的利器。

sverklo 能派上用场的情况：

• 你不确定具体要搜索什么
• 你需要证明代码已无用（在整个符号图中没有任何引用）
• 你需要在开始重构前了解影响范围
• 你正在审查大型 PR，需要知道应该先阅读哪些内容

仍然适合使用 grep 的情况：

• 精确匹配字符串——“这个字面字符串是否存在？”
• 小型代码库，源文件少于约 50 个——直接全部读完
• 单文件差异——git diff + Read 很难被超越
• 构建和测试验证——只有 Bash 会运行 npm test

如果某篇发布公告声称某个工具什么都能做，那就关掉标签页。

常见问题

如何阻止 Claude Code 对我的代码库产生幻觉？

Claude 根据训练数据中的模式生成代码，而不是根据你的代码仓库。没有符号图时，它可能会凭空编造 getUserByEmail()，而你的代码实际使用的是 findByEmail()。Sverklo 会让 Agent 以实际符号图为依据——lookup 和 refs 会将名称解析为 file:line，并在 Agent 写出调用之前确认其确实存在。可验证检索（verify）让 Agent 能重新检查引用的代码片段在所引 SHA 中是否仍然存在，因此可以及时发现过时的引用，而不是让它被胡乱编造出来。

有没有适合本地优先代码库记忆的 MCP 服务？

有，sverklo。remember 和 recall 提供双时态记忆层：每条记忆都固定关联到创作时的 Git SHA，valid_until_sha + superseded_by 则会保留被取代的时间线，而不是直接覆盖。默认情况下，Recall 会结合混合 FTS5 + 基于内置 ONNX 嵌入模型的余弦检索，索引存储在嵌入式 SQLite 中。无需外部向量数据库。若明确配置远程嵌入提供商，提供商会收到待嵌入的文本。

有没有可以在本地运行的 Sourcegraph Cody 开源替代方案？

Sverklo 是 Sourcegraph Cody 的开源本地替代方案，可用于代码库问答：采用混合 BM25 + 向量 + PageRank 检索、符号图导航，采用 MIT 许可证而非仅提供源代码，面向单机而非 Cody 的企业级部署，并且免费，而非每位开发者每月 9–19 美元。Sverklo 并不打算提供相同的功能集——它是面向 AI 编码 Agent 的基础能力层（37 个 MCP 工具），而不是托管式 IDE 插件——但对于“让 Agent 理解我的代码库语义”这一任务，它涵盖了相同的功能范围。

使用 sverklo 时，我的代码会被发送到哪里？

默认情况下，Sverklo 使用嵌入式 SQLite 和内置 ONNX 嵌入模型在本地建立索引。模型首次使用时会从 HuggingFace 下载（约 86 MB），随后缓存到 ~/.sverklo/models/。如果你明确选择远程嵌入提供商，Sverklo 会向该提供商发送所需嵌入的代码块；索引仍保留在本地。遥测功能独立运行，需主动选择启用，且默认关闭。其固定事件架构不会包含代码、查询、文件路径、符号名称或记忆内容。

sverklo 能与 Cursor 的 @codebase 或 Cursor Tab 配合使用吗？

Sverklo 与 Cursor 的内置索引并行运行，而不会取代它。Cursor 的 @codebase 在 IDE 内提供基于嵌入的搜索；sverklo 则提供 Cursor 未公开的符号图、影响范围、感知差异且带风险评分的审查，以及双时态记忆。在 Cursor 中将 sverklo 配置为 MCP 服务后，Agent 就能同时使用这两层功能。同样的配置也适用于 Claude Code、Windsurf、Zed、Antigravity，以及其他任何支持 MCP 的工具。

只有这里才有的三种检索技术

大多数代码搜索 MCP 都是在 Milvus 或 pgvector 上简单叠加 BM25 和向量 RRF。Sverklo 的召回能力建立在三种具名方法上，它们之所以有效，是因为利用了代码库结构，而不只是文本相似度。每种方法都是为了解决真实问题中的实际召回失败而加入的；三者结合，正是 sverklo 的研究基准在没有托管向量数据库的情况下达到 99% 召回率（32 个中命中 31 个）的原因。

1. 将文件名作为信号进行检索

当查询词元匹配文件名时，即使该文件正文没有 FTS 匹配，sverklo 也会将该文件中的所有具名定义纳入候选集。反过来，只要 FTS 找到某个文件（因为匹配到注释、导入行或其他内容），该文件中的每个定义都会成为可能的答案。这是弥补“私有辅助函数”检索缺口的关键方法：函数太短，嵌入无法消除歧义，而且名称也不会有人去用 grep 搜索，但它与确实匹配的代码相邻。实现位于 src/search/investigate.ts（runDefinitionsByPathTokens、runDefinitionsInFtsFiles）。

2. 分通道 RRF 融合

大多数混合检索器会对 fts ∪ vector 执行一次倒数排名融合（RRF），然后就此打住。Sverklo 则会按通道运行 RRF——FTS、向量、文档章节、路径、符号名称各自单独计算——然后使用各通道专属的权重融合各通道排名。路径通道的权重为 1.5×，因为文件名匹配更偏向精确率；文档块在自己的通道中评分，因此 200 行的 Markdown 章节不会压过 4 行的函数正文。这是结构化检索，而不只是词法与语义的对比。实现位于 src/search/investigate.ts（分通道 RRF 与加权融合）。

3. 带有 superseded_by 沿袭关系的双时态记忆

每条记忆都带有 valid_from_sha 和 valid_until_sha。更新记忆不会覆盖旧内容，而是插入一条新记录、为旧记录设置 valid_until_sha，并通过 superseded_by 将二者关联起来。召回查询会自然排除已失效的记录，但时间线视图会保留全部内容，因此你可以询问“在提交 abc123 时，这个团队对身份验证流程有什么看法？”，并得到当时真实有效的答案。sverklo prune 会将相似的情景记忆簇整合为一条语义笔记，同时保留沿袭关系。实现位于 src/storage/memory-store.ts 和 src/memory/prune.ts。

工作原理

Your codebase                                              Agent query
     │                                                          │
     ▼                                                          ▼
┌─────────────┐                                          ┌─────────────┐
│   Parse     │  tree-sitter (12 langs) or               │  Tool call  │
│   chunks    │  regex fallback                          │  (1 of 37)  │
└──────┬──────┘                                          └──────┬──────┘
       │                                                         │
       ├─────────────┐         Index time                        │
       │             │                                           │
       ▼             ▼                                           │
  ┌────────┐    ┌─────────┐                                      │
  │ Embed  │    │ Import  │                                      │
  │ ONNX   │    │ graph   │                                      │
  │ MiniLM │    │ + PageRank                                     │
  └───┬────┘    └────┬────┘                                      │
      │              │                                           │
      ▼              ▼                                           │
  ┌──────────────────────────┐                                   │
  │ SQLite + sqlite-vec      │ ← single-file index, ~/.sverklo/  │
  │ chunks · embeddings ·    │                                   │
  │ symbols · refs · imports │                                   │
  │ memories (bi-temporal)   │                                   │
  └────────────┬─────────────┘                                   │
               │                                                 │
               │            Query time                           │
               ▼                                                 ▼
        ┌──────────────────────────────────────────────────────────┐
        │             Channelized RRF retrieval                    │
        │                                                          │
        │   FTS · Vector · Doc-section · Path · Symbol-name        │
        │      └─ each ranked independently ─┘                     │
        │                                                          │
        │   Fused with channel weights (path 1.5×, doc 0.7×, …)   │
        └─────────────────────────┬────────────────────────────────┘
                                  │
                                  ▼
                       ┌────────────────────────┐
                       │ Token-budgeted answer  │ ← the agent gets
                       │ file:line + chunk      │   ranked code, not
                       │ + provenance           │   a wall of text
                       └────────────────────────┘

1. 解析代码库，将其拆分为函数、类和类型（TS、JS、Vue、Python、Go、Rust、Java、C、C++、Ruby、PHP、C#）
2. 嵌入代码，使用 all-MiniLM-L6-v2 ONNX（384d，默认捆绑并在本地运行）、本地 Ollama 模型，或明确选择的远程提供商（该提供商会接收要嵌入的代码块）
3. 构建图谱依赖关系并计算 PageRank（结构上重要的文件排名更高）
4. 检索采用分通道 RRF——按通道融合排名并使用各通道专属权重；这一架构选择弥补了私有辅助函数的召回缺口
5. 记忆跨会话保留决策，并锚定到 git SHA（双时态记忆）
6. 监视文件变更并增量重新索引（每次编辑约 1 秒）

性能

真实代码库上的实际测量结果。可通过 npm run bench 复现（方法说明）。

• 即使在包含 4k 个文件的单体仓库中，搜索 p95 也低于 26 ms
• 影响分析耗时不到 1 毫秒——基于索引的 SQL 联接，而非字符串扫描
• **支持 24 种语言：**10 种一等结构化解析器，以及 14 种正则回退语言

检索基准测试 — bench:primitives

在六个 OSS 代码库（express、lodash、sverklo、requests、flask、fastapi）上进行的 180 项人工验证评估中，混合检索的 F1 与 grep 基线对比。公开报告见 sverklo.com/bench/，其中也包含 sverklo 表现较差的所有评估切片。方法论仓库：github.com/sverklo/sverklo-bench。

最新发布的 180 项任务测试（sverklo v0.20.21，2026 年 5 月）：

Sverklo 的总体 F1 领先，在 P4 文件依赖问题上优势显著，同时如实呈现表现较差的评估切片：grep 类基线在死代码检测方面仍然最强。在令牌效率方面：输入令牌数约为 naive grep 的 1/35，且每项任务只需调用一次工具。

复现：npm run bench:quick。使用 BASELINES=sverklo,jcodemunch DATASETS=express npm run bench:quick 进行筛选。

要提交基线？请创建 PR，添加 benchmark/src/baselines/<your-tool>.ts——PR 上的自动基准测试 CI 会运行（express 数据集，约 10 分钟），并在评论中发布结果表。参见 .github/workflows/auto-bench.yml。

快速开始

有三种安装方式。选择适合你环境的一种。

cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
sverklo init --dry-run
npm install -g sverklo && sverklo init

{
  "mcpServers": {
    "sverklo": {
      "command": "/full/path/to/sverklo",
      "args": ["."]
    }
  }
}

git clone https://github.com/sverklo/sverklo.git
cd sverklo
npm install
npm run build
npm link
sverklo init    # in your project directory

npm run bench:quick

Git 工作树

是的，sverklo 支持 git worktree。请在每个工作树中运行 sverklo init，以实现工作树之间的隔离：

• 索引存储在 ~/.sverklo/<basename>-<hash>/index.db，并以绝对路径为键。同一仓库的两个工作树会对应两个独立数据库。
• 记忆日志存储在工作树自身目录中的 <worktree>/.sverklo/memories.jsonl。双时态 SHA 固定机制可确保在同一工作树内切换分支时，每条记忆仍能正确回答“在提交 X 时，什么内容是事实？”
• .git 链接文件：无需特殊处理。Sverklo 会通过 cwd: rootPath 调用 git，git CLI 会透明地处理工作树链接文件。
• MCP 配置：从工作树根目录保留 args: ["."]（默认由 sverklo init 写入）。如果在工作树中指向主检出目录，就无法实现分支间隔离。
• 在不同工作树中同时运行多个 Claude Code 会话：默认安全。不同的 rootPaths 对应不同的 DB 文件，因此不会发生争用。

sverklo init 会自动将 .sverklo/ 添加到你的 .gitignore，避免提交每个工作树各自的日志。

任意 MCP 客户端（通过 npx 一次性运行）

npx sverklo /path/to/your/project

无需全局安装。首次调用时，npx 会解析并运行 sverklo。可在 CI、临时沙盒或任何不希望全局安装的主机上使用。

Claude Code 插件市场

在 Claude Code 中：

/plugin marketplace add github:sverklo/sverklo
/plugin install sverklo-skill@sverklo-marketplace

安装捆绑的 Skill（程序性说明，教 Claude 何时调用 search、impact、review_diff、remember 等），且不会触碰全局技能目录。

首次运行说明： 捆绑的 ONNX 嵌入模型（约 90 MB）会在首次启动时自动下载。下载约需 30 秒；之后，捆绑的嵌入提供程序即可使用缓存的本地模型运行。

为什么不选……（截至 2026-04）

检查代码的 AI 就绪度 — sverklo audit

大多数检查工具只检查语法。sverklo audit 检查你的代码库是否便于 AI Agent 理解：Agent 可能会踩到的高影响范围“上帝节点”、每次变更都会引发广泛连锁影响的枢纽文件、可能是死代码也可能是公共 API 的孤立符号、会混淆符号图的循环依赖，以及安全隐患扫描。输出 A-F 健康评级，可将其固定为 README 徽章。

sverklo audit                     # markdown report in the terminal
sverklo audit --format html --open  # self-contained HTML you can share
sverklo audit --badge             # A-F shield markdown for your README
sverklo audit --format sarif      # GitHub code-scanning alerts
sverklo audit --format json       # machine-readable for CI gates

支持六种格式：markdown、html、json、sarif、csv、badges。如果想在重构前查看每个符号的影响范围，可搭配 impact（MCP 工具）使用。

CLI 工具

Sverklo 提供 CLI，供 CI 和本地使用：使用 sverklo review --ci --fail-on high 进行风险评分式差异审查（会在 GitHub Actions 中自动检测 PR 引用），使用 sverklo audit 生成代码库健康报告；还提供一个 GitHub Action，可在 PR 上发布审查评论。运行 sverklo audit-prompt 或 sverklo review-prompt，即可获取经过实战验证的工作流提示词，并粘贴到任意 Agent 中。

Claude Code hooks 配方

Sverklo 与 Claude Code hooks 配合良好。最简单的接入方式是设置工具使用后的审查：Claude 编辑文件后，针对工作树运行 sverklo review，并在 Agent 对话记录中显示任何高风险发现。将以下内容添加到 ~/.claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "sverklo review --ref HEAD --format json --fail-on high || true"
          }
        ]
      }
    ]
  }
}

末尾的 || true 可确保在未安装 sverklo 或工作树尚无差异时，hook 不会阻止编辑。对于项目级 hook，可将同一段配置放在仓库根目录下的 .claude/settings.json 中。

遥测

需主动选择加入，默认关闭。 遥测关闭时，不会发送任何内容。如果选择加入，只会发送匿名使用指标（不包含代码、查询、文件路径、符号名称或记忆内容）。遥测与捆绑模型的首次下载及任何显式配置的远程嵌入提供程序彼此独立。完整的架构和实现细节请参阅 TELEMETRY.md。

开源，开放核心

完整的 MCP 服务免费且开源（MIT）。全部 37 个工具，无任何限制；遥测需主动选择加入，且默认关闭；没有“免费层”——界线不在这里。

Sverklo Pro（今年晚些时候推出）将新增决策智能自动捕获、跨项目模式学习和更大的嵌入模型。Sverklo Team 将新增团队共享记忆和本地部署。

开放核心的界线：Pro 增添新功能，绝不限制现有功能。 如今 OSS 服务中的任何内容，都将永远保留在 OSS 服务中。

链接

• 网站
• npm
• 问题反馈
• 首次运行指南
• 基准测试
• 论文（Zenodo，CC BY 4.0）

引用 Sverklo

如果你在研究中使用 Sverklo 或其基准测试（bench:primitives、bench:swe），请引用：

Groshin, N. (2026). Sverklo: A Local-First Code Intelligence MCP Server and a Cross-Repository Software Engineering Benchmark. Zenodo. https://doi.org/10.5281/zenodo.19802051

BibTeX：

@misc{groshin2026sverklo,
  author    = {Groshin, Nikita},
  title     = {{Sverklo}: A Local-First Code Intelligence {MCP} Server and a Cross-Repository Software Engineering Benchmark},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19802051},
  url       = {https://doi.org/10.5281/zenodo.19802051}
}

Star 历史

如果 sverklo 帮你的 AI 不再凭空编造代码库中不存在的函数名，你能做的最有用的事就是**⭐ 为这个仓库点个 Star**，并分享给一位队友。

许可证

MIT