Guide de débogage

Ce guide traite des problèmes courants et des techniques de débogage pour le sdk Copilot sur tous les langages pris en charge.

Dans cet article

Table des matières

Activer la journalisation du débogage

La première étape du débogage consiste à activer la journalisation détaillée pour voir ce qui se passe sous le capot.

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

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

client = CopilotClient(log_level="debug")
Go
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",
})
.NET
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>()
});
Java
import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

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

Répertoire de journaux

L’interface CLI écrit des journaux dans un répertoire. Vous pouvez spécifier un emplacement personnalisé :

TypeScript
const client = new CopilotClient({
  cliArgs: ["--log-dir", "/path/to/logs"],
});
Python
# 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.

Remarque

La configuration de journalisation du SDK Python est limitée. Pour la journalisation avancée, exécutez l’interface CLI manuellement avec --log-dir et connectez-vous via RuntimeConnection.for_uri(...).

Go
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"},
    },
})
.NET
var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForStdio(args: new[] { "--log-dir", "/path/to/logs" })
});
Java
// 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.

Problèmes courants

« CLI introuvable » / « Copilot : commande introuvable »

Cause : L’interface CLI Copilot n’est pas installée ou non dans PATH.

Solution:

  1. Installer l’interface CLI : Guide d’installation

  2. Vérifiez l’installation :

    copilot --version

  3. Ou spécifiez le chemin d’accès complet :

JavaScript
const client = new CopilotClient({
  cliPath: "/usr/local/bin/copilot",
});
Python
client = CopilotClient({"cli_path": "/usr/local/bin/copilot"})
Go
client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.StdioConnection{Path: "/usr/local/bin/copilot"},
})
.NET
var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = "/usr/local/bin/copilot"
});
Java
var client = new CopilotClient(new CopilotClientOptions()
    .setCliPath("/usr/local/bin/copilot")
);

« Non authentifié »

Cause : L’interface CLI n’est pas authentifiée avec GitHub.

Solution:

  1. Authentifiez l’interface CLI :

    copilot auth login

  2. Ou fournissez un jeton de manière programmatique :

JavaScript
const client = new CopilotClient({
  gitHubToken: process.env.GITHUB_TOKEN,
});
Python
import os
client = CopilotClient({"github_token": os.environ.get("GITHUB_TOKEN")})
Go
client := copilot.NewClient(&copilot.ClientOptions{
    GithubToken: os.Getenv("GITHUB_TOKEN"),
})
.NET
var client = new CopilotClient(new CopilotClientOptions
{
    GithubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN")
});
Java
var client = new CopilotClient(new CopilotClientOptions()
    .setGitHubToken(System.getenv("GITHUB_TOKEN"))
);

« Session introuvable »

Cause : Tentative d’utilisation d’une session qui a été détruite ou qui n’existe pas.

Solution:

  1. Vérifiez que vous n’appelez pas les méthodes après disconnect():

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

  2. Pour reprendre des sessions, vérifiez que l’ID de session existe :

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

« Connexion refusée » / « ECONNREFUSED »

Cause : Le processus du serveur CLI a échoué ou n’a pas pu démarrer.

Solution:

  1. Vérifiez si l’interface CLI s’exécute correctement autonome :

    copilot --server --stdio

  2. Vérifiez les conflits de ports si vous utilisez le mode TCP :

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

Débogage du serveur MCP

Les serveurs MCP (Model Context Protocol) peuvent être difficiles à déboguer. Pour obtenir des conseils complets sur le débogage MCP, consultez l’AUTOTITLE dédié.

Liste de contrôle MCP rapide

  • Le fichier exécutable du serveur MCP existe et s’exécute indépendamment
  • Chemin de commande correct (utiliser des chemins absolus)
  • Les outils sont activés : tools: ["*"]
  • Le serveur répond correctement à la initialize demande
  • Répertoire de travail (cwd) est défini si nécessaire

Tester votre serveur MCP

Avant d’intégrer le Kit de développement logiciel (SDK), vérifiez que votre serveur MCP fonctionne :

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

Consultez MCP server debugging guide pour obtenir une résolution des problèmes détaillée.

Problèmes de connexion

stdio vs mode TCP

Le Kit de développement logiciel (SDK) prend en charge deux modes de transport :

ModeDescriptionCas d’usage
Stdio (par défaut)L’interface CLI s’exécute en tant que sous-processus, communique via des canauxDéveloppement local, processus unique
TCPL’interface CLI s’exécute séparément, communique via le socket TCPPlusieurs clients, interface CLI distante

Mode Stdio (par défaut) :

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

Mode TCP :

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

Connectez-vous au serveur existant :

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

Diagnostic des échecs de connexion

  1. Vérifiez l’état du client :

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

  2. Écoutez les modifications d’état :

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

  3. Vérifiez que le processus CLI est en cours d’exécution :

    # Check for copilot processes
ps aux | grep copilot

Problèmes d’exécution des outils

Outil personnalisé n’est pas appelé

  1. Vérifier l’inscription de l’outil :

    const session = await client.createSession({
  tools: [myTool],
});

// Check registered tools
console.log("Registered tools:", session.getTools?.());

  2. Le schéma de l’outil de vérification est un schéma JSON valide :

    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. Vérifiez que le gestionnaire retourne un résultat valide :

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

Erreurs d’outil non affichées

S’abonner aux événements d’erreur :

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

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

Problèmes spécifiques à la plateforme

Windows

  1. Séparateurs de chemin : Utilisez des chaînes brutes ou des barres obliques :

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

  2. Résolution PATHEXT : Le Kit de développement logiciel (SDK) gère cette opération automatiquement, mais si les problèmes persistent :

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

  3. Encodage de la console : Vérifiez UTF-8 pour une gestion JSON appropriée :

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

macOS

  1. Problèmes liés à Gatekeeper : Si l’interface CLI est bloquée :

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

  2. Problèmes PATH dans les applications GUI : Les applications GUI peuvent ne pas hériter du chemin d’accès de l’interpréteur de commandes :

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

Linux

  1. Problèmes d’autorisation :

    chmod +x /path/to/copilot

  2. Bibliothèques manquantes : Recherchez les bibliothèques partagées requises :

    ldd /path/to/copilot

Obtention d’aide

Si vous êtes toujours bloqué :

  1. Collectez les informations de débogage :

    • Version du SDK
    • Version de l’interface CLI (copilot --version)
    • Système d'exploitation
    • Journaux de débogage
    • Code de reproduction minimal

  2. problèmes existants Search :GitHub Problèmes

  3. Ouvrir un nouveau problème avec les informations collectées

Voir aussi