结论先说
- Plugin(插件)是把 Skills、Rules、Hooks 和 MCP 捆绑在一起的「命名空间包裹」:只要在目录下放一份必填的
plugin.json清单,这四类定制就会作为一个整体同时启用或同时卸载。 - 原生插件有两个目录位置细节别写错:插件规则推荐合并写成
rules/AGENTS.md;而钩子文件hooks.json必须直接放在插件根目录,放进子文件夹不会被原生扫描识别。 - 开关状态记在外部
config.json里,升级插件不会冲掉你的设置:可通过界面设置或agy plugin enable / disable一键启停,关闭后插件里的 MCP 和规则完全不加载。 - 同名定制冲突时,工作区
.agents/永远压过本机~/.gemini/config/:官方严格按五层优先级从近到远覆盖。 - 账号配套与跨平台编程订阅入口:运行
agy命令行、SDK 与多子代理并发依赖正常可用的谷歌账号与充裕模型配额,账号准备见本站 谷歌账号说明页,免境外卡开通终端编程会员见 Claude Code 订阅页 与 AI 会员充值总览。

图:本站根据 Antigravity Plugins 官方文档 整理的示意图
本文根据 Google Antigravity 官方插件与定制系统文档(antigravity.google/docs/plugins)整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是软件界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 团队内部积累了好几个技能(Skills)、规则(Rules)、钩子(Hooks)和内网 MCP 配置,不想在十几个仓库里零散复制粘贴的架构师;
- 想把某套重型工具(比如数据库巡检全家桶)做成按需一键开关、不用时彻底零上下文占用的开发者;
- 在本机全局目录和项目
.agents/里配了同名项,搞不清到底哪一份会覆盖哪一份的人。
一、标准插件目录结构与 plugin.json 写法
在项目根目录 .agents/plugins/(或本机全局 ~/.gemini/config/plugins/)下新建一个以插件命名的文件夹,标准布局如下:
text
.agents/plugins/backend-devops-kit/
├── plugin.json # 必填:声明该目录是一个插件
├── mcp_config.json # 可选:随插件自动启动的专属 MCP 服务器
├── hooks.json # 可选:注意必须放在插件根目录,不要套子目录
├── rules/ # 可选:插件启用时合并生效的规则
│ └── AGENTS.md # 官方推荐用单份 AGENTS.md 汇总插件规则
└── skills/ # 可选:插件暴露的工作流技能包
└── db-release-check/
└── SKILL.md
根目录下的 plugin.json 是系统识别插件的标志文件,最简写法只需一行 name(若省略则默认取文件夹名称),也可以补齐团队维护信息或设为默认关闭:
json
{
"name": "backend-devops-kit",
"author": {
"name": "Platform Engineering Team",
"url": "https://internal.example.com/devops"
},
"repository": "https://git.example.com/ai/backend-devops-kit",
"disabled": false
}
当插件启用时,系统会自动为它暴露的技能和 MCP 工具加上必要的命名空间(Namespacing),防止和别的插件重名打架。各子组件的详细语法可分别查阅本站前几篇拆解:Antigravity Skills 技能编写、Antigravity MCP 服务器配置 与 Antigravity Hooks 钩子配置。
准备搭建团队开发环境但还缺少合规个人谷歌账号的读者,可参考 谷歌账号购买与首登指南 或前往自动发货的 谷歌邮箱成品号商品页(质保说明以商品页为准)。
二、怎么按需启停插件(外部 config.json 机制)
大多数被自动发现的插件默认处于开启状态;如果某个插件挂了好几个重型内网 MCP,你只想在做发版值班那天打开,平时关掉省上下文,可以通过两种方式切换:
- 在客户端设置界面或命令行切换:在图形界面的插件设置页点击开关,或在终端执行
agy plugin disable backend-devops-kit(重新打开用agy plugin enable backend-devops-kit)。 - 理解
config.json覆盖逻辑:无论你在界面点还是敲命令,系统都不会去改动插件自身的plugin.json,而是把你的开关选择按插件文件夹名记录在用户外部的config.json里:
json
{
"plugins": {
"backend-devops-kit": { "enabled": false }
}
}
只要 config.json 里有记录,你的手动选择就永远优先于插件自带的默认声明;而且因为偏好存在插件目录之外,日后团队用 Git 更新或重装插件时,你的个人开关状态完好保留。如果插件存放在非默认的共享目录,还可以通过工作区的 plugins.json 显式注册引入。
三、一张表看懂五层定制加载优先级

图:本站根据 Antigravity 定制系统总览文档 整理的优先级示意图
当你在工作区、共享 JSON、本机全局同时配了同名技能或规则时,Antigravity 严格按从高到低的五级顺序裁决:
- 第一优先级:工作区项目目录发现(从当前目录向上扫描至仓库根
.agents/); - 第二优先级:工作区 JSON 显式声明(仓库内的
skills.json或plugins.json); - 第三优先级:本机全局目录发现(
~/.gemini/config/); - 第四优先级:客户端内置默认定制(软件自带技能与内置插件,且内置插件规则豁免 2 万 Token 常驻预算上限,详见 Antigravity Rules 预算机制);
- 第五优先级:本机全局 JSON 声明。
常见问题
问:我把 Claude Code 或旧版 Gemini CLI 的扩展迁过来时,hooks/hooks.json 能识别吗?
答:如果你是通过命令 agy plugin install 导入纯 Gemini CLI(gemini-extension.json)或 Claude Code(.claude-plugin/plugin.json)扩展包,安装器会自动帮你把子目录里的钩子搬运到插件根目录;但如果你是自己手建带 plugin.json 的原生插件,必须直接放在 <插件根>/hooks.json。
问:插件里的钩子脚本怎么找到插件自带的数据缓存目录?
答:官方运行时会自动向插件钩子与插件 MCP 进程注入两个环境变量:PLUGIN_ROOT(插件所在目录)与 PLUGIN_DATA(插件持久化数据目录),在脚本里直接读取这两个环境变量即可。
问:禁用插件后它还会显示在插件列表里吗?
答:会保留在列表里显示为未启用状态,方便你随时一键重新打开,但处于禁用期间不会加载它内部的任何规则、技能或外部工具进程。
问:跑多子代理和终端工具时没有合规谷歌账号或海外信用卡怎么办?
答:可在 本站充值中心 通过支付宝、微信支付或 AlipayHK 即买即发获取 谷歌邮箱成品号,或免上号自助兑换 Claude Pro 自助卡密 与 Claude Max 充值,实时价格与售后边界(封号不在质保范围)以对应商品页为准。
0 条评论
还没有评论,来抢沙发~