2026年7月24日 星期五

Antigravity CLI 工具使用指南：Plugins（上）

隨著舊版 Gemini CLI 停止維護，開發者社群正全面跨越至具備自主代理架構的 Antigravity CLI。如果你過去曾使用過 Gemini CLI 的擴充功能（Extensions），或正準備打造新一代的 AI 代理工具，這篇文章將帶你了解如何從舊版 Gemini CLI 順暢跨越至 Antigravity CLI，並掌握其全新升級的外掛程式（Plugins）機制與遷移技巧！

1. 前言與演進背景（Introduction & Background）

1.1 從 Gemini CLI Extensions 到 Antigravity CLI Plugins 的演進

在 Gemini CLI 時代，開發者透過擴充功能（Extensions）為終端機介面新增技能（Skills）與工具，並由資訊清單（Manifest）檔案 gemini-extension.json 進行宣告。

隨著系統演進至 Antigravity 代理平台，Agy CLI 的標準擴充機制唯一為外掛程式（Plugins）（單軌制）。底層升級為全平台共享的代理控制框架（Agent Harness）執行期（Runtime）。擴充機制也隨之全面升級為外掛程式（Plugins），將原本單純的 CLI 擴充，提升為具備命名空間隔離、跨開發表面（Surfaces）攜帶與多代理協同能力的模組化能力包。

1.2 核心跨越與升級動機

從舊版 Gemini CLI Extensions 跨越至新版 Antigravity CLI Plugins，主要帶來了三大核心轉變：

  • 跨開發表面可攜性（Cross-Surface Portability）：舊版 Extension 僅作用於 Gemini CLI 終端；新版 Plugin 封裝的能力可同時載入至 CLI、整合開發環境側邊欄（IDE Sidebar）與桌面應用程式（Desktop App）。
  • 強制的技能命名空間（Skill Namespacing）：舊版 Extension 的技能存放在 skills/<skill-name>/，全域載入同名技能時易生衝突；新版 Plugin 強制將技能隔離於 skills/<plugin-name>/ 目錄下。
  • 多代理與規則原生支援（Subagents & Rules）：新版 Plugin 原生支援於 agents/ 宣告自主子代理（Subagents）與於 rules/ 宣告程式碼庫規則（Rules），提供更深度的代理工作流程。

2. 概念定義與架構定位（Concept & Architecture）

2.1 舊版 Gemini CLI 擴充功能（Extensions）之定位

舊版 Gemini CLI Extensions 是專門為 Gemini CLI 終端介面設計的擴充套件，100% 吻合 geminicli.com 事實標準。其特點包括：

  • 資訊清單（Manifest）：於擴充功能專案根目錄宣告獨立資訊清單檔案 gemini-extension.json，用於宣告名稱、版本、描述與工具限制（excludeTools）。
  • 範疇與設定：支援工具限制（excludeTools）、模型上下文協定（Model Context Protocol）設定 mcpServers，以及存放於 skills/<skill-name>/SKILL.md 的技能（Skills）檔案與簡單腳本。
  • 管理方式：透過指令（Commands） gemini extensions install / update / list / disable / enable / uninstall 進行管理。

2.2 新版 Antigravity CLI 外掛程式（Plugins）之定位

新版 Antigravity CLI Plugins 是 Antigravity 體系中的一等公民（First-class Citizen）發布資產，確立 Agy CLI 的標準擴充機制唯一為 Plugin（單軌制）。由 plugin.json 宣告，其特點包括：

  • 資訊清單（Manifest）：使用符合官方結構清單（Schema）規範的 plugin.json 進行驗證。plugin.json 中無 permissions 與 dependencies 欄位，安全完全由代理控制框架（Agent Harness）沙盒（Agent Harness Runtime Sandbox）與 trusted_hooks.json 掌管。
  • 全元件整合：可單一封裝技能（skills/）、規則（rules/）、子代理（agents/）、MCP 伺服器（mcp_config.json）與事件掛鉤（hooks.json）。
  • 管理方式：透過 agy plugin 專屬指令集進行管理，支援 list、import、install、uninstall、enable、disable、validate 與 link 等操作。

3. 核心差異綜合對照（Core Comparison Matrix）

下表詳盡比較舊版 Gemini CLI 擴充功能（Extension）與新版 Antigravity CLI 外掛程式（Plugin）的核心維度：

比較維度 舊版 Gemini CLI 擴充功能（Extension） 新版 Antigravity CLI 外掛程式（Plugin）
系統地位 舊版 Gemini CLI 專用擴充套件 新版全平台共享模組化代理能力包（唯一標準單軌制）
底層引擎 Gemini CLI 專屬終端執行期 全平台代理控制框架（Agent Harness）執行期
表面相容性 僅作用於 Gemini CLI 終端 可同時載入至 CLI、整合開發環境側邊欄（IDE Sidebar）與桌面應用程式（Desktop App）
資訊清單檔名 獨立資訊清單 gemini-extension.json 官方 plugin.json 規範（無 permissions / dependencies 欄位）
技能目錄結構 自由技能名：skills/<skill-name>/SKILL.md（易產生全域衝突） 強制命名空間：skills/<plugin-name>/SKILL.md（隔離防衝突）
自主子代理封裝 核心（Core）支援 Subagents，但舊版 Extension 不支援於外掛專案內部打包 agents/ 原生支援於外掛專案 agents/ 目錄內建發布專屬自主子代理（Subagents）
專案規則支援 不支援 支援於 rules/ 目錄定義程式碼庫規則（Rules）
工具與安全防護 於 gemini-extension.json 宣告 excludeTools 停用特定工具，支援 mcpServers 由代理控制框架（Agent Harness）沙盒與 trusted_hooks.json 白名單掌管保護
CLI 管理指令 gemini extensions ... agy plugin install / list / disable / enable / uninstall / validate

