Girder

Girder

**Girder 通过向编码 Agent 提供恰好所需的代码，而非整个文件，来保留 AI 编码 Agent 的上下文。**它会为你的代码库构建本地语义图，让 Claude Code、Codex、Cursor 和其他 Agent 无需用无关代码填满上下文窗口，即可检索精确的函数、定义、调用方、被调用方和任务上下文。它以单个静态二进制文件运行，无需账户，也不依赖云服务。

npx -y girder-mcp setup

这条命令会自动检测并配置 Claude Code、Codex 和 Cursor。

最新稳定版本：v0.4.0（Apache-2.0）。 贡献方式：参见 CONTRIBUTING.md。

衡量的是输出字节数，而非 token 数（未运行分词器）：

• girder context ... --json --source-only 的 CLI 标准输出（MCP get_source） 与读取整个文件相比：字节数减少 97.85%；测试对象为按源码大小十分位抽样的十个函数 （方法与局限说明）。
• girder names ... --json 的 CLI 标准输出（MCP find_definition）与纯文本 grep 相比：字节数减少 97.98%；测试对象为十个标识符 （方法）。
• orient（一次组合调用：获取一个节点的源码、调用方、被调用方、测试和影响范围） 与效果相当的一系列独立调用相比：48,814 字节 对比 101,302 字节，调用次数为 15 次，对比 78 次；测试基于涵盖十个固定版本代码库的 15 项任务 （方法）。

以上两个百分比衡量的是 CLI 输出；未测量 MCP 传输开销。

支持 Girder

Girder 由独立团队开发，旨在帮助编码 Agent 减少代码消耗：提供精确的语义上下文，而不是读取整个文件和反复检索代码库。赞助有助于为上下文效率、语义图正确性、Agent 集成、可复现基准测试和维护提供资金。Girder 会公开其测量结果，包括失败和局限。如果 Girder 为你节省了上下文、算力或开发时间，请赞助其持续开发。

**筹资目标：**每月 1,000 美元，用于 Girder 的持续维护、版本发布、基准测试和上下文效率相关工作。请参阅赞助资金的用途。

真实的捕获输出（确切来源请参阅 docs/observations/release-prep/）：

$ girder context demo-project --nodes crate::greeter::shout_greeting --json --source-only
{
  "nodes": [{
    "language": "python",
    "path": "crate::greeter::shout_greeting",
    "source": "def shout_greeting(name):\n    return format_greeting(name).upper()"
  }]
}

返回的是某个函数的精确源码，而不是它所在的整个文件——这就是 Girder 为 Agent 上下文窗口提供的核心能力。

如实说明语言支持，而非宣称对等：Rust 和 Python 均已完成对三个固定版本代码库中 100 个调用点的审计，该样本中没有不可靠的回答。两者的结果均为 1 个 Must 和 99 个 Unknown；精确率证据有限（测量结果）。TypeScript 已完成测量并设有门槛，但明确仍在进行中——它仍存在一个单独披露的节点身份冲突机制（重复的 it()/describe() 描述字符串可能会悄无声息地覆盖彼此的图节点；请参阅 docs/observations/stage3-typescript-audit/）。Go 的 Stage 3 审计尚未完成。各语言经过测量的确切限制，请参阅 docs/typescript-support.md 和 docs/go-support.md。

此外还包含一项基于同一张图构建的额外能力——保守的变更影响分析和测试选择：test-impact 会根据同一张语义图列出变更可能影响的测试；对于无法排除的测试，它宁可将其纳入，也不会悄悄漏掉。真实的捕获输出：

$ girder test-impact . --quiet
test-impact: 82 unresolved call-evidence boundaries found; this selection is the conservative must∪may∪unknown union — pass --classified to see why each test is included
test_farewell
test_format_greeting
test_shout_greeting_delegates_to_format_greeting

具体了解此测试选择能证明和不能证明的内容，请参阅状态。

**定价和许可证：**Girder 根据 Apache License 2.0 免费开源。目前没有付费层级，也不需要许可证密钥或账户——请参阅许可证。

供持怀疑态度的读者查阅的证据： docs/evidence-index.md 列出了上述说法背后的所有已提交审计、测量结果和对抗性发现——包括过程中发现并修复的问题，而不仅是最终数字。

