Sverklo 是一款本地托管的代码搜索服务器，它现在允许开发者在 AI 代理根据结果采取行动之前，检查查询的每一步——从文件发现到符号图推理。

为什么现有的编程代理会陷入困境

大多数代码生成工具将代码库视为一个巨大的文本堆栈。它们嵌入代码片段，运行相似度搜索，然后返回得分最高的片段。当片段是过时的、超出范围的，或者仅仅是一个文件名时，代理无法指出其来源。这种失败模式并非缺少某个单词，而是缺少了一个上下文层，无法告诉人类该事实来自何处以及它是否仍然适用。

Sverklo 的四层验证模型

Sverklo 将自己定位为一个“工程假设”服务器，将传统搜索与结构化分析相结合：

  • 文件发现 (File Discovery) – 索引会读取 .gitignore 和其他忽略文件。在信任结果之前，你可以查询索引以查看实际扫描了哪些路径。
  • 代码结构 (Code Structure) – 符号存在于一个记录了定义、导入和调用关系的图中。查找操作返回的是符号对象，而不仅仅是文件路径，因此你可以确认引用的 API 表面是否正确。
  • 上下文交付 (Context Delivery) – 当你设置 Token 预算时，Sverklo 会返回对答案有贡献的代码片段映射。该映射包含一个 found_by 字段，告诉你匹配是来自 BM25 关键词匹配、ONNX 生成的嵌入，还是 PageRank 排序的符号图。
  • 记忆账本 (Memory Ledger) – 服务器会记录每项决策。如果文件发生了变化，账本会将相应的记忆条目标记为过时，从而显示缓存的答案是否仍然有效。

检索栈的工作原理

Sverklo 不仅仅依赖嵌入。它运行经典的 BM25 关键词引擎进行精确术语匹配，利用基于 ONNX 的向量嵌入来增强这些命中结果以实现语义相似度，然后对符号图应用 PageRank 算法以呈现高影响力的定义。通过暴露产生每次命中的方法，开发者可以发现分歧——例如，一个被嵌入模型认为无关的 BM25 命中结果——并选择信任哪种信号。

实际用途

  • 探索陌生的代码库 – 无需手动使用 grep，即可从函数名跳转到其所有调用者。
  • 映射依赖图 – 可视化跨多个包的导入链。
  • 评估重构影响 – 查看如果给定文件发生变化，哪些符号会失效。
  • 回答语义问题 – 询问“这个辅助函数是做什么的？”，并获得简洁且有据可查的摘录。

注意事项

  • 时效性 – 重新索引可能已经完成，但索引时间戳仍显示为旧值。请始终查询 index-status 端点，而不是假设最近的一次运行就是最新的。
  • 项目注册 – 注销项目时，请使用 Sverklo 提供的内部项目名称，而不是绝对文件系统路径，否则操作将静默失败。
  • 工具命名的特殊情况 – MCP hosts 有时会两次前缀项目名称，产生类似 sverklo_sverklo_impact 的标识符。在调用工具之前，请仔细检查名称。

下一步尝试

  1. 克隆一个临时仓库并在本地启动 Sverklo。
  2. 运行一个简单的符号查找并检查 found_by 字段。
  3. 修改一个源文件并重新运行查找；注意记忆账本如何标记过时的条目。
  4. 将 index-status 检查集成到你的构建脚本中，以自动捕获过时的索引。

核心总结

Sverklo 将代码搜索引擎转变为一条可审计的证据链。通过强制开发者验证文件覆盖范围、符号准确性、检索方法和记忆时效性，它让开发者能够在 AI 驱动的建议进入生产环境之前，决定其是否值得信赖。