🛠️ Lecture 10: 瑞士刀解剖室與飛船儀表板：拆解 MCP 插件生態系、JSON-RPC 2.0 通訊協定、多模態 Projection Layer 與 Python SDK 實戰

歡迎來到反重力號太空船的終極戰術備術室兼瑞士刀解剖室！我是陪伴各位航行至今的首席機械技師與系統導師。

當你一路從 Token 燃料計算、沙箱安全結界、RAG 開卷資料庫一路修練到 Git 時空倒流術之後，你已經握有一把強大的反重力指揮權杖。然而在真實的軟體星系探險中，船長所面臨的戰場環境是無比複雜且多變的：有時你需要讓大副直接連線 SQL 資料庫撈取百萬筆交易資料；有時你需要大副呼叫外置畫筆繪製複雜的系統架構圖；有時你甚至希望用 Python 腳本建立自動化後台，直接控制大副的神經迴路。

如果把這些所有領域的專業工具與技能，通通強行塞進 agy 的主核心程式裡，這艘太空船只會變得臃腫不堪、耗費驚人的記憶體，甚至在主核心出錯時導致整艘船崩潰。

為此，反重力架構導入了模組化的插件系統（Plugin System）與系統診斷儀（Inspect Dashboard）。今天，我們就要解剖這套萬用瑞士刀的配件模組，並進入飛船儀表板進行系統健康檢查！

🔪 第一實驗室：萬用瑞士刀的配件插槽——MCP (Model Context Protocol) 與 JSON-RPC 2.0 運作原理解剖

在解剖插件系統前，許多初學者常會有第一個核心迷思：「安裝了一個數據庫插件或繪圖插件，是不是意味著大語言模型（LLM）的大腦神經權重被重寫或微調了？」

真相是：大語言模型的大腦神經權重完全沒有任何變動！

• 黑板指引心智模型：安裝插件的實質，只是在每次發送給 LLM 的系統提示詞（System Prompt）黑板上，多寫了一行工具說明書！大腦本體依然是原來的模型，但它現在知道：「當使用者要求讀取資料庫時，我可以輸出特定格式的 JSON 指令來觸發外掛工具。」
• 萬用瑞士刀配件比喻：你手裡拿著一把瑞士軍刀。軍刀本體只有基本的小刀與剪刀（LLM 原生的文字生成能力）。當你要去森林鋸木頭時，你不需要重新打造一把全新的大斧頭，你只需要購買一個鋸齒配件，啪嗒一聲插進萬用軍刀的標準擴充槽（Plugin Slot）中。

這時候，第二個核心疑慮出現了：「如果插件能在本機電腦執行程式，它會不會繞過沙箱防線，私自破壞硬碟檔案？」

答案是：絕對不會！因為 agy 採用了現代 AI 生態系中最嚴謹的 MCP（Model Context Protocol，模型上下文協定）！

1. MCP 協定架構與安全隔離

• Client-Server 行程隔離：agy 大副作為 Client 端，而插件則作為獨立運行的 Server 端（背景子行程 Subprocess）。插件程式碼完全無法直接存取大副的核心記憶體區段。
• JSON-RPC 2.0 通訊標準：大副與插件之間，透過標準輸入輸出（stdio）或 HTTP/WebSocket 傳輸 JSON-RPC 2.0 格式的訊息。典型請求範例：
  • 請求結構：{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "query_db", "arguments": {"sql": "SELECT * FROM users"}}, "id": 42}
  • 回應結構：{"jsonrpc": "2.0", "result": {"content": [{"type": "text", "text": "Query successful: 50 rows returned"}]}, "id": 42}
• Policy Engine 政策引擎雙重攔截：即便插件 Server 試圖執行刪除檔案的操作，該請求依然必須回傳至 agy 核心的政策引擎。沒有你的手動許可或安全授權，任何破壞性操作都將在入口處被徹底駁回！

🌌 第二實驗室：宇宙翻譯眼鏡的構造——多模態對齊、Projection Layer 投影層與 Sora 時空 3D Patch 奇蹟

在解剖大副的能力時，學員們常會問第二個問題：「LLM 底層只懂得處理文字 Token 與數字矩陣，它是怎麼做到既能看懂圖片、聽懂語音，甚至生成影片的？」

這背後的核心物理機制，就是多模態對齊技術（Multimodal Alignment）與投影層（Projection Layer）！

