Debughandbuch

Inhaltsverzeichnis

• Debugprotokollierung aktivieren
• Häufige Probleme
• Debuggen von MCP-Servern
• Verbindungsprobleme
• Probleme bei der Toolausführung
• Plattformspezifische Probleme

Debugprotokollierung aktivieren

Der erste Schritt beim Debuggen ermöglicht ausführliche Protokollierung, um zu sehen, was unter der Haube passiert.

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

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

from copilot import CopilotClient

client = CopilotClient(log_level="debug")

package main

import copilot "github.com/github/copilot-sdk/go"

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        LogLevel: "debug",
    })
    _ = client
}

import copilot "github.com/github/copilot-sdk/go"

client := copilot.NewClient(&copilot.ClientOptions{
    LogLevel: "debug",
})

using GitHub.Copilot;
using Microsoft.Extensions.Logging;

// Using ILogger
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.SetMinimumLevel(LogLevel.Debug);
    builder.AddConsole();
});

var client = new CopilotClient(new CopilotClientOptions
{
    LogLevel = "debug",
    Logger = loggerFactory.CreateLogger<CopilotClient>()
});

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setLogLevel("debug")
);

Protokollverzeichnis

Die CLI schreibt Protokolle in ein Verzeichnis. Sie können einen benutzerdefinierten Speicherort angeben:

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

# The Python SDK does not currently support passing extra CLI arguments.
# Logs are written to the default location or can be configured via
# the CLI when running in server mode.

package main

import copilot "github.com/github/copilot-sdk/go"

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        Connection: copilot.StdioConnection{
            Args: []string{"--log-dir", "/path/to/logs"},
        },
    })
    _ = client
}

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{
        Args: []string{"--log-dir", "/path/to/logs"},
    },
})

var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForStdio(args: new[] { "--log-dir", "/path/to/logs" })
});

// The Java SDK does not currently support passing extra CLI arguments.
// For custom log directories, run the CLI manually with --log-dir
// and connect via cliUrl.

Häufig auftretende Probleme

"CLI nicht gefunden" / "Copilot: Befehl nicht gefunden"

Ursache: Die Copilot CLI ist nicht installiert oder nicht im PATH.

Solution:

1. Installieren der CLI: Installationshandbuch

2. Installation überprüfen:

   copilot --version
   

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

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

client = CopilotClient({"cli_path": "/usr/local/bin/copilot"})

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{Path: "/usr/local/bin/copilot"},
})

var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = "/usr/local/bin/copilot"
});

var client = new CopilotClient(new CopilotClientOptions()
    .setCliPath("/usr/local/bin/copilot")
);

"Nicht authentifiziert"

Cause: Die CLI ist nicht mit GitHub authentifiziert.

Solution:

1. Authentifizieren der CLI:

   copilot auth login
   

2. Oder stellen Sie programmgesteuert ein Token bereit:

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

import os
client = CopilotClient({"github_token": os.environ.get("GITHUB_TOKEN")})

client := copilot.NewClient(&copilot.ClientOptions{
    GithubToken: os.Getenv("GITHUB_TOKEN"),
})

var client = new CopilotClient(new CopilotClientOptions
{
    GithubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN")
});

var client = new CopilotClient(new CopilotClientOptions()
    .setGitHubToken(System.getenv("GITHUB_TOKEN"))
);

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

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

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

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

„Verbindung abgelehnt“ / „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:

   copilot --server --stdio
   

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

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

Debugging auf dem MCP-Server

MCP-Server (Model Context Protocol) können schwierig zu debuggen sein. Umfassende MCP-Debugginganleitungen finden Sie in der dedizierten MCP-Serverdebugginghandbuch.

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

Eine detaillierte Fehlerbehebung finden Sie unter MCP-Serverdebugginghandbuch.

Verbindungsprobleme

Stdio vs TCP-Modus

Das SDK unterstützt zwei Transportmodi:

Stdiomodus (Standard):

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
});

Herstellen einer Verbindung mit vorhandenem Server:

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

Diagnose von Verbindungsfehlern

1. Clientstatus überprüfen:

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

2. Auf Zustandsänderungen warten:

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

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

   # Check for copilot processes
   ps aux | grep copilot
   

Probleme bei der Toolausführung

Benutzerdefiniertes Tool wird nicht aufgerufen

1. Überprüfen sie die Toolregistrierung:

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

2. Das Überprüfungstoolschema ist ein gültiges JSON-Schema:

   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 gültiges Ergebnis zurückgibt:

   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);
});

Plattformspezifische Probleme

Windows

1. Pfadtrennzeichen: Verwenden Sie unformatierte Zeichenfolgen oder Schrägstriche:

   CliPath = @"C:\Program Files\GitHub\copilot.exe"
   // or
   CliPath = "C:/Program Files/GitHub/copilot.exe"
   

2. PATHEXT-Auflösung: Das SDK behandelt dies automatisch, aber wenn Probleme weiterhin bestehen:

   // Explicitly specify .exe
   Command = "myserver.exe"  // Not just "myserver"
   

3. Konsolencodierung: Stellen Sie UTF-8 für die ordnungsgemäße JSON-Behandlung sicher:

   Console.OutputEncoding = System.Text.Encoding.UTF8;
   

macOS

1. Gatekeeper-Probleme: Wenn CLI blockiert ist:

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

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

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

Linux

1. Berechtigungsprobleme:

   chmod +x /path/to/copilot
   

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

   ldd /path/to/copilot
   

Hilfe erhalten

Wenn Sie noch hängen bleiben:

1. Sammeln von Debuginformationen:

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

2. Search existing issues:GitHub Issues

3. Öffnen Sie ein neues Issue mit den erfassten Informationen

Siehe auch

• Erstellen Sie Ihre erste Copilot-gestützte App
• AUTOTITLE – MCP-Konfiguration und -Einrichtung
• MCP-Serverdebugginghandbuch – Detaillierte MCP-Problembehandlung
• API-Referenz