适合谁
- 使用 AI 编码代理并希望减少 token 消耗的开发者
- 需要跨文件影响分析与实体级差异的团队
- 在 Git 仓库中工作、希望获得确定性依赖图查询而非 grep 结果的项目
S
69FMRS · C
Sem 是 Ataraxy Labs 开发的语义版本控制工具，构建在 Git 之上，通过 tree-sitter 提供实体级差异、影响分析、blame 与上下文能力，支持 32 种语言及多种结构化数据格式。其 MCP 服务器通过 stdio 传输暴露 8 个实体级工具，主要用于让编码代理在不读取整个文件的情况下获得确定性的依赖图查询结果，从而节省 token。它适合使用 AI 编码代理的开发者与需要跨文件影响分析的团队，但需要先安装 sem 二进制文件，且不适用于非 MCP 客户端或浏览器、云存储等场景。
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_entities
列出某个文件或目录路径下的所有实体。
sem_diff
实体级差异比较，支持重命名检测、结构化哈希和词级内联高亮。
sem_blame
实体级 blame，显示每个函数、类或方法最后被谁修改。
sem_impact
跨文件依赖图分析，显示某个实体变更会影响什么。
sem_log
追踪单个实体在 git 历史中的演变过程。
sem_context
为 LLM 提供符合 token 预算的上下文：实体本身及其依赖与被依赖方。
sem_find
查找某个实体在何处被定义。
sem_grep
在源文件中进行文本搜索，输出与 ripgrep 兼容的 file:line:text 格式。
安装接入
- 安装 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 与其它命令打包在同一个二进制文件中，无需单独安装。
claude_desktop_config.json
{
"mcpServers": {
"sem": {
"command": "sem",
"args": ["mcp"]
}
}
}
选型与风险
不适合谁
- 不使用 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 强制禁用
- 代理会对仓库代码发起读取类查询，需确保其工作目录与权限范围符合预期
常见排障
- 运行 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 会在本地计算并输出相同结果，无需额外处理
使用场景
让编码代理在修改代码前查询「改动 submitOrder 会破坏什么」（sem_impact）
为重构某个函数请求恰好够用的上下文，返回函数源码及其调用者与被调用者（sem_context）
在不阅读整个文件的情况下获取实体级代码变更信息，节省 token
跨文件依赖分析，评估变更的影响范围
在 AI 代理工作流中执行实体级 blame 与历史演变追踪
支持客户端
Claude Code完整支持
Cursor完整支持
Claude Desktop完整支持