零依赖本地插件,让 Antigravity 少花三成 token 配额、少传四成流量
agy-fast 是一个零依赖、符合平台策略的本地 MCP(Model Context Protocol,模型上下文协议)插件,适用于 Google Antigravity(CLI agy、Desktop 2.0 与 IDE)。它把高频搜索、多语言符号大纲、原子化多文件编辑以及构建/测试检查合并成批量的本地调用,并在每次会话开始时注入一份耗时不到 50 ms 的 workspace 快照,从而降低 agent 的墙钟延迟(wall-clock latency)、计费 token 配额和上传流量——同时不改变 Antigravity 的原生 UI、diff 查看器、修改文件列表、checkpoint 与安全检查。
| 指标 | 效果 |
|---|---|
| LLM 轮次(每 10 个操作) | -33.7%;≥150k 上下文 -38.2%;子代理 -58.8% |
| 预估计费配额 | -31.5%;≥150k 上下文 -36.5%;子代理 -54.0% |
| 工具返回上传量 | -39.7%;未缓存新输入 -53.7% |
| 磁盘溢写与原生 UI 影响 | 0 次 · 内联上限 ≤8.8 KB · 原生 diff 与 UI 不受影响 |
快速开始
环境要求:Node.js >= 20(无需 npm install——dist/ 中已包含预构建、未压缩、零依赖的 ESM bundle)。可选:ripgrep(rg),装上之后代码搜索更快,缺失时会自动回退到纯 Node.js 实现。
一条命令安装(推荐)
安装脚本会把运行时文件放到 ~/.gemini/config/plugins/agy-fast;如果本机装了 agy,会自动执行 agy plugin validate --strict 和 agy plugin enable agy-fast;最后还会实机验证 MCP 服务器与 SessionStart hook 是否都能跑通。
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/INK-Q/agy-fast/main/install.sh | sh
Windows(PowerShell):
irm https://raw.githubusercontent.com/INK-Q/agy-fast/main/install.ps1 | iex
> 提示:在 Desktop 2.0 / IDE 中激活。打开 Customizations → Installed,确认 agy-fast 已启用,然后新建一个会话,让 SessionStart hook 和 MCP 工具被加载进来。
更多安装方式
除了上面的一键脚本,还有本地克隆、直接 git clone、agy CLI、按仓库团队安装,或者干脆让 Antigravity 自己装这几种方式。
本地克隆(任意系统)
git clone https://github.com/INK-Q/agy-fast.git
cd agy-fast
node scripts/install.mjs install
直接克隆到 Antigravity 插件目录(不需要脚本)
Antigravity 会自动发现放在 ~/.gemini/config/plugins/ 下的插件:
# macOS / Linux
git clone https://github.com/INK-Q/agy-fast.git ~/.gemini/config/plugins/agy-fast
# Windows (PowerShell)
git clone https://github.com/INK-Q/agy-fast.git "$env:USERPROFILE\.gemini\config\plugins\agy-fast"
使用 Antigravity 原生 CLI(agy)
agy plugin install /path/to/agy-fast
agy plugin enable agy-fast
按仓库安装(团队共享)
只给单个仓库安装(写入 <repo>/.agents/plugins/agy-fast),适合团队把插件配置随仓库一起共享:
node scripts/install.mjs install --project /path/to/your-repo
让 Antigravity 自己装
把下面这段提示词粘进 Antigravity:
Clone https://github.com/INK-Q/agy-fast.git to ~/.gemini/config/plugins/agy-fast, run `node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs doctor`, and enable the agy-fast plugin.
工作原理
对 55 个真实 Antigravity 会话(8,446 个 LLM 轮次、17,302 次工具调用、55.25 小时单 agent 活跃时间;见 docs/ANALYSIS_REPORT.md)的实证分析显示:慢任务很少受限于 token 生成速度,真正吃掉墙钟时间的是下面四个结构性瓶颈。
| 实测瓶颈 | 实测代价 | agy-fast 如何消除 |
|---|---|---|
| 每轮 TTFT 下限 | 中位 TTFT 约 6.1 s(占中位单轮时间的 79%;68.1% 的轮次输出不到 700 token) | 每次 MCP 调用平均批量 4.89 个逻辑操作(子代理中达 5.95×),减少不必要的往返轮次(每轮约 6–8 s) |
| 串行检查与碎片化操作 | 52.5% 的 edit_file 调用是同一文件的拆分编辑;46.3% 的 run_command 是只读搜索(中位约 2.0 s,而本地 rg 只要 2.1 ms) | 在一个常驻本地 Stdio MCP 服务器内,合并最多 20 个搜索、50 个文件编辑加校验,或 12 条构建/测试命令 |
| 冷启动探索 | 前 3 轮平均花 49.2 秒查看目录结构、git 状态和脚本 | SessionStart hook 在约 35–50 ms 内注入一份 ≤1.5 KB 快照(git 状态、两层目录树、多模块脚本) |
| 上下文膨胀与缓存衰减 | read_file 占总工具返回字节的 81.9%;间隔超过 60 s 会让缓存未命中率从 1.4% 飙到 15.9%–93.8% | 先给符号大纲再并行定向 read_file,硬性 ≤8.8 KB UTF-8 内联上限(零 output.txt 磁盘溢写),并配合多模态隔离规则 |
混合执行架构
agy-fast 从不替代那些本来就很快的原生读取。它把批量化的本地 MCP 工具与 Antigravity 本地白名单放行的 read_file(约 7 ms、每次调用 46 KB 内联、零远程检查)组合起来用:小文件和已知行区间交给内置 read_file,多查询搜索、符号大纲、多 hunk/多文件编辑与并发检查走 MCP。这样既拿到批量收益,又不牺牲原生路径的低延迟。
插件组件
| 组件 | 路径 | 作用 |
|---|---|---|
| 插件清单 | plugin.json | 标准 Antigravity manifest,能通过 agy plugin validate --strict |
| 本地 Stdio MCP 服务器 | mcp_config.json → dist/mcp-server.mjs | 常驻本地进程,在 agy-fast_fast 下暴露 5 个预加载的复合工具("eager": true) |
| 启动快照 hook | hooks.json → dist/session-start.mjs | 在 SessionStart 时跑一次(约 35–50 ms,带 250 ms 扫描熔断和操作系统/家目录跳过名单),输出 ≤1.5 KB 工作区快照 |
| 路由与卫生规则 | rules/AGENTS.md | 约 6.5 KB 的精简路由指南,内联了工具 schema(支持用户自有的 rules/AGENTS.local.md,带 trigger: always_on frontmatter,更新时会被保留) |
| 后台自动更新器 | dist/updater.mjs | 分离进程,每 12 小时检查一次新版本,替换前先做 MCP 冒烟验证 |
| 离线基准 CLI | dist/benchmark.mjs | 本地 transcript.jsonl 分析器,以及前后 A/B 对比工具 |
真实基准测试
基于 10 天脱敏后的真实编码会话记录(14 个基线主会话 / 5,771 轮,对比 7 个 agy-fast 主会话 / 901 轮;另有 104 个基线子代理会话对比 4 个 agy-fast 子代理会话;所有仓库名、路径和标识符都已剥离),每次 agy-fast 调用平均批量了 4.89 个逻辑操作(子代理中达 5.95×):
| 指标(按逻辑操作归一化) | 主会话(基线) | 主会话(agy-fast) | 变化 | ≥150k 长上下文 | 子代理 |
|---|---|---|---|---|---|
| LLM 轮次 / 10 个操作 | 5.23 | 3.47 | -33.7% | -38.2% | -58.8% |
| 上游请求 / 10 个操作(LLM + 远程检查) | 9.82 | 6.05 | -38.4% | -42.6% | -62.0% |
| Prompt Cache 命中率(未命中尖峰) | 89.6%(7.5%) | 94.0%(4.8%) | +4.4 pp | 95.0%(3.3%) | 92.4%(2.8%) |
| 未缓存新输入 / 操作 | 10,413 tok | 4,822 tok | -53.7% | -61.5% | -51.3% |
| 预估计费配额 / 操作(1 : 0.1 : 5) | 22,458 eq | 15,387 eq | -31.5% | -36.5% | -54.0% |
| 工具返回上传 / 操作(实际本地字节) | 5.06 KB | 3.05 KB | -39.7% | -42.6% | -13.3% |
| 增量文本上传 / 操作(新输入估算) | 35.6 KB | 16.5 KB | -53.7% | -61.6% | -51.3% |
| 全上下文文本上传 / 操作(无状态重发估算) | 342.2 KB | 276.2 KB | -19.3% | -21.9% | -58.9% |
v0.2.x 的生产化加固要点:
- 连续 134 次 v0.2.x MCP 调用中 0 次磁盘溢写——严格的 ≤8.8 KB UTF-8 内联上限,避免了 Antigravity 因 output.txt 溢写磁盘而多出来的额外轮次。
- 同一会话内 v0.2.1 前后对比(99 轮 vs 374 轮)中,有效吞吐提升 75%(35.1 → 61.5 tok/s),超过 60 s 的卡顿轮次从 31.2% 降到 7.4%——这发生在把多模态截图从超过 180k token 的主会话中隔离出去之后(升级后主编码会话中加载的截图数为 0)。
- 0 次惰性加载读 schema 的轮次——精简 schema 直接内联在 rules/AGENTS.md 里。
方法论、配额敏感性与固定提示开销
- 逻辑操作归一化:一个 batch_search 带 5 个查询算 5 个操作;一次 apply_edits 涉及 6 个 hunk 加校验算 7 个操作;一次内置 read_file / edit_file / run_command 算 1 个操作——这样比较的是“每单位工作量”的成本,而不是原始工具调用次数,保证口径一致。
- 配额权重敏感性:标准权重(未缓存输入 1.0×、缓存读取 0.1×、输出 5.0×)下主会话为 -31.5%(≥150k 会话为 -36.5%)。换成保守缓存折扣(1 : 0.25 : 4)仍为 -25.8%,换成高输出权重(1 : 0.1 : 8)仍为 -29.4%。
- 固定提示开销:rules/AGENTS.md 加 SessionStart 快照,每个会话一次性增加约 1.7k token(从第 2 轮起被缓存,约 170 eq token/轮)。只要省掉一次多余轮次(约 44k eq token)或一次盲目的整文件读取,这笔开销就回本 20 倍以上。
用你自己的会话记录离线验证
完全在本地测量你自己的 Antigravity 会话,数据不会离开你的机器:
# 汇总所有本地 Antigravity 会话记录
node dist/benchmark.mjs analyze --local
# 只分析最近修改的 10 个本地记录
node dist/benchmark.mjs analyze --local --recent 10
# 切出安装之后的会话,对比用与不用 agy-fast
node dist/benchmark.mjs analyze --local --since 2026-11-19T12:51:00+08:00 --split-usage
# 对比两次任务运行(前 vs 后)
node dist/benchmark.mjs compare --before ./run-before/transcript.jsonl --after ./run-after/transcript.jsonl
5 个 MCP 工具
| 场景 | 首选工具 | 原因 |
|---|---|---|
| 要跑 ≥2 个文本、正则、glob、模糊或只读 git 查询 | batch_search | 一次调用并发最多 20 个查询(本地 <70 ms) |
| 想摸清未知的大文件(>300 行) | quick_outline(或 read_slices) | 最多 40 个文件的扁平“仅路径 + 符号”大纲,不整文件倾倒 |
| 读小文件(<300 行)或已知行区间 | 内置 read_file | 本地白名单放行(约 7 ms、每次 46 KB、0 远程检查) |
| 一轮内改 ≥2 个 hunk/文件,或“编辑 + 校验” | apply_edits | 原子或 bestEffort 多文件编辑,附带可选内联校验 |
| 跑 ≥2 条独立的构建、lint、测试或诊断命令 | run_checks | 并发执行,首尾折叠、聚焦错误的输出 |
1. batch_search —— 并发代码、路径与只读 Git 搜索
- 每次调用最多 20 个混合查询:文本、正则、glob、模糊,以及只读 git(status、diff、log、show、branch、rev-parse、ls-files、blame、shortlog、describe、tag --list、remote -v),还支持按查询指定路径做跨仓库查找。
- 精度控制:按 fileType(如 typescript、python、gdscript)或 glob 过滤;切换 outputMode(content | files_with_matches | count);开启跨行 multiline: true(此时 count 会按文件报告出现次数);用 type: "fuzzy" 做大小写不敏感的路径匹配;或在 glob 查询上设置 sortBy: "mtime" 让最新文件排在前面。
- 稳健且内联安全:装了 rg 就用 rg,没装自动回退 Node.js;能自动纠正 LLM 常见的 glob 写法错误(| 分支写法和裸关键字);强制 ≤8.8 KB UTF-8 上限。
2. apply_edits —— 原子化多 hunk、多文件编辑 + 校验
- 每次调用最多 50 个文件:落盘前先在内存中校验每个 hunk 和重叠区间(出错时 0 个文件被改动);大批量时也可以传 bestEffort: true,让合法文件按文件原子提交,失败的文件返回最近行/漂移行片段,方便定点重试。
- 忠实处理文件:保留 CRLF 换行、文件权限和符号链接;支持 startLine/endLine、replaceAll、创建/覆盖以及 dryRun。
- 内联校验:可选在写完立刻跑构建/类型检查/测试命令,并剥离噪音日志(如 Pino/Bunyan 的 info JSON、Maven footer),让根因信息留在预算之内。
3. quick_outline —— 扁平的多语言符号大纲
- 每次调用最多 40 个文件(建议每批 10–20 个):传入扁平的 paths: string[] 数组,即可为 TypeScript / JavaScript(含 Fastify/Express 路由与测试块)、HTML / Vue / Svelte、CSS / SCSS / Less、Python、Godot GDScript(.gd)、Go、Rust、Java / Kotlin / C# / Swift / C / C++、Shell、Markdown 以及 JSON / YAML 提取精确的 [startLine, endLine] 符号/区段映射——先用大纲探索,再并行内置 read_file,非常顺手。
4. read_slices —— 符号大纲 + 定向行切片
- 大纲 + 顺带切片:支持同样的 15 种格式大纲(文件之间按广度优先的“注水”策略分配预算),还能在 ≤8.8 KB UTF-8 预算内,于同一次调用里附带少量 [startLine, endLine] 切片,同时把大段区间读取(>150 行)引导到并行的内置 read_file。
5. run_checks —— 并发构建、Lint、测试与诊断执行器
- 每次调用最多 12 条命令:在有界 worker 池中执行独立的非交互式 shell 命令(concurrency: 1..8),每条命令带超时(1..170 s,共享 170 s 的调用预算,以适配 Antigravity 180 s 的 MCP 上限),会剥离 ANSI 转义;在 Windows 上透明地拆掉包住白名单二进制(git、npm、node、rg、pytest、cargo 等)的 powershell -Command "..." 简单包装,跳过 PowerShell 冷启动开销,而真正的 PowerShell cmdlet/别名保持不动。
- Head-Tail 自适应输出模式:compact(默认)把通过的命令折叠成一行摘要,失败很大时用 Head-Tail 折叠,让开头的根因错误和结尾的摘要/堆栈尾巴都能装进 ≤8.8 KB 内联上限;full 保留 stdout,供诊断或审计脚本使用,超上限时同样折叠。
批量 MCP 调用示例(JSON 载荷)
batch_search —— 一次调用发 3 个异构查询:
{
"queries": [
{ "type": "regex", "pattern": "export (async )?function", "fileType": "typescript", "outputMode": "files_with_matches" },
{ "type": "fuzzy", "pattern": "mcp server" },
{ "type": "git", "pattern": "status --short" }
]
}
apply_edits —— 一次调用完成多文件编辑 + 内联类型检查:
{
"edits": [
{ "path": "src/a.ts", "hunks": [{ "target": "oldCall()", "replacement": "newCall()" }] },
{ "path": "src/b.ts", "hunks": [{ "target": "v1", "replacement": "v2", "startLine": 10, "endLine": 25 }] }
],
"bestEffort": true,
"verify": "npm run typecheck"
}
更新、诊断与卸载
日常 CLI 速查
| 任务 | 命令 |
|---|---|
| 健康检查(Node、rg、MCP 实机握手、SessionStart 延迟、manifest 校验) | node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs doctor |
| 检查更新(只读) | node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs update --check |
| 立即更新(先暂存并跑 MCP 冒烟测试,再替换) | node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs update |
| 配置自动更新(auto / notify / off) | node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs config --auto-update notify --interval 24 |
| 干净卸载 | node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs uninstall |
如果是在本地仓库克隆里操作,./install.sh <command>(macOS/Linux)和 .\install.ps1 <command>(Windows)接受同样的子命令(doctor、update、config、uninstall)。
零延迟后台自动更新器
- 会话启动 0 ms 成本:每 12 小时,SessionStart 在输出工作区快照之后再拉起一个分离的后台进程(dist/updater.mjs)。
- 替换前先验证:检查 GitHub release tag(git ls-remote --tags,带 GitHub Releases API 兜底),克隆到隔离的暂存目录,跑一次实机 MCP 冒烟测试,然后原子替换运行时文件——坏版本会被自动拒绝,同时保留用户自建的 rules/AGENTS.local.md(加上 ---\ntrigger: always_on\n--- 的 YAML frontmatter 后 Antigravity 才会加载它;git clone 安装时该文件被 gitignore)。
- 设计上就是安全的:标准复制安装和干净的直接 git clone 安装会自动更新;--link 开发符号链接和脏 git 仓库永远不会被覆盖(只通知)。更新被应用或有新版本可用时,会在下一个新会话中弹一次提示。
环境变量覆盖与应用更新
| 环境变量 | 取值 / 默认 | 用途 |
|---|---|---|
AGY_FAST_AUTO_UPDATE | auto(默认) / notify / off | 覆盖已保存的自动更新模式 |
AGY_FAST_UPDATE_INTERVAL_HOURS | 12(默认;1..720) | 后台检查间隔(小时) |
AGY_FAST_UPDATE_CHANNEL | release(默认) / main | 跟踪稳定 semver release tag 还是 main |
AGY_FAST_REPO | Git URL | 使用自定义镜像或 fork |
AGY_FAST_EDITS_FORMAT | auto(默认) / array / string | 控制 apply_edits.edits 的 schema(auto 在支持 eager 的 CLI ≥1.5.8、Desktop 2.0、IDE 和第三方宿主上使用更省 token 的原生数组,在 pre-eager 的 CLI 1.5.0–1.5.7 上切换为 JSON 数组字符串;服务器始终两者都接受) |
AGY_FAST_HOST | 如 cli@1.5.14、ide@2.7.0、desktop@2.34.0 | 覆盖自动探测的 Antigravity 宿主界面与版本 |
应用更新:更新后的 rules/AGENTS.md 和 dist/session-start.mjs 会在下一个新会话自动生效。在 Antigravity Desktop 2.0 / IDE 中,需要重载或重启窗口一次,以刷新常驻的 MCP 服务器进程。
政策合规与安全
- 只用官方接口:完全基于 Antigravity 官方文档化的扩展 API(plugin.json、mcp_config.json、hooks.json、rules/AGENTS.md)。
- 非侵入式设计:从不修改或干扰 Antigravity 的原生 UI、diff 查看器/窗口、修改文件列表、checkpoint 或内置工具。
- 不碰安全机制与二进制:不 patch 客户端二进制,不修改认证,不绕过 Antigravity 内置的安全评估。
- 零逐步阻塞 hook:不注册 PreToolUse、PostToolUse、PreInvocation、PostInvocation 或 Stop hook。
- 启动 hook 故障开放(fail-open):遇到不可读目录或畸形 stdin 时,SessionStart 返回 {} 并正常退出——绝不阻塞会话。
- 本地优先、可审计:5 个 MCP 工具和基准 CLI 全部 100% 本地运行,不上传任何代码或会话记录;随包发布的 dist/*.mjs 是未压缩的 ESM,执行的每一行都可直接审计。
常见问题
agy-fast 会影响 Antigravity 的原生 UI、diff 查看器或修改文件列表吗?
不会。agy-fast 严格以标准本地 Stdio MCP 插件 + SessionStart hook 的形式运行,从不 patch Antigravity 客户端,也不会干扰原生 diff 查看器/窗口、修改文件列表、checkpoint、内置工具或安全检查。
除了降延迟,它真的能省 token 配额和上传带宽吗?
可以。在 10 天脱敏真实编码会话记录上,每次 MCP 调用批量约 4.9 个操作,使 LLM 轮次减少 33.7%,预估计费 token 配额减少 31.5%(≥150k token 会话为 36.5%;子代理为 54.0%),工具返回上传字节减少 39.7%,超过 60 s 的卡顿轮次从 31.2% 降到 7.4%。
agy-fast 会取代 Antigravity 内置的 read_file 或 edit_file 吗?
不会——它在混合工作流中做补充。内置 read_file 由本地白名单放行(约 7 ms、每次 46 KB、零远程检查),所以 agy-fast 把小文件和已知行区间直接路由给并行的内置 read_file,而多查询搜索、符号大纲、带内联校验的多 hunk/多文件编辑以及并发检查则走 MCP。
支持哪些 Antigravity 版本和操作系统?
agy-fast 支持 Antigravity CLI(agy)、Antigravity Desktop 2.0 和 Antigravity IDE,覆盖 macOS、Linux、Windows。需要 Node.js >= 20,运行时零依赖(可选 ripgrep/rg,缺失时自动回退纯 Node.js)。
agy-fast 会把代码或会话记录发到外部服务器吗?
不会。所有 MCP 工具、SessionStart 快照 hook 和会话记录基准 CLI 都 100% 本地运行。唯一可选的网络请求是后台更新检查器每 12 小时查一次公开的 GitHub release tag,可以用 config --auto-update off 或 AGY_FAST_AUTO_UPDATE=off 改成仅通知或彻底关闭。
怎么验证加速效果,或者干净卸载?
运行 node dist/benchmark.mjs analyze --local --split-usage,完全离线地基准你自己的本地会话记录。想卸载时随时执行 node ~/.gemini/config/plugins/agy-fast/scripts/install.mjs uninstall。
开发
npm install
npm run typecheck # 严格 TypeScript 检查
npm run build # 用 esbuild 把 src/*.ts 打成 dist/*.mjs
npm test # 单元、MCP 协议、hook、基准与安装器测试
npm run bench:stress # 12 个场景的端到端压力与性能基准
npm run validate # 执行 `agy plugin validate --strict .`