Sem

社区

基于 Git 的语义版本控制，为 AI 编码代理提供实体级代码智能

分类: 开发工具第 16 / 438
Stars: ★ 3.4k 非常热门
传输方式: stdio（本地进程）
运行环境: 预编译二进制 · Node.js · Docker · Rust stable
凭据: 可选 API Key
许可证: Apache-2.0
最近提交: 9 天前
工具数: 8

69FMRS · C

Sem 是 Ataraxy Labs 开发的语义版本控制工具，构建在 Git 之上，通过 tree-sitter 提供实体级差异、影响分析、blame 与上下文能力，支持 32 种语言及多种结构化数据格式。其 MCP 服务器通过 stdio 传输暴露 8 个实体级工具，主要用于让编码代理在不读取整个文件的情况下获得确定性的依赖图查询结果，从而节省 token。它适合使用 AI 编码代理的开发者与需要跨文件影响分析的团队，但需要先安装 sem 二进制文件，且不适用于非 MCP 客户端或浏览器、云存储等场景。

最强项 · 文档质量 17/20 最弱项 · 可靠性 11/20

可靠性

11/20

安全与权限

14/20

维护活跃度

13/20

文档质量

17/20

安装易用性

14/20

查看各项评分依据

可靠性 11/20: README 与 server.json 描述一致（`sem mcp` stdio，8 个实体级工具），CLI 行为、JSON 输出示例、缓存与索引说明较具体，且声明 900+ 测试。但静态审阅中未见任何 CI 工作流文件或提交的测试代码证据，无法验证 MCP 初始化与 tools/list 握手、工具参数与真实返回值是否匹配，也无法核实 `sem setup` 对 `~/.claude/settings.json` 的幂等改写是否安全可回滚。依赖树庞大（tree-sitter 30+ 语言、git2、SQLite、mmap 索引），首次建索引失败时的错误处理与恢复路径未披露。按静态校准规则，缺乏可验证执行证据可靠性上限为 12，故给 11。
安全与权限 14/20: 正面：遥测默认仅本地计数且可用 SEM_NO_TELEMETRY/DO_NOT_TRACK 完全关闭；云查询为逐仓库显式选择加入，有 `sem cloud preview`、公开/私有仓库区分、`sem cloud forget` 删除、`sem review`/`join_review` 等需确认或显式触发；无危险默认删除/部署行为。扣分：存在真实的外部网络面（npm 包 postinstall 下载二进制、`sem login` GitHub device flow、云图查询会把仓库索引上传并在云端预建图、`npx @ataraxy-labs/sem-skill` 写入客户端配置），这些数据边界的细节只在文档层面描述，静态文件中无法核实上传内容与最小权限实现；`sem setup` 会修改用户全局 Claude Code 配置与 git 集成，虽有备份说明但确认机制表述较松散。未见凭证窃取、隐蔽外传或硬编码密钥，未触红线，故给 14。
维护活跃度 13/20: 活跃度信号良好：版本号 0.16.2（server.json）与 README 中 schema 版本 0.23.x 并存说明持续迭代，3337 stars、仅 6 个 open issues，Apache-2.0/MIT 双许可明确，有 releases、CHANGELOG 链路、Homebrew/winget/Scoop/crates.io 多渠道分发，并公开安全/隐私相关的 consent 文档。扣分：缺少可核实的提交历史、发布节奏、依赖更新策略与 SECURITY 响应通道证据；server.json 版本与 README 引用的 action/库版本不一致，存在版本管理松散风险；未见治理结构或维护者身份披露。故给 13。
文档质量 17/20: 文档质量高且分层：安装（curl/brew/winget/scoop/npm/bun/cargo/Docker）、全部 CLI 子命令、MCP 配置示例（Claude Code、mcpServers JSON）、8 个工具与云评审 4 个工具的用途、JSON 输出真实样例、32 种语言实体表、`.semrc`/`.gitattributes`、实体匹配三阶段算法、令牌预算与 target_omitted、缓存/索引位置、遥测与云同意流程、GNU Parallel 命令名冲突排查、许可证均有说明，局限与配额也有披露。扣分：MCP 各工具的输入参数 schema 未逐项列出（仅工具名与用途）；server.json 与 README 版本号不一致；未提供 MCP 工具调用返回失败/错误码的排障章节。故给 17。
安装易用性 14/20: 安装路径极其清晰：`claude mcp add sem -- sem mcp` 或 mcpServers JSON 一步接入，`sem mcp` 随主二进制分发无需单独安装，README 明确提示 PATH 与绝对路径回退，跨平台（macOS/Linux/Windows、npm/bun/cargo/Docker）覆盖完整。扣分：npm/bun 路径需信任 postinstall 下载二进制、需要额外 `bun pm trust`，多语言/多平台组合增加脆弱点；`sem setup` 会改写全局配置与 git 集成，属于侵入式步骤；且静态材料中无 CI 或可复现安装验证证据，按校准规则 setup 上限 15，故给 14。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件访问网络

