SDK- und CLI-Kompatibilität

Hinweis

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

          GitHub Copilot SDK kommuniziert mit GitHub Copilot-CLI über das JSON-RPC-Protokoll. Features müssen explizit über dieses Protokoll verfügbar gemacht werden, damit sie im SDK verfügbar sind. Viele interaktive CLI-Features sind terminalspezifisch und nicht programmgesteuert verfügbar.

Funktionsvergleich

Verfügbar im SDK

Funktion	SDK-Methode	Hinweise

          **Sitzungsverwaltung** |

| | | Sitzung erstellen | createSession() | Vollständige Konfigurationsunterstützung | | Sitzung fortsetzen | resumeSession() | Mit unendlichen Sitzungsarbeitsbereichen | | Sitzung trennen | disconnect() | Freigeben von In-Memory-Ressourcen | | Sitzung zerstören | destroy() | Verwenden Sie stattdessen disconnect(). | | Sitzung löschen | deleteSession() | Aus Speicher entfernen | | Sitzungen auflisten | listSessions() | Alle gespeicherten Sitzungen | | Letzte Sitzung abrufen | getLastSessionId() | Schnelles Wiederaufnehmen | | Vordergrundsitzung abrufen | getForegroundSessionId() | Koordination mehrerer Sitzungen | | Aktuelle Sitzung in den Vordergrund setzen | setForegroundSessionId() | Koordination mehrerer Sitzungen | | Nachrichtenübermittlung | | | | Nachricht senden | send() | Mit Anlagen | | Senden und Warten | sendAndWait() | Blockiert bis zum Abschluss | | Lenkung (Sofortiger Modus) | send({ mode: "immediate" }) | Während des Vorgangs ohne Abbruch injizieren. | | Warteschlangen (Enqueue-Modus) | send({ mode: "enqueue" }) | Puffer für sequenzielle Verarbeitung (Standard) | | Dateianlagen | send({ attachments: [{ type: "file", path }] }) | Bilder automatisch codiert und verkleinert | | Verzeichnis-Anhänge | send({ attachments: [{ type: "directory", path }] }) | Anfügen des Verzeichniskontexts | | Verlauf abrufen | getMessages() | Alle Sitzungsereignisse | | Abbrechen | abort() | In-Flight-Anforderung stornieren | | Werkzeuge | | | | Registrieren von benutzerdefinierten Tools | registerTools() | Vollständige JSON-Schemaunterstützung | | Berechtigungssteuerung für Tools | onPreToolUse Haken | Zulassen/Verweigern/Fragen | | Änderung des Werkzeugergebnisses | onPostToolUse Haken | Transformieren von Ergebnissen | | Verfügbare/ausgeschlossene Tools | availableTools, excludedTools Konfig | Filterwerkzeuge | | Modelle | | | | Auflisten von Modellen | listModels() | Mit Funktionen, Abrechnung, Richtlinien | | Festlegen des Modells (beim Erstellen) | model in Sitzungskonfiguration | Pro Sitzung | | Switch-Modell (Zwischensitzung) | session.setModel() | Auch über session.rpc.model.switchTo() | | Aktuelles Modell abrufen | session.rpc.model.getCurrent() | Aktives Modell abfragen | | Begründungsaufwand | reasoningEffort Konfiguration | Für unterstützte Modelle | | Agentmodus | | | | Aktuellen Modus abrufen | session.rpc.mode.get() | Gibt den aktuellen Modus zurück. | | Modus festlegen | session.rpc.mode.set() | Wechseln zwischen Modi | | Planverwaltung | | | | Plan lesen | session.rpc.plan.read() | Abrufen des plan.md-Inhalts und des Pfads | | Plan aktualisieren | session.rpc.plan.update() | Schreiben Sie den Inhalt von plan.md | | Plan löschen | session.rpc.plan.delete() | Plan.md entfernen | | Arbeitsbereichsdateien | | | | Arbeitsbereichsdateien auflisten | session.rpc.workspace.listFiles() | Dateien im Sitzungsarbeitsbereich | | Arbeitsbereichsdatei lesen | session.rpc.workspace.readFile() | Dateiinhalt lesen | | Arbeitsbereichsdatei erstellen | session.rpc.workspace.createFile() | Datei im Arbeitsbereich erstellen | | Authentifizierung | | | | Abrufen des Authentifizierungsstatus | getAuthStatus() | Überprüfen des Anmeldestatus | | Token verwenden | Option githubToken | Programmgesteuerte Authentifizierung | | Konnektivität | | | | Pingen | client.ping() | Gesundheitsprüfung mit Serverzeitstempel | | Serverstatus abrufen | client.getStatus() | Protokollversions- und Serverinformationen | | MCP-Server | | | | Lokale/Stdio-Server | mcpServers Konfiguration | Spawn-Prozesse | | Remote-HTTP/SSE | mcpServers Konfiguration | Verbinden mit Diensten | | Hooks | | | | Vor der Werkzeugverwendung | onPreToolUse | Berechtigungen, Argumente ändern | | Nutzung nach dem Tool | onPostToolUse | Ergebnisse ändern | | Benutzeraufforderung | onUserPromptSubmitted | Ändern von Eingabeaufforderungen | | Sitzungsstart/-ende | onSessionStart, onSessionEnd | Lebenszyklus mit Quelle/Grund | | Fehlerbehandlung | onErrorOccurred | Benutzerdefinierte Behandlung | | Ereignisse | | | | Alle Sitzungsereignisse | on(), once() | 40+ Ereignistypen | | Streamen | streaming: true | Delta-Ereignisse | | Sitzungskonfiguration | | | | Benutzerdefinierte Agents | customAgents Konfiguration | Definieren von spezialisierten Agents | | Systemmeldung | systemMessage Konfiguration | Anfügen oder Ersetzen | | Benutzerdefinierter Anbieter | provider Konfiguration | BYOK-Unterstützung | | Unendliche Sitzungen | infiniteSessions Konfiguration | Automatische Komprimierung | | Berechtigungshandler | onPermissionRequest | Genehmigen/Ablehnen von Anforderungen | | Benutzereingabehandler | onUserInputRequest | Verarbeitung von ask_user | | Fähigkeiten | skillDirectories Konfiguration | Benutzerdefinierte Qualifikationen | | Deaktivierte Fähigkeiten | disabledSkills Konfiguration | Deaktivieren bestimmter Fähigkeiten | | Konfigurationsverzeichnis | configDir Konfiguration | Standardkonfigurationsspeicherort außer Kraft setzen | | Client-Name | clientName Konfiguration | App im User-Agent identifizieren | | Arbeitsverzeichnis | workingDirectory Konfiguration | Sitzungscwd festlegen | | Experimentell | | | | Agentverwaltung | session.rpc.agent.* | Auflisten, Auswählen, Abwählen, Abrufen des aktuellen Agents | | Flottenmodus | session.rpc.fleet.start() | Parallele Ausführung von Subagenten | | Manuelle Komprimierung | session.rpc.compaction.compact() | Auslösen der Komprimierung bei Bedarf |

