一个单文件，正在给 Agent 瘦身

导语：给 Agent 接海量历史数据，最怕的不是查不到，而是一查就把上下文塞爆。最近，一个叫 Leviathan 的开源小工具（GitHub 仓库：github.com/leviathan-search/leviathan，MIT 协议，上线八周累积约 3,400 star、87 个 fork，最新版本 v0.4.2，单二进制体积约 4.2 MB）在 Agent 工程圈子里被反复引用：单文件、零依赖，把 JSONL、CSV、SQLite 直接做成基于 BM25 相关度排序的全文索引，Agent 提问只返回裁剪整齐、带引用的短卡片。作者在其基准脚本中给出的数字是：在 1.2 GB 的 Enron 邮件数据集上做问答检索，相比直接 grep 转储喂给模型，平均每次查询的上下文 token 消耗从约 48,000 降至 1,900，降幅约 96%，单次查询延迟中位数 14 ms。这不是什么宏大叙事，但它戳中的是当下 Agent 工程里最疼的那个点——上下文，正在变成最贵的资源。

💥 先讲一个所有 Agent 开发者都经历过的场景

检索不是问题，返回什么才是问题。

设想一个常见任务：你让 Agent 帮你梳理公司过去三年的工单数据，找出客户流失的前兆信号。数据是现成的，几千条 JSONL 日志，或者一个 SQLite 库。Agent 拿到任务，第一步是搜索——然后悲剧发生了。

它 grep 到了几百条匹配记录，一股脑塞进上下文窗口。轻则回答质量断崖式下跌，重则直接超限报错。做过 Agent 工程的人对这一幕都不陌生：上下文窗口看起来很大，实际上非常脆。塞进去的东西多，不代表模型用得上，反而会稀释注意力、拉高推理成本、拖慢响应速度。

Leviathan 给出的解法朴素到令人意外：它在本地把数据做成全文索引，Agent 用自然语言提问，返回的不是原始数据倾泻，而是一张张裁剪整齐、带引用来源的简短卡片，并且按 BM25 分值降序排列，默认只返回 top-5、单卡片截断到 200 token。作者在 README 中给出的对比示例是：针对「找出 2001 年 11 月讨论加利福尼亚电力危机的邮件」这一查询，grep 匹配到 312 行、约 41,000 token；Leviathan 返回 5 张卡片、共 1,860 token，且前两张卡片即覆盖了人工核对后的最佳答案所在的两封原始邮件。

这中间的差别，本质上是「把原始世界搬给模型」和「把结论递给模型」的差别。前者是搬运工思维，后者是编辑思维。而 Agent 时代的工程范式，正在从前者向后迁移。

🧱 单文件、零依赖，一种被低估的工程美德

基础设施的尽头，是无聊的技术。

Leviathan 的定位写得非常克制：一个没有外部依赖的单文件静态二进制。仓库的 Cargo.toml 里没有任何运行时第三方依赖——索引、分词、BM25 打分全部内置实现，没有服务进程，没有数据库集群，没有控制面。拷贝过去就能跑，数据在哪它就索引在哪。

做过平台工程的人都懂这意味着什么。部署摩擦是所有数据工具的隐形税：一个需要 Python 环境、需要装向量库、需要起一个常驻服务的检索方案，在个人开发者的 Mac 上能跑，到了客户的内网服务器上就全是坑。而单文件二进制是另一条路线——SQLite 靠这个特性统治了嵌入式数据库几十年，ripgrep、fd 这类命令行工具靠这个特性成了开发者的肌肉记忆。

开源社区里其实一直有一种朴素的共识：真正的工具，是不需要运维的工具。尤其当使用方是 Agent 的时候——Agent 自己要调用这个工具，它没有耐心去排查端口冲突和依赖版本。

从工程视角看，Leviathan 的输入面设计也体现了一种务实的判断：JSONL、CSV、SQLite，甚至各种数据库 CLI（psql、mysql、duckdb）的导出结果。这几乎覆盖了数据工程师日常打交道的一大半格式。它不试图成为数据仓库，也不试图取代 ETL，它就站在「数据已经是文件、或者能变成文件」这个最普遍的现实上。

这张表是工程判断而非跑分结论，但它勾勒出一个清晰的位置：Leviathan 不和重装方案抢地盘，它卡住的是「个人和小团队给 Agent 接本地数据」这个最大基数的场景。

🎯 词法检索的回潮：为什么不是向量数据库

当所有人都涌向向量检索时，倒回去看一眼词法，可能反而清醒。

过去两年，做检索几乎默认等于上向量数据库：文本切块、嵌入、建索引、近似最近邻查询。这条路线在互联网语义搜索场景被充分验证，也催生了一整条产业链。

但 Agent 的本地数据问答，和互联网语义搜索其实是两个问题。前者面对的往往是结构化或半结构化的记录——日志、工单、交易明细、导出报表。这类数据里，精确匹配的价值经常高于模糊语义：一个客户 ID、一个错误码、一个订单号，词法索引一击即中，语义嵌入反而可能「智能」地匹配回一堆似是而非的内容。

Leviathan 选择了带相关度排序的全文索引这条老路，具体实现也并不神秘：建索引时按字段做倒排索引，字段权重可配置（默认正文字段权重 1.0、标题/ID 类字段权重 2.0）；查询时用标准 Okapi BM25 打分，参数取学术界常用值 k1=1.5、b=0.75，并按记录做去重和跨字段归并。老路的好处是可以把工程精力全部花在返回什么上：排序保证最相关的排前面，裁剪保证不超量，引用保证每张卡片可溯源——每张卡片附带原始文件的路径和行号（或 SQLite 的表名与 rowid），Agent 可以据此回查原文。

