當舊版 Gemini CLI 正式走入歷史，全面跨越至 Antigravity CLI 已是 AI 代理開發者的必然趨勢。無論你是想將過去的舊版套件跨越升級，或是打算從頭打造全新的 Antigravity 外掛程式（Plugins），這篇文章都將手把手帶你掌握從目錄規劃、資訊清單（Manifest）設定、撰寫技能（Skills）、本地驗證，到發布至 GitHub 輔助託管與一鍵安裝的完整開發流程！
1. 簡介與前置準備（Introduction & Prerequisites）
1.1 本指南目標與適用對象
在 Antigravity 代理平台的架構演進下，舊版 Gemini CLI 擴充功能（Extensions）已全面升級為支援命名空間（Namespace）隔離、跨開發表面（Surfaces）相容、具備自主子代理（Subagents）與事件驅動掛鉤（Hooks）的新版外掛程式（Plugins）架構。
本指南適用對象包括：
- 希望為
Antigravity CLI開發自訂擴充功能（Extensions）與指令（Commands）的外掛程式（Plugins）開發者。 - 欲將舊版
Gemini CLI擴充套件遷移至新版Antigravity CLI外掛架構的維護人員。 - 希望封裝團隊通用技能（Skills）與規則（Rules）並透過 GitHub 共享的外掛維護者。
1.2 開發環境準備
在開始開發外掛程式之前，請確保開發環境已安裝並設定以下軟體與工具鏈：
- Antigravity CLI 工具：命令列介面主程式
agy（Antigravity CLI為獨立二進位執行檔，無需依賴 Node.js 環境即可獨立運作）。 - Git 版本控制工具：用於管理外掛程式原始碼儲存庫（Repository）與發布至 GitHub 輔助託管與一鍵安裝。
- 自訂腳本執行器（選填）：若外掛程式包含 Node.js（
.mjs）或 Python 等自訂事件掛鉤（Hooks）腳本，需準備對應之本地執行期環境。
2. 外掛程式基本目錄結構與 Layout 規範（Directory Structure & Layout）
2.1 標準外掛程式目錄架構說明
一個符合 Antigravity CLI 官方規範的外掛程式專案，在 Git 檔案庫與發布目錄中必須遵循嚴格的檔案結構分工：
my-custom-plugin/
├── plugin.json # [必填] 外掛程式資訊清單（Manifest）
├── README.md # [推薦] 說明文件 (含繁中與英文說明)
├── hooks.json # [選填] 事件驅動掛鉤（Hooks）設定檔
├── mcp_config.json # [選填] 模型上下文協定（Model Context Protocol） MCP 伺服器整合設定檔
├── skills/ # [必填] 技能（Skills）目錄根節點
│ └── my-custom-plugin/ # [必填] 命名空間隔離目錄 (名稱必須與 plugin.json 的 name 完全一致)
│ ├── SKILL.md # [必填] 技能說明書（含 YAML 前置資料（Frontmatter）標頭）
│ ├── references/ # [選填] 補充參考文件
│ ├── resources/ # [選填] 靜態資源 (如範本或字典檔)
│ └── scripts/ # [選填] 執行期腳本 (如 Node.js .mjs 腳本)
└── agents/ # [選填] 外掛內建自主子代理（Subagents）宣告目錄
└── my-subagent.json下表詳細說明各實體路徑之職責與用途：
| 檔案/目錄路徑 | 類型 | 必填性 | 職責與用途說明 |
|---|---|---|---|
plugin.json |
檔案 | 必填 | 資訊清單（Manifest），宣告外掛名稱、版本與描述。 |
skills/ |
目錄 | 必填 | 外掛技能之容器目錄。 |
skills/<plugin-name>/ |
目錄 | 必填 | 命名空間（Namespace）隔離目錄。目錄名稱必須與 plugin.json 中宣告之 name 屬性完全一致。 |
skills/<plugin-name>/SKILL.md |
檔案 | 必填 | 人工智慧（AI, Artificial Intelligence）代理閱讀之技能說明書，定義觸發條件與任務指示。 |
skills/<plugin-name>/references/ |
目錄 | 選填 | 存放補充參考文件 Markdown 檔案。 |
skills/<plugin-name>/resources/ |
目錄 | 選填 | 存放外掛所需之靜態資源，例如 JSON 專案範本。 |
skills/<plugin-name>/scripts/ |
目錄 | 選填 | 存放執行期腳本（如 Node.js .mjs 腳本）。 |
rules/ |
目錄 | 選填 | 存放專案程式碼庫規則（Rules）Markdown 檔案。 |
hooks.json |
檔案 | 選填 | 宣告事件驅動掛鉤（Hooks）腳本對應之生命週期觸發事件。 |
agents/ |
目錄 | 選填 | 宣告外掛內建之自主子代理（Subagents）設定檔。 |
2.2 外掛資產與系統目錄區分說明
在進行外掛程式專案開發時，請注意以下目錄用途之區分：
- 外掛資產目錄（
agents/）：外掛若包含內建自主子代理角色宣告檔，請放置於外掛根目錄下的agents/資料夾中（例如agents/my-subagent.json）。 - 開發期系統目錄（
.agents/）：專案根目錄下帶有前綴點號的.agents/目錄，為Antigravity CLI多代理團隊協作於開發期自動生成的系統中繼資料（Metadata）目錄，並不屬於外掛發布資產的一部份。
3. 步驟 1：建立外掛程式設定檔 plugin.json（Creating plugin.json）
3.1 plugin.json 欄位規格說明
資訊清單（Manifest）檔案 plugin.json 位於外掛程式根目錄，是 Antigravity CLI 識別外掛身份、版本與能力的進入點。
主要欄位規範說明如下：
| 欄位名稱 (Key) | 資料型態 | 必填性 | 規範與細節說明 |
|---|---|---|---|
name |
String | 必填 | 外掛程式之機器識別名稱。僅能包含小寫英文字母、數字、連字號（-）與底線（_）。必須與 skills/ 底下之命名空間目錄名稱完全相符。 |
description |
String | 必填 | 外掛程式之功能簡述。CLI 終端機與 AI 代理在讀取外掛清單時以此判定功能範疇。 |
version |
String | 推薦 | 符合語意化版本（Semantic Versioning，如 1.0.0）之版號字串。 |
author |
String | 選填 | 開發者姓名或 GitHub 帳號名稱。 |
license |
String | 選填 | 開源授權條款名稱（例如 MIT、Apache-2.0）。 |
homepage |
String | 選填 | 專案官方網站或 GitHub 儲存庫 URL。 |
plugin.json結構描述（Schema）中絕對不包含permissions與dependencies欄位（外掛程式無法在plugin.json中宣告權限或相依性），每個外掛均為獨立發布與執行的單元。- 所有安全防護與執行期隔離，均由代理控制框架（Agent Harness）執行期沙盒（Runtime Sandbox）與
trusted_hooks.json信任白名單機制掌管。
3.2 完整範例程式碼展示
以下為通用外掛 my-custom-plugin 之 plugin.json 範例程式碼：
{
"name": "my-custom-plugin",
"version": "1.0.0",
"description": "A compliant Antigravity CLI plugin providing custom project automation skills.",
"author": "developer-name",
"license": "MIT",
"homepage": "https://github.com/developer-name/my-custom-plugin"
}4. 步驟 2：設計與撰寫命名空間技能（Writing Skills）
4.1 SKILL.md 的 YAML 前置資料（Frontmatter）規範
技能（Skills）是 Antigravity CLI 外掛程式的核心功能載體。必須存放於命名空間目錄 skills/<plugin-name>/SKILL.md。
---
name: my-custom-plugin
description: 當使用者需要自動化專案建立或執行特定程式碼品質檢查時啟用此技能。
---5. 步驟 3：本地測試與語法校驗（Local Validation）
5.1 執行 agy plugin validate 靜態校驗
agy plugin validate ./6. 步驟 4：設定檔註冊與安全信任（Settings & Trust Model）
6.1 設定檔註冊三層架構實作
Antigravity CLI 採用三層優先權（Priority）設定檔（settings.json）架構：
- CLI 專屬設定檔（CLI Config，最高優先權）：
~/.gemini/antigravity-cli/settings.json。 - 全域設定檔（Global Config，中優先權）：
~/.gemini/settings.json。 - 專案層級設定檔（專案專屬）：
<project-root>/.gemini/settings.json。
6.2 將 Hook 腳本註冊至 trusted_hooks.json 之信任機制
若外掛程式包含事件掛鉤（Hooks）腳本，必須向全域信任檔案 ~/.gemini/trusted_hooks.json 註冊授權命令，以通過代理控制框架（Agent Harness）執行期沙盒的安全驗證。
7. 步驟 5：發布至 GitHub 與一鍵安裝（Publishing & Installing）
7.1 將外掛專案推送至 GitHub
git add .
git commit -m "feat: release my-custom-plugin v1.0.0"
git push origin main7.2 一鍵安裝遠端外掛
agy plugin install https://github.com/developer-name/my-custom-pluginAgy CLI 會自動下載遠端儲存庫並解壓安裝至全域外掛目錄：~/.gemini/config/plugins/my-custom-plugin/。
8. 結論（Conclusion）
遵循 Antigravity CLI 官方的外掛架構規範，能幫助開發者構建出高品質、具備命名空間隔離且跨平台相容的模組化工具包。透過將技能、規則與子代理妥善封裝並發布至 GitHub，團隊成員可實現高效的能力共享與自動化開發！
沒有留言:
張貼留言