Debuggen des Copilot SDK

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

Debugprotokollierung aktivieren

Um mit der Problembehandlung zu beginnen, aktivieren Sie die ausführliche Protokollierung, um einen Einblick in die zugrunde liegenden Prozesse zu erhalten.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "debug",  // Options: "none", "error", "warning", "info", "debug", "all"
});

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "debug",  // Options: "none", "error", "warning", "info", "debug", "all"
});

Beispiele in Python, Go und .NET finden Sie im Debughandbuch im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

Protokollverzeichnis

Die CLI schreibt standardmäßig Protokolle in das ABC-Verzeichnis. Sie können einen anderen Speicherort mithilfe des --log-dir Arguments angeben:

const client = new CopilotClient({
  cliArgs: ["--log-dir", "/path/to/logs"],
});

const client = new CopilotClient({
  cliArgs: ["--log-dir", "/path/to/logs"],
});

Führen Sie bei Python und Go, die derzeit keine zusätzlichen CLI-Argumente akzeptieren können, die CLI manuell mit der Option --log-dir aus und verbinden Sie sich über die Option cliUrl. Weitere Informationen finden Sie im Debughandbuch im github/copilot-sdk Repository.

Häufig auftretende Probleme

"CLI nicht gefunden" oder "Copilot: Befehl nicht gefunden"

          **Ursache:**GitHub Copilot-CLI ist entweder nicht installiert oder nicht im PATH enthalten.

          **Solution:**

1. Installieren Sie die CLI. Weitere Informationen findest du unter Installieren von GitHub Copilot CLI.

2. Installation überprüfen:

   Bash

   copilot --version
   

3. Oder geben Sie den vollständigen Pfad an:

   TypeScript

   const client = new CopilotClient({
     cliPath: "/usr/local/bin/copilot",
   });
   

   Beispiele in Python, Go und .NET finden Sie im Debughandbuch im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

"Nicht authentifiziert"

          **Ursache:** Die CLI ist nicht authentifiziert mit GitHub.

          **Solution:**

1. Authentifizieren der CLI:

   Bash

   copilot auth login
   

2. Oder stellen Sie programmgesteuert ein Token bereit:

   TypeScript

   const client = new CopilotClient({
     githubToken: process.env.GITHUB_TOKEN,
   });
   

   Beispiele in Python, Go und .NET finden Sie im Debughandbuch im github/copilot-sdk Repository. Java finden Sie im github/copilot-sdk-java Repository.

"Sitzung nicht gefunden"

          **Ursache:** Es wird versucht, eine Sitzung zu verwenden, die zerstört wurde oder nicht vorhanden ist.

          **Solution:**

1. Stellen Sie sicher, dass Sie keine Methoden nach diesem disconnect()-Aufruf aufrufen:

   TypeScript

   await session.disconnect();
   // Don't use session after this!
   

2. Überprüfen Sie bei der Fortsetzung von Sitzungen, ob die Sitzungs-ID vorhanden ist:

   TypeScript

   const sessions = await client.listSessions();
   console.log("Available sessions:", sessions);
   

"Verbindung verweigert" oder "ECONNREFUSED"

          **Ursache:** Der CLI-Serverprozess ist abgestürzt oder konnte nicht gestartet werden.

          **Solution:**

1. Überprüfen Sie, ob die CLI ordnungsgemäß eigenständig ausgeführt wird:

   Bash

   copilot --server --stdio
   

2. Überprüfen Sie bei Verwendung des TCP-Modus nach Portkonflikten:

   TypeScript

   const client = new CopilotClient({
     useStdio: false,
     port: 0,  // Use random available port
   });
   

MCP-Server-Debugging

MCP-Server (Model Context Protocol) können schwierig zu debuggen sein. Umfassende MCP-Debugginganleitungen finden Sie unter Debuggen von MCP-Servern im Copilot SDK.

Kurze MCP-Checkliste

• Die ausführbare Datei des MCP-Servers ist vorhanden und läuft unabhängig.
• Befehlspfad ist richtig (absolute Pfade verwenden)
• Tools sind aktiviert: tools: ["*"]
• Server antwortet ordnungsgemäß auf initialize Anforderung
• Das Arbeitsverzeichnis (cwd) wird bei Bedarf automatisch festgelegt.

Testen des MCP-Servers

Überprüfen Sie vor der Integration mit dem SDK, ob Ihr MCP-Server funktioniert:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

Ausführliche Informationen zur Problembehandlung finden Sie unter Debuggen von MCP-Servern im Copilot SDK.

