ontomics

ontomics

ontomics 让任何编码 Agent 即时了解你的代码库。只需调用一次工具，而非 19 次。令令牌用量减少约 20 倍。

https://github.com/user-attachments/assets/01afa8a0-1bc2-4686-94d7-965fef7610c3

voxelmorph 项目的可视化——一个用于图像配准无监督学习的库

基准测试

使用 Claude Sonnet 测试——同一个问题，分别在使用和不使用 ontomics 的情况下进行。

在 voxelmorph 中提问“此代码库中的‘transform’是什么意思？”（完整对话记录）：

	使用 ontomics	不使用
工具调用数	1	19
令牌数	~3.7k	~76k
耗时	5s	1m 15s
回答质量	完整	完整

在 ScribblePrompt 中提问“此代码库中的主要领域概念有哪些？”（完整对话记录）：

	使用 ontomics	不使用
工具调用数	1	26
令牌数	~3.7k	~61.6k
耗时	~5s	56s
回答质量	完整	完整

两种情况下都得到了完整、正确的回答。ontomics 只用一次调用就完成了任务。

搜索做不到的事

搜索会告诉你某个字符串出现在哪里。LSP 会告诉你某个符号的定义和引用位置。但两者都无法回答：此代码库中有哪些领域概念？它们之间有什么关系？形成了哪些命名惯例？自上次发布以来，领域词汇有哪些变化？哪些函数行为相似，而不论它们的名称是什么？

ontomics 会构建项目领域的语义索引——将相关符号聚类为概念，根据使用频率检测命名惯例，解析缩写，按行为相似性对函数分组，并跟踪词汇随时间的演变。该索引可导出为可移植的成果，用于在其他代码仓库中引入这些惯例。

行为相似性

除了命名和概念之外，ontomics 还会使用 CodeRankEmbed（768 维、对比式代码检索）嵌入原始函数体，并按行为相似性进行聚类。这能揭示命名和调用图都无法呈现的关系：

❯ What functions behave like spatial_transform()?

  random_transform()   nn/functional.py:352   0.80
  spatial_transform()  functional.py:596      0.69
  random_transform()   functional.py:1399     0.67
  random_disp()        nn/functional.py:275   0.65
  integrate_disp()     functional.py:764      0.65
  compose()            nn/functional.py:216   0.63
  disp_to_trf()        functional.py:343      0.62

结果还显示，random_transform 出现在两个位置，且相似度分数不同——这表明存在实现重复，而概念级搜索完全无法发现这一点。

安装

只需安装一次，即可在每个项目中使用。无需配置——ontomics 会自动检测代码仓库，并在首次运行时为其建立索引。

ontomics 需要 Git 代码仓库（.git/ 目录）。它会拒绝为主目录、根目录或临时目录建立索引。若要为非 Git 目录建立索引，请传入 --force。

1. 安装二进制文件

npm（macOS/Linux）：

npm install -g @ontomics/ontomics

macOS（Homebrew）：

brew install EtienneChollet/tap/ontomics

Shell 安装程序（macOS/Linux）：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/EtienneChollet/ontomics/releases/latest/download/ontomics-installer.sh | sh

从源代码安装：

git clone https://github.com/EtienneChollet/ontomics.git
cd ontomics
cargo build --release

2. 在你的运行环境中注册

Claude Code：

claude mcp add -s user ontomics -- ontomics

Codex：

codex mcp add ontomics -- ontomics

OpenClaw：

openclaw mcp set ontomics '{"command":"ontomics"}'

pi-coding-agent：

pi install npm:@ontomics/ontomics

与团队共享 — 在代码库根目录中放置一个 .mcp.json：

{
  "mcpServers": {
    "ontomics": {
      "command": "npx",
      "args": ["-y", "@ontomics/ontomics", "--repo", "."]
    }
  }
}

支持的语言

Python、TypeScript、JavaScript、Rust。根据文件扩展名自动检测。

工具

概念与词汇

工具	功能
query_concept	查找某个术语的所有变体、相关概念和出现位置
locate_concept	查找某个概念对应的关键签名、类和文件
describe_symbol	获取函数或类的签名、文档字符串和关系
trace_concept	通过调用链追踪某个概念在代码库中的流转
list_concepts	按出现频率列出主要领域概念
list_conventions	列出所有检测到的命名模式（前缀、后缀、转换）
list_entities	按概念、角色或类型筛选并列出代码实体（类、函数）
check_naming	根据项目约定检查标识符，并建议规范形式
suggest_name	生成符合项目词汇的标识符名称
vocabulary_health	衡量约定覆盖率、命名一致性和聚类凝聚度
ontology_diff	显示自某个 git 引用以来新增、更改或移除的领域概念
export_domain_pack	将领域知识导出为可移植的 YAML，供其他代码库使用

行为相似性

工具	功能
find_similar_logic	查找行为相似的函数实现，并按嵌入相似度排序
describe_logic	获取函数的行为描述、函数体文本和逻辑聚类成员信息
compact_context	为符号组装分层上下文（概念 + 逻辑），并针对大模型使用进行优化

代码库结构

工具	功能
describe_file	概述文件中的实体、概念和关系
concept_map	展示各模块包含哪些领域概念
type_flows	展示主要类型以及数据如何在代码库中流转
trace_type	追踪特定类型在文件和调用位置之间的传播

资源

资源	功能
ontomics://briefing	会话简报：主要约定、缩写、关键概念、对比术语对和词汇警告。也可通过 ontomics briefing CLI 获取。

工作原理

ontomics 会在你的机器上运行多阶段流水线，无需 API 密钥：

1. 解析 — tree-sitter 从源文件中提取每个标识符、签名和调用位置
2. 分析 — TF-IDF 评分识别领域专属概念并检测命名约定
3. 嵌入（概念） — BGE-small（384 维）按语义相似度聚类相关概念
4. 嵌入（逻辑） — CodeRankEmbed（768 维）嵌入原始函数体，并按行为相似度进行聚类
5. 中心性 — PageRank 根据结构重要性为实体评分

两种嵌入模型都会在首次运行时下载一次，并缓存在本地。索引位于 <repo>/.ontomics/index.db — 后续启动时会从缓存加载，并监视文件更改。

通过代码库根目录中的 .ontomics/config.toml 进行配置。所有字段均有合理的默认值。完整设计规范请参阅 SPEC.md。