研发人员用自然语言问规范、接口或项目历史却检索不到答案，原因通常落在两处：知识本身没进入可检索范围，或者知识在范围内但检索环节没命中。排查从确认“这个问题是否可答”开始，先看目标文档是否存在且当前账号能访问，再用原文关键词复测，逐步放开过滤条件，最后核对切片与索引状态。每一步都留下证据，避免把假设当结论。
要点总览（TL;DR）
- 先界定症状：完全无结果、返回无关内容、返回旧版本内容、回答含糊拒答四类表现指向的原因不同，排查起点也不同。
- 排查按“知识是否存在 → 当前账号是否可见 → 是否被检索到”的顺序推进，前一层不成立时调整检索配置没有意义。
- 每条原因假设都要拿到对应证据才算成立，例如权限问题需同时满足有权限账号能查到、原账号可见范围确实排除该文档。
- 处置按原因分类：补知识、修权限、调切片与字段、改检索配置、改写提问；批量重建索引或改权限前先备份配置并设停止点。
- 用固定问题集回归验证，确认命中恢复且引用版本正确，再把高频未命中问题整理成知识补充清单定期回填。
先界定症状：是查不到、答非所问，还是答了但不可信
“检索不到答案”是一句笼统描述，不同表现指向的原因差别很大。先把它拆成可观察的症状，才能确定从哪查、查多深。
| 症状类型 | 可观察表现 | 初步指向 |
|---|---|---|
| 完全无结果 | 系统返回空结果或明确提示未找到相关内容 | 知识未入库、权限隔离、过滤条件过严 |
| 返回无关内容 | 有结果，但内容与问题主题不相关 | 问法表述差异大、同义词与缩写未覆盖、切片语义不完整 |
| 返回旧版本内容 | 结果指向已废弃或过期文档 | 文档版本未更新、重复文档未清理 |
| 回答含糊或拒答 | 检索到了片段，但回答笼统、回避或表示无法确定 | 切片缺少上下文、答案段落被切断、字段信息缺失 |
确定症状后，记录复现信息：提问原文（保留原始措辞，不要事后改写）、提问账号及其角色、提问时间、涉及的知识域或文档范围。同一问题换一个账号、换一个时间点再问一次，观察结果是否一致，可以快速判断是账号相关问题还是知识内容问题。
接着判断影响范围。只影响某一个问题，属于单点问题；某类文档（如接口文档、部署规范）普遍问不到，说明该类文档的入库或切片存在系统性问题；某个团队普遍反馈问不到，则优先怀疑该团队所在知识空间的权限配置或同步状态。范围判断决定了后续排查是查单篇文档还是查整批配置。
按假设逐条验证：知识在不在、能不能被看到、有没有被检索到
症状明确后，把可能原因写成假设，逐条找证据验证。排查顺序建议按“知识是否存在 → 是否可见 → 是否被检索到”推进，前一层不成立时，后一层的调整没有意义。
| 假设 | 验证方法 | 成立所需的证据 |
|---|---|---|
| 目标文档未进入知识库或同步失败 | 在知识库中按文档标题或编号直接查找，查看入库状态与最近更新时间 | 知识库中确实不存在该文档，或存在但更新时间明显落后于源文档 |
| 权限或空间隔离导致当前账号看不到 | 换一个有该知识域权限的账号提同样问题；核对文档所在空间的可见范围设置 | 有权限账号能检索到、原账号不能，且可见范围配置确实排除了原账号所属角色 |
| 切片、标题与字段缺失导致语义不完整 | 打开该文档的切片结果，检查包含答案的段落是否被完整保留，标题、摘要、标签是否为空 | 答案段落被切断、切片中缺少关键上下文，或结构化字段大面积缺失 |
| 问法与文档表述差异大，缩写与同义词未覆盖 | 改用文档中的原文关键词、接口名或规范编号重新提问 | 原文关键词能命中、自然语言问法不能命中，差异可复现 |
| 过滤条件、时间范围或知识域限定过窄 | 逐步去掉时间范围、知识域、文档类型等限定条件，观察结果变化 | 放开某一条件后结果出现，且该条件确实把目标文档排除在外 |
每条假设都要拿到对应证据才算成立。例如“应该是权限问题”只是猜测，需要同时具备两个事实：有权限账号能查到、原账号的可见范围配置确实不含该文档。只有其中一个事实时，继续排查其他假设，不要提前下结论。
排查顺序上，先验证假设一和假设二，因为它们决定问题是否可答；这两条排除后，再用原文关键词复测区分假设四和假设五；最后检查切片与字段。这样安排的好处是，多数问题在前两步就能定位，不必一开始就动检索配置。
在知识入库与权限这一层，ONES 的文档与知识库管理可以承接：文档在项目或团队空间内维护，入库状态、版本更新和空间可见范围都有对应记录，排查时可以直接核对文档是否存在、最近一次更新是什么时候、当前账号所属角色是否在可见范围内。把文档维护和需求、缺陷等工作项放在同一套协作流程里，也能减少“规范改了但知识库没同步”这类过期问题。
按排查结果处置：补知识、修权限、调检索配置或改写提问
原因确认后，处置动作与原因一一对应。以下按原因分类给出动作，涉及权限和索引的操作附带风险边界。
知识缺失或过期
补齐缺失文档，更新已过期的版本，同时清理重复文档和明确废弃的旧文档。重复文档会让检索结果分散到多个相似片段，旧版本残留则会让回答引用过期内容。处置完成的标志是：知识库中该主题只保留一份现行有效文档，且更新时间与源文档一致。
权限问题
核对知识域的可见范围，确认目标角色是否被排除。放开权限时按最小必要原则处理：只对需要该知识的角色开放对应空间，避免一次性全量开放。全量开放会让内部敏感文档进入所有人的检索范围，事后收回成本高。改动前记录原可见范围配置，便于回退。
切片与字段问题
补充文档标题、摘要、标签等结构化信息，让切片携带足够的主题线索；对答案段落被切断的文档，调整切片粒度，使规范条款、接口说明保持完整。调整后抽查若干切片，确认答案段落完整、上下文可读。
检索配置
补充同义词与缩写词表，把团队常用的简称、英文缩写与文档中的正式表述建立对应；过滤条件过严时适度放宽时间范围或知识域限定。每次改动前记录原配置，改动后立即用固定问题复测，确认没有引入新的误命中。
提问侧改写
当问题本身过于口语化时，引导提问者补充模块名、接口名、版本号等具体线索。例如把“登录接口怎么调”改写为“用户中心登录接口 v2.3 的请求参数和返回码”，把“发布规范是什么”改写为“前端发布规范中关于灰度比例的条款”。具体问法能显著缩小检索范围。
涉及批量重建索引或批量修改权限的操作，先备份当前配置，安排在低峰期执行，并设定停止点：例如重建过程中命中率持续下降或出现大量报错，立即停止并回滚到备份配置。单篇文档的补充和个别权限调整风险较低，可以随查随改。
验证恢复并减少复发：用固定问题集回归，把知识维护纳入日常
处置完成后，用一组固定的典型问题做回归验证，覆盖本次出问题的知识域，同时包含此前能正常命中的问题作为对照。对比处置前后的命中情况：原来无结果的现在能否返回正确内容，原来返回旧版本的现在是否指向现行文档，原来答非所问的现在是否切题。回归通过的标准是目标问题稳定命中，且对照问题没有退化。
逐条确认回答引用的文档版本正确、内容与现行规范一致。检索到内容不等于内容可信，版本核对是验证环节不可省略的一步。
把排查过程中发现的高频未命中问题整理成知识补充清单，标注缺失的知识点和负责补充的角色，定期回填。同时明确知识维护规则：每类文档指定知识负责人，规定文档更新触发条件（如规范修订、接口变更、项目复盘后），以及文档下线的判断标准，减少过期与重复文档的积累。
最后记录本次排查结论：症状类型、验证成立的假设、处置动作、回归结果。这份记录既是本次问题的闭环，也能作为同类问题再次出现时的排查起点，缩短下一次定位时间。
常见问题
同一个问题，有的同事能查到答案，有的查不到，应该先查什么？
先查权限与可见范围，这是账号间结果差异最常见的来源。核对两件事：能查到的账号属于哪些角色、所在知识空间；查不到的账号是否被可见范围排除。同时确认两人提问的是同一知识域、同一时间范围，排除过滤条件差异。如果可见范围配置一致但结果仍不同，再检查两人是否使用了不同的问法，以及切片是否对同一文档返回了不同片段。
改用原文关键词能查到，用自然语言问就查不到，说明什么？
说明知识已入库且当前账号可见，问题出在问法与文档表述的匹配上。常见原因是团队简称、英文缩写与文档正式表述不一致，或问法过于口语化缺少模块名、接口名、版本号等线索。处置上先补充同义词与缩写词表，再引导提问者补充具体标识。改动词表前记录原配置，改完用固定问题复测，确认没有引入新的误命中。
文档明明更新了，问答却还引用旧内容，怎么处理？
先确认知识库中该文档的入库状态与最近更新时间是否与源文档一致，同步滞后或重复文档未清理都会导致回答指向旧版本。处置时更新过期版本，清理重复与明确废弃的文档，使该主题只保留一份现行有效文档。若涉及批量重建索引，先备份配置、安排在低峰期执行，并设定停止点，出现命中率持续下降或大量报错时立即停止并回滚。
放开权限后检索恢复了，还需要注意什么？
按最小必要原则放开，只对需要该知识的角色开放对应空间，避免一次性全量开放，否则内部敏感文档会进入所有人的检索范围，事后收回成本高。改动前记录原可见范围配置以便回退。放开后用固定问题集回归，既验证目标问题恢复命中，也确认对照问题没有因权限扩大而出现不该有的结果。
怎么判断问题已经真正解决，而不是碰巧查到一次？
用一组固定的典型问题做回归，覆盖本次出问题的知识域，并保留此前能正常命中的问题作对照。对比处置前后的命中情况：原来无结果的能否返回正确内容，原来返回旧版本的是否指向现行文档，原来答非所问的是否切题。回归通过的标准是目标问题稳定命中、对照问题没有退化，且回答引用的文档版本与现行规范一致。
