Antigravity 自定义插件(plugin.json)与工作区配置优先级详解

团队既有 Skills 又有 Rules、Hooks 和专属 MCP 服务器,怎么打包成一个一键开关的整体?本文按 Google Antigravity 官方文档详解 plugin.json 目录规范、启停机制与五层配置加载优先级。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

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

打包自定义插件(plugin.json)四步

图:本站根据 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,你只想在做发版值班那天打开,平时关掉省上下文,可以通过两种方式切换:

  1. 在客户端设置界面或命令行切换:在图形界面的插件设置页点击开关,或在终端执行 agy plugin disable backend-devops-kit(重新打开用 agy plugin enable backend-devops-kit)。
  2. 理解 config.json 覆盖逻辑:无论你在界面点还是敲命令,系统都不会去改动插件自身的 plugin.json,而是把你的开关选择按插件文件夹名记录在用户外部的 config.json 里:
json
{
  "plugins": {
    "backend-devops-kit": { "enabled": false }
  }
}

只要 config.json 里有记录,你的手动选择就永远优先于插件自带的默认声明;而且因为偏好存在插件目录之外,日后团队用 Git 更新或重装插件时,你的个人开关状态完好保留。如果插件存放在非默认的共享目录,还可以通过工作区的 plugins.json 显式注册引入。

三、一张表看懂五层定制加载优先级

Antigravity 五层定制加载优先级

图:本站根据 Antigravity 定制系统总览文档 整理的优先级示意图

当你在工作区、共享 JSON、本机全局同时配了同名技能或规则时,Antigravity 严格按从高到低的五级顺序裁决:

  1. 第一优先级:工作区项目目录发现(从当前目录向上扫描至仓库根 .agents/);
  2. 第二优先级:工作区 JSON 显式声明(仓库内的 skills.json 或 plugins.json);
  3. 第三优先级:本机全局目录发现(~/.gemini/config/);
  4. 第四优先级:客户端内置默认定制(软件自带技能与内置插件,且内置插件规则豁免 2 万 Token 常驻预算上限,详见 Antigravity Rules 预算机制);
  5. 第五优先级:本机全局 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 充值,实时价格与售后边界(封号不在质保范围)以对应商品页为准。

相关教程

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~