Uso de una CLI agrupada con el SDK de Copilot

Empaquetar CLI de Copilot junto con la aplicación para que los usuarios no necesiten instalar ni configurar nada por separado.

¿Quién puede utilizar esta característica?

SDK de GitHub Copilot está disponible con todos los Copilot planes.

En este artículo

Nota:

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Envíe CLI de Copilot como parte de la aplicación para que los usuarios puedan empezar a trabajar sin ninguna configuración adicional.

          **Lo mejor para:** Aplicaciones de escritorio, herramientas independientes, aplicaciones Electron y utilidades CLI distribuibles.

Cómo funciona

En lugar de confiar en una CLI instalada globalmente, se incluye el binario de la CLI en la agrupación de aplicaciones. El SDK señala a su copia en paquete mediante la opción cliPath. Las características clave son:

  • El binario de la CLI se distribuye con la aplicación; no se necesita ninguna instalación independiente.
  • Controla la versión exacta de la CLI que usa la aplicación.
  • Los usuarios se autentican a través de la aplicación, las variables de entorno o BYOK.
  • Las sesiones se administran por usuario en su máquina.

Configuración

Paso 1: Incluir la CLI en el proyecto

La CLI se distribuye como parte del @github/copilot paquete npm.

npm install @github/copilot

Paso 2: Conectar el SDK a tu CLI agrupada

Node.js/TypeScript

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

const client = new CopilotClient({
    // Point to the CLI binary in your app bundle
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

const session = await client.createSession({ model: "gpt-4.1" });
const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

Python

from copilot import CopilotClient, PermissionHandler
from pathlib import Path

client = CopilotClient({
    "cli_path": str(Path(__file__).parent / "vendor" / "copilot"),
})
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)

await client.stop()

Go

client := copilot.NewClient(&copilot.ClientOptions{
    CLIPath: "./vendor/copilot",
})
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
fmt.Println(*response.Data.Content)

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = Path.Combine(AppContext.BaseDirectory, "vendor", "copilot"),
});

await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-4.1" });

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });
Console.WriteLine(response?.Data.Content);

Estrategias de autenticación

Al agrupar la CLI, debe decidir cómo se autenticarán los usuarios. En el diagrama siguiente se muestran patrones comunes.

Diagrama que muestra las opciones de estrategia de autenticación para una implementación de la CLI agrupada.

Opción A: Credenciales de inicio de sesión del usuario (más sencilla)

El usuario inicia sesión en la CLI una vez y la aplicación agrupada usa esas credenciales. No se necesita código adicional: este es el comportamiento predeterminado.

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
    // Default: uses signed-in user credentials
});

Opción B: Token a través de la variable de entorno

Establezca un token mediante programación o indique a los usuarios que establezcan uno antes de iniciar la aplicación:

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),
    },
});

Reemplace getUserToken() con la lógica en su aplicación que recupera el token OAuth del usuario GitHub.

Opción C: BYOK (sin GitHub necesidad de autenticación)

Si administra sus propias claves de proveedor de modelos, los usuarios no necesitan tener cuentas GitHub.

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});

Administración de sesiones

Las aplicaciones agrupadas suelen querer sesiones con nombre para que los usuarios puedan reanudar conversaciones:

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

// Create a session tied to the user's project
const sessionId = `project-${projectName}`;
const session = await client.createSession({
    sessionId,
    model: "gpt-4.1",
});

// Resume the session in a later run
const resumed = await client.resumeSession(sessionId);

El estado de sesión se almacena en ~/.copilot/session-state/SESSION-ID/, donde SESSION-ID es el identificador de sesión que proporcionó.

Patrones de distribución

Aplicación de escritorio (Electron, Tauri)

Incluya el binario de la CLI en el directorio de recursos de la aplicación:

import { app } from "electron";
import path from "path";

const cliPath = path.join(
    app.isPackaged ? process.resourcesPath : __dirname,
    "copilot"
);

const client = new CopilotClient({ cliPath });

Herramienta de la CLI

Para herramientas CLI distribuibles, resuelva la ruta de acceso relativa a tu archivo binario:

import { fileURLToPath } from "url";
import path from "path";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const cliPath = path.join(__dirname, "..", "vendor", "copilot");

const client = new CopilotClient({ cliPath });

Archivos binarios específicos de la plataforma

Al distribuir para varias plataformas, incluya el binario correcto para cada destino:

my-app/
├── vendor/
│   ├── copilot-darwin-arm64    # macOS Apple Silicon
│   ├── copilot-darwin-x64      # macOS Intel
│   ├── copilot-linux-x64       # Linux x64
│   └── copilot-win-x64.exe     # Windows x64
└── src/
    └── index.ts

import os from "os";

function getCLIPath(): string {
    const platform = process.platform;   // "darwin", "linux", "win32"
    const arch = os.arch();              // "arm64", "x64"
    const ext = platform === "win32" ? ".exe" : "";
    const name = `copilot-${platform}-${arch}${ext}`;
    return path.join(__dirname, "vendor", name);
}

const client = new CopilotClient({
    cliPath: getCLIPath(),
});

Limitaciones

LimitaciónDetalles
          **Tamaño del paquete** | El binario de la CLI aumenta el tamaño de distribución de la aplicación. |

| Actualizaciones | Usted gestiona las actualizaciones de la versión de CLI en su ciclo de lanzamiento. | | Construcciones de plataforma | Se necesitan archivos binarios independientes para cada sistema operativo o arquitectura. | | Usuario único | Cada instancia de la CLI agrupada sirve a un usuario. |

Pasos siguientes