Plugin Directories

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

适用场景

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

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

目录结构

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

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 加载

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'),
    ],
));

也可以用数组形式指定。

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 时会被忽略。

$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 或外部分发的插件时，将使用的版本写入文档
在生产环境下，不要允许从用户输入直接指定任意插件路径

参考

最新信息请参考 GitHub 仓库。