安装

预编译二进制文件，无需 Rust 工具链：

curl -fsSL https://raw.githubusercontent.com/dhishwasher/Girder/main/install.sh | sh
girder --version

或从源码构建：

cargo install --path crates/aether-app
girder --help

这会构建默认的无头配置，并将 girder 二进制文件安装到 ~/.cargo/bin（请确保该目录位于你的 PATH 中）。无需 GPU、显示器、网络或 API 密钥。

Windows 安装程序

每个 Windows 版本还包含 Girder-<version>-setup.exe。它会为当前用户安装到 %LOCALAPPDATA%\Programs\Girder，将 Girder 添加到用户的 PATH，创建“开始”菜单快捷方式，且不会请求管理员权限。安装后请打开新的终端，以便识别更新后的 PATH。安装程序包含桌面 GUI，其“开始”菜单快捷方式会打开该界面。压缩包和 npm 安装仍会提供无头 CLI。

安装程序尚未进行代码签名，因此 Windows SmartScreen 会在首次运行时发出警告。从 GitHub 发布页面下载安装程序后，双击运行；在“Windows protected your PC”对话框中选择 More info，确认应用是 Girder，且发布者显示为未知，然后选择 Run anyway。如果这些信息不符，请取消操作。

竞品基准测试

在包含 20 个任务的适度跨语言基础测试集中，Girder 通过了 5/20，而 Ripwire 通过了 7/20——Girder 落败。但在两款产品都通过的 60 次尝试中， Girder 返回了 35,764 字节，而 Ripwire 返回了 158,514 字节——少了 77.4%—— 且调用次数相同（均为 120 次）。GitNexus 无法评分：在这台测量机器上，它的安装 超出了冻结的 1 GiB 上限。这反映的是受限主机上的安装占用，而非对其质量的判断。

本次基准测试中，没有任何产品达到完全正确，也不能据此认定哪款产品总体最佳。请参阅完整的 报告，了解测试方法、各语言结果，以及 上述数字无法证明的所有内容。

在 AI 编码 Agent 中使用

girder mcp 通过 模型上下文协议提供只读图谱命令，让 Agent 可以询问代码库，而不必将文件读入上下文窗口。

预览更改，然后配置检测到的 Agent：

npx -y girder-mcp setup --dry-run
npx -y girder-mcp setup

setup 会检测 Claude Code（~/.claude 或主目录中已有的项目 .mcp.json）、Codex（~/.codex 或主目录中的 CODEX_HOME）和 Cursor （~/.cursor）。它会将 girder MCP 条目合并到每个已检测 Agent 的文档所述配置中，并为 Claude Code 和 Codex 安装嵌套的 PreToolUse 和 PostToolUse 钩子。前置钩子涵盖结构化的 Read、read_file 和 mcp__.*__read_file 事件；后置钩子涵盖 Claude 的 Edit|Write|NotebookEdit 和 Codex 的 apply_patch|Edit|Write 编辑名称。 不会解析 Shell 命令。Cursor 虽有钩子文档，但前置读取钩子无法在不阻止操作的情况下添加建议性上下文（preToolUse 和 beforeReadFile 只能允许、拒绝或重写输入；只有 postToolUse 和 sessionStart 会在操作之后返回 additional_context），因此 setup 会为 Cursor 注册 MCP 和项目规则，但不注册钩子。通用 MCP 客户端没有统一的配置路径，因此会报告为未检测到。Setup 不会写入主目录之外的任何位置。现有的外部 girder 条目会保持不变，即使使用 --force 也一样；girder setup --uninstall 只会移除由 setup 管理的更改。

先定位再阅读的指令。 除 MCP 外，setup 还会通过每个客户端自身的机制安装一条简短的共享指令，使 Agent 在大范围读取或 grep 前先调用 Girder 的 orient，在不确定时明确说明，并在不确定时改为阅读源代码，而不是猜测：

