Sense

Sense ⠎⠑⠝⠎⠑

一款面向 AI 编码 Agent 的代码库上下文 MCP 服务。

你的 AI Agent 明明有代码库的文本，却没有结构图，因此为了回答“谁调用了这个函数？”，会读取 19 个文件。它每次执行任务都会重新推导结构，耗费 token 追踪一连串 grep 结果，还会臆造并不存在的依赖。Sense 只需为仓库建立一次索引，就能通过 MCP 提供符号图和语义代码搜索。Claude Code、Cursor、Codex CLI 和任何 MCP 客户端都能用 10 次工具调用（而不是 19 次）、消耗 156K 个 token（而不是 228K），以相同的准确度完成同一任务（见 bench/）。

一个二进制文件、一个本地索引、四个供 AI 使用的工具。不需要 SaaS 账户、API 密钥或云端依赖。

Sense 运行在你的机器上，没有学习门槛，而且不是为你准备的。它是为你的 AI 准备的。

初次使用？从指南开始，根据你的身份找到所有文档的索引。

Sense 的理念

代码库是结构，而不只是文本。谁调用什么、什么会导致什么出错，以及团队如何编写代码，这些关系真实存在、可以了解，也值得保留。Sense 将这些信息保存在你的机器上，并交给你的 AI。

其他一切都由此而来。采用本地模式，因为代码属于你。只读，因为理解代码不应要求获得修改代码的权限。只有四个工具，因为你的 AI 需要的是几个好用的工具，而不是上百个待选工具。

这些不是功能，而是 Sense 如今形态的原因。

你的 AI 能获得什么

四个供 AI 使用的工具，以及一套完整的 CLI 供你使用。没有冗余。

工具	能力
sense_graph	符号关系、调用方、被调用方、继承关系、测试、死代码
sense_search	混合式双编码器 + 交叉编码器语义代码搜索，并支持关键词和文本回退
sense_blast	影响范围、受影响的代码、受影响的测试、风险评分
sense_conventions	从源代码中检测到的项目约定

你的 AI 不再需要读取 30 个文件来回答“谁调用了这个？”。它不再臆造依赖，也不再编写虽然正确、却不符合团队代码风格的代码。

约定检测

四个工具中，约定检测是其他工具都做得不够好的功能。AI 工具不仅难以理解结构，也难以掌握风格。它们写出的代码虽然正确，却不遵循你自己的代码库所采用的风格。

Sense 从实际源代码中检测模式：关键类型及其声明、框架惯用写法（Rails 关联、Go 接口、Django 模型）、架构分层和命名约定。你的 AI 能遵循这些模式，是因为它看到了这些模式，而不是因为有人告诉过它。约定检测不是一项功能，而是让 AI 编写的代码看起来像属于这个项目的关键。

有哪些变化

在 7 个真实代码库中进行测量（Discourse、Flask、Next.js、Axum、Gin、Javalin，以及一个私有电商仓库）。 完整方法和原始数据：bench/。与 Serena、Probe、GitNexus 和代码搜索 MCP 的正面对比排行榜：docs/bench-leaderboard.svg。

指标	Claude Code (Opus 4.6)	Claude Code (Opus 4.6) + Sense	变化
每项任务的工具调用次数	19	10	-47%
每项任务的 Token 数	228K	156K	-32%
每项任务的成本	$0.42	$0.31	-26%
会话耗时	91s	73s	-19%
每 100K Token 的得分	0.19	0.30	+64%
每分钟得分	0.28	0.38	+37%

正确性不变，工作量却大幅减少。Sense 不会让模型变得更聪明，而是赋予模型结构化理解能力，让它不再浪费精力。

结构化任务

需要理解代码关系、而非只阅读文本的任务，正是 Sense 表现更出色的地方。

任务类型	基线	+ Sense	原因
影响范围	0.17	0.25	预先计算的依赖图，而非手动串联 grep
查找调用方	0.27	0.33	图查询，而非阅读数十个文件
死代码	0.00	0.05	基线完全无法完成此任务
语义搜索	0.36	0.38	两阶段检索（双编码器 + 交叉编码器），并提供文本回退

Sense 无法提供帮助的场景

