當舊版 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 檔案庫與發布目錄中必須遵循嚴格的檔案結構分工（以 AndyAWD/antigravity-cli-statusline 專案為真實範例）：
antigravity-cli-statusline/ ├── plugin.json # [必填] 外掛程式資訊清單（Manifest） ├── README.md # [推薦] 說明文件 (英文) ├── README.zh-TW.md # 說明文件 (繁體中文) ├── CONTRIBUTING.md # 貢獻指南 ├── skills/ # [必填] 技能（Skills）目錄根節點 │ └── antigravity-cli-statusline/ # [必填] 命名空間隔離目錄 (名稱必須與 plugin.json 的 name 完全一致) │ ├── SKILL.md # [必填] 技能說明書（含 YAML 前置資料（Frontmatter）標頭） │ ├── references/ # 補充參考文件 (windows.md, config-files.md, pitfalls.md) │ ├── resources/ # 靜態資源 (狀態列設定範本) │ └── scripts/ # 執行期腳本 (如 Node.js .mjs 腳本) └── docs/ # 專案說明文件與網誌文章目錄
下表詳細說明各實體路徑之職責與用途：
| 檔案/目錄路徑 | 類型 | 必填性 | 職責與用途說明 |
|---|---|---|---|
| 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 完整範例程式碼展示
以下為 AndyAWD/antigravity-cli-statusline 外掛專案之 plugin.json 真實程式碼：
{
"name": "antigravity-cli-statusline",
"version": "1.7.0",
"description": "Customize the Antigravity CLI statusline (footer) with quota, token, context, model, git branch and more across macOS / Linux / Windows.",
"author": "andyawd",
"license": "MIT",
"homepage": "https://github.com/andyawd/antigravity-cli-statusline"
}
4. 步驟 2：設計與撰寫命名空間技能（Writing Skills）
4.1 SKILL.md 的 YAML 前置資料（Frontmatter）規範
技能（Skills）是 Antigravity CLI 外掛程式的核心功能載體。必須存放於命名空間目錄 skills/<plugin-name>/SKILL.md（以 AndyAWD/antigravity-cli-statusline 專案之 skills/antigravity-cli-statusline/SKILL.md 為真實範例）。
--- name: antigravity-cli-statusline description: 本技能用於設定 Antigravity 命令列介面（CLI）（agy）的狀態列（Statusline / Footer）顯示指標、顯示順序與多語系介面（繁體中文 zh-tw / English us / 日本語 jp），並自動部署跨平台 Node.js 掛鉤（Hook）腳本（statusline-quota.mjs、fetch-local-quota.mjs）至 ~/.gemini/antigravity-cli/hooks/，同步註冊三層 settings.json（全域、命令列介面（CLI）專屬、專案）與 trusted_hooks.json 信任機制。 ---
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 antigravity-cli-statusline v1.7.0" git push origin main
7.2 一鍵安裝遠端外掛
agy plugin install https://github.com/andyawd/antigravity-cli-statusline
Agy CLI 會自動下載遠端儲存庫並解壓安裝至全域外掛目錄：~/.gemini/config/plugins/antigravity-cli-statusline/。
8. 綜合總結（Conclusion）
在看完 Antigravity CLI 外掛程式（Plugins）的架構演進介紹與完整實務開發指南後，相信你已經能更深入了解從 Gemini CLI 擴充功能（Extensions）到 Antigravity CLI 外掛程式（Plugins）的核心轉變，並掌握外掛程式在命名空間（Namespace）隔離、全元件封裝與安全沙盒機制上的設計精髓。
透過遵循官方的外掛架構規範（如本教學引用的 AndyAWD/antigravity-cli-statusline 真實範例），你能構建出高品質、跨平台相容且安全無虞的模組化代理工具包。將專屬技能（Skills）、程式碼庫規則（Rules）與子代理（Subagents）角色妥善封裝並發布至 GitHub，不僅能提升個人開發效率，更能為團隊帶來強大的能力共享與自動化工作流程！
沒有留言:
張貼留言