# GitHub Copilot CLI 插件参考

查找 CLI 插件的命令和配置详细信息。

> \[!NOTE]
> 可以通过在终端中输入 `copilot plugin [SUBCOMMAND] --help` 来查找有关使用插件的帮助。

## CLI 命令

可以在终端中使用以下命令来管理插件 Copilot 命令行界面（CLI）。

| 命令                                             | 说明                                                                          |
| ---------------------------------------------- | --------------------------------------------------------------------------- |
| `copilot plugin install SPECIFICATION`         | 安装插件。 请参阅下面 [`install` 命令的插件规范](#plugin-specification-for-install-command)。 |
| `copilot plugin uninstall NAME`                | 删除插件                                                                        |
| `copilot plugin list`                          | 列出已安装的插件                                                                    |
| `copilot plugin update NAME`                   | 更新插件                                                                        |
| `copilot plugin marketplace add SPECIFICATION` | 注册市场平台                                                                      |
| `copilot plugin marketplace list`              | 列出已注册的交易平台                                                                  |
| `copilot plugin marketplace browse NAME`       | 浏览应用市场插件                                                                    |
| `copilot plugin marketplace remove NAME`       | 取消注册市场平台                                                                    |

###

```
          `install` 命令的插件规范
```

| Format      | 示例                           | 说明            |
| ----------- | ---------------------------- | ------------- |
| Marketplace | `plugin@marketplace`         | 来自已注册市场的插件    |
| GitHub      | `OWNER/REPO`                 | 存储库的根目录GitHub |
| GitHub  子目录 | `OWNER/REPO:PATH/TO/PLUGIN`  | 存储库中的子目录      |
| Git URL     | `https://github.com/o/r.git` | 任何 Git 网址     |
| 本地路径        |                              |               |

```
          `./my-plugin` 或 `/abs/path`    | 本地目录 |
```

## `plugin.json`

所有插件都包含一个插件目录，该目录至少包含一个位于 `plugin.json` 插件目录根目录的清单文件。 请参阅“[为 GitHub Copilot 命令行界面 (CLI) 创建插件](/zh/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating)”。

### 必填字段

| 领域     | 类型  | 说明                                       |
| ------ | --- | ---------------------------------------- |
| `name` | 字符串 | kebab-case 插件名称（仅限字母、数字和连字符）。 最大 64 个字符。 |

### 可选元数据字段

| 领域            | 类型  | 说明                  |
| ------------- | --- | ------------------- |
| `description` | 字符串 | 简要说明。 最大 1024 个字符。  |
| `version`     | 字符串 | 语义版本（例如 `1.0.0`， ）。 |
| `author`      | 对象  |                     |

```
          `name` （必需）、 `email` （可选）、 `url` （可选）。 |
```

\| `homepage`   | 字符串    | 插件主页 URL。 |
\| `repository` | 字符串    | 源存储库 URL。 |
\| `license`    | 字符串    | 许可证标识符（例如， `MIT`）。 |
\| `keywords`   | 字符串\[]  | 搜索关键字。 |
\| `category`   | 字符串    | 插件类别。 |
\| `tags`       | 字符串\[]  | 其他标记。 |

### 组件路径字段

这些命令告知 CLI 在何处查找插件的组件。 所有选项都是可选的。 如果省略，CLI 将使用默认约定。

| 领域           | 类型            | 默认        | 说明                                      |
| ------------ | ------------- | --------- | --------------------------------------- |
| `agents`     | 字符串 \| 字符串\[] | `agents/` | 智能体目录的路径（`.agent.md` 文件）。               |
| `skills`     | 字符串 \| 字符串\[] | `skills/` | 技能目录的路径（`SKILL.md` 文件）。                 |
| `commands`   | 字符串 \| 字符串\[] | —         | 命令目录路径。                                 |
| `hooks`      | string \| 对象  | —         | 挂钩配置文件或内联挂钩对象的路径。                       |
| `mcpServers` | string \| 对象  | —         | MCP 配置文件的路径（例如 "`.mcp.json`"），或内联服务器定义。 |
| `lspServers` | string \| 对象  | —         | LSP 配置文件路径或内嵌服务器定义。                     |

### 示例 `plugin.json` 文件

```json copy
{
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "license": "MIT",
  "keywords": ["react", "frontend"],
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}
```

## `marketplace.json`

可以通过创建一个 `marketplace.json` 文件并将其保存到 `.github/plugin/` 存储库的目录来创建插件市场，供用户用来发现和安装插件。 还可以将 `marketplace.json` 文件存储在本地文件系统中。 例如，将文件保存为 `/PATH/TO/my-marketplace/.github/plugin/marketplace.json` 允许你使用以下命令将其添加到 CLI：

```shell
copilot plugin marketplace add /PATH/TO/my-marketplace
```

> \[!NOTE]
> Copilot 命令行界面（CLI） 还会在 `.claude-plugin/` 目录中查找 `marketplace.json` 文件。

有关详细信息，请参阅“[为 GitHub Copilot 命令行界面 (CLI) 创建插件市场](/zh/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace)”。

### 示例 `marketplace.json` 文件

```json copy
{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Organization",
    "email": "plugins@example.com"
  },
  "metadata": {
    "description": "Curated plugins for our team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "frontend-design",
      "description": "Create a professional-looking GUI ...",
      "version": "2.1.0",
      "source": "./plugins/frontend-design"
    },
    {
      "name": "security-checks",
      "description": "Check for potential security vulnerabilities ...",
      "version": "1.3.0",
      "source": "./plugins/security-checks"
    }
  ]
}
```

> \[!NOTE]
> 每个插件的 `source` 字段值是插件目录的路径，相对于存储库的根目录。 不需要在路径的开头使用 `./` 。 例如，`"./plugins/plugin-name"` 和 `"plugins/plugin-name"` 指向同一目录。

###

```
          `marketplace.json` 字段
```

#### 顶级字段

| 领域      | 类型  | 必需 | 说明                     |
| ------- | --- | -- | ---------------------- |
| `name`  | 字符串 | 是的 | 串式命名法的市场名称。 最大 64 个字符。 |
| `owner` | 对象  | 是的 |                        |

```
          `{ name, email? }` — 市场所有者信息。 |
```

\| `plugins`  | 数组    | 是的      | 插件条目列表（请参阅下表）。 |
\| `metadata` | 对象   | 否       | `{ description?, version?, pluginRoot? }` |

#### 插件输入字段（数组中的 `plugins` 对象）

| 领域            | 类型            | 必需 | 说明                                                                           |
| ------------- | ------------- | -- | ---------------------------------------------------------------------------- |
| `name`        | 字符串           | 是的 | kebab-case 插件名称。 最大 64 个字符。                                                  |
| `source`      | string \| 对象  | 是的 | 获取插件的途径（相对路径、GitHub 或 URL）。                                                  |
| `description` | 字符串           | 否  | 插件说明。 最大 1024 个字符。                                                           |
| `version`     | 字符串           | 否  | 插件版本。                                                                        |
| `author`      | 对象            | 否  | `{ name, email?, url? }`                                                     |
| `homepage`    | 字符串           | 否  | 插件主页 URL。                                                                    |
| `repository`  | 字符串           | 否  | 源存储库 URL。                                                                    |
| `license`     | 字符串           | 否  | 许可证标识符。                                                                      |
| `keywords`    | 字符串\[]        | 否  | 搜索关键字。                                                                       |
| `category`    | 字符串           | 否  | 插件类别。                                                                        |
| `tags`        | 字符串\[]        | 否  | 其他标记。                                                                        |
| `commands`    | 字符串 \| 字符串\[] | 否  | 命令目录路径。                                                                      |
| `agents`      | 字符串 \| 字符串\[] | 否  | 代理目录路径。                                                                      |
| `skills`      | 字符串 \| 字符串\[] | 否  | 技能目录路径。                                                                      |
| `hooks`       | string \| 对象  | 否  | 钩子配置的路径或内嵌钩子对象。                                                              |
| `mcpServers`  | string \| 对象  | 否  | MCP 配置或内联服务器定义的路径。                                                           |
| `lspServers`  | string \| 对象  | 否  | LSP 配置或内联服务器定义的路径。                                                           |
| `strict`      | 布尔            | 否  | 当 `true`（默认值）时，插件必须符合完整的架构和验证规则。 当 `false` 时，使用宽松验证，允许更大的灵活性，特别是对于直接安装或旧版插件。 |

## 文件位置

| 物品     | 路径 |
| ------ | -- |
| 已安装的插件 |    |

```
          `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME` （通过市场安装）和 `~/.copilot/installed-plugins/_direct/SOURCE-ID/` （直接安装） |
```

\| 市场缓存    | 平台缓存目录： `~/.cache/copilot/marketplaces/` （Linux）、 `~/Library/Caches/copilot/marketplaces/` （macOS）。 可使用 `COPILOT_CACHE_HOME` 覆盖。 |
\| 插件清单      |
`.plugin/plugin.json`、 `plugin.json`、 `.github/plugin/plugin.json`或 `.claude-plugin/plugin.json` （按此顺序选中） |
\| 市场清单 |
`marketplace.json`、 `.plugin/marketplace.json`、 `.github/plugin/marketplace.json`或 `.claude-plugin/marketplace.json` （按此顺序选中） |
\| Agents               |
`agents/`（默认值，可在清单中覆盖） |
\| 技能               |
`skills/`（默认值，可在清单中覆盖） |
\| 挂钩配置  |
`hooks.json` 或 `hooks/hooks.json` |
\| MCP 配置    |
`.mcp.json`、`.github/mcp.json` |
\| LSP 配置    |
`lsp.json` 或 `.github/lsp.json` |

## 加载顺序和优先级

如果安装多个插件，则某些自定义代理、技能、MCP 服务器或通过 MCP 服务器提供的工具可能具有重复的名称。 在这种情况下，CLI 会根据优先顺序确定要使用的组件。

* **智能体和技能**采用“先找到者优先”的优先级。

  如果项目级自定义代理或技能的名称或 ID 与所安装的插件中的名称或 ID 相同，则插件中的代理或技能将被无提示忽略。 该插件无法替代项目级或个人配置。 自定义代理使用其 ID 删除重复数据，该 ID 派生自其文件名（例如，如果文件命名 `reviewer.agent.md`，则代理 ID 为 `reviewer`）。 技能通过其在 `SKILL.md` 文件中的名称字段进行去重。

* **MCP 服务器** 使用最后胜出优先权。

  如果安装一个插件，该插件使用与已安装的 MCP 服务器相同的服务器名称来定义 MCP 服务器，则插件的定义优先。 可以使用 `--additional-mcp-config` 命令行选项替代使用插件安装的相同名称的 MCP 服务器配置。

* **内置工具和智能体**始终存在，不能被用户定义的组件覆盖。

下图说明了加载顺序和优先规则。

```text
┌──────────────────────────────────────────────────────────────────┐
│  BUILT-IN - HARDCODED, ALWAYS PRESENT                            │
│  • tools: bash, view, apply_patch, glob, rg, task, ...           │
│  • agents: explore, task, code-review, general-purpose, research │
└────────────────────────┬─────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  CUSTOM AGENTS - FIRST LOADED IS USED (dedup by ID)                 │
  │  1. ~/.copilot/agents/           (user, .github convention)         │
  │  2. <project>/.github/agents/    (project)                          │
  │  3. <parents>/.github/agents/    (inherited, monorepo)              │
  │  4. <project>/.claude/agents/    (project)                          │
  │  5. <parents>/.claude/agents/    (inherited, monorepo)              │
  │  6. PLUGIN: agents/ dirs         (plugin, by install order)         │
  │  7. Remote org/enterprise agents (remote, via API)                  │
  └──────────────────────┬──────────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  AGENT SKILLS - FIRST LOADED IS USED (dedup by name)                │
  │  1. <project>/.github/skills/        (project)                      │
  │  2. <project>/.agents/skills/        (project)                      │
  │  3. <project>/.claude/skills/        (project)                      │
  │  4. <parents>/.github/skills/ etc.   (inherited)                    │
  │  5. ~/.copilot/skills/               (personal-copilot)             │
  │  6. ~/.agents/skills/                (personal-agents)              │
  │  7. PLUGIN: skills/ dirs             (plugin)                       │
  │  8. COPILOT_SKILLS_DIRS env + config (custom)                       │
  │  --- then commands (.claude/commands/), skills override commands ---│
  └──────────────────────┬──────────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  MCP SERVERS - LAST LOADED IS USED (dedup by server name)           │
  │  1. ~/.copilot/mcp-config.json       (lowest priority)              │
  │  2. PLUGIN: MCP configs              (plugins)                      │
  │  3. --additional-mcp-config flag     (highest priority)             │
  └─────────────────────────────────────────────────────────────────────┘
```

## 延伸阅读

* [GitHub Copilot 命令行界面 (CLI)](/zh/copilot/how-tos/copilot-cli)
* [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference)
* [GitHub Copilot 命令行界面编程参考](/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference)