Depuración del SDK de Copilot

Habilite el registro de depuración y resuelva problemas comunes de conexión, autenticación y ejecución de herramientas en SDK de Copilot.

¿Quién puede utilizar esta característica?

SDK de GitHub Copilot está disponible con todos los Copilot planes.

En este artículo

Nota:

          SDK de Copilot actualmente está en versión preliminar pública. La funcionalidad y la disponibilidad están sujetas a cambios.

Habilitar el registro de depuración

Para empezar a solucionar problemas, habilite el registro detallado para obtener visibilidad de los procesos subyacentes.

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

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

Para obtener ejemplos en Python, Go y .NET, consulte Guía de depuración en el github/copilot-sdk repositorio. Para Java, consulte el github/copilot-sdk-java repositorio.

Directorio de logs

La CLI escribe registros en el directorio ABC de forma predeterminada. Puede especificar una ubicación diferente mediante el --log-dir argumento :

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

Para Python y Go, que actualmente no admiten pasar argumentos adicionales de la CLI, ejecute la CLI manualmente con --log-dir y conéctese mediante la cliUrl opción . Para obtener más información, vea Guía de depuración en el github/copilot-sdk repositorio.

Problemas comunes

"CLI no encontrada" o "copilot: comando no encontrado"

          **Causa:**CLI de GitHub Copilot no está instalado o no en PATH.

          **Solution:**

  1. Instale la CLI. Para obtener más información, vea Instalación de GitHub Copilot CLI.

  2. Compruebe la instalación:

    Bash
    copilot --version

  3. O especifique la ruta de acceso completa:

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

    Para obtener ejemplos en Python, Go y .NET, consulte Guía de depuración en el github/copilot-sdk repositorio. Para Java, consulte el github/copilot-sdk-java repositorio.

"No autenticado"

          **Causa:** La CLI no está autenticada con GitHub.

          **Solution:**

  1. Autenticar la CLI:

    Bash
    copilot auth login

  2. O bien, proporcione un token mediante programación:

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

    Para obtener ejemplos en Python, Go y .NET, consulte Guía de depuración en el github/copilot-sdk repositorio. Para Java, consulte el github/copilot-sdk-java repositorio.

"Sesión no encontrada"

          **Causa:** Intentar usar una sesión que se destruyó o no existe.

          **Solution:**

  1. Asegúrese de que no llama a métodos después de disconnect().

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

  2. Para reanudar sesiones, compruebe que el identificador de sesión existe:

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

"Conexión rechazada" o "ECONNREFUSED"

          **Causa:** El proceso del servidor de la CLI se bloqueó o no se pudo iniciar.

          **Solution:**

  1. Compruebe si la CLI se ejecuta correctamente de forma independiente:

    Bash
    copilot --server --stdio

  2. Compruebe si hay conflictos de puertos si usa el modo TCP:

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

Depuración del servidor MCP

Los servidores MCP (Protocolo de Contexto de Modelo) pueden resultar complicados de depurar. Para obtener instrucciones completas sobre la depuración de MCP, consulte Depuración de servidores MCP en el SDK de Copilot.

Lista de comprobación rápida de MCP

  • El ejecutable del servidor MCP existe y se ejecuta de forma independiente
  • La ruta de acceso del comando es correcta (utilice rutas de acceso absolutas)
  • Las herramientas están habilitadas: tools: ["*"]
  • El servidor responde a la initialize solicitud correctamente
  • El directorio de trabajo (cwd) se establece si es necesario.

Prueba del servidor MCP

Antes de realizar la integración con el SDK, compruebe que el servidor MCP funciona:

Bash
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

Para obtener una solución de problemas detallada, consulte Depuración de servidores MCP en el SDK de Copilot.

Problemas de conexión

Modo Stdio frente a TCP

El SDK admite dos modos de transporte:

ModoDescripciónCaso de uso
          **Stdio** (valor predeterminado) | La CLI se ejecuta como subproceso, se comunica a través de canalizaciones. | Desarrollo local, proceso único |

| TCP | La CLI se ejecuta por separado, se comunica a través del socket TCP. | Varios clientes, CLI remota |

          **Modo Stdio (valor predeterminado):**
TypeScript
const client = new CopilotClient({
  useStdio: true,  // This is the default
});

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

          **Conéctese al servidor existente:**
TypeScript
const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

Diagnóstico de errores de conexión

  1. Compruebe el estado del cliente:

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

  2. Escuche los cambios de estado:

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

  3. Compruebe que el proceso de la CLI se está ejecutando:

    Bash
    # Check for copilot processes
ps aux | grep copilot

Problemas de ejecución de herramientas

No se llama a la herramienta personalizada

  1. Compruebe el registro de herramientas:

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

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

  2. Compruebe que el esquema de la herramienta es un esquema JSON válido:

    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. Asegúrese de que el controlador devuelve un resultado válido:

    TypeScript
    handler: async (args) => {
  // Must return something JSON-serializable
  return { success: true, data: "result" };

  // Don't return undefined or non-serializable objects
}

Errores de herramientas que no se muestran

Suscríbase a eventos de error:

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

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

Problemas específicos de la plataforma

Windows

  1.        **Separadores de ruta:** Use cadenas literales o barras diagonales. Para ejemplos específicos de .NET, consulte [Guía de depuración](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) en el repositorio `github/copilot-sdk`.

  2.        **Codificación de consola:** Asegúrese de que UTF-8 se encarga del control de JSON adecuado. Para ejemplos específicos de .NET, consulte [Guía de depuración](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) en el repositorio `github/copilot-sdk`.

macOS

  1.        **Problemas de Gatekeeper:** Si la CLI está bloqueada:
    Bash
    xattr -d com.apple.quarantine /path/to/copilot

  2.        **Problemas de PATH en las aplicaciones de GUI:** Es posible que las aplicaciones de GUI no hereden path del shell:
    TypeScript
    const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

Linux

  1.        **Problemas de permisos:**
    Bash
    chmod +x /path/to/copilot

  2.        **Faltan bibliotecas:** Compruebe si hay bibliotecas compartidas necesarias:
    Bash
    ldd /path/to/copilot

Obtener ayuda

Si todavía está bloqueado, recopile la siguiente información de depuración antes de abrir un problema:

  • Versión del SDK
  • Versión de la CLI (copilot --version)
  • Sistema operativo
  • Registros de depuración
  • Código de reproducción mínimo

Busque problemas existentes o abra un nuevo problema en el repositorio github/copilot-sdk .