# SDK- und CLI-Kompatibilität Dieses Dokument beschreibt, welche Copilot-CLI-Funktionen über das SDK verfügbar sind und welche ausschließlich in der CLI verfügbar sind. ## Ü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()` | Schnelles Wiederaufnehmen | | 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 | | 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** | | | | | | | | 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 | | Verwendung nach dem Einsatz des Tools (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 | | | 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 des Sub-Agents; siehe [Flottenmodus](/de/copilot/how-tos/copilot-sdk/features/fleet-mode) | | 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-UI | | Modellauswahlwerkzeug | `/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` | Direct 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 | | Anzeigen/Verwalten von Anweisungen | `/instructions` | TUI-Befehl | | Arbeitsbereich neu indizieren | `/reindex` | TUI-Befehl | | IDE-Integration | `/ide` | IDE-spezifischer Workflow | | **Nicht interaktiver Modus** | | | | | | | | Prompt-Modus | | | | `-p`, `--prompt` | Einzellaufausführung | | | Interaktive Eingabeaufforderung | | | | `-i`, `--interactive` | Automatisch ausführen, dann interaktiv | | | Stille Ausgabe | | | | `-s`, `--silent` | Skriptfreundlich | | | Sitzung fortsetzen | `--continue` | Letzte Fortsetzung | | Agentauswahl | `--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 Sub-Agenten 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](/de/copilot/how-tos/copilot-sdk/features/fleet-mode). ### Sitzungsexport Die `--share` Option ist über das SDK nicht verfügbar. Problemumgehungen 1. **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.getEvents(); // Format as markdown yourself ``` 2. **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: ```typescript 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, }); }); ``` ### 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.history.compact(); console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); ``` > \[!NOTE] > 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(); ``` ### 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" }); ``` ## 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: 1. **Auf Alternativen überprüfen** – Viele Features verfügen über SDK-Entsprechungen (siehe oben beschriebene Problemumgehungen) 2. **Verwenden Sie die CLI direkt** – Rufen Sie für einmalige Vorgänge die CLI auf. 3. **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: ```typescript const status = await client.getStatus(); console.log("Protocol version:", status.protocolVersion); ``` ## Siehe auch * [Erstellen Sie Ihre erste Copilot-gestützte App](/de/copilot/how-tos/copilot-sdk/getting-started) * [Sitzungshaken](/de/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [Using MCP servers with the GitHub Copilot SDK](/de/copilot/how-tos/copilot-sdk/features/mcp) * [Debughandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/debugging)