适合谁

使用 AI 编码代理并希望减少 token 消耗的开发者
需要跨文件影响分析与实体级差异的团队
在 Git 仓库中工作、希望获得确定性依赖图查询而非 grep 结果的项目

不适合谁

不使用 MCP 客户端的用户
需要浏览器自动化、云存储或数据库访问能力的场景
希望零安装即用的用户：运行 sem mcp 需要先安装 sem 二进制文件

所需权限

读取本地代码仓库文件
在本机存储 SQLite 实体缓存与查询索引（默认位于操作系统缓存目录，可用 SEM_CACHE_DIR 覆盖）
可选：通过 sem login 使用 GitHub 设备流程登录 sem cloud（仅在使用云加速时需要）

风险与副作用

sem 与 GNU Parallel 提供的 sem 二进制文件存在命名冲突，可用 sem --version 检查实际使用的是哪一个
实体缓存默认存储在仓库之外的系统缓存目录，若设置 SEM_CACHE_DIR 可能改变缓存位置
云端查询为按仓库选择性加入，登录本身不会上传仓库或发送查询；但启用云查询后会向 sem cloud 发送数据
本地遥测默认只在本机记录命令名称，不上传任何内容；开启遥测后会上传计数，可用 SEM_NO_TELEMETRY=1 或 DO_NOT_TRACK=1 强制禁用
代理会对仓库代码发起读取类查询，需确保其工作目录与权限范围符合预期

安装接入

准备工作

运行环境：预编译二进制 · Node.js · Docker · Rust stable

其他可选配置项（4 个）

SEM_CACHE_DIR 可选覆盖 SQLite 实体缓存和查询索引的缓存根目录，默认在操作系统缓存目录下；非必需。

SEM_LOCAL 可选设为 1 时即使已登录 sem cloud 也强制本地计算；非必需。

SEM_NO_TELEMETRY 可选设为 1 强制完全不记录遥测计数；非必需。

DO_NOT_TRACK 可选通用禁止跟踪变量，设为 1 强制不记录任何遥测；非必需。

安装 sem CLI：使用 curl 安装脚本（curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh），或通过 Homebrew（brew install sem-cli）、winget（winget install AtaraxyLabs.sem）、Scoop（scoop install sem）、npm（npm install --save-dev @ataraxy-labs/sem）、cargo（cargo install sem-cli）或 Docker 安装。
在支持 mcpServers 配置的客户端（如 Cursor、Claude Desktop）中加入配置：command 为 sem，args 为 ["mcp"]。
对于 Claude Code，可直接运行 claude mcp add sem -- sem mcp。
如果 sem 不在代理的 PATH 中，请在配置中使用该二进制文件的绝对路径。
sem mcp 与其它命令打包在同一个二进制文件中，无需单独安装。

.mcp.json

