Verwenden einer gebündelten CLI mit Copilot SDK

Packen Sie Copilot CLI zusammen mit Ihrer Anwendung, damit Benutzer nichts separat installieren oder konfigurieren müssen.

Wer kann dieses Feature verwenden?

GitHub Copilot SDK ist mit allen Copilot Tarifen verfügbar.

In diesem Artikel

Hinweis

          Copilot SDK ist zurzeit in Technische Preview. Funktionalität und Verfügbarkeit können geändert werden.

Versenden Sie Copilot CLI als Teil Ihrer Anwendung, damit Ihre Benutzer ohne zusätzliche Einrichtung beginnen können.

          **Am besten geeignet für:** Desktop-Apps, eigenständige Tools, Elektronen-Apps und verteilbare CLI-Dienstprogramme.

So funktioniert es

Anstatt sich auf eine global installierte CLI zu verlassen, fügen Sie die CLI-Binärdatei in Ihr Anwendungsbundle ein. Das SDK verweist über die cliPath Option auf Ihre gebündelte Kopie. Die wichtigsten Merkmale sind:

  • Die CLI-Binärdatei wird mit Ihrer App ausgeliefert– es ist keine separate Installation erforderlich.
  • Sie steuern die genaue CLI-Version, die Ihre App verwendet.
  • Benutzer authentifizieren sich über Ihre App, Umgebungsvariablen oder BYOK.
  • Sitzungen werden pro Benutzer auf ihrem Computer verwaltet.

Konfiguration

Schritt 1: Einschließen der CLI in Ihr Projekt

Die CLI wird als Teil des @github/copilot npm-Pakets verteilt.

npm install @github/copilot

Schritt 2: Richten Sie das SDK auf Ihre gebundene CLI

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()

Los geht's

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);

Authentifizierungsstrategien

Beim Bündeln der CLI müssen Sie entscheiden, wie sich Ihre Benutzer authentifizieren werden. Das folgende Diagramm veranschaulicht allgemeine Muster.

Diagramm mit Authentifizierungsstrategieoptionen für eine gebündelte CLI-Bereitstellung.

Option A: Anmeldeinformationen des Benutzers (am einfachsten)

Der Benutzer meldet sich einmal bei der CLI an, und Ihre gebündelte App verwendet diese Anmeldeinformationen. Kein zusätzlicher Code erforderlich – dies ist das Standardverhalten.

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

Option B: Token über Umgebungsvariable

Legen Sie ein Token programmgesteuert fest oder weisen Sie Benutzer an, ein Token festzulegen, bevor Sie Ihre App starten:

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

Ersetzen Sie getUserToken() durch die Logik in Ihrer App, die das OAuth-Token des Benutzers GitHub abruft.

Option C: BYOK (keine GitHub Authentifizierung erforderlich)

Wenn Sie Ihre eigenen Modellanbieterschlüssel verwalten, benötigen GitHub Benutzer keine Konten:

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,
    },
});

Sitzungsverwaltung

Gebündelte Apps möchten in der Regel benannte Sitzungen, damit Benutzer Unterhaltungen fortsetzen können:

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);

Der Sitzungszustand wird bei ~/.copilot/session-state/SESSION-ID/ gespeichert, wobei die von Ihnen angegebene Sitzungs-ID SESSION-ID ist.

Verteilungsmuster

Desktop-App (Electron, Tauri)

Fügen Sie die CLI-Binärdatei in das Ressourcenverzeichnis Ihrer App ein:

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

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

const client = new CopilotClient({ cliPath });

CLI-Tool

Lösen Sie für verteilungsfähige CLI-Tools den Pfad relativ zu Ihrer Binärdatei auf:

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 });

Plattformspezifische Binärdateien

Geben Sie bei der Verteilung für mehrere Plattformen die richtige Binärdatei für jedes Ziel ein:

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(),
});

Einschränkungen

EinschränkungEinzelheiten
          **Paketgröße** | Die CLI-Binärdatei erhöht die Distributionsgröße Ihrer App. |

| Updates | Sie verwalten CLI-Versionsupdates im Veröffentlichungszyklus. | | Plattformkompilierungen | Für jedes Betriebssystem/jede Architektur sind separate Binärdateien erforderlich. | | Einzelner Benutzer | Jede gebündelte CLI-Instanz dient einem Benutzer. |

Nächste Schritte