我为AI代理打造了一个小型本地图书管理员，源于观察它们在仓库搜索中如浣熊闯入厨房般的行为

披露：我构建了此项目，因此这是一篇项目介绍而非独立评论。我分享它是因为它源于我自己代理工作流中一个非常真实的烦恼，并且我真诚地希望从处理大型仓库、日志、文档和本地AI工具的人那里获得反馈。 我一直遇到同一个荒谬的问题：AI代理能写出惊人的好代码……但当我要求它在仓库中找到一句话时，它有时表现得像凌晨两点闯入厨房的浣熊。打开一个文件。搜索另一个。转储47个模糊相关的匹配。忘记哪个看起来有希望。重新开始。然后自信地解释说“相关信息可能不存在。” 问题通常不在于模型的智能。而在于导航。因此，我构建了一个名为 baoer_signal_grep 的小型本地搜索插件。最简单的描述是：它试图成为AI代理的耐心图书管理员。不是神奇的预言家，不是巨大的云索引，不是另一个带有38个发光图表的仪表板。只是一个本地工具，帮助代理找到正确的书架，打开正确的页面，保持书签，并从那里继续，而不假装部分搜索已完成。 它做什么 1. 小型搜索直接返回有用段落 如果你正在寻找错误消息、一句话、产品名称、配置键或人名，它可以返回匹配的文本以及文件路径和位置。这意味着代理不必总是打开每个文件夹并手动滚动每个文档。对于小型搜索，结果也故意小。找到句子。显示它所在的位置。让代理在需要时检查周围的上下文。这听起来非常基础，这可能就是为什么当它缺失时，很容易低估浪费了多少时间。 2. 广泛搜索从地图开始，而非文本洪流 有些搜索本质上是广泛的。“哪些文档提到退款？”“我们在哪里讨论认证？”“哪些日志包含与此事件相关的任何内容？”这些搜索可能返回大量材料。插件可以不是立即将整个堆扔进对话，而是从一个紧凑的相关文件和片段地图开始。代理然后可以决定哪些文件值得仔细查看。这很有用，因为第一个问题通常不是：“答案是什么？”而是：“我应该去哪里寻找答案？”这些是不同的任务，将它们混在一起往往会产生一个非常大、非常昂贵的混乱。 3. 后续问题保持书签 我最喜欢的小细节之一是延续性。如果第一个结果不适合一页，下一个请求可以从现有结果继续，而不是静默地开始新搜索并希望它再次找到相同内容。因此，后续可以像“从我们停止的地方继续”这样简单。搜索结果保持其光标、保留的匹配及其与原始快照的关系。这使得多步调查感觉不那么像反复摇晃一盒纸并希望同一份文件掉出来。 4. 它可以处理不完美记忆的措辞 人类很少记住他们看到的确切句子。我们记得类似：“可能是关于退款截止日期的部分……”“某处解释了会话如何过期……”“我认为文档说了一些关于超时后重试的内容……”对于那种搜索，模式：混合结合精确字面匹配与本地语义候选。精确匹配保持第一。语义候选被清晰标记为语义候选，按相似度排序，并在与精确结果重叠时去重。这种区分对我来说很重要。语义相似的段落是线索，不是证明。代理应该能够说：“这是确切文本。”或者：“这个段落似乎相关；请检查它。”这些不是相同的句子，搜索工具不应该将它们混为一谈。简化的请求如下所示： { "mode": "hybrid", "query": "where do we explain the refund deadline?", "conceptLimit": 3 } 当本地概念模型可用时，用于语义部分。搜索设计为保持本地，即使语义步骤被跳过、超时或失败，精确字面结果仍可用。换句话说，花哨的部分允许有糟糕的一天，而不拖累无聊但重要的部分。我欣赏这种行为比预期的更多。 5. 多个条件可以一起表达 有时一个关键词太宽泛。你想要同时包含客户名称和订单号的文件。或同时包含“退款”和“截止日期”。或几种可能拼写中的任何一种。插件支持组合条件，因此代理可以直接表达这些搜索，而不是执行几个不相关的搜索并在事后心理上交叉结果。这听起来微不足道，直到你有一个充满日志、生成文件、笔记、示例和旧文档的仓库，所有这些都使用稍微不同的词汇。 6. 搜索范围可以缩小 如果代理只需要搜索一个文件夹，请求可以限制在该文件夹。如果你只记得部分文件名，它可以帮助先定位文件，然后检查相关内容。目标是让搜索范围可见且有意。聚焦的搜索通常更容易理解、调试，并且不太可能意外地从名为 old、tmp 或 please_do_not_use_this_anymore 的遗忘目录中拉入不相关的示例。有意义的隐藏文件默认可搜索，而 .git 内部文件被排除。因为隐藏并不总是意味着不相关。有时最重要的配置文件是以点开头并一直在角落里安静地评判每个人的那个。 7. 它也可以帮助源结构 对于 JavaScript 和 TypeScript，有模式查看符号、导入、引用、调用者、被调用者、实现、依赖和相关测试候选。对于 Python，大纲模式提供基于缩进的有限类和函数证据。这不是声称静态关系证明运行时行为。它们并不。它只是一种帮助代理在阅读整个代码库之前定位的方式，就像它是一本非常有敌意的小说。 8. 它试图诚实地面对限制 这可能是最不花哨的功能，但它可能是代理工具最重要的功能之一。搜索结果可以分页。覆盖可以是部分的。文件可能不可用。概念候选可能被跳过。限制被报告。原因被保留。部分快照不应该悄悄地伪装成完整答案。如果语义搜索无法完成，精确搜索结果不会被丢弃。响应仍然可以显示精确证据，并解释语义候选被跳过。这是一个比返回空的成功外观结果并让代理围绕它编造故事更有用的失败模式。 技术部分，对于喜欢管道的人 几个实现细节可能有用：混合搜索在一个自有请求下运行精确字面匹配和本地语义检索。精确证据在语义候选之前呈现。重叠的语义段落被去重。保留的结果可以继续而不重新运行原始搜索。语义排名覆盖请求源预算允许的 UTF-8 段落，而不仅仅是采样固定前缀。长段落通过重叠的令牌安全窗口处理，因此后续内容不会被静默忽略。本地嵌入按内容、模型修订和分块修订缓存。本地缓存限制在 512 MiB。缓存写入或清理失败保持可见，而不是被转换为假成功。