基于 Git 的语义版本控制工具。
与按行比较不同，sem 能告诉你哪些代码实体发生了变化：函数、方法、类。

为什么选择 sem？ · 安装 · 命令 · MCP 服务器 · 发布记录

sem 是一款基于 Git 的语义版本控制工具。它使用 tree-sitter 解析你的代码，将每个函数、类和方法提取为独立的代码实体，并在实体级别进行差异比较，而不是逐行比较。这意味着你会看到“函数 blahh 被修改”而不是“第 x 行到第 y 行发生了变化”。

它可以在任何 Git 仓库中直接使用，无需额外配置。

安装

brew install sem-cli

或者将 npm 包安装到 node_modules 中：

npm install --save-dev @ataraxy-labs/sem

如果你使用 Bun，需要信任该包以便其 postinstall 脚本能下载二进制文件：

bun add -d @ataraxy-labs/sem
bun pm trust @ataraxy-labs/sem

你也可以从源码构建（需要 Rust）：

git clone https://github.com/Ataraxy-Labs/sem
cd sem/crates
cargo install --path sem-cli

或者直接从 GitHub Releases 下载预编译的二进制文件。

此外，还可以通过 Docker 运行：

docker build -t sem .
docker run --rm -it -u "$(id -u):$(id -g)" -v "$(pwd):/repo" sem diff

命令

sem 可以在任何 Git 仓库中使用，无需任何配置。它同样适用于非 Git 环境中的任意文件比较。

sem diff

实体级别的差异比较，支持重命名检测、结构化哈希以及单词级别的内联高亮。

# 工作区更改的语义差异
sem diff

# 仅暂存区的更改
sem diff --staged

# 指定提交
sem diff --commit abc1234

# 提交范围
sem diff --from HEAD~5 --to HEAD

# 详细模式（每个实体的单词级内联差异）
sem diff -v

# 纯文本输出（类似 git status 格式）
sem diff --format plain

# JSON 输出（适用于 AI 代理、CI 流水线）
sem diff --format json

# Markdown 输出（适用于 PR、报告）
sem diff --format markdown

# 比较任意两个文件（无需 Git 仓库）
sem diff file1.ts file2.ts

# 从标准输入读取文件变更（无需 Git 仓库）
echo '[{"filePath":"src/main.rs","status":"modified","beforeContent":"...","afterContent":"..."}]' \
  | sem diff --stdin --format json

# 仅针对特定文件类型
sem diff --file-exts .py .rs

sem impact

跨文件依赖图展示了当某个代码实体发生变化时，哪些部分会受到影响。

# 全面的影响分析
sem impact authenticateUser

# 仅显示直接依赖
sem impact authenticateUser --deps

# 仅显示直接被依赖者
sem impact authenticateUser --dependents

# 仅显示受影响的测试
sem impact authenticateUser --tests

# JSON 输出
sem impact authenticateUser --json

# 按文件细化结果
sem impact authenticateUser --file src/auth.ts

sem blame

实体级别的代码归属追踪，显示每个函数、类或方法的最后修改人。

sem blame src/auth.ts

# JSON 输出
sem blame src.auth.ts --json

sem log

跟踪单个代码实体在整个 Git 历史中的演变过程。

sem log authenticateUser

# 详细模式（显示各版本之间的内容差异）
sem log authenticateUser -v

# 限制扫描的提交数量
sem log authenticateUser --limit 20

# JSON 输出
sem log authenticateUser --json

sem entities

列出文件中的所有代码实体及其类型和所在行范围。

sem entities src/auth.ts

# JSON 输出
sem entities src.auth.ts --json

sem context

为大模型量身定制的上下文信息：目标代码实体、其依赖项和被依赖项，可根据指定的 token 预算进行裁剪。

sem context authenticateUser

# 自定义 token 预算
sem context authenticateUser --budget 4000

# JSON 输出
sem context authenticateUser --json