这里其实藏着 Agent 检索设计的一个关键转向：追求的目标从召回率变成了上下文精度。传统搜索恨不得把所有可能相关的内容都捞出来；而 Agent 场景下，返回给模型的每一个 token 都是有价格的，多返回一条弱相关记录，就是一次对模型注意力的稀释和一次对钱包的消耗。

这不是说向量检索过时了。语义模糊查询、跨文档主题归纳，仍然是词法方案的盲区。更可能的产业走向是两者分层：词法索引负责精确事实的快速抽取，向量检索负责模糊语义的广域召回，Agent 按任务类型选择工具。事实上，这种「不二选一、按需组合」的思路已经有明确的实现先例：Anthropic 官方的 Claude Code 在代码检索中就以 grep/ripgrep 等词法工具为主力手段，OpenAI 的 File Search 同样是关键词与向量双路并行、按查询特征路由。词法检索在 Agent 工具链里的位置，已经从「过时技术」重新变成了「默认组件」。

💰 上下文即成本：一笔每个团队都该算的账

模型推理按 token 计费，浪费上下文就是真金白银地烧钱。

把上下文经济学摊开看，事情会更清楚。Agent 的单次运行成本，大致由「输入 token × 单价 + 输出 token × 单价 × 轮数」构成，而检索转储恰恰是输入侧最大的漏水口。一次不负责任的 grep 转储可能塞进几万 token 的无关内容，而这些内容在多轮 Agent 任务里还可能被反复携带、反复计费。

Leviathan 的卡片式返回，本质上是把「上下文预算管理」前移到了检索层：进入模型窗口之前，先在工具侧完成一次压缩和编辑。按仓库基准脚本的口径粗算一笔账：以 Enron 数据集的 40 条测试查询计，grep 转储路线平均每次消耗约 48,000 输入 token，Leviathan 约 1,900；在主流旗舰模型每百万输入 token 数美元的价位上，单次查询的输入成本差约 25 倍，一个日均执行 200 次检索查询的 Agent 任务流，一天仅输入侧就能省下数美元级别的费用，且更短的上下文通常意味着更少的重试轮数。这不省模型的钱，它省的是模型的注意力——而被稀释的注意力，最终也会以更低的质量和更多的重试轮数，折算成钱。

从产业视角看，「上下文工程」正在成为一个独立的工种和卖点。围绕它已经分化出几条产品线：长上下文模型在堆窗口，上下文缓存服务在压单价，而 Leviathan 代表的是第三条路——在数据侧就把上下文做小。三条路不冲突，但对大多数没拿到模型厂补贴的普通团队来说，第三条路的投入产出比最直观：不需要换模型，不需要改架构，加一个工具就见效。

这也是为什么一个功能并不炫技的单文件工具能在几周内攒下三千多个 star——它不是在追逐 Agent 叙事，它是在给 Agent 叙事还债。叙事讲完之后，剩下的都是工程账。

⚠️ 它不是银弹：这条路线的边界在哪里

工具的价值，一半在它能做什么，一半在它明确不做什么。

冷静看，Leviathan 的适用边界也相当清晰。

第一，词法索引的语义理解天花板是摆在那的。问「用户对产品整体的情绪倾向如何」，全文索引帮不了太多忙，这仍是嵌入模型和语义检索的领地。第二，它的质量上限取决于索引和排序层的功力——多语言分词、字段权重、结构化数据里的数值比较，这些都是全文检索的经典难题；Leviathan 目前对中文等无空格语言的支持仍依赖内置的简易分词，作者在 issue 区也承认这需要持续打磨，单文件形态下能做到什么程度，还需要真实数据集的长期检验。第三，面对真正的大规模数据（比如数十亿行的生产库表），轻量方案的性能边界也需要验证——仓库目前公布的基准只到千万行级别（1.2 GB 索引耗时约 90 秒），重数据场景仍然属于数仓和专业的检索引擎。

另外，凡是把数据做成索引持久化的工具，都要回答数据安全的问题：索引文件落在哪里、访问权限如何管控、敏感字段是否会通过卡片泄漏给模型。Leviathan 的索引默认写到数据同目录的 .leviathan/ 下，提供字段级排除配置，且因为整个流程不出本地，不涉及数据外发——但前提是使用者在接入 Agent 前把权限设计做扎实。

所以更准确的判断是：Leviathan 不是要取代谁，而是把「Agent 本地数据问答」这件高频小事，做到了部署成本几乎为零、失败模式几乎为零的程度。在 Agent 工程从 demo 走向生产的当下，这种定位本身就是稀缺品。

小结

Leviathan 的信号意义大于工具本身：Agent 时代的瓶颈已经从「模型够不够聪明」转移到「上下文喂得对不对」，而解决方案未必需要一套重型基础设施——一个零依赖的 BM25 词法索引加严格的返回裁剪，就能在真实数据集上把单次查询的上下文开销压缩一个数量级。可以预见，围绕上下文精度的轻量工具层会在未来一年持续增厚，词法与向量的组合检索会成为 Agent 数据接入的默认形态。泡沫退潮之后，活下来的往往是这些不好看但好用的东西。