4. 外掛程式（Plugin）架構元件解析（Plugin Components Deep Dive）

Antigravity CLI 外掛程式（Plugin）是模組化的發布資產。一個完整的外掛程式由以下核心元件構成：

4.1 資訊清單（plugin.json）

位於外掛專案根目錄，為識別外掛身份的進入點：

{
  "name": "my-custom-plugin",
  "version": "1.0.0",
  "description": "A compliant Antigravity CLI plugin providing custom skills and rules.",
  "author": "developer-name",
  "license": "MIT",
  "homepage": "https://github.com/developer-name/my-custom-plugin"
}
💡 註：官方 plugin.json 結構清單（Schema）規範不包含 permissions 與 dependencies 欄位，敏感操作完全由代理控制框架（Agent Harness）沙盒動態保護。

4.2 命名空間技能（skills/<plugin-name>/SKILL.md）

外掛程式的技能必須放置於強制命名空間目錄 skills/<plugin-name>/SKILL.md。檔頭包含 YAML 前置資料（Frontmatter）：

---
name: my-custom-plugin
description: 當使用者需要自動化專案建立或執行特定程式碼品質檢查時啟用此技能。
---

4.3 代理、規則、MCP 與掛鉤元件

外掛程式可根據需求選擇性包含以下元件：

  • 自主子代理（agents/）：宣告獨立運作的專屬子代理角色 JSON 檔案。
  • 程式碼庫規則（rules/）：定義團隊方針與程式碼風格約束 Markdown 檔案。
  • MCP 伺服器整合（mcp_config.json）：宣告專屬的模型上下文協定（Model Context Protocol）伺服器整合。
  • 事件掛鉤（hooks.json）：宣告事件驅動腳本之生命週期掛鉤（Hooks）。

5. 舊版 Extensions 遷移至新版 Plugins 指南（Migration Guide）

如果你手邊擁有舊版 Gemini CLI 的擴充功能專案（包含 gemini-extension.json），可以透過以下方式順暢遷移至 Antigravity CLI Plugins：

5.1 使用 agy plugin import 一鍵自動匯入

Antigravity CLI 提供了專屬的自動遷移指令：

agy plugin import gemini

執行該指令後，Agy CLI 會自動掃描本地的舊版 Gemini 擴充功能，將 gemini-extension.json 轉譯重構為符合官方結構清單（Schema）的 plugin.json，並自動建立 skills/<plugin-name>/ 命名空間目錄結構。

5.2 手動重構與命名空間修復步驟

若希望手動將 GitHub 上的舊版延伸功能發布為新版 Plugin，請遵循以下步驟：

  1. 重構資訊清單：將根目錄的 gemini-extension.json 重命名為 plugin.json 並調整對應欄位。
  2. 建立命名空間目錄：將原本 skills/<skill-name>/ 底下的技能檔案，移至以外掛名稱命名的 skills/<plugin-name>/ 目錄中。
  3. 本地驗證：在終端機執行 agy plugin validate ./ 確保結構校驗通過。

6. 管理指令完全對照（Command Reference）

在日常營運與維護中，兩者管理指令（Commands）的對照如下（注意：Agy CLI 無 update 指令，更新時重新執行 install 即可）：

管理功能 舊版 Gemini CLI 指令 新版 Antigravity CLI 指令
安裝外掛/延伸 gemini extensions install <URL/Path> agy plugin install <URL/Path>
更新外掛/延伸 gemini extensions update <name> 無 update 指令。重新執行 agy plugin install <target> 覆蓋即可
列出已安裝項 gemini extensions list agy plugin list
停用外掛/延伸 gemini extensions disable <name> agy plugin disable <name>
啟用外掛/延伸 gemini extensions enable <name> agy plugin enable <name>
卸載外掛/延伸 gemini extensions uninstall <name> agy plugin uninstall <name>
本地語法校驗 無 agy plugin validate [path]
匯入舊版延伸 無 agy plugin import gemini

7. 結論（Conclusion）

隨著 Gemini CLI 正式走入歷史，全面跨越至 Antigravity CLI 及其 Plugin 架構已是必然趨勢。理解 Gemini CLI Extensions 與 Antigravity CLI Plugins 之間的演進脈絡，並掌握 Plugin 在技能封裝、命名空間隔離與多代理協同上的核心優勢，能協助開發者快速完成資產遷移，構建出更符合現代代理工程規範的模組化工具。

於

沒有留言:

張貼留言

訂閱： 張貼留言 (Atom)