SDK- und CLI-Kompatibilität

Übersicht

Das Copilot SDK kommuniziert über JSON-RPC Protokoll mit der CLI. 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
Zerstören der Sitzung (veraltet)	`destroy()`	Verwenden Sie stattdessen `disconnect()`.
Sitzung löschen	`deleteSession()`	Aus Speicher entfernen
Sitzungen auflisten	`listSessions()`	Alle gespeicherten Sitzungen
Letzte Sitzung abrufen	`getLastSessionId()`	Für einen schnellen Überblick
Vordergrundsitzung abrufen	`getForegroundSessionId()`	Koordination mehrerer Sitzungen
Aktuelle Sitzung in den Vordergrund setzen	`setForegroundSessionId()`	Koordination mehrerer Sitzungen
Messaging
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	`getEvents()`	Alle Sitzungsereignisse
Abbruch	`abort()`	In-Flight-Anforderung stornieren
Werkzeuge
Registrieren von benutzerdefinierten Tools	`registerTools()`	Vollständige JSON-Schemaunterstützung
Berechtigungssteuerung für Tools	`onPreToolUse` hook	Zulassen/Verweigern/Fragen
Änderung des Werkzeugergebnisses	`onPostToolUse` hook	Transformieren von Ergebnissen
Verfügbare/ausgeschlossene Tools	`availableTools`, `excludedTools` Konfiguration	Filterwerkzeuge
Modelle
Modelle auflisten	`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-Einsatz (Erfolg)	`onPostToolUse`	Ergebnisse ändern
Nutzung nach dem Tool-Einsatz (Fehler)	`onPostToolUseFailure`	Beobachte fehlgeschlagene Toolaufrufe und füge Hinweise für einen erneuten Versuch ein
Benutzeraufforderung	`onUserPromptSubmitted`	Ändern von Eingabeaufforderungen
Sitzungsstart/-ende
`onSessionStart`, `onSessionEnd`	Lebenszyklus mit Quelle/Grund
Fehlerbehandlung	`onErrorOccurred`	Benutzerdefinierte Behandlung
Ereignisse
Alle Sitzungsereignisse
`on()`, `once()`	40+ Ereignistypen
Streaming	`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 Fähigkeiten
Deaktivierte Fähigkeiten
`disabledSkills` Konfiguration	Deaktivieren bestimmter Fähigkeiten
Konfigurationsverzeichnis
`configDir` Konfiguration	Standardkonfigurationsspeicherort außer Kraft setzen
Clientname
`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 des Sub-Agents; siehe Flottenmodus
Manuelle Komprimierung	`session.rpc.history.compact()`	Auslösen der Komprimierung bei Bedarf
Verlaufskürzung	`session.rpc.history.truncate()`	Ereignisse ab einem bestimmten Punkt entfernen
Sitzungsaufspaltung	`server.rpc.sessions.fork()`	Eine Sitzung zu einem bestimmten Zeitpunkt in der Historie abspalten

❌ Im SDK nicht verfügbar (nur CLI)

Funktion	CLI-Befehl/-Option	Grund
Sitzungsexport
Exportieren als Datei
`--share`, `/share`	Nicht im Protokoll
In „gist“ exportieren
`--share-gist`, `/share gist`	Nicht im Protokoll
Interaktive Benutzeroberfläche
Slash-Befehle
`/help`, `/clear`, `/exit`, usw.	NUR TUI
Dialogfeld "Agentauswahl"	`/agent`	Interaktive Benutzeroberfläche
Diff-Modus-Dialog	`/diff`	Interaktive Benutzeroberfläche
Feedback-Dialog	`/feedback`	Interaktive Benutzeroberfläche
Theme-Auswahl	`/theme`	Terminal-Benutzeroberfläche
Modellauswahl	`/model`	Interaktive Benutzeroberfläche (verwenden Sie stattdessen SDK `setModel()` )
In Zwischenablage kopieren	`/copy`	Terminalspezifisch
Context-Management	`/context`	Interaktive Benutzeroberfläche
Forschung & Geschichte
Tiefe Forschung	`/research`	TUI-Workflow mit Websuche
Sitzungsverlaufstools	`/chronicle`	Standup, Tipps, verbessern, neuindizieren
Terminalfunktionen
Farbausgabe	`--no-color`	Terminalspezifisch
Bildschirmlesemodus	`--screen-reader`	Accessibility
Detailliertes Diff-Rendering	`--plain-diff`	Terminal-Rendering
Startbanner	`--banner`	Visuelles Element
Streamer-Modus	`/streamer-mode`	TUI-Anzeigemodus
Alternativer Bildschirmpuffer
`--alt-screen`, `--no-alt-screen`	Terminal-Rendering
Mausunterstützung
`--mouse`, `--no-mouse`	Terminaleingabe
Pfad-/Berechtigungsverknüpfungen
Alle Pfade zulassen	`--allow-all-paths`	Berechtigungshandler verwenden
Alle URLs zulassen	`--allow-all-urls`	Berechtigungshandler verwenden
Alle Berechtigungen zulassen
`--yolo`, --allow-all``/allow-all	Berechtigungshandler verwenden
Granulare Toolberechtigungen
`--allow-tool`, `--deny-tool`	Verwenden Sie den `onPreToolUse`-Hook
URL-Zugriffssteuerung
`--allow-url`, `--deny-url`	Berechtigungshandler verwenden
Zulässige Tools zurücksetzen	`/reset-allowed-tools`	TUI-Befehl
Verzeichnisverwaltung
Verzeichnis hinzufügen
`/add-dir`, `--add-dir`	In der Sitzung konfigurieren
Verzeichnisse auflisten	`/list-dirs`	TUI-Befehl
Verzeichnis ändern	`/cwd`	TUI-Befehl
Plug-In-/MCP-Verwaltung
Plug-In-Befehle	`/plugin`	Interaktive Verwaltung
MCP-Serververwaltung	`/mcp`	Interaktive Benutzeroberfläche
Kontoverwaltung
Anmeldefluss
`/login`, `copilot auth login`	OAuth-Gerätefluss
Abmelden
`/logout`, `copilot auth logout`	Direkter CLI
Benutzerinformationen	`/user`	TUI-Befehl
Sitzungsvorgänge
Konversation leeren	`/clear`	NUR TUI
Planansicht	`/plan`	TUI-only (stattdessen SDK `session.rpc.plan.*` verwenden)
Sitzungsverwaltung
`/session`, /resume``/rename	TUI Workflow
Flottenmodus (interaktiv)	`/fleet`	TUI-only (stattdessen SDK `session.rpc.fleet.start()` verwenden)
Kompetenzmanagement
Qualifikationen verwalten	`/skills`	Interaktive Benutzeroberfläche
Aufgabenverwaltung
Anzeigen von Hintergrundaufgaben	`/tasks`	TUI-Befehl
Nutzungs- und Statistiken
Tokenverwendung	`/usage`	Abonnieren von Verwendungsereignissen
Codeprüfung
Änderungen überprüfen	`/review`	TUI-Befehl
Delegierung
An PR delegieren	`/delegate`	TUI Workflow
Terminaleinrichtung
Shell-Integration	`/terminal-setup`	Shell-spezifisch
Entwicklung
Experimentelle Funktion umschalten
`/experimental`, `--experimental`	Laufzeitkennzeichnung
Verwaltung benutzerdefinierter Anweisungen	`--no-custom-instructions`	CLI-Kennzeichnung
Diagnosesitzung	`/diagnose`	TUI-Befehl
Anzeigen/Verwalten von Anweisungen	`/instructions`	TUI-Befehl
Sammeln von Debugprotokollen	`/collect-debug-logs`	Diagnosetool
Arbeitsbereich neu indizieren	`/reindex`	TUI-Befehl
IDE-Integration	`/ide`	IDE-spezifischer Workflow
Nicht interaktiver Modus
Prompt-Modus
`-p`, `--prompt`	Einmalige Ausführung
Interaktive Eingabeaufforderung
`-i`, `--interactive`	Automatisch ausführen, dann interaktiv
Stille Ausgabe
`-s`, `--silent`	Skriptfreundlich
Sitzung fortsetzen	`--continue`	Zuletzt aktualisiert
Agentauswahl	`--agent <agent>`	CLI-Kennzeichnung

Behelfslösungen

Flottenmodus

Der Flottenmodus ist über session.rpc.fleet.start() für SDK-Anwendungen verfügbar, die die Laufzeit veranlassen möchten, zur Erreichung eines übergeordneten Ziels parallele Subagents einzusetzen. Verwenden Sie sie, wenn unabhängige Teilvorgänge gleichzeitig ausgeführt und dann von der Hauptsitzung zusammengefasst werden können. Eine vollständige Anleitung finden Sie unter Flottenmodus.

Sitzungsexport

Die --share Option ist über das SDK nicht verfügbar. Problemumgehungen:

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

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

Verwenden Sie die CLI direkt zum Exportieren – Führen Sie die CLI mit --share für einmalige Exporte aus.

Berechtigungsverwaltung

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

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

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

Tokenverwendungsnachverfolgung

Statt /usage abonnieren Sie Nutzungsereignisse:

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:

// 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.history.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:

// 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.

// 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:

Auf Alternativen überprüfen – Viele Features verfügen über SDK-Entsprechungen (siehe oben beschriebene Problemumgehungen)
Verwenden Sie die CLI direkt – Rufen Sie für einmalige Vorgänge die CLI auf.
Anfordern des Features – Öffnen eines Problems zum Anfordern der Protokollunterstützung

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.

Versionen zur Laufzeit prüfen:

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

In diesem Artikel