客户端	指令位置	备注
Claude Code	~/.claude/CLAUDE.md 中的分隔块	Claude Code 会将用户和项目的 CLAUDE.md 文件拼接到上下文中
Codex	$CODEX_HOME/AGENTS.md 中的分隔块（默认为 ~/.codex/AGENTS.md）	如果存在非空的 AGENTS.override.md，则跳过并报告，因为此时 Codex 会忽略 AGENTS.md
Cursor	当前项目中的 .cursor/rules/girder-orient.mdc，仅在使用 girder setup --project 时	项目规则是带有 alwaysApply: true 的 .mdc 文件；Cursor 未说明用户规则的文件路径，因此不会写入

该区块会在 girder-setup-state.json 中标记并记录：重新运行 setup 不会更改任何内容；--uninstall 会精确还原文件；已编辑的区块会保持不变；--no-instructions 会跳过此步骤。以上格式已于 2026-10-06 根据各客户端自身的文档核实；来源和引文见 docs/observations/stage4-clients/。 不同形式会安装什么。 使用已构建或已安装的二进制文件运行 girder setup，会安装 MCP、钩子和指令，并写入一个启动该已安装二进制文件的 MCP 条目（<path-to-girder> mcp .），因此客户端启动时无需下载软件包即可运行本地 Girder。运行 npx -y girder-mcp setup 会执行 已发布 软件包的设置；只有在包含该指令的版本发布后，才会安装指令。若设置从 npx 的临时缓存运行，就没有稳定的二进制文件路径，因此条目会回退到 npx -y girder-mcp . 启动形式，设置过程也会说明这一点（安装 Girder 后运行 girder setup，即可切换为本地二进制文件）。

打包的钩子启动器会将每个事件转发给固定版本的原生 girder hook 可执行文件，并在出错时保持放行。只有独立的 PreToolUse JSON 会转发到 stdout；编辑后的原生诊断信息会通过 stderr 输出，而 MCP 仍通过自己的 stdout 使用 JSON-RPC。读取建议只有在 project.aether 已存在时才会提供指引。编辑后建议使用已保存的图快照，不会扫描或重建项目，并会描述已更改文件最后一次分析的版本。有关配置路径、所有权和手动 JSON 回退方案，请参阅设置与客户端路径指南。

对于设置无法检测到的客户端，或需要手动设置时，请将该条目添加到客户端文档说明的 MCP 配置中。各客户端的配置位置：

客户端	位置	格式
Claude Code	项目 .mcp.json 或用户 ~/.claude.json	JSON mcpServers.girder（见下文）
Cursor	项目 .cursor/mcp.json 或用户 ~/.cursor/mcp.json	JSON mcpServers.girder（见下文）
Codex	~/.codex/config.toml（或受信任项目的 .codex/config.toml）	TOML 表，见 JSON 之后的示例
任何其他 MCP 客户端	该客户端文档说明的 MCP 配置	相同的 command 和 args

JSON 格式：

{
  "mcpServers": {
    "girder": {
      "command": "npx",
      "args": ["-y", "girder-mcp", "."]
    }
  }
}

Codex 使用 TOML 表：

[mcp_servers.girder]
command = "npx"
args = ["-y", "girder-mcp", "."]

如果已安装二进制文件，"command": "girder", "args": ["mcp", "."] 会完全跳过 npm。要手动向任何客户端提供指令，请将 npm/instructions/orient-first.md 的文本粘贴到其文档说明的指令文件中（CLAUDE.md、AGENTS.md 或 Cursor .mdc 规则）。

Girder 0.2.6 及更高版本可通过 girder mcp . --watch 或 npx -y girder-mcp . --watch 选择启用缓存的图生成。服务会在内存中保留一个经过验证的图生成，并增量重新解析更改的文件。已提交的监视器测量结果显示，在 45 次变更后，结果与全新冷分析一致，同时复用了 98.70% 的文件提取结果；此声明仅限于在复用解析的同时保留冷分析的解析结果。请参阅监视器结果与限制。

七种工具，全部只读且免费：

工具	回答的问题
get_source	特定函数的源代码，不包括其所在文件的其余内容。
find_definition	精确标识符的声明位置。不是子字符串搜索。
search_code	不知道函数名称时，哪些函数符合描述。
ask_codebase	通过遍历图，查找调用方、被调用方和影响范围。
impacted_tests	变更可能影响到的保守测试集——仅供参考，见下文。
review_changes	工作树中发生了哪些变化，以语义而非文本的方式呈现。
orient	一次调用即可获取一个节点的源代码、调用方、被调用方、测试和影响。

