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

從可見到可執行的三道門

1

來源與路徑

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

2

啓用狀態

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

3

執行信任

項目插件按 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

提交物
插件骨架與威脅表

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

插件系統的核心價值由能力面與信任面共同決定。目錄解決發現，安裝器解決落盤，運行時信任門決定哪些內容可以進入執行鏈。

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