ucn

UCN - 通用代码导航器

可审计的答案：统计每个匹配项，标记不确定项，并指出盲区。

如果你使用 AI Agent，可将 UCN 添加为 Skill 或 MCP 工具。一个工具 即可为 Agent 提供简洁且带有源代码链接的调用者、影响范围和测试问题答案， 并标明不确定之处，而非猜测。答案取决于已建立索引的源代码，而非提问者身份： 无论是在终端操作的人，还是通过 MCP 连接的 Agent，对同一问题都会获得相同记录。

概念概览 · 静态图片

可直接使用 CLI、安装 Agent 技能（无需服务）， 或通过 MCP 连接。三种方式使用同一个引擎：

  Terminal              AI Agents           Agent Skills
       │                    │                    │
      CLI                  MCP                 Skill
       └────────────────────┼────────────────────┘
                            │
                     ┌──────┴──────┐
                     │ UCN Engine  │
                     │  commands   │
                     │ tree-sitter │
                     └─────────────┘

UCN 使用 tree-sitter 抽象语法树（AST）进行静态代码分析， 无需编译项目或启动语言服务。CLI 按需运行并复用增量索引； MCP 则会让进程保持运行，以便重复查询。无需项目配置， 缓存存储在仓库之外。

支持 JavaScript、TypeScript、JSX/TSX、Python、Go、Rust、Java、C、C++、C#， 以及 HTML 内嵌脚本。

安装

npm install -g ucn                    # Node.js 20+

在终端中使用

在项目目录中：

ucn repo
ucn show handleRequest --lines
ucn source handleRequest --raw
ucn impact --staged --lines
ucn check --staged

repo 用于映射项目。show --lines 可定位调用者，source --raw 可获取实现，而 impact 和 check 可检查已暂存的更改。 名称存在歧义时，find 会返回 file:line:name 句柄，后续命令可使用该句柄。

--lines 返回 path:line:text 记录；--raw 返回源代码。 两者都适用于 Agent 现有的脚本，无需解析面向人的报告。

文本搜索仍适用于注释、配置、字符串以及不受支持语言中的代码。 如果任务需要列出所有出现位置（包括非调用项），usages 可提供字面名称清单。

代码导航与更改分析

show 会收集符号的签名、源代码、调用者、被调用者及相关上下文。 你可以选择所需部分，或设置输出预算，让答案聚焦重点。trace 会跨文件沿调用图追踪， 向下追踪被调用者，或向上追踪调用者直至入口点。未验证的关系仍会显示， 树状结构的统计信息会报告探索停止的位置。

impact 会将符号或 Git 差异与其调用者关联起来。tests 会沿已建立索引的调用和引用路径， 识别静态关联的测试，包括相隔多个跳数的关联。plan 会预览重命名或签名更改， 并提供源代码位置和审查事项；它不会编辑文件。这些命令共同支持在终端或 AI Agent 中 进行代码探索、重构和更改审查。

答案能够证明什么

对于调用方答案，UCN 会检查绑定、导入、接收者类型和所有权，以区分对所选定义的调用与名称相同的其他用法。证据不足的调用会继续显示为未经验证，并附上原因。仅方法名相同，并不能确定实际运行的是哪个实现；接收者和所有权证据决定如何对候选项进行分类。

在 ripgrep 的 82313cf9 中，所选的 file_name 辅助函数有 4 个已确认的调用位置和 1 个未经验证的候选项。此动画展示了全部 29 行匹配结果，以及 UCN 输出中的导入关系和同名定义。

捕获的查找结果 · 静态图片 · 数据

ACCOUNT 行会核对观察到的名称出现情况：已确认的调用、未经验证的候选项、非调用出现，以及归属于其他目标的匹配。每次出现都只计入一个类别，因此可以逐行核对总数，而非盲目信任。CONTRACT 描述了此核算的范围。警告会指出索引无法覆盖的源代码。这些详情即使在 Agent 的输出预算导致文本截断后仍会保留；如果预算小到无法容纳这些信息，系统就会暂不提供答案，并指出所需预算。

因此，空结果对已检查的代码有明确含义。它无法证明反射、生成的代码、运行时注册或外部使用方永远不会触及某个符号。deadcode 会提供待调查的候选项；删除前仍需佐证。重构预览仍需经过编译器和测试的验证。

准确性与验证

发布门槛会在包含 10 个固定生产代码库的测试集上，将 UCN 的回答与独立编译器和语言服务器进行比较。本地评估于 2026 年 10 月 4 日记录了以下抽样调用方结果：

该评估报告显示，调用方和被调用方答案中均没有遗漏范围内的预言机关系边；8,000 次跨命令比较中也没有任何分歧。默认死代码审计在 9 项已评分判断中发现零项误报死代码；另有 4 项判断无法由预言机确认，因此未计分。所有 10 个代码库均符合性能预算，稳态查询 p95 为 4.7 至 101.1 ms。这些耗时不包括进程启动和索引；冷构建和缓存加载会单独测量。

抽样具有确定性，并按引用活动分层。已确认精确率适用于已评分判断；召回率则统计在已确认或未验证区间中发现的范围内预言机关系边。未验证候选、预言机弃答和未评分结果分别统计。这些测量并不能证明具备完整的运行时知识，也不代表在每台机器上性能都相同。

