Sense：给 coding agent 一张本地代码结构图
AI coding agent 找上下文时，最常见的浪费不是“不会搜索”，而是每次都要重新推导代码结构。它先 grep 一个函数名，打开几个文件，再追 import、调用方、测试和相邻模块。这个过程能跑通，但很容易把 token 花在机械定位上。更麻烦的是，agent 看到的是文本片段，不一定真正知道谁调用谁、一次修改会影响哪里、这个项目惯用什么写法。
今天想记下的 luuuc/sense，就是为这个缝隙做的本地工具。它不是编辑器，也不是新的 agent runtime，而是一个给 AI coding agent 使用的 MCP server 和 CLI。Sense 会在本机索引代码库，用 tree-sitter 提取 symbol、call、import、inheritance 等关系，再把这些结构通过四个工具交给 Claude Code、Cursor、Codex CLI、OpenCode 或其他 MCP client：sense_graph、sense_search、sense_blast、sense_conventions。
按 GitHub repository API、README、Releases page、Tags page、commit history、languages API 和 LICENSE 在 2026-07-14 能核验的公开信息，luuuc/sense 当前有 21 stars、1 fork。仓库主语言是 Go，许可证是 MIT。仓库创建于 2026-04-17 18:19:50 UTC，最近 push 是 2026-07-14 09:15:21 UTC。默认分支 main 当前最新提交是 ae5976b，提交时间 2026-07-14 09:15:19 UTC。GitHub Releases 页和 Tags 页当前最新版本都是 v1.11.25，release 发布时间为 2026-07-14 09:23:38 UTC。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | luuuc/sense |
| 定位 | 面向 AI coding agent 的本地代码结构索引、MCP server 和 CLI |
| Stars | 21 |
| Forks | 1 |
| 主语言 | Go |
| 许可证 | MIT |
| 仓库创建时间 | 2026-04-17 18:19:50 UTC |
| 最近 push | 2026-07-14 09:15:21 UTC |
| 最新 main 提交 | ae5976b，2026-07-14 09:15:19 UTC |
| Latest GitHub release | v1.11.25，2026-07-14 09:23:38 UTC |
| 最新 tag | v1.11.25 |
| 核心入口 | curl -fsSL https://luuuc.github.io/sense/install.sh | sh、sense scan、sense setup |
| 关键词 | MCP、tree-sitter、symbol graph、semantic search、blast radius、conventions、local-first |
结构问题应该交给结构工具
Sense README 里有一句很能说明它的目标：agent 拥有代码文本，但没有地图。一个人类工程师问“谁调用这个函数”，脑子里其实会先切换到结构视角；而 agent 如果只有 grep 和 file read，就会把结构问题拆成大量文本检索。Sense 试图把这层结构预先算好。
它暴露的四个工具也比较克制。sense_graph 处理 symbol relationship、caller、callee、inheritance、tests、dead code；sense_search 做 hybrid semantic code search，并带 keyword / text fallback；sense_blast 看 blast radius、affected code、affected tests 和 risk score；sense_conventions 从源码里检测项目约定。对 coding agent 来说，这比丢一个巨大 grep 输出更容易使用，因为每类问题有明确入口。
我最看重的是 sense_blast 和 sense_conventions。前者回答“改这里会碰到哪里”，后者回答“这个项目通常怎么写”。很多 AI 生成代码的问题并不是语法错，而是写得不像这个仓库：命名、层次、framework idiom、test 放置位置都略微偏掉。Sense 把 convention detection 当成一等能力，这个角度比单纯做搜索更有意思。
本地索引，不把仓库交给外部服务
安装路径很直接：
curl -fsSL https://luuuc.github.io/sense/install.sh | sh
cd /path/to/project && sense scan
cd /path/to/project && sense setupREADME 写得很清楚：Sense 在本机解析代码，用 bundled ONNX model 做 embedding，把索引写到本地 .sense/。它不要求 SaaS account、API key 或 cloud dependency。对公司代码库来说，这一点很实际。很多团队愿意让本地 agent 读仓库，但不愿意把整个 codebase 传给外部代码搜索服务。
setup 的动作也值得注意。它会自动检测 Claude Code、Cursor、Codex CLI、OpenCode 等工具，写入对应的 MCP 配置，比如 .mcp.json、.cursor/mcp.json、.codex/config.toml、opencode.json，并可以写入 CLAUDE.md、.cursorrules、AGENTS.md 等 routing guidance。这有点强势，因为它会碰 agent 指令文件；但从产品目标看也合理：如果 agent 不知道什么时候该用结构工具，它很快又会退回 grep 加乱读文件。
采用时我会先在小仓库里跑一次 sense setup，看它具体改了哪些文件，再决定是否把这些配置提交进项目。工具本身是本地的，但它对工作流有明确意见，不是一个完全无痕的 grep 替代品。
支持面是工程化的，而不是 demo 式的
Sense 的 README 列出两层语言支持。核心 tier 覆盖 Go、JavaScript、TypeScript、TSX、Ruby、Swift、Lua、Bash、Zsh 等；standard tier 覆盖 Python、Rust、Java、Kotlin、C#、C++、C、PHP、Scala 等结构能力。它的仓库语言 API 显示 Go 代码量最大，同时还有 Python、Shell、Dockerfile、Makefile。对一个 21 stars 的项目来说，这个实现面不算薄。
README 还给出了一组 benchmark 描述：在若干真实代码库上，Sense 让 agent 更少读文件、少用 token、少跑 tool call。这里我不会把这些数字当成跨项目性能承诺，因为 benchmark 总有场景依赖；但它至少说明作者把问题定义为“减少 agent 为结构问题付出的重复成本”，而不是只做一个向量检索包装。
最新 release v1.11.25 也能看出维护重点。release note 说这版移除了 Go 大仓库里 interfaces × structs 的 500K budget 限制，让更大的 Go codebase 也能得到 implicit interface satisfaction edges。这个细节很工程化：不是泛泛宣传 AI，而是在补 code graph 的正确性和覆盖范围。
适合什么场景
第一类场景，是你经常让 agent 做跨文件修改，但发现它为了定位 caller、callee、测试和影响范围花太多回合。Sense 的 symbol graph 和 blast radius 正是为这类问题准备的。
第二类场景，是项目约定比语法本身更重要。比如 Rails association、Go interface、Django model、分层目录、命名习惯。sense_conventions 让 agent 在写代码前先看到项目惯例，而不是只靠一段 AGENTS.md 文字说明。
第三类场景，是你希望代码理解能力留在本机。Sense 的索引和模型都在本地，对私有仓库试验更容易接受。
第四类场景，是你同时使用多个 agent 客户端。Sense 不是只绑定某个编辑器插件，而是通过 MCP 和 CLI 暴露能力，适合 Claude Code、Codex CLI、Cursor、OpenCode 混用的环境。
需要注意的地方
第一，项目很年轻。21 stars、1 fork，仓库创建于 2026-04-17，虽然提交、release 和 tag 很活跃，但外部反馈还少。采用时最好固定版本，先在非关键仓库试。
第二，sense setup 会写 agent 配置和指令文件。这个体验方便，但团队项目里应该先看 diff，避免和已有 AGENTS.md、CLAUDE.md、Cursor rules 冲突。
第三，README 自己也说 Sense 不是通用搜索引擎。找日志字符串、配置键、错误码这类纯文本问题，plain grep 仍然更直接。Sense 更适合结构问题，而不是替代所有搜索。
第四，benchmark 数字只能当参考。代码库语言、规模、agent 类型、任务分布都会影响结果。真正要判断价值，应该拿自己的项目跑几类常见任务对比。
总结
Sense 的有趣之处在于，它没有把 AI coding 的问题简单归结为“模型再强一点”。它承认 agent 在大仓库里缺的是一张可查询的本地结构图：谁调用谁，改哪里会影响哪里，项目惯例是什么，哪些搜索该走语义，哪些该回到文本。
如果你已经在用 Codex CLI、Claude Code、Cursor 或 OpenCode，并且经常看到 agent 为了理解代码关系反复 grep、读文件、再 grep，luuuc/sense 值得放进试验清单。它还很小，但方向清楚：把 codebase understanding 放回本地，用结构化工具减少 agent 的盲读成本。