# @ataraxy-labs/sem 中文文档

规范地址：https://npmcn.com/package/%40ataraxy-labs/sem/

版本：0\.29\.1
npm 元数据更新时间：2026-11-02T23:23:28.623Z
中文译文更新时间：2026-11-07T01:47:18.102Z
软件包许可：MIT OR Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ataraxy-labs/sem
原文对照：https://npmcn.com/package/%40ataraxy-labs/sem/?lang=original
项目主页：https://github.com/Ataraxy-Labs/sem
源码仓库：https://github.com/Ataraxy-Labs/sem

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：159 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-04-13T01:01:02.837Z
- 最新版本发布：2026-11-02T23:23:28.467Z
- 近 30 天下载量：17563（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

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

## 安装

```sh
npm install @ataraxy-labs/sem
```

也可以使用：`pnpm add @ataraxy-labs/sem`、`yarn add @ataraxy-labs/sem`、`bun add @ataraxy-labs/sem`

## README

> **部分 [阿塔拉西实验室](https://ataraxy-labs.com/) 堆栈**: 软件开发的代理本土基础设施. 另见: [编织](https://ataraxy-labs.com/weave) (实体级别 git 合并驱动程序)- [检查](https://github.com/Ataraxy-Labs/inspect) (语义代码审查) [开幕会话](https://github.com/Ataraxy-Labs/opensessions) (tmux sidebar用于编码代理).
> 
> 阅读宣言: [https://ataraxy-labs.com/#thesis 页面存档备份,存于互联网档案馆](https://ataraxy-labs.com/#thesis) 论文: [https://taraxy-labs.com/blogs (中文(简体) )](https://ataraxy-labs.com/blogs) 法学硕士: [https://taraxy-labs.com/llms.txt (中文(简体) )](https://ataraxy-labs.com/llms.txt)

![sem](https://npmcn.com/package/%40ataraxy-labs/sem/assets/banner.svg)

[![Ataraxy-Labs%2Fsem | Trendshift](https://trendshift.io/api/badge/repositories/25348)](https://trendshift.io/repositories/25348)

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

[为什么?](https://ataraxy-labs.com/blogs/code-is-not-text) • 妇女 [用毒剂杀人](https://npmcn.com/package/%40ataraxy-labs/sem/#readme-using-sem-with-agents) • 妇女 [安装](https://npmcn.com/package/%40ataraxy-labs/sem/#readme-install) • 妇女 [图标](https://npmcn.com/package/%40ataraxy-labs/sem/#readme-commands) • 妇女 [代理人(MCP)](https://npmcn.com/package/%40ataraxy-labs/sem/#readme-use-with-ai-agents-mcp) • 妇女 [云同意书](https://npmcn.com/package/%40ataraxy-labs/sem/docs/cloud-consent.html) • 妇女 [释放](https://github.com/Ataraxy-Labs/sem/releases/latest)

[![Release](https://img.shields.io/github/v/release/Ataraxy-Labs/sem?color=blue&label=release)](https://github.com/Ataraxy-Labs/sem/releases/latest) ![Rust](https://img.shields.io/badge/rust-stable-orange) ![Tests](https://img.shields.io/badge/tests-900%2B_passing-brightgreen) [![License](https://img.shields.io/badge/license-MIT-yellow)](https://npmcn.com/package/%40ataraxy-labs/sem/LICENSE-MIT) ![Languages](https://img.shields.io/badge/languages-32-blue)

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

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

云后查询是每回所选择的:登录中不上传回所或发送查询. 见 [云同意流量](https://npmcn.com/package/%40ataraxy-labs/sem/docs/cloud-consent.html) 用于公共/私人回购状态,预览屏幕,本地审计日志,以及忘记控制.

![sem diff](https://npmcn.com/package/%40ataraxy-labs/sem/assets/terminal.svg)

## 用毒剂杀人

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

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

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

```bash
sem find parse_config
```

```
function parse_config src/config.py:1
```

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

```bash
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`数字 :

```bash
sem grep splitlines
```

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

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

```bash
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出站无法决定:

```bash
sem check
```

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

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

```bash
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` 作为工具的同一种动词(参见 [与人工智能代理使用](https://npmcn.com/package/%40ataraxy-labs/sem/#readme-use-with-ai-agents-mcp)) (中文(简体) ).

## 安装

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

或通过Homebrew:

```bash
brew install sem-cli
```

或者通过Winget在Windows上:

```powershell
winget install AtaraxyLabs.sem
```

或者通过 Scoop 在 Windows 上 :

```powershell
scoop install sem
```

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

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

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

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

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

```bash
sem config update
```

或者通过货物,从 [货箱.io](https://crates.io/crates/sem-cli)数字 :

```bash
cargo install sem-cli
```

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

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

或者拿一个二进制 [GitHub 发布](https://github.com/Ataraxy-Labs/sem/releases)。 。 。 .

或跑过多克:

```bash
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号](https://github.com/Ataraxy-Labs/sem/issues/77)(中文(简体) )

**快速修正 :**

```bash
# 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 config` | git diff 集成、 遥测、 完成、 更新、 统计 |
| `sem mcp` | 与代理的 MCP 工具相同的动词 |

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

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

### 寻找

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

```bash
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` 输出,当存在时从索引的三分法发布中提供.

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

### 碎片撞击

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

```bash
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,从来没有通过.

```bash
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` 给出架构视图:新的或已删除的数据路径、副作用、依赖性、周期,以及没有改变的,排序.

```bash
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 有重命名检测,结构散列,和词级内含亮点.

```bash
# 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` ; 旗帜选择其他层次.

```bash
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
```

### 历史

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

```bash
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 配置

```bash
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 X` | `sem find X --callers` |
| `sem refs X` | `sem find X --refs` |
| `sem context X` | `sem find X --context` |
| `sem entities PATH` | `sem find --in PATH` |
| `sem log X` | `sem history X` |
| `sem blame FILE` | `sem history --blame FILE` |
| `sem arch-diff RANGE` | `sem certify RANGE --arch` |
| `sem topology OP` | `sem graph --modules OP` |
| `sem dataflow` | `sem graph --dataflow` |
| `sem system OP` | `sem graph --system OP` |
| `sem promises verify` | `sem check --promises` |
| `sem login`, (中文(简体) ), `logout`, (中文(简体) ), `whoami`, (中文(简体) ), `review`, (中文(简体) ), `xref`, (中文(简体) ), `repos` | `sem cloud ...` |
| `sem cloud never` | `sem cloud disable` |
| `sem setup`, (中文(简体) ), `unsetup`, (中文(简体) ), `telemetry`, (中文(简体) ), `completions`, (中文(简体) ), `update`, (中文(简体) ), `stats` | `sem config ...` |

### 承诺

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

```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" } }
] }
```

```bash
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`](https://npmcn.com/package/%40ataraxy-labs/sem/scripts/promises-hook.sh) 每次编辑后。 剧本出道后2出道并打印出违章行为等承诺被打破后再出道,否则保持沉默. 在克洛德代码中,将其添加到您的设置中作为 `PostToolUse` 钩:

```json
{ "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 输出.

```bash
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( 同时去除会话钩) :

```bash
sem config unsetup
```

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

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

```yaml
# .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/action@v0.23.1
```

没有配置, 没有 API 密钥, 永远不会失败您的构建 。 见 [动作/](https://npmcn.com/package/%40ataraxy-labs/sem/action/) 详细情况.

## 云加速(规模和队伍)

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

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

```bash
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` 强制本地计算, 即使登录时.
-   小的回放没有变化, 本地已经快了 。 胜利是针对大型代码库的,其中每次重建图表都是瓶颈.

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

```bash
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` `.cljc` | vars,函数,宏,多方法,协议,记录,类型 |
| 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 预览](https://npmcn.com/package/%40ataraxy-labs/sem/docs/mcp-http.md) 添加经认证的本地只读访问; stdio 仍然是默认的 .

在macOS和Linux上,同名的客户端共享一个温暖的寄存器守护进程. 运行 `sem mcp --status` 检查它。 见 [共享运行时间合同和可复制基准](https://npmcn.com/package/%40ataraxy-labs/sem/docs/shared-mcp.md) 用于会话隔离、倒置行为和当前平台限制.

`sem mcp` 开始 a [示范背景协议](https://modelcontextprotocol.io/) 服务器通过 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结果.

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

**克劳德代码 :**

```bash
claude mcp add sem -- sem mcp
```

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

```bash
npx @ataraxy-labs/sem-skill
```

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

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

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

## JSON 输出

```bash
sem diff --format json
```

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

```json
{
  "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](https://crates.io/crates/sem-core)数字 :

```toml
[dependencies]
sem-core = "0.23"
```

用于 [编织](https://github.com/Ataraxy-Labs/weave) (语义合并驱动)和 [检查](https://github.com/Ataraxy-Labs/inspect) (实体一级代码审查).

## 建筑

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

## 遥测

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

```bash
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本身不会污染数字.

## 捐款

想要添加一个新的语言吗? 见 [捐款额](https://npmcn.com/package/%40ataraxy-labs/sem/CONTRIBUTING.md) 以向导.

## 恒星历史

[![Star History Chart](https://npmcn.com/package/%40ataraxy-labs/sem/assets/star-history.png)](https://star-history.com/#Ataraxy-Labs/sem&Date)

## 许可证

麻省理工学院或阿帕奇2.0

## 常见问题

### @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 和提交记录判断。