Verbindungsprobleme

Stdio vs TCP-Modus

Das SDK unterstützt zwei Transportmodi:

          **Stdio** (Standard) | CLI läuft als Unterprozess, kommuniziert über Rohre | Lokale Entwicklung, einzelner Prozess |

| TCP | CLI wird separat ausgeführt, kommuniziert über TCP-Socket | Mehrere Clients, Remote CLI |

          **Stdiomodus (Standard):**

const client = new CopilotClient({
  useStdio: true,  // This is the default
});

const client = new CopilotClient({
  useStdio: true,  // This is the default
});

          **TCP-Modus:**

const client = new CopilotClient({
  useStdio: false,
  port: 8080,  // Or 0 for random port
});

const client = new CopilotClient({
  useStdio: false,
  port: 8080,  // Or 0 for random port
});

          **Herstellen einer Verbindung mit vorhandenem Server:**

const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

Diagnose von Verbindungsfehlern

1. Clientstatus überprüfen:

   TypeScript

   console.log("Connection state:", client.getState());
   // Should be "connected" after start()
   

2. Zuhören auf Zustandsänderungen

   TypeScript

   client.on("stateChange", (state) => {
     console.log("State changed to:", state);
   });
   

3. Überprüfen Sie, ob der CLI-Prozess ausgeführt wird:

   Bash

   # Check for copilot processes
   ps aux | grep copilot
   

Probleme bei der Toolausführung

Benutzerdefiniertes Tool wird nicht aufgerufen

1. Überprüfen sie die Toolregistrierung:

   TypeScript

   const session = await client.createSession({
     tools: [myTool],
   });
   
   // Check registered tools
   console.log("Registered tools:", session.getTools?.());
   

2. Überprüfen Sie, ob das Toolschema gültiges JSON-Schema ist:

   TypeScript

   const myTool = {
     name: "get_weather",
     description: "Get weather for a location",
     parameters: {
       type: "object",
       properties: {
         location: { type: "string", description: "City name" },
       },
       required: ["location"],
     },
     handler: async (args) => {
       return { temperature: 72 };
     },
   };
   

3. Stellen Sie sicher, dass der Handler ein gültiges Ergebnis zurückgibt:

   TypeScript

   handler: async (args) => {
     // Must return something JSON-serializable
     return { success: true, data: "result" };
   
     // Don't return undefined or non-serializable objects
   }
   

Nicht sichtbare Toolfehler

Fehlerereignisse abonnieren:

session.on("tool.execution_error", (event) => {
  console.error("Tool error:", event.data);
});

session.on("error", (event) => {
  console.error("Session error:", event.data);
});

session.on("tool.execution_error", (event) => {
  console.error("Tool error:", event.data);
});

session.on("error", (event) => {
  console.error("Session error:", event.data);
});

Plattformspezifische Probleme

Windows

1.        **Pfadtrennzeichen:** Verwenden Sie unformatierte Zeichenfolgen oder Schrägstriche. Für .NET-spezifische Beispiele, siehe [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) im `github/copilot-sdk` Repository.
   

2.        **Konsolencodierung:** Stellen Sie UTF-8 für die ordnungsgemäße JSON-Behandlung sicher. Für .NET-spezifische Beispiele, siehe [Debugging Guide](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) im `github/copilot-sdk` Repository.
   

macOS

1.        **Gatekeeper-Probleme:** Wenn CLI blockiert ist:
   

   Bash

   xattr -d com.apple.quarantine /path/to/copilot
   

2.        **PATH-Probleme in GUI-Apps:** GUI-Anwendungen erben vielleicht nicht den Shell-PATH:
   

   TypeScript

   const client = new CopilotClient({
     cliPath: "/opt/homebrew/bin/copilot",  // Full path
   });
   

Linux

1.        **Berechtigungsprobleme:**
   

   Bash

   chmod +x /path/to/copilot
   

2.        **Fehlende Bibliotheken:** Prüfen Sie auf erforderliche geteilte Bibliotheken:
   

   Bash

   ldd /path/to/copilot
   

Hilfe erhalten

Wenn Sie noch hängen bleiben, sammeln Sie die folgenden Debuginformationen, bevor Sie ein Problem öffnen:

• SDK-Version
• CLI-Version (copilot --version)
• Betriebssystem
• Debugprotokolle
• Minimaler Reproduktionscode

Suchen Sie nach vorhandenen Problemen, oder öffnen Sie ein neues Problem im Github/copilot-sdk-Repository .