@ataraxy-labs/sem

中文文档
0.29.1发布于 2026/11/03MIT OR Apache-2.0ES Module零依赖近 30 天下载 1.8万

npm 为 sem CLI所包装. 下载匹配的发布二进制,并在node modules/.bin中曝光 sem 命令.

中文使用文档
文档目录29 节
  1. 用毒剂杀人
  2. 安装
  3. 名称与 GNU 并行冲突
  4. 图标
  5. 寻找
  6. sem grep (英语)
  7. 碎片撞击
  8. 测试
  9. sem 认证
  10. 变身
  11. sem 图
  12. 历史
  13. sem 云, sem 配置
  14. 旧命令名称
  15. 承诺
  16. 用作默认 Git diff
  17. 每个拉动请求上的实体级别 diffs
  18. 云加速(规模和队伍)
  19. 如何解释
  20. 自定义扩展名和无扩展名文件
  21. 如何匹配工作
  22. 使用人工智能代理( MCP)
  23. JSON 输出
  24. 作为图书馆
  25. 建筑
  26. 遥测
  27. 捐款
  28. 恒星历史
  29. 许可证

部分 阿塔拉西实验室 堆栈: 软件开发的代理本土基础设施. 另见: 编织 (实体级别 git 合并驱动程序)- 检查 (语义代码审查) 开幕会话 (tmux sidebar用于编码代理).

阅读宣言: https://ataraxy-labs.com/#thesis 页面存档备份,存于互联网档案馆 论文: https://taraxy-labs.com/blogs (中文(简体) ) 法学硕士: https://taraxy-labs.com/llms.txt (中文(简体) )

sem

Ataraxy-Labs%2Fsem | Trendshift

在Git上构建的语义版控制.
而不是换行,sem告诉你什么实体改变了:函数,方法,类.

为什么? • 妇女 用毒剂杀人 • 妇女 安装 • 妇女 图标 • 妇女 代理人(MCP) • 妇女 云同意书 • 妇女 释放

Release Rust Tests License Languages

sem是一个语义性版本控制工具,在Git上工作. 它以树保姆来解析您的代码, 提取每个函数, 类, 和方法作为一个实体, 并在实体级别 而不是行 。 这意味着你看到"功能" blahh 被修改",而不是"行x-y更改"

它在任何Git Repo中工作 没有设置.

云后查询是每回所选择的:登录中不上传回所或发送查询. 见 云同意流量 用于公共/私人回购状态,预览屏幕,本地审计日志,以及忘记控制.

sem diff

用毒剂杀人

四问四相相相. 每个动词都用 --json。 。 。 .

问题动词
它在哪? 它在吗?sem find, (中文(简体) ), sem grep
我改变的感受是什么?sem impact
是吗?sem check
人类审查应该是什么?sem certify

它在哪? 它在吗? 按名称查找一个函数、类或方法:

sem find parse_config
function parse_config src/config.py:1

