> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Directories

> 说明如何使用 Plugin Directory 一次性加载技能、钩子、MCP、自定义代理等。

## Plugin Directories

Plugin Directory 是一种把技能、钩子、MCP 服务器、自定义代理、LSP 配置等打包在一个目录中一起加载的机制。适用于希望把可复用的功能集合捆绑到应用或仓库的场景。

在 Laravel 版中，可以通过 `SessionConfig` 或 `ResumeSessionConfig` 的 `pluginDirectories` 指定。

## 适用场景

* 将多个扩展作为一个能力包分发
* 把插件与仓库一起分发，让所有人使用相同的配置
* 在上架 Marketplace 之前在本地开发、验证插件
* 用本地 checkout 临时覆盖已安装的插件

如果只是一个 MCP 服务器、一个钩子、一个自定义代理，直接指定到 `mcpServers`、`hooks`、`customAgents` 会更简单。Plugin Directory 更适合把多个相关功能一起分发的场景。

## 目录结构

Copilot CLI 会在每个插件目录中查找 `plugin.json` 或根目录下的 `SKILL.md`。

```text theme={null}
my-plugin/
├── plugin.json
├── SKILL.md
├── hooks.json
├── .mcp.json
├── agents/
│   └── code-reviewer.md
└── skills/
    └── lint-fix/
        └── SKILL.md
```

`plugin.json` 也可以放在 `.github/plugin.json` 或 `.github/plugin/plugin.json`。由于技能、钩子、MCP、代理等各自有独立的加载器，只包含需要的内容即可。

## 从 Laravel 加载

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session): void {
    $response = $session->sendAndWait(
        prompt: '请按照插件的评审规范来检查这个变更',
    );

    dump($response->content());
}, config: new SessionConfig(
    pluginDirectories: [
        base_path('plugins/code-reviewer'),
        base_path('plugins/lint-fix'),
    ],
));
```

也可以用数组形式指定。

```php theme={null}
Copilot::run(
    prompt: '改进 README',
    config: [
        'pluginDirectories' => [
            base_path('plugins/docs-writer'),
        ],
    ],
);
```

## 与 `cli_args` 的区别

在官方 SDK 中，有时会作为运行时启动时的 `--plugin-dir` 参数进行说明。在 Laravel 版中，基本上使用会话配置的 `pluginDirectories`。

另一方面，如果想给 CLI 进程启动本身传递参数，可以使用 `config/copilot.php` 的 `cli_args` 或 `Copilot::useStdio()` 的 `cli_args`。但 `cli_args` 只在 stdio 下由 SDK 启动 CLI 时有效，在 `useTcp()` 等连接外部 runtime 时会被忽略。

```php theme={null}
$stdioConfig = config('copilot');
$stdioConfig['cli_args'] = [
    '--plugin-dir',
    base_path('plugins/code-reviewer'),
];

Copilot::useStdio($stdioConfig)->start(fn (CopilotSession $session) => ...);
```

通常请优先使用 `pluginDirectories`。它可以按会话显式指定，并且与其他 `SessionConfig` 设置在同一位置进行管理。

## 为了可复现性

* 与其使用相对路径，不如使用 `base_path()` 等改为绝对路径
* 对与仓库一起分发的插件进行版本管理
* 使用 Marketplace 或外部分发的插件时，将使用的版本写入文档
* 在生产环境下，不要允许从用户输入直接指定任意插件路径

## 参考

* [SessionConfig](/zh/packages/laravel-copilot-sdk/session-config)
* [自定义代理](/zh/packages/laravel-copilot-sdk/custom-agents)
* [MCP](/zh/packages/laravel-copilot-sdk/mcp)
* [Hooks](/zh/packages/laravel-copilot-sdk/hooks)
* [Skills](/zh/packages/laravel-copilot-sdk/skills)

<Info>
  最新信息请参考 [GitHub 仓库](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [SessionConfig](/zh/packages/laravel-copilot-sdk/session-config.md)
- [流式事件](/zh/packages/laravel-copilot-sdk/streaming-events.md)
- [laravel/agent-skills — Laravel 官方 AI 智能体技能集](/zh/blog/agent-skills-introduction.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/zh/packages/laravel-boost-phpstorm-copilot.md)
- [使用 Vite 打包资源](/zh/vite.md)