Sense 提供的是结构化理解，而非通用搜索引擎。对于本质上是文本 grep 的任务（查找日志消息、定位字符串字面量），普通 grep 才是合适的工具，Sense 帮不上忙。搜索的文本回退（ripgrep）可以弥补部分差距，但它只是回退方案，而非替代品。

安装

curl -fsSL https://luuuc.github.io/sense/install.sh | sh

或者从最新版本下载适用于你操作系统的二进制文件，解压后将 sense 移到 PATH 中的某个位置。

验证版本（可选）

每个版本的校验和文件都使用 Sigstore 签名（无需密钥，并绑定到此仓库的发布工作流）。安装 cosign 后：

cosign verify-blob \
  --certificate-identity-regexp '^https://github.com/luuuc/sense/\.github/workflows/release\.yml@refs/tags/v.+$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate sense_<version>_checksums.txt.pem \
  --signature sense_<version>_checksums.txt.sig \
  sense_<version>_checksums.txt

制品还附带构建来源证明：gh attestation verify sense_<version>_<os>_<arch>.tar.gz --owner luuuc。

使用 Go（1.26+）

go install github.com/luuuc/sense/cmd/sense@latest

为代码库建立索引

cd /path/to/project && sense scan

使用 tree-sitter 解析代码，提取符号和关系，使用捆绑的 ONNX 模型为所有内容生成嵌入向量，并写入本地 .sense/ 索引。每次运行都会增量更新。

连接你的 AI

cd /path/to/project && sense setup

自动检测已安装的 AI 工具（Claude Code、Cursor、Codex CLI、OpenCode、Windsurf 和 Cline），并为每个工具写入集成配置：

• .mcp.json / .cursor/mcp.json / .codex/config.toml / opencode.json，为检测到的工具（或任何 MCP 客户端）添加 MCP 服务条目
• CLAUDE.md / .cursorrules / AGENTS.md，写入包含工具替换表的路由指南，内容来自单一共享源
• .claude/settings.json，用于引导 Claude 使用 Sense 工具的生命周期钩子
• .claude/skills/ 和 .opencode/skills/，用于探索、影响分析和代码约定的工作流技能

Windsurf 和 Cline 只会从全局设置中读取 MCP 服务，因此对于这两款工具，sense setup 会写入 AGENTS.md，并打印出需要手动添加的条目。

无需手动设置。运行 sense setup，你的 AI 就能理解代码结构。

Sense 还会生成 .sense/summary.md，作为代码库的冷启动地图（包含顶层命名空间、核心符号、入口点和约定）。你的 AI 会在会话开始时读取它，立即了解项目结构。无需调用任何工具即可完成初步了解。

升级 Sense 后重新配置：

sense setup

设置后无需操心

运行 sense setup 后，就无需再做任何事。编辑器已启动的 MCP 服务会在后台监视你的工作树，并在更改发生时重新建立索引，因此无论编辑来自 AI、你自己的编辑器、git pull 还是分支切换，索引都会保持最新。无需启动第二个进程，也不用记得添加 --watch。每次扫描都会重新生成摘要。你的 AI 能更快地获得答案、消耗更少的令牌，而你也会逐渐忘记那些曾经存在的阻碍。

工作原理

Sense 使用 tree-sitter 解析代码库，提取符号（函数、类、模块、方法）及其关系（调用、导入、继承），使用捆绑的量化 ONNX 模型为每个符号生成嵌入向量，并将所有内容存储在 .sense/ 下的本地 SQLite 索引中。

cd /path/to/project && sense scan

从此，你的 AI 就能通过 MCP 提出有关代码结构的问题。以下是 AI 会调用的工具。你也可以手动运行它们进行验证。完整参考请参阅 CLI.md。

MCP 服务不只是回答查询：在整个编辑器会话期间，它会通过带防抖的文件系统监视器观察工作树，并在后台重新索引已更改的文件，不会阻塞请求处理。切换分支时，它会根据 git diff 重新索引一次，而不是对每个文件的变化分别作出响应。如果你查询的文件在几微秒前刚刚更改，服务会在回答前内联修复该文件，因此不会漏掉任何编辑。一次只为一个项目建立索引——单写入者锁意味着第二个编辑器窗口或终端中的 sense scan --watch 可以处理读取，而不会重复建立索引。在 .sense/config.yml 中设置 watch: false，即可关闭后台监视器。

