Plugin Directories

Una Plugin Directory è un meccanismo che raccoglie in una singola directory skill, hook, server MCP, agenti personalizzati, configurazioni LSP e altro, caricandoli insieme. Usalo quando vuoi distribuire un insieme di funzionalità riutilizzabili all’interno dell’app o del repository. Nella versione Laravel puoi specificarli tramite pluginDirectories di SessionConfig o ResumeSessionConfig.

Casi d’uso

Distribuire più estensioni come un unico pacchetto di capacità
Includere plugin nel repository per far usare a tutti la stessa configurazione
Sviluppare e testare in locale plugin non ancora pubblicati sul Marketplace
Sovrascrivere temporaneamente plugin già installati con un checkout locale

Se hai un solo server MCP, un hook singolo o un solo agente personalizzato, è più semplice specificarli direttamente in mcpServers, hooks, customAgents. La Plugin Directory è più indicata quando vuoi distribuire insieme più funzionalità correlate.

Struttura della directory

Copilot CLI cerca in ciascuna plugin directory plugin.json oppure SKILL.md nella radice.

my-plugin/
├── plugin.json
├── SKILL.md
├── hooks.json
├── .mcp.json
├── agents/
│   └── code-reviewer.md
└── skills/
    └── lint-fix/
        └── SKILL.md

plugin.json può anche essere posto in .github/plugin.json o .github/plugin/plugin.json. Skill, hook, MCP, agenti ecc. hanno ciascuno loader indipendenti, quindi è sufficiente includere solo ciò che serve.

Caricamento da 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: 'Verifica questa modifica secondo le linee guida di review del plugin',
    );

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

Puoi specificarli anche come array.

Copilot::run(
    prompt: 'Migliora il README',
    config: [
        'pluginDirectories' => [
            base_path('plugins/docs-writer'),
        ],
    ],
);

Differenza rispetto a `cli_args`

Nell’SDK ufficiale sono a volte descritti come argomento --plugin-dir all’avvio del runtime. Nella versione Laravel, la scelta di base è usare pluginDirectories di SessionConfig. D’altra parte, se vuoi passare argomenti all’avvio del processo CLI stesso, puoi usare cli_args di config/copilot.php o di Copilot::useStdio(). Attenzione però: cli_args è efficace solo quando è l’SDK ad avviare il CLI in stdio e viene ignorato al collegamento a runtime esterni come useTcp().

$stdioConfig = config('copilot');
$stdioConfig['cli_args'] = [
    '--plugin-dir',
    base_path('plugins/code-reviewer'),
];

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

Di norma, preferisci pluginDirectories: puoi renderlo esplicito a livello di sessione e gestirlo nello stesso posto delle altre impostazioni di SessionConfig.

Buone pratiche per la riproducibilità

Usa percorsi assoluti con base_path() piuttosto che percorsi relativi
Metti sotto versione i plugin distribuiti col repository
Se usi plugin del Marketplace o distribuiti esternamente, documenta la versione utilizzata
In produzione, non lasciare specificare percorsi arbitrari di plugin direttamente dall’input utente

Riferimenti

Per le informazioni più recenti fai riferimento al repository GitHub.