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 條評論

登入 後參與評論

還沒有評論,來搶沙發~