AI Pulse

零依赖本地插件,让 Antigravity 少花三成 token 配额、少传四成流量

零依赖本地插件,让 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)
启动快照 hookhooks.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 冒烟验证
离线基准 CLIdist/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.233.47-33.7%-38.2%-58.8%
上游请求 / 10 个操作(LLM + 远程检查)9.826.05-38.4%-42.6%-62.0%
Prompt Cache 命中率(未命中尖峰)89.6%(7.5%)94.0%(4.8%)+4.4 pp95.0%(3.3%)92.4%(2.8%)
未缓存新输入 / 操作10,413 tok4,822 tok-53.7%-61.5%-51.3%
预估计费配额 / 操作(1 : 0.1 : 5)22,458 eq15,387 eq-31.5%-36.5%-54.0%
工具返回上传 / 操作(实际本地字节)5.06 KB3.05 KB-39.7%-42.6%-13.3%
增量文本上传 / 操作(新输入估算)35.6 KB16.5 KB-53.7%-61.6%-51.3%
全上下文文本上传 / 操作(无状态重发估算)342.2 KB276.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_UPDATEauto(默认) / notify / off覆盖已保存的自动更新模式
AGY_FAST_UPDATE_INTERVAL_HOURS12(默认;1..720)后台检查间隔(小时)
AGY_FAST_UPDATE_CHANNELrelease(默认) / main跟踪稳定 semver release tag 还是 main
AGY_FAST_REPOGit URL使用自定义镜像或 fork
AGY_FAST_EDITS_FORMATauto(默认) / 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 .`
阅读原文
📚 相关主题 开源工程

订阅 AI Pulse

每天 08:00 · 12:30 · 18:30 · 23:50 更新