Ü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 von Subagenten |
| 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 |
| 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 | Einzellaufausführung | |
| Interaktive Eingabeaufforderung | ||
-i, --interactive | Automatisch ausführen, dann interaktiv | |
| Stille Ausgabe | ||
-s, --silent | Skriptfreundlich | |
| Sitzung fortsetzen | --continue | Letzte Fortsetzung |
| Agentauswahl | --agent <agent> | CLI-Kennzeichnung |
Behelfslösungen
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
--sharefü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);