# 插件 · 清单、发现与信任模型

> grok 的插件把 skills/commands/agents/hooks/MCP/LSP 打成一个可分发的目录。这一章看它的清单 schema、按作用域的发现优先级，以及那个关键的信任模型——信任按作用域判定，未受信插件只露出 agent 的元数据，技能、hooks 与 MCP 一律不加载。

- 作者：David（道雾轩）
- 专栏：Grok Build 源码解读（https://daiw.org/manual/grok-build.md）
- 最后更新：2026-09-15
- 原文：https://daiw.org/manual/grok-build/plugins-manifest
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

# 插件 · 清单、发现与信任模型

Part 4 讲扩展机制。插件是「把扩展打包分发」的顶层容器——一个自包含目录，捆着 skills、commands、agents、hooks、MCP、LSP。这套在 `xai-grok-agent/src/plugins/` + `xai-grok-plugin-marketplace`。

<Callout type="info">
  这一部分和你已读过的 [Claude Code 手册 · Plugins](https://daiw.org/manual/claude-code/plugins) 高度对应——grok **有意兼容** Claude 的插件约定(`.claude/plugins/`、`.claude-plugin/plugin.json`、`${CLAUDE_PLUGIN_ROOT}`)。两边对照读，能看清「同一套插件生态，一个是文档、一个是源码」。
</Callout>

## 清单：向前兼容的 plugin.json

清单按序找：`plugin.json` → `.grok-plugin/plugin.json` → `.claude-plugin/plugin.json`。它**故意向前兼容**(不 `deny_unknown_fields`，未知字段忽略)，字段有 `name`(kebab、≤64 字符)、`version`、`description`、`author`，以及各组件的路径覆盖(`skills`/`commands`/`agents`/`hooks`/`mcpServers`/`lspServers`)。

没有清单也行：按**约定**——目录名当插件名，只要目录里至少有一个组件(`skills/`、`.mcp.json`……)。两个安全细节：路径覆盖会做 `is_path_contained` 校验，**拒绝用 `..` 逃出插件根**；`${GROK_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_ROOT}`(Claude 别名 = Grok 同值)等 token 由 `substitute_plugin_tokens` 统一替换。

## 发现：按作用域定优先级

`discover_plugins` 按作用域扫，`PluginScope` 的枚举序数就是优先级：**`CliOverride`(0)> `Project`(1)> `User`(2)> `ConfigPath`(3)**。同名冲突时序数最小的赢。还有更细的 `PluginOrigin` 记来源(含 `ProjectClaude`/`UserClaude`/各种 marketplace 来源)，兼容 `.claude/plugins/installed_plugins.json`。

一个默认策略：CLI/ConfigPath 来源的插件**默认启用**，User/Project 来源的**默认禁用**(得显式 enable)——越「就近、越明确」的越自动生效。

## 信任模型：这一部分的重点

插件能跑任意代码(hooks、MCP 服务器命令)，所以信任是核心。**信任按作用域判定**：

- **CLI 指定的、用户级的**(`~/.grok/plugins/`、`~/.claude/plugins/`，以及从 marketplace 或 CLI 装进来的——装机即表态)**自动受信**；
- **项目插件跟随[目录信任](https://daiw.org/manual/grok-build/agents-md)**(folder-trust)——信任这个项目目录，其中的项目插件就一并受信，不再逐个授权；
- 只有 `[plugins].paths` 里、位于 `$HOME` 之外的目录，才查按「插件根的规范路径」记录的 `TrustStore`(`~/.grok/trusted-plugins`，一行一个路径)。

**未受信插件的行为**很讲究：它的 agents 只解析 frontmatter(提示词正文在受信前绝不进模型)，skills、commands 不加载(插件面板里仍列出名字)，**hooks、MCP 服务器、LSP 一律不启用**(面板显示为 blocked)。也就是「只露元数据，不跑任何东西」。

`active_plugins()`(enabled + **trusted**)才放行 skills、commands 与各种可执行组件；`enabled_plugins()`(仅 enabled)只给 agents 的元数据用。安全测试专门验证：一个在 enabled 列表里但未受信的项目插件，**绝不出现在 `active_plugins()` 里**——hooks 永不触发。顺带一提，`trust.rs` 的模块注释还写着「按插件根粒度信任、未受信插件的 skills 照样列出」，已经跟不上实现——读源码时，注释也要对照代码看。

```mermaid
flowchart TB
  D[发现插件] --> E{enabled?}
  E -->|否| SKIP["组件不加载(仍会列出)"]
  E -->|是| T{"trusted?<br/>(按作用域判定)"}
  T -->|是| ACT["active：skills+commands+agents+hooks+MCP+LSP 全放行"]
  T -->|否| MET["agents 仅 frontmatter；skills/commands 不加载<br/>hooks/MCP/LSP 一律拦"]
```

## 和《从 LLM 到 Coding Agent》对照

那本没有插件系统——它是产品级的分发关注点。grok 的插件把前面几章的能力(skills、hooks、MCP、subagent)打成可分发单元，还配了一套按作用域判定、「只露元数据不跑代码」的信任分层。这是「让第三方扩展你的 agent，又不被恶意扩展坑」的必答题。下一章看这些插件从哪来：marketplace。

---

上一篇：[Hooks](https://daiw.org/manual/grok-build/hooks) · 下一篇：[插件市场 · marketplace](https://daiw.org/manual/grok-build/plugins-marketplace)