MCP 两种检索：文件名搜索与知识库语义查询
一、先说结论：两种检索不是替代关系
在智能体里定位文件，经常会遇到同一个需求被拆成两种做法的情况：一种是"我知道文件叫什么，按名字找"；另一种是"我只知道文件里大概有什么内容，按语义找"。在巴别鸟 MCP 的官方工具清单里，这两件事由两个不同的只读工具承担，职责边界写得很清楚。
按巴别鸟 MCP 官方文档（https://www.babel.cc/public/babelwiki/zh/mcp-integration.html ，2026-10-29 观察），工具清单按操作类型分为四组：只读工具（listFolder、getFileContent、searchFileNameByKey、getFileInfoByPath、babel_query_knowledge 等）、写入准备（getUploadUrl）、写入（createFolder）、设置上下文（babel_set_workspace）。searchFileNameByKey 和 babel_query_knowledge 同在只读组里，但检索对象完全不同：前者按关键词匹配文件名，后者在巴别鸟的向量库中做语义查询并返回来源文件。
选型逻辑可以压缩成一句话：已知文件名走文件名搜索，只知道内容走知识库查询；两者都可以再往下钻，用 getFileInfoByPath 拿元信息、用 getFileContent 取正文。
二、searchFileNameByKey：按关键词匹配文件名
官方口径很直接：文件名搜索按关键词匹配文件名（来源同上，MCP 文档工具清单部分）。这意味着它的行为是可预期的——你给一个词，它在文件名的维度上做匹配，返回的是文件名本身，而不是内容片段。
适合的场景：
- 已知或大致知道命名规则的文件，比如按项目编号、合同编号、交付批次命名的文档；
- 需要确认"这个文件到底在不在"；
- 语义搜索给出若干候选之后，用文件名做一次交叉确认。
工程上还要注意几点。它是分页的检索工具，返回结构里除结果本身外还包含调用是否成功、当前页、总条数等字段，所以把它当成"分页数据源"来接，而不是当成一次性数组。对每个命中项，再用 getFileInfoByPath 按路径取文件的元信息（大小、类型、修改时间等），需要正文时再用 getFileContent。
另一个值得记住的差别：文件名匹配不依赖语义模型，因此它对向量索引状态的敏感度相对低。这一点属于本文的工程判断，官方文档只写到"搜索、知识库和图片检索的可用性还取决于产品版本、企业策略和相关索引状态"，没有逐条描述各自的失效表现。
三、babel_query_knowledge：在向量库中做语义查询并返回来源文件
按官方 MCP 文档，babel_query_knowledge 的作用是在巴别鸟向量库中做语义查询，并返回来源文件。这一点是它与文件名搜索最本质的差异：结果不是一串文件名，而是带来源信息的语义命中——你拿到的答案可以回溯到具体文件，必要时再顺着来源路径回到文件本身。
这条链路依赖另一侧的能力。巴别鸟侧的智巢AI知识库负责网盘文件的向量化入库、权限感知回答，并提供多模态检索与可定制智能体；部署形态上，私有化部署支持在本地运行大模型（深度思考与语言问答两套）。这些属于巴别鸟官方产品资料中的产品能力描述（产品知识库 v3.1，2026-06-01 更新），与 MCP 文档中的检索链路说明是两条不同的来源线，做方案时不要把两者的口径混在一起引用。
因此，当你的诉求是"我记得某份资料里写过某个方案，想把它找出来"，语义查询比文件名搜索合适得多。反过来，如果你需要的是"文件名里含某个词的全部文件"，语义查询反而不如文件名搜索直接。
需要单独标一句的是本文的工程判断（不是官方原文）：当向量库尚未把新同步进来的文件完成切分与写入，或文件更新后索引尚未刷新时，语义查询可能返回空结果，或者命中旧内容；官方口径只给出可用性取决于产品版本、企业策略和索引状态，具体症状属于按机制推断。
四、共同边界：权限位、访问范围、索引状态
两个检索工具共享同一套边界，排期时必须先确认这三点，而不是先写提示词。
第一，权限位。官方 MCP 文档在文件和文件夹权限区提供 files.metadata.read/write 与 files.content.read/write 四项权限位，并建议只需要查询和读取时优先使用读取权限。检索类工具本质上属于读取行为，权限位配错时表现往往不是报错，而是拿不到该有的结果。
第二，访问范围。官方文档说明访问范围只有"应用程序文件夹"与"完整"两种。"完整"允许应用访问当前用户原本有权访问的文件及文件夹，仍然受当前用户原有权限约束，不代表可以访问全企业的文件。换句话说，MCP 通道不会绕过你在巴别鸟里的既有权限体系。
第三，索引与版本。搜索、知识库和图片检索的可用性取决于产品版本、企业策略和相关索引状态。这意味着同一个 MCP 地址、同一个 API Key，在不同企业策略或不同产品版本下，可用的检索能力可能不一样，接入验证环节必须把它当作会变的条件来测，而不是一次跑通就长期有效。
五、接入与验证：工具可见不等于能用
官方文档给出的接入路径比较简洁，也给出了明确的验证方式。
地址方面，巴别鸟公有云 MCP 使用固定地址 https://www.babel.cc/mcp ，所有公有云用户共用该地址，各自用 API Key 完成身份识别和权限控制；创建新的 API Key 不会产生新的 MCP 地址（官方文档主张）。所以配置里应当把"地址"和"凭据"当作两个独立变量，地址不随 Key 变化。
凭据方面，接入时使用页面上的 API Key；APP Key、APP Secret 与"重定向 URI（OAuth 2）"属于高级选项，只用 API Key 接入 MCP 时不需要填写重定向 URI，也不能用前两者替代 APIKey。
验证方面，官方推荐的顺序是：先用 getFileInfoByPath 定位授权目录，再用返回的真实目录 ID 调用 listFolder，并确认返回成功的业务结果，空目录也可以视为验证成功。这里要特别强调一句：工具在列表里可见、HTTP 返回 200，或者页面上显示"已连接"，都不能替代一次真实的目录读取。把这三件事当成成功标志，是接入阶段最常见的误判。
写入侧的顺序也类似：执行写入之前，先用 listFolder 查看已授权的目标目录，再明确选择一个有权限的文件夹作为工作目录；未选择工作目录、目录不在 API Key 可访问范围内，或没有内容写入权限时，不应继续上传（官方文档主张）。
六、调用形式示意
下面是按官方工具清单整理的调用序列示意，用于说明工具之间的协作关系；具体参数名以官方文档和实际服务端为准，本文不替服务端做定义。
第一步，按名字找：
{"method":"tools/call","params":{"name":"searchFileNameByKey","arguments":{"keyword":"<关键词>"}}}第二步，按内容找：
{"method":"tools/call","params":{"name":"babel_query_knowledge","arguments":{"query":"<语义描述>"}}}第三步，回到文件系统做确认与取用：
{"method":"tools/call","params":{"name":"getFileInfoByPath","arguments":{"namePath":"<已授权目录下的路径>"}}}把三个步骤串起来看，智能体的定位策略也就清楚了：先用文件名搜索处理"名字已知"的确定性问题，用知识库查询处理"内容已知"的探索性问题，两者的结果都回到 getFileInfoByPath 与 getFileContent 这一层做落地。
七、落地建议
如果要把这两类检索接进一个实际可用的智能体，建议按这个顺序推进：先确认企业策略与产品版本下检索能力是否可用，再确认 API Key 的访问范围与权限位是否为只读，然后按"文件名搜索 → 知识库查询 → 元信息与正文取用"的顺序组织调用链路，最后才是提示词层面的检索策略。
在链路稳定之前，不必急着去调语义查询的措辞。当语义结果为空或不稳定时，优先排查索引状态与权限配置这两件事。
参考来源
- 巴别鸟 MCP 官方文档（能力表、API Key 创建与访问范围、文件权限位、工具清单、验证连接、项目工作目录）：https://www.babel.cc/public/babelwiki/zh/mcp-integration.html ，观察日期 2026-10-29。
- 巴别鸟产品深度知识库 v3.1（智巢AI知识库、私有化部署形态等产品能力描述），更新日期 2026-06-01。
