Depurando o SDK do Copilot

Habilitar o log de depuração

Para começar a solução de problemas, habilite o log detalhado para obter visibilidade dos processos subjacentes.

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

Para obter exemplos em Python, Go e .NET, consulte o Guia de Depuração no github/copilot-sdk repositório. Para Java, consulte o github/copilot-sdk-java repositório.

Diretório de log

A CLI grava logs no diretório ABC por padrão. Você pode especificar um local diferente usando o --log-dir argumento:

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

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

Para Python e Go, que atualmente não dão suporte à passagem de argumentos extras da CLI, execute a CLI manualmente com --log-dir e conecte-se por meio da opção cliUrl. Para obter mais informações, consulte o Guia de Depuração no github/copilot-sdk repositório.

Problemas comuns

"CLI não encontrada" ou "copilot: comando não encontrado"

          **Causa:**CLI do GitHub Copilot não está instalado ou não está no PATH.

          **Solution:**

1. Instale a CLI. Para obter mais informações, consulte Instalando o CLI do GitHub Copilot.

2. Verifique a instalação:

   Bash

   copilot --version
   

3. Ou especifique o caminho completo:

   TypeScript

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

   Para obter exemplos em Python, Go e .NET, consulte o Guia de Depuração no github/copilot-sdk repositório. Para Java, consulte o github/copilot-sdk-java repositório.

"Não autenticado"

          **Causa:** A CLI não é autenticada com GitHub.

          **Solution:**

1. Autenticar a interface de linha de comando (CLI):

   Bash

   copilot auth login
   

2. Ou forneça um token programaticamente:

   TypeScript

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

   Para obter exemplos em Python, Go e .NET, consulte o Guia de Depuração no github/copilot-sdk repositório. Para Java, consulte o github/copilot-sdk-java repositório.

"Sessão não encontrada"

          **Causa:** Tentando usar uma sessão que foi destruída ou não existe.

          **Solution:**

1. Verifique se você não está chamando métodos após disconnect():

   TypeScript

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

2. Para retomar as sessões, verifique se a ID da sessão existe:

   TypeScript

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

"Conexão recusada" ou "ECONNREFUSED"

          **Causa:** O processo do servidor da CLI falhou ou falhou ao iniciar.

          **Solution:**

1. Verifique se a CLI é executada corretamente autônoma:

   Bash

   copilot --server --stdio
   

2. Verifique se há conflitos de porta se estiver usando o modo TCP:

   TypeScript

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

Depuração do servidor MCP

Os servidores MCP (Protocolo de Contexto de Modelo) podem ser complicados de depurar. Para obter diretrizes abrangentes de depuração do MCP, consulte Depurando servidores MCP no SDK do Copilot.

Lista de verificação rápida do MCP

• O executável do servidor MCP existe e é executado de forma independente
• O caminho do comando está correto (use caminhos absolutos)
• As ferramentas estão habilitadas: tools: ["*"]
• O servidor responde à initialize solicitação corretamente
• O diretório de trabalho (cwd) é definido, se necessário

Testar o servidor MCP

Antes de integrar com o SDK, verifique se o servidor MCP funciona:

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

Para obter uma solução de problemas detalhada, consulte Depurando servidores MCP no SDK do Copilot.

Problemas de conexão

Modo de operação Stdio vs TCP

O SDK dá suporte a dois modos de transporte:

          **Stdio** (padrão) | A CLI é executada como subprocesso, comunica-se por meio de pipes | Desenvolvimento local, processo único |

| TCP | A CLI é executada separadamente, comunica-se por meio do soquete TCP | Vários clientes, CLI remota |

          **Modo stdio (padrão):**

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

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

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

          **Conecte-se ao servidor existente:**

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

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

Diagnosticando falhas de conexão

1. Verifique o estado do cliente:

   TypeScript

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

2. Escute as alterações de estado:

   TypeScript

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

3. Verifique se o processo da CLI está em execução:

   Bash

   # Check for copilot processes
   ps aux | grep copilot
   

Problemas de execução da ferramenta

Ferramenta personalizada não está sendo chamada

1. Verificar o registro da ferramenta:

   TypeScript

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

2. Verifique se o esquema da ferramenta é um 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. Verifique se o manipulador retorna um 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
   }
   

Erros de ferramenta que não são exibidos

Inscreva-se em eventos de erro:

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

Problemas específicos da plataforma

Windows

1.        **Separadores de caminho:** Use cadeias de caracteres brutas ou barras para frente. Para exemplos específicos do .NET, consulte [o Guia de Depuração](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) no `github/copilot-sdk` repositório.
   

2.        **Codificação do console:** Certifique-se de que UTF-8 esteja configurado para o tratamento adequado de JSON. Para exemplos específicos do .NET, consulte [o Guia de Depuração](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) no `github/copilot-sdk` repositório.
   

macOS

1.        **Problemas do gatekeeper:** Se a CLI estiver bloqueada:
   

   Bash

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

2.        **Problemas de PATH em aplicativos de GUI:** Os aplicativos de GUI podem não herdar o PATH do shell:
   

   TypeScript

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

Linux

1.        **Problemas de permissão:**
   

   Bash

   chmod +x /path/to/copilot
   

2.        **Bibliotecas ausentes:** Verifique se há bibliotecas compartilhadas necessárias:
   

   Bash

   ldd /path/to/copilot
   

Obtendo ajuda

Se você ainda estiver com dificuldades, colete as seguintes informações de depuração antes de relatar um problema:

• Versão do SDK
• Versão da CLI (copilot --version)
• Sistema operacional
• Debugar logs
• Código de reprodução mínimo

Pesquise problemas existentes ou abra um novo problema no repositório github/copilot-sdk .