性能

Sense 会融入你的工作流，不再引人注意。查询会在毫秒内完成，因此 AI 可以推理代码结构，而不会出现卡顿。

操作	实测（p50 / p95）
图查询	0.2ms / 3ms
影响范围	0.1ms / 10ms
代码约定	16ms / 16ms
冷启动	48ms
完整扫描	4.9s
增量扫描	2.3s

数据基于 Sense 自身的代码库（382 个文件、4,032 个符号）。在你的项目中运行 sense benchmark，即可获取本地数据。

Sense 不是什么

不是代码编辑器。不是令牌优化器。不是搜索引擎。不是以功能数量取胜的竞争者。也不依赖任何东西。这些非目标并非遗漏，而是产品本身的定位。完整说明请参阅：NON-GOALS.md。

支持的平台

平台	状态
Linux amd64	支持
Linux arm64	支持
macOS Apple Silicon (arm64)	支持
macOS Intel (amd64)	支持（旧版）
Windows	通过 WSL2 支持

目前尚未提供 Windows 原生构建版本。请通过 WSL2 使用 Linux 二进制文件。

macOS Intel 仍提供二进制文件且可以正常运行，但需要 macOS 10.15（Catalina）或更高版本，并固定使用较旧的捆绑运行时（ONNX Runtime 1.23.1），因为 Microsoft 在该版本之后停止构建 macOS x86_64 运行时。此依赖已被冻结，无法升级，因此推荐将 Apple Silicon 作为 Mac 目标平台。

要求

• 二进制文件需要约 60 MB 磁盘空间
• .sense/ 索引需要 100-200 MB（因项目大小而异）

语言支持

Sense 使用 tree-sitter 进行解析。它内置了适用于两个级别共 13 种语言的提取器：

完整级别。 符号、调用、继承、导入、影响范围、语义搜索和特定于框架的推断：

语言	框架支持
Ruby	Rails（关联、回调、路由）、Stimulus、Turbo
TypeScript / JavaScript	React（JSX 组件调用）
Go	-
ERB	Stimulus、Turbo（与 JS 控制器的跨语言边）

标准级别。 符号、调用、继承、导入、影响范围和语义搜索：

语言	备注
Python	Django（模型、URL 模式）、FastAPI（路由、Depends）
Rust	结构体、trait、枚举、impl 块
Java	类、接口、枚举、记录
Kotlin	类、接口、对象
C#	类、接口、结构体、命名空间
C++	类、结构体、命名空间（:: 作用域）
C	函数、结构体、枚举
PHP	类、接口、trait（\ 作用域）
Scala	类、trait、对象

Java、Kotlin、C#、C++、C、PHP 和 Scala 使用表驱动的通用提取器，每种语言只需约 25 行配置，而不是手写遍历器。Python 和 Rust 有专用提取器，Python 还支持 Django 和 FastAPI 推断。请参阅 CONTRIBUTING-A-LANGUAGE.md 了解如何添加新语言，并参阅 CONTRIBUTING-A-FRAMEWORK.md 了解如何添加框架支持（以及与之配套的死代码细粒度识别）。

文章

深入介绍代码库智能、基准测试方法以及 Sense 背后的思考：ARTICLES.md。

反馈

请在 github.com/luuuc/sense/issues 提交问题。

开发

make build    # build the binary
make test     # run tests
make lint     # run linters
make ci       # all of the above

贡献

Sense 的 v1 功能已完整。欢迎外部贡献以下三个方面：新增语言和框架、针对某种语言或框架进行死代码细粒度识别，以及 AI 工具集成。始终欢迎修复错误；不接受全新功能。完整范围和分步指南请参阅 CONTRIBUTING.md：

• CONTRIBUTING-A-LANGUAGE.md，添加新语言。
• CONTRIBUTING-A-FRAMEWORK.md，框架支持和死代码细粒度识别。
• CONTRIBUTING-AN-AI-TOOL.md，添加新的 AI 编码工具集成。

许可证

MIT。请参阅 LICENSE。