navigator

mentu-navigator

面向人类和 AI Agent、只读且优先考虑来源信息的代码仓库导航工具。

指定一个代码仓库并提出问题。它会返回按相关性排序的文件与行范围，并说明每项结果的排序原因；它绝不会写入所读取的代码仓库。它专为这样的 Agent 而构建：必须在文档繁多的代码仓库中找到能够回答问题的文档，却不能将整个仓库都载入上下文。同时，它也适用于审核这些 Agent 操作的人。

范围。 默认排序在文档语料上进行了评估：针对 Markdown 语料，在预先注册的研究中进行（见 证据）。它尚未在源代码上进行评估；已发表的比较研究显示，其他定位工具在源代码上表现更佳（见 证据范围）。代码结构命令（map、symbol、impact）适用于任何代码仓库，但其效果尚未经过评估。

mentu-navigator 是产品名称。mentu-nav 是其简短 CLI 名称。

安装

需要 Node.js 20 或更高版本。

npm install -g mentu-navigator     # CLI: mentu-nav, MCP server: mentu-navigator-mcp

如需在不安装的情况下运行：

npx -p mentu-navigator mentu-nav "where is retry handled?"

包名和命令名不同，因此仅运行 npx mentu-navigator 无法解析到可执行文件。请按上文所示传入 -p。

许可证：Apache-2.0。遥测数据仅以 JSONL 格式保存在本地的 ~/.mentu/pd1/ 下（规范：docs/TELEMETRY-SPEC.md）；可通过 MENTU_NAV_TELEMETRY=off 禁用。任何数据都不会离开本机。

在 Mentu 中的定位

mentu-navigator 是检索入口。 mentu-pdv 用于验证本工具所使用的 frontmatter 架构，并生成 locate 所应用的降级集合。二者配套设计，架构规范已公开发布 （SPEC-frontmatter.md）。

存在的意义

搜索工具能够查找匹配文本。代码仓库导航工具还会保留问题的意图，并返回相关的契约、测试、文档、Git 沿袭记录和风险面，帮助用户安全地采取行动。

首个版本刻意采用确定性设计：

• 不使用嵌入；
• 不建立后台索引；
• 不写入目标代码仓库；
• 按需生成有界的 frontmatter 句柄，用于指向文档，但绝不取代阅读文档；
• 提供带文件和行号来源信息的有界片段；
• 在读取内容前排除已知包含机密的路径。

一条命令即可开始

cd /path/to/repository
mentu-nav
mentu-nav "where is DEMO-274 implemented and tested?"

交互式终端会显示简洁的人类可读视图。管道会接收精简 JSON； --json 用于请求完整封装。 Agent 应使用 --agent 获取精简且节省令牌的 JSON 契约：

mentu-nav --agent "where is DEMO-274 implemented and tested?"

入口会自动路由到 map、query、handles、symbol 或 impact。仍可使用对应的显式命令执行脚本和高级操作。

用于 docs-as-code 网络：

mentu-nav handles "catalog lineage"

此命令会返回元数据指针、类型化关系和诊断信息。每个指针都带有 requiresHydration: true。query 会将这些指针与源正文证据分开，因此摘要不会悄然取代答案。

功能

功能	回答的问题	证据
map	这里有什么？	文件、语言、契约、清单、类型化文档、Git 状态
query	相关证据在哪里？	按相关性排序的路径／行号／片段命中结果及路由原因
locate	我应该阅读哪些范围？	按 BM25 排序的命中结果及检索器归因（有证据支持的默认设置）
read-range	该范围说了什么？	按标题界定的片段，frontmatter 单独返回
handles	哪些文档和类型化关系可能相关？	frontmatter 指针、关系解析、诊断信息；需要进行内容补全
symbol	该符号周围有哪些内容？	定义、引用、测试、文档、配置
impact	此更改可能影响什么？	Git 范围、工单、契约、测试、风险信号

渐进式披露：locate 和 read-range

locate 是 Agent 接口。其默认分支是排名词法检索（BM25）。这个默认值由预注册研究确定，而非凭个人偏好（见下文的证据）。目前有两条路径：

• 排名词法路径：对遍历器已生成的同一组文件执行内存中的 Okapi BM25，使用随附的 Spanish 和 English Snowball 词干提取器，并根据每份文档的 lang frontmatter 标签进行路由（检测结果作为回退方案，并会记录日志，绝不会写入）；
• 精确路径：语义保持不变的确定性 query 流程。

融合分支（将两条路径的排名进行倒数排名融合）作为测量分支存在。它最初是默认分支，但在预注册的对比测试发现其定位效果比纯 BM25 低 7.8 个百分点后，根据其自身的预注册消融规则，将其从默认路径中移除（见证据）。每条命中都会说明是由哪条路径（或两者）检索到的。

mentu-nav locate "compaction policy" --k 8
mentu-nav read-range docs/adr/ADR-014-ledger-compaction.md 38 62 --widen 1

