Отладка Copilot SDK

Включите логирование отладки и решите распространённые проблемы с соединением, аутентификацией и выполнением инструментов в Copilot SDK.

Кто может использовать эту функцию?

GitHub Copilot SDK Доступна со всеми Copilot тарифными планами.

В этой статье

Примечание.

          Copilot SDK в настоящее время находится в public preview. Функциональность и доступность могут меняться.

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

Для начала устранения неполадок включите подробный лог, чтобы получить видимость в основе процессов.

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

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

Для примеров в Python, Go и .NET см. Руководство по отладке в github/copilot-sdk репозитории. Для Java см. репозиторийgithub/copilot-sdk-java.

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

CLI по умолчанию записывает журналы в каталог ABC. Вы можете указать другое местоположение с помощью аргумента --log-dir :

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

Для Python и Go, которые сейчас не поддерживают передачу дополнительных CLI-аргументов, запускайте CLI вручную и --log-dir подключайтесь через эту cliUrl опцию. Для получения дополнительной информации смотрите руководство по отладке в github/copilot-sdk репозитории.

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

«CLI не найден» или «второй пилот: команда не найдена»

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

          **Solution:**

  1. Установите CLI. Дополнительные сведения см. в разделе Установка GitHub Copilot CLI.

  2. Проверьте установку:

    Bash
    copilot --version

  3. Или укажите полный путь:

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

    Для примеров в Python, Go и .NET см. Руководство по отладке в github/copilot-sdk репозитории. Для Java см. репозиторийgithub/copilot-sdk-java.

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

          **Причина:** CLI не аутентифицируется с GitHubпомощью .

          **Solution:**

  1. Аутентифицировать CLI:

    Bash
    copilot auth login

  2. Или программно предоставить токен:

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

    Для примеров в Python, Go и .NET см. Руководство по отладке в github/copilot-sdk репозитории. Для Java см. репозиторийgithub/copilot-sdk-java.

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

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

          **Solution:**

  1. Убедитесь, что вы не вызываете методы после disconnect():

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

  2. Для возобновления сессий проверьте наличие идентификатора сессии:

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

«Соединение отказано» или «ОТКАЗАНО»

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

          **Solution:**

  1. Проверьте, работает ли CLI самостоятельно:

    Bash
    copilot --server --stdio

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

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

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

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

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

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

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

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

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

Для подробного устранения неполадок см. Отладка MCP-серверов в Copilot SDK.

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

Режим Stdio против TCP

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

РежимОписаниеСценарий использования
          **Stdio** (по умолчанию) | CLI работает как подпроцесс, общается через трубы | Местное развитие, единый процесс |

| TCP | CLI работает отдельно, общается через TCP-сокет | Несколько клиентов, удалённый CLI |

          **Режим Stdio (по умолчанию):**
TypeScript
const client = new CopilotClient({
  useStdio: true,  // This is the default
});

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

          **Подключитесь к существующему серверу:**
TypeScript
const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

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

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

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

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

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

  3. Проверьте, что процесс CLI запущен:

    Bash
    # Check for copilot processes
ps aux | grep copilot

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

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

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

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

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

  2. Проверьте, валидна ли схема инструмента в JSON Schema:

    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. Убедитесь, что обработчик возвращает действительный результат:

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

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

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

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

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

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

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

Виндоус

  1.        **Сепараторы путей:** Используйте необработанные струны или прямые слэши. Для . Примеры, специфичные для NET, см. [Руководство по отладке](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) в `github/copilot-sdk` репозитории.

  2.        **Консольное кодирование:** Убедитесь, что UTF-8 для правильной обработки JSON. Для . Примеры, специфичные для NET, см. [Руководство по отладке](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) в `github/copilot-sdk` репозитории.

macOS

  1.        **Проблемы с хранителями врат:** Если CLI заблокирован:
    Bash
    xattr -d com.apple.quarantine /path/to/copilot

  2.        **Проблемы с PATH в GUI-приложениях:** GUI-приложения не могут наследовать PATH оболочки:
    TypeScript
    const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

Линукс

  1.        **Проблемы с разрешением:**
    Bash
    chmod +x /path/to/copilot

  2.        **Отсутствующие библиотеки:** Проверьте наличие обязательных общих библиотек:
    Bash
    ldd /path/to/copilot

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

Если вы всё ещё застряли, соберите следующую отладочную информацию перед открытием выпуска:

  • Версия пакета SDK
  • Версия CLI (copilot --version)
  • Операционная система
  • Логи отладки
  • Код минимального воспроизведения

Ищите существующие проблемы или откройте новую в репозитории github/copilot-sdk .