设置为默认的 Git diff

用实体级别的差异替换 git diff 的输出。无论是自动化工具还是人工操作，都会自动获得 sem 的输出，而无需更改任何命令。

sem setup

现在，git diff 将显示实体级别的变更，而非逐行差异。无需任何提示，也无需额外配置代理。所有调用 git diff 的地方都会自动使用 sem 的输出。此外，还会安装一个 pre-commit 钩子，用于展示暂存区更改所影响的实体范围。

若要恢复为正常的 Git diff：

sem unsetup

解析的内容

通过 Tree-sitter 实现完整实体提取的 23 种编程语言：

语言	扩展名	实体
TypeScript	.ts .tsx .mts .cts	函数、类、接口、类型、枚举、导出
JavaScript	.js .jsx .mjs .cjs	函数、类、变量、导出
Python	.py	函数、类、装饰器定义
Go	.go	函数、方法、类型、变量、常量
Rust	.rs	函数、结构体、枚举、实现块、特质、模块、常量
Java	.java	类、方法、接口、枚举、字段、构造函数
C	.c .h	函数、结构体、枚举、联合、类型别名
C++	.cpp .cc .hpp	函数、类、结构体、枚举、命名空间、模板
C#	.cs	类、方法、接口、枚举、结构体、属性
Ruby	.rb	方法、类、模块
PHP	.php	函数、类、方法、接口、特质、枚举
Swift	.swift	函数、类、协议、结构体、枚举、属性
Elixir	.ex .exs	模块、函数、宏、守卫、协议
Bash	.sh	函数
HCL/Terraform	.hcl .tf .tfvars	块、属性（嵌套块的限定名称）
Kotlin	.kt .kts	类、接口、对象、函数、属性、伴生对象
Fortran	.f90 .f95 .f	函数、子程序、模块、程序
Vue	.vue	模板/脚本/样式块 + 内部 TS/JS 实体
XML	.xml .plist .svg .csproj	元素（嵌套，标签名标识）
ERB	.erb .html.erb	块、表达式、代码标签
Svelte	.svelte .svelte.js .svelte.ts	组件块 + Rune JS/TS 模块
Perl	.pl .pm .t	子程序、包
Dart	.dart	类、混入、扩展、枚举、类型别名、函数

此外，还包括结构化数据格式：

格式	扩展名	实体
JSON	.json	属性、对象（RFC 6901 路径）
YAML	.yml .yaml	节、属性（点号路径）
TOML	.toml	节、属性
CSV	.csv .tsv	行（第一列作为标识）
Markdown	.md .mdx	基于标题的章节

其他所有内容则回退到基于块的差异比较。

匹配机制

三阶段实体匹配：

1. 精确 ID 匹配 — 前后相同的实体 = 已修改或未更改
2. 结构哈希匹配 — AST 结构相同但名称不同 = 重命名或移动（忽略空格和注释）
3. 模糊相似度 — 令牌重叠率 >80% = 可能是重命名

这意味着 sem 不仅能检测添加和删除，还能检测重命名和移动。结构哈希还能区分外观上的变化（如空格、格式）与实际逻辑变化。

MCP 服务器

sem 包含一个 MCP 服务器，为 AI 代理提供 6 种工具：sem_entities、sem_diff、sem_blame、sem_impact、sem_log、sem_context。这些工具与 CLI 命令完全一致。

{
  "mcpServers": {
    "sem": {
      "command": "sem-mcp"
    }
  }
}

安装 MCP 二进制文件：

cd sem/crates
cargo install --path sem-mcp

JSON 输出

sem diff --format json

{
  "summary": {
    "fileCount": 2,
    "added": 1,
    "modified": 1,
    "deleted": 1,
    "total": 3
  },
  "changes": [
    {
      "entityId": "src/auth.ts::function::validateToken",
      "changeType": "added",
      "entityType": "function",
      "entityName": "validateToken",
      "filePath": "src/auth.ts"
    }
  ]
}

