有一次，我在检查一个知识库工具的控件查询能力。文档写得很有信心：这是一次 SQLite 直查，通常大约 2ms 就能返回。这样的承诺会影响使用方式。既然是本地索引查询，我会把它当成一个可以频繁调用的基础动作，而不是需要等待的复杂检索。
但真实结果完全不是这个节奏。一次控件查询持续超过 100 秒，最后被 timeout 终止，只留下空结果。空结果尤其容易制造误判：使用者可能以为库里没有匹配内容，也可能以为只是偶发卡顿，于是把等待阈值调大，再试一次。
我没有先改阈值。因为一个承诺约 2ms 的路径，如果实际要等 100 秒，首先要解释的不是“为什么这次慢一点”，而是“这次究竟走了哪条路径”。
先把承诺还原成执行路径
“秒查”不是一个单独的体验形容词，它应该对应一条能被观察和验证的执行路径。比如，查询先打开本地数据库，再利用已有索引完成条件匹配，最后返回控件记录。这个路径的每一段都很短，失败也应该在短时间内暴露。
如果数据库文件缺失，程序可能无法打开直查入口；如果索引损坏，查询可能执行失败；如果路由判断没有识别出这类失败，还可能悄悄转到语义检索。后者也许能找到相近内容，却需要嵌入计算或大模型参与，耗时自然不再是毫秒级。
所以我会把文档里的性能承诺拆成几个问题：有没有命中目标数据库？有没有真正使用索引？查询在哪一步发生了回退？回退后的耗时由什么组成？如果这些信息没有留下来，“2ms”就只是一个漂亮数字，不能帮助排障。
性能承诺只有绑定到可观测的执行路径，才是可以验收的承诺。
这件事让我重新意识到，工具说“快”，其实是在告诉我它准备怎样工作。文档不只是在介绍结果，也在暗示内部边界。既然承诺的是 SQLite 直查，就必须让使用者知道直查成功、直查失败和进入慢速路径之间的区别。
百秒等待暴露的不是普通抖动
面对一次超过 100 秒的查询，最容易误判的是把它归到环境抖动。机器忙、磁盘慢、第一次加载较久，这些解释都可能成立，但它们不能解释为什么一个约 2ms 的查询会持续到 100 秒。数量级已经发生变化，排查就不能只停留在调整等待时间。
如果不处理这个差异，后果不只是用户多等一会儿。调用方可能会把空结果当成“没有控件”，上层流程据此做出错误判断；也可能因为频繁重试，让多个慢速检索同时运行，进一步拖慢机器。更麻烦的是，团队会逐渐习惯把 timeout 设置得更大，最后没人再知道一次查询正常应该花多久。
我会先记录阶段耗时，而不是只记录总耗时。打开数据库用了多久，执行索引查询用了多久，生成嵌入用了多久，语义检索用了多久，结果整理用了多久。总时长只能说明症状，分段时长才有机会指出病灶。
这也是为什么一次“被 timeout 终止并返回空结果”不能算作正常的无结果。它至少说明调用者没有拿到一个明确的失败原因。空结果和查询失败是两件事，超时和没有匹配也是两件事。把它们混在一起，后续所有统计都会失真。
先分诊数据库，再判断是否回退
我会把排查分成两层。第 1 层只回答直查能不能成立：数据库是否存在，是否可以打开，必要的表和索引是否可用，最小查询能不能在预期时间内返回。这里不需要引入语义检索，因为那会改变问题本身。
第 2 层才看路由和回退：直查失败后，程序是否明确记录失败原因，是否因为授权的策略才进入慢速语义路径，慢速路径是否有独立的耗时和状态。这样做的价值在于，数据库缺失、索引损坏和语义回退虽然都会表现为“查询很慢或没结果”，修法却完全不同。
如果数据库缺失，应该修复构建或加载流程；如果索引损坏，应该重建或报错；如果直查本来成功，却被错误路由到语义检索，就要修正路由判断。只有在这些问题都排除后，才值得讨论语义检索本身的性能。
我选择先做路径级分诊，是因为它能把“数据不存在”和“程序没查到”区分开，也能把“索引坏了”和“程序主动走了另一条路”区分开。若一开始就把 timeout 从 100 秒改成 300 秒，所有这些差异都会被更长的等待掩盖。
超时阈值只能保护调用者，不能替代对执行路径的解释。
错误捷径是把慢结果合理化
这次最容易走的错误捷径，就是把超时阈值改得更大，再把慢结果解释成偶发抖动。它看起来很务实：至少程序不那么快失败了。但它没有修复任何问题，只是把错误从“立刻暴露”改成“晚一点暴露”。
还有一种更隐蔽的捷径，是把回退结果包装成直查结果。用户看到的是一个相关答案，可能觉得功能仍然可用；维护者看到的是一次成功调用，也可能继续保留“毫秒级”的文档。可一旦这个回退路径被大量调用，成本、延迟和稳定性都会变成另一套系统，原来的承诺也就失去了边界。
我宁愿让直查失败时明确报错，也不愿让它无声地切换到慢速路径。这里的“失败”并不意味着工具更差，它是在保护调用者的判断。调用者知道索引不可用，就可以修复索引或选择明确授权的慢查；调用者拿到一个没有解释的空结果，就只能继续猜。
如果确实需要自动回退，也应该把它作为独立能力来描述：什么时候触发，允许等待多久，结果是否保证完整，延迟大约处于什么范围。直查和语义检索可以共存，但不能共用一条模糊的性能承诺。
验收要测真实控件，不只测健康信号
为了判断问题是否真的解决，我不会只检查数据库文件存在，也不会只运行一条最简单的健康查询。文档承诺的是控件查询，所以验收也应该使用多个真实控件查询，确认它们都命中预期的直查路径，并且在小于 1 秒的范围内返回。
这里的“小于 1 秒”不是把文档里的 2ms 偷换成新的目标，而是一个更稳妥的验收门槛。一次实测可能受机器状态影响，但如果多个真实查询都能在 1 秒内完成，至少说明没有发生持续 100 秒的慢速回退。至于是否能稳定接近 2ms，还需要再看具体环境和统计口径。
验收记录还应该留下命中的索引、是否发生回退、各阶段耗时和最终状态。这样下一次再出现异常时，可以比较这次与上次的路径，而不必从“到底查了什么”重新猜起。
一个流程成熟的标志，不是它能在正常时返回结果，而是它能在异常时告诉我自己走到了哪里。健康检查证明组件还活着，真实控件查询才证明用户要用的路径确实可用。
把性能写成可追责的规则
这件事表面上是一次查询变慢，实际上是在检查文档、实现和验收是否说的是同一件事。文档说 SQLite 直查，代码却可能回退到语义检索；测试只看“有结果”，没有检查路径；调用者只看空结果，没有区分超时。每一层单独看都像合理，合在一起就会产生误导。
我会把可复用的方法写成一条顺序规则：先确认入口，再确认索引，再记录阶段耗时，再判断是否回退，最后用多个真实输入验收。直查失败就 fail loud，只有在明确授权时才进入慢速语义路径；一旦长期实测与文档承诺不一致，就修复路由或如实修改承诺。
这个规则也适用于其他“快”的工具。无论是缓存读取、文件搜索还是本地自动化，只要文档给出了明确的时间预期，就应该能指出对应的执行路径。否则，性能承诺只是宣传语，出问题时每个人都会用自己的经验填空。
真正可靠的性能不是永远很快，而是快的时候有证据，慢的时候有边界，失败的时候有原因。
下次我会怎么做
下次遇到一个声称“秒查”却突然卡住的工具，我会先停止扩大 timeout。第 1 步确认实际命中的数据源和索引，第 2 步检查数据库缺失、损坏或不可打开，第 3 步把直查、回退和结果整理分别计时，第 4 步确认是否存在未经说明的语义检索，第 5 步用多个真实控件查询做小于 1 秒的验收。
如果直查路径坏了，我会修路径，并让失败尽早暴露；如果慢速回退是有意设计的，我会把它写进文档，说明触发条件和时间边界；如果 2ms 只是理想状态而不是当前环境能兑现的事实，我会改成符合实测的表述。这样做不是降低要求，而是让要求重新和现实对齐。
这件事让我更愿意把性能当成一种可验证的工作承诺，而不是一个需要维护的乐观印象。工具真正改变的不是速度本身，而是我们是否愿意把判断过程留下来。下一次看到“秒查”，我想先问的不会是“还能不能再快”，而是“这几个字对应的路径，今天还能不能被证明”。