Руководство по отладке

Включение ведения журнала отладки

Первым шагом в отладке является возможность подробного ведения логирования, чтобы видеть, что происходит под капотом.

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

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

Каталог журналов

CLI записывает журналы в каталог. Вы можете указать пользовательское местоположение:

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.

Примечание.

Конфигурация логирования Python SDK ограничена. Для продвинутой логировки запускайте CLI вручную с --log-dir .RuntimeConnection.for_uri(...)

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.

Распространенные проблемы

"CLI не найден" / "Copilot: команда не найдена"

Причина: Copilot CLI не установлен и не установлен в PATH.

Solution:

Установка CLI: руководство по установке
Проверьте установку:
```
copilot --version
```
Или укажите полный путь:

JavaScript

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

Python

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

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

«Не подтвержено»

Причина: CLI не аутентифицирован с GitHub.

Solution:

Аутентифицировать CLI:
```
copilot auth login
```
Или программно предоставить токен:

JavaScript

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

Python

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

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

«Сессия не найдена»

Причина: Попытка использовать сессию, которая была уничтожена или не существует.

Solution:

Убедитесь, что вы не вызываете методы после disconnect():
```
await session.disconnect();
// Don't use session after this!
```
Для возобновления сессий проверьте наличие идентификатора сессии:
```
const sessions = await client.listSessions();
console.log("Available sessions:", sessions);
```

"Соединение отказано" / "ОТКАЗАНО"

Причина: Процесс CLI-сервера вылетел или не запустился.

Solution:

Проверьте, работает ли CLI самостоятельно:
```
copilot --server --stdio
```

Проверьте на конфликты портов при использовании режима TCP:

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

Отладка серверов MCP

Серверы MCP (Model Context Protocol) могут быть сложны в отладке. Для полных рекомендаций по отладке MCP смотрите специальный раздел AUTOTITLE.

Быстрый чек-лист MCP

Исполняемый файл сервера MCP существует и работает независимо
Путь команды верен (используйте абсолютные пути)
Инструменты включены: tools: ["*"]
Сервер правильно отвечает на initialize запрос
Рабочая директория (cwd) устанавливается при необходимости

Тестирование сервера MCP

Перед интеграцией с SDK убедитесь, что ваш MCP-сервер работает:

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

См. MCP server debugging guide для подробного устранения неполадок.

Проблемы с подключением

stdio против TCP режима

SDK поддерживает два режима транспорта:

Режим	Description	Вариант использования
Stdio (по умолчанию)	CLI работает как подпроцесс, общается через трубы	Местное развитие, единый процесс
TCP	CLI работает отдельно, общается через TCP-сокет	Несколько клиентов, удалённый CLI

Режим Stdio (по умолчанию):

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

Режим TCP:

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

Подключитесь к существующему серверу:

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

Диагностика сбоев соединения

Проверьте состояние клиента:

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

Слушайте изменения в состоянии:

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

Проверьте, что процесс CLI запущен:
```
# Check for copilot processes
ps aux | grep copilot
```

Проблемы с выполнением инструментов

Пользовательский инструмент не вызывается

Проверьте регистрацию инструмента:

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

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

Check Tool Scheme is valid 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 };
  },
};

Убедитесь, что обработчик возвращает действительный результат:

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

Ошибки инструмента не появляются

Подписывайтесь на события ошибок:

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

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

Проблемы, связанные с платформой

Windows

Сепараторы путей: Используйте необработанные струны или прямые слэшы:
```
CliPath = @"C:\Program Files\GitHub\copilot.exe"
// or
CliPath = "C:/Program Files/GitHub/copilot.exe"
```
Разрешение PATHEXT: SDK обрабатывает это автоматически, но если проблемы сохраняются:
```
// Explicitly specify .exe
Command = "myserver.exe"  // Not just "myserver"
```
Консольное кодирование: Убедитесь, что UTF-8 для правильной обработки JSON:
```
Console.OutputEncoding = System.Text.Encoding.UTF8;
```

macOS

Проблемы с хранителями врат: Если CLI заблокирован:
```
xattr -d com.apple.quarantine /path/to/copilot
```
Проблемы с PATH в GUI-приложениях: GUI-приложения не могут наследовать PATH оболочки:
```
const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});
```

Linux

Проблемы с разрешениями:
```
chmod +x /path/to/copilot
```
Отсутствующие библиотеки: Проверьте наличие обязательных общих библиотек:
```
ldd /path/to/copilot
```

Получение помощи

Если вы всё ещё застряли:

Собирайте отладочную информацию:
- Версия пакета SDK
- Версия CLI (copilot --version)
- Операционная система
- Логи отладки
- Код минимального воспроизведения
Поиск существующих номеров:GitHub Проблемы
Откройте новый выпуск с собранной информацией

См. также

Создайте своё первое приложение на базе Copilot
Using MCP servers with the GitHub Copilot SDK — конфигурация и настройка MCP
MCP server debugging guide — подробное устранение неполадок MCP
Справочник по интерфейсам API

В этой статье

Оглавление

Включение ведения журнала отладки

Каталог журналов

Распространенные проблемы

"CLI не найден" / "Copilot: команда не найдена"

«Не подтвержено»

«Сессия не найдена»

"Соединение отказано" / "ОТКАЗАНО"

Отладка серверов MCP

Быстрый чек-лист MCP

Тестирование сервера MCP

Проблемы с подключением

stdio против TCP режима

Диагностика сбоев соединения

Проблемы с выполнением инструментов

Пользовательский инструмент не вызывается

Ошибки инструмента не появляются

Проблемы, связанные с платформой

Windows

macOS

Linux

Получение помощи

См. также