作为库

sem-core 可以作为 Rust 库依赖使用：

[dependencies]
sem-core = { git = "https://github.com/Ataraxy-Labs/sem", version = "0.3" }

被 weave（语义合并驱动）和 inspect（实体级代码审查）所使用。

架构

• Tree-sitter 用于代码解析（原生 Rust，非 WASM）
• git2 用于 Git 操作
• rayon 用于并行文件处理
• xxhash 用于结构哈希
• 插件系统用于添加新语言和格式

贡献

想添加一种新语言吗？请参阅 CONTRIBUTING.md，获取分步指南。

星标历史

许可证

MIT 或 Apache-2.0

sem 快速上手指南

sem 是一个基于 Git 构建的语义版本控制工具。它利用 tree-sitter 解析代码，将函数、类、方法等提取为独立实体（Entity），从而在实体级别而非行级别进行差异对比。这意味着你能看到“函数 blahh 被修改了”，而不是"X-Y 行发生了变化”。

环境准备

• 操作系统：macOS, Linux, Windows (通过 Docker 或二进制文件)
• 前置依赖：
  • Git：必须在系统中安装并配置好 Git。
  • Rust (可选)：仅当你需要从源码编译时需要。
• 支持语言：原生支持 23 种编程语言（包括 TypeScript, JavaScript, Python, Go, Rust, Java, C/C++ 等）及多种结构化数据格式（JSON, YAML, TOML 等）。

安装步骤

根据你的开发环境选择以下任一方式安装：

方式一：使用 Homebrew (推荐 macOS 用户)

brew install sem-cli

方式二：使用 npm (Node.js 项目)

将其作为开发依赖安装到 node_modules：

npm install --save-dev @ataraxy-labs/sem

方式三：使用 Bun

Bun 需要信任包以便执行下载二进制文件的脚本：

bun add -d @ataraxy-labs/sem
bun pm trust @ataraxy-labs/sem

方式四：从 GitHub Releases 下载二进制文件

访问 GitHub Releases 下载对应平台的二进制文件并放入 PATH。

方式五：使用 Docker

无需本地安装，直接通过容器运行：

docker build -t sem .
docker run --rm -it -u "$(id -u):$(id -g)" -v "$(pwd):/repo" sem diff

方式六：从源码编译 (需要 Rust)

git clone https://github.com/Ataraxy-Labs/sem
cd sem/crates
cargo install --path sem-cli

基本使用

sem 无需任何配置即可在任何 Git 仓库中工作。

1. 执行语义差异对比 (核心功能)

替代传统的 git diff，查看实体级别的变更（如函数重命名、移动检测）：

# 查看工作区的语义差异
sem diff

# 仅查看暂存区的差异
sem diff --staged

# 查看特定提交的差异
sem diff --commit abc1234

# 详细模式：显示每个实体内部的单词级差异
sem diff -v

# 输出为 JSON 格式（适合 AI Agent 或 CI 流水线）
sem diff --format json

2. 替换默认 Git Diff (可选)

如果你希望所有调用 git diff 的命令（包括 IDE 插件或 AI 助手）自动获得语义差异输出，可以运行设置命令：

# 将 git diff 替换为 sem diff
sem setup

# 恢复为原始的 git diff
sem unsetup

3. 分析代码影响范围

查看如果修改某个实体（如函数），会影响哪些其他文件或测试：

# 分析 authenticateUser 函数的影响范围
sem impact authenticateUser

# 仅查看受影响的测试
sem impact authenticateUser --tests

4. 实体级追溯 (Blame)

查看是谁最后修改了特定的函数或类，而不是某一行代码：

sem blame src/auth.ts

5. 为 LLM 生成上下文

生成包含实体及其依赖关系的精简上下文，适配 Token 预算：

# 生成适合 4000 token 预算的上下文
sem context authenticateUser --budget 4000