Im SDK nicht verfügbar (nur CLI)

Funktion	CLI-Befehl/-Option	Grund

          **Sitzungsexport** |

Problemumgehungen

Sitzungsexport

Die --share Option ist über das SDK nicht verfügbar. Dieses Problem können Sie folgendermaßen umgehen:

        **Manuelles Sammeln von Ereignissen:** Abonnieren Sie Sitzungsereignisse, und erstellen Sie Ihren eigenen Export:

TypeScript

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

        **Verwenden Sie die CLI direkt** für einmalige Exporte.

Berechtigungsverwaltung

Das SDK verwendet ein Berechtigungsmodell, das standardmäßig verweigert. Alle Berechtigungsanforderungen (Dateischreibvorgänge, Shellbefehle, URL-Abrufe und andere) werden verweigert, es sei denn, Ihre App stellt einen onPermissionRequest Handler bereit.

Verwenden Sie anstelle von --allow-all-paths oder --yolo den Berechtigungshandler:

TypeScript

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

Tokenverwendungsnachverfolgung

Statt /usage abonnieren Sie Nutzungsereignisse:

TypeScript

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

Kontextkomprimierung

Anstelle von /compact automatische Komprimierung zu konfigurieren oder manuell auszulösen:

TypeScript

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

Hinweis

Schwellenwerte sind Kontextauslastungsverhältnisse (0,0-1,0), keine absolute Tokenanzahl.

Planverwaltung

Programmgesteuertes Lesen und Schreiben von Sitzungsplänen:

TypeScript

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

Nachrichtensteuerung

Fügen Sie eine Nachricht in die aktuelle LLM-Runde ein, ohne abzubrechen.

TypeScript

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

Protokollbeschränkungen

Das SDK kann nur auf Features zugreifen, die über das JSON-RPC-Protokoll der CLI verfügbar gemacht werden. Wenn Sie ein CLI-Feature benötigen, das nicht verfügbar ist:

        **Suchen Sie nach Alternativen:** Viele Features verfügen über SDK-Entsprechungen (siehe [oben beschriebene Problemumgehungen](#workarounds) ).

        **Verwenden Sie die CLI direkt:** Rufen Sie bei einmaligen Vorgängen die CLI auf.

        **Fordern Sie das Feature an:** Öffnen Sie ein Problem im [Github/copilot-sdk-Repository](https://github.com/github/copilot-sdk/issues) , um die Protokollunterstützung anzufordern.

Versionskompatibilität

SDK-Protokollbereich	CLI-Protokollversion	Compatibility
v2-v3	v3	Vollständiger Support
v2-v3	v2	Unterstützt durch automatische v2-Adapter

Das SDK verhandelt Protokollversionen mit der CLI beim Start. Das SDK unterstützt Protokollversionen 2 bis 3. Beim Herstellen einer Verbindung mit einem v2 CLI-Server passt das SDK automatisch tool.call- und permission.request-Nachrichten an das v3-Ereignismodell an – es sind keine Codeänderungen erforderlich.

Sie können Versionen zur Laufzeit überprüfen:

TypeScript

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

Wer kann dieses Feature verwenden?

In diesem Artikel

Funktionsvergleich

Verfügbar im SDK

Im SDK nicht verfügbar (nur CLI)

Problemumgehungen

Sitzungsexport

Berechtigungsverwaltung

Tokenverwendungsnachverfolgung

Kontextkomprimierung

Planverwaltung

Nachrichtensteuerung

Protokollbeschränkungen

Versionskompatibilität