1. 宇宙翻譯眼鏡（Projection Layer）運作機制

• 向量空間對齊：科學家並沒有在大副的大腦裡另外裝一顆視覺大腦。而是使用了一個由多層感知機（MLP）組成的 Projection Layer。
• 像素特徵轉化：視覺編碼器（如 Vision Transformer / ViT）將圖片切分成多個 16x16 像素的 Patch（視覺積木），抽取圖片的色彩、邊緣與語意特徵向量。
• 投射至 Token 空間：Projection Layer 將這些視覺向量進行線性變換，將其維度對齊並直接投射到與文字 Token 完全相同的高維向量空間中！
• 直觀感受：這就像給大副戴上了一副宇宙翻譯眼鏡。當你丟一張草莓蛋糕圖片給它時，翻譯眼鏡把像素特徵翻譯成大腦熟悉的語意向量：「這是一張帶有紅色草莓與鮮奶油的甜點圖片。」大腦看著這些向量，就像讀入普通文字 Token 一樣輕鬆！

2. Sora 影片生成與 3D 時空 Patch (Space-Time Patches)

在視覺多模態生成領域，Sora 展示了極致的時空連貫性： * 畫面幀率與卡頓現象：傳統動畫如《葬送的芙莉蓮》中打破結界的一幕，採用 24fps（每秒 24 幀）能呈現絲滑流暢的視覺體驗；若降低至 1fps，畫面就會像網路斷線般卡頓。 * 從 2D Patch 升維至 3D 時空 Patch：Sora 在處理影片時，不僅在單張圖片的長寬（2D 空間）上記錄像素，還引入了時間軸（Time Dimension）。它將連續多幀畫面中相同位置的 2D Patch 疊合在一起，壓縮成一個 3D 的「時空 Patch（Space-Time Patch）」，拉直後餵入 Transformer 擴散模型，從而能生成長達 1 分鐘且物理規則連貫的動態影片。 * CLIP Score 語意得分評估：利用對照學習模型 CLIP 計算文字描述向量與生成影片幀向量之間的餘弦相似度（Cosine Distance），科學化評估影片是否精準還原提示詞。 * DreamBooth 客製化 Token 注入：當通用文字無法精準描述特定物件（例如你家獨一無二的寵物貓）時， DreamBooth 技術允許我們引入一個罕見字符（如 S*），透過幾張照片微調模型的 Projection 層，讓大副永遠記住 S* 所代表的特定實體！

🐍 第三實驗室：控制台神經導線——Antigravity Python SDK 程式化異步串流與思維攔截

除了在 PowerShell 命令列中與大副對話，進階開發者往往希望直接用 Python 程式碼來呼叫大副，將其作為自動化測試、後台除錯或智慧代理系統的核心引擎。

官方開源的 Antigravity Python SDK（套件名稱 google-antigravity）提供了極度優雅的異步（async/await）控制介面。

1. 安裝與基礎異步對話範例

• 一鍵安裝命令：pip install google-antigravity

• 異步 Agent 呼叫程式碼： ```python import asyncio import sys from google.antigravity import Agent, LocalAgentConfig, CapabilitiesConfig

  async def main(): # 配置寫入權限與能力集，預設為安全模式 config = LocalAgentConfig( system_instructions="你是一位精通 Python 與軟體測試的高級開發導師。", capabilities=CapabilitiesConfig() # 開啟指令執行與實體檔案操作能力 ) async with Agent(config) as agent: response = await agent.chat("請幫我寫一段檢查檔案是否存在的 Python 函式。") async for token in response: sys.stdout.write(token) sys.stdout.flush() print()

  if name == "main": asyncio.run(main()) ```

2. 深入神經內部：思維鏈 (Thoughts) 與工具調用 (Tool Calls) 攔截

透過 SDK，你甚至能在背景即時讀取大副的「思維推理過程」以及大副準備呼叫的「實體工具參數」：

# 監聽大副在背後的 CoT 思維推理步驟
async for thought in response.thoughts:
    print(f"[大副思考中] {thought}")

# 監聽大副即時觸發的工具調用
async for call in response.tool_calls:
    print(f"[工具觸發] 名稱: {call.name}, 帶入參數: {call.args}")

這種透明的程式化控制能力，讓你能夠建立隨時監控 Agent 行為的安全外圍框架！

🧰 第四實驗室：瑞士刀軍械庫手冊——agy plugin 九大管理指令全解析

