找资料时最常见的失败不是"没找到"，而是"以为没有"。搜了一个词没结果，就下结论说知识库里没这个内容，然后重新造轮子——而实际答案可能就在库里，只是当时写的人用了另一个叫法。
检索是一项可以练的技能，而且它的瓶颈很少在工具，在提问方式。这篇按"失败归因 → 两种检索的适用面 → 混合做法 → 检索前的准备 → 结果的二次加工 → 自建索引"的顺序展开。
1. 检索失败的三种原因
把失败分成三类，因为它们的解法完全不同。混在一起，就会把"换词"的问题当成"补文档"的问题。
| 原因 | 表现 | 判别方法 | 解法 |
|---|---|---|---|
| 不知道叫什么 | 你知道有这个东西，但说不上术语 | 能描述现象，写不出名词 | 从现象词入手，或问人 |
| 术语不一致 | 库里叫 A，你搜 B | 搜 B 无果，搜 A 立刻命中 | 维护术语表，做同义词映射 |
| 知识确实没有 | 换三种说法都无果 | 三种不同角度都空 | 补文档，或去找外部来源 |
判别顺序很重要：先换词，再换角度，最后才断言"没有"。 只搜一次就断言缺失，是最常见的低效行为。
把换词过程写下来，避免第二轮再从头试：
检索记录（三行，写给自己看）：
目标：找「连接池归还时机」相关说明
① 术语尝试：连接池归还 / release / 回池 / 借还 ── 只有 "release" 命中 2 条
② 角度尝试：从"报错信息"倒推 ── 搜 "Cannot get a connection" 命中排查记录
③ 结论：库里有，叫法不一致；把 release 加入术语表同义项
2. 关键词检索：适用面与局限
关键词检索（grep、Ctrl+F、库内搜索）的本质是字面匹配。它的优点是精确、可解释、无延迟；缺点是对说法不宽容。
| 场景 | 关键词是否够用 | 原因 |
|---|---|---|
| 找具体函数名、类名、报错码 | 够用，且最快 | 标识符唯一，不存在同义 |
| 找配置项名 | 够用 | 字面固定 |
| 找某次事故的记录 | 勉强 | 取决于当时用了什么词 |
| 找"某个概念怎么做" | 不够 | 不同人叫法不同 |
| 找"为什么这么设计" | 不够 | 问题本身就是一句话 |
关键词检索真正的局限只有一条：它只能匹配你已经在脑子里拼出来的字。 当你不知道那个字，它就帮不上。
3. 语义检索：擅长什么，不擅长什么
语义检索按意思匹配，所以换个说法也能命中。但它在需要字面精确的地方反而更差。
| 查询类型 | 语义检索表现 | 说明 |
|---|---|---|
| "服务变慢怎么查" → 命中"性能瓶颈定位" | 强 | 表述不同、意图相同 |
| "为什么用户登不上" → 命中"鉴权失败排查" | 强 | 现象与结论之间靠语义桥接 |
精确报错 NullPointerException at Foo:42 |
弱 | 语义模型会忽略标识符细节 |
代码符号 getConnectionTimeoutMs |
弱 | 会被"相似语义"的符号淹没 |
| 版本号、日期、工单号 | 弱 | 数字与短串不构成语义 |
结论：语义检索解决"换说法"，不解决"精确标识"。 把它用在前者，别指望它替代后者。
4. 混合检索的现实做法
工程上真正可用的不是二选一，而是三层递进。按成本从低到高排：
第一层：精确串（必须最先用）
grep -rn "getConnectionTimeoutMs" --include=*.java .
第二层：关键词 + 同义词扩展（人脑补词）
grep -rniE "(连接池|pool|timeout|超时).*(配置|config)" .
第三层：语义检索（换说法、描述现象）
自然语言提问：「请求量上来之后延迟突然变高，通常先看哪里？」
| 层 | 成本 | 命中率 | 何时跳过 |
|---|---|---|---|
| 精确串 | 秒级 | 有则必中 | 只在有确切标识符时有效 |
| 关键词扩展 | 分钟级 | 中 | 不知该扩什么词就没法用 |
| 语义检索 | 秒级 | 高（概念类） | 查标识符时别用 |
实际操作顺序：有精确标识符 → 直接 grep；描述性问题 → 语义先行，再拿命中结果里的关键词回 grep 精确定位。 语义负责找入口，关键词负责挖到底。
5. 提问式检索 vs 关键词检索
同一个需求，写成完整句子往往比堆关键词更准，因为句子带着意图、条件和边界。
| 需求 | 关键词写法 | 提问式写法 | 哪个更好 |
|---|---|---|---|
| 排查慢请求 | 慢 排查 |
"接口在流量高峰变慢，但 CPU 不高，该看哪些指标？" | 提问式 |
| 找配置项 | 连接池 配置 |
pool.maxActive |
关键词 |
| 找设计理由 | 为什么 这样设计 |
"这个模块为什么不直接用现成的缓存，而要自己写一层？" | 提问式 |
| 找历史事故 | 事故 |
"上次订单超卖是什么原因、怎么修好的？" | 提问式 |
写提问的三条规则：带场景、带已排除项、带期望的答案形态。
提问模板：
【场景】在 ______ 条件下，出现 ______ 现象
【已排除】我确认 ______ 不是原因
【想要】给我 ______（判断标准 / 排查步骤 / 配置项 / 设计理由）
第三条最容易被忽略：不说要什么形态的答案，拿回来的东西往往不是你要的那个层级。
6. 检索前的准备：先分清概念还是事实
同一个词，你要的可能是"定义"也可能是"具体值"，这两种需求的检索策略完全不同。
| 你要找的 | 特征 | 检索策略 |
|---|---|---|
| 概念 | 它是什么、为什么这样、何时不适用 | 提问式检索 + 找讲解型材料 |
| 具体事实 | 某个值、某个路径、某个人名 | 精确串 + 表格/清单型材料 |
| 归属 | 谁负责、在哪定义 | 代码跳转、责任人表、提交记录 |
| 时序 | 什么时候改的、之前是什么 | 变更记录、版本历史、工单 |
判断方法：如果答案是一段话，找概念；如果答案是一个词，找事实。 用错策略的典型症状是拿提问式去搜一个配置项名字，得到一堆泛泛的说明。
7. 结果的二次加工：找到就转述
检索不是终点。找到材料的十秒内不做加工，下次还得重来——这是检索效率最大的漏洞。
找到后的三十秒动作：
1. 用一句话写下"这条材料回答了我的什么问题"；
2. 再写一句"它在我这个场景里需要注意什么"；
3. 记下来源位置（文件+行号 / URL+小节），不记全文。
| 加工层级 | 做法 | 复用率 |
|---|---|---|
| 只留链接 | 复制 URL 到笔记 | 低，下次还要重读 |
| 摘关键句 | 抄两三句原文 | 中，仍要对照语境 |
| 转述 + 定位 | 自己的话 + 出处坐标 | 高，可直接引用 |
关键是坐标：记"哪个文件的哪一节"，不记"我大致记得在哪看过"。 没有坐标的结论，用的时候不敢引用，等于没有。
8. 建自己的索引
检索速度的上限，往往取决于你有多少东西根本不用搜。三类索引最值得维护，因为它们决定了你每天重复付出多少检索成本。
| 索引 | 内容 | 维护频率 | 收益 |
|---|---|---|---|
| 常用链接 | 十个以内每天要开的面板、文档、工单系统 | 每月一次 | 省掉搜索动作 |
| 术语表 | 本领域/本团队的特殊叫法 → 通用说法 | 随遇随加 | 直接消掉"术语不一致"这类失败 |
| 代码片段库 | 能直接跑的最小示例，带一句说明 | 每次重写就存 | 省掉重新推导 |
术语表的写法示例，一行一条，不需要长篇：
[术语表]
- 骨架 / 大纲 / 框架 → 统一叫「骨架」，指章节划分与顺序
- 连接池满 / 借不到连接 / pool exhausted → 同一现象
- 冷启动 / 首包慢 / 预热不足 → 视语境区分，不混用
维护纪律：术语表只在"你搜失败过一次"时增加条目。 没失败过的词不用记，那只是自我满足。
9. 常见坑
| 现象 | 原因 | 处理 |
|---|---|---|
| 一个词搜不到就断定没有 | 未做换词与换角度 | 三种说法、三个角度都试过再断言 |
| 把检索当学习 | 搜来的碎片没有结构 | 检索只解决具体问题，体系靠阅读与整理 |
| 结果不验证就用 | 语义检索会返回"看起来相关"的错误内容 | 命中后回原文核对，尤其版本与前提 |
| 只搜不问人 | 有些知识不在库里 | 三次检索无果，直接问人，成本更低 |
| 检索词越加越长 | 认为多加词能缩小范围 | 先减词再换词，长查询反而更容易全空 |
| 不记来源 | 用完就忘，无法复核 | 记文件+行号或 URL+小节 |
| 一直用同一套问法 | 没意识到失败模式 | 建立"换词 → 换角度 → 问人"的固定顺序 |
10. 边界：什么情况别检索
| 场景 | 更合适的做法 | 理由 |
|---|---|---|
| 需要做决定、承担后果 | 找人讨论，检索只提供素材 | 决策需要语境与责任 |
| 库本身不可信或过期 | 先核对版本，再决定是否检索 | 检索越快，错得越快 |
| 你要的是原创洞察 | 检索只能找到已有观点 | 组合与判断发生在你脑子里 |
| 问题还没成形 | 先把问题写清楚再搜 | 含混的问题只能得到含混的答案 |
| 检索成本高于试错 | 直接写最小示例跑一遍 | 实验比找文档快 |
一句话选择：有精确标识符用字面搜，描述现象用句子问，三次无果就换人问——检索的正确姿态是"有顺序地试"，不是"一直搜"。
11. 自测
- 检索失败的三种原因，各自该用什么办法判别？
- 什么情况下语义检索一定比关键词差，为什么？
- 混合检索里，语义层与关键词层各自负责什么角色？
- 提问式检索的三条规则分别防止哪类低质量结果？
- 找到材料后的三十秒里，最该记下的是什么？
- 术语表应该在什么时候增加条目？