谁叫它--callers),其用法为:--refs),或其与被调用者和被调用者的代码(--context:

sem find parse_config --callers
function parse_config src/config.py:1
  function load src/config.py:6
  function test_parse_config tests/test_config.py:4

搜索文本, 如 rg数字 :

sem grep splitlines
src/config.py:2:    pairs = [line.split("=", 1) for line in text.splitlines() if line]

我改变的感受是什么? 所有依赖于实体 和测试运行:

sem impact parse_config --tests
⚡ 1 tests affected:
    tests/test_config.py
      function test_parse_config (L4–5)

sem impact --diff HEAD --tests 你那没承诺的零用钱也一样.

是吗? 运行项目自己的编译器,类型检查器,linter和测试,只重新检查当给出相同答案时变化会影响什么. 0出站表示通过,1出站失败,2出站无法决定:

sem check
cmd    FAIL      full        sh (0 rechecked, 279 ms)
  `python3 -m pytest -q tests` exited 1:
  E       AssertionError: assert {'a': '1'} == {'a': '2'}

人类审查应该是什么? 承诺范围的审查证书: 变化是什么, 哪些要求更改所留下的, 哪些测试达到:

sem certify main..HEAD
# sem certificate 94f4bd74e26e..d73d4d092b43
1 files, 2 entities changed (1 added, 1 modified, 0 deleted, 0 renamed, 0 moved).
- modified `parse_config` (src/config.py:1): 2 static caller(s) in 2 file(s) that this change does not modify

对讲MCP的特工来说, sem mcp 作为工具的同一种动词(参见 与人工智能代理使用) (中文(简体) ).

安装

curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh

或通过Homebrew:

brew install sem-cli

或者通过Winget在Windows上:

winget install AtaraxyLabs.sem

或者通过 Scoop 在 Windows 上 :

scoop install sem

或者安装 npm 包装器到 node_modules数字 :

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

和Bun一起,相信这个包裹 postinstall 脚本可以下载二进制 :

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

安装后, 随时更新到最新版本 :

sem config update

或者通过货物,从 货箱.io数字 :

cargo install sem-cli

或建立最新 main 从源( 需要 Rust) :

cargo install --git https://github.com/Ataraxy-Labs/sem sem-cli

或者拿一个二进制 GitHub 发布。 。 。 .

或跑过多克:

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

名称与 GNU 并行冲突

GNU 平行舰只 a sem 二进制( e)/usr/bin/sem作为与 parallel如果你们都安装好了,它们就会碰撞 运行 sem --version 检查你用的是什么77号(中文(简体) )

快速修正 :

# Option 1: alias in your shell profile (~/.bashrc, ~/.zshrc)
alias sem="$HOME/.cargo/bin/sem"

# Option 2: make sure cargo bin comes first in PATH
export PATH="$HOME/.cargo/bin:$PATH"

# Option 3: if installed via Homebrew
export PATH="$(brew --prefix)/bin:$PATH"

如果您通过 npm/ bun 安装, 二进制会生活在 node_modules/.bin/sem 并通过 npx sem 或者说 bunx sem完全避免了冲突.

图标

工作在任何Git Repo。 不需要设置。 另外在Git以外工作进行任意文件比较.

动词它回答的问题
sem find定义在哪里? 谁叫它,它用什么,它周围是什么?
sem grep这个文字出现在哪里?
sem impact是什么改变了这个实体, 或这个diff,触摸?
sem check我的零钱对吗?
sem certify在这个承诺范围内,人类审查应该是什么?
sem diff哪些职能和类别有所改变?
sem graph密码是怎样连接的?
sem history随着时间的推移,这个实体是如何变化的? 谁最后改了?
sem cloud账户、云评、交叉检索查询
sem configgit diff 集成、 遥测、 完成、 更新、 统计
sem mcp与代理的 MCP 工具相同的动词

sem <verb> --help 以示例显示每个旗帜.

sem 默认将其 SQLite 实体缓存存储在寄存器外的OS缓存目录下. 设定 SEM_CACHE_DIR=/path/to/cache 以覆盖缓存根; repo- local 覆盖被忽略,所以缓存文件不会弄脏工作树 .

寻找

按名称查找实体定义,然后问一个:谁称呼它,它使用什么,或者它的代码与周围的代码. 答案来自一个上盘查询索引(index.sem,在实体缓存旁边);repo中的第一个调用构建它,后来直接调用,没有守护进程.

sem find "function diff_command"        # where it is defined ("type name" narrows by kind)
sem find diff_command load_config       # several names in one call
sem find diff_command --callers         # who calls it; says when the caller set may be incomplete
sem find diff_command --refs            # what it calls and references
sem find diff_command --context         # its code plus callers and callees, within a token budget
sem find diff_command --context --budget 4000 --hops 1
sem find --in src/auth.ts               # every entity in a file or directory
sem find diff_command --in src/         # only definitions under src/
sem find --text "retry budget"          # entity bodies containing a string, named by entity
sem find diff_command --json            # JSON on any of the above

与 --context,当目标签名本身不合适时,JSON输出报告 target_omitted: true。 。 。 .

sem grep (英语)

源文件之间的文本搜索, 与 rg 兼容 file:line:text 输出,当存在时从索引的三分法发布中提供.

sem grep "TODO"
sem grep -i todo src/                   # case-insensitive, under src/
sem grep -e foo -e bar --json           # several patterns, hits kept apart

碎片撞击

如果一个实体改变:其依附关系、其依附关系(暂时)以及达到它的测试,又会有什么突破.

sem impact authenticateUser             # full impact
sem impact authenticateUser --deps      # direct dependencies only
sem impact authenticateUser --dependents
sem impact authenticateUser --tests     # the tests to run
sem impact authenticateUser --file src/auth.ts   # disambiguate by file
sem impact --diff HEAD --tests          # tests for the uncommitted change
sem impact --diff main..HEAD --json     # one impact report per changed entity

与 --diff 财务报告和审定财务报表 --tests 在JS/TS工作空间中,答案是模块图对已更改文件的影响测试选择(sem graph --modules affected-tests在其他地方,它是实体图的. --no-default-excludes 包括生成、固定、销售、基准和建设树木.

测试

运行工程的编译器,类型检查器,linter以及工作树上的测试,并打印出一个判定:出站0通过,1失败,2无法决定. 每个检查器都给出了真正的工具会给整个项目带来的判断;它只重新检查当可以证明是相同的答案时变化会影响什么,否则就将工具全数运行,并说原因. 没有什么可以检查的 是2,从来没有通过.

sem check                               # every checker the project has
sem check --checkers ts,lint,tests      # only these
sem check --base origin/main            # against origin/main instead of HEAD
sem check --promises                    # also prove every promise in .sem/promises can fail
sem check --json                        # one JSON object with a verification certificate

从项目中检测出跳棋 。 TypeScript, lint和JS测试(vitest, jest)遵循模块图,去重新检查受影响的包,Python类型检查(由导入的pyright范围,或mypy),pytest只重新运行一个更改可以到达的文件,C和C++只重新编译其中的翻译单元 compile_commands.json 包括更改的文件。 Cargo, Gradle 或 Maven, dotnet 和 SwiftPM 运行自己的构建,这些构建已经只重建了改变的东西,并且在基底过后没有改变输入时直接跳出(一个 TypeScript 编辑从不重运行 Rust 构建).

Python 函数的正文内部编辑后宣布返回类型,无法更改其他文件所见,所以只有该文件会被重新检查.

命令自己输入 .sem/check.json,比如说. {"commands": [{"run": "make lint", "inputs": ["src/**"]}]}。列出其 inputs 当他们中没有一个人变了的时候,他们就回避了.

sem 认证

承诺范围的审查证书:被触碰的实体、签名的更改和他们留下的呼叫者、被呼叫者三角洲、遵守或被破坏的承诺(与证人一起)、模块可达三角洲(JS/TS)、受影响的测试以及静态参考锥. --arch 给出架构视图:新的或已删除的数据路径、副作用、依赖性、周期,以及没有改变的,排序.

sem certify main..HEAD                  # markdown certificate
sem certify main..HEAD --json           # the full certificate
sem certify main..HEAD --arch           # architecture delta
sem certify main..HEAD --arch --view    # at most 10 ranked items
sem certify main..HEAD --html > view.html   # one self-contained page

<base>...<head> 使用合并基数; 1 ref 表示 <ref>..HEAD。 。 。 .

变身

实体级 diff 有重命名检测,结构散列,和词级内含亮点.

# Semantic diff of working changes
sem diff

# Staged changes only
sem diff --staged

# Specific commit
sem diff --commit abc1234

# Commit range
sem diff --from HEAD~5 --to HEAD

# Verbose mode (word-level inline diffs for each entity)
sem diff -v

# Plain text output (git status style)
sem diff --format plain

# JSON output (for AI agents, CI pipelines)
sem diff --format json

# Markdown output (for PRs, reports)
sem diff --format markdown

# Compare any two files (no git repo needed)
sem diff file1.ts file2.ts

# Read file changes from stdin (no git repo needed)
echo '[{"filePath":"src/main.rs","status":"modified","beforeContent":"...","afterContent":"..."}]' \
  | sem diff --stdin --format json

# Only specific file types
sem diff --file-exts .py .rs

sem 图

代码是如何连接的. 没有旗帜, 实体依赖图( 图) sem impact 财务报告和审定财务报表 sem find --context ; 旗帜选择其他层次.

sem graph --json                        # entities and the calls/references between them
sem graph --modules metrics             # JS/TS module graph: density, cycles, depth, centrality
sem graph --modules blast-radius pkg-a  # who breaks if pkg-a changes
sem graph --modules path src/a.ts src/b.ts
sem graph --dataflow                    # reads, writes and source -> sink paths
sem graph --dataflow --witness          # experimental: witness tasks per static flow
sem graph --system                      # exact dependency versions from every lockfile
sem graph --system build --out sys/     # the layered whole-system graph

历史

一个实体是如何通过历史改变的, 逻辑改变除了化妆品.

sem history authenticateUser
sem history authenticateUser -v         # with the content diff of each version
sem history authenticateUser --limit 20
sem history                             # repo hotspots and co-change pairs
sem history --blame src/auth.ts         # who last changed each entity in the file

没有实体, sem history 分析最近实体级的回波历史: 热点 (大多数更改的职能/类别,包括作者数)和 共变对 (重复改变同一种的实体承诺:"如果触摸一个,不要忘记另一个").

sem 云, sem 配置

sem cloud login                         # API key, or GitHub when omitted
sem cloud enable                        # cloud queries for this public repo (shows what is sent, asks first)
sem cloud disable                       # stop cloud for this repo
sem cloud review listen <diff-id>       # attach an agent to a cloud code review
sem cloud xref --json                   # cross-repo dependencies
sem cloud repos                         # where your code is stored

sem config setup                        # make `git diff` show sem's entity diff
sem config telemetry off
sem config completions zsh              # shell completions
sem config update
sem config stats                        # local diff counters; nothing leaves your machine

旧命令名称

每个早期的命令名称和旗帜仍然有效,输出相同. 在终端上,Sem用新拼法在stderr上打印出一行音符 --json 模式或输出被管道化时,它不会额外打印.

旧新设
sem callers Xsem find X --callers
sem refs Xsem find X --refs
sem context Xsem find X --context
sem entities PATHsem find --in PATH
sem log Xsem history X
sem blame FILEsem history --blame FILE
sem arch-diff RANGEsem certify RANGE --arch
sem topology OPsem graph --modules OP
sem dataflowsem graph --dataflow
sem system OPsem graph --system OP
sem promises verifysem check --promises
sem login, (中文(简体) ), logout, (中文(简体) ), whoami, (中文(简体) ), review, (中文(简体) ), xref, (中文(简体) ), repossem cloud ...
sem cloud neversem cloud disable
sem setup, (中文(简体) ), unsetup, (中文(简体) ), telemetry, (中文(简体) ), completions, (中文(简体) ), update, (中文(简体) ), statssem config ...

承诺

承诺是代理人(或个人)对密码库的要求, "完成"是指支票通过. 承诺是活在 .sem/promises/*.json每条法律都可以载着人类 "promise"。代码形状定律是用任何语言 sem 解析的树保姆查询;每一次抓取,其名称并非以 _ 在最外围的节点报告一次巢穴被俘 譬如说, .sem/promises/jsx-no-logic.json数字 :

{ "laws": [
  { "id": "jsx-no-logic/conditionals",
    "promise": "JSX contains no conditional rendering",
    "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_expression"],
                       "query": "(ternary_expression) @conditional" } },
  { "id": "jsx-no-logic/inline-handler-bodies",
    "promise": "JSX event handlers are references, not block bodies",
    "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_attribute"],
                       "query": "(arrow_function body: (statement_block (_))) @handler_body" } }
] }
sem promises check                        # KEPT / BROKEN n per promise, then file:line:col  capture  snippet; exit 1 if any broken
sem promises check --changed src/App.tsx  # only violations in these files (what an edit hook runs)
sem promises check --since main           # only files changed since a ref, uncommitted and untracked included
sem promises status --json                # id, kept, violation count per promise
sem check --promises                      # prove every promise can fail (each needs a mutation)

sem promises 未列在 sem --help· ; sem certify 报告承诺得到遵守或违反的范围。 同一文件也与 sem graph --modules check --laws <file>,增加了图表和输入法(forbid, (中文(简体) ), only, (中文(简体) ), acyclic, (中文(简体) ), layers, (中文(简体) ), forbidImport, (中文(简体) ), allowImports联合来文/临时秘书处工作空间。 与 --changed 或者说 --since但只有涉及更改文件(或包含文件的包)的违法行为才得到报告.

让经纪人在编辑后看到一个被破坏的承诺, 运行 scripts/promises-hook.sh 每次编辑后。 剧本出道后2出道并打印出违章行为等承诺被打破后再出道,否则保持沉默. 在克洛德代码中,将其添加到您的设置中作为 PostToolUse 钩:

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
    "hooks": [ { "type": "command", "command": "sh /path/to/sem/scripts/promises-hook.sh" } ] } ] } }

脚本读取 tool_input.file_path 从钩子的 stdin。 其他被调用者可以通过编辑过的路径作为参数。 例如,在pii中,扩展可以从它的 tool_result 编辑和写入工具的处理器: 运行 sh promises-hook.sh <path> 当脚本退出 2 时,将 stderr 附加到工具结果中.

用作默认 Git diff

替换 git diff 使用实体级别 diffs 输出。 特工和人类在不改变任何命令的情况下自动获得 sem 输出.

sem config setup

现在 git diff 显示实体级别而不是行级别。 没有提示,不需要代理配置 。 一切唤作 git diff 自动获得 sem 输出 。 还安装了预承诺悬钩,显示相位变化的实体级爆炸半径.

关于macOS和Linux, sem config setup 还登记了克洛德密码 UserPromptSubmit 钩子( r)sem hook prompt-submit用于快速上下文注射,以及 sem hook tool 围绕编辑、写入和多编辑工具。 每次编辑后,钩子会告诉代理商哪个兄弟会执行它没有触及的被改变的方法,哪个呼叫者仍然使用它刚刚改变的签名,哪个测试到达了变化,有一个命令来运行它们;当无话可说时,它保持沉默. 它编辑 ~/.claude/settings.json 独断专行,先退后 留下你已经没有的钩子.

要禁用并返回正常的 git diff( 同时去除会话钩) :

sem config unsetup

每个拉动请求上的实体级别 diffs

添加 GitHub 动作, 每个 PR 都会收到一个粘贴的注释, 显示哪个 函数、类别和方法发生变化。 它更新了每个推和 明确列出只有化妆品的PR(格式/评论):

# .github/workflows/entity-diff.yml
name: Entity diff
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  entity-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Ataraxy-Labs/sem/[email protected]

没有配置, 没有 API 密钥, 永远不会失败您的构建 。 见 动作/ 详细情况.

云加速(规模和队伍)

本地总是免费的,总是快的:上盘指数甚至从冷的流程中解答了一数毫秒的日常查询,所以没有什么可以保持温暖,不需要登录. 你没有付钱让你的笔记本电脑快速.

云是电脑不能做的 在一个非常大的单列上,第一个本地图形构建需要几秒钟;共享的团队图形不应该被每个开发者重建;而CI想要的图形不需要检查任何东西. sem cloud login 将这些案件与 sem 云相连接, 它保存一个温暖的预建图 用于您注册的重置, 并服务于它的重置询问 而不是本地重建 .

sem cloud login                        # GitHub device flow, one time
sem impact myFunc --file src/foo.rs    # served from the cloud's warm graph

它完全具有可选性和透明度:

  • 没有登入,或者云是无法到达的? sem计算本地并打印出完全相同的输出。 没有失败,没有结果的差异.
  • SEM_LOCAL=1 强制本地计算, 即使登录时.
  • 小的回放没有变化, 本地已经快了 。 胜利是针对大型代码库的,其中每次重建图表都是瓶颈.

相关命令, 所有云账户范围 :

sem cloud logout          # log out
sem cloud whoami          # show current cloud identity
sem cloud enable          # turn on cloud queries for a public repo (shows what's sent first)
sem cloud disable         # stop cloud for this repo
sem cloud xref --json     # cross-repo dependencies across your indexed repos
sem cloud repos           # where your code is stored: cloud-indexed repos + local caches
sem cloud status          # cloud + telemetry state for this repo (offline; sends nothing)
sem cloud share           # cloud queries for a private repo, with extra confirmation
sem cloud forget          # delete this repo's cloud index and unregister it

status, (中文(简体) ), share, (中文(简体) ), forget, (中文(简体) ), list, (中文(简体) ), preview 财务报告和审定财务报表 log 未显示于 sem cloud --help 但按所列工作;每个只读,或在发送任何信息之前需要明确确认.

如果你的团队通过星云进行代码审查, sem cloud review listen <diff-id-or-url> 执行一个预配置的编码代理,加入该评论,作为现场的收听者,回答基于diff特定行的复核者问题.

如何解释

32个编程语言,通过树保姆提取完整的实体:

语言扩展实体
类型脚本.ts .tsx .mts .cts函数、类、界面、类型、enum、导出
Java 脚本.js .jsx .mjs .cjs .es6函数、类别、变量、导出
蟒.py .pyi函数、类别、装饰定义
星lar( Batzel, Buck2)BUILD BUCK WORKSPACE PACKAGE .bzl .bazel .bxl .star建立目标、职能
走开.go函数、方法、类型、 vars、 custs
锈.rs函数、结构、enums、imps、特质、mods、consts
爪哇语.java类、方法、接口、enums、字段、构造器
C级.c .h函数、结构、元素、结合、类型防御
C++ 组合.cpp .cc .cxx .hpp .hh .hxx函数、类、结构、enum、命名空间、模板
C# (韩语).cs类、方法、界面、enums、structs、属性
鲁比.rb方法、类别、模块
前一頁.php .inc .phtml .module函数、类、方法、接口、特征、活性
挥发.swift函数、类、协议、结构、元素、属性
埃利克斯尔.ex .exs模块、函数、宏、守护、协议
巴许.sh函数
鱼.fish函数
卢亚.lua函数(全球、当地、表格和方法表格)
高氯酸盐/铁质.hcl .tf .tfvars块、 属性( 嵌入区块的合格名称)
科特林语Name.kt .kts类、接口、对象、函数、属性、伴对象
堡垒.f90 .f95 .f03 .f08 .f .for函数、子例程、模块、程序
阴道.vue模板/标本/样式块+内部TS/JS实体
XML 数据.xml .plist .svg .csproj +9再增加MSBuild/资源扩展元素(已注销,标签名称身份)
应急局.erb .html.erb块、 表达式、 代码标记
丝绒.svelte .svelte.js .svelte.ts (+ 数) .test编号 :.spec 变体)+ une JS/TS模块
佩尔.pl .pm .t子例程, 软件包
达特.dart类、 混音、 扩展、 enum、 类型别名、 函数
奥巴马.ml .mli值、模块、类型、类、外部
斯卡拉语Name.scala .sc .sbt .kojo .mill分类、对象、特征、enums、函数、vals、扩展
无.nix约束、继承声明
哈斯凯尔.hs函数、签名、数据类型、新类型、类别、实例、同义词
精灵.elm值声明、 类型别名、 类型声明、 端口说明、 插入声明
克洛朱尔.clj .cljs .cljcvars,函数,宏,多方法,协议,记录,类型
D级.d .di模块、功能、类、结构、界面、联盟、enum、模板、别名、单位测试
齐格.zig函数、测试、变量
SQL 组合键.sql .psql .pgsql .ddl表格、视图、函数、索引、类型、计划、触发器、序列

加结构化数据格式 :

格式扩展实体
贾森.json属性、对象(RFC 6901路径)
也门.yml .yaml区域、属性(点路径)
移动.toml区域,属性
厄立特里亚.edn顶级映射条目( 关键字密钥)
简历.csv .tsv行( 第一列作为身份)
标记.md .mdx基于标题的款次
拉特克语Name.tex .latex .cls .sty部分/章节/节/.),加上定理/lemma/防/图/表/算法和其他有轨环境

其他一切都归为以块为基的分水岭.

自定义扩展名和无扩展名文件

对于非标准扩展名的文件,创建 .semrc 在您的工程根中 :

.xyz = cpp
.j = json
.mypy = python

sem 也读作 .gitattributes 模式(diff= 财务报告和审定财务报表 linguist-language=如果你已经安排好了. .semrc 当两者都定义同一扩展时,优先.

对于完全没有扩展名的文件, sem 从内容中自动检测语言( shebang lines, vim modelines, 和结构heuristics 如 package编号 :import编号 :use 发言。 这涵盖30+语言,不需要配置.

如何匹配工作

三相实体匹配 :

  1. 精确的ID匹配: 在前/后相同实体=修改或不变
  2. 结构散列匹配: 相同的AST结构,不同名称=更名或移动(ignores whitespace/comments)
  3. 模糊的相似性: > 80% 符号重叠 = 可能重命名

这意味着 sem 检测重命名和移动,而不仅仅是添加和删除. 结构散列还区分了化妆品变化(白空间,格式化)与真实逻辑变化.

使用人工智能代理( MCP)

需要一个基于 URL 的客户端吗? 这个 可流式 HTTP 预览 添加经认证的本地只读访问; stdio 仍然是默认的 .

在macOS和Linux上,同名的客户端共享一个温暖的寄存器守护进程. 运行 sem mcp --status 检查它。 见 共享运行时间合同和可复制基准 用于会话隔离、倒置行为和当前平台限制.

sem mcp 开始 a 示范背景协议 服务器通过 stdin/ stdout 。 这不是您自己运行和读取的命令: 它是一个服务器 您的编码代理在背景中发射, 这样它就可以在工作时问问题 。 就是这个原因 mcp 与正常命令并存。 代理人获得核心动词作为工具:

工具答复
sem_find定义在哪里? mode数字 : callers, (中文(简体) ), refs 或者说 context· ; in 列出文件或目录
sem_grep这个文字出现在哪里?
sem_impact是什么改变了这个实体? 附属物、道具、测试
sem_check我的零钱对吗? 判决:通过、失败、不能决定
sem_certify在这个承诺范围内,人类审查应该是什么?
sem_diff哪些实体在两个裁判之间有所改变?
sem_graph实体、模块、数据流或系统图表
sem_history一个实体是如何改变的? blame 用于文件

调用早期工具名的客户端( E)sem_entities, (中文(简体) ), sem_context, (中文(简体) ), sem_callers, (中文(简体) ), sem_log, (中文(简体) ), sem_blame)仍然得到答案;这些名字只是没有列出. 审查会议sem mcp --review,哪个 sem cloud review listen 名单 join_review, (中文(简体) ), wait_for_branch, (中文(简体) ), reply_to_branch 财务报告和审定财务报表 list_open_branches。 。 。 .

为什么一个经纪人想要这些: 而不是阅读整个文件 和正在燃烧的符号, 它可以问"如果我改变,有什么突破 submitOrder" (中文(简体) )sem_impact)或"仅给我上下文来重构此函数"(第1行)sem_find 有模式 context,它返回函数的源及其呼叫者和被呼叫者),并从依赖图中获取一个精确的,决定性的答案,而不是可能错过呼叫者的grep结果.

加入一次,然后跟你的经纪人正常交谈。 它叫工具 自己.

克劳德代码 :

claude mcp add sem -- sem mcp

或者一个同时安装技能的命令 所以特工知道 何时 以达到 sem:

npx @ataraxy-labs/sem-skill

光标、 Claude 桌面或任何客户端 mcpServers 配置 :

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

若为 sem 使用二进制的绝对路径。 不需要单独安装 : sem mcp 和所有其他命令一样.

JSON 输出

sem diff --format json

实际输出, 从一行逻辑更改为 Python 函数 :

{
  "summary": {
    "fileCount": 1,
    "added": 0,
    "modified": 1,
    "deleted": 0,
    "moved": 0,
    "renamed": 0,
    "reordered": 0,
    "binary": 0,
    "orphan": 0,
    "total": 1
  },
  "changes": [
    {
      "entityId": "auth.py::function::authenticate_user",
      "changeType": "modified",
      "entityType": "function",
      "entityName": "authenticate_user",
      "startLine": 1,
      "endLine": 6,
      "oldStartLine": 1,
      "oldEndLine": 4,
      "oldEntityName": null,
      "filePath": "auth.py",
      "oldFilePath": null,
      "oldParentId": null,
      "beforeContent": "def authenticate_user(username, password):\n    if not username or not password:\n        return False\n    return check_credentials(username, password)",
      "afterContent": "def authenticate_user(username, password):\n    if not username or not password:\n        return False\n    if not check_credentials(username, password):\n        return False\n    return True",
      "commitSha": null,
      "author": null,
      "structuralChange": true
    }
  ],
  "binaryChanges": []
}

命名为更改型桶( :added, (中文(简体) ), modified, (中文(简体) ), deleted, (中文(简体) ), moved, (中文(简体) ), renamed, (中文(简体) ), reordered总是总和 total。 。 。 . orphan 是一个用于模块级别变化的交叉元数据计数,这些变化已经包含在命名的更改类型桶中. beforeContent编号 :afterContent 将实体的全部来源放在变化的两边; structuralChange 实值 false 当 diff 仅仅是化妆品时( 空白, 注释) .

作为图书馆

sem-core可用作 Rust 库依赖,来自 货箱.io数字 :

[dependencies]
sem-core = "0.23"

用于 编织 (语义合并驱动)和 检查 (实体一级代码审查).

建筑

  • 植树人 代码解析( 原生锈, 不是 WASM)
  • gi2 git 业务
  • 线条 用于并行文件处理
  • [xxhash] (韩语) 结构散列
  • 每repo缓存目录(SQLite实体缓存+可mmap查询索引) find编号 :callers编号 :refs编号 :grep 带有冷处理的浏览, 没有背景守护进程
  • 用于添加新语言和格式的插件系统(见 捐款额(中文(简体) )

遥测

默认本地: sem 计数命令名( 如. diff, (中文(简体) ), impact只有你自己的机器, 在这个模式下,没有上传。 没有记录代码,文件路径,repo名称,或用户身份,也没有网络呼叫.

sem config telemetry preview   # see current mode and exactly what would be sent
sem config telemetry on        # opt in: also upload counts to help improve sem
sem config telemetry off       # record nothing at all

SEM_NO_TELEMETRY=1 或者说 DO_NOT_TRACK=1 强迫记录- 无行为, 不管模式。 开发建设(任何项目耗尽) cargo build target/ directory)从不做记录,所以在研究 sem本身不会污染数字.

捐款

想要添加一个新的语言吗? 见 捐款额 以向导.

恒星历史

Star History Chart

许可证

麻省理工学院或阿帕奇2.0

版本与发布记录

@ataraxy-labs/sem 共发布 43 个版本,首次发布于 2026/04/13;过去 12 个月发布了 43 个版本。

版本发布日期距今
0.29.1latest2026/11/034 天前
0.29.02026/10/308 天前
0.28.32026/10/299 天前
0.28.22026/10/2612 天前
0.28.12026/10/2019 天前
0.28.02026/10/1919 天前

关于 @ataraxy-labs/sem 的常见问题

@ataraxy-labs/sem 是什么?

npm 为 sem CLI所包装. 下载匹配的发布二进制,并在node modules/.bin中曝光 sem 命令.

如何安装 @ataraxy-labs/sem?

在项目目录运行 npm install @ataraxy-labs/sem,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sem,可以用 npx sem 直接运行。

@ataraxy-labs/sem 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/ataraxy-labs__sem 是否存在。

@ataraxy-labs/sem 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@ataraxy-labs/sem 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@ataraxy-labs/sem 可以商用吗?

@ataraxy-labs/sem 使用 MIT OR Apache-2.0 许可。可在 MIT、Apache-2.0 中任选其一遵守。选择 MIT 时,宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@ataraxy-labs/sem 的下载量有多少?

根据 npm 官方下载统计,@ataraxy-labs/sem 在 2026/10/07 – 2026/11/05 这 30 天内被下载 17,563 次,日均约 585 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@ataraxy-labs/sem 还在维护吗?

最新版本 0.29.1 发布于 2026/11/03(4 天前);至今共发布 43 个版本,其中过去 12 个月发布了 43 个;首次发布于 2026/04/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。