{
  "mcpServers": {
    "sem": {
      "command": "sem",
      "args": ["mcp"]
    }
  }
}

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "sem": {
      "command": "sem",
      "args": [
        "mcp"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add sem -- sem mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端配置中添加 sem mcp 后重启，工具列表里应出现 sem_entities、sem_diff、sem_impact 等 8 个工具；可以问“sem_diff 当前有哪些语义层面的改动”来验证连接。

常见排障

运行 sem --version 确认调用的是 Ataraxy Labs 的 sem 而非 GNU Parallel 的同名二进制文件；如有冲突，可设置 alias 或调整 PATH 顺序
若代理报告中找不到 sem，请在 MCP 配置中使用 sem 二进制文件的绝对路径
npm/bun 安装时二进制位于 node_modules/.bin/sem，可通过 npx sem 或 bunx sem 调用；使用 Bun 时需执行 bun pm trust @ataraxy-labs/sem 允许 postinstall 下载二进制
首次在仓库中调用 find/callers/refs/grep 会构建索引，之后的调用直接读取索引；如缓存异常可检查 SEM_CACHE_DIR 设置
若云端不可达或未登录，sem 会在本地计算并输出相同结果，无需额外处理

试试这样问

连接成功后，可以直接对 AI 助手这样说：

sem_diff 看看当前工作区改了哪些函数和类？
sem_impact 分析一下改动 authenticateUser 会影响哪些文件和测试？
用 sem_blame 告诉我 src/auth.ts 里每个函数最后一次是谁改的？
sem_context 给我 authenticateUser 函数加上它的调用者和被调用者的上下文。

工具能力 8

sem_entities 只读

列出某个文件或目录路径下的所有实体。

sem_diff 只读

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

sem_blame 只读

实体级 blame，显示每个函数、类或方法最后被谁修改。

sem_impact 只读

跨文件依赖图分析，显示某个实体变更会影响什么。

sem_log 只读

追踪单个实体在 git 历史中的演变过程。

sem_context 只读

为 LLM 提供符合 token 预算的上下文：实体本身及其依赖与被依赖方。

sem_find 只读

查找某个实体在何处被定义。

sem_grep 只读

在源文件中进行文本搜索，输出与 ripgrep 兼容的 file:line:text 格式。

使用场景

让编码代理在修改代码前查询「改动 submitOrder 会破坏什么」（sem_impact）

为重构某个函数请求恰好够用的上下文，返回函数源码及其调用者与被调用者（sem_context）

在不阅读整个文件的情况下获取实体级代码变更信息，节省 token

跨文件依赖分析，评估变更的影响范围

在 AI 代理工作流中执行实体级 blame 与历史演变追踪

支持客户端

Claude Code

Cursor

Claude Desktop

依据项目文档列出，未经本站实测。

详细介绍

Sem 是构建在 Git 之上的语义版本控制工具，由 Ataraxy Labs 开发。它使用 tree-sitter 解析代码，将每个函数、方法和类提取为实体，并在实体级别而非行级别进行差异比较，因此输出的是「函数 blahh 被修改」而不是「第 x-y 行发生变化」。它支持 32 种编程语言以及 JSON、YAML、TOML、EDN、CSV、Markdown、LaTeX 等结构化数据格式，并提供重命名与移动检测、结构化哈希（区分空白/注释等外观改动与真实逻辑改动）以及模糊相似度匹配。sem mcp 通过 stdin/stdout 启动一个 Model Context Protocol 服务器，供编码代理在后台启动并调用，提供 8 个实体级工具：sem_entities、sem_diff、sem_blame、sem_impact、sem_log、sem_context、sem_find、sem_grep。该服务器以 stdio 传输方式运行，随 sem 二进制文件一同分发，无需单独安装。本地使用始终免费且不要求登录；云端查询为按仓库选择性加入，未登录或云端不可达时会在本地计算并输出完全相同的结果。

Sem