它节省了什么，又没有节省什么

orient 将 get_source + ask_codebase（调用方、被调用方和影响范围）+ impacted_tests 原本需要通过 5-6 次独立调用才能提供的内容合并为一次调用。在涵盖十个固定版本仓库的 15 项任务语料中，这一次调用使用的总字节数少于它所替代的调用链（48,814 对 101,302，比例为 0.48），同时将 78 次往返减少到 15 次——每项任务一次；修复披露的两个缺陷后，37 项门控检查全部通过。第一次运行发现，impacted_tests --quiet 会悄悄丢弃非 Rust/Python 测试名称（orient 自身的测试覆盖率部分没有这个问题，因此才发现了该缺陷）；现已移除该过滤器。其自然语言 intent 输入仍继承了 search_code 的准确性——本语料中的三项意图任务都定位到了错误节点，这一点未变，也不在此次修复范围内——但 orient 的置信度启发式原先未能捕捉到这三项中的任何一项，现在会将三项全部标记为 "confidence": "low"，并附上候选项分数；代价是当次优候选项分数接近时，也会将一些正确的定位标记出来。请参阅 docs/orient-tool.md 和已提交的策略／原始观测结果／修复后观测结果。

另外两项预先提交的测量均统计命令输出的字节数，而非令牌数（未运行分词器）：

• 将 girder context ... --json --source-only（MCP get_source 会调用的命令）与简单的整文件读取基线进行比较：从按源码大小十分位抽样的十个函数来看，CLI 标准输出字节数减少了 97.85%，且十个函数的开销都更低（docs/context-vs-read-cost.md）。
• 将 girder names ... --json（MCP find_definition 会调用的命令）与普通 grep 基线进行比较：十个标识符的 CLI 标准输出字节数减少了 97.98%（docs/names-cost.md）。

未测量 MCP 传输开销和令牌数。

两项测量都基于单个仓库。其趋势是结构性的——文件远大于其中的函数，而 grep 会返回每一处提及，find_definition 则只返回声明——但具体百分比不具备普适性。

这些比较没有衡量一个合格的 Agent 如何自适应地选择 grep 搜索和有边界的文件读取。本文并未证实任何关于 Agentic grep 成本的说法。

之后使用本地 1.5B 模型开展的 Agentic grep 测试 未能完成，也没有产生一对两个答案都正确的结果。因此，它无法证明存在比较成本优势，也无法说明前沿模型的行为。

impacted_tests 仅供参考。它会选出过多无关测试，而且仍无法解析某些动态分派形式——当 Girder 无法证明某个调用点时，冻结策略要求纳入相关测试，而不是猜测可以安全跳过；因此，目前测得的后果是过度纳入（在有代表性的多态分派案例中，召回率为 1.000，精确率为 0.667），而不是悄悄漏掉测试。底层的分派解析缺口仍未解决；目前只是不再悄悄丢弃测试。测量结果及具体改动内容请参阅 docs/core-representative-mutations.md。在判定更改安全之前，完整测试运行仍是最终依据。

多选测试会增加 CPU 时间；漏掉相关测试则可能掩盖回归问题。

项目根目录在服务启动时固定，因此任何工具调用都无法访问其他目录。GIRDER_MCP_TIMEOUT_SECONDS（默认值为 120）限制每次调用的时长；对于非常大的仓库，可调高该值。

以下内容均假定 girder 已位于 PATH 中。若从源代码检出版本构建但不安装，用 cargo run -p aether-app -- 替代 girder，操作方式相同。

快速入门

# Full end-to-end demo — no GPU, display, or API key required:
girder

# Run the test suite:
cargo test --workspace

分析代码仓库

使用 CLI 构建并查询代码仓库的语义图：

# Build the semantic graph from a project and save it as <dir>/project.aether:
girder analyze sample-project

# Inspect a saved graph and a node's impact set:
girder inspect sample-project/project.aether crate::lib::add

# Graph-semantic rename — follows Calls edges (not text search) and rewrites
# only the real callers, then saves the updated graph:
girder refactor sample-project rename crate::lib::add plus