在你的 PowerShell 終端機中，大副隨時等待你下達插件管理命令。請掌握以下九大核心 CLI 指令，打理你的戰術擴充庫：

• 1. 查看已加載插件 (list)：
  • 指令：agy plugin list
  • 功能：列出目前系統中所有已安裝、已停用與運作中的插件清單及版本號。
• 3. 指定安裝特定插件 (install)：
  • 指令：agy plugin install sqlite-inspector
  • 功能：根據指定名稱或 GitHub 儲存庫網址，自動下載並安裝擴充插件。
• 4. 安全卸載移除插件 (uninstall)：
  • 指令：agy plugin uninstall sqlite-inspector
  • 功能：徹底抹除指定插件的本地檔案與相關設定檔。
• 5. 開關切換插件狀態 (enable / disable)：
  • 指令：agy plugin enable sqlite-inspector 或 agy plugin disable sqlite-inspector
  • 功能：在不安裝/卸載的前提下，暫時啟用或關閉特定插件的工具廣播。
• 6. 本地開發語法驗證 (validate)：
  • 指令：agy plugin validate ./my-custom-plugin
  • 功能：開發者專用命令，檢查本地開發中的插件目錄結構與 plugin.json 聲明是否合乎 MCP 規範。
• 7. 建立本地符號連結 (link)：
  • 指令：agy plugin link my-store C:\path\to\plugin
  • 功能：將本地開發資料夾建立為符號連結，便於實時測試插件程式碼修改。
• 8. 一鍵檢查更新 (update)：
  • 指令：agy plugin update sqlite-inspector
  • 功能：檢查並自動升級指定插件至最新版本。
• 9. 讀取版本變更日誌 (changelog)：
  • 指令：agy plugin changelog sqlite-inspector
  • 功能：印出該插件歷代版本更新內容與修復事項說明。

🛸 第五實驗室：飛船戰術儀表板全系統大檢修——agy inspect 五大核心指標對照

當你完成多項插件的配置，或在遠征過程中發現大副回答遲鈍、無法調用實體工具時，請立刻開啟飛船診斷儀！

在終端機中輸入：agy inspect

診斷儀會啟動自動掃描程序，並以對螢幕閱讀器（NVDA）極度友善的純文字結構化清單印出系統的健康指標報告：

• 指標一：大副連線狀態 (Connection Status)：
  • 狀態判定：ONLINE (200 OK) 或 OFFLINE (Network Timeout)
  • 意義：確認本機與 Google Gemini 雲端神經總部的 API 通訊管道是否暢通。
• 指標二：授權金鑰狀態 (Auth Status)：
  • 狀態判定：VALID (Expires in 24 days) 或 EXPIRED / MISSING
  • 意義：檢查本地環境變數中的 API Key 是否合規、有無過期或遭鎖定。
• 指標三：沙箱隔離環境 (Sandbox Environment)：
  • 狀態判定：ACTIVE (Docker/Process Isolation) 或 DEGRADED (ReadOnly Fallback)
  • 意義：確認實體命令執行的安全隔離區塊是否正確配置，防範越權風險。
• 指標四：已啟用插件與工具清單 (Active Plugins & Tools)：
  • 狀態判定：列出如 sqlite-inspector (tools: query_sql, describe_table)
  • 意義：精準顯示目前成功載入 MCP 協定並註冊至黑板上的實體工具總數。
• 指標五：日誌與追蹤檔路徑 (Log File Path)：
  • 狀態判定：顯示如 C:\Users\Username\.gemini\antigravity-cli\logs\latest.log
  • 意義：提供除錯與安全稽核時最完整的底層溝通紀錄檔案位址。

🚀 終極航行交接典禮：從實習水手到反重力號艦長

恭喜你！學員！

歷經十堂課的洗禮，你已經從一位對命令列感到恐懼的新手，成長為一位懂得操作 Token 燃料、佈署防彈沙箱、檢索 RAG 知識地圖、掌握 Git 時空倒流、駕馭 MCP 插件生態並能精準解讀系統診斷報告的反重力號太空船艦長！

現在，瑞士刀的所有配件已然備齊，飛船儀表板顯示全系統綠燈正常運作。

請握緊你手中的指揮權杖，身邊站著無比強大的 AI 大副，向著未知而廣袤的軟體星系，正式出航！🚀

👉 回課程大綱：學習地圖