Ummon

██╗   ██╗███╗   ███╗███╗   ███╗ ██████╗ ███╗   ██╗
██║   ██║████╗ ████║████╗ ████║██╔═══██╗████╗  ██║
██║   ██║██╔████╔██║██╔████╔██║██║   ██║██╔██╗ ██║
██║   ██║██║╚██╔╝██║██║╚██╔╝██║██║   ██║██║╚██╗██║
╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║╚██████╔╝██║ ╚████║
 ╚═════╝ ╚═╝     ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═══╝

"WHAT ARE THE ACTIVITIES OF A SYSTEM?
 I HAVE NOT THE SLIGHTEST IDEA.
 THE PATH APPEARS"

⚠️ 警告：此项目仍处于早期开发阶段，尚不稳定。不同版本之间的 API 和功能可能会有重大变化。

Ummon 是一款代码分析工具，可从代码库构建知识图谱，以增强理解、改进 AI 助手，并支持复杂查询。它会在代码实体（函数、类、模块）与领域概念之间建立关联，让复杂软件系统更易于分析，并帮助识别特定任务所需的相关代码。

本项目以 Dan Simmons 的《海伯利安诗篇》中的 AI Ummon 命名，旨在深入洞察代码库，帮助人类和 AI 助手更好地理解软件系统。

核心功能

1. 知识图谱构建

   • 为代码编制索引，以创建语义表示
   • 映射代码实体之间的关系（调用、导入、依赖）
   • 支持多种语言（Rust、Python、JavaScript、Java）
   • 支持增量更新和完整重建
   • 跟踪文件修改，以尽量减少重复处理
   • 更多详情请参阅知识图谱文档

2. 高级查询系统

   • 使用功能强大的结构化查询语言或自然语言查询代码库
   • 两种主要查询类型：
     • 选择查询：select [entity_type] where [conditions]
     • 遍历查询：[source_type] [relationship] [target_type] where [conditions]
   • 支持自然语言转换，便于用户交互
   • 提供丰富的筛选功能，包括属性条件和逻辑运算符
   • 支持多种输出格式（文本、JSON、CSV、树形）
   • 示例："select functions where name like 'auth%'"、"显示所有身份验证函数"
   • 更多详情请参阅查询系统文档

3. 相关性 Agent

   • 推荐与拟议更改或查询相关的代码文件
   • 使用语义分析从自然语言描述中提取技术关键词
   • 利用实体关系在知识图谱中识别相关实体
   • 根据邻近度和图中心性指标评估文件的相关性
   • 提供按相关性排序的文件列表，实现上下文感知的辅助
   • 示例：对于“修复身份验证漏洞”，它会识别与身份验证相关的文件
   • 更多详情请参阅相关性 Agent 文档

4. 领域模型提取

   • 使用大模型识别业务实体和概念
   • 将领域概念映射到实现细节
   • 在技术理解与业务理解之间搭建桥梁
   • 更多详情请参阅领域提取文档

安装与设置

cargo install ummon

使用方法

# Index a codebase (performs incremental update by default)
ummon index /path/to/codebase

# Perform a full rebuild of the knowledge graph
ummon index /path/to/codebase --full

# Index with domain model extraction enabled
ummon index /path/to/codebase --enable-domain-extraction

# Specify a custom domain directory for extraction
ummon index /path/to/codebase --enable-domain-extraction --domain-dir models/

# Query using natural language
ummon query "show all authentication functions"

# Query using structured query language
ummon query "select functions where name like 'auth%'" --no-llm

# Find relationships between entities (traversal query)
ummon query "functions calling functions where name like 'validate%'" --no-llm

# Query with different output formats
ummon query "select functions" --format json
ummon query "select functions" --format csv
ummon query "select functions" --format tree

# Filter query results by type
ummon query "find api" --type-filter function

# Filter by file path pattern
ummon query "show all entities" --path src/auth

# Limit the number of results
ummon query "select functions" --limit 10

# Skip LLM processing for structured queries
ummon query "select functions where file_path like 'src/auth/%'" --no-llm

# Generate AI-assisted recommendations
ummon assist "implement a user registration function"

# Get relevant file suggestions for a proposed change
ummon assist --suggest-files "fix authentication token validation"

配置

Ummon 仅使用环境变量存储敏感信息：

• OPENROUTER_API_KEY：大模型服务的 API 密钥（查询和领域提取所需）

其他所有配置均通过命令行标志处理。

架构

Ummon 采用模块化架构构建：

• 用于代码分析的特定语言解析器
• 用于存储实体和关系的基于图的存储
• 使用元数据跟踪实现高效更新的 SQLite 数据库
• 用于增量编制索引的智能更新机制
• 用于语义理解的大模型集成
• 用于上下文感知辅助的相关性 Agent
• 用于用户交互的命令行界面

语言支持

Ummon 支持解析和分析多种编程语言：

• Rust：类/结构体、trait、实现、函数、模块
• Python：类、函数、装饰器、导入
• JavaScript：类、函数、箭头函数、导入
• Java：类、接口、方法、构造函数、字段

Java 解析器支持解析：

• 带修饰符的类和接口定义
• 构造函数声明
• 带参数类型的方法声明
• 带类型的字段声明
• 包声明和导入（包括通配符导入和静态导入）
• 提取文档注释
• 方法调用和关系

知识图谱更新

Ummon 提供两种更新知识图谱的方式：

增量更新（默认）

不带 --full 标志运行时，Ummon 将执行增量更新：

• 跟踪上次索引操作的时间戳
• 根据文件修改时间检测自上次索引后修改的文件
• 仅删除与修改文件关联的实体和关系
• 仅重新索引修改过的文件，同时保留图谱的其余部分
• 对于改动较小的大型代码库，速度显著更快

完全重建

带 --full 标志运行时，Ummon 将执行完全重建：

• 清除数据库中的所有实体和关系
• 从头开始重新索引整个代码库
• 适用于重大更改后，或图谱可能处于不一致状态时

文档

如需更详细的文档，请参阅：

• 入门指南：安装和快速入门指南
• 功能文档：各项功能的详细文档
• CLI 参考：完整的命令行参考
• 配置：配置选项和最佳实践

开发

构建和测试命令

# Build the project
cargo build

# Run the project
cargo run

# Run with specific command
cargo run -- index .              # Incremental index of current directory
cargo run -- index . --full       # Full rebuild of the knowledge graph
cargo run -- query "show funcs"   # Query the knowledge graph

# Run tests
cargo test
cargo test -- --nocapture  # Show test output
cargo test <test_name>     # Run specific test

# Format code
cargo fmt

测试资源

• test/java/：用于解析器测试的 Java 测试文件
  • Test.java：用于基础解析的简单 Java 类
  • ComplexExample.java：包含高级 Java 特性（泛型、注解等）的示例
• test/javascript/：用于测试的 JavaScript 测试文件

许可证

APACHE 许可证