定期测试集涵盖 25 个固定代码库：上述 10 个，以及 zod、express、hono、zustand、fastify、rich、click、attrs、grpc-go、chi、cursive、itertools、rayon、gson 和 jsoup。轮换式新代码库测试组会检查固定测试集之外的代码库。

代码库清单记录了完整提交。Publish 工作流用于把关发布；Eval 工作流则按计划运行检查，也可按需运行。对应的运行页面提供 CI 结果和评估产物。安装预言机依赖后，可在本地复现这些检查：

npm run verify
npm run trust:gate

命令

deps --cycles 会将循环依赖归类，并区分急切导入与延迟或仅类型边。它会说明枚举限制。repo 除了报告项目结构，还会报告源代码覆盖率；其 HOT 排名会准确统计已确认的生产环境调用方（仅当仓库非常大时，细化预算才会生效，并会予以说明），而 repo --sections=stats --hot 会按所有调用方排名。

endpoints --bridge 会匹配其框架提取器识别的服务端路由和客户端请求。当归属关系明确时，plan 会处理导入、重写以及接口或 trait 方法等代码关系；关系不明确时，则会保留为待审查项。

运行 ucn --help 查看标志，或使用命令参考。

Shell 输出

记录和代码输出到 stdout；统计信息和备注输出到 stderr。未经验证的 记录会附带以制表符分隔的原因。空列表以状态码 1 退出，错误以状态码 2 退出，成功列出结果则以状态码 0 退出。--lines 支持 find、show、 usages、search 和 impact；show --lines 默认列出调用方。 当脚本需要结构化字段或树形结果时，请使用 --json。

对于给定的源代码树，列表结果是确定的：全新构建、加载缓存和增量 重建都会以相同顺序返回相同记录。列表没有默认行数上限。显式限制会 说明省略了哪些内容，而 Shell 模式下超出字符预算会在写入部分输出前报错。 除非明确请求行数限制，否则 source --raw 会提取完整的函数和类；如果 因此发生截断，会在 stderr 上报告。

普通文本模式下的命令错误也以状态码 2 退出。对于成功但结果为空的情况， JSON 保持状态码 0；对于命令错误，则以状态码 1 退出（meta.ok: false 并附带 error）。UCN 内部发生异常时会报告 Internal error: ...（JSON 会添加 meta.internalError: true），绝不会将其作为有关代码的答案。 不带目标的 check 在 TRUST 为 BLOCKED 时以状态码 1 退出，其他已完成的 检查以状态码 0 退出，无法运行时则以状态码 2 退出。

除 --lines 外，find、文本模式的 search、deadcode、api 和 repo --sections=files 默认最多返回 500 条结果。文本模式下的 find 会详细显示前 5 条，并统计其余结果（JSON 最多返回 500 条）；--limit=N 会提高这两项上限。使用 --limit=N 可请求更多结果；除非指定限制或 --exclude-tests，否则 usages 会列出每个使用位置，包括测试文件。宽泛的 find 查询会先按近似使用总数筛选候选项，再计算由定义固定的调用方活动； 若有限制，还会说明这一筛选过程。

名为 *.min.js、*.bundle.js 和 *.map 的文件会作为跳过的源文件报告， 并使完整性状态变为部分完整。--include-bundled（MCP include_bundled=true）会在遵守用户排除规则的同时索引 JavaScript 包； 此选项会绕过共享缓存。源映射仍会予以说明，但不会被索引。

AI 设置

一个工具、18 条命令，可提供精简且关联到源代码的答案，即使答案被截断， 也会保留信任元数据。

MCP

# Claude Code
claude mcp add ucn -- npx -y ucn --mcp

# OpenAI Codex CLI
codex mcp add ucn -- npx -y ucn --mcp

# VS Code Copilot
code --add-mcp '{"name":"ucn","command":"npx","args":["-y","ucn","--mcp"]}'

{
  "mcpServers": {
    "ucn": {
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

{
  "servers": {
    "ucn": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

Agent Skill（无需服务）

macOS / Linux：

# Claude Code
mkdir -p ~/.claude/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/

# OpenAI Codex CLI
mkdir -p ~/.agents/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/

Windows PowerShell：

$npmRoot = npm root -g
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.claude\skills\"

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.agents\skills\"

此技能会指导 Agent 如何了解项目概况、固定符号、选择最精简且实用的 命令、解读证据层级，以及从不完整的答案中恢复。它是在同一引擎之上的 指导，而非第二套实现。

范围

UCN 会分析一个项目中已索引的源代码。它不会执行程序，也不会索引 node_modules 和 site-packages 等已安装的依赖项。repo --sections=health --deep 会报告源代码覆盖情况和已知的分析限制。

C 和 C++ 可以使用 compile_commands.json 获取包含路径和头文件上下文， 但 UCN 不会运行预处理器，也不会复现特定于编译器构建的视图。C# 源代码 生成器和外部程序集也不在索引范围内。HTML 有回归测试覆盖，但没有编译器／LSP 仓库验证基准。

CLI、MCP 和技能共享相同的解析规则和证据。更改传输方式不会改变引擎对代码 的了解。

MIT