Directorios de complementos

En esta guía se explica el diseño de la carpeta del complemento, cómo cargar un complemento desde un directorio, cuándo usar directorios de complementos frente al registro de extensiones individuales y cómo hacer que los conjuntos de complementos sean deterministas.

Cuándo usar directorios de complementos

Use un directorio de complementos cuando desee:

•           **Distribuye un paquete de capacidades** como una sola unidad; por ejemplo, un paquete de revisor de TypeScript con una habilidad, un `preToolUse`hook que aplica la validación de código y un agente personalizado que ejecuta el revisor.
  

• La funcionalidad del proveedor se empaqueta en un repositorio para que cada clon de la aplicación host cargue las mismas extensiones de forma determinista.
• Desarrolle un complemento localmente antes de publicarlo en marketplace.

•           **Sobrescribe o amplía** un complemento instalado desde el marketplace con una copia local para realizar pruebas.
  

Si solo necesita agregar un único servidor MCP, un único enlace o un único agente personalizado, puede registrarlo en línea a través de la configuración del SDK (mcpServers, hooks, customAgents). Los directorios de complementos son más útiles una vez que tiene tres o más extensiones relacionadas que se envían juntas.

Diseño de carpeta del complemento

La CLI de Copilot analiza cada directorio de complementos en busca de un plugin.json manifiesto o un SKILL.md en el nivel raíz. Un complemento mínimo tiene este aspecto:

my-plugin/
├── plugin.json              # manifest (required unless using SKILL.md only)
├── SKILL.md                 # optional: top-level skill
├── hooks.json               # optional: hooks config
├── .mcp.json                # optional: MCP server config
├── agents/                  # optional: custom agents (one .md file per agent)
│   └── code-reviewer.md
└── skills/                  # optional: additional skills
    └── lint-fix/
        └── SKILL.md

El manifiesto también puede estar activo en .github/plugin.json o .github/plugin/plugin.json para que los complementos puedan estar dentro de un repositorio existente sin cambiar su diseño raíz. Cada subsistema (enlaces, MCP, LSP, aptitudes, agentes) tiene su propio cargador y es opcional, un complemento solo necesita las partes que contribuye.

Para consultar el esquema completo del manifiesto, consulta la documentación del tiempo de ejecución a la que se hace referencia desde el comando de barra (/plugin) de tu CLI.

Carga de un directorio de complementos desde el SDK

Los directorios de complementos se cargan pasando --plugin-dir <path> a la CLI de Copilot cuando el SDK lo genera. Cada lenguaje expone esto a través de la opción extra-args de la conexión de tiempo de ejecución. Esta opción puede repetirse para cargar varios plugins.

import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";

const client = new CopilotClient({
  connection: RuntimeConnection.forStdio({
    args: [
      "--plugin-dir", "./plugins/code-reviewer",
      "--plugin-dir", "./plugins/lint-fix",
    ],
  }),
});

await client.start();

from copilot import CopilotClient, StdioRuntimeConnection

client = CopilotClient(
    connection=StdioRuntimeConnection(
        args=(
            "--plugin-dir", "./plugins/code-reviewer",
            "--plugin-dir", "./plugins/lint-fix",
        ),
    ),
)
await client.start()

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{
        Args: []string{
            "--plugin-dir", "./plugins/code-reviewer",
            "--plugin-dir", "./plugins/lint-fix",
        },
    },
})
if err := client.Start(ctx); err != nil {
    return err
}

using GitHub.Copilot;

await using var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForStdio(args: new[]
    {
        "--plugin-dir", "./plugins/code-reviewer",
        "--plugin-dir", "./plugins/lint-fix",
    }),
});

await client.StartAsync();

var options = new CopilotClientOptions()
    .setCliArgs(new String[] {
        "--plugin-dir", "./plugins/code-reviewer",
        "--plugin-dir", "./plugins/lint-fix",
    });

var client = new CopilotClient(options);
client.start().get();

use github_copilot_sdk::{Client, ClientOptions};

let client = Client::start(
    ClientOptions::new().with_extra_args([
        "--plugin-dir", "./plugins/code-reviewer",
        "--plugin-dir", "./plugins/lint-fix",
    ]),
)
.await?;

En el ejemplo anterior se usa una conexión de ejecución stdio, la opción predeterminada cuando el SDK incluye la CLI. Si te conectas a un Integration Runtime externo a través de una URL (forUri / ForUri), pasa --plugin-dir al servidor CLI de ejecución prolongada al iniciarlo; el SDK no reenvía --plugin-dir a entornos de ejecución que no haya iniciado él mismo.

Directorios de complementos de confianza incluidos en el paquete del host

Las aplicaciones que envían sus propios complementos de confianza pueden registrarlas como una opción de inicio de cliente. El SDK envía el conjunto completo ordenado tras conectarse y verificar el protocolo, antes de que start devuelva un resultado o se pueda crear cualquier sesión. Las rutas deben ser absolutas; dejar la opción sin definir o vacía no realiza ninguna llamada RPC.

La opción equivalente en cada SDK es:

Se trata de un límite de confianza para los complementos agrupados y controlados por la aplicación host. Es distinto de --plugin-dir, que es un argumento de inicio de proceso de la CLI para cargar explícitamente directorios de complementos ordinarios. La opción de inicio también funciona al conectarse a un entorno de ejecución existente porque se envía a través de JSON-RPC en lugar de reenviarse como argumento de proceso.

Qué puede contribuir un complemento

La carga de un directorio de complementos hace que sus extensiones estén visibles para cada sesión creada por el cliente. El tiempo de ejecución combina las extensiones proporcionadas por el plugin con todo lo que registres directamente en línea:

Los agentes de complemento son subagentes de primera clase en Modo flota: un agente padre puede invocarlos mediante agent_type, y el entorno de ejecución activa los ganchos subagentStart / subagentStop para estos, igual que con cualquier otro subagente.

Directorio de complementos frente a complementos del marketplace

El entorno de ejecución tiene dos formas de instalar complementos, y ambas terminan viéndose igual para una sesión:

• Los complementos de Marketplace o de repositorio directo se instalan de forma persistente a través del comando con barra de la CLI /plugin o del ajuste de usuario subyacente installedPlugins. Son «ambient» — toda sesión que se ejecuta con la misma configuración de usuario las ve, e intervienen en las reglas de detección de complementos.
• --plugin-dir complementos son explícitos y efímeros — solo se aplican al proceso de la CLI que hayas iniciado con esa opción. Tienen prioridad sobre el descubrimiento ambiental y se deduplican con respecto a las entradas del marketplace que tengan la misma ruta de caché, de modo que el mismo complemento no se cargará dos veces cuando ambas superficies lo referencien.

En el caso de las aplicaciones controladas por SDK, --plugin-dir suele ser la opción adecuada: mantiene el conjunto de complementos bajo el control de la aplicación en lugar de depender del estado de usuario por máquina.

Creación de conjuntos de complementos deterministas

Cuando la máquina anfitriona pueda tener instalados otros complementos (del marketplace o personalizados), establezca COPILOT_PLUGIN_DIR_ONLY=true en el entorno de ejecución para suprimir la detección automática de complementos. Solo se cargarán los directorios que pases a través de --plugin-dir.

process.env.COPILOT_PLUGIN_DIR_ONLY = "true";

const client = new CopilotClient({
  connection: RuntimeConnection.forStdio({
    args: ["--plugin-dir", "./plugins/code-reviewer"],
  }),
});
await client.start();

Úselo en CI, en implementaciones de servidor sin encabezado y en cualquier lugar en el que desee un conjunto de complementos reproducible que no dependa de la configuración de usuario del host.

Inspección de los complementos cargados

Una vez creada una sesión, enumere los complementos activos para confirmar que un directorio se ha seleccionado correctamente:

const plugins = await session.rpc.plugins.list();
for (const plugin of plugins.plugins) {
  console.log(`${plugin.name} (${plugin.enabled ? "enabled" : "disabled"})`);
}

Los complementos cargados a través de --plugin-dir aparecen en esta lista con la ruta de caché establecida en el directorio que proporcionó. Las instalaciones del Marketplace se etiquetan con su registro de origen.

Solución de problemas

• "No se ha encontrado ni plugin.json ni SKILL.md en <dir>" — el directorio existe, pero no puede considerarse un complemento. Añade un manifiesto plugin.json en la raíz (o bajo .github/), o incluye un SKILL.md de nivel superior.
• Complemento cargado pero agentes o aptitudes no visibles : asegúrese de que el manifiesto del complemento declara los agentes o aptitudes que contribuye, o use el diseño implícito (agents/*.md, skills/*/SKILL.md). A continuación, llame session.rpc.skills.reload() a para recoger los cambios sin reiniciar.

•           **Activación de hooks duplicados**: el tiempo de ejecución elimina las duplicadas mediante `cache_path`, pero solo cuando se hace referencia al mismo directorio tanto como instalación del marketplace como `--plugin-dir`. Si dos directorios diferentes contienen el mismo complemento, ambos se cargarán. Quite uno o utilice `COPILOT_PLUGIN_DIR_ONLY=true`.
  

• --plugin-dir omitido al conectarse a un entorno de ejecución externo : el SDK solo reenvía argumentos adicionales cuando genera la PROPIA CLI. Para los entornos de ejecución externos (forUri/ForUri), pase --plugin-dir en la línea de comandos que inicia el servidor del entorno de ejecución.

Related

• Agentes personalizados y orquestación de subagentes: escribe agentes que se incluyen dentro de la carpeta agents/ de un plugin.
• Aptitudes personalizadas: cómo SKILL.md se cargan los archivos y las reglas de ordenación por niveles de aptitud.
• Trabajar con enlaces: los hooks definidos por un plugin se activan junto con los hooks registrados por el SDK.
• Uso de servidores MCP con el SDK de GitHub Copilot: los servidores MCP proporcionados por complementos se integran de la misma forma que los registros en línea.
• Modo flota: los agentes proporcionados por complementos se pueden distribuir como subagentes.