grove

# Grove — 代码智能代理的结构化视图 Grove 通过 tree-sitter 为代码智能代理提供**结构化、精确到字节、成本较低的访问代码库的方式**，而非读取整个文件。Grove 包含一个引擎、七种工具、**两种接口**（人类 CLI `grove <verb>` 和 MCP 服务器 `grove serve`），并且在运行时从 WASM 注册表中加载语法，从而无需重新编译即可添加新语言。  *(asciinema 演示：[`docs/assets/grove_demo.cast`](docs/assets/grove_demo.cast) — 交互式播放：`asciinema play docs/assets/grove_demo.cast`.)* ## 为什么选择 Grove 智能代理在回答问题时通常会通过 `grep` 和读取整个文件来查找定义、功能调用等信息，这会消耗大量令牌和时间。Grove 取代了这种方式，**每次只处理一个符号，精确到字节**，并通过稳定的 ID 在不同调用中传递。 - **成本较低** — 可以快速概述 1700 行文件的结构；获取单个符号的源码，而非整个文件。 - **精确到字节且稳定** — 每个结果都带有 `symbol-id`（`<lang>:<relpath>#<name>@<line>`，1-based），可以在不同调用中传递。 - **一个引擎，两种接口** — 同一个 Rust 二进制文件驱动 CLI 和 MCP 服务器，确保人类和智能代理看到相同的信息。 - **运行时语法加载** — 所有 27 种官方 tree-sitter 语法都从托管的 WASM 注册表中加载；添加新语言只需在注册表中添加条目，无需重新编译。 **不是 LSP。** Grove 是一个为智能代理提供语法层面的结构化视图的工具，基于 tree-sitter 而非 LSP。它不提供类型推断、代码补全、重命名等功能，而是提供一种**廉价的语法层面的能力**，作为 LSP 语义层面的补充。 **27 种语言开箱即用** — 一个二进制文件，语法在运行时从 [托管的 WASM 注册表](docs/languages.md) 加载： <table><tr><td><img src="docs/assets/langs/bash.svg" width="18" height="18" alt="Bash" valign="middle">&nbsp;<b>bash</b></td><td><img src="docs/assets/langs/c.svg" width="18" height="18" alt="C" valign="middle">&nbsp;<b>C</b></td><td><img src="docs/assets/langs/cpp.svg" width="18" height="18" alt="C++" valign="middle">&nbsp;<b>C++</b></td><td><img src="docs/assets/langs/c_sharp.svg" width="18" height="18" alt="C#" valign="middle">&nbsp;<b>C#</b></td><td><img src="docs/assets/langs/go.svg" width="18" height="18" alt="Go" valign="middle">&nbsp;<b>Go</b></td><td><img src="docs/assets/langs/java.svg" width="18" height="18" alt="Java" valign="middle">&nbsp;<b>Java</b></td><td><img src="docs/assets/langs/javascript.svg" width="18" height="18" alt="JavaScript" valign="middle">&nbsp;<b>JavaScript</b></td><td><img src="docs/assets/langs/julia.svg" width="18" height="18" alt="Julia" valign="middle">&nbsp;<b>Julia</b></td><td><img src="docs/assets/langs/php.svg" width="18" height="18" alt="PHP" valign="middle">&nbsp;<b>PHP</b></td><td><img src="docs/assets/langs/python.svg" width="18" height="18" alt="Python" valign="middle">&nbsp;<b>Python</b></td></tr><tr><td><img src="docs/assets/langs/ruby.svg" width="18" height="18" alt="Ruby" valign="middle">&nbsp;<b>Ruby</b></td><td><img src="docs/assets/langs/rust.svg" width="18" height="18" alt="Rust" valign="middle">&nbsp;<b>Rust</b></td><td><img src="docs/assets/langs/scala.svg" width="18" height="18" alt="Scala" valign="middle">&nbsp;<b>Scala</b></td><td><img src="docs/assets/langs/typescript.svg" width="18" height="18" alt="TypeScript" valign="middle">&nbsp;<b>TypeScript</b></td><td><img src="docs/assets/langs/typescript.svg" width="18" height="18" alt="TSX" valign="middle">&nbsp;<b>TSX</b></td><td><kbd>Agda</kbd>²</td><td><img src="docs/assets/langs/css.svg" width="18" height="18" alt="CSS" valign="middle">&nbsp;<b>CSS</b>²</td><td><kbd>嵌入式模板</kbd>²</td><td><img src="docs/assets/langs/haskell.svg" width="18" height="18" alt="Haskell" valign="middle">&nbsp;<b>Haskell</b>²</td><td><img src="docs/assets/langs/html.svg" width="18" height="18" alt="HTML" valign="middle">&nbsp;<b>HTML</b>²</td></tr><tr><td><kbd>JSDoc</kbd>²</td><td><img src="docs/assets/langs/json.svg" width="18" height="18" alt="JSON" valign="middle">&nbsp;<b>JSON</b>²</td><td><img src="docs/assets/langs/ocaml.svg" width="18" height="18" alt="OCaml" valign="middle">&nbsp;<b>OCaml</b>²</td><td><img src="docs/assets/langs/ocaml.svg" width="18" height="18" alt="OCaml 接口" valign="middle">&nbsp;<b>OCaml 接口</b>²</td><td><kbd>CodeQL</kbd>²</td><td><kbd>正则表达式</kbd>²</td><td><kbd>Verilog</kbd>²</td><td></td><td></td><td></td></tr></table> ² 最简配置 — 仅核心工具；完整配置 = 所有工具。`<kbd>` = 无官方 logo。配置文件是数据，而非编译结果。详见 [语言和语法](docs/languages.md)。 查看 [`VISION.md`](VISION.md) 了解产品愿景。 ## 快速开始 ```bash # 1. 安装（单行命令 — 检测平台，验证 sha256） curl -fsSL https://raw.githubusercontent.com/Entelligentsia/grove/main/install.sh | sh # 2. 接入项目（在项目根目录） grove init ``` `grove init` 会检测项目的语言，自动获取其语法，并写入 `.mcp.json`（工具存在）+ `CLAUDE.md` 指令（代理使用 Grove 而非 grep）+ `grove.lock`。至此，您的代理已具备结构化视图。其他安装方式（Homebrew、npm、cargo、代理技能）和 `--as mcp|skill|both` 配置详见 **[安装](docs/install.md)** 和 **[设置](docs/setup.md)**。 > 作为 **代理技能**（Claude Code、Cursor、Codex、Cline 等）： > `npx skills add Entelligentsia/grove` — 技能会在首次使用时自动安装二进制文件。详见 [设置](docs/setup.md)。 ## 在真实代码库中评估 评估工具是 [`Entelligentsia/grove-testbench`](https://github.com/Entelligentsia/grove-testbench)： 它使用 **相同的代理（Claude）和提示词**，在关闭 Grove（`baseline`）和启用 Grove（`grove`）的情况下，对 10 个大型、流行的、有语法支持的代码库进行评估，并衡量 **上下文令牌、墙钟时间、调用次数和答案质量** 的影响。评估结果公正（盲评答案与源代码对比），而非亮点展示；如果 Grove 表现不佳，会报告并修复。  **早期数据 — L2 调用站点，运行 2，Grove v0.1.7** （1 次运行/侧；完整数据见 testbench 的 `FINDINGS.md`）： - **上下文令牌：** 中位数 **−93%** （范围 −89% 至 −97%，最佳情况下）— 例如 [redis](https://github.com/redis/redis) 2.81M → 83K（**−97%**）， [rails](https://github.com/rails/rails) 1.98M → 128K（**−94%**）， [webpack](https://github.com/webpack/webpack) 4.52M → 307K（**−93%**）， [django](https://github.com/django/django) 1.40M → 95K（**−93%**）， [tokio](https://github.com/tokio-rs/tokio) 1.22M → 98K（**−92%**）， [hugo](https://github.com/gohugoio/hugo) 4.52M → 377K（**−92%**）， [laravel](https://github.com/laravel/framework) 3.76M → 432K（**−89%**）。 - **工具调用：** 中位数 **−91%** （范围 −77% 至 −96%）— 调用次数更少，跳转更精确，而非 grep 和读取整个文件。 - **墙钟时间：** 中位数 **−64%** （范围 −48% 至 −82%，可比较情况下）。 诚实地讲，Grove **尚未在所有场景中表现最佳** — 在 [spring-boot](https://github.com/spring-projects/spring-boot) 上，它的表现较差（+36% 上下文，速度较慢）用于 L2 调用站点任务；该问题已在 testbench 的 `GROVE-ISSUES.md` 中跟踪。testbench 中的其他两个图表仓库是 [TypeScript](https://github.com/microsoft/TypeScript) 和 [bitcoin](https://github.com/bitcoin/bitcoin)（工具调用 −96% / −59%；其基准上下文委托给子代理，因此不在令牌图表上）。完整的按仓库分解、方法和原始运行结果： [`Entelligentsia/grove-testbench`](https://github.com/Entelligentsia/grove-testbench)。 ## Grove 工具 | | 命令 | 返回内容 | |---|---|---| | outline | `grove outline <file>` | 文件的定义骨架（类型 · 名称 · 父节点 · 签名 · ID） | | symbols | `grove symbols <dir> --name <n>` | 仓库范围的符号搜索 — `--name` 为 **精确匹配**， `--name-contains` 为子字符串匹配 | | source | `grove source <id>` | 一个符号的完整源码 — 无需读取整个文件 | | check | `grove check <file>` | 错误 / 缺失节点 — 编辑后语法检查（若有错误则退出 1） | | callers | `grove callers <name> -d <dir>` | 符号的调用站点，每个调用站点带有其封闭函数 | | map | `grove map <dir>` | 目录依赖图：定义 + 输出引用，无源码 | | definition | `grove definition <name>` / `--at <f:l:c>` | 跳转到定义，按名称或从使用位置 | 为代理接口添加 `--json` 以获取相应格式。完整参考和示例： **[工具](docs/tools.md)**。 ## 文档 - **[安装](docs/install.md)** — curl/Homebrew/npm/cargo，源码构建，代理技能 - **[设置](docs/setup.md)** — `grove init`， `--as mcp|skill|both`，输出内容，离线/干燥运行 - **[语言和语法](docs/languages.md)** — WASM 注册表，`fetch`/`lock`，语法位置，配置文件 - **[工具](docs/tools.md)** — 七种工具， `--json`，`symbol-id`，示例 - **[MCP 服务器](docs/mcp.md)** — `grove serve`， `.mcp.json`，控制，错误模型 - **[路线图和仓库布局](docs/roadmap.md)** — 待完成事项，源码映射 - **[FAQ](docs/faq.md)** — *Grove 是 LSP 吗？* 及其他定位问题 - [`VISION.md`](VISION.md) — 产品愿景 · [`CHANGELOG.md`](CHANGELOG.md) — 版本发布 - 评估： [`Entelligentsia/grove-testbench`](https://github.com/Entelligentsia/grove-testbench) — 相同代理，Grove 关闭 vs 开启，跨 10 个大型仓库 - 注册表： [`Entelligentsia/grove-registry`](https://github.com/Entelligentsia/grove-registry) · Homebrew 镜像： [`Entelligentsia/homebrew-grove`](https://github.com/Entelligentsia/homebrew-grove) ## 状态 Pre-1.0。`callers`/`definition` 基于名称（无接收者类型解析）；12 种语言提供最小配置（仅核心工具）；暂无增量重新解析。详见 **[路线图](docs/roadmap.md)**。