locate 返回 {path, line, range, snippet, score, retriever, why}。这是待读取的范围，而不是答案。read-range 返回该片段；每个 --widen 步骤都会进一步扩展 ±20 行，并在包围它的标题边界处停止；frontmatter 会作为独立字段返回，以免将元数据误认为正文证据。句柄仍是指针层，保持不变：每个指针仍携带 requiresHydration: true。

固定参数

这些是设计参数，而非实现细节。每个参数都会作为一项消融进行注册和测量；更改任一参数，都需要作出带日期的决策并重新测量。

参数	值	控制内容
LOCATE_DEFAULT_K	8	locate 默认返回的命中数
LOCATE_MAX_K	40	k 的上限，无论调用方请求多少
SNIPPET_MAX_CHARS	240	片段长度，空白字符会规范化为单行
WIDEN_STEP_LINES	20	read-range 每次扩展的行数
RRF_K	60	倒数排名融合常数
DEMOTION_MULTIPLIER	0.5	应用于降权文档的惩罚系数

旧版 query 命令保留其面向用户的默认结果数 40；上述固定参数适用于 locate。

降权

--demotions <path> 会读取 pdv demotions JSON 文件（相对于仓库根目录解析），并将这些文档的分数乘以 0.5。降权文档的排名会降低，但绝不会被移除。文档不可用会造成更大的问题。无法读取或格式错误的降权集合会在封套诊断信息中报告，而不会被静默忽略。

--retriever 用于测量

--retriever=bm25|exact|fused 用于选择一个分支（默认为 bm25）。它的作用是让预注册对比测试的各个分支由已发布的代码路径生成，而不是通过测试框架的分叉版本生成。这里的默认值正是通过这种方式确定的。此标志不是调优旋钮。

证据

此工具中每个与性能相关的默认设置都可追溯至一项已注册、经机械化裁定的研究，以下每项结论都注明了适用范围：一个包含 141 份文档的双语运维文档语料库、一组全新的 115 道盲测题，以及本工具的 k=8 契约。对比测试 （doi:10.5281/zenodo.21969901， doi:10.5281/zenodo.21960138 的配套研究）：

• BM25 在 93.0% 的问题中定位到了标准答案文档，而经过强化的精确搜索为 71.3%（McNemar p < 1e-5）。因此默认使用 bm25。
• 融合方案比单独使用 BM25 低 7.8 个百分点（p = 0.0225），未能通过预先冻结的“融合绝不会降低定位效果”预测；预注册的消融规则将其从默认路径中移除 （docs/build/D3-REVISION-2026-08-16.md）。
• 现成的 SQLite FTS5 对照组（89.6%）与此实现之间没有统计学上的显著差异。效果提升来自 BM25 本身。
• 使用更好的定位器后，下游答案准确率提高了 5.2 个百分点，几乎完全归因于定位效果。

本文不主张这些结论适用于该类语料库之外的情形；上述 DOI 中公开了研究、语料清单、问题集和裁定器，可供重新运行。

证据适用范围

这些默认设置所依据的所有研究都使用了 Markdown 文档；没有一项研究使用源代码，这一区别很重要。根据问题描述查找需要修改的文件，是一项文本重合度较低的任务；已发表的比较表明，在这类任务中，BM25 的排名低于嵌入检索。在 SWE-bench Lite 中，BM25 有 61.7% 的概率将正确文件排在前五位，而基于代码嵌入的检索器为 84.7% （Chen 等人，LocAgent，表 4）。因此：

• 对于可由文档（如运维手册、ADR、规范）回答的问题，使用 locate，然后读取它返回的范围；
• 对于根据问题或行为描述查找代码的任务，在有针对代码的研究之前，优先使用你的运行框架原生搜索或具备代码感知能力的定位器；
• 已拟定一项预注册比较研究：在实际运行的 Agent 中，将此工具与运行框架的原生工具进行比较，并设置代码定位分层。该研究尚未开展。完成后，本节将如实报告结果。

每次提交时，测试套件还会验证以下事项：索引不会向目标仓库写入任何内容，并在进程运行期间驻留于内存；相同的语料库和查询在不同运行及重建索引后都会产生字节级一致的命中列表；包含机密的路径会在分词前而非分词后排除；以 - 开头的搜索模式会放在字面量 -- 之后传入，因此绝不会被解析为引擎标志。

MCP

mentu-navigator-mcp 提供：

• navigator：优先使用的精简自动路由入口
• locate：按 BM25 排序的范围，支持 retriever 和 demotions
• read_range：locate 移交给它的披露步骤
• navigator_map
• navigator_query
• navigator_handles
• navigator_symbol_context
• navigator_change_impact

MCP 客户端配置：

{
  "mcpServers": {
    "mentu-navigator": {
      "command": "npx",
      "args": ["-y", "-p", "mentu-navigator", "mentu-navigator-mcp"]
    }
  }
}

或者直接启动已安装的二进制文件 mentu-navigator-mcp。

Agent 设置

mentu-nav setup --target all
mentu-nav doctor --human

设置过程会将捆绑的技能链接到 Codex 和 Claude，而不会复制其逻辑。它不会替换现有路径。仓库导航本身仍为只读。

采用方式

可执行文件仍集中管理。仓库只需采用简短的操作契约，无需复制实现。参见 docs/adoption.md。