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 整理。目录树合并了源码默认约定，用于教学表达；来源优先级、路径约束、启用配置和信任行为保持源码语义。