项目背景与核心定位

大家好，我是小木头。本期视频的核心议题是：同一个代码问题，换一套搜索工具，Agent 会不会回答得更快？会不会用掉更少的 Token？ 为了验证这一点，我将 zvec-grep 做成了 DeepSeek Harness (DSH) 和 Pi Agent 的插件，并通过两个独立会话基于相同问题进行对比测试。在之前的视频中我们介绍过 zvec 和 zvec-grep：简单来说，zvec 是一个进程内、本地持久化的向量数据库，它像向量检索领域的 SQLite，应用可以直接把它嵌进自己的进程，不需要另外维护一套数据库服务。而 zvec-grep 则在它上面补齐了文件发现、代码与文档切分、embedding、全文检索向量召回和最终结果的融合，变成一套可以给 Agent 使用的代码搜索层。这里需要强调：zvec-grep 并不是用向量搜索替代了 grep，如果已经知道函数名、错误信息或正则表达式，精确的文本搜索通常更快且更确定。但如果只知道功能大概做什么而不知道具体命名，或者问题涉及架构、关系控制流和多个文件时，语义搜索就更容易先找到入口。找到入口后，再读取实时源代码进行验证。

插件化改造与安装体验

在试用过程中，我意识到既然它是给 Agent 使用的搜索工具，能不能直接把它放进 Agent 自己的生命周期？ 而不是要求每个用户先安装 zg、为项目建立索引并配置 MCP。因此，我分别开发了 DeepSeek Harness 和 Pi 的插件。插件只需要安装一次，以后每次会话启动，它会自动识别当前工作区，在后台建立或更新索引，并持续监听文件变化。Agent 会直接获得一个叫 zvec_search 的工具，正常使用不需要运行 zg install、zg index 或单独启动 MCP Server。在 DeepSeek Harness 中，运行 npx dsh plugin add 将插件加入 Web profile，完成后运行 npx dsh web 进入工作区。插件会在后台打开或更新索引，首次使用本地 embedding model 可能需要自动下载模型。DSH Web 右下角会有 zvec index 状态胶囊，从 Indexing 变为 Ready 后，Agent 即可调用 zvec_search。在 Pi Agent 中，安装命令为 pi install npm:@sugarforever/pi-zvec-grep。启动后插件自动协调索引并注册同名工具，可通过 /zvec-status 查看状态或 /zvec-reindex 进行诊断恢复，正常使用无需手动重建索引。

基准测试设计与执行环境

为了公平对比，我们在 DeepSeek Harness 中进行了同问题的比对（Pi Agent 也可做同样测评）。两个独立会话使用相同模型，从相同的初始上下文开始。问题非常相似：“find out how the knowledge base is designed and implemented”（找出知识库是如何设计和实现的）。普通组不指定搜索路径或工具，让 Agent 自己使用内置工具；zvec 组明确要求使用 zvec_search。我们记录五项信息：从提问到完整回答的时间、input Token 工具调用的总轮次、第一次命中关键入口的轮次，以及最终回答覆盖的关键信息。这里不能在问题里提前泄露文件名或函数名，否则就失去了语义发现的意义。博主指出：“这里不能在问题里提前泄露文件名或函数名，否则呢就失去了语义发现的意义”。这种设计确保了测试的是 Agent 通过工具自主探索代码库的能力，而非简单的关键词匹配。

Baseline：原生搜索工具的实测数据

我们先看使用内置搜索工具（Baseline）的表现。它最后给出了一份完整回答，从数据模型到接口，再到文档处理、向量存储检索路径及前端入口。在这个过程中，Agent 需要不断地猜测项目词汇，再通过多轮的搜索和读取扩大范围。在工具调用的整个链路上可以看到蛛丝马迹：整个任务走了大约 30 个步骤，运行时间是 1 分 34 秒。关于 Token 开销，应该在 136 万左右的 Token。具体的 input、cache 和 output 数据可以在画面中看到。这表明，在没有专用语义索引的情况下，Agent 需要大量的试错和上下文累积才能构建出完整的代码视图。博主提到：“整个任务走了大约30个步骤，运行时间呢是1分34秒”。这种高步数和高 Token 消耗反映了传统搜索在理解复杂架构时的低效性，Agent 必须在广阔的代码空间中盲目探索。

zvec-grep：语义搜索的实测数据与对比

