結論先說
- 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 條評論
還沒有評論,來搶沙發~