Débogage du SDK Copilot

Activer l’enregistrement du débogage

Pour commencer la résolution des problèmes, activez la journalisation détaillée pour obtenir une visibilité sur les processus sous-jacents.

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

Pour obtenir des exemples dans Python, Go et .NET, consultez le Guide de débogage dans le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

Répertoire du journal

L’interface en ligne de commande (CLI) écrit les logs dans le répertoire ABC par défaut. Vous pouvez spécifier un autre emplacement à l’aide de l’argument --log-dir :

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

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

Pour Python et Go, qui ne prennent pas actuellement en charge le passage d’arguments CLI supplémentaires, exécutez l’interface CLI manuellement avec --log-dir et connectez-vous via l’option cliUrl . Pour plus d’informations, consultez Le Guide de débogage dans le github/copilot-sdk référentiel.

Problèmes courants

« CLI introuvable » ou « copilot : commande introuvable »

          **Cause :**CLI GitHub Copilot n’est pas installé ou non dans PATH.

          **Solution:**

1. Installez l’interface CLI. Pour plus d’informations, consultez « Installation du CLI GitHub Copilot ».

2. Vérifiez l’installation :

   Bash

   copilot --version
   

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

   TypeScript

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

   Pour obtenir des exemples dans Python, Go et .NET, consultez le Guide de débogage dans le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

« Non authentifié »

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

          **Solution:**

1. Authentifiez l’interface CLI :

   Bash

   copilot auth login
   

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

   TypeScript

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

   Pour obtenir des exemples dans Python, Go et .NET, consultez le Guide de débogage dans le github/copilot-sdk référentiel. Pour Java, consultez le github/copilot-sdk-java référentiel.

« 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():

   TypeScript

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

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

   TypeScript

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

« Connexion refusée » ou « 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 :

   Bash

   copilot --server --stdio
   

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

   TypeScript

   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 Débogage de serveurs MCP dans le Kit de développement logiciel (SDK) Copilot.

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

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

Pour obtenir une résolution des problèmes détaillée, consultez Débogage de serveurs MCP dans le Kit de développement logiciel (SDK) Copilot.

Problèmes de connexion

Stdio vs mode TCP

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

          **Mode Stdio (par défaut) :**

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

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

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

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

Diagnostic des échecs de connexion

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

   TypeScript

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

2. Écoutez les modifications d’état :

   TypeScript

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

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

   Bash

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

   TypeScript

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

2. Vérifiez que le schéma de l’outil est un schéma JSON valide :

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

   TypeScript

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

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

Fenêtres

1.        **Séparateurs de chemin d’accès :** Utilisez des chaînes de caractères brutes ou des barres obliques. Pour des exemples spécifiques à .NET, consultez le [Guide de débogage](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) dans le`github/copilot-sdk` répertoire.
   

2.        **Encodage de la console :** Vérifiez UTF-8 pour une gestion JSON appropriée. Pour des exemples spécifiques à .NET, consultez le [Guide de débogage](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) dans le`github/copilot-sdk` répertoire.
   

macOS

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

   Bash

   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 :
   

   TypeScript

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

Linux

1.        **Problèmes d’autorisation :**
   

   Bash

   chmod +x /path/to/copilot
   

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

   Bash

   ldd /path/to/copilot
   

Obtention d’aide

Si vous êtes toujours bloqué, collectez les informations de débogage suivantes avant d’ouvrir un problème :

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

Recherchez des problèmes existants ou ouvrez un nouveau problème dans le dépôt github/copilot-sdk .