# Emit graph context, a real Plan Format v2 authoring schema, and a plan
# skeleton as one JSON object — for pasting into any external chat model.
# See "External authoring" below for the full loop to a verified, applied edit:
girder context demo-project --nodes crate::greeter::farewell "add an exclamation mark to the farewell" --json

# Validate/inspect/execute a plan file directly:
girder plan validate my-plan.json
girder plan explain my-plan.json
girder plan run my-plan.json --dry

# Semantic code review vs HEAD (typed mutations, not text diffs):
girder review sample-project --since HEAD~1

# Conservative test selection: find every test that might be reachable
# from changed functions:
girder test-impact sample-project --run

# Knowledge-graph query — answer a question by traversing the semantic graph:
girder query sample-project "what would break if I change add?"
girder query sample-project "what calls sum_list?"
girder query sample-project  # interactive REPL (reads stdin)

# Full help:
girder --help

外部编写：girder context + plan run --authored

girder do 会自动驱动一个内置的 provider（OpenAI、Anthropic、Ollama 或离线的 MockProvider）。girder context 和 plan run --authored 则在模型边界处拆分同一工作流，因此任何聊天模型——即使本代码库完全没有为其集成 API——也可以编写经过验证的图编辑。

只需阅读，而非编写？ 添加 --source-only。下面的默认输出包含 Plan Format v2 schema 和计划骨架，这是模型编写编辑所需的固定约 6 KB 内容，而仅仅阅读代码的模型并不需要——在 10 个节点中的 2 个上，测得其开销超过读取整个文件；对于较小的文件，开销则是文件大小的 15.6 倍。--source-only 会移除封装内容；在同样的 10 个节点上，测得其开销比读取文件低 97.85%（docs/context-vs-read-cost.md）。 它也不需要 git 仓库，因为没有 base_commit 需要固定。

编写流程：

# 1. Emit graph context, a real Plan Format v2 authoring schema, and a plan
#    skeleton (base_commit, on_failure, the mandatory tests.impacted check)
#    as one JSON object:
girder context demo-project --nodes crate::greeter::farewell \
  "add an exclamation mark to the farewell" --json > context.json

# 2. Paste context.json into any chat model. Ask it to fill in the plan
#    skeleton's step (id, description, edits) so the step satisfies the
#    schema exactly, and save its response as plan.json — the schema is the
#    literal Plan Format v2 the executor loads, not an approximation of it,
#    so a model that follows it produces a file that loads without
#    translation.

# 3. Run and verify it. `plan run` has no project-directory argument — the
#    root is always the current directory, so run this from inside
#    demo-project/. --authored applies the same harness guarantees `do`
#    applies internally to a model-authored plan: on_failure is forced to
#    rollback_plan, a tests.impacted check is injected if the plan doesn't
#    already carry one, and a zero-step plan is refused outright rather than
#    passing vacuously. --authored-by <name> records who authored it in the
#    written report:
(cd demo-project && girder plan run ../plan.json --authored --authored-by claude-opus-5)

运行通过后，会将编辑应用到真实代码树，并在 .girder/reports/ 下写入报告；如果检查失败，则会自动将代码树回滚到 base_commit，因此不受信任的外部模型所做的错误编辑绝不会以半应用状态落地。plan_schema() 的确切结构（每种编辑/检查类型都使用一个 oneOf 判别联合，与 planfile::schema 的反序列化器字段逐一匹配）正是第 2 步可靠性的保障——有关此举修复的问题及证明这一点的往返测试，请参见 docs/core-gap-analysis.md 中的差距 17。

演示目标：demo-project/，绝非 sample-project/

girder do 和 plan run --authored 都会直接拒绝将 sample-project/ 作为目标，并报错指出应改用 demo-project/：

$ girder do sample-project "uppercase greet's return value"
error: sample-project/ is a pinned measurement fixture (see gap 18/21 in
docs/core-gap-analysis.md) and refuses authored writes; run demos against
demo-project/ instead

