sem: A new code understanding primitive tool at a semantic granularity
摘要
正文介绍 Ataraxy Labs 推出的 sem-cli 工具，对 Git 进行语义理解的代码理解原语工具。工具基于 Git，diff、blame、impact、log 都是按函数/类/方法/类型等实体层面处理（而非行级），支持 rename detection、structural hashing 和行内高亮。列出六条命令：sem diff（实体级变更）、sem blame（实体级作者）、sem impact（跨文件依赖图）、sem log（实体演化历史）、sem entities（路径下实体列表）、sem context（带依赖的智能上下文）。全部命令支持 --json 输出。工具特性包括支持 26 种语言、5 种数据格式、无需配置，在任何 Git 仓库运行，典型 diff 耗时 8ms。
荐读理由
brew 安装 sem-cli 后在任意 git 项目运行 sem diff 就能生成实体级 diff、rename 检测和结构哈希输出，对比传统 git diff 后，AI 代理给 sem 输出的准确率提升 2.3 倍，微调 prompt 模板就能直接在 AI 工程项目里吃到这个代码理解提升。
原文
Know what changed.
Semantic understanding on top of Git. Diff, blame, impact, log. Functions, not lines.
copied $ brew install sem-cli
~/project
Same commit. Different lens.
Left: what git shows you. Right: what actually happened.
git diff
diff --git a/src/auth/login.ts b/src/auth/login.ts
index 4a2b1c0..8f3d2e1 100644
--- a/src/auth/login.ts
+++ b/src/auth/login.ts
@@ -12,6 +12,18 @@
+export function validateToken(token: string) {
+ const decoded = jwt.verify(token, SECRET);
+ if (!decoded.exp || decoded.exp < Date.now()) {
+ throw new TokenExpiredError();
+ }
+ return decoded;
+}
+
@@ -24,8 +36,10 @@
export async function authenticateUser(
- const user = await db.findUser(email);
- if (!user) return null;
+ const user = await db.findUser(email);
+ if (!user) throw new UserNotFoundError();
+ await rateLimiter.check(email);
@@ -45,12 +59,0 @@
-export function legacyAuth(user, pass) {
- return db.query('SELECT * FROM users
- WHERE email = ? AND password = ?',
- [user, pass]);
-}
sem diff
┌─ src/auth/login.ts ────────────────
│
│ ⊕ function validateToken [added]
│ ∆ function authenticateUser [modified]
│ ⊖ function legacyAuth [deleted]
│
└────────────────────────────────────
3 entities changed across 1 file
AI agents are 2.3x more accurate when given sem output vs raw line diffs. See the benchmark.
Six commands. One binary.
Everything works in any Git repo. No config. No plugins.
sem diff
What changed? Entity-level diffs with rename detection, structural hashing, and word-level inline highlights.
│ ⊕ function validateToken [added]
│ ∆ function authenticateUser [modified]
│ ⊖ function legacyAuth [deleted]
sem blame
Who changed it? Per-entity blame showing the last commit that touched each function, class, or method.
│ ⊕ render_inline_diff a1a6fbf Rohan 04-03
│ ⊕ format_terminal a1a6fbf Rohan 04-03
sem impact
What breaks? Cross-file dependency graph shows every entity that depends on a given function, plus affected tests.
⊕ function authenticateUser
→ depends on: db.findUser, rateLimiter
← used by: loginRoute, authMiddleware
! 42 entities transitively affected
sem log
How did it evolve? Git history for a single entity. See every commit that touched a specific function.
│ ae576ab Rohan 02-05 added
│ a105183 Rohan 02-08 modified (logic)
│ a1a6fbf Rohan 04-03 modified (logic)
sem entities
What's under a path? Lists every function, class, method, and type with line ranges.
entities: src/auth/login.ts
function validateToken (L12:24)
function authenticateUser (L26:45)
interface AuthConfig (L47:52)
sem context
Smart context for AI. Token-budgeted context window: the entity, its dependencies, and dependents. Fits in any LLM prompt.
context for authenticateUser (budget: 8000)
target: ~705 tokens
dependencies: ~256 tokens
dependents: ~812 tokens
All commands support --json for machine-readable output. Full reference.
Your stack. Covered.
26 languages. 5 data formats. One binary.
TypeScript
JavaScript
Python
Go
Rust
Java
C
C++
C#
Ruby
PHP
Swift
Kotlin
Elixir
Bash
HCL
Fortran
Vue
Svelte
XML
ERB
Dart
Perl
OCaml
Scala
Zig
JSON
YAML
TOML
CSV
Markdown
8ms typical diff
26 languages
0 config needed
4,000+ downloads
Try it. 10 seconds.
$ brew install sem-cli
$ sem setup
✓ Created wrapper script
✓ Set git config --global diff.external = sem
✓ Pre-commit hook installed
Done! Running git diff in any repo will now use sem.
To revert, run: sem unsetup
One command. Every git diff becomes a sem diff. No config files.
Also: cargo install --git https://github.com/Ataraxy-Labs/sem sem-cli
这条对你有帮助吗？