Grok Build Source Course · 12 / 21

Marketplace：發現、安裝、執行分層

目錄能展示外掛，安裝器能複製或克隆外掛，執行時還要判斷啟用狀態與信任。把三層拆開，才能看清外掛生態的真實安全邊界。

Indexed + FallbackManifestInstall RegistryPer Plugin Root Trust

01 / OBJECTIVES

課程目標

還原發現鏈

解釋索引優先、檔案系統回退、manifest 解析與來源優先順序。

分開四種狀態

區分可發現、已安裝、已啟用、受信任，避免用一個「已安裝」覆蓋全部語義。

畫出執行邊界

判斷 skill、agent、hook、MCP 與 script 在未信任狀態下的處理差異。

02 / CORE VISUAL

外掛從目錄走向執行時

03 / STRUCTURE

Marketplace 與 Plugin 的真實結構

MARKETPLACE

目錄負責「有哪些」

marketplace-root/
├── .grok-plugin/
│   ├── marketplace.json
│   └── plugin-index.json
├── plugins/
│   └── sample-plugin/
└── default-skills/

掃描器先讀索引；缺失或無效時掃描 plugins/*/。default-skills 可作為虛擬外掛加入結果。

xai-grok-plugin-marketplace/src/scanner.rs · index.rs · catalog.rs

PLUGIN

外掛負責「包含什麼」

sample-plugin/
├── plugin.json
├── skills/*/SKILL.md
├── commands/
├── agents/
├── hooks/hooks.json
├── .mcp.json
└── scripts/

plugin.json 是首選 manifest，.grok-plugin/plugin.json 與 .claude-plugin/plugin.json 是後備位置。PluginManifest 可覆蓋 skills、commands、agents、hooks、MCP 與 LSP 路徑；解析後還要驗證路徑仍包含在外掛根目錄內。

xai-grok-agent/src/plugins/manifest.rs · docs/hooks-and-plugins.md

04 / DISCOVERY

兩條發現鏈各司其職

CLI override--plugin-dir
最高來源優先順序

Project.grok/plugins
相容 .claude

User$GROK_HOME/plugins
已安裝外掛

Registrymarketplace provenance
git / local 來源

Config path[plugins].paths
位置影響信任

關鍵區分：xai-grok-plugin-marketplace 負責目錄、掃描和安裝；xai-grok-agent::plugins 負責執行時發現、去重、名稱衝突、啟用與信任。Marketplace 中出現一條記錄，不代表元件立即執行。

05 / THREE GATES

從可見到可執行的三道門

來源與路徑

MarketplaceRelativePath 拒絕絕對路徑、父目錄穿越和越界 join。遠端條目可用 git ref 或 SHA 定位內容。

啟用狀態

發現配置維護 enabled 與 disabled。專案或使用者範圍預設加入 disabled 列表，CLI override 與 config path 預設加入 enabled，使用者可顯式調整。

執行信任

專案外掛按 canonical plugin root 授權，粒度是單個外掛根。信任記錄寫入 ~/.grok/trusted-plugins。

06 / TRUST

未信任外掛的元件矩陣

元件

發現

未信任時的執行

Skills / Agents

可列出中繼資料

保持中繼資料級發現

Hooks

可從 manifest 識別

阻止載入執行

MCP Servers

可從配置路徑識別

阻止啟動命令

Scripts

屬於外掛內容

阻止執行

FAIL CLOSED

路徑解析失敗視為未信任

match dunce::canonicalize(plugin_root) {
    Ok(path) => self.trusted.contains(&path),
    Err(_) => false,
}

TRUST SCOPE

來源影響初始判斷

CLI override 與使用者範圍在原始碼中標記為 trusted；專案範圍要求顯式信任；config path 位於使用者 home 下時可自動信任，其他位置仍需授權。

crates/codegen/xai-grok-agent/src/plugins/trust.rs · discovery.rs

07 / SOURCE

安裝器保留來源，目錄不承諾規模

PROVENANCE

安裝記錄可追溯

本地 Marketplace 透過 managed install storage 安裝；遠端條目透過 Git URL、ref、SHA 與 subdir 定位。InstallRegistry 寫入 MarketplaceProvenance。

xai-grok-plugin-marketplace/src/installer.rs

EVIDENCE LIMIT

原始碼證明機制，不證明生態規模

當前程式碼能夠證明官方源常量、多個來源、目錄索引、搜尋和安裝流程。它無法單獨證明外掛數量、活躍作者、審核覆蓋率或增長速度，本頁不作這些推斷。

xai-grok-plugin-marketplace/src/lib.rs · types.rs

08 / LAB

課堂練習：為外掛畫威脅模型

35 MIN

提交物
外掛骨架與威脅表

建立一個含 skill、hook 與 MCP 配置的最小外掛目錄，寫出 manifest。
建立 Marketplace 索引項，並說明索引缺失時檔案系統如何回退。
列出可發現、已安裝、已啟用、受信任四個狀態，畫出允許的轉換。
設計三個攻擊：路徑穿越、惡意專案 Hook、同名外掛搶佔，逐項找到原始碼護欄。
指出一個剩餘風險，並給出安裝前審閱、SHA 固定或最小權限方案。

Takeaway

外掛系統的核心價值由能力面與信任面共同決定。目錄解決發現，安裝器負責寫入磁碟，執行時信任門決定哪些內容可以進入執行鏈。

原始碼快照說明：本頁依據本地 grok-build-main 的 xai-grok-plugin-marketplace 與 xai-grok-agent::plugins 整理。目錄樹合併了原始碼預設約定，用於教學表達；來源優先順序、路徑約束、啟用配置和信任行為保持原始碼語義。