sample-project/ 是固定基线，tools/authoring_task_check.py 和 tools/plan_executor_oracle.py 会基于特定的干净源代码提交读取它，用于图寻址编写成本测量语料库，而不是临时目标。在那里进行真实（非 dry-run）的编写会修改测量工具依赖的同一个文件——这种情况发生过两次，间隔三天；在发现夹具发生漂移之前，修复损坏的裁判器耗费了整整一天的调试时间；详情请参见 docs/core-gap-analysis.md 中的差距 18。demo-project/ 的存在正是为了避免这种情况再次发生：它是一个小型、可随意处置的 Python 项目，tools/ 或 docs/ 下的任何内容都不会读取它，因此可安全进行真实（非 dry-run）的编写。 只读命令（context、search、analyze、test-impact）仍可针对 sample-project/ 使用——只有两个会写入内容的命令会被拒绝。

工作区

Crate	作用
aether-graph	持续演进的语义图：节点/边、影响分析和 .aether 序列化。事实来源。
aether-builder	tree-sitter → 图映射、增量编辑同步、语法高亮范围。
aether-ai	AiProvider trait、离线 MockProvider、OpenAI/Anthropic 在线 provider、多 provider Router、provider 扩展点。
aether-app	girder 二进制程序：MCP 服务和图 CLI。

工作区还包含较早期的子系统（Agent 蜂群、协作、tracer 和 DAP adapter、扩展、桌面 GUI）。它们不属于公开工具，默认关闭，只有使用 --features legacy 才会构建。

状态

Girder 是面向编码 Agent 的语义图 MCP 服务和 CLI。以下测量结果描述了该图当前的行为和局限。

已检验的 核心可信度测量 将受影响测试选择与隔离的运行时执行进行比较。其有限基线测得 Rust 和 Python 的精确率/召回率均为 1.000/1.000 （此前 0.667 的 Rust 精确率缺陷已修复）。这只是小型测试夹具上的结果，并不代表其优于典型仓库；相反的证据也一并纳入了检验：在一个真实依赖中，多态分派变更目前测得召回率 1.000、精确率 0.667 （docs/core-representative-mutations.md） ——2026-10 的修复阻止了分派无法解析时测试被悄然漏选，改为回退到保守并集；底层的分派解析缺口并未改变，修复的只是静默漏选这一症状。因此，测试选择被标注为建议，而非权威结果。

已实现的功能：

功能	作用
语义图	节点/边；支持 Rust 别名/返回值/作用域模式/Cargo 入口点感知以及 Python 别名/可空注解/构造函数感知的跨文件调用解析；识别字面量的宏调用；影响范围 BFS；相似度边；严格的版本化 .aether 持久化和源代码协调
语义审查	类型化差异（新增/修改/删除的节点 + 边）、影响范围、测试缺口报告
保守测试选择	从变更函数出发的调用图可达性分析，可选 --run
项目契约	验证 girder.toml 中的源代码范围、图路径、测试运行器和 Agent 输出
源代码投影	由作者编写的计划修改和图重命名，会通过可恢复的日志事务验证源代码和图
候选项验证	可处置的项目副本、可选的 bubblewrap 隔离、Cargo 构建/测试、已配置的检查、取消/超时、受限诊断信息、绑定快照的提交门控
外部编写	girder context 会为任何外部聊天模型输出图上下文和真实的 Plan Format v2 schema；plan run --authored 会对结果重新执行回滚/受影响测试保证

实测的基础功能对比、当前正确性证据和 优先级排序后的未解决风险均维护在 docs/core-gap-analysis.md。

许可证

本仓库中的 Girder 源代码根据 Apache License, Version 2.0 授权。这允许商业使用、修改、 再分发、分叉和托管使用，但须遵守许可证条款；LICENSE 是具有权威性的文本。

此前发布的 v0.3.2 npm 包和发行版二进制文件仍受其发布时附带的 BUSL 许可证约束；已发布的版本不可更改。当前 v0.4.0 npm 包和发行版二进制文件采用 Apache-2.0 许可证。

目前没有付费层级，所有已发布工具均不设门槛：无需账户 或许可证密钥。此前已持有较早版本所签发的许可证密钥的用户，仍可在原先解锁的范围内继续使用；密钥系统本身（GIRDER_LICENSE_KEY 或按操作系统存放的密钥文件，离线验证，不会回传数据）仅为保持历史兼容性而保留。

较早版本仍遵循其发布时附带的条款；本次更改并非追溯性地变更许可证。贡献条款请参阅 CONTRIBUTING.md。