再来看明确使用 zvec_search 的会话。它的步骤少了许多，用了 9 个步骤。运行时间也大幅缩短至 37 秒。关于 Token 开销，是 339,000 左右。相较于刚才的会话，看起来少了不少。对比数据如下：和 Baseline 相比，这次的时间减少大约 60%，步骤少了 70%（30步降至9步），Token 开销使用上减少了大约 75%。它同样找到了数据模型、文件处理检索、聊天调用等，但更早进入了能够回答问题的关键文件。不过需要说明一个实际情况：如果细心比对两个会话的输出，虽然回答的是同一个问题且核心架构重合，但展开重点细节和输出长度并不完全相同。所以这并不是说“相同答案用了更少 Token”的严格基准，只能看作同问题同模型下两条实际的调查路径的参考。不同的人对同一个问题也完全可能有不同的回答预期。博主强调：“Token 开销使用上减少了大约75%”，这一数据直观展示了语义检索在降低 LLM 上下文负担方面的巨大潜力。

Pi Agent 插件体验总结

Pi 这次没有再做一轮性能对比，只是简单总结一下插件提供的体验。安装一次以后从项目目录启动 Pi 插件自动识别工作区，在后台建立或更新索引，监听运行期间的文件变化。再向 Agent 注册 zvec_search 工具。索引正在更新时搜索并不会卡住整个会话，而是返回一个可以重试的状态。需要确认工作区和索引情况时可以使用 slash 命令 /zvec-status。也就是说，它跟 DeepSeek Harness 插件解决的是同一个问题：让这套检索能力跟着 Agent 的会话自动工作。这种无缝集成的体验消除了用户手动维护索引和配置 MCP Server 的繁琐步骤，使得语义搜索能力成为 Agent 会话的自然延伸。博主指出：“索引正在更新时搜索呢并不会卡住整个会话，而是返回一个可以重试的状态”，这种异步处理机制保证了用户体验的流畅性。

适用场景与代价分析

通过这些对比，我们可以更具体地判断什么时候值得维护一份索引。第一是较大且陌生的代码仓库，Agent 还不知道应该从哪里开始；第二是自然语言描述与代码命名并不一致的问题；第三是答案分散在代码、配置、文档之间需要跨文件综合去检索；第四是同一个项目会被多个会话反复查询，第一次建索引的成本可以被后续的使用来摊薄。当然它也是有代价的。一个小小代价呢就是首次模型的下载和建立索引需要时间，另一方面很重要的是：召回质量受到 embedding model 和查询语言的影响。为了保证语义搜索达到最好效果并反映当前代码或文档的实际情况，索引还需要随时保持最新。这个也是额外的代价。博主提醒：“为了保证语义搜索搜索能够达到最好的效果反映出当前的代码或文档的实际的情况呢索引还需要随时保持最新”。这意味着用户需要在检索精度和实时性之间做出权衡，特别是在代码频繁变动的开发环境中。

开源发布与社区互动

DeepSeek Harness 和 Pi 这两个插件目前都已经开源并发布了 npm。你可以从视频描述里的链接获取，直接安装并且体验。也可以拿自己的仓库来做一次对比。不同项目、不同模型和不同问题可能都会得到不一样的结果。如果使用过程中遇到问题或者想到可以改进的地方，欢迎大家在 GitHub 提 issue，也欢迎直接提交合并请求。博主表示：“比起一句‘向量搜索更快’我更希望这些插件能够给到大家或者为大家提供一个可以亲自尝试改进的起点”。以上呢就是本期视频的全部内容，希望对大家有所帮助。我是小木头，我们下期再见吧。

结论

本期视频通过实际对比测试证明，将 zvec-grep 集成为 Agent 插件（DSH 和 Pi）能显著优化代码搜索效率。在相同问题和模型下，使用 zvec_search 相比原生工具，步骤减少约 70%，时间缩短约 60%，Token 开销降低约 75%。这主要得益于语义搜索能更精准地定位入口，减少 Agent 的盲目探索。然而，这种优势并非没有代价：首次索引建立耗时、模型下载需求以及为保持召回质量所需的持续更新机制。此外，测试结果并非绝对的性能基准，因为不同 Agent 路径可能导致回答细节差异。该方案特别适合大型陌生仓库、命名不一致或跨文件综合检索的场景，且随着多次使用可摊薄初始成本。开源插件旨在提供一个可扩展的起点，鼓励社区根据具体项目特性进行优化和反馈。